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