SSL configuration

SSL configuration reference

The following table lists configuration that can be included in zero.config to enable an application to accept requests using HTTPS:

Key stores and trust stores

When you configure an application to accept requests using HTTPS, you must define a key store. The key store must contain the private keys that the application will use when negotiating an incomming HTTPS connection from a client.

Trust stores normally contain the public keys used by the server to negotiate a connection with a client. If a trust store is not defined, then the public keys must also be stored within the defined key store. The defined key store is used as both the source for the private and public encryption keys.

Most application development and testing occurs with privately created and signed encryption keys in which only the key store configuration is necessary. When a certificate is obtained from a commercial certificate authority, they supply both the key store and trust store files.

Key store types

WebSphere sMash uses the Java™ Secure Socket Extension (JSSE) implementation provided by the Java runtime and supports all of the key types of the underlying JSSE implementation. JSSE became a standard extension to J2SE in Java 2 Standard Edition 5.0.

The exact key types supported by the JSSE implementation vary between JDK vendors, however the most common key types are Java Key Store (JKS) and Personal Information Exchange Syntax Standard (PKCS12).

For more information on the key types supported by a specific JDK, see the JSSE documentation of the vendor.

The following JSSE documentation links show documentation provided by some vendors:

• IBM JDK JSSE Provider Reference Guide
• Sun JDK JSSE Provider Reference Guide

Example SSL configuration

The following extract shows an example configuration to allow an application to accept requests over HTTPS:

/config/https/port = 8443
/config/https/sslconfig = {
        "keyStore": "./config/key.jks",
        "keyStorePassword": "<xor>JTotMC8+LCw=",
        "keyStoreType": "JKS"
}

The example configurations specifies a JKS key store file but not a separate trust store file. The password for the key store has been encoded using the XOR encoder command. For more information on the XOR encoder command, see Leveraging XOREncoding.

After adding this configuration to an application, a client can send requests over HTTPS using the following URL:

https://localhost:8443/

Default SSL certificate for testing

The component zero.core.webtools provides a preconfigured test SSL certificate for use during development. To enable the use of the SSL configuration for an application, all that is required is to specify the https port in addition to adding zero.core.webtools as a dependency.

It is important to remember that the test certificate is for testing purposes only and should not be used for deployed applications. Refer to the following section to create a valid certificate once initial testing has completed.

Creating an SSL certificate

There are many tools for creating and managing SSL certificates and keys. Any tools that support the creation of certificates in which the types match the supported types of the underlying JSSE implementation can be used.

Two of the most common SSL key management tools for Java developers are IBM's IKeyman and Sun's keytool, both of which are distributed with their respective Java development kits.

For examples of creating certificates and keys with these tools, see the following articles:

• IKeyman Users Guide
• DeveloperWorks article: Using the Java Secure Socket Extension
• Using keytool to create a key store for use with JSSE