Installation of the Application Server generates a digital certificate in JSSE (Java Secure Socket Extension) or NSS (Network Security Services) format suitable for internal testing. By default, the Application Server stores its certificate information in a certificate database in the domain-dir/config directory:
Keystore file, key3.db, contains the Application Server's certificate, including its private key. The keystore file is protected with a password. Change the password using the asadmin change-master-password command. For more information about certutil, read Using the certutil Utility.
Each keystore entry has a unique alias. After installation, the Application Server keystore has a single entry with alias s1as.
Truststore file, cert8.db, contains the Application Server's trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate's owner. Trusted certificates generally include those of certification authorities (CAs).
In the Platform Edition, on the server side, the Application Server uses the JSSE format, which uses keytool to manage certificates and key stores. In the Enterprise Edition, on the server side, the Application Server uses NSS, which uses certutil to manage the NSS database which stores private keys and certificates. In both editions, the client side (appclient or stand-alone), uses the JSSE format.
By default, the Application Server is configured with a keystore and truststore that will work with the example applications and for development purposes. For production purposes, you may wish to change the certificate alias, add other certificates to the truststore, or change the name and/or location of the keystore and truststore files.
The keystore and truststore files provided for development are stored in the domain-dir/config directory.
Use the Admin Console to expand the server-config node > JVM Settings >JVM Options tab to add or modify the value field for the new location of the certificate files.
-Dcom.sun.appserv.nss.db=${com.sun.aas.instanceRoot}/NSS-database-directory |
where NSS-database-directory is the location of the NSS database.
Use keytool to set up and work with JSSE (Java Secure Socket Extension) digital certificates. In both the Platform Edition and Enterprise Edition, the client side (appclient or stand-alone) uses the JSSE format.
The J2SE SDK ships with keytool, which enables the administrator to administer public/private key pairs and associated certificates. It also enables users to cache the public keys (in the form of certificates) of their communicating peers.
To run keytool, the shell environment must be configured so that the J2SE /bin directory is in the path, or the full path to the tool must be present on the command line. For more information on keytool, see the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.
The following examples demonstrate usage related to certificate handling using JSSE tools:
Create a self-signed certificate in a keystore of type JKS using an RSA key algorithm. RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.
keytool -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias} -dname ${dn.name} -keypass ${key.pass} -keystore ${keystore.file} -storepass ${keystore.pass} |
Another example of creating a certificate is shown in Generating a Certificate Using the keytool Utility.
Create a self-signed certificate in a keystore of type JKS using the default key algorithm.
keytool -genkey -noprompt -trustcacerts -alias ${cert.alias} -dname ${dn.name} -keypass ${key.pass} -keystore ${keystore.file} -storepass ${keystore.pass} |
An example of signing a certificate is shown in Signing a Digital Certificate Using the keytool Utility
Display available certificates from a keystore of type JKS.
keytool -list -v -keystore ${keystore.file} -storepass ${keystore.pass} |
Display certificate information from a keystore of type JKS.
keytool -list -v -alias ${cert.alias} -keystore ${keystore.file} -storepass ${keystore.pass} |
Import an RFC/text-formatted certificate into a JKS store. Certificates are often stored using the printable encoding format defined by the Internet RFC (Request for Comments) 1421 standard instead of their binary encoding. This certificate format, also known as Base 64 encoding, facilitates exporting certificates to other applications by email or through some other mechanism.
keytool -import -noprompt -trustcacerts -alias ${cert.alias} -file ${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass} |
Export a certificate from a keystore of type JKS in PKCS7 format. The reply format defined by the Public Key Cryptography Standards #7, Cryptographic Message Syntax Standard, includes the supporting certificate chain in addition to the issued certificate.
keytool -export -noprompt -alias ${cert.alias} -file ${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass} |
Export a certificate from a keystore of type JKS in RFC/text format.
keytool -export -noprompt -rfc -alias ${cert.alias} -file ${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass} |
Delete a certificate from a keystore of type JKS.
keytool -delete -noprompt -alias ${cert.alias} -keystore ${keystore.file} -storepass ${keystore.pass} |
Another example of deleting a certificate from a keystore is shown in Deleting a Certificate Using the keytool Utility
Use keytool to generate, import, and export certificates. By default, keytool creates a keystore file in the directory where it is run.
Change to the directory where the certificate is to be run.
Always generate the certificate in the directory containing the keystore and truststore files, by default domain-dir/config. For information on changing the location of these files, see Changing the Location of Certificate Files.
Enter the following keytool command to generate the certificate in the keystore file, keystore.jks:
keytool -genkey -alias keyAlias-keyalg RSA -keypass changeit -storepass changeit -keystore keystore.jks |
Use any unique name as your keyAlias. If you have changed the keystore or private key password from their default, then substitute the new password for changeit in the above command.
A prompt appears that asks for your name, organization, and other information that keytool uses to generate the certificate.
Enter the following keytool command to export the generated certificate to the file server.cer (or client.cer if you prefer):
keytool -export -alias keyAlias-storepass changeit -file server.cer -keystore keystore.jks |
If a certificate signed by a certificate authority is required, see Signing a Digital Certificate Using the keytool Utility.
To create the truststore file cacerts.jks and add the certificate to the truststore, enter the following keytool command:
keytool -import -v -trustcacerts -alias keyAlias -file server.cer -keystore cacerts.jks -keypass changeit |
If you have changed the keystore or private key password from their default, then substitute the new password for changeit in the above command.
The tool displays information about the certificate and prompts whether you want to trust the certificate.
Type yes, then press Enter.
Then keytool displays something like this:
Certificate was added to keystore [Saving cacerts.jks] |
Restart the Application Server.
After creating a digital certificate, the owner must sign it to prevent forgery. E-commerce sites, or those for which authentication of identity is important can purchase a certificate from a well-known Certificate Authority (CA). If authentication is not a concern, for example if private secure communications is all that is required, save the time and expense involved in obtaining a CA certificate and use a self-signed certificate.
Follow the instructions on the CA's Web site for generating certificate key pairs.
Download the generated certificate key pair.
Save the certificate in the directory containing the keystore and truststore files, by default domain-dir/config directory. See Changing the Location of Certificate Files.
In your shell, change to the directory containing the certificate.
Use keytool to import the certificate into the local keystore and, if necessary, the local truststore.
keytool -import -v -trustcacerts -alias keyAlias -file server.cer -keystore cacerts.jks -keypass changeit -storepass changeit |
If the keystore or private key password is not the default password, then substitute the new password for changeit in the above command.
Restart the Application Server.
To delete an existing certificate, use the keytool -delete command, for example:
keytool -delete -alias keyAlias -keystore keystore-name -storepass password
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:
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 <$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.
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 |
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>
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 |
You can use hardware accelerator tokens to improve the cryptographic performance and to furnish a secure key storage facility. Additionally, you can provide end users with mobile secure key storage through smart cards.
Sun Java System Application Server 8.1 and 8.2 Standard Edition or Enterprise Edition when run on the Java 2 Platform, Standard Edition (J2SE platform) 5.0, supports the use of PKCS#11 tokens for SSL or TLS communications and Network Security Services (NSS) tools for managing keys and PKCS#11 tokens. This section describes how Application Server provides that support and walks you through the procedures for the related configurations.
J2SE 5.0 PKCS#11 providers can be easily integrated with the Application Server runtime. Through these providers, you can use hardware accelerators and other PKCS#11 tokens in Application Server to achieve fast performance and to protect the private key inherent in SSL or TLS communications.
This section contains the following topics:
Sun Java System Application Server 8.1 and 8.2 Standard Edition or Enterprise Edition have been tested with Sun Crypto Accelerator 1000 (SCA-1000) and SCA-4000.
Application Server, when used in conjunction with J2SE 5.0, can communicate with PKCS#11 tokens. Packaged with Application Server are an NSS PKCS#11 token library (for the NSS Internal PKCS#11 Module, commonly known as the NSS soft token) and NSS command-line management tools. For more details, see Using Network Security Services (NSS) Tools.
Use the NSS tools to create keys and certificates on PKCS#11 tokens and J2SE PKCS#11 providers to access token keys and certificates at runtime. A PKCS#11 provider is a cryptographic service provider that acts as a wrapper around a native PKCS#11 library. A PKCS#11 token generally refers to all the hardware and software tokens with a native PKCS#11 interface. A hardware token is a PKCS#11 token implemented in physical devices, such as hardware accelerators and smart cards. A software token is a PKCS#11 token implemented entirely in software.
If you run Application Server on the J2SE 1.4.x platform, only one PKCS#11 token, the NSS soft token, is supported.
For the Microsoft Windows environment, add the location of NSS libraries AS_NSS and the NSS tools directory, AS_NSS_BIN to the PATH environment variable. For simplicity, the procedures described in this section use UNIX commands only. You should replace the UNIX variables with the Windows variables, where appropriate.
Configuring the hardware crypto accelerators is divided into two main procedures:
This section describes how to configure PKCS#11 tokens with the NSS security tool modutil. Use the following procedure to configure a PKCS#11 token.
Enter the following command (all on one line):
modutil -dbdir AS_NSS_DB -nocertdb -force -add moduleName -libfile absolute_path_of_pkcs11_library -mechanisms list_of_security_mechanisms
where, AS_NSS_DB is the NSS database directory (same as AS_DOMAIN_CONFIG when you use the Domain Administration Server (DAS))
For example, to configure a hardware accelerator token, enter the following (all on one line):
modutil -dbdir AS_NSS_DB -nocertdb -force -add "Sun Crypto Accelerator" -libfile /opt/SUNWconn/crypto/lib/libpkcs11.so -mechanisms RSA:DSA:RC4:DES
The hardware accelerator in this example is a SCA–1000 cryptographic accelerator. The corresponding PKCS#11 library, by default, is located in /opt/SUNWconn/crypto/lib/libpkcs11.so.
The mechanisms must be a complete list of the cryptographic mechanisms that are available in the token. To use just a few of the available cryptographic mechanisms, see Configuring J2SE 5.0 PKCS#11 Providers. For a list of all supported mechanisms, see the modutil documentation on the NSS Security Tools site at http://www.mozilla.org/projects/security/pki/nss/tools.
The examples that follow assume that the token name specified at token installation time is mytoken.
To verify that the hardware accelerator is configured properly, enter the following command:
modutil -list -dbdir AS_NSS_DB
The standard output will look similar to the following:
Using database directory /var/opt/SUNWappserver/domains/domain1/config ... Listing of PKCS#11 Modules ----------------------------------------------------------- 1. NSS Internal PKCS#11 Module slots: 2 slots attached status: loaded slot: NSS Internal Cryptographic Services token: NSS Generic Crypto Services slot: NSS User Private Key and Certificate Services token: NSS Certificate DB 2. Sun Crypto Accelerator library name: /opt/SUNWconn/crypto/lib/libpkcs11.so slots: 1 slot attached status: loaded slot: Sun Crypto Accelerator:mytoken token: mytoken ----------------------------------------------------------- |
This section describes a few common procedures for creating and managing keys and certificates using certutil and pk12util. For details on certutil and pk12util, see Using Network Security Services (NSS) Tools and documentation on the NSS Security Tools site at http://www.mozilla.org/projects/security/pki/nss/tools.
By configuring a PKCS#11 provider in the java.security properties file (located in the JAVA_HOME/jre/lib/security directory of the Java runtime), you can also use the J2SE keytool utility to manage keys and certificates.
This section describes the following topics:
To list the keys and certificates in the configured PKCS#11 tokens, run the following command:
certutil -L -d AS_NSS_DB [-h tokenname]
For example, to list the contents of the default NSS soft token, type:
certutil -L -d AS_NSS_DB
The standard output will be similar to the following:
verisignc1g1 T,c,c verisignc1g2 T,c,c verisignc1g3 T,c,c verisignc2g3 T,c,c verisignsecureserver T,c,c verisignc2g1 T,c,c verisignc2g2 T,c,c verisignc3g1 T,c,c verisignc3g2 T,c,c verisignc3g3 T,c,c s1as u,u,u |
The output displays the name of the token in the left column and a set of three trust attributes in the right column. For Application Server certificates, it is usually T,c,c. Unlike the J2SE java.security.KeyStore API, which contains only one level of trust, the NSS technology contains several levels of trust. Application Server is primarily interested in the first trust attribute, which describes how this token uses SSL. For this attribute:
T indicates that the Certificate Authority (CA) is trusted for issuing client certificates. |
u indicates that you can use the certificates (and keys) for authentication or signing. |
The attribute combination of u,u,u indicates that a private key exists in the database. |
To list the contents of the hardware token, mytoken, run the following command:
certutil -L -d AS_NSS_DB -h mytoken
You will be prompted for the password for the hardware token. The standard output is similar to the following:
Enter Password or Pin for "mytoken": mytoken:Server-Cert 	u,u,u |
Use certutil to create self-signed certificates and to import or export certificates. To import or export private keys, use the pk12util utility. For more details, see Using Network Security Services (NSS) Tools
In Application Server, do not modify the NSS password directly with the NSS tools certutil and modutil. If you do so, security data in Application Server might be corrupted.
Application Server relies on J2SE PKCS#11 providers to access keys and certificates that are located in PKCS#11 tokens at runtime. By default, Application Server configures a J2SE PKCS#11 provider for the NSS soft token. This section describes how to override the default configuration for the J2SE PKCS#11 provider.
In Application Server, the following default PKCS#11 configuration parameters are generated for each PKCS#11 token.
Configuration for the default NSS soft token:
name=internal library=${com.sun.enterprise.nss.softokenLib} nssArgs="configdir='${com.sun.appserv.nss.db}' certPrefix='' keyPrefix='' secmod='secmod.db'" slot=2 omitInitialize = true |
Configuration for the SCA 1000 hardware accelerator:
name=HW1000 library=/opt/SUNWconn/crypto/lib/libpkcs11.so slotListIndex=0 omitInitialize=true |
These configurations conform to the syntax described in the Java PKCS#11 Reference Guide.
The name parameter has no requirements other than that it must be unique. Certain older versions of J2SE 5.0 support alphanumeric characters only.
You can override the default configuration parameters by creating a custom configuration file. For example, you can explicitly disable the RSA Cipher and RSA Key Pair Generator in SCA–1000. For details on disabling the RSA Cipher and RSA Key Pair Generator, see http://www.mozilla.org/projects/security/pki/nss/tools.
To create a custom configuration file:
Create a configuration file called install-dir/mypkcs11.cfg with the following code and save the file.
name=HW1000 library=/opt/SUNWconn/crypto/lib/libpkcs11.so slotListIndex=0 disabledMechanisms = { 	CKM_RSA_PKCS 	CKM_RSA_PKCS_KEY_PAIR_GEN } omitInitialize=true |
Update the NSS database, if necessary. In this case, update the NSS database so that it will disable RSA.
Run the following command :
modutil -undefault "Sun Crypto Accelerator" -dbdir AS_NSS_DB -mechanisms RSA |
The name of the algorithm on the mechanisms list differs from the one in the default configuration. For a list of valid mechanisms in NSS, see the modutil documentation on the NSS Security Tools site at http://www.mozilla.org/projects/security/pki/nss/tools.
Update the server with this change by adding a property in the appropriate location, as follows:
<property name="mytoken" value="&InstallDir;/mypkcs11.cfg"/> |
The location for the property could be one of the following:
If the provider is for a DAS or server instance, add the property under the associated <security-service>.
If the provider is for a node agent, add the property under the associated <node-agent> element in the domain.xml file.
Restart the Application Server.
The customized configurations will be in effect after the restart.