The WSIT Tutorial

Configuring Keystores and Truststores

This section describes configuring keystores and truststores. Security mechanisms that use certificates require keystore and truststore files for deployment.

For GlassFish, default keystore and truststore files come bundled. However, WSIT security mechanisms for message security require 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 To Update 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/.

This section covers the following topics:

To Update 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 –

The XWSS keystores 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.

To update the GlassFish certificates, follow these steps.

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[amp ]expandFolder=6645[amp ]folderID=6645

Unzip this file and change into its directory, copyv3.

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:

as-install/lib/ant/bin/ant

The command window will echo back the certificates that are being added to the keystore and truststore files, and should look something like this:

[echo] WARNING: currently we add non-CA certs to GF truststore, this 
will not be required in later releases when WSIT starts supporting CertStore(s)
     [java] Added Key Entry  :xws-security-server
     [java] Added Key Entry  :xws-security-client
     [java] Added Trusted Entry  :xwss-certificate-authority
     [java] Added Key Entry  :wssip
     [java] Added Trusted Entry  :xws-security-client
     [java] Added Trusted Entry  :xws-security-server
     [java] Added Trusted Entry  :wssip
     [echo] Adding JVM Option for https outbound alias, this will take at least 
One Minute.
...

To verify that the updates were successful, follow these steps:

Change to the directory containing the GlassFish keystore and truststore files, as-install/domains/domain1/config.

Verify that the v3 certificate has been imported into the GlassFish truststore. To do this, run the following keytool command (all on one line):
java-home/bin/keytool -list -keystore cacerts.jks -alias wssip -storepass changeit
If the certificates are successfully updated, your response will look something like this:
wssip, Aug 20, 2007, trustedCertEntry, Certificate fingerprint (MD5): 1A:0E:E9:69:7D:D0:80:AD:5C:85:47:91:EB:0D:11:B1
If the certificates were not successfully update, your response will look something like this:
keytool error: java.lang.Exception: Alias <wssip> does not exist

Verify that the v3 certificate has been imported into the GlassFish keystore. To do this, run the following keytool commands:

java-home/bin/keytool -list -keystore keystore.jks 
-alias xws-security-server -storepass changeit 
java-home/bin/keytool -list -keystore keystore.jks 
-alias xws-security-client -storepass changeit

If the certificates were successfully updated, your response should look something like this:

xws-security-server, Aug 20, 2007, PrivateKeyEntry,
Certificate fingerprint (MD5): E4:E3:A9:02:3C:B0:36:0C:C1:48:6E:0E:3E:5C:5E:84

If your certificates were not successfully updated, your response will look more like this:

keytool error: java.lang.Exception: Alias <xws-security-server> does not exist

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 7–3.

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

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

Configuring the Keystore and Truststore

NetBeans IDE already knows the location of the default keystore file and its password, but you need to specify which alias is to be used. The following sections discuss configuring the keystore on the service and on the client.

To Configure the Keystore on a Service

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.

To configure a keystore on a service, perform the following steps.

Check the table in Summary of Service-Side Configuration Requirements to see if a keystore needs to be configured for the selected security mechanism. If so, continue.

Right-click the web service and select Edit Web Service Attributes.

The Web Service Attributes editor is displayed.

Enable Secure Service, then select a security mechanism.

Check the table in Summary of Service-Side Configuration Requirements to see what keystore configuration, if any, is required for that mechanism.

Click the Keystore button. The dialog shown in Figure 7–5 appears.

Figure 7–5 Keystore Configuration Dialog

Depending on what is required for the selected mechanism, you may specify the following information in the Keystore Configuration dialog:
- Keystore Password: Specifies the password for the keystore file. If you are running under GlassFish, GlassFish’s password is already entered. If you have changed the keystore’s password from the default, you must specify the correct value in this field.
- 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 alias of the certificate in the specified keystore to be used for authentication. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias to choose for the selected security mechanism.
- 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.

To Configure the Truststore on a Service

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 certificates 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, place the trusted certificates of other parties in GlassFish’s truststore, cacerts.jks. This is not normally 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 a service, perform the following steps.

Check the table in Summary of Service-Side Configuration Requirements to see if a truststore is required for the selected security mechanism. If so, continue.

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. The GlassFish truststore file is as-install/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. If you have changed the value of the truststore password, you must type the new value in this field.
  
  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.
- Load Aliases: Click the Load Aliases button to populate the Alias field with the aliases contained in the truststore file. The Location and Store Password fields must be specified correctly for this option to work.
- Alias: Specifies the peer alias of the certificate in the truststore that is to be used when the client needs to send encrypted data. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism. A truststore contains trusted other-party certificates and certificates of Certificate Authorities (CA). A peer alias is the alias of the other party (peer) that the sending party needs to use to encrypt the request.

Click OK to close the dialog.

To Configure the Keystore and Truststore on a Client

On the client side, a keystore and truststore file must be configured for some of the security mechanisms. Refer to the table in Summary of Client-Side Configuration Requirements for information on which mechanisms require the configuration of keystores and truststores.

If the mechanism configured for the service requires the configuration of keystores and truststores, follow these steps.

Check the table in Summary of Client-Side Configuration Requirements to see if a keystore needs to be configured for the client for the selected security mechanism. If so, continue.

In the Projects window, expand the node for the web service client.

Expand the Web Service References node.

Right-click the node for the web service reference for which you want to configure security options.

Select Edit Web Service Attributes.

When the Web Service References Attributes Editor is opened, select the WSIT Configuration tab to display the WSIT options.

Expand the Certificates section to specify the keystore and truststore information if required by the service.

Depending on what is required for the selected mechanism, you may specify the following information in the Certificates section:
- Keystore Location: The directory and file name containing the certificate key to be used to authenticate the client. By default, the location is already set to the default GlassFish keystore, as-install/domains/domain1/config/keystore.jks.
- Keystore Password: The password for the keystore used by the client. By default, the password for the GlassFish keystore is already entered. This password is changeit.
  
  Note –
  When specified, this password is stored in a WSIT configuration file in clear text. Setting the keystore password in the development environment is fine, however, when you go into production, remember to use the container’s default CallbackHandler 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 CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Keystore Password, Truststore Password, or Key Password fields.
- Load Aliases: Click this button to populate the Alias list with all of the certificates available in the selected keystore. This option will only work if the keystore location and password are correct.
- Keystore Alias: Select the alias in the keystore. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism.
- Key Password: If the client key has been password-protected, type the password for this key. The GlassFish certificate key password is changeit.
- Truststore Location: The directory and file name of the client truststore containing the certificate of the server. By default, this field points to the default GlassFish truststore, as-install/domains/domain1/config/cacerts.jks.
- Truststore Password: The password for the truststore used by the client. By default, the password for the GlassFish truststore is already specified. The password is changeit.
  
  Note –
  When specified, this password is stored in a WSIT configuration file in clear text. Setting the truststore password in the development environment is fine; however, when you go into production, remember to use the container’s default CallbackHandler 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 CallbackHandler class that implements the javax.security.auth.callback.CallbackHandler interface in the Keystore Password, Truststore Password, or Key Password fields.
- Load Aliases: Click this button to populate the Alias list with all of the certificates available in the selected keystore. This option will only work if the truststore location and password are correct.
- Truststore Alias: Select the alias of the server certificate and private key in the client truststore. Refer to the table in Specifying Aliases with the Updated Stores to determine which alias is appropriate for the selected security mechanism.
When the certificates are configured as suggested for some of the examples in this chapter, the dialog will appear as shown in Figure 7–6.

Figure 7–6 Client-side Certificate Configuration Dialog

Click OK to close the dialog.

Configuring Validators

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.

To Set Validator Configuration Options

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.
- Timestamp Validator: Specifies the validator class to be used to check the token timestamp to determine whether the token has expired or is still valid.
- Certificate Validator: Specifies the validator class to be used to validate the certificate supplied by the client or the web service.
- SAML Validator: Specifies the validator class to be used to validate SAML token supplied by the client or the web service.

Click OK to close the dialog.