Using Network Security Services (NSS) Tools (Sun Java System Application Server Enterprise Edition 8.2 Administration Guide)

Sun Java System Application Server Enterprise Edition 8.2 Administration Guide

Using Network Security Services (NSS) Tools

In the Enterprise Edition, use Network Security Services (NSS) digital certificates on the server-side to manage the database that stores private keys and certificates. For the client side (appclient or stand-alone), use the JSSE format as discussed in Using Java Secure Socket Extension (JSSE) Tools.

The tools for managing security with Network Security Services (NSS) include the following:

certutil, a command-line utility for managing certificates and key databases. Some examples using the certutil utility are shown in Using the certutil Utility.
pk12util, a command-line utility used to import and export keys and certificates between the certificate/key databases and files in PKCS12 format. Some examples using the pk12util utility are shown in Importing and Exporting Certificates Using the pk12util Utility.
modutil, a command-line utility for managing PKCS #11 module information within secmod.db files or within hardware tokens. Some examples using the modutil utility are shown in Adding and Deleting PKCS11 Modules using modutil.

The tools are located in the install-dir/lib/ directory. The following environment variables are used to point to the location of the NSS security tools:

LD_LIBRARY_PATH =${install-dir}/lib
${os.nss.path}

In the examples, the certificate common name (CN) is the name of the client or server. The CN is also used during SSL handshake for comparing the certificate name and the host name from which it originates. If the certificate name and the host name do not match, warnings or exceptions are generated during SSL handshake. In some examples, the certificate common name CN=localhost is used for convenience so that all users can use that certificate instead of creating a new one with their real host name.

The examples in the following sections demonstrate usage related to certificate handling using NSS tools:

Using the `certutil` Utility

Before running certutil, make sure that LD_LIBRARY_PATH points to the location of the libraries required for this utility to run. This location can be identified from the value of AS_NSS_LIB in asenv.conf (product wide configuration file).

The certificate database tool, certutil, is an NSS command-line utility that can create and modify the Netscape Communicator cert8.db and key3.db database files. It can also list, generate, modify, or delete certificates within the cert8.db file and create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key3.db file.

The key and certificate management process generally begins with creating keys in the key database, then generating and managing certificates in the certificate database. The following document discusses certificate and key database management with NSS, including the syntax for the certutil utility: http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html.

Each of the items in the list below gives an example using NSS and JSSE security tools to create and/or manage certificates.

Generate a self-signed server and client certificate. In this example, the CN must be of the form hostname.domain.[com|org|net|...].

In this example, domain-dir/config. The serverseed.txt and clientseed.txt files can contain any random text. This random text will be used for generating the key pair.

certutil -S -n $SERVER_CERT_NAME -x -t "u,u,u"
 -s "CN=$HOSTNAME.$HOSTDOMAIN, OU=Java Software, O=Sun Microsystems Inc., 
    L=Santa Clara, ST=CA, C=US"
 -m 25001 -o  $CERT_DB_DIR/Server.crt
 -d $CERT_DB_DIR -f passfile &lt;$CERT_UTIL_DIR/serverseed.txt

Generate the client certificate. This certificate is also a self-signed certificate.

certutil -S -n $CLIENT_CERT_NAME  -x -t "u,u,u"
 -s "CN=MyClient, OU=Java Software, O=Sun Microsystems Inc., 
    L=Santa Clara, ST=CA, C=US"
 -m 25002 -o  $CERT_DB_DIR/Client.crt
 -d $CERT_DB_DIR -f passfile &lt;$CERT_UTIL_DIR/clientseed.txt

Verify the certificates generated in the previous bullet.

certutil -V -u V -n $SERVER_CERT_NAME -d  $CERT_DB_DIR
certutil -V -u C -n $CLIENT_CERT_NAME -d  $CERT_DB_DIR

Display available certificates.
certutil -L -d $CERT_DB_DIR

Import an RFC text-formatted certificate into an NSS certificate database.

certutil -A -a -n ${cert.nickname} -t ${cert.trust.options} 
-f ${pass.file} -i ${cert.rfc.file} 
-d ${admin.domain.dir}/${admin.domain}/config

Export a certificate from an NSS certificate database in RFC format.

certutil -L -a -n ${cert.nickname} -f ${pass.file} 
-d ${admin.domain.dir}/${admin.domain}/config > cert.rfc

Delete a certificate from an NSS certificate database.

certutil -D -n ${cert.nickname} -f ${pass.file} 
-d ${admin.domain.dir}/${admin.domain}/config

Move a certificate from an NSS database to JKS format

certutil -L -a -n ${cert.nickname} 
-d ${admin.domain.dir}/${admin.domain}/config > cert.rfc
keytool  -import -noprompt -trustcacerts -keystore ${keystore.file} 
-storepass ${keystore.pass} -alias ${cert.alias} -file cert.rfc

Importing and Exporting Certificates Using the `pk12util` Utility

The command-line utility used to import and export keys and certificates between the certificate/key databases and files in PKCS12 format is pk12util. PKCS12 is Public-Key Cryptography Standards (PKCS) #12, Personal Information Exchange Syntax Standard. More description of the pk12util utility can be read at http://www.mozilla.org/projects/security/pki/nss/tools/pk12util.html.

Import a PKCS12-formatted certificate into an NSS certificate database.

pk12util -i ${cert.pkcs12.file} -k ${certdb.pass.file} 
-w ${cert.pass.file} -d ${admin.domain.dir}/${admin.domain}/config

Import a PKCS12-formatted certificate into an NSS certificate database token module.

pk12util -i ${cert.pkcs12.file} -h ${token.name} -k ${certdb.pass.file} 
-w ${cert.pass.file} -d ${admin.domain.dir}/${admin.domain}/config

Export a certificate from an NSS certificate database in PKCS12 format.

pk12util -o -n ${cert.nickname} -k ${pass.file} -w${cert.pass.file} 
-d ${admin.domain.dir}/${admin.domain}/config

Export a certificate from an NSS certificate database token module in PKCS12 format (useful for hardware accelerator configuration).

pk12util -o -n ${cert.nickname} -h ${token.name} -k ${pass.file} 
-w ${cert.pass.file} -d ${admin.domain.dir}/${admin.domain}/config

Convert a PKCS12 certificate into JKS format (requires a Java source):

&lt;target name="convert-pkcs12-to-jks" depends="init-common">
   &lt;delete file="${jks.file}" failonerror="false"/>
   &lt;java classname="com.sun.enterprise.security.KeyTool">
      &lt;arg line="-pkcs12"/>
      &lt;arg line="-pkcsFile ${pkcs12.file}"/>
      &lt;arg line="-pkcsKeyStorePass ${pkcs12.pass}"/>
      &lt;arg line="-pkcsKeyPass ${pkcs12.pass}"/>
      &lt;arg line="-jksFile ${jks.file}"/>
      &lt;arg line="-jksKeyStorePass ${jks.pass}"/>
      &lt;classpath>
         &lt;pathelement path="${s1as.classpath}"/>
         &lt;pathelement path="${env.JAVA_HOME}/jre/lib/jsse.jar"/>
      &lt;/classpath>
   &lt;/java>
&lt;/target>

Adding and Deleting PKCS11 Modules using `modutil`

The Security Module Database Tool, modutil, is a command-line utility for managing PKCS #11 (Cryptographic Token Interface Standard) module information within secmod.db files or within hardware tokens. You can use the tool 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. This tool can also create key3.db, cert7.db, and secmod.db security database files. For more information on this tool, see http://www.mozilla.org/projects/security/pki/nss/tools/modutil.html.

Add a new PKCS11 module or token.

modutil -add ${token.module.name} -nocertdb -force -mechanisms RSA:DSA:RC4:DES 
-libfile ${SCA.lib.path} -dbdir ${admin.domain.dir}/${admin.domain}/config

Delete a PKCS11 module from an NSS store.

modutil -delete ${token.module.name} -nocertdb -force -mechanisms RSA:DSA:RC4:DES 
-libfile ${SCA.lib.path} -dbdir ${admin.domain.dir}/${admin.domain}/config

List available token modules in an NSS store.

modutil -list  -dbdir ${admin.domain.dir}/${admin.domain}/config