Package software.amazon.awssdk.crt.io

Class 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.

    • 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

      • 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