Documentation

You are viewing the documentation for the 2.3.5 release in the 2.3.x series of releases. The latest stable release series is 3.0.x.

§Configuring Trust Stores and Key Stores

Trust stores and key stores contain X.509 certificates. Those certificates contain public (or private) keys, and are organized and managed under either a TrustManager or a KeyManager, respectively.

If you need to generate X.509 certificates, please see Certificate Generation for more information.

§Configuring a Trust Manager

A trust manager is used to keep trust anchors: these are root certificates which have been issued by certificate authorities. It determines whether the remote authentication credentials (and thus the connection) should be trusted. As an HTTPS client, the vast majority of requests will use only a trust manager.

If you do not configure it at all, WS uses the default trust manager, which points to the cacerts key store in ${java.home}/lib/security/cacerts. If you configure a trust manager explicitly, it will override the default settings and the cacerts store will not be included.

If you wish to use the default trust store and add another store containing certificates, you can define multiple stores in your trust manager. The CompositeX509TrustManager will try each in order until it finds a match:

ws.ssl {
  trustManager = {
      stores = [
        { path: ${store.directory}/truststore.jks, type: "JKS" }  # Added trust store
        { path: ${java.home}/lib/security/cacerts, password = "changeit" } # Default trust store
      ]
  }
}

NOTE: Trust stores should only contain CA certificates with public keys, usually JKS or PEM. PKCS12 format is supported, but PKCS12 should not contain private keys in a trust store, as noted in the reference guide.

§Configuring a Key Manager

A key manager is used to present keys for a remote host. Key managers are typically only used for client authentication (also known as mutual TLS).

The CompositeX509KeyManager may contain multiple stores in the same manner as the trust manager.

ws.ssl {
    keyManager = {
      stores = [
        {
          type: "pkcs12",
          path: "keystore.p12",
          password: "password1"
        },
      ]
    }
}

NOTE: A key store that holds private keys should use PKCS12 format, as indicated in the reference guide.

§Configuring a Store

A store corresponds to a KeyStore object, which is used for both trust stores and key stores. Stores may have a type – PKCS12, JKS or PEM (aka Base64 encoded DER certificate) – and may have an associated password.

Stores must have either a path or a data attribute. The path attribute must be a file system path.

{ type: "PKCS12", path: "/private/keystore.p12" }

The data attribute must contain a string of PEM encoded certificates.

{
  type: "PEM", data = """
-----BEGIN CERTIFICATE-----
...certificate data
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...certificate data
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...certificate data
-----END CERTIFICATE-----
"""
}

§Debugging

To debug the key manager / trust manager, set the following flags:

ws.ssl.debug = [ "ssl", "trustmanager", "keymanager" ]

§Further Reading

In most cases, you will not need to do extensive configuration once the certificates are installed. If you are having difficulty with configuration, the following blog posts may be useful:

Next: Configuring Protocols