SSL configuration

In addition to the HTTP protocol, a Project Zero application can also be enabled for communicating with clients over HTTPS. This function is enabled by adding a [/config/https] section to your zero.config file. The following sections of this article provide information about SSL configuration:

SSL configuration reference

The following table lists the parameters and values required to enable HTTPS:

Key stores and trust stores

When configuring HTTPS, a key store must be defined. The key store must contain the private keys the Project Zero application will use when negotiating a new HTTPS connection with 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 keyStore values are necessary. When a certificate is obtained from a commercial certificate authority, they supply both the key store and trust store files.

Key store types

Project Zero uses the JSSE (Java Secure Socket Extension) implementation provided by the runtime JDK. Therefore, Project Zero 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 JKS (Java Key Store) and PKCS12 (Personal Information Exchange Syntax Standard).

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 an example is from a zero.config file that is ocated in module myApp, in which HTTPS has been enabled.

/config/https/port = 8443
/config/https/keyStore = "config/myKeyStore.p12"
/config/https/keyStorePassword = "<xor>JTotMA=="
/config/https/keyStoreType = "PKCS12" 

In this example, there is no trust store and only a key store is used. The password for the key store has been encoded using the XOR encoder command. For more information on the XOR encoder command, see the Leveraging XOREncoding article.

After adding this configuration to an application, the application can be accessed over HTTPS using the following URL:

https://localhost:8443/

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 JDK 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 JDKs.

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