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.disabledAlgorithms`¹	Disabled certificate verification cryptographic algorithm (see Disabled and restricted cryptographic algorithms)	`MD2,` `MD5,SHA1 jdkCA & usage TLSServer,` `RSA keySize < 1024,DSA keySize < 1024, EC keySize < 224,` `include jdk.disabled.namedCurves` ²	None
`jdk.tls.disabledAlgorithms`¹	Disabled and restricted cryptographic algorithms	`SSLv3,TLSv1, TLSv1.1,` `RC4,` `DES,` `MD5withRSA,` `DH keySize < 1024,3DES_EDE_CBC, DESede,` `EC keySize < 224,anon, NULL,DES_CBC,` `include jdk.disabled.namedCurves`²	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.
`jdk.tls.keyLimits`¹	Limiting the amount of data that algorithms can encrypt with a set of keys	AES/GCM/NoPadding KeyUpdate 2^37	Limits 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.
`jdk.tls.legacyAlgorithms`¹	Legacy algorithms	`K_NULL, C_NULL, M_NULL, DH_anon, ECDH_anon, RC4_128, RC4_40, DES_CBC, DES40_CBC, 3DES_EDE_CBC`²	Specifies which algorithms are considered legacy algorithms, which are not negotiated during TLS security parameters negotiation unless there are no other candidates.
`jdk.tls.maxCertificateChainLength`¹	Certificate chain handling	10	Specifies the maximum allowed length of the certificate chain in TLS/DTLS handshaking.
`jdk.tls.maxHandshakeMessageSize`¹	Certificate chain handling	32768 (32 kilobytes)	Specifies the maximum allowed size, in bytes, for the handshake message in TLS/DTLS handshaking.
`jdk.tls.rejectClientInitiatedRenegotiation`¹	Rejects client-initiated renegotiation on the server side. If this system property is `true`, then the server will not accept client initiated renegotiation and will fail with a fatal `handshake_failure` alert.	`false`	None
`jdk.tls.server.defaultDHEParameters`¹	Diffie-Hellman groups	Safe prime Diffie-Hellman groups in JDK TLS implementation	Defines default finite field Diffie-Hellman ephemeral (DHE) parameters for TLS processing
`ocsp.enable`¹	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.provider`¹	Default `SSLServerSocketFactory` implementation	SSLServerSocketFactory implementation from IBM: com.ibm.jsse2.SSLServerSocketFactoryImpl	None
`ssl.SocketFactory.provider`¹	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

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

² 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
`com.ibm.jsse2.allowLegacyHelloMessages`	Transport Layer Security (TLS) Renegotiation Issue	`true`	If `true`, then allow the peer to handshake without requiring the proper RFC 5746 messages.
`com.ibm.jsse2.allowUnsafeRenegotiation`	Transport Layer Security (TLS) Renegotiation Issue	`false`	If `true`, then permit full (unsafe) legacy negotiation.
`com.ibm.jsse2.checkRevocation`¹	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.disableSSLv3`¹	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.
`com.ibm.jsse2.sslEngineCloseNotifyReceive`	Whether to throw an SSLException on an SSLEngine.closeInbound() method call if the engine did not receive the proper SSL/TLS close notification from the peer	`true`	When the value of the property is `true`, an SSLException is thrown, as specified in the SSLEngine.closeInputBound() API documentation. Throwing the SSLException causes the SSL session to be invalidated and therefore the SSL session cannot be resumed. Set this property to `false` to not throw an SSLException, which complies with the TLS 1.1 and later standards and allows SSL session resumption when a close/notify message is not received from the peer.
`com.ibm.jsse2.overrideDefaultCSName`	Whether to return cipher suite names that match Oracle equivalents	`false`	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.
`com.ibm.jsse2.sp800-131`¹	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.strictServerSigCheck` ¹	Whether to strictly enforce RFC 5246 - TLS 1.2 Section 7.4.1.4.1. Signature Algorithms on the entire certificate chain that the server presented or not.	`false`	Set this property to `false` to validate only the server’s end entity certificate. The entire server's certificate chain need not match the client's signature algorithm extension. Set this property to `true` to validate that the server's certificate chain is in compliance with the client's signature algorithm extension.
`com.ibm.jsse2.suiteB`¹	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.usefipsprovider`¹	Run IBMJSSE2 in FIPS mode	`false`	Set this property to `true` to run IBMJSSE2 in FIPS mode.
Customize via `port` field in the HTTPS URL¹	Default HTTPS port	`443`	None
`https.cipherSuites`¹	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.protocols`¹	Default handshaking protocols for HTTPS connections. See also Enabling TLS 1.3	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.proxyHost`¹	Default proxy host	None	None
`https.proxyPort`¹	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.keyStore`¹	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.keyStorePassword`¹	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.keyStoreProvider`¹	Default keystore provider; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords	None	None
`javax.net.ssl.keyStoreType`¹	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.trustStore`¹	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.trustStorePassword`¹	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.trustStoreProvider`¹	Default truststore provider; see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords	None	None
`javax.net.ssl.trustStoreType`¹	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).
`jdk.tls.acknowledgeCloseNotify`¹	Specifying that a close_notify alert is sent when one is received	`false`	If 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.
`jdk.tls.client.cipherSuites`¹	Client-side default enabled cipher suites; see Specifying default enabled cipher suites.	See Cipher suites for a list of currently implemented IBMJSSE2 cipher suites, sorted by order of preference.	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.
`jdk.tls.client.enableCAExtension`	Enables certificate authorities extension for server certificate selection.	`false`	The 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 2¹⁶ bytes), the extension is not enabled. Some server implementations do not allow handshake messages to exceed 2¹⁴ 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.
`jdk.tls.client.enableStatusRequestExtension`¹	Setting up a Java Client to Use OCSP Stapling	`false`	If `true`, then the status_request and status_request_v2 extensions are enabled, and processing for CertificateStatus messages sent by the server is enabled.
`jdk.tls.client.disableExtensions`¹	Configuring Default Extensions	`None`	Blocks extensions used on the client side.
`jdk.tls.client.protocols`¹	Default handshaking protocols for TLS clients. See Protocols and Enabling TLS 1.3.	`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.
`jdk.tls.client.SignatureSchemes`¹	Contains 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.	None	Unrecognized 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.
`jdk.tls.ephemeralDHKeySize`¹	Customizing the size of Ephemeral Diffie-Hellman Keys	`2048` bits	None
`jdk.tls.namedGroups`¹	Customizing the supported named groups for TLS key exchange.	If 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.	This contains a comma-separated list within quotation marks of enabled named groups in preference order. For example: `jdk.tls.namedGroups="secp521r1,secp256r1,ffdhe2048"`
`jdk.tls.server.cipherSuites`¹	Server-side default enabled cipher suites. See Specifying default enabled cipher suites.	See Cipher suites to determine which cipher suites are enabled by default	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.
`jdk.tls.server.enableStatusRequestExtension`¹	Setting Up a Java Server to Use OCSP Stapling	`false`	If `true`, then server-side support for OCSP stapling is enabled
`jdk.tls.server.disableExtensions`¹	Configuring Default Extensions	None	Blocks extensions used on the server side.
`jdk.tls.server.protocols`¹	Default handshaking protocols for TLS servers. See Protocols and Enabling TLS 1.3.	`none`	To 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.
`jdk.tls.server.SignatureSchemes`¹	Contains 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.	None	Unrecognized 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.
`jsse.enableCBCProtection`¹	Adds randomness to prevent CBC attacks. For more information, see Browser Exploit Against SSL/TLS (BEAST) security vulnerability.	`false` (Initial release) `true`	Set this property to `true` to specify that CBC protection is enabled.
`jsse.enableFFDHE`	Enables or disables Finite Field Diffie-Hellman Ephemeral (FFDHE) parameters for TLS key exchange.	`true`	FFDHE 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.
`jsse.enableMFLNExtension`¹	Customizing the Maximum Fragment Length Negotiation (MFLN) extension	`false`	None
`jsse.enableSNIExtension`¹	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.acceptLargeFragments`¹	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).

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