BREAKING: Streamlined TLS configuration

[ianbotsf]

An upcoming release of the AWS SDK for Kotlin includes a redesigned API for TLS configuration of HTTP client engines. This change streamlines how custom TLS settings are configured, which may affect some existing code.

Note: If you don't customize TLS settings for your HTTP client engines, this change should not affect you.

Release date

This feature will ship with the v0.23.0-beta release planned for 05/04/2023.

What's changing

The HttpClientEngineConfig class is getting a new tlsContext member which can be used to configure settings related to TLS and secure connections. Accordingly, the following breaking changes will be made:

• The alpn setting for controlling which protocols are sent during TLS negotiation is moving from HttpClientEngineConfig into tlsContext. This setting is directly related to TLS and thus will more naturally fit in a TLS-specific config location.
• The tlsContext member of CrtClientEngineConfig is being removed. This will avoid naming/type conflicts with the base HttpClientEngineConfig class. At present, an equivalent setting for setting the minimum allowable TLS version is being lifted to HttpClientEngineConfig.tlsContext. No other settings from CrtClientEngineConfig are included at this time but task smithy-kotlin#820 may add additional settings which were previously available in this class.

How to migrate

Migration steps depend on current use case.

Migrating alpn configuration

Previously, ALPN was configured like this:

val engine = DefaultHttpEngine {
    alpn = listOf(AlpnId.HTTP1_1, AlpnId.HTTP2)
}

After this change, ALPN will be configured like this:

val engine = DefaultHttpEngine {
    tlsContext {
        alpn = listOf(AlpnId.HTTP1_1, AlpnId.HTTP2)
    }
}

Migrating CRT-specific minimum TLS version configuration

Previously, the CRT engine allowed configuring minimum TLS version like this:

val tlsContextOptions = TlsContextOptions.build {
    minTlsVersion = TlsVersion.TLS_V1_2
}
val engine = CrtHttpEngine {
    tlsContext = TlsContext(tlsContextOptions)
}

After this change, minimum TLS version configuration will be configured like this:

val engine = CrtHttpEngine {
    tlsContext {
        minVersion = TlsVersion.TLS_1_2
    }
}

Note: The tlsContext.minVersion setting is no longer CRT-specific. Any engine variant may now be configured by setting this field.

Removing CRT-specific TLS configuration (other than minimum TLS version)

Previously, the CRT engine allowed configuring other TLS settings besides minimum version:

val tlsContextOptions = TlsContextOptions.build {
    verifyPeer = false
    caDir = "/path/to/ca/files/"
}
val engine = CrtHttpEngine {
    tlsContext = TlsContext(tlsContextOptions)
}

Besides minimum TLS version, these settings are no longer available for the CRT engine and must be removed. Task smithy-kotlin#820 may lift some of the settings previously available for the CRT engine into the common tlsContext in HttpClientEngineConfig.

Additional resources

If you have any questions concerning this change, please feel free to engage with us in this discussion. If you encounter a bug with these changes, please file an issue.