You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Table of Contents | Previous | Next | Index


Chapter 2
Getting Started With SSL

This chapter describes how to set up your environment, including certificate and key databases, to run the NSS sample code. The sample code and makefiles are available via LXR in the SSLSamples directory.

SSL, PKCS #11, and the Default Security Databases
Setting Up the Certificate and Key Databases
Building NSS Programs

Important This chapter refers in several places to a tool called Key Database Tool, or keyutil. The capabilities of keyutil have been folded into the tool called Certificate Database Tool, or certutil. The samples given in this chapter are therefore out of date.

SSL, PKCS #11, and the Default Security Databases

The basic relationships among the NSS libraries are described in Introduction to Network Security Services. Before running the sample programs, it's important to understand the relationships between the SSL interface, the PKCS #11 interface, PKCS #11 modules, and the default Netscape security databases.

A PKCS #11 module (also called a cryptographic module) manages cryptographic services such as encryption and decryption via the PKCS #11 interface. PKCS #11 modules can be thought of as drivers for cryptographic devices that can be implemented in either hardware or software. Netscape provides a built-in PKCS #11 module with NSS. Other kinds of PKCS #11 modules include the Netscape FORTEZZA module, used by the government, and the Litronic PKCS #11 module for smart card readers.

Figure 2.1 illustrates the relationships between NSPR, SSL, PKCS #11, and the available cryptographic modules. SSL is built on top of NSPR, which handles sockets, threads, and related low-level OS operations. On any given server or client, one or more PKCS #11 modules may be available.

Figure 2.1    Relationships among NSS libraries, cryptographic modules, slots, and tokens

As shown in the figure, SSL communicates with PKCS #11 modules through the PKCS #11 interface. Any PKCS #11 module that supports PKCS #11 can be used with the NSS libraries. Netscape software uses a file called secmod.db to keep track of the modules available.

A PKCS #11 module always has one or more slots, which may be implemented as physical hardware slots in some form of physical reader (for example, for smart cards) or as conceptual slots in software. Each slot for a PKCS #11 module can in turn contain a token, which is the hardware or software device that actually provides cryptographic services and optionally stores certificates and keys.

Netscape provides three built-in modules with NSS and with server and client products:

If you are creating a server application, you must use the Certificate Database Tool, which comes with NSS, to create the certX.db and keyX.db files and populate them with the appropriate certificates and keys.

If you are creating a client application, you can use either the Certificate Database Tool or the Communicator security interface to create the database files and populate them with the appropriate certificates and keys. You can use Communicator to set up client certificate databases by obtaining certificates from either a public CA or from a certificate server such as Netscape Certificate Management System. The instructions that follow assume you are using the Certificate Database Tool to set up both the server and client databases for testing purposes.

You can use the Security Module Database Tool, a command-line utility that comes with NSS, to manage PKCS #11 module information within secmod.db files. The Security Module Database Tool allows you to add and delete PKCS #11 modules, change passwords, set defaults, list module contents, enable or disable slots, enable or disable FIPS-140-1 compliance, and assign default providers for cryptographic operations.

Setting Up the Certificate and Key Databases

Before you can run the sample programs (server.c and client.c) that come with NSS, you must set up certificate, key, and security module databases for both the client and the server and populate them with valid CA, client SSL, and server SSL certificates. The following sections decribe how to the Certificate Database Tool to perform these tasks:

Setting Up the CA and Server Certificates
Setting Up the Client Certificate
Verifying the Server and Client Certificates

WARNING: The CA certificate you produce with the NSS tools is a self-signed certificate that works correctly for testing purposes but should not be used in a real-world deployment. Similarly, the client SSL and server SSL certificates created with the NSS tools are for testing purposes only. To deploy certificates used in a real public-key infrastructure (PKI), either use a third-party CA or use a certificate server (such as Netscape Certificate Management System) to set up your own CA and issue certificates. The Certificate Database Tool does not provide the facilities for a full-blown PKI deployment, and the certificates it creates should not be considered trustworthy for that purpose.
For complete information about the command-line options used in the examples that follow, see Using the Certificate Database Tool.

Setting Up the CA and Server Certificates

The sections that follow describe how to set up the CA and server certificates:

Creating the Databases and Generating the Keys
Creating the CA Certificate and Adding It to the Database
Creating the Server Certificate and Adding It to the Database

Creating the Databases and Generating the Keys

First create the certificate and key databases for the server and generate two key pairs: one for the CA certificate and one for the server SSL certificate.

  1. Create a new certificate database in the server_db directory.
    2. C:\nss11\winnt>certutil -N -d server_db

  2. Create two key pairs in the server_db directory. The Certificate Database Tool automatically creates the key database and the security module database (if they don't already exist) when it creates the first key pair. 
    3. C:\nss11\winnt>keyutil -G -d server_db 
    C:\nss11\winnt>keyutil -G -d server_db

  3. List the public keys.
    4. C:\nss11\winnt>keyutil -L -d server_db 
    Enter Password or Pin for "Communicator Certificate DB": 
    RSA Public-Key: 
       modulus: 
          00:f7:c1:1f:a2:c1:cb:12:cc:08:91:60:48:e4:00:43:17:f1: 
          fc:b1:88:4b:54:47:2d:11:64:ec:c3:15:d7:5b:68:32:93:f9: 
          86:71:ce:c9:cc:f0:e0:a6:28:80:86:cc:88:29:70:67:81:1d: 
          4f:86:04:38:52:0f:b0:aa:83:36:1b:27:06:b9:99:08:0c:3b: 
          d8:98:53:16:08:09:20:44:c7:8a:72:da:a2:b5:7b:71:b7:ce: 
          ab:48:fc:31:1e:61:09:31:0c:ef:00:05:f2:de:09:7f:f7:af: 
          d6:24:3e:29:09:ba:d3:98:31:12:9e:d9:b9:b4:7e:ef:01:81: 
          cc:92:79 
    RSA Public-Key: 
       modulus: 
       00:b6:2b:e8:71:6e:a5:e3:90:51:00:9d:7a:00:3b:50:eb:9e: 
       78:33:d8:ac:1d:95:a9:21:47:25:d0:39:ad:22:0f:d9:81:ed: 
       60:be:4d:db:20:f5:91:15:76:bf:5f:6c:06:aa:d1:08:8c:f9: 
       7c:79:b7:cd:f0:76:da:2d:5f:42:21:40:3b:92:86:b3:df:4e: 
       42:b8:92:18:01:91:48:c1:9d:ee:ae:03:55:c0:a1:74:69:9b: 
       86:f8:c0:9a:47:0a:52:30:d9:53:40:24:54:15:19:a6:92:c8: 
       7f:1f:3b:e4:0e:4c:09:73:ad:1e:16:00:e7:f4:3d:5f:f4:22: 
       f4:dd:7f
You can identify either of the keys listed above the first few characters that are unique in the database. For example, the first key can be identified as f7c1.

Creating the CA Certificate and Adding It to the Database

After the databases have been created and the key pairs generated, create the CA certificate and add it to the certificate database.

  1. Create the CA certificate request, specifying the subject name for the certificate and the key f7c1. 
    2. C:\nss11\winnt>certutil -R -s
    "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k f7c1 -o
    server_db\rootca.req -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":

  2. Create a new certificate from the certificate request and self-sign it.
    3. C:\nss11\winnt>certutil -C -i server_db\rootca.req -o
    server_db\rootca.crt -k f7c1 -x -m 1234 -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":

  3. Add the CA certificate to the certificate database in the server_db directory with the appropriate trust flags and nickname.
    4. C:\nss11\winnt>certutil -A -n "MyCo's Root CA" 
    -i server_db\rootca.crt -t "CTu,CTu,CTu" -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":
The trust flag settings "CTu,CTu,CTu" indicate that the certificate is a CA certificate that is trusted to issue both client (C) and server (T) SSL certificates as well as email and object-signing certificates. The u flag indicates that the CA certificate can itself be used for signing or authentication operations.

NOTE: The u flag should not be set in a root CA certificate intended for deployment in a real (as opposed to a test) PKI for chaining purposes. Only the authorized CA should be able to sign anything or authenticate itself with a CA certificate.

Creating the Server Certificate and Adding It to the Database

At this point the CA certificate has been self-signed and added to the certificate database. Next, create a server certificate signed with the CA's private key and add it to the certificate database.

  1. Create the server certificate request, specifying the subject name for the certificate and the public key b62b. Note that the common name (CN) must be identical to the hostname of the server, or SSL server authentication will not work.
    2. C:\nss11\winnt>certutil -R -s
    "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k b62b -o
    server_db\server.req -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":

  2. Create a new server certificate from the certificate request and sign it with the CA's private key.
    3. C:\nss11\winnt>certutil -C -c "MyCo's Root CA" 
    -i server_db\server.req -o server_db\server.crt -m 1222 -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":

  3. Add the new server certificate to the certificate database in the server_db directory with the appropriate trust flags and nickname.
    4. C:\nss11\winnt>certutil -A -n myco.mcom.org 
    -i server_db\server.crt -t "u,u,u" -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":
The trust flag settings "u,u,u" indicate that the certificate can be used for authentication or signing as an SSL certificate, an email certificate, or an object-signing certificate.

Setting Up the Client Certificate

Setting up the client certificate database involves three stages:

Creating the Databases and Generating the Keys
Creating the Client Certificate and Adding It to the Database
Adding the CA Certificate to the Database

Creating the Databases and Generating the Keys

The first step in setting up the client certificate is to create the certificate and key databases for the client and generate a key pair.

  1. Create a new certificate database in the client_db directory.
    2. C:\nss11\winnt>certutil -N -d client_db

  2. Create two key pairs in the client_db directory. The Certificate Database Tool automatically creates the key database directory when it creates the first key pair.
    3. C:\nss11\winnt>keyutil -G -d client_db

  3. List the public key.
    4. C:\nss11\winnt>keyutil -L -d client_db 
    Enter Password or Pin for "Communicator Certificate DB": 
    RSA Public-Key: 
       modulus: 
          00:d8:7e:3c:5b:26:9a:d5:77:69:7d:b8:b0:ce:6d:1e:fe:f6: 
          82:f9:b4:4b:4d:76:26:8b:e2:a4:fc:01:99:11:22:3f:21:0f: 
          85:26:d3:cd:4c:94:1f:a8:81:26:af:1b:08:41:4f:7f:4d:ad: 
          2f:c5:c5:4a:c2:41:1d:71:80:1c:4f:91:80:ae:e2:29:ab:a8: 
          1d:06:d1:f8:a9:1a:63:5f:09:cb:65:a5:a1:a4:8a:dc:29:5f: 
          85:d7:fc:3c:8e:64:ea:f5:a8:d7:12:d3:03:18:1b:54:24:1e: 
          7d:86:00:6d:b6:d8:80:c1:a7:98:8f:7e:f3:16:70:3f:bc:0f: 
          5e:56:c5

Creating the Client Certificate and Adding It to the Database

After the databases have been created and the key pair generated, create the client certificate and add it to the certificate database.

  1. Create the client certificate request, specifying the subject name for the certificate and the key d87e.
    2. C:\nss11\winnt>certutil -R -s
    "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k d87e -o
    client_db\client.req -d client_db 
    Enter Password or Pin for "Communicator Certificate DB":

  2. Create a new certificate from the certificate request and sign it with the CA's private key. Note that this key resides in the key database located in the directory server_db, as specified for the -d option. (This step assumes that the client certificate is being created on the same machine on which you created the server and CA certificates.)
    3. C:\nss11\winnt>certutil -C -c "MyCo's Root CA" 
    -i client_db\client.req -o client_db\client.crt -m 3434 -d server_db 
    Enter Password or Pin for "Communicator Certificate DB":

  3. Add the new server certificate to the certificate database in the client_db directory with the appropriate trust flags and nickname.
    4. C:\nss11\winnt>certutil -A -n myco.mcom.org 
    -i client_db\client.crt -t "u,u,u" -d client_db 
    Enter Password or Pin for "Communicator Certificate DB":

Adding the CA Certificate to the Database

The last step is to add the CA certificate to the client database so that the client can authenticate the server's certificate.

NOTE: The u flags should not be set in a root CA certificate intended for deployment in a real PKI for chaining purposes. Only the authorized CA should be able to sign anything or authenticate itself with a CA certificate.

Verifying the Server and Client Certificates

When you have finished setting up the server and client certificate databases, verify that the client and server certificates are valid, as follows:

C:\nss11\winnt>certutil -V -u V -n myco.mcom.org -d server_db 
Certificate:'myco.mcom.org' is valid! 
C:\nss11\winnt>certutil -V -u C -n myco.mcom.org -d client_db 
Certificate:'myco.mcom.org' is valid!

Building NSS Programs

The SSLSamples directory includes sample makefiles for building the sample programs. On Unix, use the GNU utility gmake to run the makefile. On Windows NT, use the nmake utility that comes with Visual C++.

If you create your own makefiles, be sure to include the libraries in the same order that they are listed in the sample makefiles. In addition, you must use the following compiler flags:

Solaris flags: 

-c -O -KPIC -DSVR4 -DSYSV -D__svr4 -D__svr4__ 
-DSOLARIS -D_REENTRANT -DSOLARIS2_5 -D_SVID_GETTOD 
-DXP_UNIX -UDEBUG -DNDEBUG
Windows NT flags: 

-c -O2 -MD -W3 -nologo -D_X86_ -GT 
-DWINNT -DXP_PC -UDEBUG -U_DEBUG -DNDEBUG 
-DWIN32 -D_WINDOWS
Table of Contents | Previous | Next | Index

Last Updated: 10/18/00 09:17:42