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

Nested classes/interfaces inherited from class software.amazon.awssdk.crt.CrtResource

CrtResource.ResourceInstance

Field Summary

Fields

Modifier and Type	Field and Description
List<String>	alpnList Sets the ALPN protocol list that will be provided when a TLS connection starts e.g.
TlsContextOptions.TlsVersions	minTlsVersion Sets the minimum acceptable TLS version that the TlsContext will allow.
TlsCipherPreference	tlsCipherPreference Sets the TLS Cipher Preferences that can be negotiated and used during the TLS Connection.
boolean	verifyPeer Set whether or not the peer should be verified.

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
long	getNativeHandle() returns the native handle associated with this CRTResource.
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	setCipherPreference(TlsCipherPreference cipherPref)
TlsContextOptions	withAlpnList(String alpnList) Sets the ALPN protocols list for any connections using this TlsContext
TlsContextOptions	withCertificateAuthority(String caRoot) Specifies the certificate authority to use.
TlsContextOptions	withCertificateAuthorityFromPath(String caDirPath, String caFilePath) Specifies the certificate authority to use.
TlsContextOptions	withCipherPreference(TlsCipherPreference cipherPref) Sets the ciphers that the TlsContext will be able to use
TlsContextOptions	withMinimumTlsVersion(TlsContextOptions.TlsVersions version) Sets the minimum TLS version that the TlsContext will allow.
TlsContextOptions	withMtls(String certificate, String privateKey) Enables mutual TLS (mTLS) on this TlsContext
TlsContextOptions	withMtlsFromPath(String certificatePath, String privateKeyPath) Enables mutual TLS (mTLS) on this TlsContext
TlsContextOptions	withMtlsPkcs12(String pkcs12Path, String pkcs12Password) Apple platforms only, specifies mTLS using PKCS#12
TlsContextOptions	withVerifyPeer() Enables TLS peer verification of certificates
TlsContextOptions	withVerifyPeer(boolean verify) Sets whether or not TLS will validate the certificate from the peer.

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

acquireNativeHandle, addRef, addReferenceTo, close, collectNativeResource, collectNativeResources, decRef, getResourceLogDescription, isNull, logNativeResources, releaseReferences, removeReferenceTo, setDescription, swapReferenceTo, waitForNoResources

Methods inherited from class java.lang.Object

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

Field Detail

minTlsVersion

public TlsContextOptions.TlsVersions minTlsVersion

Sets the minimum acceptable TLS version that the TlsContext will allow. Not compatible with setCipherPreference() API. Select from TlsVersions, a good default is TlsVersions.TLS_VER_SYS_DEFAULTS as this will update if the OS TLS is updated

tlsCipherPreference

public TlsCipherPreference tlsCipherPreference

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

alpnList

public List<String> alpnList

Sets the ALPN protocol list that will be provided when a TLS connection starts e.g. "x-amzn-mqtt-ca"

verifyPeer

public boolean verifyPeer

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.

Method Detail

getNativeHandle

public long getNativeHandle()

Description copied from class: CrtResource

returns the native handle associated with this CRTResource.

Overrides:

getNativeHandle in class CrtResource

Returns:

native address

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

Returns:

true if this resource releases synchronously, false if this resource performs async shutdown

releaseNativeHandle

protected void releaseNativeHandle()

Frees the native resources associated with this instance

Specified by:

releaseNativeHandle in class CrtResource

setCipherPreference

public void setCipherPreference(TlsCipherPreference cipherPref)

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

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 - if the CA Root PEM file is malformed

createDefaultClient

public static TlsContextOptions createDefaultClient()

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

createDefaultServer

public static TlsContextOptions createDefaultServer()

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

createWithMtlsFromPath

public static TlsContextOptions createWithMtlsFromPath(String certificatePath,
                                                       String privateKeyPath)

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

createWithMtls

public static TlsContextOptions createWithMtls(String certificate,
                                               String privateKey)
                                        throws 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:

IllegalArgumentException - If either PEM fails to parse

createWithMtlsPkcs12

public static TlsContextOptions createWithMtlsPkcs12(String pkcs12Path,
                                                     String pkcs12Password)

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

withCipherPreference

public TlsContextOptions withCipherPreference(TlsCipherPreference cipherPref)

Sets the ciphers that the TlsContext will be able to use

Parameters:

cipherPref - The preference set of ciphers to use

Returns:

this

withMinimumTlsVersion

public TlsContextOptions withMinimumTlsVersion(TlsContextOptions.TlsVersions version)

Sets the minimum TLS version that the TlsContext will allow. Defaults to OS defaults.

Parameters:

version - Minimum acceptable TLS version

Returns:

this

withAlpnList

public TlsContextOptions withAlpnList(String alpnList)

Sets the ALPN protocols list for any connections using this TlsContext

Parameters:

alpnList - Semi-colon delimited list of supported ALPN protocols

Returns:

this

withMtls

public TlsContextOptions withMtls(String certificate,
                                  String privateKey)

Enables mutual TLS (mTLS) on this TlsContext

Parameters:

certificate - mTLS certificate, in PEM format

privateKey - mTLS private key, in PEM format

Returns:

this

withMtlsFromPath

public TlsContextOptions withMtlsFromPath(String certificatePath,
                                          String privateKeyPath)

Enables mutual TLS (mTLS) on this TlsContext

Parameters:

certificatePath - path to mTLS certificate, in PEM format

privateKeyPath - path to mTLS private key, in PEM format

Returns:

this

withCertificateAuthority

public TlsContextOptions withCertificateAuthority(String caRoot)

Specifies the certificate authority to use. By default, the OS CA repository will be used.

Parameters:

caRoot - Certificate Authority, in PEM format

Returns:

this

withCertificateAuthorityFromPath

public TlsContextOptions withCertificateAuthorityFromPath(String caDirPath,
                                                          String caFilePath)

Specifies the certificate authority to use.

Parameters:

caDirPath - Path to certificate directory, e.g. /etc/ssl/certs

caFilePath - Path to ceritificate authority, in PEM format

Returns:

this

withMtlsPkcs12

public TlsContextOptions withMtlsPkcs12(String pkcs12Path,
                                        String pkcs12Password)

Apple platforms only, specifies mTLS using PKCS#12

Parameters:

pkcs12Path - Path to PKCS#12 certificate, in PEM format

pkcs12Password - PKCS#12 password

Returns:

this

withVerifyPeer

public TlsContextOptions withVerifyPeer(boolean verify)

Sets whether or not TLS will validate the certificate from the peer. On clients, this is enabled by default. On servers, this is disabled by default.

Parameters:

verify - true to verify peers, false to ignore certs

Returns:

this

withVerifyPeer

public TlsContextOptions withVerifyPeer()

Enables TLS peer verification of certificates

Returns:

this

See Also:

withVerifyPeer(boolean)