Generating keys
You can create AWS Payment Cryptography keys by using the CreateKey API operation. During this process, you will specify various attributes of the key or the resultant output such as the key algorithm (for example, TDES_3KEY), the KeyUsage (for example TR31_P0_PIN_ENCRYPTION_KEY) , permitted operations (for example, encrypt, signing) and whether it is exportable. You cannot change these properties after the AWS Payment Cryptography key is created.
Examples
Generating a 2KEY TDES key
This command generates a 2KEY TDES key for the purpose of generating and verifying CVV/CVV2 values. The response echos back the request parameters, including an ARN for subsequent calls as well as a KCV (Key Check Value).
$aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=TDES_2KEY,\ KeyUsage=TR31_C0_CARD_VERIFICATION_KEY,KeyClass=SYMMETRIC_KEY, \ KeyModesOfUse='{Generate=true,Verify=true}'
{ "Key": { "CreateTimestamp": "2022-10-26T16:04:11.642000-07:00", "Enabled": true, "Exportable": true, "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/hjprdg5o4jtgs5tw", "KeyAttributes": { "KeyAlgorithm": "TDES_2KEY", "KeyClass": "SYMMETRIC_KEY", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": false, "Encrypt": false, "Generate": true, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": true, "Wrap": false }, "KeyUsage": "TR31_C0_CARD_VERIFICATION_KEY" }, "KeyCheckValue": "B72F", "KeyCheckValueAlgorithm": "ANSI_X9_24", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2022-10-26T16:04:11.559000-07:00" } }
Generating a Pin Encryption Key
Example Generating a Pin Encryption Key (PEK)
This command generates a 3KEY TDES key for the purpose of encrypting PIN values (known as a Pin Encryption Key). This key may be used for securing storing PINs or for decrypting PINs provided during a verification attempt, for example during a transaction. The response echos back the request parameters, including an ARN for subsequent calls as well as a KCV (Key Check Value).
$aws payment-cryptography create-key --exportable --key-attributes \ KeyAlgorithm=TDES_3KEY,KeyUsage=TR31_P0_PIN_ENCRYPTION_KEY, \ KeyClass=SYMMETRIC_KEY,/ KeyModesOfUse='{Encrypt=true,Decrypt=true,Wrap=true,Unwrap=true}'
{ "Key": { "CreateTimestamp": "2022-10-27T08:27:51.795000-07:00", "Enabled": true, "Exportable": true, "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h", "KeyAttributes": { "KeyAlgorithm": "TDES_3KEY", "KeyClass": "SYMMETRIC_KEY", "KeyModesOfUse": { "Decrypt": true, "DeriveKey": false, "Encrypt": true, "Generate": false, "NoRestrictions": false, "Sign": false, "Unwrap": true, "Verify": false, "Wrap": true }, "KeyUsage": "TR31_P0_PIN_ENCRYPTION_KEY" }, "KeyCheckValue": "9CA6", "KeyCheckValueAlgorithm": "ANSI_X9_24", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2022-10-27T08:27:51.753000-07:00" } }
Create an asymmetric (RSA) key
In this example, we will generate a new asymmetric RSA 2048 bit key pair. A new private key will be generated as well as the matching public key. The public key can be retrieved using the getPublicCertificate API.
$aws payment-cryptography create-key --exportable \ --key-attributes KeyAlgorithm=RSA_2048,KeyUsage=TR31_D1_ASYMMETRIC_KEY_FOR_DATA_ENCRYPTION, \ KeyClass=ASYMMETRIC_KEY_PAIR,KeyModesOfUse='{Encrypt=true, Decrypt=True,Wrap=True,Unwrap=True}'
{ "Key": { "CreateTimestamp": "2022-11-15T11:15:42.358000-08:00", "Enabled": true, "Exportable": true, "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/nsq2i3mbg6sn775f", "KeyAttributes": { "KeyAlgorithm": "RSA_2048", "KeyClass": "ASYMMETRIC_KEY_PAIR", "KeyModesOfUse": { "Decrypt": true, "DeriveKey": false, "Encrypt": true, "Generate": false, "NoRestrictions": false, "Sign": false, "Unwrap": true, "Verify": false, "Wrap": true }, "KeyUsage": "TR31_D1_ASYMMETRIC_KEY_FOR_DATA_ENCRYPTION" }, "KeyCheckValue": "40AD487F", "KeyCheckValueAlgorithm": "CMAC", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2022-11-15T11:15:42.182000-08:00" } }
Generating a PIN Verification Value (PVV) Key
This command generates a 3KEY TDES key for the purpose of generating PVV values (known as a Pin Verification Value). You can use this key for generating a PVV value that can be compared against a subsequent calculated PVV. The response echos back the request parameters, including an ARN for subsequent calls as well as a KCV (Key Check Value).
$aws payment-cryptography create-key --exportable/ --key-attributes KeyAlgorithm=TDES_3KEY,KeyUsage=TR31_V2_VISA_PIN_VERIFICATION_KEY,/ KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate=true,Verify=true}'
{ "Key": { "CreateTimestamp": "2022-10-27T10:22:59.668000-07:00", "Enabled": true, "Exportable": true, "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/j4u4cmnzkelhc6yb", "KeyAttributes": { "KeyAlgorithm": "TDES_3KEY", "KeyClass": "SYMMETRIC_KEY", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": false, "Encrypt": false, "Generate": true, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": true, "Wrap": false }, "KeyUsage": "TR31_V2_VISA_PIN_VERIFICATION_KEY" }, "KeyCheckValue": "5132", "KeyCheckValueAlgorithm": "ANSI_X9_24", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2022-10-27T10:22:59.614000-07:00" } }
Generating an asymmetric ECC key
This command generates an ECC key pair for the purpose of establishing an ECDH (Elliptic Curve Diffie-Hellman) key agreement between two parties by deriving a shared key from their public-private key pairs. Using ECDH, each party generates its own ECC key pair with key purpose K3 and mode of use X and exchange the public keys. Both parties then use their private key and the received public key to establish a shared derived key.
To maintain the single use principle of cryptographic keys in payments, it is recommended to not re-use ECC key pairs for multiple purposes, such as ECDH key derivation and signing.
$aws payment-cryptography create-key --exportable/ --key-attributes KeyAlgorithm=ECC_NIST_P256,KeyUsage=TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT,/ KeyClass=ASYMMETRIC_KEY_PAIR,KeyModesOfUse='{DeriveKey=true}'
{ "Key": { "CreateTimestamp": "2024-10-17T01:31:55.908000+00:00", "Enabled": true, "Exportable": true, "KeyArn": "arn:aws:payment-cryptography:us-west-2:075556953750:key/xzydvquw6ejfxnwq", "KeyAttributes": { "KeyAlgorithm": "ECC_NIST_P256", "KeyClass": "ASYMMETRIC_KEY_PAIR", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": true, "Encrypt": false, "Generate": false, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": false, "Wrap": false }, "KeyUsage": "TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT" }, "KeyCheckValue": "7E34F19F", "KeyCheckValueAlgorithm": "CMAC", "KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2024-10-17T01:31:55.866000+00:00" } }
