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

      • setCipherPreference

        public void setCipherPreference​(TlsCipherPreference cipherPref)
        Sets the TLS cipher preferences to use in contexts using this configuration
        Parameters:
        cipherPref - cipher preferences to use

      • initMtlsFromPath

        public void initMtlsFromPath​(String certificatePath,
                             String privateKeyPath)
        Sets the path to the certificate that identifies this mutual TLS (mTLS) 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 mutual TLS (mTLS) 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)
        Apple platforms only - Initializes mutual TLS (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 mutual TLS (mTLS) 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 mutual TLS (mTLS) 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)
        Apple platforms only - Helper which creates mutual TLS (mTLS) 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 mTLS connection

      • createWithMtlsPkcs11

        public static TlsContextOptions createWithMtlsPkcs11​(TlsContextPkcs11Options pkcs11Options)
        Unix platforms only - Helper which creates mutual TLS (mTLS) options using a PKCS#11 library for private key operations.
        Parameters:
        pkcs11Options - PKCS#11 options
        Returns:
        A set of options for creating a PKCS#11 mTLS connection

      • createWithMtlsCustomKeyOperations

        public static TlsContextOptions createWithMtlsCustomKeyOperations​(TlsContextCustomKeyOperationOptions custom)
        Unix platforms only - Helper which creates mutual TLS (mTLS) options using the applied custom key operations. This allows you to perform custom private key operations such as signing and decrypting. This is necessary if you require an external library to handle private key operations.
        Parameters:
        custom - The options for the custom private key operations
        Returns:
        A set of options for creating a custom key operation mTLS connection

      • createWithMtlsWindowsCertStorePath

        public static TlsContextOptions createWithMtlsWindowsCertStorePath​(String certificatePath)
        Windows platforms only - Helper which creates mutual TLS (mTLS) options using a certificate in a Windows certificate store.
        Parameters:
        certificatePath - Path to certificate in a Windows certificate store. The path must use backslashes and end with the certificate's thumbprint. Example: CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6
        Returns:
        A set of options for setting up an mTLS connection

      • createWithMtlsJavaKeystore

        public static TlsContextOptions createWithMtlsJavaKeystore​(KeyStore keyStore,
                                                           String certificateAlias,
                                                           String certificatePassword)
        Helper which creates mutual TLS (mTLS) options using a certificate and private key stored in a Java keystore. Will throw an exception if there is no certificate and key at the given certificate alias, or there is some other error accessing or using the passed-in Java keystore. Note: function assumes the passed keystore has already been loaded from a file by calling "keystore.load()" or similar.
        Parameters:
        keyStore - The Java keystore to use. Assumed to be loaded with the desired certificate and key
        certificateAlias - The alias of the certificate and key to use.
        certificatePassword - The password of the certificate and key to use.
        Returns:
        A set of options for setting up an mTLS connection
        Throws:
        CrtRuntimeException - if the certificate alias does not exist or the certificate/key cannot be found in the certificate alias

      • 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 mutual TLS (mTLS) using PKCS#12
        Parameters:
        pkcs12Path - Path to PKCS#12 certificate, in PEM format
        pkcs12Password - PKCS#12 password
        Returns:
        this

      • withMtlsPkcs11

        public TlsContextOptions withMtlsPkcs11​(TlsContextPkcs11Options pkcs11Options)
        Unix platforms only, specifies mutual TLS (mTLS) using a PKCS#11 library for private key operations.
        Parameters:
        pkcs11Options - PKCS#11 options
        Returns:
        this

      • withMtlsCustomKeyOperations

        public TlsContextOptions withMtlsCustomKeyOperations​(TlsContextCustomKeyOperationOptions customKeyOperations)
        Unix platforms only, specifies TLS options for custom private key operations. This allows you to perform custom private key operations such as signing and decrypting.
        Parameters:
        customKeyOperations - The custom private key operations
        Returns:
        this

      • withMtlsWindowsCertStorePath

        public TlsContextOptions withMtlsWindowsCertStorePath​(String certificatePath)
        Windows platforms only, specifies mutual TLS (mTLS) using a certificate in a Windows certificate store.
        Parameters:
        certificatePath - Path to certificate in a Windows certificate store. The path must use backslashes and end with the certificate's thumbprint. Example: CurrentUser\MY\A11F8A9B5DF5B98BA3508FBCA575D09570E0D2C6
        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