feat(client-kms): This feature allows customers to use their keys sto…

…red in KMS to derive a shared secret which can then be used to establish a secured channel for communication, provide proof of possession, or establish trust with other parties.
aws · Jun 13, 2024 · 06c6041 · 06c6041
1 parent 59f9e1a
commit 06c6041
Show file tree

Hide file tree

Showing 27 changed files with 802 additions and 68 deletions.
diff --git a/clients/client-kms/README.md b/clients/client-kms/README.md
@@ -377,6 +377,14 @@ DeleteImportedKeyMaterial
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/kms/command/DeleteImportedKeyMaterialCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Interface/DeleteImportedKeyMaterialCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Interface/DeleteImportedKeyMaterialCommandOutput/)
 
+</details>
+<details>
+<summary>
+DeriveSharedSecret
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/kms/command/DeriveSharedSecretCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Interface/DeriveSharedSecretCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-kms/Interface/DeriveSharedSecretCommandOutput/)
+
 </details>
 <details>
 <summary>

diff --git a/clients/client-kms/src/KMS.ts b/clients/client-kms/src/KMS.ts
@@ -32,6 +32,11 @@ import {
   DeleteImportedKeyMaterialCommandInput,
   DeleteImportedKeyMaterialCommandOutput,
 } from "./commands/DeleteImportedKeyMaterialCommand";
+import {
+  DeriveSharedSecretCommand,
+  DeriveSharedSecretCommandInput,
+  DeriveSharedSecretCommandOutput,
+} from "./commands/DeriveSharedSecretCommand";
 import {
   DescribeCustomKeyStoresCommand,
   DescribeCustomKeyStoresCommandInput,
@@ -191,6 +196,7 @@ const commands = {
   DeleteAliasCommand,
   DeleteCustomKeyStoreCommand,
   DeleteImportedKeyMaterialCommand,
+  DeriveSharedSecretCommand,
   DescribeCustomKeyStoresCommand,
   DescribeKeyCommand,
   DisableKeyCommand,
@@ -377,6 +383,23 @@ export interface KMS {
     cb: (err: any, data?: DeleteImportedKeyMaterialCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link DeriveSharedSecretCommand}
+   */
+  deriveSharedSecret(
+    args: DeriveSharedSecretCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<DeriveSharedSecretCommandOutput>;
+  deriveSharedSecret(
+    args: DeriveSharedSecretCommandInput,
+    cb: (err: any, data?: DeriveSharedSecretCommandOutput) => void
+  ): void;
+  deriveSharedSecret(
+    args: DeriveSharedSecretCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: DeriveSharedSecretCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link DescribeCustomKeyStoresCommand}
    */

diff --git a/clients/client-kms/src/KMSClient.ts b/clients/client-kms/src/KMSClient.ts
@@ -75,6 +75,7 @@ import {
   DeleteImportedKeyMaterialCommandInput,
   DeleteImportedKeyMaterialCommandOutput,
 } from "./commands/DeleteImportedKeyMaterialCommand";
+import { DeriveSharedSecretCommandInput, DeriveSharedSecretCommandOutput } from "./commands/DeriveSharedSecretCommand";
 import {
   DescribeCustomKeyStoresCommandInput,
   DescribeCustomKeyStoresCommandOutput,
@@ -178,6 +179,7 @@ export type ServiceInputTypes =
   | DeleteAliasCommandInput
   | DeleteCustomKeyStoreCommandInput
   | DeleteImportedKeyMaterialCommandInput
+  | DeriveSharedSecretCommandInput
   | DescribeCustomKeyStoresCommandInput
   | DescribeKeyCommandInput
   | DisableKeyCommandInput
@@ -235,6 +237,7 @@ export type ServiceOutputTypes =
   | DeleteAliasCommandOutput
   | DeleteCustomKeyStoreCommandOutput
   | DeleteImportedKeyMaterialCommandOutput
+  | DeriveSharedSecretCommandOutput
   | DescribeCustomKeyStoresCommandOutput
   | DescribeKeyCommandOutput
   | DisableKeyCommandOutput

diff --git a/clients/client-kms/src/commands/CreateGrantCommand.ts b/clients/client-kms/src/commands/CreateGrantCommand.ts
@@ -104,7 +104,7 @@ export interface CreateGrantCommandOutput extends CreateGrantResponse, __Metadat
  *   GranteePrincipal: "STRING_VALUE", // required
  *   RetiringPrincipal: "STRING_VALUE",
  *   Operations: [ // GrantOperationList // required
- *     "Decrypt" || "Encrypt" || "GenerateDataKey" || "GenerateDataKeyWithoutPlaintext" || "ReEncryptFrom" || "ReEncryptTo" || "Sign" || "Verify" || "GetPublicKey" || "CreateGrant" || "RetireGrant" || "DescribeKey" || "GenerateDataKeyPair" || "GenerateDataKeyPairWithoutPlaintext" || "GenerateMac" || "VerifyMac",
+ *     "Decrypt" || "Encrypt" || "GenerateDataKey" || "GenerateDataKeyWithoutPlaintext" || "ReEncryptFrom" || "ReEncryptTo" || "Sign" || "Verify" || "GetPublicKey" || "CreateGrant" || "RetireGrant" || "DescribeKey" || "GenerateDataKeyPair" || "GenerateDataKeyPairWithoutPlaintext" || "GenerateMac" || "VerifyMac" || "DeriveSharedSecret",
  *   ],
  *   Constraints: { // GrantConstraints
  *     EncryptionContextSubset: { // EncryptionContextType

diff --git a/clients/client-kms/src/commands/CreateKeyCommand.ts b/clients/client-kms/src/commands/CreateKeyCommand.ts
@@ -71,9 +71,12 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  *                <p>Asymmetric KMS keys contain an RSA key pair, Elliptic Curve (ECC) key pair, or an
  *             SM2 key pair (China Regions only). The private key in an asymmetric KMS key never leaves
  *             KMS unencrypted. However, you can use the <a>GetPublicKey</a> operation to
- *             download the public key so it can be used outside of KMS. KMS keys with RSA or SM2 key
- *             pairs can be used to encrypt or decrypt data or sign and verify messages (but not both).
- *             KMS keys with ECC key pairs can be used only to sign and verify messages. For
+ *             download the public key so it can be used outside of KMS. Each KMS key can have only one key usage. KMS keys with RSA key
+ *             pairs can be used to encrypt and decrypt data or sign and verify messages (but not both).
+ *             KMS keys with NIST-recommended ECC key pairs can be used to sign and verify messages or
+ *             derive shared secrets (but not both). KMS keys with <code>ECC_SECG_P256K1</code>
+ *             can be used only to sign and verify messages. KMS keys with SM2 key pairs (China Regions only)
+ *             can be used to either encrypt and decrypt data, sign and verify messages, or derive shared secrets (you must choose one key usage type). For
  *             information about asymmetric KMS keys, see <a href="https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html">Asymmetric KMS keys</a> in the
  *             <i>Key Management Service Developer Guide</i>.</p>
  *                <p> </p>
@@ -204,7 +207,7 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  * const input = { // CreateKeyRequest
  *   Policy: "STRING_VALUE",
  *   Description: "STRING_VALUE",
- *   KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC",
+ *   KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC" || "KEY_AGREEMENT",
  *   CustomerMasterKeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2",
  *   KeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2",
  *   Origin: "AWS_KMS" || "EXTERNAL" || "AWS_CLOUDHSM" || "EXTERNAL_KEY_STORE",
@@ -229,7 +232,7 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  * //     CreationDate: new Date("TIMESTAMP"),
  * //     Enabled: true || false,
  * //     Description: "STRING_VALUE",
- * //     KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC",
+ * //     KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC" || "KEY_AGREEMENT",
  * //     KeyState: "Creating" || "Enabled" || "Disabled" || "PendingDeletion" || "PendingImport" || "PendingReplicaDeletion" || "Unavailable" || "Updating",
  * //     DeletionDate: new Date("TIMESTAMP"),
  * //     ValidTo: new Date("TIMESTAMP"),
@@ -246,6 +249,9 @@ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBea
  * //     SigningAlgorithms: [ // SigningAlgorithmSpecList
  * //       "RSASSA_PSS_SHA_256" || "RSASSA_PSS_SHA_384" || "RSASSA_PSS_SHA_512" || "RSASSA_PKCS1_V1_5_SHA_256" || "RSASSA_PKCS1_V1_5_SHA_384" || "RSASSA_PKCS1_V1_5_SHA_512" || "ECDSA_SHA_256" || "ECDSA_SHA_384" || "ECDSA_SHA_512" || "SM2DSA",
  * //     ],
+ * //     KeyAgreementAlgorithms: [ // KeyAgreementAlgorithmSpecList
+ * //       "ECDH",
+ * //     ],
  * //     MultiRegion: true || false,
  * //     MultiRegionConfiguration: { // MultiRegionConfiguration
  * //       MultiRegionKeyType: "PRIMARY" || "REPLICA",

diff --git a/clients/client-kms/src/commands/DecryptCommand.ts b/clients/client-kms/src/commands/DecryptCommand.ts
@@ -207,7 +207,8 @@ export interface DecryptCommandOutput extends DecryptResponse, __MetadataBearer
  *         <code>KeyUsage</code> must be <code>ENCRYPT_DECRYPT</code>. For signing and verifying
  *       messages, the <code>KeyUsage</code> must be <code>SIGN_VERIFY</code>. For generating and
  *       verifying message authentication codes (MACs), the <code>KeyUsage</code> must be
- *         <code>GENERATE_VERIFY_MAC</code>. To find the <code>KeyUsage</code> of a KMS key, use the
+ *         <code>GENERATE_VERIFY_MAC</code>. For deriving key agreement secrets, the
+ *       <code>KeyUsage</code> must be <code>KEY_AGREEMENT</code>. To find the <code>KeyUsage</code> of a KMS key, use the
  *         <a>DescribeKey</a> operation.</p>
  *          <p>To find the encryption or signing algorithms supported for a particular KMS key, use the
  *         <a>DescribeKey</a> operation.</p>