ssl-utils

Is a library of utilities to assist with developing security functionality in Java applications.

In the diagram below (Source: Oracle) you can see how a secure connection is created in general and which component's are involved.

ssl-utils provides some builder to create key materials easily and quickly. There are also helpers to access the key materials and to control the runtime behavior. The library is written in Java and requires version 6 or higher.

KeyStoreBuilder

The KeyStoreBuilder is a builder-pattern style factory to create a KeyStore. The KeyStore represents a storage facility for cryptographic keys and certificates (key materials). To create a KeyStore, the type and the provider must be configured.

The following example sets up a PKCS #12 key store, while the private keys are provided by a file ...

KeyStore keyStore = KeyStoreBuilder.create()
		.setType(KeyStoreType.PKCS12)
		.setPath("/path/to/cert.p12")  // have to be absolute
		.build();

It is also possible to using a custom PKCS #11 provider. Note: The provider must already be registered.

KeyStore keyStore = KeyStoreBuilder.create()
		.setType(KeyStoreType.PKCS11)
		.setProvider("CustomProvider") // name of the security provider
		.build();

An other option is to access a PKCS #11 key store via a library (e.g. smart card reader).

KeyStore keyStore = KeyStoreBuilder.create()
		.setType(KeyStoreType.PKCS11)
		.setLibraryPath("/path/to/pkcs11.lib") // have to be absolute
		.setPassword("123456") // optional, password or pin to access the store
		.build();

SSLContextBuilder

The SSLContextBuilder is a builder-pattern style factory to create a SSLContext.

To create the default SSL Context, nothing has to be configured. In this case the default key- and trust-store of the JVM is used. The default SSL protocol is TLS v1.2 (JVM v7 or higher) or TLS v1.0 (JVM v6 or lower).

SSLContext sslContext = SSLContextBuilder.create()
		.build();

you can also build a SSLContext with existing key- and trust-store ...

KeyStore trustStore = ...
KeyStore keyStore = ...
SSLContext sslContext = SSLContextBuilder.create()
		.setTrustStore(trustStore)
		.setKeyStore(keyStore)
		.setKeyStorePassword("changeit")
		.build();

or you can also register a KeyManagerStrategy to specify an alias which will be selected when there are more than one in the key store ..

SSLContext sslContext = SSLContextBuilder.create()
		.setKeyManagerStrategy(() -> "MyAlias")
		.build();

or use the KeyStoreHelper to find certificates supporting a key usage.

KeyStore keyStore = ...
SSLContext sslContext = SSLContextBuilder.create()
		.setKeyStore(keyStore)
		.setKeyManagerStrategy(() -> KeyStoreHelper.getAliases(keyStore, DIGITAL_SIGNATURE)[0])
		.build();

To control the trustworthiness of peers - independent of the trust manager of the actual context - the TrustManagerStrategy must be configured.

The following example overrule the result of the trust manager validation (trust any certificate/peer) ...

SSLContext sslContext = SSLContextBuilder.create()
		.setTrustManagerStrategy((chain, authType) -> true)
		.build();

The next example uses the CertificateHelper to find a certificate where the issuer is MyIssure...

SSLContext sslContext = SSLContextBuilder.create()
		.setTrustManagerStrategy((chain, authType) -> CertificateHelper.getIssuers(chain).contains("CN=MyIssuer"))
		.build();