Import keys

PDFRSS

Important

Examples require the latest version of the AWS CLI V2. Before getting started, make sure that you've upgraded to the latest version.

Importing symmetric keys

Import keys using asymmetric techniques (TR-34)

TR-34 uses RSA asymmetric cryptography to encrypt and sign symmetric keys for exchange. This ensures both confidentiality (encryption) and integrity (signature) of the wrapped key.

To import your own keys, check out the AWS Payment Cryptography sample project on GitHub. For instructions on how to import/export keys from other platforms, review the sample code on GitHub or consult the user guide for those platforms.

1. Call the Initialize Import command

   Call get-parameters-for-import to initialize the import process. This API generates a key pair for key imports, signs the key, and returns the certificate and certificate root. Encrypt the key to be exported using this key. In TR-34 terminology, this is known as the KRD Cert. These certificates are base64 encoded, short-lived, and intended only for this purpose. Save the ImportToken value.

   $ aws payment-cryptography get-parameters-for-import \
       --key-material-type TR34_KEY_BLOCK \
       --wrapping-key-algorithm RSA_2048

   {
       "ImportToken": "import-token-bwxli6ocftypneu5", 
       "ParametersValidUntilTimestamp": 1698245002.065, 
       "WrappingKeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0....", 
       "WrappingKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0....", 
       "WrappingKeyAlgorithm": "RSA_2048"
   }

2. Install public certificate on key source system

   With most HSMs, you need to install, load, or trust the public certificate generated in step 1 to export keys using it. This could include the entire certificate chain or just the root certificate from step 1, depending on the HSM.

3. Generate key pair on source system and provide certificate chain to AWS Payment Cryptography

   To ensure integrity of the transmitted payload, the sending party (Key Distribution Host or KDH) signs it. Generate a public key for this purpose and create a public key certificate (X509) to provide back to AWS Payment Cryptography.

   When transferring keys from an HSM, create a key pair on that HSM. The HSM, a third party, or a service such as AWS Private CA can generate the certificate.

   Load the root certificate to AWS Payment Cryptography using the importKey command with KeyMaterialType of RootCertificatePublicKey and KeyUsageType of TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE.

   For intermediate certificates, use the importKey command with KeyMaterialType of TrustedCertificatePublicKey and KeyUsageType of TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE. Repeat this process for multiple intermediate certificates. Use the KeyArn of the last imported certificate in the chain as an input to subsequent import commands.

   Note

   Don't import the leaf certificate. Provide it directly during the import command.

4. Export key from source system

   Many HSMs and related systems support exporting keys using the TR-34 norm. Specify the public key from step 1 as the KRD (encryption) cert and the key from step 3 as the KDH (signing) cert. To import to AWS Payment Cryptography, specify the format as TR-34.2012 non-CMS two pass format, which may also be referred to as the TR-34 Diebold format.

5. Call Import Key

   Call the importKey API with a KeyMaterialType of TR34_KEY_BLOCK. Use the keyARN of the last CA imported in step 3 for certificate-authority-public-key-identifier, the wrapped key material from step 4 for key-material, and the leaf certificate from step 3 for signing-key-certificate. Include the import-token from step 1.

   $ aws payment-cryptography import-key \
       --key-material='{"Tr34KeyBlock": { \
       "CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/zabouwe3574jysdl", \
       "ImportToken": "import-token-bwxli6ocftypneu5", \
       "KeyBlockFormat": "X9_TR34_2012", \
       "SigningKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV2RENDQXFTZ0F3SUJ...", \
       "WrappedKeyBlock": "308205A106092A864886F70D010702A08205923082058E020101310D300B0609608648016503040201308203..."} \
       }'

   {
     "Key": {
       "CreateTimestamp": "2023-06-13T16:52:52.859000-04:00",
       "Enabled": true,
       "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza",
       "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_K1_KEY_ENCRYPTION_KEY"
       },
       "KeyCheckValue": "CB94A2",
       "KeyCheckValueAlgorithm": "ANSI_X9_24",
       "KeyOrigin": "EXTERNAL",
       "KeyState": "CREATE_COMPLETE",
       "UsageStartTimestamp": "2023-06-13T16:52:52.859000-04:00"
     }
   }

6. Use imported key for cryptographic operations or subsequent import

   If the imported KeyUsage was TR31_K0_KEY_ENCRYPTION_KEY, you can use this key for subsequent key imports using TR-31. For other key types (such as TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY), you can use the key directly for cryptographic operations.

Import keys using asymmetric techniques (RSA Unwrap)

Overview: AWS Payment Cryptography supports RSA wrap/unwrap for key exchange when TR-34 isn't feasible. Like TR-34, this technique uses RSA asymmetric cryptography to encrypt symmetric keys for exchange. However, unlike TR-34, this method doesn't have the sending party sign the payload. Also, this RSA wrap technique doesn't maintain the integrity of the key metadata during transfer because it doesn't include key blocks.

Note

You can use RSA wrap to import or export TDES and AES-128 keys.

1. Call the Initialize Import command

   Call get-parameters-for-import to initialize the import process with a KeyMaterialType of KEY_CRYPTOGRAM. Use RSA_2048 for the WrappingKeyAlgorithm when exchanging TDES keys. Use RSA_3072 or RSA_4096 when exchanging TDES or AES-128 keys. This API generates a key pair for key imports, signs the key using a certificate root, and returns both the certificate and certificate root. Encrypt the key to be exported using this key. These certificates are short-lived and intended only for this purpose.

   $ aws payment-cryptography get-parameters-for-import \
       --key-material-type KEY_CRYPTOGRAM \
       --wrapping-key-algorithm RSA_4096

   {
     "ImportToken": "import-token-bwxli6ocftypneu5",
     "ParametersValidUntilTimestamp": 1698245002.065,
     "WrappingKeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0....",
     "WrappingKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0....",
     "WrappingKeyAlgorithm": "RSA_4096"
   }

2. Install public certificate on key source system

   With many HSMs, you need to install, load, or trust the public certificate (and/or its root) generated in step 1 to export keys using it.

3. Export key from source system

   Many HSMs and related systems support exporting keys using RSA wrap. Specify the public key from step 1 as the encryption cert (WrappingKeyCertificate). If you need the chain of trust, use the WrappingKeyCertificateChain from step 1. When exporting the key from your HSM, specify the format as RSA, with Padding Mode = PKCS#1 v2.2 OAEP (with SHA 256 or SHA 512).

4. Call import-key

   Call the import-key API with a KeyMaterialType of KeyMaterial. You need the ImportToken from step 1 and the key-material (wrapped key material) from step 3. Provide the key parameters (such as Key Usage) because RSA wrap doesn't use key blocks.

   $ cat import-key-cryptogram.json 

   {
     "KeyMaterial": {
       "KeyCryptogram": {
         "Exportable": true,
         "ImportToken": "import-token-bwxli6ocftypneu5",
         "KeyAttributes": {
           "KeyAlgorithm": "AES_128",
           "KeyClass": "SYMMETRIC_KEY",
           "KeyModesOfUse": {
             "Decrypt": true,
             "DeriveKey": false,
             "Encrypt": true,
             "Generate": false,
             "NoRestrictions": false,
             "Sign": false,
             "Unwrap": true,
             "Verify": false,
             "Wrap": true
           },
           "KeyUsage": "TR31_K0_KEY_ENCRYPTION_KEY"
         },
         "WrappedKeyCryptogram": "18874746731....",
         "WrappingSpec": "RSA_OAEP_SHA_256"
       }
     }
   }

   $ aws payment-cryptography import-key --cli-input-json file://import-key-cryptogram.json

   {
     "Key": {
       "KeyOrigin": "EXTERNAL",
       "Exportable": true,
       "KeyCheckValue": "DA1ACF",
       "UsageStartTimestamp": 1697643478.92,
       "Enabled": true,
       "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h",
       "CreateTimestamp": 1697643478.92,
       "KeyState": "CREATE_COMPLETE",
       "KeyAttributes": {
         "KeyAlgorithm": "AES_128",
         "KeyModesOfUse": {
           "Encrypt": true,
           "Unwrap": true,
           "Verify": false,
           "DeriveKey": false,
           "Decrypt": true,
           "NoRestrictions": false,
           "Sign": false,
           "Wrap": true,
           "Generate": false
         },
         "KeyUsage": "TR31_K0_KEY_ENCRYPTION_KEY",
         "KeyClass": "SYMMETRIC_KEY"
       },
       "KeyCheckValueAlgorithm": "CMAC"
     }
   }

5. Use imported key for cryptographic operations or subsequent import

   If the imported KeyUsage was TR31_K0_KEY_ENCRYPTION_KEY, you can use this key for subsequent key imports using TR-31. If the key type was any other type (such as TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY), you can use the key directly for cryptographic operations.

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

When exchanging multiple keys or supporting key rotation, partners typically first exchange an initial key encryption key (KEK). You can do this using techniques such as paper key components or, for AWS Payment Cryptography, using TR-34.

After establishing a KEK, you can use it to transport subsequent keys (including other KEKs). AWS Payment Cryptography supports this key exchange using ANSI TR-31, which is widely used and supported by HSM vendors.

1. Import Key Encryption Key (KEK)

   Make sure you've already imported your KEK and have the keyARN (or keyAlias) available.

2. Create key on source platform

   If the key doesn't exist, create it on the source platform. Alternatively, you can create the key on AWS Payment Cryptography and use the export command.

3. Export key from source platform

   When exporting, specify the export format as TR-31. The source platform will ask for the key to export and the key encryption key to use.

4. Import into AWS Payment Cryptography

   When calling the import-key command, use the keyARN (or alias) of your key encryption key for WrappingKeyIdentifier. Use the output from the source platform for WrappedKeyBlock.

   $ aws payment-cryptography import-key \
       --key-material='{"Tr31KeyBlock": { \
       "WrappingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza", \
       "WrappedKeyBlock": "D0112B0AX00E00002E0A3D58252CB67564853373D1EBCC1E23B2ADE7B15E967CC27B85D5999EF58E11662991FF5EB1381E987D744334B99D"} \
       }'

   {
     "Key": {
       "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h",
       "KeyAttributes": {
         "KeyUsage": "TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY",
         "KeyClass": "SYMMETRIC_KEY",
         "KeyAlgorithm": "AES_128",
         "KeyModesOfUse": {
           "Encrypt": true,
           "Decrypt": true,
           "Wrap": true,
           "Unwrap": true,
           "Generate": false,
           "Sign": false,
           "Verify": false,
           "DeriveKey": false,
           "NoRestrictions": false
         }
       },
       "KeyCheckValue": "0A3674",
       "KeyCheckValueAlgorithm": "CMAC",
       "Enabled": true,
       "Exportable": true,
       "KeyState": "CREATE_COMPLETE",
       "KeyOrigin": "EXTERNAL",
       "CreateTimestamp": "2023-06-02T07:38:14.913000-07:00",
       "UsageStartTimestamp": "2023-06-02T07:38:14.857000-07:00"
     }
   }

Importing asymmetric (RSA) keys

Importing RSA public keys

AWS Payment Cryptography supports importing public RSA keys as X.509 certificates. To import a certificate, first import its root certificate. All certificates must be unexpired at the time of import. The certificate should be in PEM format and base64 encoded.

1. Import Root Certificate into AWS Payment Cryptography

   Use the following command to import the root certificate:

   $ aws payment-cryptography import-key \
       --key-material='{"RootCertificatePublicKey": { \
       "KeyAttributes": { \
       "KeyAlgorithm": "RSA_2048", \
       "KeyClass": "PUBLIC_KEY", \
       "KeyModesOfUse": { \
       "Verify": true}, \
       "KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE"}, \
       "PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURKVENDQWcyZ0F3SUJBZ0lCWkRBTkJna3Foa2lHOXcwQkFR..."} \
       }'

   {
     "Key": {
       "CreateTimestamp": "2023-08-08T18:52:01.023000+00:00",
       "Enabled": true,
       "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/zabouwe3574jysdl",
       "KeyAttributes": {
         "KeyAlgorithm": "RSA_2048",
         "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-08-08T18:52:01.023000+00:00"
     }
   }

2. Import Public Key Certificate into AWS Payment Cryptography

   You can now import a public key. There are two options for importing public keys:

   • Use TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE if the key's purpose is to verify signatures (for example, when importing using TR-34).

   • Use TR31_D1_ASYMMETRIC_KEY_FOR_DATA_ENCRYPTION when encrypting data for use with another system.

   $ aws payment-cryptography import-key \
       --key-material='{"Tr31KeyBlock": { \
       "WrappingKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ov6icy4ryas4zcza", \
       "WrappedKeyBlock": "D0112B0AX00E00002E0A3D58252CB67564853373D1EBCC1E23B2ADE7B15E967CC27B85D5999EF58E11662991FF5EB1381E987D744334B99D"} \
       }'

   {
     "Key": {
       "CreateTimestamp": "2023-08-08T18:55:46.815000+00:00",
       "Enabled": true,
       "KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/4kd6xud22e64wcbk",
       "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-08-08T18:55:46.815000+00:00"
     }
   }