Sun Java System Application Server 9.1 Administration Guide

Using Hardware Crypto Accelerator With Application Server

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

About Configuring Hardware Crypto Accelerators

Sun Java System Application Serverhas 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.

Note –

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:

Configuring PKCS#11 Tokens

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

Managing Keys And Certificates

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.

Note –

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. For details on using keytool, and Java PKCS#11 Reference Guide at http://java.sun.com/j2se/1.5.0/docs/guide/security/p11guide.html.

This section describes the following topics:

Listing Keys and Certificates

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

Working With Private Keys and Certificates

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

Caution –

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.

Configuring J2SE 5.0 PKCS#11 Providers

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.

Note –

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 as-install/mypkcs11.cfg with the following code and save the file.

name=HW1000
library=/opt/SUNWconn/crypto/lib/libpkcs11.so
slotListIndex=0
disabledMechanisms = {
&#9;CKM_RSA_PKCS
&#9;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.