Sun GlassFish Enterprise Server v2.1.1 Administration Guide

Using Hardware Crypto Accelerator With Enterprise 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 Enterprise 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 Enterprise Server runtime. Through these providers, you can use hardware accelerators and other PKCS#11 tokens in Enterprise 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 GlassFish Enterprise Server has been tested with Sun Crypto Accelerator 1000 (SCA-1000) and SCA-4000.

Enterprise Server can communicate with PKCS#11 tokens. Packaged with Enterprise 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 Enterprise 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/ -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/

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

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/
         slots: 1 slot attached
        status: loaded

         slot: Sun Crypto Accelerator:mytoken
        token: mytoken


Passing Additional Passwords for a PKCS#11 Crypto Device

For standard parameters, you can create a password alias in the password file. For example, you can create a password alias for the admin password as follows:


To pass in additional (non-standard) passwords, you need to create an entry in the password file and use the create-password-alias command for that entry.

For a PKCS#11 crypto-device that works with GlassFish, add an entry, as follows, to the GlassFish password file.


Then create a password alias. For example, if you are using the Sun Metaslot device with GlassFish, the asadmin start-domain command would prompt for password as follows:

asadmin start-domain Starting Domain domain1, please wait. 
Default Log location is /opt/glassfish/domains/domain1/logs/server.log. 
Please enter password for NSS slot Sun Metaslot>  

To pass this non-standard password as an additional password, do the following:

  1. Add an entry to the GlassFish password file (specified by the --passwordfile option) as follows:

  2. Create the password alias as follows:

    asadmin> create-password-alias --user admin --passwordfile mypwdfile abc123
  3. Replace the password in the GlassFish password file with the alias password as follows:


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

Note –

By configuring a PKCS#11 provider in the 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

This section describes the following topics:

Listing Keys and Certificates

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

In Enterprise Server, do not modify the NSS password directly with the NSS tools certutil and modutil. If you do so, security data in Enterprise Server might be corrupted.

Configuring J2SE 5.0 PKCS#11 Providers

Enterprise Server relies on J2SE PKCS#11 providers to access keys and certificates that are located in PKCS#11 tokens at runtime. By default, Enterprise 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 Enterprise Server, the following default PKCS#11 configuration parameters are generated for each PKCS#11 token.

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

To create a custom configuration file:

  1. Create a configuration file called as-install/mypkcs11.cfg with the following code and save the file.

    disabledMechanisms = {
  2. 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

  3. Update the server with this change by adding a property in the appropriate location, as follows:

    &lt;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 &lt;security-service>.

    • If the provider is for a node agent, add the property under the associated &lt;node-agent> element in the domain.xml file.

  4. Restart the Enterprise Server.

    The customized configurations will be in effect after the restart.