feat(client-payment-cryptography-data): Adding support for dynamic keys for encrypt, decrypt, re-encrypt and translate pin functions. With this change, customers can use one-time TR-31 keys directly in dataplane operations without the need to first import them into the service.

Author: awstools

clients/client-payment-cryptography-data/src/commands/DecryptDataCommand.ts

@@ -98,6 +98,12 @@ export interface DecryptDataCommandOutput extends DecryptDataOutput, __MetadataB
  *       InitializationVector: "STRING_VALUE",
  *     },
  *   },
+ *   WrappedKey: { // WrappedKey
+ *     WrappedKeyMaterial: { // WrappedKeyMaterial Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
  * };
  * const command = new DecryptDataCommand(input);
  * const response = await client.send(command);

clients/client-payment-cryptography-data/src/commands/EncryptDataCommand.ts

@@ -104,6 +104,12 @@ export interface EncryptDataCommandOutput extends EncryptDataOutput, __MetadataB
  *       InitializationVector: "STRING_VALUE",
  *     },
  *   },
+ *   WrappedKey: { // WrappedKey
+ *     WrappedKeyMaterial: { // WrappedKeyMaterial Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
  * };
  * const command = new EncryptDataCommand(input);
  * const response = await client.send(command);

clients/client-payment-cryptography-data/src/commands/ReEncryptDataCommand.ts

@@ -37,9 +37,9 @@ export interface ReEncryptDataCommandInput extends ReEncryptDataInput {}
 export interface ReEncryptDataCommandOutput extends ReEncryptDataOutput, __MetadataBearer {}
 
 /**
- * <p>Re-encrypt ciphertext using DUKPT, Symmetric and Asymmetric  Data Encryption Keys. </p>
- *          <p>You can either generate an encryption key within Amazon Web Services Payment Cryptography by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a> or import your own encryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. The <code>KeyArn</code> for use with this operation must be in a compatible key state with <code>KeyModesOfUse</code> set to <code>Encrypt</code>. In asymmetric encryption, ciphertext is encrypted using public component (imported by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>) of the asymmetric key pair created outside of Amazon Web Services Payment Cryptography. </p>
- *          <p>For symmetric and DUKPT encryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> and <code>AES</code> algorithms. For asymmetric encryption, Amazon Web Services Payment Cryptography supports <code>RSA</code>. To encrypt using DUKPT, a DUKPT key must already exist within your account with <code>KeyModesOfUse</code> set to <code>DeriveKey</code> or a new DUKPT can be generated by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a>.</p>
+ * <p>Re-encrypt ciphertext using DUKPT or Symmetric data encryption keys. </p>
+ *          <p>You can either generate an encryption key within Amazon Web Services Payment Cryptography by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a> or import your own encryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. The <code>KeyArn</code> for use with this operation must be in a compatible key state with <code>KeyModesOfUse</code> set to <code>Encrypt</code>. </p>
+ *          <p>For symmetric and DUKPT encryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> and <code>AES</code> algorithms. To encrypt using DUKPT, a DUKPT key must already exist within your account with <code>KeyModesOfUse</code> set to <code>DeriveKey</code> or a new DUKPT can be generated by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a>.</p>
  *          <p>For information about valid keys for this operation, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-validattributes.html">Understanding key attributes</a> and <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/crypto-ops-validkeys-ops.html">Key types for specific data operations</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>. </p>
  *          <p>
  *             <b>Cross-account use</b>: This operation can't be used across different Amazon Web Services accounts.</p>
@@ -106,6 +106,18 @@ export interface ReEncryptDataCommandOutput extends ReEncryptDataOutput, __Metad
  *       InitializationVector: "STRING_VALUE",
  *     },
  *   },
+ *   IncomingWrappedKey: { // WrappedKey
+ *     WrappedKeyMaterial: { // WrappedKeyMaterial Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
+ *   OutgoingWrappedKey: {
+ *     WrappedKeyMaterial: {//  Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
  * };
  * const command = new ReEncryptDataCommand(input);
  * const response = await client.send(command);

clients/client-payment-cryptography-data/src/commands/TranslatePinDataCommand.ts

@@ -102,6 +102,18 @@ export interface TranslatePinDataCommandOutput extends TranslatePinDataOutput, _
  *     DukptKeyDerivationType: "STRING_VALUE",
  *     DukptKeyVariant: "STRING_VALUE",
  *   },
+ *   IncomingWrappedKey: { // WrappedKey
+ *     WrappedKeyMaterial: { // WrappedKeyMaterial Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
+ *   OutgoingWrappedKey: {
+ *     WrappedKeyMaterial: {//  Union: only one key present
+ *       Tr31KeyBlock: "STRING_VALUE",
+ *     },
+ *     KeyCheckValueAlgorithm: "STRING_VALUE",
+ *   },
  * };
  * const command = new TranslatePinDataCommand(input);
  * const response = await client.send(command);

clients/client-payment-cryptography-data/src/models/models_0.ts

@@ -953,12 +953,84 @@ export namespace EncryptionDecryptionAttributes {
   };
 }
 
+/**
+ * @public
+ * @enum
+ */
+export const KeyCheckValueAlgorithm = {
+  ANSI_X9_24: "ANSI_X9_24",
+  CMAC: "CMAC",
+} as const;
+
+/**
+ * @public
+ */
+export type KeyCheckValueAlgorithm = (typeof KeyCheckValueAlgorithm)[keyof typeof KeyCheckValueAlgorithm];
+
+/**
+ * <p>Parameter information of a WrappedKeyBlock for encryption key exchange.</p>
+ * @public
+ */
+export type WrappedKeyMaterial = WrappedKeyMaterial.Tr31KeyBlockMember | WrappedKeyMaterial.$UnknownMember;
+
+/**
+ * @public
+ */
+export namespace WrappedKeyMaterial {
+  /**
+   * <p>The TR-31 wrapped key block.</p>
+   * @public
+   */
+  export interface Tr31KeyBlockMember {
+    Tr31KeyBlock: string;
+    $unknown?: never;
+  }
+
+  /**
+   * @public
+   */
+  export interface $UnknownMember {
+    Tr31KeyBlock?: never;
+    $unknown: [string, any];
+  }
+
+  export interface Visitor<T> {
+    Tr31KeyBlock: (value: string) => T;
+    _: (name: string, value: any) => T;
+  }
+
+  export const visit = <T>(value: WrappedKeyMaterial, visitor: Visitor<T>): T => {
+    if (value.Tr31KeyBlock !== undefined) return visitor.Tr31KeyBlock(value.Tr31KeyBlock);
+    return visitor._(value.$unknown[0], value.$unknown[1]);
+  };
+}
+
+/**
+ * <p>Parameter information of a WrappedKeyBlock for encryption key exchange.</p>
+ * @public
+ */
+export interface WrappedKey {
+  /**
+   * <p>Parameter information of a WrappedKeyBlock for encryption key exchange.</p>
+   * @public
+   */
+  WrappedKeyMaterial: WrappedKeyMaterial | undefined;
+
+  /**
+   * <p>The algorithm that Amazon Web Services Payment Cryptography uses to calculate the key check value (KCV). It is used to validate the key integrity.</p>
+   *          <p>For TDES keys, the KCV is computed by encrypting 8 bytes, each with value of zero, with the key to be checked and retaining the 3 highest order bytes of the encrypted result. For AES keys, the KCV is computed using a CMAC algorithm where the input data is 16 bytes of zero and retaining the 3 highest order bytes of the encrypted result.</p>
+   * @public
+   */
+  KeyCheckValueAlgorithm?: KeyCheckValueAlgorithm;
+}
+
 /**
  * @public
  */
 export interface DecryptDataInput {
   /**
    * <p>The <code>keyARN</code> of the encryption key that Amazon Web Services Payment Cryptography uses for ciphertext decryption.</p>
+   *          <p>When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.</p>
    * @public
    */
   KeyIdentifier: string | undefined;
@@ -974,6 +1046,12 @@ export interface DecryptDataInput {
    * @public
    */
   DecryptionAttributes: EncryptionDecryptionAttributes | undefined;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key for ciphertext decryption.</p>
+   * @public
+   */
+  WrappedKey?: WrappedKey;
 }
 
 /**
@@ -1164,6 +1242,7 @@ export interface DukptDerivationAttributes {
 export interface EncryptDataInput {
   /**
    * <p>The <code>keyARN</code> of the encryption key that Amazon Web Services Payment Cryptography uses for plaintext encryption.</p>
+   *          <p>When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.</p>
    * @public
    */
   KeyIdentifier: string | undefined;
@@ -1182,6 +1261,12 @@ export interface EncryptDataInput {
    * @public
    */
   EncryptionAttributes: EncryptionDecryptionAttributes | undefined;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key for plaintext encryption.</p>
+   * @public
+   */
+  WrappedKey?: WrappedKey;
 }
 
 /**
@@ -2109,6 +2194,7 @@ export namespace ReEncryptionAttributes {
 export interface ReEncryptDataInput {
   /**
    * <p>The <code>keyARN</code> of the encryption key of incoming ciphertext data.</p>
+   *          <p>When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key. Otherwise, it is the key identifier used to perform the operation.</p>
    * @public
    */
   IncomingKeyIdentifier: string | undefined;
@@ -2136,6 +2222,18 @@ export interface ReEncryptDataInput {
    * @public
    */
   OutgoingEncryptionAttributes: ReEncryptionAttributes | undefined;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key of incoming ciphertext data.</p>
+   * @public
+   */
+  IncomingWrappedKey?: WrappedKey;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key of outgoing ciphertext data after encryption by Amazon Web Services Payment Cryptography.</p>
+   * @public
+   */
+  OutgoingWrappedKey?: WrappedKey;
 }
 
 /**
@@ -2277,6 +2375,7 @@ export namespace TranslationIsoFormats {
 export interface TranslatePinDataInput {
   /**
    * <p>The <code>keyARN</code> of the encryption key under which incoming PIN block data is encrypted. This key type can be PEK or BDK.</p>
+   *          <p>When a WrappedKeyBlock is provided, this value will be the identifier to the key wrapping key for PIN block. Otherwise, it is the key identifier used to perform the operation.</p>
    * @public
    */
   IncomingKeyIdentifier: string | undefined;
@@ -2316,6 +2415,18 @@ export interface TranslatePinDataInput {
    * @public
    */
   OutgoingDukptAttributes?: DukptDerivationAttributes;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key under which incoming PIN block data is encrypted.</p>
+   * @public
+   */
+  IncomingWrappedKey?: WrappedKey;
+
+  /**
+   * <p>The WrappedKeyBlock containing the encryption key for encrypting outgoing PIN block data.</p>
+   * @public
+   */
+  OutgoingWrappedKey?: WrappedKey;
 }
 
 /**
@@ -2973,6 +3084,22 @@ export const EncryptionDecryptionAttributesFilterSensitiveLog = (obj: Encryption
   if (obj.$unknown !== undefined) return { [obj.$unknown[0]]: "UNKNOWN" };
 };
 
+/**
+ * @internal
+ */
+export const WrappedKeyMaterialFilterSensitiveLog = (obj: WrappedKeyMaterial): any => {
+  if (obj.Tr31KeyBlock !== undefined) return { Tr31KeyBlock: SENSITIVE_STRING };
+  if (obj.$unknown !== undefined) return { [obj.$unknown[0]]: "UNKNOWN" };
+};
+
+/**
+ * @internal
+ */
+export const WrappedKeyFilterSensitiveLog = (obj: WrappedKey): any => ({
+  ...obj,
+  ...(obj.WrappedKeyMaterial && { WrappedKeyMaterial: WrappedKeyMaterialFilterSensitiveLog(obj.WrappedKeyMaterial) }),
+});
+
 /**
  * @internal
  */
@@ -2982,6 +3109,7 @@ export const DecryptDataInputFilterSensitiveLog = (obj: DecryptDataInput): any =
   ...(obj.DecryptionAttributes && {
     DecryptionAttributes: EncryptionDecryptionAttributesFilterSensitiveLog(obj.DecryptionAttributes),
   }),
+  ...(obj.WrappedKey && { WrappedKey: WrappedKeyFilterSensitiveLog(obj.WrappedKey) }),
 });
 
 /**
@@ -3001,6 +3129,7 @@ export const EncryptDataInputFilterSensitiveLog = (obj: EncryptDataInput): any =
   ...(obj.EncryptionAttributes && {
     EncryptionAttributes: EncryptionDecryptionAttributesFilterSensitiveLog(obj.EncryptionAttributes),
   }),
+  ...(obj.WrappedKey && { WrappedKey: WrappedKeyFilterSensitiveLog(obj.WrappedKey) }),
 });
 
 /**
@@ -3080,6 +3209,8 @@ export const ReEncryptDataInputFilterSensitiveLog = (obj: ReEncryptDataInput): a
   ...(obj.OutgoingEncryptionAttributes && {
     OutgoingEncryptionAttributes: ReEncryptionAttributesFilterSensitiveLog(obj.OutgoingEncryptionAttributes),
   }),
+  ...(obj.IncomingWrappedKey && { IncomingWrappedKey: WrappedKeyFilterSensitiveLog(obj.IncomingWrappedKey) }),
+  ...(obj.OutgoingWrappedKey && { OutgoingWrappedKey: WrappedKeyFilterSensitiveLog(obj.OutgoingWrappedKey) }),
 });
 
 /**
@@ -3124,6 +3255,8 @@ export const TranslatePinDataInputFilterSensitiveLog = (obj: TranslatePinDataInp
     OutgoingTranslationAttributes: TranslationIsoFormatsFilterSensitiveLog(obj.OutgoingTranslationAttributes),
   }),
   ...(obj.EncryptedPinBlock && { EncryptedPinBlock: SENSITIVE_STRING }),
+  ...(obj.IncomingWrappedKey && { IncomingWrappedKey: WrappedKeyFilterSensitiveLog(obj.IncomingWrappedKey) }),
+  ...(obj.OutgoingWrappedKey && { OutgoingWrappedKey: WrappedKeyFilterSensitiveLog(obj.OutgoingWrappedKey) }),
 });
 
 /**

clients/client-payment-cryptography-data/src/protocols/Aws_restJson1.ts

@@ -96,6 +96,8 @@ import {
   VisaPin,
   VisaPinVerification,
   VisaPinVerificationValue,
+  WrappedKey,
+  WrappedKeyMaterial,
 } from "../models/models_0";
 import { PaymentCryptographyDataServiceException as __BaseException } from "../models/PaymentCryptographyDataServiceException";
 
@@ -117,6 +119,7 @@ export const se_DecryptDataCommand = async (
     take(input, {
       CipherText: [],
       DecryptionAttributes: (_) => _json(_),
+      WrappedKey: (_) => _json(_),
     })
   );
   b.m("POST").h(headers).b(body);
@@ -141,6 +144,7 @@ export const se_EncryptDataCommand = async (
     take(input, {
       EncryptionAttributes: (_) => _json(_),
       PlainText: [],
+      WrappedKey: (_) => _json(_),
     })
   );
   b.m("POST").h(headers).b(body);
@@ -242,8 +246,10 @@ export const se_ReEncryptDataCommand = async (
     take(input, {
       CipherText: [],
       IncomingEncryptionAttributes: (_) => _json(_),
+      IncomingWrappedKey: (_) => _json(_),
       OutgoingEncryptionAttributes: (_) => _json(_),
       OutgoingKeyIdentifier: [],
+      OutgoingWrappedKey: (_) => _json(_),
     })
   );
   b.m("POST").h(headers).b(body);
@@ -269,9 +275,11 @@ export const se_TranslatePinDataCommand = async (
       IncomingDukptAttributes: (_) => _json(_),
       IncomingKeyIdentifier: [],
       IncomingTranslationAttributes: (_) => _json(_),
+      IncomingWrappedKey: (_) => _json(_),
       OutgoingDukptAttributes: (_) => _json(_),
       OutgoingKeyIdentifier: [],
       OutgoingTranslationAttributes: (_) => _json(_),
+      OutgoingWrappedKey: (_) => _json(_),
     })
   );
   b.m("POST").h(headers).b(body);
@@ -883,6 +891,10 @@ const de_VerificationFailedExceptionRes = async (
 
 // se_VisaPinVerificationValue omitted.
 
+// se_WrappedKey omitted.
+
+// se_WrappedKeyMaterial omitted.
+
 // de_PinData omitted.
 
 // de_ValidationExceptionField omitted.