Export keys - AWS Payment Cryptography

Export keys

Exporting symmetric keys

Important

Examples may require the latest version of the AWS CLI V2. Before getting started, please ensure that you have upgraded to the latest version.

Export keys using asymmetric techniques (TR-34)

Overview: TR-34 utilizes RSA asymmetric cryptography to encrypt symmetric keys for exchange as well as ensuring the source of the data (signing). This ensures both the confidentiality (encryption) and integrity (signature) of the wrapped key. When exporting, AWS Payment Cryptography becomes the key distribution host (KDH) and the target system becomes the key receiving device (KRD).

1. Call the initialize export command

Call get-parameters-for-export to initialize the export process. This API will generate a keypair for the purpose of key exports, sign the key and return back the certificate and certificate root. Ultimately, the private key generated by this command used to sign the export payload. In TR-34 terminology, this is known as the KDH signing cert. Note that these certificates are short lived and are only intended for this purpose. The parameter ParametersValidUntilTimestamp specifies their duration.

NOTE: All certificates are returned in a base64 encoded format

$ aws payment-cryptography get-parameters-for-export \ --signing-key-algorithm RSA_2048 --key-material-type TR34_KEY_BLOCK
{ "SigningKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV2RENDQXFTZ0F3SUJBZ0lRZFAzSzNHNEFKT0I4WTNpTmUvYlF0akFOQmdrcWhraUc5dzBCQVEwRkFEQ0IKaVRFTE1Ba0dBMVVFQmhNQ1ZWTXhHVEFYQmdOVkJBb01FRUZYVXlCRGNubHdkRzluY21Gd2FIa3hJVEFmQmdOVgpCQXNNR0VGWFV5QlFZWGx0Wlc1MElFTnllWEIwYjJkeVlYQm9lVEVSTUE4R0ExVUVDQXdJVm1seVoybHVhV0V4CkZUQVRCZ05WQkFNTUREVXlPVEF5TnpRMU5UUTVOVEVTTUJBR0ExVUVCd3dKUVhKc2FXNW5kRzl1TUI0WERUSXoKTURZd05qSXhOREF5TVZvWERUSXpNRFl4TXpJeU5EQXlNRm93TERFVk1CTUdBMVVFQXd3TU5USTVNREkzTkRVMQpORGsxTVJNd0VRWURWUVFGRXdveE9ETTROemt5TWpNeU1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFBT0NBUThBCk1JSUJDZ0tDQVFFQXNTLzZ0TkhPK29RaTczVFMvYXJFSE40aEhRSjdFVThaT3dXN0RuNVlTTlZmZmM0b1B6ZVUKNHQ5Q045djViamxrL3p5TTJORllVL0NsTHNueFk2Y3IvaWwwY2hROVFtM1hUMHZVWGZGNzdRSzFSWnZzNkVkdApicVFaWGlqVDZ4UkJGcUxUMjV0dGJYQTlXMjlUd1d1eXdVN1c4dDZDZEIxSVFoOFFhYlBGaHRhWmVpWmVVWjNPCnRSa2NZU1VtRDRncWJxTElEL2M2RlpmdGpkYS9HbkhkZ1dmMk5oUUFvVnkxOS9ZZXhlZzdmTlVOZXVzWmRYSWYKZkNpM0VNaFF4S3lYY3dUMC9TZ2g5alZNakQwSDdyZWpCMGF4Tit0RUNqeVFEcm5XS2ZvbVA2ZFdkMExCSUM2bgpNQ1VKcmVtSDV3emVzZjFrWnF1VjRMbjYwdzZSNDNhQzRRSURBUUFCbzN3d2VqQUpCZ05WSFJNRUFqQUFNQjhHCkExVWRJd1FZTUJhQUZDNklyYUZzYnRUMDFGL2JjQ0c3Z3RVR1phM1RNQjBHQTFVZERnUVdCQlRXbldEWXNsMXMKalhnVExRRmFCYm1DakFZcHNUQU9CZ05WSFE4QkFmOEVCQU1DQmFBd0hRWURWUjBsQkJZd0ZBWUlLd1lCQlFVSApBd0VHQ0NzR0FRVUZCd01DTUEwR0NTcUdTSWIzRFFFQkRRVUFBNElDQVFCdUJmVjJmVFBlM0VkSEhnODFoVnZECnRQZUJsQzAvRy8wQ25XNFhPVEt2NUJtNXNudDBpczg4Yzc1SlRRUXdvdm9ScEVUTzZLdXdxMUFuUFR1c3RyRDYKL0I1bDd0MGw3ZUh6Z3pPVGZSN29Wem9TZXlGamkvVEVwK2M0NXBHWDBpY0ovTDlMaE0ybUVOZHhqNmtzVUcxMApuZnJCbzJyejkwRUJQYTVFb1lhMlRYYW90VlU4NFRiSFVyMlUzaFhrRExDWmhpSTdLY2I5cWRwenVlV0dWRzRTCmFreGJQcW5LQjMrek9JSzFZYTl2aENHZjRaMDFtWFFtVmRjQlpnbGE5SWFyeEcvKy9xWXEvNzBKalFnYk5HOUUKcUd1UFFadE5QQ0lJckJXOFN4cVpmUjVJbmxtUDlkZEY0SStOR002aHNoRUNXeWJCWkdUZjhYVCtwYVRFZXA2ZQpZUHp2UXI2cWQ4TExDYk5wOEI3ZTNrcmRKc0VUV0tBaU93TzFoZ1BReld2ZTRWKzBNdVlQaDczNk0xUS9rUTJVCmN5VmhDVDNCWENmOFhXVjMwYzg2c2J2dlhIeGJ5cVl1dWs4anZvRHl6T3R0T0QxbVdlRDBNeXV6OU1Fb3JTanIKM3ZwUDhBWXowMVI0UWNBMUR5cVl1dVErQ1BFRHlqU3VPK2tTQ1JIYXFLRzFOVzY5aVMxWWQyWG9LZTdtRlVpaAp3REM0WTlISlZjNjk5bWNMQ0NXWmhyYlZmZUJrOUxDS1BlUzZWUFZDMGdpVnJRYUtxbFhkTnh5SGJ2ZzBsRlUvCjZkUm5nYmVPMTZQdUhhN1hjL2FCUUF6N3JNaWlvRFFjSVdrQVdyK0NIOHl0UVFXZXRjSFdHNWRMMmZiSFgzOU0KMWhIeXFraHAwdDhXc0dTdVhjbWJBQT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=", "SigningKeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUY0VENDQThtZ0F3SUJBZ0lSQUtlN2piaHFKZjJPd3FGUWI5c3VuOEV3RFFZSktvWklodmNOQVFFTkJRQXcKZ1lreEN6QUpCZ05WQkFZVEFsVlRNUmt3RndZRFZRUUtEQkJCVjFNZ1EzSjVjSFJ2WjNKaGNHaDVNU0V3SHdZRApWUVFMREJoQlYxTWdVR0Y1YldWdWRDQkRjbmx3ZEc5bmNtRndhSGt4RVRBUEJnTlZCQWdNQ0ZacGNtZHBibWxoCk1SVXdFd1lEVlFRRERBdzFNamt3TWpjME5UVTBPVFV4RWpBUUJnTlZCQWNNQ1VGeWJHbHVaM1J2YmpBZUZ3MHkKTXpBMk1EWXdNalEzTlRKYUZ3MHlPREEyTURZd016UTNOVEphTUlHSk1Rc3dDUVlEVlFRR0V3SlZVekVaTUJjRwpBMVVFQ2d3UVFWZFRJRU55ZVhCMGIyZHlZWEJvZVRFaE1COEdBMVVFQ3d3WVFWZFRJRkJoZVcxbGJuUWdRM0o1CmNIUnZaM0poY0doNU1SRXdEd1lEVlFRSURBaFdhWEpuYVc1cFlURVZNQk1HQTFVRUF3d01OVEk1TURJM05EVTEKTkRrMU1SSXdFQVlEVlFRSERBbEJjbXhwYm1kMGIyNHdnZ0lpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElDRHdBdwpnZ0lLQW9JQ0FRQzJyMld2eGJxZjJSUHhOem1JUk5ZeWZRQ2labGxYUVBQSDQycnAyQ1VtTk1VMkc2ZzdFRUZBCm5TWnNvRlN6Z1NJaEhUSWU4UDdUd1l3ckpPL3VNcEtka3lac1ppTEhUNGo4M1l1VkNlT1dSVERjdnRWMFV0M1IKaCs5UWVyaHhRQnVrK2dnZkRkT0FFUkR3S1pWckZqM3diT1FFMXY2WnRYSmpVZytWTXZKcEphUTg0WkFvYnpyUgpuY2JaL0hnbFhDM09xampSSk1laGJFaE93ZFJCTU4yQ2dTNHlhWTB3YlBvazhMSlRORVp5ZnkxUEtkaTd1UmxxCm9qeEdjc3pCRHFvdCsvTURBNVdZUjd5NVhiOGdOdSt0alkrMWdQSGRkWHFhRTR2bXV2cEtsQUttcml2SDRYWXQKZk9sa1kzYnRJckVuWDEwQkp1UXVGN0dRNyt3ZjN6TDZ4NFNIcGpiQWxpMDQyUmdXTVpibmlscW15YnhuUkRrUwpjZXZ3aEx2L0tnT09WM05KZlplWlVzT1N6NWNzTmRLME4rM2FCUlZQcVc5b2k3dDJ2dTc5eCtvb1pIS2FibFdiCmJDMDJxR1VDaTE3cHhDQ0JJdUVDZWJiWDhSS3dLa3RwbTRSOUZWYjBXZGFqNUc1ekdudTBsUlRMUVNaZ0QyU1EKSjRmQjh2em9Bb3BYenpSSStMSjNBaC9NcThXSTNHTHFIakhzcm5vdVJzMmNzcjVBYnNMbXUyUTlvMFJmNTd1RApwK1R1cXpKTysrNFpUWDlsb0N3UXdzKzNEZWUyL1pUSmJCNkFCdy9xdnovQjhsL2duY29Wc3lHTFhkaXdleTV1CjJHNnl2NGgrN0FBQldvdjhwWVBPUlRMY1FkanhVdWNDdllRYjJiRXY4ZGh1anN6TWo2ZDBDUUlEQVFBQm8wSXcKUURBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUIwR0ExVWREZ1FXQkJRdWlLMmhiRzdVOU5SZjIzQWh1NExWQm1XdAowekFPQmdOVkhROEJBZjhFQkFNQ0FZWXdEUVlKS29aSWh2Y05BUUVOQlFBRGdnSUJBSS9Ta1NaS0pyMm1JakJ6ClJxQXQ3dmJ4eWNhQXhCU3VqbDlqVSttYkh1RDg4Qyt3TDh4TzNYRHJ1Vm9IZTdYanhrNXpaN0RWMjMza3haQlEKR3BET1hWaGNZdE5UNzk2YXd1K0VNU2kzK3RzTVJBMmMxODJ2ZVNDSE9HQmVseTlRS3FHWkJBZGU2ZGNzTkpMTwpiRE10NlB3NXpiRHNqalJnMGY5SGQrRFZheXV6QzBtdXVGWEZkT0txU0VWZVNmZWVNOUl5KzFMWDMzOFlVd05zCjdhS2ppaFVFSkg4ZkVFU1NEUGE5OGNOSEsyZ0t5UENrRUorMGlNZkJiTi9yUE1CYlhqTUtHYWpXSFFhWWtieDUKalVRUmdvd25ZbStycDRwRnNhalpSTFB0NE9mbkswNWYvRHdCUXVGWUUzUFJ2d2NQSWxJNHpkcWh0NE9ZSVY4RAo2MktleVEzb3R6eTdsVXIxamNrZldkSHpHc3NKVjYxc0xRTTBudVFNUnRTZjlHeEpYTEkyNjFaRWFMYVY5WFduCnY3YnByb090UTNiYk9RbjI0elJDVm5kZ0Z3aCtUVHMzVmFOQjhURmY2QjFoV1R5aTYzOCtoa1FTRnJTbXI1WTcKTXNGUXZXSVZVbjQ2cWNjVGNuNlc2Y2JIUlhyQkRiR0tlWUJiVjVXSkJwRUtSN0JuQ25HNnJCbmxGNjZ5eTUyLwpSbWZLRWZwWG1qbkh0WW94UnlQVlJZWDhPcnkzUFQrYSt0REtlMDBXY1MyM0U3MWl2QTBNdnVrODlwTzJIUVorCjNHUU9xdWJpQ3RMbVppdVFCZC9aN1NGWGlzcUxyTE5aOW52Q2VRSkxTckVDajRpZjV2dmJkWVhLdkozamhtSjkKeVZvc0xZVzA3SklzSFE0aDAwVWphSnhrVjdoWgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t", "SigningKeyAlgorithm": "RSA_2048", "ExportToken": "export-token-au7pvkbsq4mbup6i", "ParametersValidUntilTimestamp": "2023-06-13T15:40:24.036000-07:00" }
2. Import AWS Payment Cryptography certificate into receiving system

Import the certificate chain provided in step 1 into your receiving system as necessary.

3. Generate a key pair, create a public certificate and provide the certificate root to AWS Payment Cryptography

To ensure confidentiality of the transmitted payload, it is encrypted by the sending party (known as the Key Distribution Host or KDH). The receiving party (typically your HSM or your partners' HSM) will want to generate a public key for this purpose and then create a public key certificate (x.509) that can be provided back to AWS Payment Cryptography. AWS Private CA is one option for generating certificates, but there is no restrictions on the certificate authority used.

Once you have the certificate, you'll want to load the root certificate to AWS Payment Cryptography using the ImportKey command and KeyMaterialType of ROOT_PUBLIC_KEY_CERTIFICATE and KeyUsageType of TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE.

The KeyUsageType of this certificate is TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE because it is the root key and is used to sign the leaf certificate. Leaf certificates for import/export are not imported into AWS Payment Cryptography but are passed inline.

Note

If the root certificate was previously imported, this step can be skipped.

4. Call Export key

As the last step, you will call the ExportKey API with a KeyMaterialType of TR34_KEY_BLOCK. The certificate-authority-public-key-identifier will be the keyARN of the root CA import in step 3, WrappingKeyCertificate will be leaf certificate from step 3 and export-key-identifier is the keyARN (or alias) to be exported. You will also need to provide the export-token from step 1.

Export keys using asymmetric techniques (RSA Wrap)

Overview: AWS Payment Cryptography supports RSA wrap/unwrap for key exchange when TR-34 is not an option available by the counter party. Similar to TR-34, this technique utilizes RSA asymmetric cryptography to encrypt symmetric keys for exchange. However, unlike TR-34, this method does not have the payload signed by the sending party. Also, this RSA wrap technique does not include key blocks which are used to maintain the integrity of key metadata during transport.

Note

RSA wrap can be used to export TDES and AES-128 keys.

1. Generate an RSA key and certificate on receiving system

Create (or identify) an RSA key that will be used for receiving the wrapped key. AWS Payment Cryptography expects keys in X.509 certificate format. Certificate should be signed by a root certificate that is imported (or can be imported) into AWS Payment Cryptography.

2. Install root public certificate on AWS Payment Cryptography
$ aws payment-cryptography import-key --key-material='{"RootCertificatePublicKey":{"KeyAttributes":{"KeyAlgorithm":"RSA_4096","KeyClass":"PUBLIC_KEY","KeyModesOfUse":{"Verify": true},"KeyUsage":"TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE"},"PublicKeyCertificate":"LS0tLS1CRUdJTiBDRV..."}}'
{ "Key": { "CreateTimestamp": "2023-09-14T10:50:32.365000-07:00", "Enabled": true, "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/nsq2i3mbg6sn775f", "KeyAttributes": { "KeyAlgorithm": "RSA_4096", "KeyClass": "PUBLIC_KEY", "KeyModesOfUse": { "Decrypt": false, "DeriveKey": false, "Encrypt": false, "Generate": false, "NoRestrictions": false, "Sign": false, "Unwrap": false, "Verify": true, "Wrap": false }, "KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE" }, "KeyOrigin": "EXTERNAL", "KeyState": "CREATE_COMPLETE", "UsageStartTimestamp": "2023-09-14T10:50:32.365000-07:00“ } }
3. Call export key

Next you want to instruct AWS Payment Cryptography to export your key using your leaf certificate. You will specify the ARN for the previously imported root certificate, the leaf certificate to use for export and the symmetric key to export. The output will be a hex encoded binary wrapped (encrypted) version of your symmetric key.

$ cat export-key.json
{ "ExportKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi", "KeyMaterial": { "KeyCryptogram": { "CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/zabouwe3574jysdl", "WrappingKeyCertificate": "LS0tLS1CRUdJTiBD...", "WrappingSpec": "RSA_OAEP_SHA_256" } } }
$ aws payment-cryptography export-key --cli-input-json file://export-key.json
{ "WrappedKey": { "KeyMaterial": "18874746731E9E1C4562E4116D1C2477063FCB08454D757D81854AEAEE0A52B1F9D303FA29C02DC82AE7785353816EFAC8B5F4F79CC29A1DDA80C65F34364373D8C74E5EC67E4CB55DEA7F091210DCACD3C46FE4A5DAA0F0D9CAA7C959CA7144A5E7052F34AAED93EF44C004AE7ABEBD616C955BBA10993C06FB905319F87B9B4E1B7A7C7D17AF15B6154E807B9C574387A43197C31C6E565554437A252EFF8AC81613305760D11F9B53B08A1BA79EC7E7C82C48083C4E2D0B6F86C34AB83647BDD7E85240AD1AF3C0F6CA8C5BF323BB2D3896457C554F978F4C9436513F494130A6FADBC038D51898AAD72E02A89FF256C524E7B5D85B813751B718C4933D9DC6031F2C5B2E13351A54B6021B2DB72AA0C7EA54727FBCD557E67E5E7CC2E165576E39DB4DA33510BA9A3C847313103A18EF3B23A3440471864D58C79C569D5CD2A653AC16043CA9A61E6878F74C18EE15F9AB23754C37A945B68C0437C19F0079F74B573D9B59DAC25A20781DBE8075C947C9EDC76177A1B0794288CBF89567A541E8401C74E85B8E1C3E501860AF702F641CAA04327018A84EF3A82932A2BCF37047AB40FE77E0A6F68D0904C7E60983CD6F871D5E0E27EEF425C97D39E9394E8927EEF5D2EA9388DF3C5C241F99378DF5DADE8D0F0CF453C803BA38BA702B9651685FAFA6DCB4B14333F8D3C57F2D93E0852AA94EEC3AF3217CAE5873EFD9", "WrappedKeyMaterialFormat": "KEY_CRYPTOGRAM" } }
4. Import key to receiving system

Many HSMs and related systems support the ability to import keys using RSA unwrap (including AWS Payment Cryptography). In order to do so, specify the public key from step 1 as the (encryption) cert. and the format should be specified as RSA, Padding Mode = PKCS#1 v2.2 OAEP (with SHA 256). The exact terminology may vary by HSM.

Note

AWS Payment Cryptography outputs the wrapped key in hexBinary. You may need to convert the format before importing if your system requires a different binary representation like base64.

Export symmetric keys using a pre-established key exchange key (TR-31)

When partners are exchanging multiple keys (or to support key rotation), it is typical to first exchange an initial key encryption key (KEK) using techniques such as paper key components or in the case of AWS Payment Cryptography using TR-34. Once a KEK is established, you can use this key to transport subsequent keys (including other KEK). AWS Payment Cryptography supports this kind of key exchange using ANSI TR-31 which is widely used and widely supported by HSM vendors.

1. Exchange Key Encryption Key (KEK)

It is assumed that you've already exchange your KEK and have the keyARN (or keyAlias) available to you.

2. Create key on AWS Payment Cryptography

If the key doesn't already exist, create the key. Conversely, you can create the key on the other system and use the import command instead.

3. Export key from AWS Payment Cryptography

When exporting, the format will be TR-31. When calling the API, you will specify the key to be exported and the wrapping key to be used.

$ aws payment-cryptography export-key --key-material='{"Tr31KeyBlock": {"WrappingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza"}}' --export-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/5rplquuwozodpwsp
{ "WrappedKey": { "KeyCheckValue": "73C263", "KeyCheckValueAlgorithm": "ANSI_X9_24", "KeyMaterial": "D0144K0AB00E0000A24D3ACF3005F30A6E31D533E07F2E1B17A2A003B338B1E79E5B3AD4FBF7850FACF9A3784489581A543C84816C8D3542AE888CE6D4EDDFD09C39957B131617BC", "WrappedKeyMaterialFormat": "TR31_KEY_BLOCK" } }
4. Import into your system

You or your partner will use the import key implementation on your system to import the key.

Export DUKPT Initial Keys (IPEK/IK)

When using DUKPT, a single Base Derivation Key(BDK) may be generated for a fleet of terminals. Terminals, however, never have access to that original BDK but are each injected with a unique, initial terminal key known as IPEK or Initial Key(IK). Each IPEK is a key derived from the BDK and is intended to be unique per terminal but is derived from the original BDK. The derivation data for this calculation is known as the Key Serial Number (KSN). Per X9.24, for TDES the 10 byte KSN typically consists of 24 bits for the Key Set ID, 19 bits for the terminal ID and 21 bits for the transaction counter. For AES, the 12 byte KSN typically consists of 32 bits for the BDK ID, 32 bits for the derivation identifier(ID) and 32 bits for the transaction counter.

AWS Payment Cryptography provides a mechanism to generate and export these initial keys. Once generated, these keys can be exported using the TR-31, TR-34 and RSA wrap methods. IPEK keys are not persisted and cannot be used for subsequent operations on AWS Payment Cryptography

AWS Payment Cryptography does not enforce the split between the first two parts of the KSN. If you wish to store the derivation identifier along with the BDK, you can use the AWS tags feature for this purpose.

Note

The counter portion of the KSN (32 bits for AES DUKPT) is not used for IPEK/IK derivation. Therefore, an input of 12345678901234560001 and 12345678901234569999 will output the same IPEK.

$ aws payment-cryptography export-key --key-material='{"Tr31KeyBlock": {"WrappingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza"}}' --export-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi --export-attributes 'ExportDukptInitialKey={KeySerialNumber=12345678901234560001}'
{ "WrappedKey": { "KeyCheckValue": "73C263", "KeyCheckValueAlgorithm": "ANSI_X9_24", "KeyMaterial": "B0096B1TX00S000038A8A06588B9011F0D5EEF1CCAECFA6962647A89195B7A98BDA65DDE7C57FEA507559AF2A5D601D1", "WrappedKeyMaterialFormat": "TR31_KEY_BLOCK" } }

Exporting asymmetric (RSA) keys

Call get-public-key-certificate to export a public key in certificate form. This API will export the certificate as well as its root certificate encoded in base64 format.

NOTE: This API is not idempotent - subsequent calls may result in different certificates even though the underlying key is the same.

$ aws payment-cryptography get-public-key-certificate \ —key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/5dza7xqd6soanjtb
{ "KeyCertificate": "LS0tLS1CRUdJTi...", "KeyCertificateChain": "LS0tLS1CRUdJT...“ }