index.rst (15227B)
1 .. _mozilla_projects_nss_ssl_functions_gtstd: 2 3 gtstd 4 ===== 5 6 .. container:: 7 8 .. note:: 9 10 - This page is part of the :ref:`mozilla_projects_nss_ssl_functions_old_ssl_reference` that 11 we are migrating into the format described in the `MDN Style 12 Guide <https://developer.mozilla.org/en-US/docs/Project:MDC_style_guide>`__. If you are 13 inclined to help with this migration, your help would be very much appreciated. 14 15 - Upgraded documentation may be found in the :ref:`mozilla_projects_nss_reference` 16 17 .. rubric:: Getting Started With SSL 18 :name: Getting_Started_With_SSL 19 20 -------------- 21 22 .. _chapter_2_getting_started_with_ssl: 23 24 `Chapter 2 <#chapter_2_getting_started_with_ssl>`__ Getting Started With SSL 25 ---------------------------------------------------------------------------- 26 27 .. container:: 28 29 This chapter describes how to set up your environment, including certificate and key databases. 30 31 | `SSL, PKCS #11, and the Default Security Databases <#1011970>`__ 32 | `Setting Up the Certificate and Key Databases <#1011987>`__ 33 | `Building NSS Programs <#1013274>`__ 34 35 .. _ssl_pkcs_11_and_the_default_security_databases: 36 37 `SSL, PKCS #11, and the Default Security Databases <#ssl_pkcs_11_and_the_default_security_databases>`__ 38 ------------------------------------------------------------------------------------------------------- 39 40 .. container:: 41 42 The basic relationships among the NSS libraries are described in `Introduction to Network 43 Security Services <../../intro.html>`__. Before running the sample programs, it's important to 44 understand the relationships between the SSL interface, the PKCS #11 interface, PKCS #11 modules, 45 and the default Netscape security databases. 46 47 A **PKCS #11 module** (also called a **cryptographic module**) manages cryptographic services 48 such as encryption and decryption via the PKCS #11 interface. PKCS #11 modules can be thought of 49 as drivers for cryptographic devices that can be implemented in either hardware or software. 50 Netscape provides a built-in PKCS #11 module with NSS. Other kinds of PKCS #11 modules include 51 the Netscape FORTEZZA module, used by the government, and the Litronic PKCS #11 module for smart 52 card readers. 53 54 `Figure 2.1 <#1013181>`__ illustrates the relationships between NSPR, SSL, PKCS #11, and the 55 available cryptographic modules. SSL is built on top of NSPR, which handles sockets, threads, and 56 related low-level OS operations. On any given server or client, one or more PKCS #11 modules may 57 be available. 58 59 **Figure 2.1 Relationships among NSS libraries, cryptographic modules, slots, and tokens** 60 61 .. image:: /en-US/docs/Mozilla/Projects/NSS/SSL_functions/gtstd/pkcs.gif 62 63 As shown in the figure, SSL communicates with PKCS #11 modules through the PKCS #11 interface. 64 Any PKCS #11 module that supports PKCS #11 can be used with the NSS libraries. Netscape software 65 uses a file called ``secmod.db`` to keep track of the modules available. 66 67 A PKCS #11 module always has one or more **slots,** which may be implemented as physical hardware 68 slots in some form of physical reader (for example, for smart cards) or as conceptual slots in 69 software. Each slot for a PKCS #11 module can in turn contain a **token,** which is the hardware 70 or software device that actually provides cryptographic services and optionally stores 71 certificates and keys. 72 73 Netscape provides three built-in modules with NSS and with server and client products: 74 75 - The default Netscape Internal PKCS #11 Module comes with two built-in tokens: 76 77 - The Generic Crypto Services token performs all cryptographic operations, such as 78 encryption, decryption, and hashing. 79 - The Communicator Certificate DB token handles all communication with the certificate and 80 key database files (called ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db``, respectively, 81 where\ *X* is a version number) that store certificates and keys. 82 83 - The FORTEZZA module is intended for use with FORTEZZA hardware tokens. 84 - The FIPS 140-1 module is compliant with the FIPS 140-1 government standard for implementations 85 of cryptographic modules. Many products sold to the U.S. government must comply with one or 86 more of the FIPS standards. The FIPS 140-1 module includes a single, built-in FIPS 140-1 87 Certificate DB token (see `Figure 2.1 <#1013181>`__), which handles both cryptographic 88 operations and communication with the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files. 89 90 If you are creating a server application, you must use the Certificate Database Tool, which comes 91 with NSS, to create the ``cert``\ *X*\ ``.db`` and ``key``\ *X*\ ``.db`` files and populate them 92 with the appropriate certificates and keys. 93 94 If you are creating a client application, you can use either the Certificate Database Tool or the 95 Communicator security interface to create the database files and populate them with the 96 appropriate certificates and keys. You can use Communicator to set up client certificate 97 databases by obtaining certificates from either a public CA or from a certificate server such as 98 Netscape Certificate Management System. The instructions that follow assume you are using the 99 Certificate Database Tool to set up both the server and client databases for testing purposes. 100 101 You can use the Security Module Database Tool, a command-line utility that comes with NSS, to 102 manage PKCS #11 module information within s\ ``ecmod.db`` files. The Security Module Database 103 Tool allows you to add and delete PKCS #11 modules, change passwords, set defaults, list module 104 contents, enable or disable slots, enable or disable FIPS-140-1 compliance, and assign default 105 providers for cryptographic operations. 106 107 .. _setting_up_the_certificate_and_key_databases: 108 109 `Setting Up the Certificate and Key Databases <#setting_up_the_certificate_and_key_databases>`__ 110 ------------------------------------------------------------------------------------------------ 111 112 .. container:: 113 114 Before you can run the sample programs (``server.c`` and ``client.c``) that come with NSS, you 115 must set up certificate, key, and security module databases for both the client and the server 116 and populate them with valid CA, client SSL, and server SSL certificates. The following sections 117 decribe how to the Certificate Database Tool to perform these tasks: 118 119 | `Setting Up the CA DB and Certificate <#1012301>`__ 120 | `Setting Up the Server DB and Certificate <#1012351>`__ 121 | `Setting Up the Client DB and Certificate <#1012067>`__ 122 | `Verifying the Server and Client Certificates <#1012108>`__ 123 124 **WARNING:** The instructions below illustrate the use of NSS command line tools to operate a 125 simple root Certificate Authority for test purposes only. The CA, SSL server and SSL client 126 certificates produced by these instructions work correctly for short term testing purposes. 127 Although it is possible to use NSS command line tools to operate a proper CA, these 128 instructions do not provide nearly enough understanding of the many considerations required to 129 competently operate a CA. The NSS teams **strongly** recommends that users should not attempt 130 to operate a CA for use in mission critical production business uses using NSS's command line 131 tools, nor with the simple command line test tools that come with any package of cryptographic 132 libraries. Many who have attempted it have eventually come to regret that decision. For 133 production deployment, the NSS team strongly recommends that you either: 134 135 - Use certificates from a competent third-party CA that is already known to your relying 136 party software (e.g. your SSL clients), or 137 - Use professional grade CA software, such as Red Hat's 138 `Dogtag <http://pki.fedoraproject.org/wiki/PKI_Main_Page>`__ `Certificate 139 System <http://www.redhat.com/certificate_system/>`__, to set up and operate your own CA 140 and issue your own certificates. 141 142 For complete information about the command-line options used in the examples that follow, see 143 `Using the Certificate Database Tool <../../tools/certutil.html>`__. 144 145 .. _setting_up_the_ca_db_and_certificate: 146 147 `Setting Up the CA DB and Certificate <#setting_up_the_ca_db_and_certificate>`__ 148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 149 150 .. container:: 151 152 Set up the CA with its own separate set of databases. 153 154 #. Create a new certificate database in the ``CA_db`` directory. 155 ``>mkdir CA_db >certutil -N -d CA_db`` 156 #. Create the self-signed Root CA certificate, specifying the subject name for the certificate. 157 ``>certutil -S -d CA_db -n "MyCo's Root CA" -s "CN=My CA,O=MyCo,ST=California,C=US" -t "CT,," -x -2 Enter Password or Pin for "Communicator Certificate DB":`` 158 #. Extract the CA certificate from the CA's certificate database to a file. 159 ``>certutil -L -d CA_db -n "MyCo's Root CA" -a -o CA_db/rootca.crt Enter Password or Pin for "Communicator Certificate DB":`` 160 #. Display the contents of the CA's certificate databases. 161 ``>certutil -L -d CA_db`` 162 163 The trust flag settings ``"CTu,u,u"`` indicate that the certificate is a CA certificate that is 164 trusted to issue both client (``C``) and server (``T``) SSL certificates. The ``u`` flag 165 indicates that the private key for the CA certificate is present in this set of databases, so the 166 CA can issue SSL client and server certificates with these databases. 167 168 .. _setting_up_the_server_db_and_certificate: 169 170 `Setting Up the Server DB and Certificate <#setting_up_the_server_db_and_certificate>`__ 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 172 173 .. container:: 174 175 The sections that follow describe how to set up the Server DB and certificate: 176 177 #. Create a new certificate database in the ``server_db`` directory. 178 ``>mkdir server_db >certutil -N -d server_db`` 179 #. Import the new CA certificate into the server's certificate database, and mark it trusted for 180 issuing certificates for SSL client and server authentication. 181 ``>certutil -A -d server_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt`` 182 #. Create the server certificate request, specifying the subject name for the server certificate. 183 We make the common name (CN) be identical to the hostname of the server. Note that this step 184 generates the server's private key, so it must be done in the server's database directory. 185 ``>certutil -R -d server_db -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -a -o server_db/server.req Enter Password or Pin for "Communicator Certificate DB":`` 186 #. This step simulates the CA signing and issuing a new server certificate based on the server's 187 certificate request. The new cert is signed with the CA's private key, so this operation uses 188 the CA's databases. This step leaves the server's new certificate in a file. 189 ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i server_db/server.req -o server_db/server.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":`` 190 #. Import (Add) the new server certificate to the server's certificate database in the 191 ``server_db`` directory with the appropriate nickname. Notice that no trust is explicitly 192 needed for this certificate. 193 ``>certutil -A -d server_db -n myco.mcom.org -a -i server_db/server.crt -t ",,"`` 194 #. Display the contents of the server's certificate databases. 195 ``>certutil -L -d server_db`` 196 197 The trust flag settings ``"u,u,u"`` indicate that the server's databases contain the private key 198 for this certificate. This is necessary for the SSL server to be able to do its job. 199 200 .. _setting_up_the_client_db_and_certificate: 201 202 `Setting Up the Client DB and Certificate <#setting_up_the_client_db_and_certificate>`__ 203 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 204 205 .. container:: 206 207 Setting up the client certificate database involves three stages: 208 209 #. Create a new certificate database in the ``client_db`` directory. 210 ``>mkdir client_db >certutil -N -d client_db`` 211 #. Import the new CA certificate into the client's certificate database, and mark it trusted for 212 issuing certificates for SSL client and server authentication. 213 ``>certutil -A -d client_db -n "MyCo's Root CA" -t "TC,," -a -i CA_db/rootca.crt`` 214 #. Create the client certificate request, specifying the subject name for the certificate. 215 ``>certutil -R -d client_db -s "CN=Joe Client,O=MyCo,ST=California,C=US" -a -o client_db/client.req Enter Password or Pin for "Communicator Certificate DB":`` 216 #. This step simulates the CA signing and issuing a new client certificate based on the client's 217 certificate request. The new cert is signed with the CA's private key, so this operation uses 218 the CA's databases. This step leaves the client's new certificate in a file. 219 ``>certutil -C -d CA_db -c "MyCo's Root CA" -a -i client_db/client.req -o client_db/client.crt -2 -6 Enter Password or Pin for "Communicator Certificate DB":`` 220 #. Add the new client certificate to the client's certificate database in the ``client_db`` 221 directory with the appropriate nickname. Notice that no trust is required for this 222 certificate. 223 ``>certutil -A -d client_db -n "Joe Client" -a -i client_db/client.crt -t ",,"`` 224 #. Display the contents of the client's certificate databases. 225 ``>certutil -L -d client_db`` 226 227 The trust flag settings ``"u,u,u"`` indicate that the client's databases contain the private key 228 for this certificate. This is necessary for the SSL client to be able to authenticate to the 229 server. 230 231 .. _verifying_the_server_and_client_certificates: 232 233 `Verifying the Server and Client Certificates <#verifying_the_server_and_client_certificates>`__ 234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 235 236 .. container:: 237 238 When you have finished setting up the server and client certificate databases, verify that the 239 client and server certificates are valid, as follows: 240 241 ``>certutil -V -d server_db -u V -n myco.mcom.org certutil: certificate is valid`` 242 243 ``>certutil -V -d client_db -u C -n "Joe Client" certutil: certificate is valid`` 244 245 .. _building_nss_programs: 246 247 `Building NSS Programs <#building_nss_programs>`__ 248 -------------------------------------------------- 249 250 .. container:: 251 252 On Unix, use the GNU utility ``gmake`` to run the makefile. On Windows NT, use the ``nmake`` 253 utility that comes with Visual C++. 254 255 If you create your own makefiles, be sure to include the libraries in the same order that they 256 are listed in the sample makefiles. In addition, you must use the following compiler flags: 257 258 Solaris flags: 259 260 ``-c -O -KPIC -DSVR4 -DSYSV -D__svr4 -D__svr4__ -DSOLARIS -D_REENTRANT -DSOLARIS2_5 -D_SVID_GETTOD -DXP_UNIX -UDEBUG -DNDEBUG`` 261 262 Windows NT flags: 263 264 ``-c -O2 -MD -W3 -nologo -D_X86_ -GT -DWINNT -DXP_PC -UDEBUG -U_DEBUG -DNDEBUG -DWIN32 -D_WINDOWS``