feat(client-payment-cryptography-data): Adding new API to generate au…

…thenticated scripts for EMV pin change use cases.
aws · Oct 21, 2024 · 573b4e2 · 573b4e2
1 parent c046f87
commit 573b4e2
Show file tree

Hide file tree

Showing 17 changed files with 1,846 additions and 288 deletions.
diff --git a/clients/client-payment-cryptography-data/README.md b/clients/client-payment-cryptography-data/README.md
@@ -235,6 +235,14 @@ GenerateMac
 
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/payment-cryptography-data/command/GenerateMacCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-payment-cryptography-data/Interface/GenerateMacCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-payment-cryptography-data/Interface/GenerateMacCommandOutput/)
 
+</details>
+<details>
+<summary>
+GenerateMacEmvPinChange
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/payment-cryptography-data/command/GenerateMacEmvPinChangeCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-payment-cryptography-data/Interface/GenerateMacEmvPinChangeCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-payment-cryptography-data/Interface/GenerateMacEmvPinChangeCommandOutput/)
+
 </details>
 <details>
 <summary>

diff --git a/clients/client-payment-cryptography-data/src/PaymentCryptographyData.ts b/clients/client-payment-cryptography-data/src/PaymentCryptographyData.ts
@@ -10,6 +10,11 @@ import {
   GenerateCardValidationDataCommandOutput,
 } from "./commands/GenerateCardValidationDataCommand";
 import { GenerateMacCommand, GenerateMacCommandInput, GenerateMacCommandOutput } from "./commands/GenerateMacCommand";
+import {
+  GenerateMacEmvPinChangeCommand,
+  GenerateMacEmvPinChangeCommandInput,
+  GenerateMacEmvPinChangeCommandOutput,
+} from "./commands/GenerateMacEmvPinChangeCommand";
 import {
   GeneratePinDataCommand,
   GeneratePinDataCommandInput,
@@ -48,6 +53,7 @@ const commands = {
   EncryptDataCommand,
   GenerateCardValidationDataCommand,
   GenerateMacCommand,
+  GenerateMacEmvPinChangeCommand,
   GeneratePinDataCommand,
   ReEncryptDataCommand,
   TranslatePinDataCommand,
@@ -108,6 +114,23 @@ export interface PaymentCryptographyData {
     cb: (err: any, data?: GenerateMacCommandOutput) => void
   ): void;
 
+  /**
+   * @see {@link GenerateMacEmvPinChangeCommand}
+   */
+  generateMacEmvPinChange(
+    args: GenerateMacEmvPinChangeCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<GenerateMacEmvPinChangeCommandOutput>;
+  generateMacEmvPinChange(
+    args: GenerateMacEmvPinChangeCommandInput,
+    cb: (err: any, data?: GenerateMacEmvPinChangeCommandOutput) => void
+  ): void;
+  generateMacEmvPinChange(
+    args: GenerateMacEmvPinChangeCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: GenerateMacEmvPinChangeCommandOutput) => void
+  ): void;
+
   /**
    * @see {@link GeneratePinDataCommand}
    */

diff --git a/clients/client-payment-cryptography-data/src/PaymentCryptographyDataClient.ts b/clients/client-payment-cryptography-data/src/PaymentCryptographyDataClient.ts
@@ -60,6 +60,10 @@ import {
   GenerateCardValidationDataCommandOutput,
 } from "./commands/GenerateCardValidationDataCommand";
 import { GenerateMacCommandInput, GenerateMacCommandOutput } from "./commands/GenerateMacCommand";
+import {
+  GenerateMacEmvPinChangeCommandInput,
+  GenerateMacEmvPinChangeCommandOutput,
+} from "./commands/GenerateMacEmvPinChangeCommand";
 import { GeneratePinDataCommandInput, GeneratePinDataCommandOutput } from "./commands/GeneratePinDataCommand";
 import { ReEncryptDataCommandInput, ReEncryptDataCommandOutput } from "./commands/ReEncryptDataCommand";
 import { TranslatePinDataCommandInput, TranslatePinDataCommandOutput } from "./commands/TranslatePinDataCommand";
@@ -92,6 +96,7 @@ export type ServiceInputTypes =
   | EncryptDataCommandInput
   | GenerateCardValidationDataCommandInput
   | GenerateMacCommandInput
+  | GenerateMacEmvPinChangeCommandInput
   | GeneratePinDataCommandInput
   | ReEncryptDataCommandInput
   | TranslatePinDataCommandInput
@@ -108,6 +113,7 @@ export type ServiceOutputTypes =
   | EncryptDataCommandOutput
   | GenerateCardValidationDataCommandOutput
   | GenerateMacCommandOutput
+  | GenerateMacEmvPinChangeCommandOutput
   | GeneratePinDataCommandOutput
   | ReEncryptDataCommandOutput
   | TranslatePinDataCommandOutput

diff --git a/clients/client-payment-cryptography-data/src/commands/DecryptDataCommand.ts b/clients/client-payment-cryptography-data/src/commands/DecryptDataCommand.ts
@@ -38,7 +38,8 @@ export interface DecryptDataCommandOutput extends DecryptDataOutput, __MetadataB
 
 /**
  * <p>Decrypts ciphertext data to plaintext using a symmetric (TDES, AES), asymmetric (RSA), or derived (DUKPT or EMV) encryption key scheme. For more information, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/decrypt-data.html">Decrypt data</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.</p>
- *          <p>You can use an encryption key generated within Amazon Web Services Payment Cryptography, or you can import your own encryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. For this operation, the key must have <code>KeyModesOfUse</code> set to <code>Decrypt</code>. In asymmetric decryption, Amazon Web Services Payment Cryptography decrypts the ciphertext using the private component of the asymmetric encryption key pair. For data encryption outside of Amazon Web Services Payment Cryptography, you can export the public component of the asymmetric key pair by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_GetPublicKeyCertificate.html">GetPublicCertificate</a>.</p>
+ *          <p>You can use an decryption key generated within Amazon Web Services Payment Cryptography, or you can import your own decryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. For this operation, the key must have <code>KeyModesOfUse</code> set to <code>Decrypt</code>. In asymmetric decryption, Amazon Web Services Payment Cryptography decrypts the ciphertext using the private component of the asymmetric encryption key pair. For data encryption outside of Amazon Web Services Payment Cryptography, you can export the public component of the asymmetric key pair by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_GetPublicKeyCertificate.html">GetPublicCertificate</a>.</p>
+ *          <p>This operation also supports dynamic keys, allowing you to pass a dynamic decryption key as a TR-31 WrappedKeyBlock. This can be used when key material is frequently rotated, such as during every card transaction, and there is need to avoid importing short-lived keys into Amazon Web Services Payment Cryptography. To decrypt using dynamic keys, the <code>keyARN</code> is the Key Encryption Key (KEK) of the TR-31 wrapped decryption key material. The incoming wrapped key shall have a key purpose of D0 with a mode of use of B or D. For more information, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/use-cases-acquirers-dynamickeys.html">Using Dynamic Keys</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.</p>
  *          <p>For symmetric and DUKPT decryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> and <code>AES</code> algorithms. For EMV decryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> algorithms. For asymmetric decryption, Amazon Web Services Payment Cryptography supports <code>RSA</code>. </p>
  *          <p>When you use TDES or TDES DUKPT, the ciphertext data length must be a multiple of 8 bytes. For AES or AES DUKPT, the ciphertext data length must be a multiple of 16 bytes. For RSA, it sould be equal to the key size unless padding is enabled.</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>
@@ -75,26 +76,26 @@ export interface DecryptDataCommandOutput extends DecryptDataOutput, __MetadataB
  *   CipherText: "STRING_VALUE", // required
  *   DecryptionAttributes: { // EncryptionDecryptionAttributes Union: only one key present
  *     Symmetric: { // SymmetricEncryptionAttributes
- *       Mode: "STRING_VALUE", // required
+ *       Mode: "ECB" || "CBC" || "CFB" || "CFB1" || "CFB8" || "CFB64" || "CFB128" || "OFB", // required
  *       InitializationVector: "STRING_VALUE",
- *       PaddingType: "STRING_VALUE",
+ *       PaddingType: "PKCS1" || "OAEP_SHA1" || "OAEP_SHA256" || "OAEP_SHA512",
  *     },
  *     Asymmetric: { // AsymmetricEncryptionAttributes
- *       PaddingType: "STRING_VALUE",
+ *       PaddingType: "PKCS1" || "OAEP_SHA1" || "OAEP_SHA256" || "OAEP_SHA512",
  *     },
  *     Dukpt: { // DukptEncryptionAttributes
  *       KeySerialNumber: "STRING_VALUE", // required
- *       Mode: "STRING_VALUE",
- *       DukptKeyDerivationType: "STRING_VALUE",
- *       DukptKeyVariant: "STRING_VALUE",
+ *       Mode: "ECB" || "CBC",
+ *       DukptKeyDerivationType: "TDES_2KEY" || "TDES_3KEY" || "AES_128" || "AES_192" || "AES_256",
+ *       DukptKeyVariant: "BIDIRECTIONAL" || "REQUEST" || "RESPONSE",
  *       InitializationVector: "STRING_VALUE",
  *     },
  *     Emv: { // EmvEncryptionAttributes
- *       MajorKeyDerivationMode: "STRING_VALUE", // required
+ *       MajorKeyDerivationMode: "EMV_OPTION_A" || "EMV_OPTION_B", // required
  *       PrimaryAccountNumber: "STRING_VALUE", // required
  *       PanSequenceNumber: "STRING_VALUE", // required
  *       SessionDerivationData: "STRING_VALUE", // required
- *       Mode: "STRING_VALUE",
+ *       Mode: "ECB" || "CBC",
  *       InitializationVector: "STRING_VALUE",
  *     },
  *   },

diff --git a/clients/client-payment-cryptography-data/src/commands/EncryptDataCommand.ts b/clients/client-payment-cryptography-data/src/commands/EncryptDataCommand.ts
@@ -38,7 +38,9 @@ export interface EncryptDataCommandOutput extends EncryptDataOutput, __MetadataB
 
 /**
  * <p>Encrypts plaintext data to ciphertext using a symmetric (TDES, AES), asymmetric (RSA), or derived (DUKPT or EMV) encryption key scheme. For more information, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/encrypt-data.html">Encrypt data</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.</p>
- *          <p>You can 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>. You can import your own encryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. For this operation, the key must have <code>KeyModesOfUse</code> set to <code>Encrypt</code>. In asymmetric encryption, plaintext is encrypted using public component. You can import the public component of an asymmetric key pair created outside Amazon Web Services Payment Cryptography by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. </p>
+ *          <p>You can 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>. You can import your own encryption key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>.</p>
+ *          <p>For this operation, the key must have <code>KeyModesOfUse</code> set to <code>Encrypt</code>. In asymmetric encryption, plaintext is encrypted using public component. You can import the public component of an asymmetric key pair created outside Amazon Web Services Payment Cryptography by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html">ImportKey</a>. </p>
+ *          <p>This operation also supports dynamic keys, allowing you to pass a dynamic encryption key as a TR-31 WrappedKeyBlock. This can be used when key material is frequently rotated, such as during every card transaction, and there is need to avoid importing short-lived keys into Amazon Web Services Payment Cryptography. To encrypt using dynamic keys, the <code>keyARN</code> is the Key Encryption Key (KEK) of the TR-31 wrapped encryption key material. The incoming wrapped key shall have a key purpose of D0 with a mode of use of B or D. For more information, see <a href="https://docs.aws.amazon.com/payment-cryptography/latest/userguide/use-cases-acquirers-dynamickeys.html">Using Dynamic Keys</a> in the <i>Amazon Web Services Payment Cryptography User Guide</i>.</p>
  *          <p>For symmetric and DUKPT encryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> and <code>AES</code> algorithms. For EMV encryption, Amazon Web Services Payment Cryptography supports <code>TDES</code> algorithms.For asymmetric encryption, Amazon Web Services Payment Cryptography supports <code>RSA</code>. </p>
  *          <p>When you use TDES or TDES DUKPT, the plaintext data length must be a multiple of 8 bytes. For AES or AES DUKPT, the plaintext data length must be a multiple of 16 bytes. For RSA, it sould be equal to the key size unless padding is enabled.</p>
  *          <p>To encrypt using DUKPT, you must already have a BDK (Base Derivation Key) key in your account with <code>KeyModesOfUse</code> set to <code>DeriveKey</code>, or you can generate a new DUKPT key by calling <a href="https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html">CreateKey</a>. To encrypt using EMV, you must already have an IMK (Issuer Master Key) key in your account with <code>KeyModesOfUse</code> set to <code>DeriveKey</code>.</p>
@@ -81,26 +83,26 @@ export interface EncryptDataCommandOutput extends EncryptDataOutput, __MetadataB
  *   PlainText: "STRING_VALUE", // required
  *   EncryptionAttributes: { // EncryptionDecryptionAttributes Union: only one key present
  *     Symmetric: { // SymmetricEncryptionAttributes
- *       Mode: "STRING_VALUE", // required
+ *       Mode: "ECB" || "CBC" || "CFB" || "CFB1" || "CFB8" || "CFB64" || "CFB128" || "OFB", // required
  *       InitializationVector: "STRING_VALUE",
- *       PaddingType: "STRING_VALUE",
+ *       PaddingType: "PKCS1" || "OAEP_SHA1" || "OAEP_SHA256" || "OAEP_SHA512",
  *     },
  *     Asymmetric: { // AsymmetricEncryptionAttributes
- *       PaddingType: "STRING_VALUE",
+ *       PaddingType: "PKCS1" || "OAEP_SHA1" || "OAEP_SHA256" || "OAEP_SHA512",
  *     },
  *     Dukpt: { // DukptEncryptionAttributes
  *       KeySerialNumber: "STRING_VALUE", // required
- *       Mode: "STRING_VALUE",
- *       DukptKeyDerivationType: "STRING_VALUE",
- *       DukptKeyVariant: "STRING_VALUE",
+ *       Mode: "ECB" || "CBC",
+ *       DukptKeyDerivationType: "TDES_2KEY" || "TDES_3KEY" || "AES_128" || "AES_192" || "AES_256",
+ *       DukptKeyVariant: "BIDIRECTIONAL" || "REQUEST" || "RESPONSE",
  *       InitializationVector: "STRING_VALUE",
  *     },
  *     Emv: { // EmvEncryptionAttributes
- *       MajorKeyDerivationMode: "STRING_VALUE", // required
+ *       MajorKeyDerivationMode: "EMV_OPTION_A" || "EMV_OPTION_B", // required
  *       PrimaryAccountNumber: "STRING_VALUE", // required
  *       PanSequenceNumber: "STRING_VALUE", // required
  *       SessionDerivationData: "STRING_VALUE", // required
- *       Mode: "STRING_VALUE",
+ *       Mode: "ECB" || "CBC",
  *       InitializationVector: "STRING_VALUE",
  *     },
  *   },

diff --git a/clients/client-payment-cryptography-data/src/commands/GenerateMacCommand.ts b/clients/client-payment-cryptography-data/src/commands/GenerateMacCommand.ts
@@ -63,31 +63,31 @@ export interface GenerateMacCommandOutput extends GenerateMacOutput, __MetadataB
  *   KeyIdentifier: "STRING_VALUE", // required
  *   MessageData: "STRING_VALUE", // required
  *   GenerationAttributes: { // MacAttributes Union: only one key present
- *     Algorithm: "STRING_VALUE",
+ *     Algorithm: "ISO9797_ALGORITHM1" || "ISO9797_ALGORITHM3" || "CMAC" || "HMAC_SHA224" || "HMAC_SHA256" || "HMAC_SHA384" || "HMAC_SHA512",
  *     EmvMac: { // MacAlgorithmEmv
- *       MajorKeyDerivationMode: "STRING_VALUE", // required
+ *       MajorKeyDerivationMode: "EMV_OPTION_A" || "EMV_OPTION_B", // required
  *       PrimaryAccountNumber: "STRING_VALUE", // required
  *       PanSequenceNumber: "STRING_VALUE", // required
- *       SessionKeyDerivationMode: "STRING_VALUE", // required
+ *       SessionKeyDerivationMode: "EMV_COMMON_SESSION_KEY" || "EMV2000" || "AMEX" || "MASTERCARD_SESSION_KEY" || "VISA", // required
  *       SessionKeyDerivationValue: { // SessionKeyDerivationValue Union: only one key present
  *         ApplicationCryptogram: "STRING_VALUE",
  *         ApplicationTransactionCounter: "STRING_VALUE",
  *       },
  *     },
  *     DukptIso9797Algorithm1: { // MacAlgorithmDukpt
  *       KeySerialNumber: "STRING_VALUE", // required
- *       DukptKeyVariant: "STRING_VALUE", // required
- *       DukptDerivationType: "STRING_VALUE",
+ *       DukptKeyVariant: "BIDIRECTIONAL" || "REQUEST" || "RESPONSE", // required
+ *       DukptDerivationType: "TDES_2KEY" || "TDES_3KEY" || "AES_128" || "AES_192" || "AES_256",
  *     },
  *     DukptIso9797Algorithm3: {
  *       KeySerialNumber: "STRING_VALUE", // required
- *       DukptKeyVariant: "STRING_VALUE", // required
- *       DukptDerivationType: "STRING_VALUE",
+ *       DukptKeyVariant: "BIDIRECTIONAL" || "REQUEST" || "RESPONSE", // required
+ *       DukptDerivationType: "TDES_2KEY" || "TDES_3KEY" || "AES_128" || "AES_192" || "AES_256",
  *     },
  *     DukptCmac: {
  *       KeySerialNumber: "STRING_VALUE", // required
- *       DukptKeyVariant: "STRING_VALUE", // required
- *       DukptDerivationType: "STRING_VALUE",
+ *       DukptKeyVariant: "BIDIRECTIONAL" || "REQUEST" || "RESPONSE", // required
+ *       DukptDerivationType: "TDES_2KEY" || "TDES_3KEY" || "AES_128" || "AES_192" || "AES_256",
  *     },
  *   },
  *   MacLength: Number("int"),