Export keys - AWS Payment Cryptography
Exporting symmetric keysExporting asymmetric (RSA) keys

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"
    }
}

Specifying key block headers upon export

AWS Payment Cryptography supports the ability to modify or append key block information when exporting in ASC TR-31 or TR-34 formats. The below table describes the TR-31 key block format and which elements can be modified upon export.

Key Block Attribute Purpose Modify or Append Upon Export? Notes

Version ID

Represents the method used to protect the underlying key material. The standard defines version A and version C (key variant), version B (derivation using TDES) and version D (key derivation using AES).

Not modifiable

AWS Payment Cryptography will use version B when the wrapping key is TDES and version D when the wrapping key is AES. Version A and Version C are deprecated and only supported for import operations.

Key Block Length

Represents the length of the remaining message

Not modifiable

This value is automatically calculated by the service. Note that the service may employ key padding as required by the specification, so the length may not appear correct prior to decrypting the payload.

Key Usage

Represents the permitted purposes of the key such as C0 (Card Verification) or B0 (Base Derivation Key)

Not modifiable

Algorithm

Represents the algorithm of the underlying key. The standard supports multiple key types such as T (TDES), A(AES) and E(ECC). AWS Payment Cryptography currently supports values of T,H and A.

Not modifiable

This is exported from AWS Payment Cryptography as-is.

Key Usage

Represents the types of operations it can be used for. Examples include Generate and Verify (C) and Encrypt/Decrypt/Wrap/Unwrap(B)

Modify*

Key Version

Represents the version number of the key if the key is replaced/rotated. This is a numeric value and defaults to 00 if not specified.

Append

Key Exportability

Represents whether the key can be exported. N means No Exportability, E means export according to X9.24 (key blocks), S means export under key block or non-key block formats.

Modify*

Optional Key Blocks

Append

Optional key blocks are a series of name/value pairs that can be cryptically bound to the key. A common example is KeySetID for DUKPT keys. The actual format includes the number of optional blocks, the length of each one and a padding block (PB), but AWS Payment Cryptography will automatically calculate these based on name/value pair input.

*When modifying, the new value must be more restrictive than the current value within AWS Payment Cryptography. For instance, if current key mode of use is Generate=True,Verify=True, when exporting, you can change it to Generate=True,Verify=False. Similarly if the key is already set to not exportable, you can not change it to exportable.

When exporting keys, AWS Payment Cryptography automatically applies the current values for the key being exported without modification. However, in some cases, you may wish to modify or append those values before sending to the receiving system even if that is permitted by within AWS Payment Cryptography. One example is that when exporting a key to a payment terminal, it is typical to restrict its exportability to Not Exportable as terminals are typically only meant to import keys and thus should not be subsequentially exporting keys.

Another example is when you want to pass associated key metadata to the receiving system. Prior to TR-31, common practice was to create a custom payload to send such information, but using TR-31 you can crptographically bind it to the key in a specific format. Key Version can be set using the KeyVersion field. TR-31/X9.143 specifies certain common headers but there is no restriction on using others as long as it fits within the AWS Payment Cryptography parameters and the receiving system is able to accept it. For more information on specifying key blocks during export, please consult the Key Block Headers in the API Guide.

In this example, we are exporting a BDK key (for instance to a KIF). We are specifying the key version as 02, setting the KeyExportability to NON_EXPORTABLE and providing an optional value for the KeySetID of 00ABCDEFAB meaning it is a TDES key (00) and the initial key is ABCDEFABCD. As key modes of use is not specified, this key will inherit the mode of use from arn:aws:payment-cryptography:us-east-2:111122223333:key/5rplquuwozodpwsp which is DeriveKey = true

Note

Even though exportability is set to Not Exportable in this example, the KIF will still be able to derive keys such as a IPEK/IK used in DUKPT and these derived keys will be exportable in order to install on the devices. This is specifically permitted by the standards. 

$ aws payment-cryptography --key-material='{"Tr31KeyBlock": {"WrappingKeyIdentifier":"arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza","KeyBlockHeaders":{"KeyModesOfUse":{"Derive":true},"KeyExportability":"NON_EXPORTABLE","KeyVersion":"02","OptionalBlocks":{"BI":"00ABCDEFABCD"}}}} --export-key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/5rplquuwozodpwsp
{
        "WrappedKey": {
            "WrappedKeyMaterialFormat": "TR31_KEY_BLOCK",
            "KeyMaterial": "D0128B0TX02N0100BI1000ABCDEFABCD1A2C0EADE244321640E94FE3A3C9D33800D47CE64238D9327DDBFE25B902352B29511AED4EF9BF65AF1E812BE665210F",
            "KeyCheckValue": "A4C9B3",
            "KeyCheckValueAlgorithm": "ANSI_X9_24"
        }
  }

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...“
}