chore: Add ECDH examples (#1461)

Co-authored-by: Lucas McDonald <[email protected]>

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";