Sun GlassFish Enterprise Server v2.1.1 Administration Guide

Chapter 9 Configuring Security

Security is about protecting data: how to prevent unauthorized access or damage to it in storage or transit. The Enterprise Server; has a dynamic, extensible security architecture based on the Java EE standard. Built in security features include cryptography, authentication and authorization, and public key infrastructure. The Enterprise Server is built on the Java security model, which uses a sandbox where applications can run safely, without potential risk to systems or users. The following topics are discussed:

Understanding Application and System Security

Broadly, there are two kinds of application security:

In addition to application security, there is also system security, which affects all the applications on an Enterprise Server system.

Programmatic security is controlled by the application developer, so this document does not discuss it; declarative security is somewhat less so, and this document touches on it occasionally. This document is intended primarily for system administrators, and so focuses on system security.

Tools for Managing Security

The Enterprise Server provides the following tools for managing security:

The Java Platform, Standard Edition (Java SE) provides two tools for managing security:

For more information on using keytool, policytool, and other Java security tools, see JDK Tools and Utilities at

In the Enterprise Profile, two other tools that implement Network Security Services (NSS) are available for managing security. For more information on NSS, go to The tools for managing security include the following:

For more information on using certutil, pk12util, and other NSS security tools, see NSS Security Tools at

Managing Security of Passwords

In Enterprise Server, the file domain.xml, which contains the specifications for a particular domain, initially contains the password of the Message Queue broker in clear text. The element in the domain.xml file that contains this password is the admin-password attribute of the jms-host element. Because this password is not changeable at installation time, it is not a significant security impact.

However, use the Admin Console to add users and resources and assign passwords to these users and resources. Some of these passwords are written to the domain.xml file in clear text, for example, passwords for accessing a database. Having these passwords in clear text in the domain.xml file can present a security hazard. You can encrypt any password in domain.xml, including the admin-password attribute or a database password. Instructions for managing the security passwords is included in the following topics:

Encrypting a Password in the domain.xml File

To encrypt a password in the domain.xml file. Follow these steps:

  1. From the directory where the domain.xml file resides (domain-dir/config by default), run the following asadmin command:

    asadmin create-password-alias --user admin alias-name

    For example,

    asadmin create-password-alias --user admin jms-password

    A password prompt appears (admin in this case). Refer to the man pages for the create-password-alias, list-password-aliases, delete-password-alias commands for more information.

  2. Remove and replace the password in domain.xml. This is accomplished using the asadmin set command. An example of using the set command for this purpose is as follows:

    asadmin set --user admin server.jms-service.jms-host.

    Note –

    Enclose the alias password in single quotes as shown in the example.

  3. Restart the Enterprise Server for the relevant domain.

Protecting Files with Encoded Passwords

Some files contain encoded passwords that need protecting using file system permissions. These files include the following:

Changing the Master Password

The master password (MP) is an overall shared password. It is never used for authentication and is never transmitted over the network. This password is the central point for overall security; the user can choose to enter it manually when required, or obscure it in a file. It is the most sensitive piece of data in the system. The user can force prompting for the master password by removing this file. When the master password is changed, it is re-saved in the master-password keystore, which is a Java JCEKS type keystore.

To change the master password, follow these steps:

  1. Stop the Enterprise Server for the domain. Use the asadmin change-master-password command, which prompts for the old and new passwords, then re-encrypts all dependent items. For example:

    asadmin change-master-password>
    Please enter the master password>
    Please enter the new master password>
    Please enter the the new master password again>
  2. Restart the Enterprise Server.

    Caution – Caution –

    At this point in time, server instances that are running must not be started and running server instances must not be restarted until the SMP on their corresponding node agent has been changed. If a server instance is restarted before changing its SMP, it will fail to come up.

  3. Stop each node agent and its related servers one at a time. Run the asadmin change-master-password command again, and then restart the node agent and its related servers.

  4. Continue with the next node agent until all node agents have been addressed. In this way, a rolling change is accomplished.

Working with the Master Password and Keystores

The master password is the password for the secure keystore . When a new application server domain is created, a new self-signed certificate is generated and stored in the relevant keystore, which is locked using the master password. If the master password is not the default, the start-domain command prompts you for the master password. Once the correct master password is entered, the domain starts.

When a node agent associated with the domain is created, the node agent synchronizes the data with domain. While doing so, the keystore is also synchronized. Any server instance controlled by this node agent needs to open the keystore. Since the store is essentially identical to the store that was created by the domain creation process, it can only be opened by an identical master password. But the master password itself is never synchronized, meaning it is not transmitted to the node agent during the synchronization, but needs to be available with the node agent locally. This is why creation and/or starting of a node agent prompts you for the master password and you need to enter the same password that you entered while creating/starting the domain. If the master password is changed for a domain, you will have to perform the same step to change it at every node agent that is associated with this domain.

Changing the Admin Password

Encrypting the admin password is discussed in Managing Security of Passwords. Encrypting the admin password is strongly encouraged. If you want to change the admin password before encrypting it, use the change-admin-password command.

Consult the Admin Console online help for instructions on changing the admin password using the Admin Console.

About Authentication and Authorization

Authentication and authorization are central concepts of application server security. The following topics are discussed related to authentication and authorization:

Authenticating Entities

Authentication is the way an entity (a user, an application, or a component) determines that another entity is who it claims to be. An entity uses security credentials to authenticate itself. The credentials may be a user name and password, a digital certificate, or something else.

Typically, authentication means a user logging in to an application with a user name and password; but it might also refer to an EJB providing security credentials when it requests a resource from the server. Usually, servers or applications require clients to authenticate; additionally, clients can require servers to authenticate themselves, too. When authentication is bidirectional, it is called mutual authentication.

When an entity tries to access a protected resource, the Enterprise Server uses the authentication mechanism configured for that resource to determine whether to grant access. For example, a user can enter a user name and password in a Web browser, and if the application verifies those credentials, the user is authenticated. The user is associated with this authenticated security identity for the remainder of the session.

The Enterprise Server supports four types of authentication. An application specifies the type of authentication it uses within its deployment descriptors.

Table 9–1 Enterprise Server Authentication Methods

Authentication Method

Communication Protocol


User Credential Encryption


HTTP (SSL optional) 

Uses the server's built-in pop-up login dialog box. 

None, unless using SSL. 


HTTP (SSL optional) 

Application provides its own custom login and error pages. 

None, unless using SSL. 



Server authenticates the client using a public key certificate. 




Server authenticates the client based on an encrypted response. 

SSL and TLS 

Verifying Single Sign-On

Single sign-on enables multiple applications in one virtual server instance to share the user authentication state. With single sign-on, a user who logs in to one application becomes implicitly logged in to other applications that require the same authentication information.

Single sign-on is based on groups. All Web applications whose deployment descriptor defines the same group and use the same authentication method (BASIC, FORM, CLIENT-CERT) share single sign-on.

Single sign-on is enabled by default for virtual servers defined for the Enterprise Server.

Authorizing Users

Once a user is authenticated, the level of authorization determines what operations can be performed. A user's authorization is based on his role. For example, a human resources application may authorize managers to view personal employee information for all employees, but allow employees to view only their own personal information. For more on roles, see Understanding Users, Groups, Roles, and Realms.

Specifying JACC Providers

JACC (Java Authorization Contract for Containers) is part of the Java EE specification that defines an interface for pluggable authorization providers. This enables the administrator to set up third-party plug-in modules to perform authorization.

By default, the Enterprise Server provides a simple, file-based authorization engine that complies with the JACC specification. It is also possible to specify additional third-party JACC providers.

JACC providers use the Java Authentication and Authorization Service (JAAS) APIs. JAAS enables services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework.

Auditing Authentication and Authorization Decisions

The Enterprise Server can provide an audit trail of all authentication and authorization decisions through audit modules. The Enterprise Server provides a default audit module, as well as the ability to customize the audit modules.

Configuring Message Security

Message Security enables a server to perform end-to-end authentication of web service invocations and responses at the message layer. The Enterprise Server implements message security using message security providers on the SOAP layer. The message security providers provide information such as the type of authentication that is required for the request and response messages. The types of authentication that are supported include the following:

Two message security providers are included with this release. The message security providers can be configured for authentication for the SOAP layer. The providers that can be configured include ClientProvider and ServerProvider.

Support for message layer security is integrated into the Enterprise Server and its client containers in the form of (pluggable) authentication modules. By default, message layer security is disabled on the Enterprise Server.

Message level security can be configured for the entire Enterprise Server or for specific applications or methods. Configuring message security at the Enterprise Server level is discussed in Chapter 10, Configuring Message Security. Configuring message security at the application level is discussed in the Developer's Guide.

Understanding Users, Groups, Roles, and Realms

The Enterprise Server enforces its authentication and authorization policies upon the following entities:

Note –

Users and groups are designated for the entire Enterprise Server, whereas each application defines its own roles. When the application is being packaged and deployed, the application specifies mappings between users/groups and roles, as illustrated in the following figure.

Figure 9–1 Role Mapping

Figure shows how users are assigned to groups, how users
and groups are assigned to roles, and how applications use groups and roles.


A user is an individual (or application program) identity that has been defined in the Enterprise Server. A user can be associated with a group. The Enterprise Server authentication service can govern users in multiple realms.


A Java EE group (or simply group) is a category of users classified by common traits, such as job title or customer profile. For example, users of an e-commerce application might belong to the customer group, but the big spenders would belong to the preferred group. Categorizing users into groups makes it easier to control the access of large numbers of users.


A role defines which applications and what parts of each application users can access and what they can do. In other words, roles determine users' authorization levels.

For example, in a personnel application all employees might have access to phone numbers and email addresses, but only managers would have access to salary information. The application might define at least two roles: employee and manager; only users in the manager role are allowed to view salary information.

A role is different from a user group in that a role defines a function in an application, while a group is a set of users who are related in some way. For example, in the personnel application there might be groups such as full-time, part-time, and on-leave, but users in all these groups would still be in the employee role.

Roles are defined in application deployment descriptors. In contrast, groups are defined for an entire server and realm. The application developer or deployer maps roles to one or more groups for each application in its deployment descriptor.


A realm, also called a security policy domain or security domain, is a scope over which the server defines and enforces a common security policy. In practical terms, a realm is a repository where the server stores user and group information.

The Enterprise Server comes preconfigured with three realms: file (the initial default realm), certificate, and admin-realm. It is possible to also set up ldap, JDBC, solaris, or custom realms. Applications can specify the realm to use in their deployment descriptor. If they do not specify a realm, the Enterprise Server uses its default realm.

In the file realm, the server stores user credentials locally in a file named keyfile. You can use the Admin Console to manage users in the file realm.

In the certificate realm, the server stores user credentials in a certificate database. When using the certificate realm, the server uses certificates with the HTTPS protocol to authenticate Web clients. For more information about certificates, see Introduction to Certificates and SSL.

The admin-realm is also a FileRealm and stores administrator user credentials locally in a file named admin-keyfile. Use the Admin Console to manage users in this realm in the same way you manage users in the file realm.

In the ldap realm the server gets user credentials from a Lightweight Directory Access Protocol (LDAP) server such as the Directory Server. LDAP is a protocol for enabling anyone to locate organizations, individuals, and other resources such as files and devices in a network, whether on the public Internet or on a corporate intranet. Consult your LDAP server documentation for information on managing users and groups in the ldap realm.

In the JDBC realm, the server gets user credentials from a database. The Enterprise Server uses the database information and the enabled JDBC realm option in the configuration file. For digest authentication, a JDBC realm should be created with jdbcDigestRealm as the JAAS context.

In the solaris realm the server gets user credentials from the Solaris operating system. This realm is supported on the Solaris 9 OS and later. Consult your Solaris documentation for information on managing users and groups in the solaris realm.

A custom realm is any other repository of user credentials, such as a relational database or third-party component. For more information, see the Admin Console online help.

ProcedureTo Configure a JDBC Realm for a Web, EJB Application

The Enterprise Server enables you to specify a user's credentials in the JDBC realm instead of in the connection pool. Using the JDBC realm instead of the connection pool prevents other applications from browsing the database tables for the user's credentials. A user's credentials are the user's name and password.

Note –

By default, storage of passwords as clear text is not supported in the JDBC realm. Under normal circumstances, passwords should not be stored as clear text.

  1. Create the database tables in which to store the users' credentials for the realm.

    How to create the database tables depends on the database that you are using.

  2. Add the users' credentials to the database tables that you created in Step 1.

    How to add users' credentials to the database tables depends on the database that you are using.

  3. Create a JDBC realm.

    Use the Admin Console GUI for this purpose. For instructions for creating a JDBC realm, see the online help for the Admin Console GUI.

  4. Specify the realm that you created in Step 3 as the realm for the application.

    To specify the realm, modify the appropriate deployment descriptor for your application:

    • For an enterprise application in an Enterprise Archive (EAR) file, modify the sun-application.xml file.

    • For a web application in a Web Application Archive (WAR) file, modify the web.xml file.

    • For an enterprise bean in an EJB JAR file, modify the sun-ejb-jar.xml file.

    For more information about how to specify a realm, see How to Set a Realm for an Application or Module in Sun GlassFish Enterprise Server v2.1.1 Developer’s Guide.

  5. Assign a security role to users in the realm.

    To assign a security role to a user, add a security-role-mapping element to the deployment descriptor that you modified in Step 4.

    The following example shows a security-role-mapping element that assigns the security role Employee to user Calvin.


Introduction to Certificates and SSL

The following topics are discussed in this section:

About Digital Certificates

Digital certificates (or simply certificates) are electronic files that uniquely identify people and resources on the Internet. Certificates also enable secure, confidential communication between two entities.

There are different kinds of certificates, such as personal certificates, used by individuals, and server certificates, used to establish secure sessions between the server and clients through secure sockets layer (SSL) technology. For more information on SSL, see About Secure Sockets Layer.

Certificates are based on public key cryptography, which uses pairs of digital keys (very long numbers) to encrypt, or encode, information so it can be read only by its intended recipient. The recipient then decrypts (decodes) the information to read it.

A key pair contains a public key and a private key. The owner distributes the public key and makes it available to anyone. But the owner never distributes the private key; it is always kept secret. Because the keys are mathematically related, data encrypted with one key can be decrypted only with the other key in the pair.

A certificate is like a passport: it identifies the holder and provides other important information. Certificates are issued by a trusted third party called a Certification Authority (CA). The CA is analogous to passport office: it validates the certificate holder's identity and signs the certificate so that it cannot be forged or tampered with. Once a CA has signed a certificate, the holder can present it as proof of identity and to establish encrypted, confidential communications.

Most importantly, a certificate binds the owner's public key to the owner's identity. Like a passport binds a photograph to personal information about its holder, a certificate binds a public key to information about its owner.

In addition to the public key, a certificate typically includes information such as:

Digital Certificates are governed by the technical specifications of the X.509 format. To verify the identity of a user in the certificate realm, the authentication service verifies an X.509 certificate, using the common name field of the X.509 certificate as the principal name.

About Certificate Chains

Web browsers are preconfigured with a set of root CA certificates that the browser automatically trusts. Any certificates from elsewhere must come with a certificate chain to verify their validity. A certificate chain is series of certificates issued by successive CA certificates, eventually ending in a root CA certificate.

When a certificate is first generated, it is a self-signed certificate. A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). When the owner sends a certificate signing request (CSR) to a CA, then imports the response, the self-signed certificate is replaced by a chain of certificates. At the bottom of the chain is the certificate (reply) issued by the CA authenticating the subject's public key. The next certificate in the chain is one that authenticates the CA's public key. Usually, this is a self-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain.

In other cases, the CA can return a chain of certificates. In this case, the bottom certificate in the chain is the same (a certificate signed by the CA, authenticating the public key of the key entry), but the second certificate in the chain is a certificate signed by a different CA, authenticating the public key of the CA to which you sent the CSR. Then, the next certificate in the chain is a certificate authenticating the second CA's key, and so on, until a self-signed root certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.

About Secure Sockets Layer

Secure Sockets Layer (SSL) is the most popular standard for securing Internet communications and transactions. Web applications use HTTPS (HTTP over SSL), which uses digital certificates to ensure secure, confidential communications between server and clients. In an SSL connection, both the client and the server encrypt data before sending it, then decrypt it upon receipt.

When a Web browser (client) wants to connect to a secure site, an SSL handshake happens:

After the handshake, the client has verified the identity of the Web site, and only the client and the Web server have a copy of the session key. From this point forward, the client and the server use the session key to encrypt all their communications with each other. Thus, their communications are ensured to be secure.

The newest version of the SSL standard is called TLS (Transport Layer Security). The Enterprise Server supports the Secure Sockets Layer (SSL) 3.0 and the Transport Layer Security (TLS) 1.0 encryption protocols.

To use SSL, the Enterprise Server must have a certificate for each external interface, or IP address, that accepts secure connections. The HTTPS service of most Web servers will not run unless a digital certificate has been installed. Use the procedure described in Generating a Certificate Using the keytool Utility to set up a digital certificate that your Web server can use for SSL.

About Ciphers

A cipher is a cryptographic algorithm used for encryption or decryption. SSL and TLS protocols support a variety of ciphers used to authenticate the server and client to each other, transmit certificates, and establish session keys.

Some ciphers are stronger and more secure than others. Clients and servers can support different cipher suites. Choose ciphers from the SSL3 and TLS protocols. During a secure connection, the client and the server agree to use the strongest cipher they both have enabled for communication, so it is usually sufficient to enable all ciphers.

Using Name-based Virtual Hosts

Using name-based virtual hosts for a secure application can be problematic. This is a design limitation of the SSL protocol itself. The SSL handshake, where the client browser accepts the server certificate, must occur before the HTTP request is accessed. As a result, the request information containing the virtual host name cannot be determined prior to authentication, and it is therefore not possible to assign multiple certificates to a single IP address.

If all virtual hosts on a single IP address need to authenticate against the same certificate, the addition of multiple virtual hosts probably will not interfere with normal SSL operations on the server. Be aware, however, that most browsers will compare the server's domain name against the domain name listed in the certificate, if any (applicable primarily to official, CA-signed certificates). If the domain names do not match, these browsers display a warning. In general, only address-based virtual hosts are commonly used with SSL in a production environment.

About Firewalls

A firewall controls the flow of data between two or more networks, and manages the links between the networks. A firewall can consist of both hardware and software elements. This section describes some common firewall architectures and their configuration. The information here pertains primarily to the Enterprise Server. For details about a specific firewall technology, refer to the documentation from your firewall vendor.

In general, configure the firewalls so that clients can access the necessary TCP/IP ports. For example, if the HTTP listener is operating on port 8080, configure the firewall to allow HTTP requests on port 8080 only. Likewise, if HTTPS requests are setup for port 8181, you must configure the firewalls to allow HTTPS requests on port 8181.

If direct Remote Method Invocations over Internet Inter-ORB Protocol (RMI-IIOP) access from the Internet to EJB modules are required, open the RMI-IIOP listener port as well, but this is strongly discouraged because it creates security risks.

In double firewall architecture, you must configure the outer firewall to allow for HTTP and HTTPS transactions. You must configure the inner firewall to allow the HTTP server plug-in to communicate with the Enterprise Server behind the firewall.

About Certificate Files

Installation of the Enterprise Server generates a digital certificate in JSSE (Java Secure Socket Extension) or NSS (Network Security Services) format suitable for internal testing. By default, the Enterprise Server stores its certificate information in a certificate database in the domain-dir/config directory:

Changing the Location of Certificate Files

The keystore and truststore files provided for development are stored in the domain-dir/config directory.

Use the Admin Console to add or modify the value field for the new location of the certificate files.


where NSS-database-directory is the location of the NSS database.

Using Java Secure Socket Extension (JSSE) Tools

Use keytool to set up and work with JSSE (Java Secure Socket Extension) digital certificates. In the Developer Profile, the Enterprise Server uses the JSSE format on the server side to manage certificates and key stores. In all the profiles, 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

Using the keytool Utility

The following examples demonstrate usage related to certificate handling using JSSE tools:

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

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

  2. 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. The default key password alias is “s1as.”

    A prompt appears that asks for your name, organization, and other information that keytool uses to generate the certificate.

  3. 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
  4. If a certificate signed by a certificate authority is required, see Signing a Digital Certificate Using the keytool Utility.

  5. 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
  6. 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.

  7. Type yes, then press Enter.

    Then keytool displays something like this:

    Certificate was added to keystore
    [Saving cacerts.jks]
  8. Restart the Enterprise Server.

Signing a Digital Certificate Using the keytool Utility

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.

  1. Follow the instructions on the CA's Web site for generating certificate key pairs.

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

  3. In your shell, change to the directory containing the certificate.

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

  5. Restart the Enterprise Server.

Deleting a Certificate Using the keytool Utility

To delete an existing certificate, use the keytool -delete command, for example:

keytool -delete
 -alias keyAlias
 -keystore keystore-name
 -storepass password

Using Network Security Services (NSS) Tools

In the Clusters and Enterprise Profile, 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:

The tools are located in the as-install/lib/ directory. The following environment variables are used to point to the location of the NSS security tools:

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:

Using the certutil Utility

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:

Each of the items in the list below gives an example using NSS and JSSE security tools to create and/or manage certificates.

Importing and Exporting Certificates Using the pk12util Utility

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

Adding and Deleting PKCS11 Modules using modutil

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

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.