Configuring Keystore, Truststore, and Validator Options

This section describes the keystore, truststore, and validator configuration options.

A certificate is a digitally signed statement from one entity (person, company, etc.) saying that the public key (and some other information) of some other entity has a particular value. When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it. It may be useful to think of a certificate as a "digital driver's license" for an Internet address. It states with which company the site is associated, along with some basic contact information about the site owner or administrator.

The digital certificate is cryptographically signed by its owner and is difficult for anyone else to forge. For sites involved in e-commerce or in any other business transaction in which authentication of identity is important, a certificate can be purchased from a well-known certificate authority (CA) such as VeriSign or Thawte.

One tool that can be used to set up a digital certificate is keytool, a key and certificate management utility that ships with the Java SE SDK. For a better understanding of keytool and public key cryptography, read the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.

Security mechanisms that use certificates require keystore and truststore files for deployment.

For GlassFish, default keystore and truststore files come bundled, however WSIT technology requires X.509 version 3 certificates. GlassFish contains version 1 certificates, therefore, to enable the WSIT applications to run on GlassFish, you will need to follow the instructions in Updating GlassFish Certificates.

For Tomcat, keystore and truststore files do not come bundled with this container, so they must be provided. You can download valid keystore and truststore files for the client and server from https://xwss.dev.java.net/.

The following sections discuss how to specify and configure the keystore, truststore, and validators.

Updating GlassFish Certificates

The WSIT message security mechanisms require the use of v3 certificates. The default GlassFish keystore and truststore do not contain v3 certificates at this time (but should before FCS). (GlassFish instances installed using JDK 1.6 do have a v3 certificate but the certificate lacks a particular extension required for supporting some secure WSIT mechanisms.) In order to use message security mechanisms with GlassFish, it is necessary to download keystore and truststore files that contain v3 certificates and import the appropriate certificates into the default GlassFish stores.

Note: v3 certificates is shorthand for Internet X.509 v3 Public Key Infrastructure Certificate. A copy of the standard for this technology can be viewed at http://www.ietf.org/rfc/rfc2459.txt.

Note: In a future release you will be able to directly use the default GlassFish certificates without this workaround.

Download the zip file that contains the certificates and the Ant scripts (copyv3.zip) by going to this URL: https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=6645.

Unzip this file and change into its directory, copyv3.

Verif that an environment variable named AS_HOME exists and points to the full directory of the location of your GlassFish installation, for example, C:\Sun\GlassFish.

Read the file README.txt.

From the copyv3 directory, execute the Ant command that will copy the keystore and truststore files to the appropriate location, and import the appropriate certificates into the GlassFish keystore and truststore. This ant command is as follows:

ant

Verify that the updates were successful. To do this, follow these steps:

Change to the directory containing the GlassFish keystore and truststore files, <GLASSFISH_HOME>/domains/domain1/config.

Verify that the v3 certificate has been imported into the GlassFish truststore. To do this, run the following keytool command:
<JDK_HOME>/bin/keytool -list -keystore cacerts.jks

When prompted for the password, enter changeit.

Verify that a key entry for xws-security-client, xws-security-server, and wssip are present in the output.

Verify that the v3 certificate has been imported into the GlassFish keystore. To do this, run the following keytool command:
<JDK_HOME>/bin/keytool -list -keystore keystore.jks

When prompted for the password, enter changeit.

Verify that the following entry is present in the output:
xws-security-server

, Jan 10, 2007, keyEntry, Certificate fingerprint (MD5): 8D:A4:E1:0D:09:0E:50:AE:E3:2E:26:99:49:7A:46:26

xws-security-client, Jan 10, 2007, keyEntry, Certificate fingerprint (MD5): CD:23:30:2D:49:72:CF:6E:C8:34:B5:B5:BF:DE:5D:9D

Note: The XWSS keystore(s) are sample keystores containing sample v3 Certificates. These sample keystores can be used for development and testing of security with WSIT technology. Once an application is in production, you should definitely use your own v3 certificates issued by a trusted authority. In order to use WSIT security on GlassFish, you will have to import your trusted stores into GlassFish's keystore and specify those certificates from NetBeans IDE.

Specifying Aliases with the Updated Stores

The configuration of the aliases for all containers (Tomcat, GlassFish) and for all applications (JSR-109-compliant and non-JSR-109-compliant), except for applications that use a Security Token Service (STS) mechanism, is as shown in Table 6-3:

Table 6-3 Keystore and Truststore Aliases
	Keystore Alias	Truststore Alias
Client-Side Configuration	xws-security-client	xws-security-server
Server-Side Configuration	xws-security-server	xws-security-client

The configuration of the aliases for applications that use a Security Token Service (STS) mechanism is as shown in Table 6-4:

The following list provides additional information about the keystore configurations:

Table 6-4 Keystore and Truststore Aliases for STS
	Keystore Alias	Truststore Alias
Client-Side Configuration	xws-security-client	xws-security-server
STS Configuration	xws-security-client	wssip

The truststore alias is not required to be specified for a service, and should be left blank, except under the following circumstances:

When the security mechanism is Mutual Certificates Security mechanism, the truststore alias is required.

When the security mechanism makes use of symmetric binding and the WSS Version is 1.0, the server-side truststore alias is required.

In a general scenario, a service is contacted by clients who are unknown to it and hence there is no way a service can configure the truststore alias correctly. If you want to specify the server-side truststore alias when it is not required, make sure that you use the correct value, which in this case is xws-security-client, and make sure that the client-side keystore alias is also specified as xws-security-client.

When developing a JSR-109-compliant service or application client, the NetBeans keystore and truststore configuration must point to the updated GlassFish certificates because the GlassFish CallbackHandler used in this case assumes the keystores are the default GlassFish keystores.

For Non-JSR-109-compliant applications, applications developed on Tomcat, or stand-alone J2SE clients, the NetBeans keystore and truststore configuration can point to any keystore and truststore files.

Some of the security mechanisms (Transport Security and the STS mechanisms) do not require keystore or truststore configuration, however, the keystore and truststore buttons are still available for configuration. If the stores are configured for a mechanism that does not require stores, they are ignored.

Note: JSR-109-compliant web services and web service clients that run under a GlassFish container (JSR-109 deployment) will not be required to configure Callback Handlers, Keystore and Truststore locations, or Validators within NetBeans IDE running WSIT UI because the container handles the callbacks and validation. You need only make sure your certificates are located in the appropriate directory and/or that you create authorized users for GlassFish using the Admin Console. This does not apply to a J2SE client accessing a JSR-109 web service. The J2SE client would still need to configure username/password and/or keystore/truststore locations.

Keystore Configuration Options

A keystore is a database of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. A key is a piece of information that controls the operation of a cryptographic algorithm. For example, in encryption, a key specifies the particular transformation of plaintext into ciphertext, or vice versa during decryption. Keys are used in digital signatures for authentication.

Right-click the web service and select Edit Web Service Attributes. The Web Service Attributes editor is displayed.

Enable Secure Service.

Click the Keystore button.

In the Keystore Configuration dialog, specify the following options:

Location--Use the Browse button to specify the location and name of the keystore that stores the keys used by the web service. If you are running under GlassFish, this field is hard-coded and may not be changed. The GlassFish keystore file is <GLASSFISH_HOME>/domains/domain1/config/keystore.jks.

Store Password--Specifies the password for the keystore file. If you are running under GlassFish, the password, changeit, is already entered.

Load Aliases--Click the Load Aliases button to populate the Alias field with the aliases contained in the keystore file. The Location and Store Password fields must be specified correctly for this option to work.

Alias--Specifies the key in the specified keystore to be used for authentication. If you are using the downloaded XWSS certificates, select xws-security-server.

Key Password--Specifies the password of the key within the keystore. For this sample, leave this blank. For this field, the default assumes the key password is the same as the store password, so you only need to specify this field when the key password is different.

Note: The Key Password field enables you to specify a password for the keystore used by the application. When specified, this password is stored in a WSIT configuration file in clear text, which is a security risk. Setting the keystore password in the development environment is fine, however, when you go into production, remember to use the container's Callback Handler to obtain the keys from the keystore. This eliminates the need for the keystore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a Callback Handler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.

When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.

When creating non-JSR-109-compliant application, you can specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.

Click OK to close the dialog.

Configure the keystore and truststore options on the client as appropriate for the chosen security mechanism. Instructions for doing so can be found at Configuring Certificates Options.

Truststore Configuration Options

A truststore is a database of trusted entities and their associated X.509 certificate chains authenticating the corresponding public keys.

The truststore contains the Certificate Authority (CA) certificates and the certificate(s) of the other party to which this entity intends to send encrypted (confidential) data. This file must contain the public key certificates of the CA and the client's public key certificate. Any kind of encryption without WS-SecureConversation will generally require that a truststore be configured on the client side. Any kind of signature without WS-SecureConversation will generally require a truststore on the server side.

Note: For this release, we are showing that you place the trusted certificates of other parties in GlassFish's truststore, cacerts.jks. This is not a recommended practice because any certificate you add to the cacerts.jks file effectively means it can be a trusted root for any and all certificate chains, which can be a security problem. In future releases, trusted certificates from other parties will be placed in a certstore and only trusted roots will be placed inside cacerts.jks.

To set the truststore configuration options on the service, perform the following steps:

Right-click the web service and select Edit Web Service Attributes. The Web Service Attributes editor is displayed.

Enable Secure Service.

Click the Truststore button.

On the Truststore Configuration page, specify the following options:

Location--By default, the location and name of the truststore that stores the public key certificates of the CA and the client's public key certificate is already entered. If you are using GlassFish, this file is hard-coded and cannot be changed. The GlassFish truststore file is <GLASSFISH_HOME>/domains/domain1/config/cacerts.jks.

Store Password--Specifies the password for the truststore. If you are using GlassFish, the value of changeit is already entered.

Note: The Store Password field enables you to specify a password for the truststore used by the application. When specified, this password is stored in a WSIT configuration file in clear text, which is a security risk. Setting the truststore password in the development environment is fine, however, when you go into production, remember to use the container's Callback Handler to obtain the keys from the truststore. This eliminates the need for the truststore passwords to be supplied by the users. You can also specify the passwords for keystores and truststores by specifying a CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Key Password or Store Password fields.

When creating JSR-109-compliant application, GlassFish will only use the default CallbackHandlers and Validators, and you cannot override the location of the keystore and truststore files. Any attempt to override the default location will be ignored. You do, however, need to specify the keystore and truststore locations in these dialogs in order to specify the alias.

Click OK to close the dialog.

Configure the keystore and truststore options on the client as appropriate for the chosen security mechanism. Instructions for doing so can be found at Configuring Certificates Options.

Note: Certificates you add to the truststore cacerts.jks are trusted roots. If you have already added a certificate for Verisign as a trusted root, then you do not need to add it again or to add subordinate trust roots, such as certificate for identity x, where x was issued by Verisign. Moreover, adding such subordinates to your truststore is discouraged, as they then become trust roots and any certificates "issued" by them will be accepted as legitimate by the trust manager.

Validator Configuration Options

A validator is an optional set of classes used to check the validity of a token, a certificate, a timestamp, or a username and password.

Applications that run under a GlassFish 9.1 container do not need to configure Callback Handlers and Validators when using the IDE with WSIT enabled. This is because the container handles the callbacks and validation. You only need to make sure that the certificates are available at locations that GlassFish requires and/or create authorized users using the Admin Console (described in Adding Users to GlassFish.

Validators are always optional because there are defaults in the runtime (regardless of the container and regardless of whether the application is a JSR-109 or a non-JSR-109 deployment.) For non-JSR-109 deployment, you only need to specify a validator when you want to override the default validators. For JSR-109 deployments, there is no point in specifying an overriding validator, as these will be overridden back to the defaults by GlassFish, thus the Validators button is not available when the selected web service is a JSR-109-compliant application. Default validators are provided for all the validators except for the Username Validator. A Username Validator need only be specified on the web service side if the security scenario involves accepting and validating UsernameToken(s) sent by a web service client.

To set the validator configuration options for a non-JSR-109-compliant application (such as a J2SE client), perform the following steps:

Right-click the web service and select Edit Web Service Attributes. The Web Service Attributes editor is displayed.

Enable Secure Service.

Click the Validator button.

On the Validator Configuration page, specify the following options, when necessary:

Username Validator--Specifies the validator class to be used to validate username and password on the server side. This option is only used by a web service.

Note: When using the default Username Validator, make sure that the username and password of the client are registered with GlassFish (using Admin Console, described in Adding Users to GlassFish) if using GlassFish, or is included in the tomcat-users.xml file if using Tomcat.