Previous      Contents      Next
Sun Java System Application Server Enterprise Edition 8 2004Q4 XML and Web Services Security Guide

---

Setting Up For Web Services Security

Most of the steps for setting up the Application Server and your applications for using WSS can be accomplished using the Admin Console, the asadmin command-line tool, or by manually editing system files. In general, editing system files is discouraged due to the possibility of making unintended changes that prevent the Application Server from running properly, therefore, where possible, steps for configuring the Application Server using the Admin Console are shown first, with the asadmin tool command shown after. Steps for manually editing system files are shown only when there is no Admin Console or asadmin equivalent.

Follow these steps to setup your system to create, run, and deploy WSS applications.

When using encryption and running on J2SE 1.4.2, configure a JCE provider as described in Configuring a JCE Provider.
If you are using different keystore and/or truststore files from those that ship with the Application Server, point the Application Server to these files as described in Setting Up the Keystore and TrustStore Files in the Application Server.
When using a username token, configure a user database as described in Configuring a User Database for Username Tokens.

Configuring a JCE Provider

The Java Cryptography Extension (JCE) provider included with J2SE 1.4.x does not support RSA encryption. Because most WSS applications use RSA encryption, you must download and install a JCE provider that does support RSA encryption in order to run WSS applications that use encryption.

Note: RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.

Follow these steps to add a JCE provider statically as part of your JDK environment:

Download and install a JCE provider JAR (Java ARchive) file. The following URL provides a list of JCE providers that support RSA encryption:

http://java.sun.com/products/jce/jce14_providers.html

Copy the JCE provider JAR file to <JAVA_HOME>/jre/lib/ext/.
Stop the Application Server. If the Application Server is not stopped and then restarted later in this process, the JCE provider will not be recognized by the Application Server.
Edit the <JAVA_HOME>/jre/lib/security/java.security properties file in any text editor. Add the JCE provider you’ve just downloaded to this file. The java.security file contains detailed instructions for adding this provider. Basically, you need to add a line of the following format in a location with similar properties:

security.provider.<n>=<provider class name>

In this example, <n> is the order of preference to be used by the Application Server when evaluating security providers. Set <n> to 2 for the JCE provider you’ve just added.

For example, if you’ve downloaded The Legion of the Bouncy Castle JCE provider, you would add this line.

security.provider.2=org.bouncycastle.jce.provider.
BouncyCastleProvider

Make sure that the Sun security provider remains at the highest preference, with a value of 1.

security.provider.1=sun.security.provider.Sun

Adjust the levels of the other security providers downward so that there is only one security provider at each level.

The following is an example of a java.security file that provides the necessary JCE provider and keeps the existing providers in the correct locations.

security.provider.1=sun.security.provider.Sun
security.provider.2=org.bouncycastle.jce.provider.
BouncyCastleProvider
security.provider.3=com.sun.net.ssl.internal.ssl.Provider
security.provider.4=com.sun.rsajca.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider

Save and close the file.
Restart the Application Server.

Setting Up the Keystore and TrustStore Files in the Application Server

Installation of the Application Server generates a digital certificate suitable for internal testing. By default, the Application Server stores its certificate information in two files in the install_dir/domains/domain_name/config directory:

Keystore file, by default named keystore.jks, contains the Application Server’s digital certificate, including its private key. The keystore file is protected with a password, initially changeit. You can change the password using keytool.

Each keystore entry has a unique alias. After installation, the Application Server keystore has a single entry with alias s1as.

Trust-store file, by default named cacerts.jks, contains the Application Server’s trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate’s owner. Trusted certificates generally include those of certification authorities (CAs).

By default, the Application Server is configured with a keystore and truststore that will work with the example applications and for development purposes. For production purposes, you may wish to change the certificate alias, add other certificates to the truststore, or change the name and/or location of the keystore and trust-store files.

In the Enterprise Edition, you can use Network Security Services (NSS) to manage keystore and truststore files. For more information on NSS, go to http://www.mozilla.org/projects/security/pki/nss/. The tools for managing security include the following:

certutil, a command-line utility for managing certificates and key databases.
pk12util, a command-line utility used to import and export keys and certificates between the certificate/key databases and files in PKCS12 format.

If you use NSS for managing keystore and truststore files, you would modify the property com.sun.appserv.nss.db in place of the javax.net.ssl.keyStore and javax.net.ssl.trustStore properties mentioned in the steps below. For more information on using certutil, pk12util, and other NSS security tools, see NSS Security Tools at http://www.mozilla.org/projects/security/pki/nss/.

Steps for changing the certificate alias and adding certificates to the truststore are discussed in the Security chapter of the J2EE 1.4 Tutorial. Steps for changing the location of the keystore and truststore files are described here.

To change the location of the keystore and truststore files, follow these steps.

Start the Application Server.
Start the Admin Console by entering the following URL in a browser window:

https://<your_host>.<your_domain>:4848(The <your_host>.<your_domain> part of the URL can be substituted with localhost if you are running the Admin Console from the machine on which the Application Server is installed.)

In the Admin Console tree, expand Configurations.
Expand the server-config (Admin Config) node.
Select the JVM Settings node.
Click the JVM Options tab.
On the JVM Options page, add or modify the following values in the Value field to reflect the new location of the certificate files:

-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/path/ks_name
-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/path/ts_name

where ks_name is the keystore file name and ts_name is the trust-store file name.

Click Save.

Note: There is a convention in SSL that keystore and key password(s) should be the same. But for the sake of completeness, the Application Server’s security environment looks for the system property com.sun.xml.wss.KeyPassword. If this property is explicitly set, the Application Server assumes that this property contains the password for all the keys of the keystore.

In the default certificates, the alias is s1as. If you are using certificates other than the default certificates, edit the following files to change the certificate alias:
In a text editor, open the file install_dir/lib/appclient/wss-client-config.xml.
Edit the following lines, changing s1as to the value of your certificate alias:

    <xwss:Encrypt receiverCertificateAlias="s1as"/>
    <xwss:Sign senderCertificateAlias="s1as"/>

Save and close the file.
In a text editor, open the file install_dir/domains/domain_name/config/wss-server-config.xml.
Edit the following lines, changing s1as to the value of your certificate alias:

    <xwss:Encrypt receiverCertificateAlias="s1as"/>
    <xwss:Sign senderCertificateAlias="s1as"/>

Save and close the file.
Restart the Application Server if Restart Required displays in the console or if you changed the certificate alias.

Configuring a User Database for Username Tokens

By default, the Application Server is configured with a User Database that can be used for Username Tokens. This database is sufficient for running the example applications and for development. In the production environment, you may wish to create another user database. If you want to configure a new user database for username tokens, follow the steps in this section. You can also use NSS to manage users. Refer to Managing Users with Network Security Services (NSS) for more information on configuring users using NSS.

Set up a username database if you are doing password-based authentication. You may be using such authentication in the servlet or EJB containers (independent of your use for message layer security), and the same database could, in many cases, sustain both forms of use. In the case of message layer security, you only need to configure such a database when you are enforcing policies where the authenticate source is sender.

In order to run applications that demonstrate username/password-based authentication, you must configure the username database on the server. In a file-type security realm, the server maintains all user, group, and password information in a text file. The first step to create the simple user database is to create a new file realm specifically for WSS applications, then add users to the realm. For more information on realms, refer to the Configuring Security chapter of the Administration Guide.

Start the Application Server.
Start the Admin Console by entering the following URL in a browser window:

https://<your_host>.<your_domain>:4848(The <your_host>.<your_domain> part of the URL can be substituted with localhost if you are running the Admin Console from the machine on which the Application Server is installed.)

In the Admin Console tree component, expand the Configurations node.
Select the instance you want to configure:
To configure a particular instance, select the instance’s config node. For example, the default instance, server, select the server-config node.
To configure the default settings for all instances, select the default-config node.
Expand the Security node.
Select the Realms node.
On the Realms page, click New.

The Create Realm page is displayed.

Enter a name for the realm in the Name field, for example, wss-realm.
Specify the class name for the realm you want to create. To create a file realm, enter com.sun.enterprise.security.auth.realm.file.FileRealm.
Select Add Property to specify the name and location of the text file that will hold the user information. Add the properties specified in the following table:

Table 1-3  Required properties for file realms

Property name	Description	Example Value
file	Full path and name to the file to which user name and password data should be written.	install_dir/domains/domain-name/ config/wss-keyfile
jaas-context	Type of login module to use for this realm.	fileRealm is the only valid value

The next step in configuring a user database is entering the user names, passwords, and the groups to which the users belong. For more discussion on users, realms, and groups, and how these entities match up with roles defined in applications, read the Security chapter of the J2EE 1.4 Tutorial at the following URL:

http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html

To add users to the database, follow these steps:

Click the Manage Users button from the Edit Realm page.
Click New to add a new user to the wss-realm.
Enter the following information on the File Users page:
User ID (required) - The name of the user.
Password (required) - The user’s password.
Confirm Password (required) - The user’s password again, for verification.
Group List (optional) - a comma-separated list of the groups to which the user belongs. These groups do not need to be defined elsewhere.
Click OK to add this user to the list of users in the wss-realm. Click Cancel to quit without saving.

Managing Users with Network Security Services (NSS)

In the Enterprise Edition, you can manage users using the Admin Console or you can manage users using NSS tools. Network Security Services (NSS) is a set of libraries designed to support cross-platform development of security-enabled client and server applications. Applications built with NSS can support SSL v2 and v3, TLS, PKCS #5, PKCS #7, PKCS #11, PKCS #12, S/MIME, X.509 v3 certificates, and other security standards. For detailed information, link to the following URLs:

Network Security Services (NSS) at http://www.mozilla.org/projects/security/pki/nss/
NSS Security Tools at http://www.mozilla.org/projects/security/pki/nss/tools/
Overview of NSS at http://www.mozilla.org/projects/security/pki/nss/overview.html

Previous      Contents      Next

---

Copyright 2004 Sun Microsystems, Inc. All rights reserved.