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

  • Field Details

    • 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 Details

    • 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

    • withVerifyPeer

      public TlsContextOptions withVerifyPeer()
      Enables TLS peer verification of certificates
      Returns:
      this
      See Also: