| This information is now currently in the upgrade guide. GlassFish V2.X EE(Enterprise Edition) uses NSS as a cryptographic software token. GlassFish V3.1 does not support NSS. So when doing an upgrade from V2.X EE to V3.1 the following steps need to be followed to perform a manual upgrade. A script that can automate these manual steps may be provided in future via Update Center. 0. Copy the V2.XEE domain into GF V3.1 domains/ directory. (Note from Bobby: these instructions assume the upgrade was performed by copying the domain to the 3.1 server and then running 'asadmin start-domain --upgrade'. You can still use the upgrade tool for testing, however. Just copy the v2.X domain to some other location before performing the steps below so that you don't affect your original v2.X installation. Then use this copy of domain1 as the source. You can even copy the domain to the 3.1 domains directory and the upgrade tool will do the right thing.) Manual steps to be carried out before upgrade (after copying the V2.XEE domain into GF V3.1)1. Copy the server.policy,keystore.jks, cacerts.jks from original V3.1 domain to the to-be-upgraded domain/config directory. Note that this will overwrite the master password for the domain with the one in the v3.1 installation. 2. Modify the domain.xml of the to-be-upgraded domain to a. add the following jvm-options in server-config and default-config: -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks b. remove the following <jvm-option>in server-config and default-config: -Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/config Now perform the upgrade. Manual Steps to be Carried out after upgrade1. Start the server and access the admin page : https://<hostname>:4848 2. The default keystore with a default self-signed key-certificate pair with alias s1as and keystore password changeit has been copied into this domain before running upgrade. If your default server alias in the NSS V2 domain is not s1as then you can delete this entry using the following command : keytool -delete -keystore keystore.jks -storepass changeit -alias s1as 3. If the masterpassword of the V2 domain being upgraded is not the default password "changeit" then you need to change the keystore password to match the master password keytool -storepasswd -new <masterpassword of v2 domain> -keystore keystore.jks -storepass changeit 4. Make a note of all the KeyEntries that exist in your NSS DB . They need to be migrated to the keystore.jks in the V3.1 domain. The following command can be used to list all the KeyEntries in the NSS DB. certutil -L -d $AS_NSS_DB here AS_NSS_DB should point to ${com.sun.aas.instanceRoot}/config of the V3.1 instance where the V2.X domain was copied. The listing with attribute combinations u,u,u are the KeyEntries. Example : CertUtil output s1as u,u,u Note : to run certutil you need to set the LD_LIBRARY_PATH to point to the directory containing NSS library/dll's. 5. For each PrivateKey-Certificate Pair (KeyEntry) that exists in the NSS Database (as determined in step 5) of the V2 Domain execute the following commands to export them from the NSS DB and import them into the newly created keystore.jks. 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 DB 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 <masterpassword of V2 domain> -deststorepass <masterpassword of new V3 domain> -srcalias s1as -destalias s1as -srckeypass <masterpassword of V2 domain> -destkeypass <masterpassword of new V3 domain> Note: the reference to <masterpassword of new V3 domain> above could actually be the same as <masterpassword of V2 domain> if you intend to retain the same masterpassword for the V3 domain post upgrade from V2. Refer to step 3 above where we originally set the password for keystore.jks to be the <masterpassword of V2 domain> If the Alias s1as represents a KeyEntry with a Self-Signed Certificate (generally true only during development and is not expected to be the case for a V2 instance in production) the an additional step of copying the self-signed certificate to the truststore needs to be executed. >certutil -L -n s1as -r -d $AS_NSS_DB > /tmp/s1as.der 6. The default truststore has been copied into the domain before upgrade as mentioned in the steps above. The default truststore is actually a copy of the cacerts file that exists in JDK1.6 jre/lib/security and hence will contain most of the CA's that are widely used in realworld. There is a rare chance that the NSS DB of the V2.X domain had some CA (Certificate Authority) certificates which are absent in the default created truststore. In such cases again a certutil listing of the NSS DB can be compared with the keytool listing of the truststore. All such aliases which are missing in the truststore (cacerts.jks) need to collected. certutil -L -d $AS_NSS_DB Example : certutil output keytool -list -keystore cacerts.jks -storepass <masterpassword of new V3 domain> Example : keytool list output 7. For each of the aliases from the certutil output in step 7 above that you think are needed and missing in the truststore listing (keytool output) in step 7 above, execute the following commands to export and import them into the V3.1 domains truststore. Example : missing alias verisignc1g1 >certutil -L -n verisignc1g1 -r -d $AS_NSS_DB > /tmp/verisignc1g1.der Note: Sometimes it is just the alias names that are used in NSS DB are different and really the same certificate would be present in the V3.1 default truststore. Hardware PKCS#11 tokens configured via NSSIf you are using GlassFishV2.X Enterprise Edition with Hardware Tokens (eg. FIPS-140 compliant Sun Cryptographic Accelerator 6000 or other Sun Cryptographic Accelerator(s) http://www.sun.com/products/networking/sslaccel/.) configured Via NSS-PKCS11 http://developers.sun.com/appserver/reference/techart/keymgmt.html#2 , then the V2.X EE to V3.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. http://download-llnw.oracle.com/javase/7/docs/technotes/guides/security/p11guide.html#JSSE The following additional steps need to be carried out on the GlassFish instance: 1. Set the javax.net.ssl.keyStoreType <jvm-options> in GlassFish to PKCS11. <jvm-options>-Djavax.net.ssl.keyStoreType=PKCS11</jvm-options> 2. The javax.net.ssl.keyStore url should be set to NONE since this is a hardware token. <jvm-options>-Djavax.net.ssl.keyStore=NONE</jvm-options> 3. The default truststore (cacerts.jks) for the migrated domain has already been copied into this domain as in the steps above. The password for the truststore is "changeit" by default. You should change the password for the truststore and also the GlassFish MasterPassword to match the PIN of your HardwareToken. 4. The default keystore (keystore.jks)with a default s1as key-pair for the migrated domain has already been copied into this domain as in the steps above . Since you are using a Hardware Token you may just delete this keystore.jks 5. Ensure the token-alias of the hardware token (private key) that you intend to use as the Server's Key for SSL is mentioned at every place in domain.xml (eg cert-nickname attribute of the <ssl/> element of protocol config). Note : this should already be the case since we are migrating a working V2.X EE domain to V3. 6. If the Hardware Token is to act as a TrustStore as well then remove the cacerts.jks file from domains/domainx/config. Ensure that the following two jvm-options are set in domain.xml <jvm-options>-Djavax.net.ssl.trustStore=NONE</jvm-options> |
1:18:A0:78:2D:EC:71:E8:2A:95:73