SSL configurations

Overview

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

• Keystore
• Default client certificate for outbound connections
• Default server certificate for inbound connections
• Truststore
• Key manager for selecting a certificate
• Trust manager or managers for establishing trust during the handshake
• Handshaking protocol
• Ciphers for negotiating the handshake
• Client authentication support and requirements

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:

• Central management selection
• Direct reference selection
• Dynamic outbound connection selection
• Programmatic selection

To manage SSL configurations...

Security | SSL certificates and key management | Manage endpoint security configurations | [Inbound | Outbound] | SSL_configuration

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