Upgrading Installations That Use NSS Cryptographic Tokens

GlassFish Server v2.x EE (Enterprise Edition) uses Network Security Services (NSS) for cryptographic software tokens. GlassFish Server 3.1 does not support NSS, so when performing an upgrade from v2.x EE to 3.1 additional manual configuration steps must be performed.

The following topics are addressed here:

• To Prepare for the Upgrade

• To Perform Post-Upgrade Configuration

• To Upgrade PKCS#11 Hardware Tokens

To Prepare for the Upgrade

This procedure explains how to prepare for modifying an NSS-based GlassFish Server 2.x installation when upgrading to GlassFish Server 3.1.

1. Download and install GlassFish Server 3.1 using the Typical Installation path.

   Ensure that you install the new GlassFish Server 3.1 product in a directory that is different than the one used for the older installation from which you are upgrading.

   See Installing GlassFish Server From a Self-Extracting Bundle in Oracle GlassFish Server 3.1 Installation Guide for instructions.

2. Rename the new GlassFish Server 3.1 as-install/domains/domain1 directory to a name of your choice.

   In this procedure, 31domain is used for the renamed GlassFish Server 3.1 domain.

3. Copy the older source domain to be upgraded to the new GlassFish Server 3.1 as-install/domains directory.

   In this procedure, domain1 is used for the older source domain that is copied to the new GlassFish Server 3.1 installation.

   ---

   Note - The remaining steps in this procedure are performed on the copy of your source domain that you created in this step, rather than on your original source domain. It is strongly recommended that you perform the GlassFish Server 3.1 upgrade on a copy of your old domain rather than on the original.

   ---

4. Copy the server.policy, keystore.jks, and cacerts.jks files from the renamed ./31domain/config directory to the ./domain1/config directory to be upgraded.

   For example:

   cp as-install/domains/31domain/config/server.policy as-install/domains/domain1/config
   cp as-install/domains/31domain/config/keystore.jks as-install/domains/domain1/config
   cp as-install/domains/31domain/config/cacerts.jks as-install/domains/domain1/config

   This will overwrite the master password for ./domain1 with the password used in the ./31domain.

5. Modify the domain.xml file for ./domain1.
   1. Add the following jvm-options under server-config and default-config:

      -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks
      -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks

   2. Remove the following jvm-option under server-config and default-config:

      -Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/config

6. Upgrade ./domain1 by starting the DAS in the new GlassFish Server 3.1 installation with the --upgrade option.

   as-install-parent/glassfish/bin/asadmin start-domain --upgrade domain1

   This upgrades the domain and then shuts down the DAS.

7. Start the upgraded DAS normally.

   as-install-parent/glassfish/bin/asadmin start-domain domain1

To Perform Post-Upgrade Configuration

These instructions explain the post-upgrade configuration steps that must be performed when upgrading from an NSS-based installation to GlassFish Server 3.1.

Before You Begin

Before proceeding with this procedure, complete the procedure explained in To Prepare for the Upgrade.

1. Start the GlassFish Server 3.1 domain, if it is not already running, and open the GlassFish Server Admin Console in a browser window.

   The default URL is https://localhost:4848

   As part of the To Prepare for the Upgrade procedure, the default keystore with a default self-signed key-certificate pair with an alias named s1as and a keystore password changeit was copied into the v2.x domain before the upgrade.

2. If your default server alias in the NSS v2.x domain is not s1as, you can delete this entry using the following command:

   keytool -delete -keystore keystore.jks -storepass changeit -alias s1as
   keytool -delete -keystore cacerts.jks -storepass changeit -alias s1as

3. If the master password for the v2.x domain is not the default password changeit, you need to change the new keystore password to match the v2.x master password.

   keytool -storepasswd -new v2-master-password \
   -keystore keystore.jks -storepass changeit
   keytool -storepasswd -new v2-master-password \
   -keystore cacerts.jks -storepass changeit

4. Take note of all the KeyEntries that exist in your NSS database.

   These entries must be migrated to the keystore.jks in the GlassFish Server 3.1 domain. The following command can be used to list all the KeyEntries in the NSS database:

   certutil -L -d $AS_NSS_DB

   AS_NSS_DB should point to the ${com.sun.aas.instanceRoot}/config for the 3.1 instance into which the v2.x domain was copied. The listing with the attribute combinations u,u,u are the KeyEntries.

   For example:

   s1as u,u,u

   ---

   Note - To run the certutil command, your LD_LIBRARY_PATH must point to the directory containing NSS library and DLLs.

   ---

5. For each PrivateKey-Certificate pair (KeyEntry) that exists in the v2.x NSS database, use the following commands to export them from the NSS database and import them into the newly created keystore.jks file.

   Make sure you use the same alias when importing the KeyEntry into the JKS keystore. For example, if s1as is the only alias present in the NSS database, the following command can be used:

   > pk12util -o /tmp/s1as_pk.p12 -n s1as -d $AS_NSS_DB
   
   >keytool -importkeystore -srckeystore /tmp/s1as_pk.p12 -destkeystore \
   ${com.sun.aas.instanceRoot}/config/keystore.jks -srcstoretype PKCS12 \
   -deststoretype JKS -srcstorepass v2-master-password \
   -deststorepass v3-master-password -srcalias s1as \
   -destalias s1as -srckeypass v2-master-password \
   -destkeypass v3-master-password

   ---

   Note - The reference to v3-master-password could be the same as v2-master-password if you intend to retain the same master password for the 3.1 domain after upgrading from v2.x.

   ---

6. If the s1as alias represents a KeyEntry with a self-signed certificate, the self-signed certificate must be copied to the truststore.

   >certutil -L -n s1as -r -d $AS_NSS_DB > /tmp/s1as.der
   >keytool -import -keystore cacerts.jks -storepass v3-master-password \
   -file /tmp/s1as.der -alias s1as

7. There is a rare chance that the 2.x NSS database has some CA (Certificate Authority) certificates that are absent in the default created truststore. In such cases, all aliases that are missing in the truststore (cacerts.jks) need to collected.
   1. certutil -L -d $AS_NSS_DB

      Example output:

      verisignc1g1 T,c,c
      verisignc1g2 T,c,c
      verisignc1g3 T,c,c

   2. keytool -list -keystore cacerts.jks -storepass v3-master-password

      Example output:

      godaddyclass2ca, Jan 20, 2005, trustedCertEntry,
      Certificate fingerprint (MD5): 91:DE:06:25:AB:DA:FD:32:17:0C:BB:25:17:2A:84:67
      verisignclass1g3ca, Mar 26, 2004, trustedCertEntry,
      Certificate fingerprint (MD5): B1:47:BC:18:57 1:18:A0:78:2D:EC:71:E8:2A:95:73
      secomevrootca1, May 1, 2008, trustedCertEntry,
      Certificate fingerprint (MD5): 22:2D:A6:01:EA:7C:0A:F7:F0:6C:56:43:3F:77:76 3

8. For each of the aliases from the certutil output in the preceding step that are required but missing in the truststore listing, execute the following commands to export and import them into the 3.1 domain's truststore.

   >certutil -L -n verisignc1g1 -r -d $AS_NSS_DB > /tmp/verisignc1g1.der
   >keytool -import -keystore cacerts.jks -storepass v3-master-password \
   -file /tmp/verisignc1g1.der -alias verisignc1g1

   ---

   Note - Sometimes just the alias names that are used in the NSS database are different, and the same certificate is, in fact, present in the 3.1 default truststore.

   ---

To Upgrade PKCS#11 Hardware Tokens

If you are using GlassFish Server v2.x Enterprise Edition with Hardware Tokens (for example, FIPS-140 compliant Sun Cryptographic Accelerator 6000 or other Sun Cryptographic Accelerators) configured by means of NSS-PKCS11, then the v2.x EE-to-3.1 upgrade solution is to directly configure the Hardware Token as a PKCS11 token using the JDK-JSSE supported mechanisms for configuring PKCS#11 tokens.

1. Set the javax.net.ssl.keyStoreType jvm-options in GlassFish Server 3.1 to PKCS11.

   <jvm-options>-Djavax.net.ssl.keyStoreType=PKCS11</jvm-options>

2. Set the javax.net.ssl.keyStore URL should be set to l since this is a hardware token.

   <jvm-options>-Djavax.net.ssl.keyStore=NONE</jvm-options>

3. Change the password for the truststore and the GlassFish Server MasterPassword to match the PIN of your HardwareToken.
4. Since you are using a Hardware Token, you can delete the keystore.jks for the migrated domain.
5. Ensure the token-alias for the hardware token (private key) that you intend to use as the Server's Key for SSL is mentioned in every relevant place in the domain.xml for the domain.

   For example, the cert-nickname attribute for the <ssl/> element under the protocol configuration.

6. If the Hardware Token is to act as a TrustStore as well then remove the cacerts.jks file from the as-install/domains/domain-name/config directory.

   Ensure that the following two jvm-options are set in the domain.xml file:

   <jvm-options>-Djavax.net.ssl.trustStore=NONE</jvm-options>
   <jvm-options>-Djavax.net.ssl.trustStoreType=PKCS11</jvm-options>