Add some docs

Author: lauzadis

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

@@ -10,6 +10,10 @@ 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) : SigV4xSignatureCalculator(AwsSigningAlgorithm.SIGV4, sha256Provider) {
     override fun calculate(signingKey: ByteArray, stringToSign: String): String =
         hmac(signingKey, stringToSign.encodeToByteArray(), sha256Provider).encodeToHex()

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

@@ -24,14 +24,25 @@ import kotlin.time.Duration.Companion.hours
  */
 internal const val MAX_KDF_COUNTER_ITERATIONS = 254.toByte()
 
+/**
+ * A [SignatureCalculator] for the SigV4a ("AWS4-ECDSA-P256-SHA256") algorithm.
+ * @param sha256Provider the [HashSupplier] to use for computing SHA-256 hashes
+ */
 internal class SigV4aSignatureCalculator(override val sha256Provider: HashSupplier = ::Sha256) : SigV4xSignatureCalculator(AwsSigningAlgorithm.SIGV4_ASYMMETRIC, sha256Provider) {
     private val privateKeyCache = ReadThroughCache<Credentials, ByteArray>(
         minimumSweepPeriod = 1.hours, // note: Sweeps are effectively a no-op because expiration is [Instant.MAX_VALUE]
     )
 
     override fun calculate(signingKey: ByteArray, stringToSign: String): String = ecdsasecp256r1(signingKey, stringToSign.encodeToByteArray()).encodeToHex()
 
-    // See https://github.com/awslabs/aws-c-auth/blob/e8360a65e0f3337d4ac827945e00c3b55a641a5f/source/key_derivation.c#L70 for more details of derivation process
+    /**
+     * Retrieve a signing key based on the signing credentials. If not cached, the key will be derived using a counter-based key derivation function (KDF)
+     * as specified in NIST SP 800-108.
+     *
+     * See https://github.com/awslabs/aws-c-auth/blob/e8360a65e0f3337d4ac827945e00c3b55a641a5f/source/key_derivation.c#L70 and
+     * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html#derive-signing-key-sigv4a for
+     * more information on the derivation process.
+     */
     override fun signingKey(config: AwsSigningConfig): ByteArray = runBlocking {
         privateKeyCache.get(config.credentials) {
             var counter: Byte = 1
@@ -40,17 +51,12 @@ internal class SigV4aSignatureCalculator(override val sha256Provider: HashSuppli
             // N value from NIST P-256 curve, minus two.
             val nMinusTwo = "FFFFFFFF00000000FFFFFFFFFFFFFFFFBCE6FAADA7179E84F3B9CAC2FC63254F".decodeHexBytes().toPositiveBigInteger()
 
-            // FIXME Public docs say secret access key needs to be Base64 encoded, that's not right.
-            // (or maybe it's already base64-encoded, and they are just repeating it)
             val inputKey = ("AWS4A" + config.credentials.secretAccessKey).encodeToByteArray()
 
             do {
-                // 1.2: Compute K0
                 val k0 = hmac(inputKey, fixedInputString(config.credentials.accessKeyId, counter), sha256Provider)
 
-                // 2: Compute the ECC key pair
                 val c = k0.toPositiveBigInteger()
-
                 privateKey = (c + BigInteger("1")).toByteArray()
 
                 if (counter == MAX_KDF_COUNTER_ITERATIONS && c > nMinusTwo) {
@@ -65,17 +71,17 @@ internal class SigV4aSignatureCalculator(override val sha256Provider: HashSuppli
     }
 
     /**
-     * Computes the fixed input string used for ECDSA private key derivation
+     * Forms the fixed input string used for ECDS private key derivation
      * The final output looks like:
      * 0x00000001 || "AWS4-ECDSA-P256-SHA256" || 0x00 || AccessKeyId || counter || 0x00000100
      */
     private fun fixedInputString(accessKeyId: String, counter: Byte): ByteArray =
-        byteArrayOf(0x00, 0x00, 0x00, 0x01) + // FIXME CRT implementation (4 bytes) and internal docs (1 byte) conflict.
+        byteArrayOf(0x00, 0x00, 0x00, 0x01) +
             "AWS4-ECDSA-P256-SHA256".encodeToByteArray() +
             byteArrayOf(0x00) +
             accessKeyId.encodeToByteArray() +
             counter +
-            byteArrayOf(0x00, 0x00, 0x01, 0x00) // FIXME CRT implementation (4 bytes) and internal docs (2 bytes) conflict.
+            byteArrayOf(0x00, 0x00, 0x01, 0x00)
 }
 
 // Convert [this] [ByteArray] to a positive [BigInteger]