Use the ssl.client.props file to configure Secure Sockets Layer (SSL) for clients. In previous releases of WebSphere® Application Server, SSL properties were specified in the sas.client.props or soap.client.props files or as system properties. By consolidating the configurations, WebSphere Application Server enables you to manage security in a manner that is comparable to server-side configuration management. You can configure the ssl.client.props file with multiple SSL configurations.
Client runtimes are dependent on the WebSphere Application Server ssl.client.props configurations.
Use the setupCmdLine.bat script on the command
line to specify the com.ibm.SSL.ConfigURL system property.
Use the setupCmdLine.sh script on the command
line to specify the com.ibm.SSL.ConfigURL system property.
-Dcom.ibm.SSL.ConfigURL=file:profile_root
\properties\ssl.client.props
The com.ibm.SSL.ConfigURL
property references a file URL that points to the ssl.client.props file.
You can reference the CLIENTSSL variable on the command line of any
script that uses the setupCmdLine.bat file.
The
com.ibm.SSL.ConfigURL property references a file URL that points to
the ssl.client.props file. You can reference the CLIENTSSL
variable on the command line of any script that uses the setupCmdLine.sh file.
com.ibm.ssl.alias=DefaultSSLSettings
com.ibm.ssl.alias=DefaultSSLSettingsIn the ssl.client.props file, you can change the administrative SSL configuration to avoid modifying the soap.client.props file.
-Djava.security.properties=profile_root/properties/java.security
Global properties
Global SSL properties are process-specific properties
that include Federal Information Processing Standard (FIPS) enablement,
the default SSL alias, the user.root property for specifying the root
location of the key and truststore paths, and so on.
Property | Default | Description |
---|---|---|
com.ibm.ssl.defaultAlias | DefaultSSLSettings | Specifies the default alias that is used whenever an alias is not specified by the protocol that calls the JSSEHelper API to retrieve an SSL configuration. This property is the final arbiter on the client side for determining which SSL configuration to use. |
com.ibm.ssl.validationEnabled | false | When set to true, this property validates each SSL configuration as it is loaded. Use this property for debug purposes only, to avoid unnecessary performance overhead during production. |
com.ibm.ssl.performURLHostNameVerification | false | When set to true, this property
enforces URL host name verification. When HTTP URL connections are
made to target servers, the common name (CN) from the server certificate
must match the target host name. Without a match, the host name verifier
rejects the connection. The default value of false omits
this check. As a global property, it sets the default host name verifier.
Any javax.net.ssl.HttpsURLConnection object can choose to enable host
name verification for that specific instance by calling the setHostnameVerifier
method with its own HostnameVerifier instance.![]() ![]() ![]() |
com.ibm.security.useFIPS | false | When set to true, FIPS-compliant algorithms are used for SSL and other Java™ Cryptography Extension (JCE)-specific applications. This property is typically not enabled unless the property is required by the operating environment. |
user.root | C:\WebSphere\AppServer \profiles\default | This property can be used by key and truststore location properties as a single property for specifying the root path to the key and truststores. Typically, this property is the profile root. However, you can modify this property to any root directory on the local machine that has the proper read and potentially write authority to that directory. |
user.root | ${WASROOT} | This property can be used by key and truststore location properties as a single property for specifying the root path to the key and truststores. Typically, this property is the profile root. However, you can modify this property to any root directory on the local machine that has the proper read and potentially write authority to that directory. |
profile_root of the profile | C\WebSphere\AppServer \profiles\default | Key and truststore location properties can use this property as a single property for specifying the root path to the key and truststores. You can modify this property to any root directory on the local machine that has the proper read (and potentially write) authority to that directory. |
Certificate creation properties
Use certificate creation properties to specify the default self-signed certificate values for the major attributes of a certificate. You can define the distinguished name (DN), expiration date, key size, and alias that are stored in the keystore.Property | Default | Description |
---|---|---|
com.ibm.ssl.defaultCertReqAlias | default_alias | This property specifies the default alias to use to reference the self-signed certificate that is created in the keystore. If the alias already exists with that name, the default alias is appended with _#, where the number sign (#) is an integer that starts with 1 and increments until it finds a unique alias. |
com.ibm.ssl.defaultCertReqSubjectDN | cn=${hostname}, o=IBM,c=US | This property uses the property distinguished name (DN) that you set for the certificate when it is created. The ${hostname} variable is expanded to the host name on which it resides. You can use correctly formed DNs as specified by the X.509 certificate. |
com.ibm.ssl.defaultCertReqDays | 365 | This property specifies the validity period for the certificate and can be as small as 1 day and as large as the maximum number of days that a certificate can be set, which is approximately 15 years. |
com.ibm.ssl.defaultCertReqKeySize | 1024 | This property is the default key size. The valid values depend upon the Java Virtual Machine (JVM) security policy files that are installed. By default, the product JVMs ship with the export policy file that limits the key size to 1024. To get a large key size such as 2048, you can download the restricted policy files from the Web site. |
Certificate revocation checking
To enable certificate revocation checking, you can set a combination of Online Certificate Status Protocol (OCSP) properties. These properties are not used unless you set the com.ibm.ssl.trustManager property to IbmPKIX. In addition, to successfully process revocation checking on the client, you must turn off the signer exchange prompt. To turn off the signer exchange prompt, change the com.ibm.ssl.enableSignerExchangePrompt property to false. For more information, see the related link to the "Enabling certificate revocation checking with the default IbmPKIX trust manager" topic.SSL configuration properties
Use the SSL configuration properties section to set multiple SSL configurations. For a new SSL configuration specification, set the com.ibm.ssl.alias property because the parser starts a new SSL configuration with this alias name. The SSL configuration is referenced by using the alias property from another file, such as sas.client.props or soap.client.props, through the default alias property. The properties that are specified in the following table enable you to create a javax.net.ssl.SSLContext, among other SSL objects.Property | Default | Description |
---|---|---|
com.ibm.ssl.alias | DefaultSSLSettings | This property is the name of this SSL configuration and must be the first property for an SSL configuration because it references the SSL configuration. If you change the name of this property after it is referenced elsewhere in the configuration, the runtime defaults to the com.ibm.ssl.defaultAlias property whenever the reference is not found. The error trust file is null or key file is null might display when you start an application using an SSL reference that is no longer valid. |
com.ibm.ssl.protocol | SSL_TLS | This property is the SSL handshake protocol that is used for this SSL configuration. This property attempts Transport Layer Security (TLS) first, but accepts any remote handshake protocol, including SSLv3 and TLS. Valid values for this property include SSLv2 (client side only), SSLv3, SSL, TLS, TLSv1, and SSL_TLS. |
com.ibm.ssl.securityLevel | ![]() ![]() |
This property specifies the cipher
group that is used for the SSL handshake. ![]() ![]() ![]() ![]() Note:
![]() ![]() |
com.ibm.ssl.trustManager | IbmX509 | This property specifies the default trust manager that you must use to validate the certificate sent by the target server. This trust manager does not perform certificate revocation list (CRL) checking. You can choose to change this value to IbmPKIX for CRL checking using CRL distribution lists in the certificate, which is a standard way to perform CRL checking. When you want to perform custom CRL checking, you must implement a custom trust manager and specify the trust manager in the com.ibm.ssl.customTrustManagers property. The IbmPKIX option might affect performance because this option requires IBMCertPath for trust validation. Use IbmX509 unless CRL checking is necessary. If you are using the Online Certificate Status Protocol (OCSP) properties, set this property value to IbmPKIX. |
com.ibm.ssl.keyManager | IbmX509 | This property specifies the default key manager to use for choosing the client alias from the specified keystore. This key manager uses the com.ibm.ssl.keyStoreClientAlias property to specify the keystore alias. If this property is not specified, the choice is delegated to Java Secure Socket Extension (JSSE). JSSE typically chooses the first alias that it finds. |
com.ibm.ssl.contextProvider | IBMJSSE2 | This property is used to choose the JSSE provider for the SSL context creation. It is recommended that you default to IBMJSSE2 when you use a Java virtual machine (JVM). The client plug-in can use the SunJSSE provider when using a Sun JVM. |
com.ibm.ssl.enableSignerExchangePrompt | true | This property determines whether to display the signer exchange prompt when a signer is not present in the client truststore. The prompt displays information about the remote certificate so that WebSphere Application Server can decide whether or not to trust the signer. It is very important to validate the certificate signature. This signature is the only reliable information that can guarantee that the certificate has not been modified from the original server certificate. For automated scenarios, disable this property to avoid SSL handshake exceptions. Run the retrieveSigners script, which sets up the SSL signer exchange, to download the signers from the server prior to running the client. If you are using the Online Certificate Status Protocol (OCSP) properties, set this property value to false. |
com.ibm.ssl.keyStoreClientAlias | default | This property is used to reference an alias from the specified keystore when the target does not request client authentication. When WebSphere Application Server creates a self-signed certificate for the SSL configuration, this property determines the alias and overrides the global com.ibm.ssl.defaultCertReqAlias property. |
com.ibm.ssl.customTrustManagers | Commented out by default | This property enables you to specify one or more custom trust managers, which are separated by commas. These trust managers can be in the form of algorithm|provider or classname. For example, IbmX509|IBMJSSE2 is in the algorithm|provider format, and the com.acme.myCustomTrustManager interface is in the classname format. The class must implement the javax.net.ssl.X509TrustManager interface. Optionally, the class can implement the com.ibm.wsspi.ssl.TrustManagerExtendedInfo interface. These trust managers run in addition to the default trust manager that is specified by the com.ibm.ssl.trustManager interface. These trust managers do not replace the default trust manager. |
com.ibm.ssl.customKeyManager | Commented out by default | This property enables you to have one, and only one, custom key manager. The key manager replaces the default key manager that is specified in the com.ibm.ssl.keyManager property. The form of the key manager is algorithm|provider or classname. See the format examples for the com.ibm.ssl.customTrustManagers property. The class must implement the javax.net.ssl.X509KeyManager interface. Optionally, the class can implement the com.ibm.wsspi.ssl.KeyManagerExtendedInfo interface. This key manager is responsible for alias selection. |
com.ibm.ssl.dynamicSelectionInfo | Commented out by default | This property enables dynamic association
with the SSL configuration. The syntax for a dynamic association is outbound_protocol, target_host,
or target_port. For multiple specifications, use
the vertical bar ( | ) as the delimiter. You can replace any of these
values with an asterisk (*) to indicate a wildcard value. Valid outbound_protocol values
include: IIOP, HTTP, LDAP, SIP, BUS_CLIENT, BUS_TO_WEBSPHERE_MQ,
BUS_TO_BUS, and ADMIN_SOAP. When you want the dynamic selection criteria
to choose the SSL configuration, uncomment the default property, and
add the connection information. For example, add the following on
one linecom.ibm.ssl.dynamicSelectionInfo=HTTP, .ibm.com,443|HTTP,.ibm.com,9443 |
com.ibm.ssl.enabledCipherSuites | Commented out by default | This property enables you to specify a custom cipher suite list and override the group selection in the com.ibm.ssl.securityLevel property. The valid list of ciphers varies according to the provider and JVM policy files that are applied. For cipher suites, use a space as the delimiter. |
com.ibm.ssl.keyStoreName | ClientDefaultKeyStore | This property references a keystore configuration name. If you have not already defined the keystore, the rest of the keystore properties must follow this property. After you define the keystore, you can specify this property to reference the previously specified keystore configuration. New keystore configurations in the ssl.client.props file have a unique name. |
com.ibm.ssl.trustStoreName | ClientDefaultTrustStore | This property references a truststore configuration name. If you have not already defined the truststore, the rest of the truststore properties must follow this property. After you define the truststore, you can specify this property to reference the previously specified truststore configuration. New truststore configurations in the ssl.client.props file should have a unique name. |
Keystore configurations
SSL configurations reference keystore configurations whose purpose is to identify the location of certificates. Certificates represent the identity of clients that use the SSL configuration. You can specify keystore configurations with other SSL configuration properties. However, it is recommended that you specify the keystore configurations in this section of the ssl.client.props file after the com.ibm.ssl.keyStoreName property identifies the start of a new keystore configuration. After you fully define the keystore configuration, the com.ibm.ssl.keyStoreName property can reference the keystore configuration at any other point in the file.Property | Default | Description |
---|---|---|
com.ibm.ssl.keyStoreName | ClientDefaultKeyStore | This property specifies the name of the keystore as it is referenced by the runtime. Other SSL configurations can reference this name further down in the ssl.client.props file to avoid duplication. |
com.ibm.ssl.keyStore | ${user.root}/etc/key.p12 | This property specifies the location
of the keystore in the required format of the com.ibm.ssl.keyStoreType
property. Typically, this property references a keystore file name.
However, for cryptographic token types, this property references a
Dynamic Link Library (DLL) file.![]() |
com.ibm.ssl.keyStorePassword | WebAS | This property is the default password, which is the cell name for the profile when it is created. The password is typically encoded using an {xor} algorithm. You can use iKeyman to change the password in the keystore, then change this reference. If you do not know the password and if the certificate is created for you, change the password in this property, then delete the keystore from the location where it resides. Restart the client to recreate the keystore by using the new password, but only if the keystore name ends with DefaultKeyStore and if the fileBased property is true. Delete both the keystore and truststore at the same time so that a proper signer exchange can occur when both are recreated together. |
com.ibm.ssl.keyStoreType | PKCS12 | This property is the keystore type. Use the default, PKCS12, because of its interoperability with other applications. You can specify this property as any valid keystore type that is supported by the JVM on the provider list. |
com.ibm.ssl.keyStoreProvider | IBMJCE | The IBM® Java Cryptography Extension property is the keystore provider for the keystore type. The provider is typically IBMJCE or IBMPKCS11Impl for cryptographic devices. |
com.ibm.ssl.keyStoreFileBased | true | This property indicates to the runtime that the keystore is file-based, meaning it is located on the file system. |
com.ibm.ssl.keyStoreReadOnly | false | This property indicates to the run time for WebSphere Application Server whether the key store can be modified during the run time. |
In the following table, the values in the
"Default values for a z/OS security product" column correspond
to the default values that are used when the Use a z/OS security
product option is indicated on the Administrative Security Selection
panel of the z/OS Profile Management Tool. This option is
the first option on the Administrative Security Selection panel. The
values in the "Default values for WebSphere Application Server security" column correspond to the default values that are
used with the Use WebSphere Application Server option
is indicated on the Administrative Security Selection panel of the z/OS Profile
Management Tool. This option is second option on the Administrative
Security Selection panel.
Property | Default values for a z/OS security product | Default values for WebSphere Application Server security | Description |
---|---|---|---|
com.ibm.ssl.keyStoreName | ClientDefaultKeyStore | ClientDefaultKeyStore | This property specifies the name of the keystore as it is referenced by the runtime. Other SSL configurations can reference this name further down in the ssl.client.props file to avoid duplication. |
com.ibm.ssl.keyStore | safreyring:///your_keyring This value is set on the SSL Customization panel of the z/OS Profile Management Tool. |
${user.root}/etc/key.p12 | This property specifies the location of the keystore in the required format of the com.ibm.ssl.keyStoreType property. Typically, this property references a keystore file name. However, for cryptographic token types, this property references a Dynamic Link Library (DLL) file. |
com.ibm.ssl.keyStorePassword | password | WebAS | This property is the default password, which is the cell name for the profile when it is created. The password is typically encoded using an {xor} algorithm. You can use iKeyman to change the password in the keystore, then change this reference. If you do not know the password and if the certificate is created for you, change the password in this property, then delete the keystore from the location where it resides. Restart the client to recreate the keystore by using the new password, but only if the keystore name ends with DefaultKeyStore and if the fileBased property is true. Delete both the keystore and truststore at the same time so that a proper signer exchange can occur when both are recreated together. |
com.ibm.ssl.keyStoreType | JCERACFKS | PKCS12 | This property is the keystore type. Use the default, PKCS12, because of its interoperability with other applications. You can specify this property as any valid keystore type that is supported by the JVM on the provider list. The type can be JCERACFKS, JCECCARACFKS, or JCECCAKS for cryptographic devices. |
com.ibm.ssl.keyStoreProvider | IBMJCE | IBMJCE | The IBM Java Cryptography Extension property is the keystore provider for the keystore type. The provider is typically IBMJCE or IBMPKCS11Impl for cryptographic devices. |
com.ibm.ssl.keyStoreFileBased | false | true | This property indicates to the runtime that the keystore is file-based, meaning it is located on the file system. |
com.ibm.ssl.keyStoreReadOnly | true | false | This property indicates to the run time for WebSphere Application Server whether the keystore can be modified during the run time. For example, you cannot modify read-only key stores using the Administrative Console or through scripting. SAF Keyrings, which are used by WebSphere Application Server for z/OS, are always read-only. |
Truststore Configurations
SSL configurations reference truststore configurations, whose purpose is to contain the signer certificates for servers that are trusted by this client. You can specify these properties with other SSL configuration properties. However, it is recommended that you specify truststore configurations in this section of the ssl.client.props file after the com.ibm.ssl.trustStoreName property has identified the start of a new truststore configuration. After you fully define the truststore configuration, the com.ibm.ssl.trustStoreName property can reference the configuration at any other point in the file.
A truststore is a keystore that JSSE uses for trust evaluation. A truststore contains the signers that WebSphere Application Server requires before it can trust the remote connection during the handshake. If you configure the com.ibm.ssl.trustStoreName=ClientDefaultKeyStore property, you can reference the keystore as the truststore. Further configuration is not required for the truststore because all of the signers that are generated through signer exchanges are imported into the keystore where they are called by the runtime.
In
the following table, the values in the "Default values with a z/OS security
product" column correspond to the default values that are used when
the Use a z/OS security product option is indicated
on the Administrative Security Selection panel of the z/OS Profile
Management Tool. This option is the first option on the Administrative
Security Selection panel. The values in the "Default values with WebSphere Application Server security"
column correspond to the default values that are used with the Use WebSphere Application Server option
is indicated on the Administrative Security Selection panel of the z/OS Profile
Management Tool. This option is the second option on the Administrative
Security Selection panel.
Property | Default | Description |
---|---|---|
com.ibm.ssl.trustStoreName | ClientDefaultTrustStore | This property specifies the name of the truststore as it is referenced by the runtime. Other SSL configurations can reference further down in the ssl.client.props file to avoid duplication. |
com.ibm.ssl.trustStore | ${user.root}/etc/trust.p12 | This property specifies the location
of the truststore in the format that is required by the truststore
type that is referenced by the com.ibm.ssl.trustStoreType property.
Typically, this property references a truststore file name. However,
for cryptographic token types, this property references a DLL file.![]() |
com.ibm.ssl.trustStorePassword | WebAS | This property specifies the default password, which is the cell name for the profile when it is created. The password is typically encoded using an {xor} algorithm. You can use iKeyman to change the password in the keystore, then change the reference in this property. If you do not know the password and if the certificate was created for you, change the password in this property, then delete the truststore from the location where it resides. Restart the client to recreate the truststore by using the new password, but only if the keystore name ends with DefaultTrustStore and the fileBased property is true. It is recommended that you delete the keystore and the truststore at the same time so that a proper signer exchange can occur when both are recreated together. |
com.ibm.ssl.trustStoreType | PKCS12 | This property is the truststore type. Use the default PKCS12 type because of its interoperability with other applications. You can specify this property as any valid truststore type that is supported by the JVM functionality on the provider list. |
com.ibm.ssl.trustStoreProvider | IBMJCE | This property is the truststore provider for the truststore type. The provider is typically IBMJCE or IBMPKCS11Impl for cryptographic devices. |
com.ibm.ssl.trustStoreFileBased | true | This property indicates to the runtime that the truststore is file-based, meaning it is located on the file system. |
com.ibm.ssl.trustStoreReadOnly | false | This property indicates to the run time for WebSphere Application Server whether the truststore can be modified during the run time. |
Property | Default values with a z/OS security product | Default values with WebSphere Application Server security | Description |
---|---|---|---|
com.ibm.ssl.trustStoreName | ClientDefaultTrustStore | ClientDefaultTrustStore | This property specifies the name of the truststore as it is referenced by the runtime. Other SSL configurations can reference further down in the ssl.client.props file to avoid duplication. |
com.ibm.ssl.trustStore | safreyring:///your_keyring This value is set on the SSL Customization panel of the z/OS Profile Management Tool. |
${user.root}/etc/trust.p12 | This property specifies the location of the truststore in the format that is required by the truststore type that is referenced by the com.ibm.ssl.trustStoreType property. Typically, this property references a truststore file name. However, for cryptographic token types, this property references a DLL file. |
com.ibm.ssl.trustStorePassword | password | WebAS | This property specifies the default password, which is the cell name for the profile when it is created. The password is typically encoded using an {xor} algorithm. You can use iKeyman to change the password in the keystore, then change the reference in this property. If you do not know the password and if the certificate was created for you, change the password in this property, then delete the truststore from the location where it resides. Restart the client to recreate the truststore by using the new password, but only if the keystore name ends with DefaultTrustStore and the fileBased property is true. It is recommended that you delete the keystore and the truststore at the same time so that a proper signer exchange can occur when both are recreated together. |
com.ibm.ssl.trustStoreType | JCERACFKS | PKCS12 | This property is the truststore type. Use the default PKCS12 type because of its interoperability with other applications. You can specify this property as any valid truststore type that is supported by the JVM functionality on the provider list. The type can be JCERACFKS, JCECCARACFKS, or JCECCAKS for cryptographic devices. |
com.ibm.ssl.trustStoreProvider | IBMJCE | IBMJCE | This property is the truststore provider for the truststore type. The provider is typically IBMJCE or IBMPKCS11Impl for cryptographic devices. |
com.ibm.ssl.trustStoreFileBased | false | true | This property indicates to the runtime that the truststore is file-based, meaning it is located on the file system. |
com.ibm.ssl.trustStoreReadOnly | true | false | This property indicates to the run time for WebSphere Application Server whether the truststore can be modified during the run time. For example, you cannot modify read-only truststores using the Administrative Console or through scripting. SAF Keyrings, which are used by WebSphere Application Server for z/OS, are always read-only. |