Package org.conscrypt
Class Conscrypt
java.lang.Object
org.conscrypt.Conscrypt
Core API for creating and configuring all Conscrypt types.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
static class
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic void
Checks that the Conscrypt support is available for the system.static byte[]
exportKeyingMaterial
(SSLEngine engine, String label, byte[] context, int length) Exports a value derived from the TLS master secret as described in RFC 5705.static byte[]
exportKeyingMaterial
(SSLSocket socket, String label, byte[] context, int length) Exports a value derived from the TLS master secret as described in RFC 5705.static String
getApplicationProtocol
(SSLEngine engine) Returns the ALPN protocol agreed upon by client and server.static String
getApplicationProtocol
(SSLSocket socket) Returns the ALPN protocol agreed upon by client and server.static String[]
getApplicationProtocols
(SSLEngine engine) Gets the application-layer protocols (ALPN) in prioritization order.static String[]
getApplicationProtocols
(SSLSocket socket) Gets the application-layer protocols (ALPN) in prioritization order.static byte[]
getChannelId
(SSLEngine engine) Gets the TLS Channel ID for the given server-side engine.static byte[]
getChannelId
(SSLSocket socket) Gets the TLS Channel ID for the given server-side socket.static ConscryptHostnameVerifier
getDefaultHostnameVerifier
(TrustManager trustManager) Returns the currently-set default hostname verifier for Conscrypt trust managers.static X509TrustManager
Gets the default X.509 trust manager.static String
getHostname
(SSLEngine engine) Returns either the hostname supplied during socket creation or viasetHostname(SSLEngine, String)
.static String
getHostname
(SSLSocket socket) Returns either the hostname supplied during socket creation or viasetHostname(SSLSocket, String)
.static String
getHostnameOrIP
(SSLSocket socket) This method attempts to create a textual representation of the peer host or IP.static ConscryptHostnameVerifier
getHostnameVerifier
(TrustManager trustManager) Returns the currently-set hostname verifier for the given trust manager.static byte[]
getTlsUnique
(SSLEngine engine) Returns the tls-unique channel binding value for this connection, per RFC 5929.static byte[]
getTlsUnique
(SSLSocket socket) Returns the tls-unique channel binding value for this connection, per RFC 5929.static boolean
Returnstrue
if the Conscrypt native library has been successfully loaded.static boolean
isConscrypt
(Provider provider) Indicates whether the givenProvider
was created by this distribution of Conscrypt.static boolean
isConscrypt
(SSLContext context) Indicates whether the givenSSLContext
was created by this distribution of Conscrypt.static boolean
isConscrypt
(SSLEngine engine) Indicates whether the givenSSLEngine
was created by this distribution of Conscrypt.static boolean
isConscrypt
(SSLServerSocketFactory factory) Indicates whether the givenSSLServerSocketFactory
was created by this distribution of Conscrypt.static boolean
isConscrypt
(SSLSocket socket) Indicates whether the givenSSLSocket
was created by this distribution of Conscrypt.static boolean
isConscrypt
(SSLSocketFactory factory) Indicates whether the givenSSLSocketFactory
was created by this distribution of Conscrypt.static boolean
isConscrypt
(TrustManager trustManager) Indicates whether the givenTrustManager
was created by this distribution of Conscrypt.static int
Returns the maximum length (in bytes) of an encrypted packet.static int
maxSealOverhead
(SSLEngine engine) Returns the maximum overhead, in bytes, of sealing a record with SSL.static SSLContextSpi
Constructs a new instance of the preferredSSLContextSpi
.static Provider
Constructs a newProvider
with the default name.static Provider
newProvider
(String providerName) Deprecated.static Conscrypt.ProviderBuilder
static void
setApplicationProtocols
(SSLEngine engine, String[] protocols) Sets the application-layer protocols (ALPN) in prioritization order.static void
setApplicationProtocols
(SSLSocket socket, String[] protocols) Sets the application-layer protocols (ALPN) in prioritization order.static void
setApplicationProtocolSelector
(SSLEngine engine, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector.static void
setApplicationProtocolSelector
(SSLSocket socket, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector.static void
setBufferAllocator
(SSLEngine engine, BufferAllocator bufferAllocator) Provides the given engine with the provided bufferAllocator.static void
setBufferAllocator
(SSLSocket socket, BufferAllocator bufferAllocator) Provides the given socket with the provided bufferAllocator.static void
setChannelIdEnabled
(SSLEngine engine, boolean enabled) Enables/disables TLS Channel ID for the given server-side engine.static void
setChannelIdEnabled
(SSLSocket socket, boolean enabled) Enables/disables TLS Channel ID for the given server-side socket.static void
setChannelIdPrivateKey
(SSLEngine engine, PrivateKey privateKey) Sets thePrivateKey
to be used for TLS Channel ID by this client engine.static void
setChannelIdPrivateKey
(SSLSocket socket, PrivateKey privateKey) Sets thePrivateKey
to be used for TLS Channel ID by this client socket.static void
setClientSessionCache
(SSLContext context, SSLClientSessionCache cache) Sets the client-side persistent cache to be used by the context.static void
setDefaultBufferAllocator
(BufferAllocator bufferAllocator) Configures the defaultBufferAllocator
to be used by all futureSSLEngine
instances from this provider.static void
Set the default hostname verifier that will be used for HTTPS endpoint identification by Conscrypt trust managers.static void
setHandshakeListener
(SSLEngine engine, HandshakeListener handshakeListener) Sets a listener on the given engine for completion of the TLS handshakestatic void
setHostname
(SSLEngine engine, String hostname) This method enables Server Name Indication (SNI) and overrides the hostname supplied during engine creation.static void
setHostname
(SSLSocket socket, String hostname) This method enables Server Name Indication (SNI) and overrides the hostname supplied during socket creation.static void
setHostnameVerifier
(TrustManager trustManager, ConscryptHostnameVerifier verifier) Set the hostname verifier that will be used for HTTPS endpoint identification by the given trust manager.static void
setServerSessionCache
(SSLContext context, SSLServerSessionCache cache) Sets the server-side persistent cache to be used by the context.static void
setUseEngineSocket
(SSLServerSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given server socket factory instance.static void
setUseEngineSocket
(SSLSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given socket factory instance.static void
setUseEngineSocketByDefault
(boolean useEngineSocket) Configures the default socket to be created for all socket factory instances.static void
setUseSessionTickets
(SSLEngine engine, boolean useSessionTickets) This method enables session ticket support.static void
setUseSessionTickets
(SSLSocket socket, boolean useSessionTickets) This method enables session ticket support.private static AbstractConscryptEngine
toConscrypt
(SSLEngine engine) private static OpenSSLServerSocketFactoryImpl
toConscrypt
(SSLServerSocketFactory factory) private static AbstractConscryptSocket
toConscrypt
(SSLSocket socket) private static OpenSSLSocketFactoryImpl
toConscrypt
(SSLSocketFactory factory) private static TrustManagerImpl
toConscrypt
(TrustManager trustManager) static SSLEngineResult
unwrap
(SSLEngine engine, ByteBuffer[] srcs, int srcsOffset, int srcsLength, ByteBuffer[] dsts, int dstsOffset, int dstsLength) Exteneded unwrap method for multiple source and destination buffers.static SSLEngineResult
unwrap
(SSLEngine engine, ByteBuffer[] srcs, ByteBuffer[] dsts) Extended unwrap method for multiple source and destination buffers.static Conscrypt.Version
version()
Returns the version of this distribution of Conscrypt.static ConscryptHostnameVerifier
wrapHostnameVerifier
(HostnameVerifier verifier) Wraps the HttpsURLConnection.HostnameVerifier into a ConscryptHostnameVerifier
-
Field Details
-
VERSION
-
-
Constructor Details
-
Conscrypt
private Conscrypt()
-
-
Method Details
-
isAvailable
public static boolean isAvailable()Returnstrue
if the Conscrypt native library has been successfully loaded. -
version
Returns the version of this distribution of Conscrypt. If version information is unavailable, returnsnull
. -
checkAvailability
public static void checkAvailability()Checks that the Conscrypt support is available for the system.- Throws:
UnsatisfiedLinkError
- if unavailable
-
isConscrypt
Indicates whether the givenProvider
was created by this distribution of Conscrypt. -
newProvider
Constructs a newProvider
with the default name. -
newProvider
Deprecated.UsenewProviderBuilder()
instead.Constructs a newProvider
with the given name. -
newProviderBuilder
-
maxEncryptedPacketLength
public static int maxEncryptedPacketLength()Returns the maximum length (in bytes) of an encrypted packet. -
getDefaultX509TrustManager
@ExperimentalApi public static X509TrustManager getDefaultX509TrustManager() throws KeyManagementExceptionGets the default X.509 trust manager.- Throws:
KeyManagementException
-
isConscrypt
Indicates whether the givenSSLContext
was created by this distribution of Conscrypt. -
newPreferredSSLContextSpi
Constructs a new instance of the preferredSSLContextSpi
. -
setClientSessionCache
Sets the client-side persistent cache to be used by the context. -
setServerSessionCache
Sets the server-side persistent cache to be used by the context. -
isConscrypt
Indicates whether the givenSSLSocketFactory
was created by this distribution of Conscrypt. -
toConscrypt
-
setUseEngineSocketByDefault
Configures the default socket to be created for all socket factory instances. -
setUseEngineSocket
@ExperimentalApi public static void setUseEngineSocket(SSLSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given socket factory instance. -
isConscrypt
Indicates whether the givenSSLServerSocketFactory
was created by this distribution of Conscrypt. -
toConscrypt
-
setUseEngineSocket
@ExperimentalApi public static void setUseEngineSocket(SSLServerSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given server socket factory instance. -
isConscrypt
Indicates whether the givenSSLSocket
was created by this distribution of Conscrypt. -
toConscrypt
-
setHostname
This method enables Server Name Indication (SNI) and overrides the hostname supplied during socket creation. If the hostname is not a valid SNI hostname, the SNI extension will be omitted from the handshake.- Parameters:
socket
- the sockethostname
- the desired SNI hostname, or null to disable
-
getHostname
Returns either the hostname supplied during socket creation or viasetHostname(SSLSocket, String)
. No DNS resolution is attempted before returning the hostname. -
getHostnameOrIP
This method attempts to create a textual representation of the peer host or IP. Does not perform a reverse DNS lookup. This is typically used during session creation. -
setUseSessionTickets
This method enables session ticket support.- Parameters:
socket
- the socketuseSessionTickets
- True to enable session tickets
-
setChannelIdEnabled
Enables/disables TLS Channel ID for the given server-side socket.This method needs to be invoked before the handshake starts.
- Parameters:
socket
- the socketenabled
- Whether to enable channel ID.- Throws:
IllegalStateException
- if this is a client socket or if the handshake has already started.
-
getChannelId
Gets the TLS Channel ID for the given server-side socket. Channel ID is only available once the handshake completes.- Parameters:
socket
- the socket- Returns:
- channel ID or
null
if not available. - Throws:
IllegalStateException
- if this is a client socket or if the handshake has not yet completed.SSLException
- if channel ID is available but could not be obtained.
-
setChannelIdPrivateKey
Sets thePrivateKey
to be used for TLS Channel ID by this client socket.This method needs to be invoked before the handshake starts.
- Parameters:
socket
- the socketprivateKey
- private key (enables TLS Channel ID) ornull
for no key (disables TLS Channel ID). The private key must be an Elliptic Curve (EC) key based on the NIST P-256 curve (aka SECG secp256r1 or ANSI X9.62 prime256v1).- Throws:
IllegalStateException
- if this is a server socket or if the handshake has already started.
-
getApplicationProtocol
Returns the ALPN protocol agreed upon by client and server.- Parameters:
socket
- the socket- Returns:
- the selected protocol or
null
if no protocol was agreed upon.
-
setApplicationProtocolSelector
public static void setApplicationProtocolSelector(SSLSocket socket, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector. If provided, this will override the list of protocols set bysetApplicationProtocols(SSLSocket, String[])
.- Parameters:
socket
- the socketselector
- the ALPN protocol selector
-
setApplicationProtocols
Sets the application-layer protocols (ALPN) in prioritization order.- Parameters:
socket
- the socket being configuredprotocols
- the protocols in descending order of preference. If empty, no protocol indications will be used. This array will be copied.- Throws:
IllegalArgumentException
- - if protocols is null, or if any element in a non-empty array is null or an empty (zero-length) string
-
getApplicationProtocols
Gets the application-layer protocols (ALPN) in prioritization order.- Parameters:
socket
- the socket- Returns:
- the protocols in descending order of preference, or an empty array if protocol indications are not being used. Always returns a new array.
-
getTlsUnique
Returns the tls-unique channel binding value for this connection, per RFC 5929. This will returnnull
if there is no such value available, such as if the handshake has not yet completed or this connection is closed. -
exportKeyingMaterial
public static byte[] exportKeyingMaterial(SSLSocket socket, String label, byte[] context, int length) throws SSLException Exports a value derived from the TLS master secret as described in RFC 5705.- Parameters:
label
- the label to use in calculating the exported value. This must be an ASCII-only string.context
- the application-specific context value to use in calculating the exported value. This may benull
to use no application context, which is treated differently than an empty byte array.length
- the number of bytes of keying material to return.- Returns:
- a value of the specified length, or
null
if the handshake has not yet completed or the connection has been closed. - Throws:
SSLException
- if the value could not be exported.
-
isConscrypt
Indicates whether the givenSSLEngine
was created by this distribution of Conscrypt. -
toConscrypt
-
setBufferAllocator
@ExperimentalApi public static void setBufferAllocator(SSLEngine engine, BufferAllocator bufferAllocator) Provides the given engine with the provided bufferAllocator.- Throws:
IllegalArgumentException
- if the provided engine is not a Conscrypt engine.IllegalStateException
- if the provided engine has already begun its handshake.
-
setBufferAllocator
@ExperimentalApi public static void setBufferAllocator(SSLSocket socket, BufferAllocator bufferAllocator) Provides the given socket with the provided bufferAllocator. If the given socket is a Conscrypt socket but does not use buffer allocators, this method does nothing.- Throws:
IllegalArgumentException
- if the provided socket is not a Conscrypt socket.IllegalStateException
- if the provided socket has already begun its handshake.
-
setDefaultBufferAllocator
Configures the defaultBufferAllocator
to be used by all futureSSLEngine
instances from this provider. -
setHostname
This method enables Server Name Indication (SNI) and overrides the hostname supplied during engine creation.- Parameters:
engine
- the enginehostname
- the desired SNI hostname, ornull
to disable
-
getHostname
Returns either the hostname supplied during socket creation or viasetHostname(SSLEngine, String)
. No DNS resolution is attempted before returning the hostname. -
maxSealOverhead
Returns the maximum overhead, in bytes, of sealing a record with SSL. -
setHandshakeListener
Sets a listener on the given engine for completion of the TLS handshake -
setChannelIdEnabled
Enables/disables TLS Channel ID for the given server-side engine.This method needs to be invoked before the handshake starts.
- Parameters:
engine
- the engineenabled
- Whether to enable channel ID.- Throws:
IllegalStateException
- if this is a client engine or if the handshake has already started.
-
getChannelId
Gets the TLS Channel ID for the given server-side engine. Channel ID is only available once the handshake completes.- Parameters:
engine
- the engine- Returns:
- channel ID or
null
if not available. - Throws:
IllegalStateException
- if this is a client engine or if the handshake has not yet completed.SSLException
- if channel ID is available but could not be obtained.
-
setChannelIdPrivateKey
Sets thePrivateKey
to be used for TLS Channel ID by this client engine.This method needs to be invoked before the handshake starts.
- Parameters:
engine
- the engineprivateKey
- private key (enables TLS Channel ID) ornull
for no key (disables TLS Channel ID). The private key must be an Elliptic Curve (EC) key based on the NIST P-256 curve (aka SECG secp256r1 or ANSI X9.62 prime256v1).- Throws:
IllegalStateException
- if this is a server engine or if the handshake has already started.
-
unwrap
public static SSLEngineResult unwrap(SSLEngine engine, ByteBuffer[] srcs, ByteBuffer[] dsts) throws SSLException Extended unwrap method for multiple source and destination buffers.- Parameters:
engine
- the target engine for the unwrapsrcs
- the source buffersdsts
- the destination buffers- Returns:
- the result of the unwrap operation
- Throws:
SSLException
- thrown if an SSL error occurred
-
unwrap
public static SSLEngineResult unwrap(SSLEngine engine, ByteBuffer[] srcs, int srcsOffset, int srcsLength, ByteBuffer[] dsts, int dstsOffset, int dstsLength) throws SSLException Exteneded unwrap method for multiple source and destination buffers.- Parameters:
engine
- the target engine for the unwrap.srcs
- the source bufferssrcsOffset
- the offset in thesrcs
array of the first source buffersrcsLength
- the number of source buffers starting atsrcsOffset
dsts
- the destination buffersdstsOffset
- the offset in thedsts
array of the first destination bufferdstsLength
- the number of destination buffers starting atdstsOffset
- Returns:
- the result of the unwrap operation
- Throws:
SSLException
- thrown if an SSL error occurred
-
setUseSessionTickets
This method enables session ticket support.- Parameters:
engine
- the engineuseSessionTickets
- True to enable session tickets
-
setApplicationProtocols
Sets the application-layer protocols (ALPN) in prioritization order.- Parameters:
engine
- the engine being configuredprotocols
- the protocols in descending order of preference. If empty, no protocol indications will be used. This array will be copied.- Throws:
IllegalArgumentException
- - if protocols is null, or if any element in a non-empty array is null or an empty (zero-length) string
-
getApplicationProtocols
Gets the application-layer protocols (ALPN) in prioritization order.- Parameters:
engine
- the engine- Returns:
- the protocols in descending order of preference, or an empty array if protocol indications are not being used. Always returns a new array.
-
setApplicationProtocolSelector
public static void setApplicationProtocolSelector(SSLEngine engine, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector. If provided, this will override the list of protocols set bysetApplicationProtocols(SSLEngine, String[])
.- Parameters:
engine
- the engineselector
- the ALPN protocol selector
-
getApplicationProtocol
Returns the ALPN protocol agreed upon by client and server.- Parameters:
engine
- the engine- Returns:
- the selected protocol or
null
if no protocol was agreed upon.
-
getTlsUnique
Returns the tls-unique channel binding value for this connection, per RFC 5929. This will returnnull
if there is no such value available, such as if the handshake has not yet completed or this connection is closed. -
exportKeyingMaterial
public static byte[] exportKeyingMaterial(SSLEngine engine, String label, byte[] context, int length) throws SSLException Exports a value derived from the TLS master secret as described in RFC 5705.- Parameters:
label
- the label to use in calculating the exported value. This must be an ASCII-only string.context
- the application-specific context value to use in calculating the exported value. This may benull
to use no application context, which is treated differently than an empty byte array.length
- the number of bytes of keying material to return.- Returns:
- a value of the specified length, or
null
if the handshake has not yet completed or the connection has been closed. - Throws:
SSLException
- if the value could not be exported.
-
isConscrypt
Indicates whether the givenTrustManager
was created by this distribution of Conscrypt. -
toConscrypt
-
setDefaultHostnameVerifier
Set the default hostname verifier that will be used for HTTPS endpoint identification by Conscrypt trust managers. Ifnull
(the default), endpoint identification will use the default hostname verifier set inHttpsURLConnection.setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier)
. -
getDefaultHostnameVerifier
Returns the currently-set default hostname verifier for Conscrypt trust managers.- See Also:
-
setHostnameVerifier
public static void setHostnameVerifier(TrustManager trustManager, ConscryptHostnameVerifier verifier) Set the hostname verifier that will be used for HTTPS endpoint identification by the given trust manager. Ifnull
(the default), endpoint identification will use the default hostname verifier set insetDefaultHostnameVerifier(ConscryptHostnameVerifier)
.- Throws:
IllegalArgumentException
- if the provided trust manager is not a Conscrypt trust manager perisConscrypt(TrustManager)
-
getHostnameVerifier
Returns the currently-set hostname verifier for the given trust manager.- Throws:
IllegalArgumentException
- if the provided trust manager is not a Conscrypt trust manager perisConscrypt(TrustManager)
- See Also:
-
wrapHostnameVerifier
Wraps the HttpsURLConnection.HostnameVerifier into a ConscryptHostnameVerifier
-
newProviderBuilder()
instead.