[Index]

web:ssl

Provides TLS Configuration for Client and Servers. Some properties apply only to servers, some only to clients. All passwords be obfuscated, see the Jetty documentation on how to do this.

Debugging

-Djavax.net.debug=ssl
-Djavax.net.debug=all
This Link will explain what's going on.

Common Errors

PKIX path building failed: unable to find valid certification path to requested target
There no certificate in the Trust Store matching the server.
org.eclipse.jetty.http.HttpParser$IllegalCharacterException: 400: Illegal character CNTL=0x15
One side is using TLS, the other isn't.
javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching some-domain found
The certificate CN does not match the host name.
java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must be non-empty
java.security.UnrecoverableKeyException: Get Key failed: null
I got this when the Key Store password was missing.
java.io.IOException: keystore password was incorrect
This one is obvious.

Property Summary

clientAuth Should the server perform client authentication.
hostnameVerifier Something that can verify if a hostname is acceptable when the host doesn't match the certificate CN.
keyManagerPassword The key password.
keyStorePassword The key store password.
keyStorePath The path of the store that contains the private key and signed cert.
keyStoreType The key store type.
port The port of the server ssl connector.
trustAll Should the client trust all certificates.
trustStorePassword The trust store password.
trustStorePath The path of the store that contains trusted public certs.
trustStoreType The trust store type.

Example Summary

Example 1 Client Accepts any certificate.
Example 2 Host Name Verification.
Example 3 One Way Trust.
Example 4 Two Way Trust.

Property Detail

clientAuth
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo, defaults to NONE, and only applicable to a server.

Should the server perform client authentication. NONE/WANT/NEED.

hostnameVerifier
Configured ByELEMENT
AccessREAD_WRITE
RequiredNo, and only applicable to a client.

Something that can verify if a hostname is acceptable when the host doesn't match the certificate CN. In Jetty, to get this work, Client Endpoint Identification Algorithm is set to null. This generates this warning: No Client EndPointIdentificationAlgorithm configured for Client

keyManagerPassword
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

The key password. Only applicable to JKS stores.

keyStorePassword
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredYes.

The key store password.

keyStorePath
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredYes for Server, No for client unless doing Client Auth.

The path of the store that contains the private key and signed cert.

keyStoreType
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo, defaults depending on JDK version.

The key store type. Either JKS or PKCS12.

port
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo, can be set from the Server configuration.

The port of the server ssl connector.

trustAll
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo, defaults to false, and only applicable to a client.

Should the client trust all certificates.

trustStorePassword
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredYes, if you have a trust store.

The trust store password.

trustStorePath
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo, unless you wish to verify your peer.

The path of the store that contains trusted public certs.

trustStoreType
Configured ByATTRIBUTE
AccessREAD_WRITE
RequiredNo.

The trust store type. Either JKS or PKCS12.

Examples

Example 1

Client Accepts any certificate. 

<oddjob id="oddjob">
    <job>
        <sequential>
            <jobs>
                <properties>
                    <values>
                        <value key="work.dir" value="${oddjob.dir}"/>
                        <file file="${work.dir}/stores" key="ssltest.stores.dir"/>
                    </values>
                </properties>
                <sequential name="Setup Keys and Certs">
                    <jobs>
                        <delete force="true" name="Delete Any Previous Store Directory">
                            <files>
                                <file file="${ssltest.stores.dir}"/>
                            </files>
                        </delete>
                        <mkdir dir="${ssltest.stores.dir}" name="Create Store Directory"/>
                        <exec dir="${ssltest.stores.dir}" name="Create Server Keystore">keytool -v -genkey -keyalg RSA -keysize 2048 -validity 360 -alias serverkey -keystore server_keystore.p12 -storetype pkcs12 -storepass storepwd -dname "CN=anything"</exec>
                    </jobs>
                </sequential>
                <web:server id="server" xmlns:web="oddjob:web">
                    <handler>
                        <web:resource base="${oddjob.dir}">
                            <welcomeFiles>
                                <list>
                                    <values>
                                        <value value="index.html"/>
                                    </values>
                                </list>
                            </welcomeFiles>
                        </web:resource>
                    </handler>
                    <modifiers>
                        <web:ssl keyStorePassword="OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4" keyStorePath="${ssltest.stores.dir}/server_keystore.p12"/>
                    </modifiers>
                </web:server>
                <web:client id="client" url="https://localhost:${server.port}" xmlns:web="oddjob:web">
                    <ssl>
                        <web:ssl trustAll="true"/>
                    </ssl>
                </web:client>
                <echo id="echo">${client.content}></echo>
                <check eq="&lt;h1>Hello World&lt;/h1>" value="#{client.get('content').trim()}"/>
                <stop job="${server}"/>
            </jobs>
        </sequential>
    </job>
</oddjob>

Example 2

Host Name Verification. The client accepts the host even if it doesn't match the certificate. 

<oddjob id="oddjob">
    <job>
        <sequential>
            <jobs>
                <properties>
                    <values>
                        <value key="work.dir" value="${oddjob.dir}"/>
                        <file file="${work.dir}/stores" key="ssltest.stores.dir"/>
                    </values>
                </properties>
                <sequential name="Setup Keys and Certs">
                    <jobs>
                        <delete force="true" name="Delete Any Previous Store Directory">
                            <files>
                                <file file="${ssltest.stores.dir}"/>
                            </files>
                        </delete>
                        <mkdir dir="${ssltest.stores.dir}" name="Create Store Directory"/>
                        <exec dir="${ssltest.stores.dir}" name="Create Server Keystore">keytool -v -genkey -keyalg RSA -keysize 2048 -validity 360 -alias serverkey -keystore server_keystore.p12 -storetype pkcs12 -storepass srvstorepwd -dname "CN=anything"</exec>
                        <exec dir="${ssltest.stores.dir}" name="Export Server Certificate">
                            <stdout>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdout>keytool -export -rfc -alias serverkey -keystore server_keystore.p12 -storepass srvstorepwd</exec>
                        <exec dir="${ssltest.stores.dir}" name="Import Server Certificate into Client Trustore">
                            <stdin>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdin>keytool -v -import -keystore client_trustore.p12 -storepass clitrustpwd -alias serverkey -noprompt</exec>
                    </jobs>
                </sequential>
                <web:server id="server" xmlns:web="oddjob:web">
                    <handler>
                        <web:resource base="${oddjob.dir}">
                            <welcomeFiles>
                                <list>
                                    <values>
                                        <value value="index.html"/>
                                    </values>
                                </list>
                            </welcomeFiles>
                        </web:resource>
                    </handler>
                    <modifiers>
                        <web:ssl keyStorePassword="srvstorepwd" keyStorePath="${ssltest.stores.dir}/server_keystore.p12"/>
                    </modifiers>
                </web:server>
                <web:client id="client" url="https://localhost:${server.port}" xmlns:web="oddjob:web">
                    <ssl>
                        <web:ssl trustStorePassword="clitrustpwd" trustStorePath="${ssltest.stores.dir}/client_trustore.p12">
                            <hostnameVerifier>
                                <web:hostname-verifier hostname=".*" regex="true"/>
                            </hostnameVerifier>
                        </web:ssl>
                    </ssl>
                </web:client>
                <echo id="echo">${client.content}></echo>
                <check eq="&lt;h1>Hello World&lt;/h1>" value="#{client.get('content').trim()}"/>
                <stop job="${server}"/>
            </jobs>
        </sequential>
    </job>
</oddjob>

Example 3

One Way Trust. The client verifies who the server is but the server doesn't care who the client is. 

<oddjob id="oddjob">
    <job>
        <sequential>
            <jobs>
                <properties>
                    <values>
                        <value key="work.dir" value="${oddjob.dir}"/>
                        <value key="ssltest.hostname" value="#{java.net.InetAddress.getLocalHost().getHostName()}"/>
                        <file file="${work.dir}/stores" key="ssltest.stores.dir"/>
                    </values>
                </properties>
                <sequential name="Setup Keys and Certs">
                    <jobs>
                        <delete force="true" name="Delete Any Previous Store Directory">
                            <files>
                                <file file="${ssltest.stores.dir}"/>
                            </files>
                        </delete>
                        <mkdir dir="${ssltest.stores.dir}" name="Create Store Directory"/>
                        <exec dir="${ssltest.stores.dir}" name="Create Server Keystore">keytool -v -genkey -keyalg RSA -keysize 2048 -validity 360 -alias serverkey -keystore server_keystore.p12 -storetype pkcs12 -storepass srvstorepwd -dname "CN=${ssltest.hostname}"</exec>
                        <exec dir="${ssltest.stores.dir}" name="Export Server Certificate">
                            <stdout>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdout>keytool -export -rfc -alias serverkey -keystore server_keystore.p12 -storepass srvstorepwd</exec>
                        <exec dir="${ssltest.stores.dir}" name="Import Server Certificate into Client Trustore">
                            <stdin>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdin>keytool -v -import -storetype pkcs12 -keystore client_trustore.p12 -storepass clitrustpwd -alias serverkey -noprompt</exec>
                    </jobs>
                </sequential>
                <web:server id="server" xmlns:web="oddjob:web">
                    <handler>
                        <web:resource base="${oddjob.dir}">
                            <welcomeFiles>
                                <list>
                                    <values>
                                        <value value="index.html"/>
                                    </values>
                                </list>
                            </welcomeFiles>
                        </web:resource>
                    </handler>
                    <modifiers>
                        <web:ssl keyStorePassword="srvstorepwd" keyStorePath="${ssltest.stores.dir}/server_keystore.p12" keyStoreType="PKCS12"/>
                    </modifiers>
                </web:server>
                <web:client id="client" url="https://${ssltest.hostname}:${server.port}" xmlns:web="oddjob:web">
                    <ssl>
                        <web:ssl trustStorePassword="clitrustpwd" trustStorePath="${ssltest.stores.dir}/client_trustore.p12" trustStoreType="PKCS12"/>
                    </ssl>
                </web:client>
                <echo id="echo">${client.content}></echo>
                <check eq="&lt;h1>Hello World&lt;/h1>" value="#{client.get('content').trim()}"/>
                <stop job="${server}"/>
            </jobs>
        </sequential>
    </job>
</oddjob>

Example 4

Two Way Trust. The client verifies who the server is and the server verifies who the client is. 

<oddjob id="oddjob">
    <job>
        <sequential>
            <jobs>
                <properties>
                    <values>
                        <value key="work.dir" value="${oddjob.dir}"/>
                        <value key="ssltest.hostname" value="#{java.net.InetAddress.getLocalHost().getHostName()}"/>
                        <file file="${work.dir}/stores" key="ssltest.stores.dir"/>
                    </values>
                </properties>
                <sequential name="Setup Keys and Certs">
                    <jobs>
                        <delete force="true" name="Delete Any Previous Store Directory">
                            <files>
                                <file file="${ssltest.stores.dir}"/>
                            </files>
                        </delete>
                        <mkdir dir="${ssltest.stores.dir}" name="Create Store Directory"/>
                        <exec dir="${ssltest.stores.dir}" name="Create Server Keystore">keytool -v -genkey -keyalg RSA -keysize 2048 -validity 360 -alias serverkey -keystore server_keystore.p12 -storetype pkcs12 -storepass srvstorepwd -dname "CN=${ssltest.hostname}"</exec>
                        <exec dir="${ssltest.stores.dir}" name="Export Server Certificate">
                            <stdout>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdout>keytool -export -rfc -alias serverkey -keystore server_keystore.p12 -storepass srvstorepwd</exec>
                        <exec dir="${ssltest.stores.dir}" name="Import Server Certificate into Client Trustore">
                            <stdin>
                                <file file="${ssltest.stores.dir}/server_cert.pem"/>
                            </stdin>keytool -v -import -storetype pkcs12 -keystore client_trustore.p12 -storepass clitrustpwd -alias serverkey -noprompt</exec>
                        <exec dir="${ssltest.stores.dir}" name="Create Client Keystore">keytool -v -genkey -keyalg RSA -keysize 2048 -validity 360 -alias clientkey -keystore client_keystore.p12 -storetype pkcs12 -storepass clistorepwd -dname "CN=anything"</exec>
                        <exec dir="${ssltest.stores.dir}" name="Export Client Certificate">
                            <stdout>
                                <file file="${ssltest.stores.dir}/client_cert.pem"/>
                            </stdout>keytool -export -rfc -alias clientkey -keystore client_keystore.p12 -storepass clistorepwd</exec>
                        <exec dir="${ssltest.stores.dir}" name="Import Server Certificate into Client Trustore">
                            <stdin>
                                <file file="${ssltest.stores.dir}/client_cert.pem"/>
                            </stdin>keytool -v -import -storetype pkcs12 -keystore server_trustore.p12 -storepass srvtrustpwd -alias clientkey -noprompt</exec>
                    </jobs>
                </sequential>
                <web:server id="server" xmlns:web="oddjob:web">
                    <handler>
                        <web:resource base="${oddjob.dir}">
                            <welcomeFiles>
                                <list>
                                    <values>
                                        <value value="index.html"/>
                                    </values>
                                </list>
                            </welcomeFiles>
                        </web:resource>
                    </handler>
                    <modifiers>
                        <web:ssl clientAuth="NEED" keyStorePassword="srvstorepwd" keyStorePath="${ssltest.stores.dir}/server_keystore.p12" keyStoreType="PKCS12" trustStorePassword="srvtrustpwd" trustStorePath="${ssltest.stores.dir}/server_trustore.p12" trustStoreType="PKCS12"/>
                    </modifiers>
                </web:server>
                <web:client id="client" url="https://${ssltest.hostname}:${server.port}" xmlns:web="oddjob:web">
                    <ssl>
                        <web:ssl keyStorePassword="clistorepwd" keyStorePath="${ssltest.stores.dir}/client_keystore.p12" keyStoreType="PKCS12" trustStorePassword="clitrustpwd" trustStorePath="${ssltest.stores.dir}/client_trustore.p12" trustStoreType="PKCS12"/>
                    </ssl>
                </web:client>
                <echo id="echo">${client.content}></echo>
                <check eq="&lt;h1>Hello World&lt;/h1>" value="#{client.get('content').trim()}"/>
                <stop job="${server}"/>
            </jobs>
        </sequential>
    </job>
</oddjob>

(c) R Gordon Ltd 2005 - Present