Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide

- Previous: Using Java Secure Socket Extension (JSSE) Tools
- Next: Further Information

## 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

- Importing and Exporting Certificates Using the `pk12util` Utility

- Adding and Deleting PKCS11 Modules using `modutil`

### Using the `certutil` Utility

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 <$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 <$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.

      <appserver_install>/lib/certutil -A -n <Internediate_CA_cert_name_to_display_at_DAS_certDB> -i <Intermediate_CA_cert> -t "cu,cu,cu" -d <domain_certdb>

- 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):

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

- Previous: Using Java Secure Socket Extension (JSSE) Tools
- Next: Further Information

- © 2010, Oracle Corporation and/or its affiliates