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 classstatic class -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic voidChecks 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 StringgetApplicationProtocol(SSLEngine engine) Returns the ALPN protocol agreed upon by client and server.static StringgetApplicationProtocol(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 ConscryptHostnameVerifiergetDefaultHostnameVerifier(TrustManager trustManager) Returns the currently-set default hostname verifier for Conscrypt trust managers.static X509TrustManagerGets the default X.509 trust manager.static StringgetHostname(SSLEngine engine) Returns either the hostname supplied during socket creation or viasetHostname(SSLEngine, String).static StringgetHostname(SSLSocket socket) Returns either the hostname supplied during socket creation or viasetHostname(SSLSocket, String).static StringgetHostnameOrIP(SSLSocket socket) This method attempts to create a textual representation of the peer host or IP.static ConscryptHostnameVerifiergetHostnameVerifier(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 booleanReturnstrueif the Conscrypt native library has been successfully loaded.static booleanisConscrypt(Provider provider) Indicates whether the givenProviderwas created by this distribution of Conscrypt.static booleanisConscrypt(SSLContext context) Indicates whether the givenSSLContextwas created by this distribution of Conscrypt.static booleanisConscrypt(SSLEngine engine) Indicates whether the givenSSLEnginewas created by this distribution of Conscrypt.static booleanisConscrypt(SSLServerSocketFactory factory) Indicates whether the givenSSLServerSocketFactorywas created by this distribution of Conscrypt.static booleanisConscrypt(SSLSocket socket) Indicates whether the givenSSLSocketwas created by this distribution of Conscrypt.static booleanisConscrypt(SSLSocketFactory factory) Indicates whether the givenSSLSocketFactorywas created by this distribution of Conscrypt.static booleanisConscrypt(TrustManager trustManager) Indicates whether the givenTrustManagerwas created by this distribution of Conscrypt.static intReturns the maximum length (in bytes) of an encrypted packet.static intmaxSealOverhead(SSLEngine engine) Returns the maximum overhead, in bytes, of sealing a record with SSL.static SSLContextSpiConstructs a new instance of the preferredSSLContextSpi.static ProviderConstructs a newProviderwith the default name.static ProvidernewProvider(String providerName) Deprecated.static Conscrypt.ProviderBuilderstatic voidsetApplicationProtocols(SSLEngine engine, String[] protocols) Sets the application-layer protocols (ALPN) in prioritization order.static voidsetApplicationProtocols(SSLSocket socket, String[] protocols) Sets the application-layer protocols (ALPN) in prioritization order.static voidsetApplicationProtocolSelector(SSLEngine engine, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector.static voidsetApplicationProtocolSelector(SSLSocket socket, ApplicationProtocolSelector selector) Sets an application-provided ALPN protocol selector.static voidsetBufferAllocator(SSLEngine engine, BufferAllocator bufferAllocator) Provides the given engine with the provided bufferAllocator.static voidsetBufferAllocator(SSLSocket socket, BufferAllocator bufferAllocator) Provides the given socket with the provided bufferAllocator.static voidsetChannelIdEnabled(SSLEngine engine, boolean enabled) Enables/disables TLS Channel ID for the given server-side engine.static voidsetChannelIdEnabled(SSLSocket socket, boolean enabled) Enables/disables TLS Channel ID for the given server-side socket.static voidsetChannelIdPrivateKey(SSLEngine engine, PrivateKey privateKey) Sets thePrivateKeyto be used for TLS Channel ID by this client engine.static voidsetChannelIdPrivateKey(SSLSocket socket, PrivateKey privateKey) Sets thePrivateKeyto be used for TLS Channel ID by this client socket.static voidsetClientSessionCache(SSLContext context, SSLClientSessionCache cache) Sets the client-side persistent cache to be used by the context.static voidsetDefaultBufferAllocator(BufferAllocator bufferAllocator) Configures the defaultBufferAllocatorto be used by all futureSSLEngineinstances from this provider.static voidSet the default hostname verifier that will be used for HTTPS endpoint identification by Conscrypt trust managers.static voidsetHandshakeListener(SSLEngine engine, HandshakeListener handshakeListener) Sets a listener on the given engine for completion of the TLS handshakestatic voidsetHostname(SSLEngine engine, String hostname) This method enables Server Name Indication (SNI) and overrides the hostname supplied during engine creation.static voidsetHostname(SSLSocket socket, String hostname) This method enables Server Name Indication (SNI) and overrides the hostname supplied during socket creation.static voidsetHostnameVerifier(TrustManager trustManager, ConscryptHostnameVerifier verifier) Set the hostname verifier that will be used for HTTPS endpoint identification by the given trust manager.static voidsetServerSessionCache(SSLContext context, SSLServerSessionCache cache) Sets the server-side persistent cache to be used by the context.static voidsetUseEngineSocket(SSLServerSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given server socket factory instance.static voidsetUseEngineSocket(SSLSocketFactory factory, boolean useEngineSocket) Configures the socket to be created for the given socket factory instance.static voidsetUseEngineSocketByDefault(boolean useEngineSocket) Configures the default socket to be created for all socket factory instances.static voidsetUseSessionTickets(SSLEngine engine, boolean useSessionTickets) This method enables session ticket support.static voidsetUseSessionTickets(SSLSocket socket, boolean useSessionTickets) This method enables session ticket support.private static AbstractConscryptEnginetoConscrypt(SSLEngine engine) private static OpenSSLServerSocketFactoryImpltoConscrypt(SSLServerSocketFactory factory) private static AbstractConscryptSockettoConscrypt(SSLSocket socket) private static OpenSSLSocketFactoryImpltoConscrypt(SSLSocketFactory factory) private static TrustManagerImpltoConscrypt(TrustManager trustManager) static SSLEngineResultunwrap(SSLEngine engine, ByteBuffer[] srcs, int srcsOffset, int srcsLength, ByteBuffer[] dsts, int dstsOffset, int dstsLength) Exteneded unwrap method for multiple source and destination buffers.static SSLEngineResultunwrap(SSLEngine engine, ByteBuffer[] srcs, ByteBuffer[] dsts) Extended unwrap method for multiple source and destination buffers.static Conscrypt.Versionversion()Returns the version of this distribution of Conscrypt.static ConscryptHostnameVerifierwrapHostnameVerifier(HostnameVerifier verifier) Wraps the HttpsURLConnection.HostnameVerifier into a ConscryptHostnameVerifier
-
Field Details
-
VERSION
-
-
Constructor Details
-
Conscrypt
private Conscrypt()
-
-
Method Details
-
isAvailable
public static boolean isAvailable()Returnstrueif 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 givenProviderwas created by this distribution of Conscrypt. -
newProvider
Constructs a newProviderwith the default name. -
newProvider
Deprecated.UsenewProviderBuilder()instead.Constructs a newProviderwith 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 givenSSLContextwas 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 givenSSLSocketFactorywas 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 givenSSLServerSocketFactorywas 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 givenSSLSocketwas 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
nullif 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 thePrivateKeyto 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) ornullfor 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
nullif 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 returnnullif 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 benullto 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
nullif 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 givenSSLEnginewas 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 defaultBufferAllocatorto be used by all futureSSLEngineinstances 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, ornullto 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
nullif 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 thePrivateKeyto 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) ornullfor 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 thesrcsarray of the first source buffersrcsLength- the number of source buffers starting atsrcsOffsetdsts- the destination buffersdstsOffset- the offset in thedstsarray 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
nullif no protocol was agreed upon.
-
getTlsUnique
Returns the tls-unique channel binding value for this connection, per RFC 5929. This will returnnullif 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 benullto 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
nullif 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 givenTrustManagerwas 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.