Customization

JSSE includes a standard implementation that can be customized by plugging in different implementations or specifying the default keystore, and so on. The following tables summarize which aspects can be customized, what the defaults are, and which mechanisms are used to provide customization.

Some of the customizations are done by setting system property or security property values. Sections following the table explain how to set such property values.

The following table shows items that are customized by setting a java.security.Security property:

Table 1. JSSE items customized by java.security.Security properties
Security Property Customized Item Default Value Notes
JCE encryption algorithms used by the IBMJSSE2 provider Give alternative JCE algorithm providers a higher preference order than the IBMJCE provider; see Customizing the Encryption Algorithm Providers. IBMJCE implementations None
jdk.certpath.disabledAlgorithms1 Disabled certificate verification cryptographic algorithm (see Disabled and restricted cryptographic algorithms) MD2, Start of changes for service refresh 2 fix pack 10MD5,End of changes for service refresh 2 fix pack 10Start of changes for service refresh 5 fix pack 10SHA1 jdkCA & usage TLSServer, End of changes for service refresh 5 fix pack 10 RSA keySize < 1024,Start of changes for service refresh 4 fix pack 5DSA keySize < 1024, EC keySize < 224End of changes for service refresh 4 fix pack 5 2 None
jdk.tls.disabledAlgorithms1 Disabled and restricted cryptographic algorithms SSLv3,Start of changes for service refresh 6 fix pack 30TLSv1, TLSv1.1,End of changes for service refresh 6 fix pack 30 Start of changes for service refresh 1RC4, End of changes for service refresh 1Start of changes for service refresh 5 fix pack 25DES,End of changes for service refresh 5 fix pack 25 Start of changes for service refresh 2 fix pack 10MD5withRSA,End of changes for service refresh 2 fix pack 10 Start of changes for service refresh 5 fix pack 10DH keySize < 1024,End of changes for service refresh 5 fix pack 10Start of changes for service refresh 4 3DES_EDE_CBC, DESede,End of changes for service refresh 4Start of changes for service refresh 4 fix pack 5 EC keySize < 224,End of changes for service refresh 4 fix pack 5Start of changes for service refresh 5 fix pack 30anon, NULL,End of changes for service refresh 5 fix pack 30Start of changes for service refresh 6 fix pack 25DES_CBCEnd of changes for service refresh 6 fix pack 252 Disables specific algorithms (protocols versions, cipher suites, key exchange mechanisms, etc.) that will not be negotiated for Transport Layer Security (TLS) connections, even if they are enabled explicitly in an application.
Note: If you are using the IBMJCEFIPS provider for TLS, add RSASSA-PSS, RSAPSS to this system property in the java.security file.
Start of changes for service refresh 6 fix pack 25jdk.tls.keyLimits1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Limiting the amount of data that algorithms can encrypt with a set of keysEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25AES/GCM/NoPadding KeyUpdate 2^37End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Limits the amount of data an algorithm may encrypt with a specific set of keys; once this limit is reached, a KeyUpdate post-handshake message is sent, which requests that the current set of keys be updated.End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 2jdk.tls.legacyAlgorithms1End of changes for service refresh 2 Start of changes for service refresh 2Legacy algorithmsEnd of changes for service refresh 2 Start of changes for service refresh 2K_NULL, C_NULL, M_NULL, DH_anon, ECDH_anon, RC4_128, RC4_40, DES_CBC, DES40_CBC, 3DES_EDE_CBC2End of changes for service refresh 2 Start of changes for service refresh 2Specifies which algorithms are considered legacy algorithms, which are not negotiated during TLS security parameters negotiation unless there are no other candidates.End of changes for service refresh 2
Start of changes for service refresh 2jdk.tls.server.defaultDHEParameters1End of changes for service refresh 2 Start of changes for service refresh 2Diffie-Hellman groupsEnd of changes for service refresh 2 Start of changes for service refresh 2Safe prime Diffie-Hellman groups in JDK TLS implementationEnd of changes for service refresh 2 Start of changes for service refresh 2Defines default finite field Diffie-Hellman ephemeral (DHE) parameters for TLS processingEnd of changes for service refresh 2
ocsp.enable1 Determine X.509 certificate revocation status with OCSP false Enables client-driven Online Certificate Status Protocol (OCSP). You must also enable revocation checking; see Setting up a Java Client to use Client-Driven OCSP.
security.provider.n Cryptographic service provider; see Customizing the Provider Implementation and Customizing the Encryption Algorithm Providers Differs per platform; check the java.security security properties file. Specify the provider in the security.provider.n= line in the security properties file, where n is an integer whose value is equal or greater than 1.
ssl.KeyManagerFactory.algorithm Default key manager factory algorithm name (see Customizing the Default Key and Trust Managers) IbmX509 None
ssl.ServerSocketFactory.provider1 Default SSLServerSocketFactory implementation SSLServerSocketFactory implementation from IBM: com.ibm.jsse2.SSLServerSocketFactoryImpl None
ssl.SocketFactory.provider1 Default SSLSocketFactory implementation SSLSocketFactory implementation from IBM: com.ibm.jsse2.SSLSocketFactoryImpl None
ssl.TrustManagerFactory.algorithm Default trust manager factory algorithm name (see Customizing the Default Key and Trust Managers) PKIX None

1 There is no guarantee the property will continue to exist or be of the same type (system or security) in future releases.

2 The list of restricted, disabled, and legacy algorithms specified in these security properties might change; see the java.security file in your SDK installation for the latest values.

The following table shows items that are customized by setting a java.lang.System property.
Table 2. JSSE items customized by java.lang.System properties
System Property Customized Item Default Notes
Start of changes for service refresh 6 fix pack 25com.ibm.jsse2.allowLegacyHelloMessagesEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Transport Layer Security (TLS) Renegotiation IssueEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25trueEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25If true, then allow the peer to handshake without requiring the proper RFC 5746 messages.End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 25com.ibm.jsse2.allowUnsafeRenegotiationEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Transport Layer Security (TLS) Renegotiation IssueEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25If true, then permit full (unsafe) legacy negotiation.End of changes for service refresh 6 fix pack 25
com.ibm.jsse2.checkRevocation1 Revocation checking false You must enable revocation checking to enable client-driven OCSP; see Determine X.509 certificate revocation status with OCSP.
com.ibm.jsse2.disableSSLv31 Padding Oracle On Downgraded Legacy Encryption (POODLE) security vulnerability true Disables use of the SSL V3.0 protocol, which is the default. Setting this value to false enables SSL V3.0 and exposes an application to this vulnerability.
Start of changes for service refresh 6 fix pack 25com.ibm.jsse2.overrideDefaultCSNameEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Whether to return cipher suite names that match Oracle equivalentsEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25

Set this property to false to return cipher suite names that match earlier releases of the SDK.

Set this property to true to return cipher suite names as defined by Oracle.

End of changes for service refresh 6 fix pack 25
com.ibm.jsse2.sp800-1311 SP800-131A Compliance off Set this property to transition to specify that SP800-131a transition compliance is requested. Set the property to strict to allow only strict adherence to the SP800-131a recommendation. The default value specifies not SP800-131a compliant.
com.ibm.jsse2.suiteB1 Suite B compliance, see Suite B Profile for Transport Layer Security (TLS) false Set this property to 128 to specify the 128-bit minimum level of security, or 192 to specify the 192-bit minimum level of security. The default value specifies not Suite B compliant.
com.ibm.jsse2.usefipsprovider1 Run IBMJSSE2 in FIPS mode false Set this property to true to run IBMJSSE2 in FIPS mode.
Customize via port field in the HTTPS URL1 Default HTTPS port 443 None
https.cipherSuites1 Default cipher suites for HTTPS connections Determined by the socket factory. This contains a comma-separated list of cipher suite names specifying which cipher suites to enable for use on this HttpsURLConnection. See the SSLSocket setEnabledCipherSuites(String[]) method. Note that this method sets the preference order of the ClientHello cipher suites directly from the String array passed to it.
https.protocols1 Default handshaking protocols for HTTPS connections.Start of changes for service refresh 6 fix pack 25 See also Enabling TLS 1.3End of changes for service refresh 6 fix pack 25 Determined by the socket factory. This contains a comma-separated list of protocol suite names specifying which protocol suites to enable on this HttpsURLConnection. See the SSLSocket setEnabledProtocols(String[]) method.
https.proxyHost1 Default proxy host None None
https.proxyPort1 Default proxy port 80 None
java.protocol.handler.pkgs Specifying an Alternative HTTPS Protocol Implementation Implementation from IBM com.ibm.net.ssl.www2.protocol None
javax.net.ssl.keyStore1 Default keystore; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords If no system property, then jssecacerts is the default. Otherwise, cacerts is the default. The value NONE may be specified. This setting is appropriate if the keystore is not file-based (for example, it resides in a hardware token)
javax.net.ssl.keyStorePassword1 Default keystore password; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords changeit It is inadvisable to specify the password in a way that exposes it to discovery by other users. For example, specifying the password on the command line. To keep the password secure, have the application prompt for the password, or specify the password in a properly protected option file.
javax.net.ssl.keyStoreProvider1 Default keystore provider; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords None None
javax.net.ssl.keyStoreType1 Default keystore type; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords KeyStore.getDefaultType() None
javax.net.ssl.sessionCacheSize Default value for the maximum number of entries in the SSL session cache 100 The session cache size can be set by calling the SSLSessionContext.setSessionCacheSize method or by setting the javax.net.ssl.sessionCachSize system property. If the cache size is not set, the default value is used.
javax.net.ssl.trustStore1 Default truststore; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords jssecacerts, if it exists; otherwise, cacerts None
javax.net.ssl.trustStorePassword1 Default truststore password; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords None It is inadvisable to specify the password in a way that exposes it to discovery by other users. For example, specifying the password on the command line. To keep the password secure, have the application prompt for the password, or specify the password in a properly protected option file.
javax.net.ssl.trustStoreProvider1 Default truststore provider; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords None None
javax.net.ssl.trustStoreType1 Default truststore type; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords KeyStore.getDefaultType() The value NONE may be specified. This setting is appropriate if the truststore is not file-based (for example, it resides in a hardware token).
Start of changes for service refresh 6 fix pack 25jdk.tls.acknowledgeCloseNotify1 End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Specifying that a close_notify alert is sent when one is receivedEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25If the system property is set to true, then when the client or server receives a close_notify alert, it sends a corresponding close_notify alert and the connection is duplex-closed.End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 25jdk.tls.client.cipherSuites1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Client-side default enabled cipher suites; see Specifying default enabled cipher suites.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25See Cipher suites for a list of currently implemented IBMJSSE2 cipher suites, sorted by order of preference.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25
Attention: These system properties can be used to configure weak cipher suites, or the configured cipher suites might be weak in the future. It is not recommended that you use these system properties without understanding the risks.
End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 30jdk.tls.client.enableCAExtensionEnd of changes for service refresh 6 fix pack 30 Start of changes for service refresh 6 fix pack 30Enables certificate authorities extension for server certificate selection.End of changes for service refresh 6 fix pack 30 Start of changes for service refresh 6 fix pack 30falseEnd of changes for service refresh 6 fix pack 30 Start of changes for service refresh 6 fix pack 30The certificate authorities extension, an optional extension introduced in TLS 1.3, is used to indicate the certificate authorities (CAs) that an endpoint supports and that should be used by the receiving endpoint to guide certificate selection. This extension is always present for client certificate selection but is optional for server certificate selection; to enable it, set the system property to true.
Notes:
  • If the client or server trusts more CAs than the size limit of the extension (less than 216 bytes), the extension is not enabled.
  • Some server implementations do not allow handshake messages to exceed 214 bytes so there might be interoperability issues if this system property is set to true and the client trusts more CAs than the server implementation limit.
End of changes for service refresh 6 fix pack 30
Start of changes for service refresh 6 fix pack 25jdk.tls.client.enableStatusRequestExtension1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Setting up a Java Client to Use OCSP StaplingEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25If true, then the status_request and status_request_v2 extensions are enabled, and processing for CertificateStatus messages sent by the server is enabled.End of changes for service refresh 6 fix pack 25
jdk.tls.client.protocols1 Default handshaking protocols for TLS clients. See ProtocolsStart of changes for service refresh 6 fix pack 25 and Enabling TLS 1.3End of changes for service refresh 6 fix pack 25. none To enable specific IBMJSSE2 protocols on the client, specify them in a comma-separated list within quotation marks; all other supported protocols are not enabled on the client. For example, if jdk.tls.client.protocols="TLSv1,TLSv1.1", the default protocol settings on the client for TLSv1 and TLSv1.1 are enabled, while SSLv3, TLSv1.2, and TLSv1.3 are not enabled.
Start of changes for service refresh 6 fix pack 25jdk.tls.client.SignatureSchemes1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Contains a comma-separated list of supported signature scheme names that specifies the signature schemes that could be used for TLS connections on the client side.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25NoneEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Unrecognized or unsupported signature scheme names specified in the property are ignored. If this system property is not defined or empty, the provider-specific default is used. The names are not case sensitive.End of changes for service refresh 6 fix pack 25
jdk.tls.ephemeralDHKeySize1 Customizing the size of Ephemeral Diffie-Hellman Keys 1024 bits None
Start of changes for service refresh 4 fix pack 5jdk.tls.namedGroups1End of changes for service refresh 4 fix pack 5 Start of changes for service refresh 4 fix pack 5Customizing the supported named groups for TLS key exchange.End of changes for service refresh 4 fix pack 5 Start of changes for service refresh 4 fix pack 5If this system property is not defined or the value is empty, the default groups and preferences will be used. For more information about the default groups, see Setting a list of enabled named groups.End of changes for service refresh 4 fix pack 5 Start of changes for service refresh 4 fix pack 5This contains a comma-separated list within quotation marks of enabled named groups in preference order. For example: jdk.tls.namedGroups="secp521r1,secp256r1Start of changes for service refresh 6 fix pack 35,ffdhe2048End of changes for service refresh 6 fix pack 35"End of changes for service refresh 4 fix pack 5
Start of changes for service refresh 6 fix pack 25jdk.tls.server.cipherSuites1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Server-side default enabled cipher suites. See Specifying default enabled cipher suites.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25See Cipher suites to determine which cipher suites are enabled by defaultEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25
Attention: These system properties can be used to configure weak cipher suites, or the configured cipher suites may be weak in the future. It is not recommended that you use these system properties without understanding the risks.
End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 25jdk.tls.server.enableStatusRequestExtension1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Setting Up a Java Server to Use OCSP StaplingEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25If true, then server-side support for OCSP stapling is enabledEnd of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 25jdk.tls.server.protocols1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Default handshaking protocols for TLS servers. See Protocols and Enabling TLS 1.3.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25noneEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25To configure the default enabled protocol suite in the server side of an IBMJSSE2 provider, specify the protocols in a comma-separated list within quotation marks. The protocols in this list are standard SSL protocol names as described in Appendix A: Standard Names. Note that this system property impacts only the default protocol suite (SSLContext of the algorithms SSL and TLS). If an application uses a version-specific SSLContext (SSLv3, TLSv1, TLSv1.1, TLSv1.2, or TLSv1.3), or sets the enabled protocol version explicitly, this system property has no impact.End of changes for service refresh 6 fix pack 25
Start of changes for service refresh 6 fix pack 25jdk.tls.server.SignatureSchemes1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Contains a comma-separated list of supported signature scheme names that specifies the signature schemes that could be used for TLS connections on the server side.End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25NoneEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Unrecognized or unsupported signature scheme names specified in the property are ignored. If this system property is not defined or empty, then the provider-specific default is used. The names are not case sensitive.End of changes for service refresh 6 fix pack 25
jsse.enableCBCProtection1 Adds randomness to prevent CBC attacks. For more information, see Browser Exploit Against SSL/TLS (BEAST) security vulnerability.
  • false (Initial release)
  • Start of changes for service refresh 1trueEnd of changes for service refresh 1
Set this property to true to specify that CBC protection is enabled.
Start of changes for service refresh 6 fix pack 35jsse.enableFFDHEEnd of changes for service refresh 6 fix pack 35 Start of changes for service refresh 6 fix pack 35Enables or disables Finite Field Diffie-Hellman Ephemeral (FFDHE) parameters for TLS key exchange.End of changes for service refresh 6 fix pack 35 Start of changes for service refresh 6 fix pack 35trueEnd of changes for service refresh 6 fix pack 35 Start of changes for service refresh 6 fix pack 35FFDHE is a TLS extension defined in RFC 7919. This extension enables TLS connections to use known finite field Diffie-Hellman groups. Some very old TLS vendors might be unable to handle TLS extensions. In this case, set this property to false to disable the FFDHE extension.End of changes for service refresh 6 fix pack 35
Start of changes for service refresh 6 fix pack 25jsse.enableMFLNExtension1End of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25Customizing the Maximum Fragment Length Negotiation (MFLN) extensionEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25falseEnd of changes for service refresh 6 fix pack 25 Start of changes for service refresh 6 fix pack 25NoneEnd of changes for service refresh 6 fix pack 25
jsse.enableSNIExtension1 Server Name Indication option true Server Name Indication (SNI) is a TLS extension, defined in RFC 6066. It enables TLS connections to virtual servers, in which multiple servers for different network names are hosted at a single underlying network address. Some very old TLS vendors might not be able handle TLS extensions. In this case, set this property to false to disable the SNI extension
jsse.SSLEngine.acceptLargeFragments1 Default sizing buffers for large TLS packets None Setting this system property to true, SSLSession will size buffers to handle large data packets by default (see the note in SSLSession and ExtendedSSLSession Interfaces). This might cause applications to allocate unnecessarily large SSLEngine buffers. Instead, applications should dynamically check for buffer overflow conditions and resize buffers as appropriate (see Status of Operations).

1 There is no guarantee the property will continue to exist or be of the same type (system or security) in future releases.