software.amazon.awssdk.crt.io

Class TlsContextOptions

java.lang.Object

software.amazon.awssdk.crt.CrtResource

software.amazon.awssdk.crt.io.TlsContextOptions

All Implemented Interfaces:

AutoCloseable

public final class TlsContextOptions
extends CrtResource

This class wraps the aws_tls_connection_options from aws-c-io to provide access to TLS configuration contexts in the AWS Common Runtime.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TlsContextOptions.TlsVersions

Method Summary

Modifier and Type	Method and Description
protected boolean	canReleaseReferencesImmediately() Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits.
static TlsContextOptions	createDefaultClient() Helper which creates a default set of TLS options for the current platform
static TlsContextOptions	createDefaultServer() Helper which creates a default set of TLS options for the current platform
static TlsContextOptions	createWithMTLS(String certificate, String privateKey) Helper which creates TLS options using a certificate and private key
static TlsContextOptions	createWithMTLSFromPath(String certificatePath, String privateKeyPath) Helper which creates TLS options using a certificate and private key
static TlsContextOptions	createWithMTLSPkcs12(String pkcs12Path, String pkcs12Password) OSX only - Helper which creates TLS options using PKCS12
void	initMTLS(String certificate, String privateKey) Sets the certificate/key pair that identifies this TLS host.
void	initMTLSFromPath(String certificatePath, String privateKeyPath) Sets the path to the certificate that identifies this TLS host.
void	initMTLSPkcs12(String pkcs12Path, String pkcs12Password) OSX only - Initializes MTLS with PKCS12 file and password
static boolean	isAlpnSupported() Returns whether or not ALPN is supported on the current platform
static boolean	isCipherPreferenceSupported(TlsCipherPreference cipherPref) Returns whether or not the current platform can be configured to a specific TlsCipherPreference.
void	overrideDefaultTrustStore(String caRoot) Helper function to provide a TlsContext-local trust store
void	overrideDefaultTrustStoreFromPath(String caPath, String caFile) Helper function to provide a TlsContext-local trust store
protected void	releaseNativeHandle() Frees the native resources associated with this instance
void	setAlpnList(String alpn) Sets the ALPN protocol list that will be provided when a TLS connection starts
void	setCipherPreference(TlsCipherPreference cipherPref) Sets the TLS Cipher Preferences that can be negotiated and used during the TLS Connection.
void	setMinimumTlsVersion(TlsContextOptions.TlsVersions version) Sets the minimum acceptable TLS version that the TlsContext will allow.
void	setVerifyPeer(boolean verify) Set whether or not the peer should be verified.
TlsContextOptions	withAlpnList(String alpnList)
TlsContextOptions	withCipherPreference(TlsCipherPreference cipherPref) .with() methods
TlsContextOptions	withMinimumTlsVersion(TlsContextOptions.TlsVersions version)

Methods inherited from class software.amazon.awssdk.crt.CrtResource

acquireNativeHandle, addReferenceTo, close, collectNativeResources, getNativeHandle, isNativeResource, isNull, logNativeResources, releaseReferences, waitForNoResources

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

canReleaseReferencesImmediately

protected boolean canReleaseReferencesImmediately()

Determines whether a resource releases its dependencies at the same time the native handle is released or if it waits. Resources that wait are responsible for calling releaseReferences() manually.

Specified by:

canReleaseReferencesImmediately in class CrtResource

releaseNativeHandle

protected void releaseNativeHandle()

Frees the native resources associated with this instance

Specified by:

releaseNativeHandle in class CrtResource

setMinimumTlsVersion

public void setMinimumTlsVersion(TlsContextOptions.TlsVersions version)

Sets the minimum acceptable TLS version that the TlsContext will allow. Not compatible with setCipherPreference() API.

Parameters:

version - Select from TlsVersions, a good default is TlsVersions.TLS_VER_SYS_DEFAULTS as this will update if the OS TLS is updated

setAlpnList

public void setAlpnList(String alpn)

Sets the ALPN protocol list that will be provided when a TLS connection starts

Parameters:

alpn - The ALPN protocol to use, e.g. "x-amzn-mqtt-ca"

setCipherPreference

public void setCipherPreference(TlsCipherPreference cipherPref)

Sets the TLS Cipher Preferences that can be negotiated and used during the TLS Connection. Not compatible with setMinimumTlsVersion() API.

Parameters:

cipherPref - The Cipher Preference to use

initMTLSFromPath

public void initMTLSFromPath(String certificatePath,
                             String privateKeyPath)

Sets the path to the certificate that identifies this TLS host. Must be in PEM format.

Parameters:

certificatePath - Path to PEM format certificate

privateKeyPath - Path to PEM format private key

initMTLS

public void initMTLS(String certificate,
                     String privateKey)
              throws IllegalArgumentException

Sets the certificate/key pair that identifies this TLS host. Must be in PEM format.

Parameters:

certificate - PEM armored certificate

privateKey - PEM armored private key

Throws:

IllegalArgumentException - If the certificate or privateKey are not in PEM format or if they contain chains

initMTLSPkcs12

public void initMTLSPkcs12(String pkcs12Path,
                           String pkcs12Password)

OSX only - Initializes MTLS with PKCS12 file and password

Parameters:

pkcs12Path - Path to PKCS12 file

pkcs12Password - PKCS12 password

setVerifyPeer

public void setVerifyPeer(boolean verify)

Set whether or not the peer should be verified. Default is true for clients, and false for servers. If you are in a development or debugging environment, you can disable this to avoid or diagnose trust store issues. This should always be true on clients in the wild. If you set this to true on a server, it will validate every client connection.

Parameters:

verify - true to verify peers, false to skip verification

isAlpnSupported

public static boolean isAlpnSupported()

Returns whether or not ALPN is supported on the current platform

Returns:

true if ALPN is supported, false otherwise

isCipherPreferenceSupported

public static boolean isCipherPreferenceSupported(TlsCipherPreference cipherPref)

Returns whether or not the current platform can be configured to a specific TlsCipherPreference.

Parameters:

cipherPref - The TlsCipherPreference to check

Returns:

True if the current platform does support this TlsCipherPreference, false otherwise

overrideDefaultTrustStoreFromPath

public void overrideDefaultTrustStoreFromPath(String caPath,
                                              String caFile)

Helper function to provide a TlsContext-local trust store

Parameters:

caPath - Path to the local trust store. Can be null.

caFile - Path to the root certificate. Must be in PEM format.

overrideDefaultTrustStore

public void overrideDefaultTrustStore(String caRoot)
                               throws IllegalArgumentException

Helper function to provide a TlsContext-local trust store

Parameters:

caRoot - Buffer containing the root certificate chain. Must be in PEM format.

Throws:

IllegalArgumentException

createDefaultClient

public static TlsContextOptions createDefaultClient()
                                             throws CrtRuntimeException

Helper which creates a default set of TLS options for the current platform

Returns:

A default configured set of options for a TLS client connection

Throws:

CrtRuntimeException - @see TlsContextOptions.TlsContextOptions()

createDefaultServer

public static TlsContextOptions createDefaultServer()
                                             throws CrtRuntimeException

Helper which creates a default set of TLS options for the current platform

Returns:

A default configured set of options for a TLS server connection

Throws:

CrtRuntimeException - @see TlsContextOptions.TlsContextOptions()

createWithMTLSFromPath

public static TlsContextOptions createWithMTLSFromPath(String certificatePath,
                                                       String privateKeyPath)
                                                throws CrtRuntimeException

Helper which creates TLS options using a certificate and private key

Parameters:

certificatePath - Path to a PEM format certificate

privateKeyPath - Path to a PEM format private key

Returns:

A set of options for setting up an MTLS connection

Throws:

CrtRuntimeException - @see #constructor()

createWithMTLS

public static TlsContextOptions createWithMTLS(String certificate,
                                               String privateKey)
                                        throws CrtRuntimeException,
                                               IllegalArgumentException

Helper which creates TLS options using a certificate and private key

Parameters:

certificate - String containing a PEM format certificate

privateKey - String containing a PEM format private key

Returns:

A set of options for setting up an MTLS connection

Throws:

CrtRuntimeException - @see #constructor()

IllegalArgumentException - If either PEM fails to parse

createWithMTLSPkcs12

public static TlsContextOptions createWithMTLSPkcs12(String pkcs12Path,
                                                     String pkcs12Password)
                                              throws CrtRuntimeException

OSX only - Helper which creates TLS options using PKCS12

Parameters:

pkcs12Path - The path to a PKCS12 file @see #setPkcs12Path(String)

pkcs12Password - The PKCS12 password @see #setPkcs12Password(String)

Returns:

A set of options for creating a PKCS12 TLS connection

Throws:

CrtRuntimeException - @see #constructor()

withCipherPreference

public TlsContextOptions withCipherPreference(TlsCipherPreference cipherPref)

.with() methods

withMinimumTlsVersion

public TlsContextOptions withMinimumTlsVersion(TlsContextOptions.TlsVersions version)

withAlpnList

public TlsContextOptions withAlpnList(String alpnList)