gtstd.html

In This Article

This page is part of the SSL Reference that we are migrating into the format described in the MDN Style Guide. If you are inclined to help with this migration, your help would be very much appreciated.

Upgraded documentation may be found in the Current NSS Reference

Getting Started With SSL

Chapter 2
Getting Started With SSL

This chapter describes how to set up your environment, including certificate and key databases.

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

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:

The default Netscape Internal PKCS #11 Module comes with two built-in tokens:
- The Generic Crypto Services token performs all cryptographic operations, such as encryption, decryption, and hashing.
- The Communicator Certificate DB token handles all communication with the certificate and key database files (called certX.db and keyX.db, respectively, where X is a version number) that store certificates and keys.
The FORTEZZA module is intended for use with FORTEZZA hardware tokens.
The FIPS 140-1 module is compliant with the FIPS 140-1 government standard for implementations of cryptographic modules. Many products sold to the U.S. government must comply with one or more of the FIPS standards. The FIPS 140-1 module includes a single, built-in FIPS 140-1 Certificate DB token (see Figure 2.1), which handles both cryptographic operations and communication with the certX.db and keyX.db files.

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 DB and Certificate
Setting Up the Server DB and Certificate
Setting Up the Client DB and Certificate
Verifying the Server and Client Certificates

WARNING: The instructions below illustrate the use of NSS command line tools to operate a simple root Certificate Authority for test purposes only. The CA, SSL server and SSL client certificates produced by these instructions work correctly for short term testing purposes. Although it is possible to use NSS command line tools to operate a proper CA, these instructions do not provide nearly enough understanding of the many considerations required to competently operate a CA. The NSS teams strongly recommends that users should not attempt to operate a CA for use in mission critical production business uses using NSS's command line tools, nor with the simple command line test tools that come with any package of cryptographic libraries. Many who have attempted it have eventually come to regret that decision. For production deployment, the NSS team strongly recommends that you either:

Use certificates from a competent third-party CA that is already known to your relying party software (e.g. your SSL clients), or

Use professional grade CA software, such as Red Hat's Dogtag Certificate System, to set up and operate your own CA and issue your own certificates.

For complete information about the command-line options used in the examples that follow, see Using the Certificate Database Tool.