Package com.unboundid.util.ssl
Class SSLUtil
- java.lang.Object
-
- com.unboundid.util.ssl.SSLUtil
-
@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class SSLUtil extends java.lang.Object
This class provides a relatively simple interface for helping to configure secure communication using TLS (formerly known as SSL) and StartTLS (which uses an LDAP extended operation to convert an already-established non-secure connection to one that uses TLS security). When establishing secure connections, there are five main concepts to be aware of:- The allowed set of TLS protocol versions
- The allowed set of TLS cipher suites
- The key manager (if any) to use for obtaining local certificates
- The trust manager to use for determining whether to trust peer certificates
- The logic used to validate certificate hostnames
TLS Protocol Versions
The TLS protocol has evolved over time to improve both security and efficiency, and each update to the protocol has been assigned a version number. At present, only TLSv1.3 and TLSv1.2 are considered secure, and only those versions will be enabled by default, with TLSv1.3 preferred over TLSv1.2. Note that some older JVMs do not support TLSv1.3, and only TLSv1.2 will be enabled by default in that case. In the very unlikely event that the JVM does not support either TLSv1.3 or TLSv1.2, the LDAP SDK may fall back to enabling support for TLSv1.1 or TLSv1.
If you want or need to explicitly specify the TLS protocol versions to use for secure communication, then you may use thesetEnabledSSLProtocols(java.util.Collection<java.lang.String>)
method to indicate which protocol versions are allowed, and thesetDefaultSSLProtocol(java.lang.String)
method to indicate which is the preferred protocol version. You can use any TLS protocol version that the underlying JVM supports.
It is also possible to specify the set of enabled and default TLS protocol versions using Java system properties. Thecom.unboundid.util.SSLUtil.enabledSSLProtocols
property may be set with a comma-delimited list of the TLS protocol versions that should be enabled by default, and thecom.unboundid.util.SSLUtil.defaultSSLProtocol
property may be set with the protocol version that should be preferred. If set, these properties will override the logic that the LDAP SDK automatically uses to select default values, but those defaults may be explicitly overridden by calls to thesetEnabledSSLProtocols
andsetDefaultSSLProtocol
methods.
TLS Cipher Suites
A cipher suite encapsulates a number of settings that will be used to actually secure TLS communication between two systems, including which algorithm to use for key exchange, which algorithm to use for bulk encryption, and which algorithm to use for integrity protection. The JVM supports a fixed set of TLS cipher suites, although it may only enable support for a subset of those by default, and the LDAP SDK may further disable support for some of those suites by default for security reasons. The logic that the LDAP SDK uses to select a good default set of TLS cipher suites is encapsulated in theTLSCipherSuiteSelector
class, and the class-level documentation for that class describes the criteria that it uses to make its selection.
If you wish to override the LDAP SDK's default selection, you may use thesetEnabledSSLCipherSuites(java.util.Collection<java.lang.String>)
method to explicitly specify the set of cipher suites that should be enabled. Alternatively, thecom.unboundid.util.SSLUtil.enabledSSLCipherSuites
system property may be set with a comma-delimited list of the cipher suites that should be enabled.
Key Managers
A key manager is used to obtain access to a certificate chain and private key that should be presented to the peer during TLS negotiation. In the most common use cases, in which the LDAP SDK is used only to establish outbound connections and does not need to use a certificate to authenticate itself to the LDAP server, there won't be any need to present a certificate chain, and there won't be any need to configure a key manager. However, if you are using the LDAP SDK to accept TLS-secured connections from LDAP clients (for example, using theInMemoryDirectoryServer
or another type ofLDAPListener
), if the server requires clients to present their own certificate for mutual TLS authentication, or if you want to use the SASL EXTERNAL mechanism to use a client certificate to authenticate to the server at the LDAP layer, then you will need to specify a key manager to provide access to that certificate chain. The key manager to use for that purpose should be provided in theSSLUtil
constructor.
While anyjavax.net.ssl.KeyManager
instance can be used, the LDAP SDK provides three options that will be sufficient for most use cases:KeyStoreKeyManager
-- Allows the certificate chain and private key to be obtained from a key store file, which will typically be in the JKS or PKCS #12 format (or in the Bouncy Castle BCFKS format when using the LDAP SDK in FIPS-compliant mode).PEMFileKeyManager
-- Allows the certificate chain and private key to be obtained from text files that contain the PEM-encoded representation of X.509 certificates and a PKCS #8 private key.PKCS11KeyManager
-- Allows the certificate chain and private key to be accessed from a PKCS #11 token, like a hardware security module (HSM).
Trust Managers
A trust manager is used to determine whether to trust a certificate chain presented by a peer during TLS negotiation. Trust is a very important aspect of TLS because it's important to make sure that the peer you're communicating with is actually who you intend it to be and not someone else who has managed to hijack the negotiation process.
You will generally always want to provide a trust manager, regardless of whether you're using the LDAP SDK to act as a client or a server, and this trust manager should be provided in theSSLUtil
constructor. The LDAP SDK offers several trust manager implementations, including:JVMDefaultTrustManager
-- Uses the JVM's defaultcacerts
trust store to obtain access to a set of trusted, well-known issuer certificates, including those from commercial certification authorities like Verisign or DigiCert, and from trusted free providers like Let's Encrypt. This trust manager will only accept valid certificates that have been signed by one of those trusted authorities.TrustStoreTrustManager
-- Uses the information in a trust store file (typically in a format like JKS, PKCS #12 or BCFKS) as a set of trusted certificates and issuers.PEMFileTrustManager
-- Uses the information one or more files containing the PEM representations of X.509 certificates as a set of trusted certificates and issuers.TopologyRegistryTrustManager
-- Uses the topology registry information in the configuration of a Ping Identity Directory Server (or related server product) to obtain a set of trusted certificates and issuers.PromptTrustManager
-- Interactively prompts the user (via the terminal) to determine whether the presented certificate chain should be trusted.TrustAllTrustManager
-- Blindly trusts all certificate chains that are presented to it. This may be convenient in some cases for testing purposes, but it is strongly discouraged for production use because it does not actually perform any real trust processing and will allow connecting to unintended or malicious peers.AggregateTrustManager
-- Allows you to combine multiple other trust managers in the course of determining whether to trust a presented certificate chain. For example, you may use this to automatically trust certificates signed by an issuer in the JVM'scacerts
file or in an explicitly specified alternative trust store file, but to fall back to interactively prompting the user for certificates not trusted by one of the previous two methods.
Certificate Hostname Validation
Trust managers can be used to ensure that a certificate chain presented by a peer originally came from a trusted source, but that doesn't necessarily mean that the peer system is the one you intend it to be. It's not at all difficult for malicious users and applications to obtain a certificate that is signed by a CA in the JVM's default set of trusted issuers. However, any certificate signed by one of those trusted issuers will include information in a subject alternative name extension that specifies the hostnames (or at least domain names) and IP addresses for systems with which that certificate is allowed to be used, and those issues are careful to verify that they only issue certificates to systems that are legitimately associated with those systems. So while a malicious user may be able to easily get a certificate from a trusted issuer, it should not be possible for them to get a certificate with a subject alternative name extension containing addresses they don't legitimately have the right to use.
Because of this, it's very important that clients not only verify that the server's certificate comes from a trusted source, but also that it's allowed to be used by that server system. This additional level of validation can help thwart attacks that rely on DNS hijacking or other methods of diverting communication away from the intended recipient to one that an attacker controls instead. The LDAP SDK does not perform this validation by default because there are unfortunately too many cases in which clients (especially those used in testing and development environments) might need to interact with a server whose certificate may not have an appropriate subject alternative name extension. However, in production environments with a properly configured TLS certificate, hostname verification can be enabled by calling theLDAPConnectionOptions.setSSLSocketVerifier(com.unboundid.util.ssl.SSLSocketVerifier)
method with an instance of theHostNameSSLSocketVerifier
. Alternatively, you can set thecom.unboundid.ldap.sdk. LDAPConnectionOptions.defaultVerifyCertificateHostnames
system property with a value of "true
" to enable this validation by default.
Examples
The following example demonstrates the process for establish a secure client connection. It relies on the LDAP SDK's default configuration for selecting TLS protocols and cipher suites, and does not use a key manager. It uses an aggregate trust manager to automatically trust any certificates signed by one of the JVM's default trusted issuers or an issuer in an explicitly specified key store file, and it enables host name validation.
AggregateTrustManager trustManager = new AggregateTrustManager(false, JVMDefaultTrustManager.getInstance(), new TrustStoreTrustManager(trustStorePath, trustStorePIN, "PKCS12", true)); SSLUtil sslUtil = new SSLUtil(trustManager); LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions(); connectionOptions.setSSLSocketVerifier( new HostNameSSLSocketVerifier(true)); try (LDAPConnection connection = new LDAPConnection( sslUtil.createSSLSocketFactory(), connectionOptions, serverAddress, serverLDAPSPort)) { // Use the connection here. RootDSE rootDSE = connection.getRootDSE(); }
The above example establishes an LDAPS connection that is secured by TLS as soon as it is created. The following example shows the process needed to use the StartTLS extended operation to secure an already-established non-secure connection:
AggregateTrustManager trustManager = new AggregateTrustManager(false, JVMDefaultTrustManager.getInstance(), new TrustStoreTrustManager(trustStorePath, trustStorePIN, "PKCS12", true)); SSLUtil sslUtil = new SSLUtil(trustManager); LDAPConnectionOptions connectionOptions = new LDAPConnectionOptions(); connectionOptions.setSSLSocketVerifier( new HostNameSSLSocketVerifier(true)); try (LDAPConnection connection = new LDAPConnection( connectionOptions, serverAddress, serverLDAPPort)) { // Use the StartTLS extended operation to secure the connection. ExtendedResult startTLSResult; try { startTLSResult = connection.processExtendedOperation( new StartTLSExtendedRequest( sslUtil.createSSLSocketFactory())); } catch (LDAPException e) { Debug.debugException(e); startTLSResult = new ExtendedResult(e); } LDAPTestUtils.assertResultCodeEquals(startTLSResult, ResultCode.SUCCESS); // Use the connection here. RootDSE rootDSE = connection.getRootDSE(); }
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
PROPERTY_DEFAULT_SSL_PROTOCOL
The name of a system property (com.unboundid.util.SSLUtil.defaultSSLProtocol) that can be used to specify the initial value for the default SSL protocol that should be used.static java.lang.String
PROPERTY_ENABLED_SSL_CIPHER_SUITES
The name of a system property (com.unboundid.util.SSLUtil.enabledSSLCipherSuites) that can be used to provide the initial set of enabled SSL cipher suites that should be used, as a comma-delimited list.static java.lang.String
PROPERTY_ENABLED_SSL_PROTOCOLS
The name of a system property (com.unboundid.util.SSLUtil.enabledSSLProtocols) that can be used to provide the initial set of enabled SSL protocols that should be used, as a comma-delimited list.static java.lang.String
SSL_PROTOCOL_SSL_2_HELLO
The name of the SSL protocol that can be used to request SSLv2Hello.static java.lang.String
SSL_PROTOCOL_SSL_3
The name of the SSL protocol that can be used to request SSLv3.static java.lang.String
SSL_PROTOCOL_TLS_1
The name of the SSL protocol that can be used to request TLSv1.static java.lang.String
SSL_PROTOCOL_TLS_1_1
The name of the SSL protocol that can be used to request TLSv1.1.static java.lang.String
SSL_PROTOCOL_TLS_1_2
The name of the SSL protocol that can be used to request TLSv1.2.static java.lang.String
SSL_PROTOCOL_TLS_1_3
The name of the SSL protocol that can be used to request TLSv1.3.
-
Constructor Summary
Constructors Constructor Description SSLUtil()
Creates a new SSLUtil instance that will not have a custom key manager or trust manager.SSLUtil(javax.net.ssl.KeyManager[] keyManagers, javax.net.ssl.TrustManager[] trustManagers)
Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.SSLUtil(javax.net.ssl.KeyManager keyManager, javax.net.ssl.TrustManager trustManager)
Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.SSLUtil(javax.net.ssl.TrustManager trustManager)
Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client.SSLUtil(javax.net.ssl.TrustManager[] trustManagers)
Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static void
applyEnabledSSLCipherSuites(java.net.Socket socket)
Updates the provided socket to apply the appropriate set of enabled SSL cipher suites.static void
applyEnabledSSLProtocols(java.net.Socket socket)
Updates the provided socket to apply the appropriate set of enabled SSL protocols.static java.lang.String
certificateToString(java.security.cert.X509Certificate certificate)
Creates a string representation of the provided certificate.static void
certificateToString(java.security.cert.X509Certificate certificate, java.lang.StringBuilder buffer)
Appends a string representation of the provided certificate to the given buffer.javax.net.ssl.SSLContext
createSSLContext()
Creates an initialized SSL context created with the configured key and trust managers.javax.net.ssl.SSLContext
createSSLContext(java.lang.String protocol)
Creates an initialized SSL context created with the configured key and trust managers.javax.net.ssl.SSLContext
createSSLContext(java.lang.String protocol, java.lang.String provider)
Creates an initialized SSL context created with the configured key and trust managers.javax.net.ssl.SSLServerSocketFactory
createSSLServerSocketFactory()
Creates an SSL server socket factory using the configured key and trust manager providers.javax.net.ssl.SSLServerSocketFactory
createSSLServerSocketFactory(java.lang.String protocol)
Creates an SSL server socket factory using the configured key and trust manager providers.javax.net.ssl.SSLServerSocketFactory
createSSLServerSocketFactory(java.lang.String protocol, java.lang.String provider)
Creates an SSL server socket factory using the configured key and trust manager providers.javax.net.ssl.SSLSocketFactory
createSSLSocketFactory()
Creates an SSL socket factory using the configured key and trust manager providers.javax.net.ssl.SSLSocketFactory
createSSLSocketFactory(java.lang.String protocol)
Creates an SSL socket factory with the configured key and trust managers.javax.net.ssl.SSLSocketFactory
createSSLSocketFactory(java.lang.String protocol, java.lang.String provider)
Creates an SSL socket factory with the configured key and trust managers.static java.lang.String
getDefaultSSLProtocol()
Retrieves the SSL protocol string that will be used by calls tocreateSSLContext()
that do not explicitly specify which protocol to use.static java.util.Set<java.lang.String>
getEnabledSSLCipherSuites()
Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.static java.util.Set<java.lang.String>
getEnabledSSLProtocols()
Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.javax.net.ssl.KeyManager[]
getKeyManagers()
Retrieves the set of key managers configured for use by this class, if any.javax.net.ssl.TrustManager[]
getTrustManagers()
Retrieves the set of trust managers configured for use by this class, if any.static void
setDefaultSSLProtocol(java.lang.String defaultSSLProtocol)
Specifies the SSL protocol string that will be used by calls tocreateSSLContext()
that do not explicitly specify which protocol to use.static void
setEnabledSSLCipherSuites(java.util.Collection<java.lang.String> enabledSSLCipherSuites)
Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK.static void
setEnabledSSLProtocols(java.util.Collection<java.lang.String> enabledSSLProtocols)
Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK.
-
-
-
Field Detail
-
PROPERTY_DEFAULT_SSL_PROTOCOL
@NotNull public static final java.lang.String PROPERTY_DEFAULT_SSL_PROTOCOL
The name of a system property (com.unboundid.util.SSLUtil.defaultSSLProtocol) that can be used to specify the initial value for the default SSL protocol that should be used. If this is not set, then the default SSL protocol will be dynamically determined. This can be overridden via thesetDefaultSSLProtocol(String)
method.- See Also:
- Constant Field Values
-
PROPERTY_ENABLED_SSL_PROTOCOLS
@NotNull public static final java.lang.String PROPERTY_ENABLED_SSL_PROTOCOLS
The name of a system property (com.unboundid.util.SSLUtil.enabledSSLProtocols) that can be used to provide the initial set of enabled SSL protocols that should be used, as a comma-delimited list. If this is not set, then the enabled SSL protocols will be dynamically determined. This can be overridden via thesetEnabledSSLProtocols(Collection)
method.- See Also:
- Constant Field Values
-
PROPERTY_ENABLED_SSL_CIPHER_SUITES
@NotNull public static final java.lang.String PROPERTY_ENABLED_SSL_CIPHER_SUITES
The name of a system property (com.unboundid.util.SSLUtil.enabledSSLCipherSuites) that can be used to provide the initial set of enabled SSL cipher suites that should be used, as a comma-delimited list. If this is not set, then the enabled SSL cipher suites will be dynamically determined using theTLSCipherSuiteSelector
. This can be overridden via thesetEnabledSSLCipherSuites(Collection)
method.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_TLS_1_3
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_3
The name of the SSL protocol that can be used to request TLSv1.3.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_TLS_1_2
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_2
The name of the SSL protocol that can be used to request TLSv1.2.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_TLS_1_1
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1_1
The name of the SSL protocol that can be used to request TLSv1.1.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_TLS_1
@NotNull public static final java.lang.String SSL_PROTOCOL_TLS_1
The name of the SSL protocol that can be used to request TLSv1.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_SSL_3
@NotNull public static final java.lang.String SSL_PROTOCOL_SSL_3
The name of the SSL protocol that can be used to request SSLv3.- See Also:
- Constant Field Values
-
SSL_PROTOCOL_SSL_2_HELLO
@NotNull public static final java.lang.String SSL_PROTOCOL_SSL_2_HELLO
The name of the SSL protocol that can be used to request SSLv2Hello.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
SSLUtil
public SSLUtil()
Creates a new SSLUtil instance that will not have a custom key manager or trust manager. It will not be able to provide a certificate to the server if one is requested, and it will only trust certificates signed by a predefined set of authorities.
-
SSLUtil
public SSLUtil(@Nullable javax.net.ssl.TrustManager trustManager)
Creates a new SSLUtil instance that will use the provided trust manager to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.- Parameters:
trustManager
- The trust manager to use to determine whether to trust server certificates presented to the client. It may benull
if the default set of trust managers should be used.
-
SSLUtil
public SSLUtil(@Nullable javax.net.ssl.TrustManager[] trustManagers)
Creates a new SSLUtil instance that will use the provided trust managers to determine whether to trust server certificates presented to the client. It will not be able to provide a certificate to the server if one is requested.- Parameters:
trustManagers
- The set of trust managers to use to determine whether to trust server certificates presented to the client. It may benull
or empty if the default set of trust managers should be used.
-
SSLUtil
public SSLUtil(@Nullable javax.net.ssl.KeyManager keyManager, @Nullable javax.net.ssl.TrustManager trustManager)
Creates a new SSLUtil instance that will use the provided key manager to obtain certificates to present to the server, and the provided trust manager to determine whether to trust server certificates presented to the client.- Parameters:
keyManager
- The key manager to use to obtain certificates to present to the server if requested. It may benull
if no client certificates will be required or should be provided.trustManager
- The trust manager to use to determine whether to trust server certificates presented to the client. It may benull
if the default set of trust managers should be used.
-
SSLUtil
public SSLUtil(@Nullable javax.net.ssl.KeyManager[] keyManagers, @Nullable javax.net.ssl.TrustManager[] trustManagers)
Creates a new SSLUtil instance that will use the provided key managers to obtain certificates to present to the server, and the provided trust managers to determine whether to trust server certificates presented to the client.- Parameters:
keyManagers
- The set of key managers to use to obtain certificates to present to the server if requested. It may benull
or empty if no client certificates will be required or should be provided.trustManagers
- The set of trust managers to use to determine whether to trust server certificates presented to the client. It may benull
or empty if the default set of trust managers should be used.
-
-
Method Detail
-
getKeyManagers
@Nullable public javax.net.ssl.KeyManager[] getKeyManagers()
Retrieves the set of key managers configured for use by this class, if any.- Returns:
- The set of key managers configured for use by this class, or
null
if none were provided.
-
getTrustManagers
@Nullable public javax.net.ssl.TrustManager[] getTrustManagers()
Retrieves the set of trust managers configured for use by this class, if any.- Returns:
- The set of trust managers configured for use by this class, or
null
if none were provided.
-
createSSLContext
@NotNull public javax.net.ssl.SSLContext createSSLContext() throws java.security.GeneralSecurityException
Creates an initialized SSL context created with the configured key and trust managers. It will use the protocol returned by thegetDefaultSSLProtocol()
method and the JVM-default provider.- Returns:
- The created SSL context.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL context.
-
createSSLContext
@NotNull public javax.net.ssl.SSLContext createSSLContext(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
Creates an initialized SSL context created with the configured key and trust managers. It will use a default provider.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.- Returns:
- The created SSL context.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL context.
-
createSSLContext
@NotNull public javax.net.ssl.SSLContext createSSLContext(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
Creates an initialized SSL context created with the configured key and trust managers.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- Returns:
- The created SSL context.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL context.
-
createSSLSocketFactory
@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory() throws java.security.GeneralSecurityException
Creates an SSL socket factory using the configured key and trust manager providers. It will use the protocol returned by thegetDefaultSSLProtocol()
method and the JVM-default provider.- Returns:
- The created SSL socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL socket factory.
-
createSSLSocketFactory
@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
Creates an SSL socket factory with the configured key and trust managers. It will use the default provider.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.- Returns:
- The created SSL socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL socket factory.
-
createSSLSocketFactory
@NotNull public javax.net.ssl.SSLSocketFactory createSSLSocketFactory(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
Creates an SSL socket factory with the configured key and trust managers.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- Returns:
- The created SSL socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL socket factory.
-
createSSLServerSocketFactory
@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory() throws java.security.GeneralSecurityException
Creates an SSL server socket factory using the configured key and trust manager providers. It will use the protocol returned by thegetDefaultSSLProtocol()
method and the JVM-default provider.- Returns:
- The created SSL server socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL server socket factory.
-
createSSLServerSocketFactory
@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull java.lang.String protocol) throws java.security.GeneralSecurityException
Creates an SSL server socket factory using the configured key and trust manager providers. It will use the JVM-default provider.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.- Returns:
- The created SSL server socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL server socket factory.
-
createSSLServerSocketFactory
@NotNull public javax.net.ssl.SSLServerSocketFactory createSSLServerSocketFactory(@NotNull java.lang.String protocol, @NotNull java.lang.String provider) throws java.security.GeneralSecurityException
Creates an SSL server socket factory using the configured key and trust manager providers.- Parameters:
protocol
- The SSL protocol to use. The Java Secure Socket Extension (JSSE) Reference Guide provides a list of the supported protocols, but commonly used values are "TLSv1.3", "TLSv1.2", "TLSv1.1", and "TLSv1". This must not benull
.provider
- The name of the provider to use for cryptographic operations. It must not benull
.- Returns:
- The created SSL server socket factory.
- Throws:
java.security.GeneralSecurityException
- If a problem occurs while creating or initializing the SSL server socket factory.
-
getDefaultSSLProtocol
@NotNull public static java.lang.String getDefaultSSLProtocol()
Retrieves the SSL protocol string that will be used by calls tocreateSSLContext()
that do not explicitly specify which protocol to use.- Returns:
- The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use.
-
setDefaultSSLProtocol
public static void setDefaultSSLProtocol(@NotNull java.lang.String defaultSSLProtocol)
Specifies the SSL protocol string that will be used by calls tocreateSSLContext()
that do not explicitly specify which protocol to use.- Parameters:
defaultSSLProtocol
- The SSL protocol string that will be used by calls to create an SSL context that do not explicitly specify which protocol to use. It must not benull
.
-
getEnabledSSLProtocols
@NotNull public static java.util.Set<java.lang.String> getEnabledSSLProtocols()
Retrieves the set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.- Returns:
- The set of SSL protocols that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
-
setEnabledSSLProtocols
public static void setEnabledSSLProtocols(@Nullable java.util.Collection<java.lang.String> enabledSSLProtocols)
Specifies the set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. When creating an SSL socket, theSSLSocket.getSupportedProtocols
method will be used to determine which protocols are supported for that socket, and then theSSLSocket.setEnabledProtocols
method will be used to enable those protocols which are listed as both supported by the socket and included in this set. If the provided set isnull
or empty, then the default set of enabled protocols will be used.- Parameters:
enabledSSLProtocols
- The set of SSL protocols that will be enabled for use for SSL sockets created within the LDAP SDK. It may benull
or empty to indicate that the JDK-default set of enabled protocols should be used for the socket.
-
applyEnabledSSLProtocols
public static void applyEnabledSSLProtocols(@NotNull java.net.Socket socket) throws LDAPException
Updates the provided socket to apply the appropriate set of enabled SSL protocols. This will only have any effect for sockets that are instances ofjavax.net.ssl.SSLSocket
, but it is safe to call for any kind ofjava.net.Socket
. This should be called before attempting any communication over the socket.- Parameters:
socket
- The socket on which to apply the configured set of enabled SSL protocols.- Throws:
LDAPException
- IfgetEnabledSSLProtocols()
returns a non-empty set but none of the values in that set are supported by the socket.
-
getEnabledSSLCipherSuites
@NotNull public static java.util.Set<java.lang.String> getEnabledSSLCipherSuites()
Retrieves the set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.- Returns:
- The set of SSL cipher suites that will be enabled for use, if available, for SSL sockets created within the LDAP SDK.
-
setEnabledSSLCipherSuites
public static void setEnabledSSLCipherSuites(@Nullable java.util.Collection<java.lang.String> enabledSSLCipherSuites)
Specifies the set of SSL cipher suites that will be enabled for SSL sockets created within the LDAP SDK. When creating an SSL socket, theSSLSocket.getSupportedCipherSuites
method will be used to determine which cipher suites are supported for that socket, and then theSSLSocket.setEnabledCipherSuites
method will be used to enable those suites which are listed as both supported by the socket and included in this set. If the provided set isnull
or empty, then the default set of enabled cipher suites will be used.- Parameters:
enabledSSLCipherSuites
- The set of SSL cipher suites that will be enabled for use for SSL sockets created within the LDAP SDK. It may benull
or empty to indicate that the JDK-default set of enabled cipher suites should be used for the socket.
-
applyEnabledSSLCipherSuites
public static void applyEnabledSSLCipherSuites(@NotNull java.net.Socket socket) throws LDAPException
Updates the provided socket to apply the appropriate set of enabled SSL cipher suites. This will only have any effect for sockets that are instances ofjavax.net.ssl.SSLSocket
, but it is safe to call for any kind ofjava.net.Socket
. This should be called before attempting any communication over the socket.- Parameters:
socket
- The socket on which to apply the configured set of enabled SSL cipher suites.- Throws:
LDAPException
- IfgetEnabledSSLCipherSuites()
returns a non-empty set but none of the values in that set are supported by the socket.
-
certificateToString
@NotNull public static java.lang.String certificateToString(@NotNull java.security.cert.X509Certificate certificate)
Creates a string representation of the provided certificate.- Parameters:
certificate
- The certificate for which to generate the string representation. It must not benull
.- Returns:
- A string representation of the provided certificate.
-
certificateToString
public static void certificateToString(@NotNull java.security.cert.X509Certificate certificate, @NotNull java.lang.StringBuilder buffer)
Appends a string representation of the provided certificate to the given buffer.- Parameters:
certificate
- The certificate for which to generate the string representation. It must not benull
.buffer
- The buffer to which to append the string representation.
-
-