feat: Kotlin implementation of SigV4a signing (#1246)

Author: lauzadis

.changes/4b6debe1-7706-484a-8599-ef8c14cecde2.json

@@ -0,0 +1,5 @@
+{
+    "id": "4b6debe1-7706-484a-8599-ef8c14cecde2",
+    "type": "feature",
+    "description": "Add SigV4a support to the default AWS signer"
+}

runtime/auth/aws-signing-common/api/aws-signing-common.api

@@ -55,6 +55,7 @@ public final class aws/smithy/kotlin/runtime/auth/awssigning/AwsSigningAlgorithm
 	public static final field SIGV4 Laws/smithy/kotlin/runtime/auth/awssigning/AwsSigningAlgorithm;
 	public static final field SIGV4_ASYMMETRIC Laws/smithy/kotlin/runtime/auth/awssigning/AwsSigningAlgorithm;
 	public static fun getEntries ()Lkotlin/enums/EnumEntries;
+	public final fun getSigningName ()Ljava/lang/String;
 	public static fun valueOf (Ljava/lang/String;)Laws/smithy/kotlin/runtime/auth/awssigning/AwsSigningAlgorithm;
 	public static fun values ()[Laws/smithy/kotlin/runtime/auth/awssigning/AwsSigningAlgorithm;
 }

runtime/auth/aws-signing-common/common/src/aws/smithy/kotlin/runtime/auth/awssigning/AwsSigningConfig.kt

@@ -12,18 +12,19 @@ public typealias ShouldSignHeaderPredicate = (String) -> Boolean
 
 /**
  * Defines the AWS signature version to use
+ * @param signingName The name of this algorithm to use when signing requests.
  */
-public enum class AwsSigningAlgorithm {
+public enum class AwsSigningAlgorithm(public val signingName: String) {
     /**
      * AWS Signature Version 4
      * see: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html
      */
-    SIGV4,
+    SIGV4("AWS4-HMAC-SHA256"),
 
     /**
      * AWS Signature Version 4 Asymmetric
      */
-    SIGV4_ASYMMETRIC,
+    SIGV4_ASYMMETRIC("AWS4-ECDSA-P256-SHA256"),
 }
 
 /**

runtime/auth/aws-signing-common/common/src/aws/smithy/kotlin/runtime/auth/awssigning/AwsSigningExceptions.kt

@@ -17,6 +17,7 @@ import aws.smithy.kotlin.runtime.InternalApi
  * @param cause The cause of the exception
  */
 @InternalApi
+@Deprecated("This exception is no longer thrown. It will be removed in the next minor version, v1.5.x.")
 public class UnsupportedSigningAlgorithmException(
     message: String,
     public val signingAlgorithm: AwsSigningAlgorithm,

runtime/auth/aws-signing-default/build.gradle.kts

@@ -18,6 +18,7 @@ kotlin {
             dependencies {
                 implementation(project(":runtime:auth:aws-signing-tests"))
                 implementation(libs.kotlinx.coroutines.test)
+                implementation(libs.kotlinx.serialization.json)
             }
         }
 

runtime/auth/aws-signing-default/common/src/aws/smithy/kotlin/runtime/auth/awssigning/BaseSigV4SignatureCalculator.kt

@@ -0,0 +1,98 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.auth.awssigning
+
+import aws.smithy.kotlin.runtime.hashing.HashSupplier
+import aws.smithy.kotlin.runtime.hashing.Sha256
+import aws.smithy.kotlin.runtime.hashing.hash
+import aws.smithy.kotlin.runtime.hashing.sha256
+import aws.smithy.kotlin.runtime.text.encoding.encodeToHex
+import aws.smithy.kotlin.runtime.time.Instant
+import aws.smithy.kotlin.runtime.time.TimestampFormat
+import aws.smithy.kotlin.runtime.time.epochMilliseconds
+
+/**
+ * Common signature implementation used for SigV4 and SigV4a, primarily for forming the strings-to-sign which don't differ
+ * between the two signing algorithms (besides their names).
+ */
+internal abstract class BaseSigV4SignatureCalculator(
+    val algorithm: AwsSigningAlgorithm,
+    open val sha256Provider: HashSupplier = ::Sha256,
+) : SignatureCalculator {
+    private val supportedAlgorithms = setOf(AwsSigningAlgorithm.SIGV4, AwsSigningAlgorithm.SIGV4_ASYMMETRIC)
+
+    init {
+        check(algorithm in supportedAlgorithms) {
+            "This class should only be used for ${supportedAlgorithms.joinToString()}, got $algorithm"
+        }
+    }
+
+    override fun stringToSign(canonicalRequest: String, config: AwsSigningConfig): String = buildString {
+        appendLine(algorithm.signingName)
+        appendLine(config.signingDate.format(TimestampFormat.ISO_8601_CONDENSED))
+        appendLine(config.credentialScope)
+        append(canonicalRequest.encodeToByteArray().hash(sha256Provider).encodeToHex())
+    }
+
+    override fun chunkStringToSign(chunkBody: ByteArray, prevSignature: ByteArray, config: AwsSigningConfig): String = buildString {
+        appendLine("${algorithm.signingName}-PAYLOAD")
+        appendLine(config.signingDate.format(TimestampFormat.ISO_8601_CONDENSED))
+        appendLine(config.credentialScope)
+        appendLine(prevSignature.decodeToString()) // Should already be a byte array of ASCII hex chars
+
+        val nonSignatureHeadersHash = when (config.signatureType) {
+            AwsSignatureType.HTTP_REQUEST_EVENT -> eventStreamNonSignatureHeaders(config.signingDate)
+            else -> HashSpecification.EmptyBody.hash
+        }
+
+        appendLine(nonSignatureHeadersHash)
+        append(chunkBody.hash(sha256Provider).encodeToHex())
+    }
+
+    override fun chunkTrailerStringToSign(trailingHeaders: ByteArray, prevSignature: ByteArray, config: AwsSigningConfig): String =
+        buildString {
+            appendLine("${algorithm.signingName}-TRAILER")
+            appendLine(config.signingDate.format(TimestampFormat.ISO_8601_CONDENSED))
+            appendLine(config.credentialScope)
+            appendLine(prevSignature.decodeToString())
+            append(trailingHeaders.hash(sha256Provider).encodeToHex())
+        }
+}
+
+private const val HEADER_TIMESTAMP_TYPE: Byte = 8
+
+/**
+ * Return the sha256 hex representation of the encoded event stream date header
+ *
+ * ```
+ * sha256Hex( Header(":date", HeaderValue::Timestamp(date)).encodeToByteArray() )
+ * ```
+ *
+ * NOTE: This duplicates parts of the event stream encoding implementation here to avoid a direct dependency.
+ * Should this become more involved than encoding a single date header we should reconsider this choice.
+ *
+ * see [Event Stream implementation](https://github.com/smithy-lang/smithy-kotlin/blob/612c39ba446e6403ea2bd9a51c4d1db111b6e26f/runtime/protocol/aws-event-stream/common/src/aws/smithy/kotlin/runtime/awsprotocol/eventstream/Header.kt#L52)
+ */
+private fun eventStreamNonSignatureHeaders(date: Instant): String {
+    val bytes = ByteArray(15)
+    // encode header name
+    val name = ":date".encodeToByteArray()
+    var offset = 0
+    bytes[offset++] = name.size.toByte()
+    name.copyInto(bytes, destinationOffset = offset)
+    offset += name.size
+
+    // encode header value
+    bytes[offset++] = HEADER_TIMESTAMP_TYPE
+    writeLongBE(bytes, offset, date.epochMilliseconds)
+    return bytes.sha256().encodeToHex()
+}
+
+private fun writeLongBE(dest: ByteArray, offset: Int, x: Long) {
+    var idx = offset
+    for (i in 7 downTo 0) {
+        dest[idx++] = ((x ushr (i * 8)) and 0xff).toByte()
+    }
+}

runtime/auth/aws-signing-default/common/src/aws/smithy/kotlin/runtime/auth/awssigning/Canonicalizer.kt

@@ -124,12 +124,13 @@ internal class DefaultCanonicalizer(private val sha256Supplier: HashSupplier = :
         }
 
         param("Host", builder.url.hostAndPort, !signViaQueryParams, overwrite = false)
-        param("X-Amz-Algorithm", ALGORITHM_NAME, signViaQueryParams)
+        param("X-Amz-Algorithm", config.algorithm.signingName, signViaQueryParams)
         param("X-Amz-Credential", credentialValue(config), signViaQueryParams)
         param("X-Amz-Content-Sha256", hash, addHashHeader)
         param("X-Amz-Date", config.signingDate.format(TimestampFormat.ISO_8601_CONDENSED))
         param("X-Amz-Expires", config.expiresAfter?.inWholeSeconds?.toString(), signViaQueryParams)
         param("X-Amz-Security-Token", sessionToken, !config.omitSessionToken) // Add pre-sig if omitSessionToken=false
+        param("X-Amz-Region-Set", config.region, config.algorithm == AwsSigningAlgorithm.SIGV4_ASYMMETRIC)
 
         val headers = builder
             .headers

runtime/auth/aws-signing-default/common/src/aws/smithy/kotlin/runtime/auth/awssigning/DefaultAwsSigner.kt

@@ -29,30 +29,29 @@ public class DefaultAwsSignerBuilder {
     )
 }
 
+private val AwsSigningAlgorithm.signatureCalculator
+    get() = when (this) {
+        AwsSigningAlgorithm.SIGV4 -> SignatureCalculator.SigV4
+        AwsSigningAlgorithm.SIGV4_ASYMMETRIC -> SignatureCalculator.SigV4a
+    }
+
 @OptIn(ExperimentalApi::class)
 internal class DefaultAwsSignerImpl(
     private val canonicalizer: Canonicalizer = Canonicalizer.Default,
-    private val signatureCalculator: SignatureCalculator = SignatureCalculator.Default,
     private val requestMutator: RequestMutator = RequestMutator.Default,
     private val telemetryProvider: TelemetryProvider? = null,
 ) : AwsSigner {
     override suspend fun sign(request: HttpRequest, config: AwsSigningConfig): AwsSigningResult<HttpRequest> {
         val logger = telemetryProvider?.loggerProvider?.getOrCreateLogger("DefaultAwsSigner")
             ?: coroutineContext.logger<DefaultAwsSignerImpl>()
 
-        // TODO: implement SigV4a
-        if (config.algorithm != AwsSigningAlgorithm.SIGV4) {
-            throw UnsupportedSigningAlgorithmException(
-                "${config.algorithm} support is not yet implemented for the default signer.",
-                config.algorithm,
-            )
-        }
-
         val canonical = canonicalizer.canonicalRequest(request, config)
         if (config.logRequest) {
             logger.trace { "Canonical request:\n${canonical.requestString}" }
         }
 
+        val signatureCalculator = config.algorithm.signatureCalculator
+
         val stringToSign = signatureCalculator.stringToSign(canonical.requestString, config)
         logger.trace { "String to sign:\n$stringToSign" }
 
@@ -74,6 +73,8 @@ internal class DefaultAwsSignerImpl(
         val logger = telemetryProvider?.loggerProvider?.getOrCreateLogger("DefaultAwsSigner")
             ?: coroutineContext.logger<DefaultAwsSignerImpl>()
 
+        val signatureCalculator = config.algorithm.signatureCalculator
+
         val stringToSign = signatureCalculator.chunkStringToSign(chunkBody, prevSignature, config)
         logger.trace { "Chunk string to sign:\n$stringToSign" }
 
@@ -93,6 +94,8 @@ internal class DefaultAwsSignerImpl(
         val logger = telemetryProvider?.loggerProvider?.getOrCreateLogger("DefaultAwsSigner")
             ?: coroutineContext.logger<DefaultAwsSignerImpl>()
 
+        val signatureCalculator = config.algorithm.signatureCalculator
+
         // FIXME - can we share canonicalization code more than we are..., also this reduce is inefficient.
         // canonicalize the headers
         val trailingHeadersBytes = trailingHeaders.entries().sortedBy { e -> e.key.lowercase() }
@@ -117,16 +120,16 @@ internal class DefaultAwsSignerImpl(
     }
 }
 
-/** The name of the SigV4 algorithm. */
-internal const val ALGORITHM_NAME = "AWS4-HMAC-SHA256"
-
 /**
- * Formats a credential scope consisting of a signing date, region, service, and a signature type
+ * Formats a credential scope consisting of a signing date, region (SigV4 only), service, and a signature type
  */
 internal val AwsSigningConfig.credentialScope: String
-    get() {
+    get() = run {
         val signingDate = signingDate.format(TimestampFormat.ISO_8601_CONDENSED_DATE)
-        return "$signingDate/$region/$service/aws4_request"
+        return when (algorithm) {
+            AwsSigningAlgorithm.SIGV4 -> "$signingDate/$region/$service/aws4_request"
+            AwsSigningAlgorithm.SIGV4_ASYMMETRIC -> "$signingDate/$service/aws4_request"
+        }
     }
 
 /**

runtime/auth/aws-signing-default/common/src/aws/smithy/kotlin/runtime/auth/awssigning/RequestMutator.kt

@@ -43,7 +43,7 @@ internal class DefaultRequestMutator : RequestMutator {
                 val credential = "Credential=${credentialValue(config)}"
                 val signedHeaders = "SignedHeaders=${canonical.signedHeaders}"
                 val signature = "Signature=$signatureHex"
-                canonical.request.headers["Authorization"] = "$ALGORITHM_NAME $credential, $signedHeaders, $signature"
+                canonical.request.headers["Authorization"] = "${config.algorithm.signingName} $credential, $signedHeaders, $signature"
             }
 
             AwsSignatureType.HTTP_REQUEST_VIA_QUERY_PARAMS ->

runtime/auth/aws-signing-default/common/src/aws/smithy/kotlin/runtime/auth/awssigning/SigV4SignatureCalculator.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package aws.smithy.kotlin.runtime.auth.awssigning
+
+import aws.smithy.kotlin.runtime.hashing.HashSupplier
+import aws.smithy.kotlin.runtime.hashing.Sha256
+import aws.smithy.kotlin.runtime.hashing.hmac
+import aws.smithy.kotlin.runtime.text.encoding.encodeToHex
+import aws.smithy.kotlin.runtime.time.TimestampFormat
+
+/**
+ * [SignatureCalculator] for the SigV4 ("AWS4-HMAC-SHA256") algorithm
+ * @param sha256Provider the [HashSupplier] to use for computing SHA-256 hashes
+ */
+internal class SigV4SignatureCalculator(override val sha256Provider: HashSupplier = ::Sha256) : BaseSigV4SignatureCalculator(AwsSigningAlgorithm.SIGV4, sha256Provider) {
+    override fun calculate(signingKey: ByteArray, stringToSign: String): String =
+        hmac(signingKey, stringToSign.encodeToByteArray(), sha256Provider).encodeToHex()
+
+    override fun signingKey(config: AwsSigningConfig): ByteArray {
+        fun hmac(key: ByteArray, message: String) = hmac(key, message.encodeToByteArray(), sha256Provider)
+
+        val initialKey = ("AWS4" + config.credentials.secretAccessKey).encodeToByteArray()
+        val kDate = hmac(initialKey, config.signingDate.format(TimestampFormat.ISO_8601_CONDENSED_DATE))
+        val kRegion = hmac(kDate, config.region)
+        val kService = hmac(kRegion, config.service)
+        return hmac(kService, "aws4_request")
+    }
+}