SSL configurations



Overview

SSL configurations control the behavior of client and server SSL endpoints using the following connection attributes:

We can assign SSL configurations to have specific management scopes. The scope that an SSL configuration inherits depends upon whether you create it using a cell, node, server, or endpoint link in the configuration topology.

We can manage an SSL configuration using any of the following methods:

To manage SSL configurations...

We can view an SSL configuration at the level it was created and in the inherited scope below that point in the topology. If we want the entire cell to view an SSL configuration, create the configuration at the cell level in the topology.


SSL configuration in security.xml

The attributes defining an SSL configuration repertoire entry for a specific management scope are stored in security.xml. The scope determines the point at which other levels in the cell topology can see the configuration...

<repertoire xmi:id="SSLConfig_1"
            alias="NodeDefaultSSLSettings"
            managementScope="ManagementScope_1"
            type="JSSE">

    <setting xmi:id="SecureSocketLayer_1"
             clientAuthentication="false"
             clientAuthenticationSupported="false"
             securityLevel="HIGH"
             enabledCiphers=""
             jsseProvider="IBMJSSE2"
             sslProtocol="SSL_TLS"
             keyStore="KeyStore_1"
             trustStore="KeyStore_2"
             trustManager="TrustManager_1"
             keyManager="KeyManager_1"
             clientKeyAlias="default"
             serverKeyAlias="default"/>

</repertoire>


security.xml attributes

security.xml attribute Description Default Associated SSL property
xmi:id Unique identifier for this XML entry. Determines how the SSL configuration is linked to other XML objects, such as SSLConfigGroup. This system-defined value must be unique. The admin configuration service defines the default value. None. This value is used only for XML associations.
alias Name of the SSL configuration.

Direct selection uses the alias attribute and the node is not prefixed to the alias. Rather, the management scope takes care of ensuring that the name is unique within the scope.

CellDefaultSSLSettings com.ibm.ssl.alias
managementScope Management scope for the SSL configuration and determines the visibility of the SSL configuration at runtime. cell Not mapped to an SSL property. However, it confirms whether or not the SSL configuration is associated with a process.
type JSSE or SSSL configuration option.

JSSE is the SSL configuration type for most secure communications within WAS.

JSSE com.ibm.ssl.sslType
clientAuthentication Whether SSL client authentication is required. false com.ibm.ssl.clientAuthentication
clientAuthenticationSupported Whether SSL client authentication is supported.

The client does not have to supply a client certificate if it does not have a client certificate.

When you set the clientAuthentication attribute to true, you override the value that is set for the clientAuthenticationSupported attribute.

false com.ibm.ssl.client.AuthenticationSupported
securityLevel Cipher suite group. Valid values include...

HIGH 128-bit ciphers
MEDIUM 40-bit ciphers
LOW ciphers without encryption
CUSTOM customized cipher suite group

When you set the enabledCiphers attribute with a specific list of ciphers, the system ignores this attribute.

HIGH com.ibm.ssl.securityLevel
enabledCiphers Specify a unique list of cipher suites. Separate each cipher suite in the list with a space. securityLevel attribute for cipher suite selection. com.ibm.ssl.enabledCipherSuites
jsseProvider Specific JSSE provider. IBMJSSE2 com.ibm.ssl.contextProvider
sslProtocol SSL handshake protocol.

Valid options include...

  • SSLv2 (client-side only)
  • SSLv3
  • SSL
  • SSL_TLS
  • TLSv1
  • TLS

The SSL option includes SSLv2 and SSLv3 values. The TLS option includes the TLSv1 value. SSL_TLS, which is the most interoperable protocol, includes all these values and defaults to a TLS handshake.

SSL_TLS. com.ibm.ssl.protocol
keyStore Keystore and attributes of the keyStore instance that the SSL configuration uses for key selection. CellDefaultKeyStore See Keystore configurations.
trustStore Key store that the SSL configuration uses for certificate signing verification. CellDefaultTrustStore A trustStore is a logical JSSE term. It signifies a key store that contains signer certificates. Signer certificates validate certificates that are sent to WAS during an SSL handshake.
keyManager Key manager that WAS uses to select keys from a key store. A JSSE key manager controls the interface...

    javax.net.ssl.X509KeyManager

A custom key manager controls the interfaces...

    javax.net.ssl.X509KeyManager
    com.ibm.wsspi.ssl.KeyManagerExtendedInfo

...which provides more information from WAS.

IbmX509 com.ibm.ssl.keyManager defines a well-known key manager and accepts the algorithm and algorithm|provider formats, for example...

  • IbmX509
  • IbmX509|IBMJSSE2

com.ibm.ssl.customKeyManager defines a custom key manager and takes precedence over the other keyManager properties. This class must implement...

javax.net.ssl.X509KeyManager

...and can implement...

com.ibm.wsspi.ssl.KeyManagerExtendedInfo
trustManager Which trust manager or list of trust managers to use for determining whether to trust the peer side of the connection. A JSSE trust manager implements the interface...

javax.net.ssl.X509TrustManager

A custom trust manager might also implement the interface...

com.ibm.wsspi.ssl.TrustManagerExtendedInfo

...to get more information from the WAS environment.

IbmX509

We can specify the IbmPKIX trust manager for certificate revocation list (CRL) verification when the certificate contains a CRL distribution point.

com.ibm.ssl.trustManager defines a well-known trust manager, which is required for most handshake situations.

com.ibm.ssl.trustManager performs certificate expiration checking and signature validation.

We can define...

com.ibm.ssl.customTrustManagers

...with additional custom trust managers that are called during an SSL handshake. Separate additional trust managers with the vertical bar (|) character.

Client SSL configurations are managed using ssl.client.props, located in...

${USER_INSTALL_ROOT}/properties

...for each profile.

Specifying any javax.net.ssl system properties will override the corresponding property in the ssl.client.props file.



Subtopics

Trust manager control of X.509 certificate trust decisions
Key manager control of X.509 certificate identities
Example: Enabling certificate revocation checking with the default IbmPKIX trust manager
Secure communications using SSL
Create an SSL configuration
Set FIPS JSSE files