docs(aws-kms-tls-auth): add readme (#5409)

Co-authored-by: Lindsay Stewart <slindsay@amazon.com>
Co-authored-by: Sam Clark <3758302+goatgoose@users.noreply.github.com>
Co-authored-by: Lindsay Stewart <stewart.r.lindsay@gmail.com>

Author: 3 people

bindings/rust/aws-kms-tls-auth/DEVELOPMENT.md

@@ -0,0 +1,49 @@
+# Managing Algorithm & Format Changes.
+
+## Backwards Compatibility: Required
+Changes must always be backwards compatible. More specifically, server's must always be able to deserialize earlier versions of PskIdentities, otherwise all of the in-flight communications would fail when an upgrade happens.
+
+## Forward Compatibility: Customer Responsibility
+We generally do not promise forwards compatibility: A `0.0.1` V1 enabled server might not be able to handshake with a `0.0.2` V2 enabled client. We will strive to maintain forward compatibility, but if there was ever an upgrade from `AES_256_GCM_SIV` to `AES_512_GCM_SIV`, that would not be forward compatible. 
+
+It would be the customer's responsibility to first deploy version 0.0.2 to all servers, and only then would it be safe to enable `PskVersion::V2`. For further
+information see the "Versioning" section in the main module docs.
+
+## Example Version Changes
+Below are some examples of scenarios that would require a new version change.
+- new field: Adding a new field to either PskIdentity or the inner obfuscated fields would require a version change. 
+- new obfuscation algorithm: switch the obfuscation algorithm from AES-256-GCM-SIV to some other AEAD algorithm.
+- new HMAC algorithm: If s2n-tls exposed a new HMAC based on SHA512, we would need
+a new PskVersion to take advantage of it.
+
+All of these version changes could be accomplished with some variation of the following strategy.
+
+```rust
+struct PskIdentity {
+    // This is a "rearranged" version of the existing wire format. As long as the
+    // PskVersion field is first, we can branch on it when parsing.
+    psk_version: PskVersion,
+    psk_identity_value: PskIdentityValue
+}
+
+enum PskIdentityValue {
+    V1(PskIdentityV1),
+    V2(PskIdentityV2),
+}
+
+impl PskIdentityValue {
+    /// version specific logic can be handled in the method
+    fn deobfuscate_datakey(&self, obfuscation_key: ObfuscationKey) -> Vec<u8> {
+        match self {
+            Self::V1(v1_struct) => {
+                // e.g. assert on the obfuscation_key version or size
+            }
+        }
+    }
+}
+```
+
+The above code structure would allow the `DecodeValue` and `EncodeValue` traits to work with both variants. Version specific logic can then be handled in the version-specific structs or the `PskIdentityValue` enum.
+
+
+

bindings/rust/aws-kms-tls-auth/README.md

@@ -0,0 +1,42 @@
+# aws-kms-tls-auth
+
+This crate provides a way to perform TLS authentication using the AWS Key Management Service (KMS) and Identity and Access Management (IAM). The only supported TLS implementation is currently [s2n-tls](https://github.com/aws/s2n-tls), but if you are interested in support for other TLS implementations please open a [github issue](https://github.com/aws/s2n-tls/issues/new/choose).
+
+## Overview
+
+Clients use the [generateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) API to create a PSK with KMS. The ciphertext datakey is used as the PSK identity, which the server can then [decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html). This PSK exchange is done using the TLS 1.3 out-of-band PSK mechanism. Other TLS protocols are not supported. 
+
+## Description
+
+### 0: setup
+We start with 
+- clients: all clients are configured with some IAM role, `client-iam-role`
+- servers: all servers are configured with some IAM role, `server-iam-role`.
+- kms-key-arn: a [KMS Key Arn](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN), which will look like `arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab`.
+    - `client-iam-role` must have `kms:GenerateDataKey` permissions on the key
+    - `server-iam-role` must have `kms:Decrypt` permissions on the key
+
+### 1: client psk generation
+When the `PskProvider` is initialized, the client will call the KMS generateDataKey api. This returns both a plaintext data key and a ciphertext datakey. The client will create a PSK using the ciphertext datakey as the PSK identity, and the plaintext datakey as the PSK secret.
+
+### 2: server psk decrypt
+The client sends the PSK to the server, which gives it access to the PSK identity (ciphertext datakey). The server then decrypts the ciphertext datakey using KMS, getting back the plaintext datakey which is the actual PSK secret.
+
+At this point the handshake can complete. This results in an mTLS connection between the `client-iam-role` and `server-iam-role`.
+
+### Caching
+The server will cache plaintext datakeys. The first connection between a client and server will result in a KMS Decrypt API call, but future TLS handshakes between that same client and server will use the cached key.
+
+### Rotation
+The client will automatically rotate its PSK every 24 hours.
+
+## Authentication
+When the handshake is complete there is a mutually authenticated connection where 
+- the client knows that the server has `kms:Decrypt` permissions on the used KMS Key ARN.
+- the server knows that the client has `kms:GenerateDataKey` permissions on one of the trusted KMS Key ARNs.
+
+For this reason, it is important to configure the key with minimal permissions. If you only want mTLS to be allowed between `client-iam-role` as a client and `server-iam-role` as a server, then `client-iam-role` must be the only IAM identity with `kms:GenerateDataKey` permissions on the KMS key, and `server-iam-role` must be the only IAM identity with `kms:Decrypt` permissions on the key.
+
+While it is possible to configure multiple client roles with `kms:GenerateDataKey` permissions so the server will trust multiple identities, the server will not authenticate the specific client identity.
+
+**Example**: `client-iam-role-A` and `client-iam-role-B` are the only identities with `kms:GenerateDataKey` permissions on a trusted KMS Key ARN. If the server successfully handshakes then it is talking to `client-iam-role-A` OR `client-iam-role-B`, but it does not know which one. 

bindings/rust/aws-kms-tls-auth/src/lib.rs

@@ -52,11 +52,11 @@
 //! Note that the [`PskReceiver`] supports lists for both of these items, so
 //! zero-downtime migrations are possible. _Example_: if the client fleet wanted
 //! to switch from Key A to Key B it would go through the following stages
-//! 1. client -> [A], server -> [A]
-//! 2. client -> [A], server -> [A, B]
-//! 3. client -> [A, B], server -> [A, B]
-//! 4. client ->    [B], server -> [A, B]
-//! 5. client ->    [B], server ->    [B]
+//! 1. clients -> [A]     server -> [A]
+//! 2. clients -> [A]     server -> [A & B]
+//! 3. clients -> [A][B], server -> [A & B]
+//! 4. clients ->    [B], server -> [A & B]
+//! 5. clients ->    [B], server ->     [B]
 //!
 //! ## Versioning
 //!