chore: Add ECDH examples (#1461)

Co-authored-by: Lucas McDonald <lucasmcdonald3@gmail.com>

Author: josecorella

Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/keyring/KmsEcdhKeyringExample.java

@@ -20,6 +20,10 @@ public class TestUtils {
     "arn:aws:kms:us-east-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
   public static final String TEST_MRK_REPLICA_KEY_ID_EU_WEST_1 =
     "arn:aws:kms:eu-west-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
+  public static final String TEST_KMS_ECDH_KEY_ID_P256_SENDER =
+    "arn:aws:kms:us-west-2:370957321024:key/eabdf483-6be2-4d2d-8ee4-8c2583d416e9";
+  public static final String TEST_KMS_ECDH_KEY_ID_P256_RECIPIENT =
+    "arn:aws:kms:us-west-2:370957321024:key/0265c8e9-5b6a-4055-8f70-63719e09fda5";
 
   // Our tests require access to DDB Table with this name
   public static final String TEST_DDB_TABLE_NAME =

Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/keyring/RawEcdhKeyringExample.java

@@ -0,0 +1,49 @@
+package software.amazon.cryptography.examples.keyring;
+
+import static software.amazon.cryptography.examples.keyring.KmsEcdhKeyringExample.EXAMPLE_ECC_PUBLIC_KEY_RECIPIENT_FILENAME;
+import static software.amazon.cryptography.examples.keyring.KmsEcdhKeyringExample.EXAMPLE_ECC_PUBLIC_KEY_SENDER_FILENAME;
+import static software.amazon.cryptography.examples.keyring.KmsEcdhKeyringExample.shouldGetNewPublicKeys;
+import static software.amazon.cryptography.examples.keyring.KmsEcdhKeyringExample.writePublicKeyPemForEccKey;
+
+import org.testng.annotations.Test;
+import software.amazon.cryptography.examples.TestUtils;
+
+public class TestKmsEcdhKeyringExample {
+
+  @Test
+  public void TestKmsEcdhKeyringExampleStatic() {
+    // You may provide your own ECC public keys at
+    // - EXAMPLE_ECC_PUBLIC_KEY_SENDER_FILENAME
+    // - EXAMPLE_ECC_PUBLIC_KEY_RECIPIENT_FILENAME.
+    // If you provide these, the keys MUST be on curve P256
+    // This must be the public key for the ECC key represented at eccKeyArn
+    // If this file is not present, this will write a UTF-8 encoded PEM file for you.
+    if (shouldGetNewPublicKeys()) {
+      writePublicKeyPemForEccKey(
+        TestUtils.TEST_KMS_ECDH_KEY_ID_P256_SENDER,
+        EXAMPLE_ECC_PUBLIC_KEY_SENDER_FILENAME
+      );
+      writePublicKeyPemForEccKey(
+        TestUtils.TEST_KMS_ECDH_KEY_ID_P256_RECIPIENT,
+        EXAMPLE_ECC_PUBLIC_KEY_RECIPIENT_FILENAME
+      );
+    }
+
+    KmsEcdhKeyringExample.KmsEcdhKeyringGetItemPutItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      TestUtils.TEST_KMS_ECDH_KEY_ID_P256_SENDER
+    );
+  }
+
+  @Test
+  public void TestKmsEcdhKeyringExampleDiscovery() {
+    // In this example you do not need to provide the recipient ECC Public Key.
+    // On initialization, the keyring will call KMS:getPublicKey on the configured
+    // recipientKmsIdentifier set on the keyring. This example uses the previous example
+    // to write an item meant for the recipient.
+    KmsEcdhKeyringExample.KmsEcdhDiscoveryGetItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      TestUtils.TEST_KMS_ECDH_KEY_ID_P256_RECIPIENT
+    );
+  }
+}

Examples/runtimes/java/DynamoDbEncryption/src/test/java/software/amazon/cryptography/examples/TestUtils.java

@@ -0,0 +1,83 @@
+package software.amazon.cryptography.examples.keyring;
+
+import java.nio.ByteBuffer;
+import java.security.spec.ECGenParameterSpec;
+import org.testng.annotations.Test;
+import software.amazon.cryptography.examples.TestUtils;
+import software.amazon.cryptography.primitives.model.ECDHCurveSpec;
+
+public class TestRawEcdhKeyringExample {
+
+  @Test
+  public void TestStaticRawEcdhKeyringExample() {
+    // You may provide your own ECC Key pairs in the files located at
+    // - EXAMPLE_ECC_PRIVATE_KEY_FILENAME_SENDER
+    // - EXAMPLE_ECC_PUBLIC_KEY_FILENAME_RECIPIENT
+    // If you provide this, the keys MUST be on curve P256
+    // If these files are not present, this will generate a pair for you.
+    // For this example we will use the curve P256.
+    if (RawEcdhKeyringExample.shouldGenerateNewEccKeyPairs()) {
+      RawEcdhKeyringExample.generateEccKeyPairs();
+    }
+
+    // Part of using these keyrings is knowing which curve the keys used in the key agreement
+    // lie on. The keyring will fail if the keys do not lie on the configured curve.
+    RawEcdhKeyringExample.RawEcdhKeyringGetItemPutItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      ECDHCurveSpec.ECC_NIST_P256
+    );
+  }
+
+  @Test
+  public void TestEphemeralRawEcdhKeyringExample() {
+    // You may provide your own ECC Public Key in the files located at
+    // - EXAMPLE_ECC_PUBLIC_KEY_FILENAME_RECIPIENT
+    // If you provide this, the keys MUST be on curve P256
+    // If these files are not present, this will generate a pair for you.
+    // For this example we will use the curve P256.
+    if (RawEcdhKeyringExample.shouldGenerateNewEccKeyPairs()) {
+      RawEcdhKeyringExample.generateEccKeyPairs();
+    }
+
+    // Part of using these keyrings is knowing which curve the keys used in the key agreement
+    // lie on. The keyring will fail if the keys do not lie on the configured curve.
+    RawEcdhKeyringExample.EphemeralRawEcdhKeyringPutItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      ECDHCurveSpec.ECC_NIST_P256
+    );
+  }
+
+  @Test
+  public void TestDiscoveryRawEcdhKeyringExample() {
+    // You may provide your own ECC Public Key in the files located at
+    // - EXAMPLE_ECC_PUBLIC_KEY_FILENAME_RECIPIENT
+    // - EXAMPLE_ECC_PRIVATE_KEY_FILENAME_RECIPIENT
+    // If you provide this, the keys MUST be on curve P256
+    // If these files are not present, this will generate a pair for you.
+    // For this example we will use the curve P256.
+    if (RawEcdhKeyringExample.shouldGenerateNewEccKeyPairs()) {
+      RawEcdhKeyringExample.generateEccKeyPairs();
+    }
+
+    // The discovery configuration is not allowed to encrypt
+    // To understand this example best, we will write a record with the ephemeral configuration
+    // in the previous example. This means that the recipient public key configured on
+    // both keyrings is the same. This means that the other party has the recipient public key
+    // and is writing messages meant only for the owner of the recipient public key to decrypt.
+
+    // In this call we are writing a record that is written with an ephemeral sender key pair.
+    // The recipient will be able to decrypt the message
+    RawEcdhKeyringExample.EphemeralRawEcdhKeyringPutItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      ECDHCurveSpec.ECC_NIST_P256
+    );
+
+    // In this call we are reading a record that was written with the recipient's public key.
+    // It will use the recipient's private key and the sender's public key stored in the message to
+    // calculate the appropriate shared secret to successfully decrypt the message.
+    RawEcdhKeyringExample.DiscoveryRawEcdhKeyringGetItem(
+      TestUtils.TEST_DDB_TABLE_NAME,
+      ECDHCurveSpec.ECC_NIST_P256
+    );
+  }
+}

Examples/runtimes/java/DynamoDbEncryption/src/test/java/software/amazon/cryptography/examples/keyring/TestKmsEcdhKeyringExample.java

@@ -1,6 +1,7 @@
 using System;
 using System.Threading;
 using System.Threading.Tasks;
+using Examples.keyring;
 
 namespace Examples
 {
@@ -22,6 +23,8 @@ static async Task Main()
             await MultiKeyringExample.MultiKeyringGetItemPutItem();
             await RawRsaKeyringExample.RawRsaKeyringGetItemPutItem();
             await KmsRsaKeyringExample.KmsRsaKeyringGetItemPutItem();
+            await RawEcdhKeyringExample.RawEcdhKeyringExamples();
+            await KmsEcdhKeyringExample.KmsEcdhKeyringExamples();
 
             var keyId = CreateKeyStoreKeyExample.KeyStoreCreateKey();
             var keyId2 = CreateKeyStoreKeyExample.KeyStoreCreateKey();

Examples/runtimes/java/DynamoDbEncryption/src/test/java/software/amazon/cryptography/examples/keyring/TestRawEcdhKeyringExample.java

@@ -24,6 +24,12 @@ public class TestUtils
     public static readonly string TEST_KMS_RSA_KEY_ID =
         "arn:aws:kms:us-west-2:658956600833:key/8b432da4-dde4-4bc3-a794-c7d68cbab5a6";
 
+    public static readonly string TEST_KMS_ECDH_KEY_ID_P256_SENDER =
+        "arn:aws:kms:us-west-2:370957321024:key/eabdf483-6be2-4d2d-8ee4-8c2583d416e9";
+
+    public static readonly string TEST_KMS_ECDH_KEY_ID_P256_RECIPIENT =
+        "arn:aws:kms:us-west-2:370957321024:key/0265c8e9-5b6a-4055-8f70-63719e09fda5";
+
     public static readonly string TEST_MRK_REPLICA_KEY_ID_US_EAST_1 =
         "arn:aws:kms:us-east-1:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7";
 

Examples/runtimes/net/src/Examples.cs

@@ -64,131 +64,13 @@ Resources:
         WriteCapacityUnits: "5"
       TableName: !Ref TableName
 
-  BasicTestJavaTable:
-    Type: AWS::DynamoDB::Table
-    Properties:
-      AttributeDefinitions:
-        - AttributeName: "partition_key"
-          AttributeType: "S"
-        - AttributeName: "sort_key"
-          AttributeType: "N"
-      KeySchema:
-        - AttributeName: "partition_key"
-          KeyType: "HASH"
-        - AttributeName: "sort_key"
-          KeyType: "RANGE"
-      ProvisionedThroughput:
-        ReadCapacityUnits: "5"
-        WriteCapacityUnits: "5"
-      TableName: !Ref BasicTestJavaTableName
-
-  BasicTestDotnetTable:
-    Type: AWS::DynamoDB::Table
-    Properties:
-      AttributeDefinitions:
-        - AttributeName: "partition_key"
-          AttributeType: "S"
-        - AttributeName: "sort_key"
-          AttributeType: "N"
-      KeySchema:
-        - AttributeName: "partition_key"
-          KeyType: "HASH"
-        - AttributeName: "sort_key"
-          KeyType: "RANGE"
-      ProvisionedThroughput:
-        ReadCapacityUnits: "5"
-        WriteCapacityUnits: "5"
-      TableName: !Ref BasicTestDotnetTableName
-
-  SearchTestJavaTable:
-    Type: AWS::DynamoDB::Table
-    Properties:
-      AttributeDefinitions:
-        - AttributeName: "aws_dbe_b_inspector_id_last4"
-          AttributeType: "S"
-        - AttributeName: "aws_dbe_b_last4UnitCompound"
-          AttributeType: "S"
-        - AttributeName: "aws_dbe_b_unit"
-          AttributeType: "S"
-        - AttributeName: "inspection_date"
-          AttributeType: "S"
-        - AttributeName: "work_id"
-          AttributeType: "S"
-      KeySchema:
-        - AttributeName: "work_id"
-          KeyType: "HASH"
-        - AttributeName: "inspection_date"
-          KeyType: "RANGE"
-      ProvisionedThroughput:
-        ReadCapacityUnits: "5"
-        WriteCapacityUnits: "5"
-      TableName: !Ref SearchTestJavaTableName
-      GlobalSecondaryIndexes:
-        - IndexName: "last4-unit-index"
-          KeySchema:
-            - AttributeName: "aws_dbe_b_inspector_id_last4"
-              KeyType: "HASH"
-            - AttributeName: "aws_dbe_b_unit"
-              KeyType: "RANGE"
-          Projection:
-            ProjectionType: ALL
-          ProvisionedThroughput:
-            ReadCapacityUnits: "5"
-            WriteCapacityUnits: "5"
-        - IndexName: "last4UnitCompound-index"
-          KeySchema:
-            - AttributeName: "aws_dbe_b_last4UnitCompound"
-              KeyType: "HASH"
-          Projection:
-            ProjectionType: ALL
-          ProvisionedThroughput:
-            ReadCapacityUnits: "5"
-            WriteCapacityUnits: "5"
-
-  SearchTestDotnetTable:
-    Type: AWS::DynamoDB::Table
-    Properties:
-      AttributeDefinitions:
-        - AttributeName: "aws_dbe_b_inspector_id_last4"
-          AttributeType: "S"
-        - AttributeName: "aws_dbe_b_last4UnitCompound"
-          AttributeType: "S"
-        - AttributeName: "aws_dbe_b_unit"
-          AttributeType: "S"
-        - AttributeName: "inspection_date"
-          AttributeType: "S"
-        - AttributeName: "work_id"
-          AttributeType: "S"
-      KeySchema:
-        - AttributeName: "work_id"
-          KeyType: "HASH"
-        - AttributeName: "inspection_date"
-          KeyType: "RANGE"
-      ProvisionedThroughput:
-        ReadCapacityUnits: "5"
-        WriteCapacityUnits: "5"
-      TableName: !Ref SearchTestDotnetTableName
-      GlobalSecondaryIndexes:
-        - IndexName: "last4-unit-index"
-          KeySchema:
-            - AttributeName: "aws_dbe_b_inspector_id_last4"
-              KeyType: "HASH"
-            - AttributeName: "aws_dbe_b_unit"
-              KeyType: "RANGE"
-          Projection:
-            ProjectionType: ALL
-          ProvisionedThroughput:
-            ReadCapacityUnits: "5"
-            WriteCapacityUnits: "5"
-        - IndexName: "last4UnitCompound-index"
-          KeySchema:
-            - AttributeName: "aws_dbe_b_last4UnitCompound"
-              KeyType: "HASH"
-          Projection:
-            ProjectionType: ALL
-          ProvisionedThroughput:
-            ReadCapacityUnits: "5"
-            WriteCapacityUnits: "5"
+  # These tables were manually created but not used in CI
+  # If we have to start using them in CI we just have to add
+  # them to the policy below.
+  # BasicTestJavaTable:
+  # BasicTestDotnetTable:
+  # SearchTestJavaTable:
+  # SearchTestDotnetTable:
 
   TestTableWithSimpleBeaconIndex:
     Type: AWS::DynamoDB::Table
@@ -384,7 +266,7 @@ Resources:
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${KeystoreTableName}"
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${KeystoreTableName}/index/*"
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${BasicTestJavaTableName}"
-              - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${BasicTestDotnetTableName}"
+              - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${BasicTestDotNetTableName}"
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${SearchTestJavaTableName}"
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${SearchTestJavaTableName}/index/*"
               - !Sub "arn:aws:dynamodb:${AWS::Region}:${AWS::AccountId}:table/${SearchTestDotnetTableName}"
@@ -450,6 +332,7 @@ Resources:
         - Fn::ImportValue: "Polymorph-CA-GitHubCAReadPolicyArn"
         - "arn:aws:iam::370957321024:policy/ESDK-Dafny-DDB-ReadWriteDelete-us-west-2"
         - "arn:aws:iam::370957321024:policy/Hierarchical-GitHub-KMS-Key-Policy"
+        - "arn:aws:iam::370957321024:policy/Github-ECDH-KMS"
         - !Ref KMSUsage
         - !Ref DDBUsage
       AssumeRolePolicyDocument: !Sub |