# Managing keys
To get started with AWS Payment Cryptography, create an AWS Payment Cryptography key.
This section explains how to create and manage various AWS Payment Cryptography key types throughout their lifecycle. You'll learn how to create, view, and edit keys, as well as how to tag keys, create key aliases, and enable or disable keys.
An AWS Payment Cryptography key is a regional resource. If you intend to use a given key in multiple AWS Regions, you can enable Multi-Region key replication which securely copies key material and metadata to AWS Regions you specify within the same AWS Partition and Account. The source key in Multi-Region key replication is known as the [Primary Region key](terminology.md#term.prk) (PRK) and this remains the authoritative source for all key management activities. The replicated key is known as the [Replica Region key](terminology.md#term.rrk)(RRK) and this is a read-only replica of the PRK. You should consider using Multi-Region keys with your keys to meet design goals around availability, disaster recovery, and low latency.
**Topics**
+ [Creating keys](create-keys.md)
+ [Listing keys](keys-list.md)
+ [Enabling and disabling keys](keys-enable-disable.md)
+ [Replicating AWS Payment Cryptography keys](keys-multi-region-replication.md)
+ [Deleting keys](keys-deleting.md)
+ [Importing and exporting keys](keys-importexport.md)
+ [Using aliases](keys-managealias.md)
+ [Get keys](getkeys.md)
+ [Tagging keys](tagging-keys.md)
+ [Understanding key attributes for AWS Payment Cryptography key](keys-validattributes.md)
# Creating keys
You can create AWS Payment Cryptography keys using the **CreateKey** API operation. When you create a key, you specify attributes such as the key algorithm, key usage, permitted operations, and whether it's exportable. You can't change these properties after you create the AWS Payment Cryptography key.
**Note**
If Multi-Region key replication is enabled for your AWS account and you create an Payment Cryptography key, this key will automatically become a [Primary Region key (PRK)](terminology.md#term.prk). PRK is replicated even if you don't specify the `--replication-regions` parameter in the **CreateKey** command. For more information, see [How Multi-Region key replication works](keys-multi-region-replication.md#how-mrr-works).
**Topics**
+ [Creating a 3KEY TDES base derivation key](#3des-deriv-mrr-example)
+ [Creating a 2KEY TDES key for CVV/CVV2](#cvvkey-example)
+ [Creating an HMAC key](#hmac-example)
+ [Creating an AES-256 key](#aes-example)
+ [Creating a PIN Encryption Key (PEK)](#pekkey-example)
+ [Creating an asymmetric (RSA) key](#asymmetrickey-example)
+ [Creating a PIN Verification Value (PVV) Key](#pvv-example)
+ [Creating an asymmetric ECC key](#ECDH-example)
## Creating a 3KEY TDES base derivation key
**Example**
This command creates creates a 3KEY TDES derivation key that will be [replicated](keys-multi-region-replication.md#how-mrr-works) to US East (Ohio) and US West (Oregon) regions. The response includes the reques parameters, an Amazon Resource Name (ARN) for subsequent calls, and a Key Check Value (KCV).
```
$ aws payment-cryptography create-key --exportable --key-attributes \
"KeyUsage=TR31_B0_BASE_DERIVATION_KEY, \
KeyClass=SYMMETRIC_KEY,KeyAlgorithm=TDES_3KEY, \
KeyModesOfUse={NoRestrictions=true}" \
--replication-regions us-east-2 --region us-west-2
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2022-10-26T16:04:11.642000-07:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "FE23D3",
"KeyAttributes": {
"KeyAlgorithm": "TDES_3KEY",
"KeyClass": "SYMMETRIC_KEY",
"KeyModesOfUse": {
"Decrypt": false,
"DeriveKey": true,
"Encrypt": false,
"Generate": false,
"NoRestrictions": false,
"Sign": false,
"Unwrap": false,
"Verify": true,
"Wrap": false
},
"KeyUsage": "TR31_B0_BASE_DERIVATION_KEY"
},
"KeyCheckValue": "FE23D3",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-10-26T16:04:11.559000-07:00"
}
```
## Creating a 2KEY TDES key for CVV/CVV2
**Example**
This command creates a 2KEY TDES key for generating and verifying CVV/CVV2 values. The response includes the request parameters, an Amazon Resource Name (ARN) for subsequent calls, and a Key Check Value (KCV).
```
$ 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}'
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2022-10-26T16:04:11.642000-07:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/7f7g4spf3xcklhzu",
"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": "AEA5CD",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-10-26T16:04:11.559000-07:00"
}
}
```
## Creating an HMAC key
**Example**
HMAC keys are used for generating or verifying hash message authentication codes (HMAC). With HMAC keys, the hash type is assigned at the time of key creation (such as HMAC\$1SHA224 and HMAC\$1SHA512) and cannot be modified.
```
$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=HMAC_SHA512,KeyUsage=TR31_M7_HMAC_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Generate = true,Verify = true}'
```
Example output:
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/qnobl5lghrzunce6",
"KeyAttributes": {
"KeyUsage": "TR31_M7_HMAC_KEY",
"KeyClass": "SYMMETRIC_KEY",
"KeyAlgorithm": "HMAC_SHA512",
"KeyModesOfUse": {
"Encrypt": false,
"Decrypt": false,
"Wrap": false,
"Unwrap": false,
"Generate": true,
"Sign": false,
"Verify": true,
"DeriveKey": false,
"NoRestrictions": false
}
},
"KeyCheckValue": "2976E7",
"KeyCheckValueAlgorithm": "HMAC",
"Enabled": true,
"Exportable": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2025-07-30T10:06:12.142000-07:00",
"UsageStartTimestamp": "2025-07-30T10:06:12.128000-07:00"
}
}
```
## Creating an AES-256 key
**Example**
This command creates an AES-256 symmetric key for data encryption and decryption. AES keys provide strong encryption for sensitive data and are commonly used in payment processing for encrypting cardholder data and other sensitive information, however TDES is more commonly used for issuer use cases like EMV.
```
$ aws payment-cryptography create-key --exportable --key-attributes KeyAlgorithm=AES_256,KeyUsage=TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY,KeyClass=SYMMETRIC_KEY,KeyModesOfUse='{Encrypt=true,Decrypt=true,Wrap=true,Unwrap=true}'
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2025-02-02T10:15:30.142000-08:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-1:111122223333:key/kwapwa6qaifllw2h",
"KeyAttributes": {
"KeyAlgorithm": "AES_256",
"KeyClass": "SYMMETRIC_KEY",
"KeyModesOfUse": {
"Decrypt": true,
"DeriveKey": false,
"Encrypt": true,
"Generate": false,
"NoRestrictions": false,
"Sign": false,
"Unwrap": true,
"Verify": false,
"Wrap": true
},
"KeyUsage": "TR31_D0_SYMMETRIC_DATA_ENCRYPTION_KEY"
},
"KeyCheckValue": "2976F5",
"KeyCheckValueAlgorithm": "CMAC",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2025-02-02T10:15:30.128000-08:00"
}
}
```
## Creating a PIN Encryption Key (PEK)
**Example**
This command creates a 3KEY TDES key for encrypting PIN values although pin keys can also be AES depending on your need for interoperability. You can use this key to securely store PINs or decrypt PINs during verification, such as in a transaction. The response includes the request parameters, an ARN for subsequent calls, and a KCV.
```
$ 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}'
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2022-10-27T08:27:51.795000-07:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/ivi5ksfsuplneuyt",
"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": "7CC9E2",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-10-27T08:27:51.753000-07:00"
}
}
```
## Creating an asymmetric (RSA) key
**Example**
This command generates a new asymmetric RSA 2048-bit key pair. It creates a new private key and its matching public key. You can retrieve the public key using the [getPublicCertificate](keys.getpubliccertificate-example.md) 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}'
```
Example output:
```
{
"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": "SHA-1",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-11-15T11:15:42.182000-08:00"
}
}
```
## Creating a PIN Verification Value (PVV) Key
**Example**
This command creates a 3KEY TDES key for generating PVV values. You can use this key to generate a PVV that can be compared against a subsequently calculated PVV. The response includes the request parameters, an ARN for subsequent calls, and a KCV.
```
$ 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}'
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2022-10-27T10:22:59.668000-07:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2",
"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": "7F2363",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-10-27T10:22:59.614000-07:00"
}
}
```
## Creating an asymmetric ECC key
**Example**
This command generates an ECC key pair for establishing an ECDH (Elliptic Curve Diffie-Hellman) key agreement between two parties. With ECDH, each party generates its own ECC key pair with key purpose K3 and mode of use X, and they exchange 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, we recommend not reusing 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}'
```
Example output:
```
{
"Key": {
"CreateTimestamp": "2024-10-17T01:31:55.908000+00:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv",
"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": "SHA-1",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2024-10-17T01:31:55.866000+00:00"
}
}
```
# Listing keys
Use the **ListKeys** operation to get a list of keys accessible to you in your account and Region.
**Example**
```
$ aws payment-cryptography list-keys
```
Example output:
```
{
"Keys": [
{
"CreateTimestamp": "2022-10-12T10:58:28.920000-07:00",
"Enabled": false,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/37y2tsl45p5zjbh2",
"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_P1_PIN_GENERATION_KEY"
},
"KeyCheckValue": "7F2363",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStopTimestamp": "2022-10-27T14:19:42.488000-07:00"
}
]
}
```
# Enabling and disabling keys
You can disable and re-enable AWS Payment Cryptography keys. When you create key, it is enabled by default. If you disable a key, it cannot be used in any [cryptographic operation](data-operations.md) until you re-enable it. Start/stop usage commands take immediate effect, so it's recommended that you review usage before making such a change. You can also set a change (start or stop usage) to take effect in the future using the optional `timestamp` parameter.
Because it's temporary and easily undone, disabling an AWS Payment Cryptography key is a safer alternative to deleting an AWS Payment Cryptography key, an action that is destructive and irreversible. If you are considering deleting an AWS Payment Cryptography key, disable it first and ensure that you will not need to use the key to encrypt or decrypt data in the future.
**Topics**
+ [Start key usage](#keys-startusage)
+ [Stop key usage](#keys-stopusage)
## Start key usage
Key usage must be enabled in order to use a key for cryptographic operations. If a key is not enabled, you can use this operation to make it usable. The field `UsageStartTimestamp` will represent when the key became/will become active. This will be in the past for an enabled token, and in the future if pending activation.
**Example**
In this example, a key is requested to be enabled for key usage. The response includes the key information and the enable flag has been transitioned to true. This will also be reflected in list-keys response object.
```
$ aws payment-cryptography start-key-usage --key-identifier "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh"
```
```
{
"Key": {
"CreateTimestamp": "2022-10-12T10:58:28.920000-07:00",
"Enabled": true,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh",
"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_P1_PIN_GENERATION_KEY"
},
"KeyCheckValue": "369D",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStartTimestamp": "2022-10-27T14:09:59.468000-07:00"
}
}
```
## Stop key usage
If you no longer plan to use a key, you can stop the key usage to prevent further cryptographic operations. This operation is not permanent, so you are able to reverse it using [starting key usage](#keys-startusage). You can also set a key to be disabled in the future. The field `UsageStopTimestamp` will represent when the key became/will become disabled.
**Example**
In this example, it's requested to stop key usage in the future. After execution, this key cannot be used for cryptographic operations unless re-enabled via [start key usage](#keys-startusage) The response includes the key information and the enable flag has been transitioned to false. This will also be reflected in list-keys response object.
```
$ aws payment-cryptography stop-key-usage --key-identifier "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh"
```
```
{
"Key": {
"CreateTimestamp": "2022-10-12T10:58:28.920000-07:00",
"Enabled": false,
"Exportable": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/alsuwfxug3pgy6xh",
"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_P1_PIN_GENERATION_KEY"
},
"KeyCheckValue": "369D",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"KeyState": "CREATE_COMPLETE",
"UsageStopTimestamp": "2022-10-27T14:09:59.468000-07:00"
}
}
```
# Replicating AWS Payment Cryptography keys
AWS Payment Cryptography supports Multi-Region key replication, allowing you to securely distribute key material and metadata from any given AWS Payment Cryptography Key to one or more AWS Regions within the same AWS partition and account.
The source key is known as the [Primary Region key (PRK)](terminology.md#term.prk) and remains the authoritative source for all key management activities while both the PRK and the [Replica Region keys (RRK)](terminology.md#term.rrk) can be used for cryptographic operations in their respective AWS Regions.
## Benefits of Multi-Region key replication
The following outlines some benefits of Multi-Region key replication.
+ *Easier setup for highly available applications* - AWS Payment Cryptography handles key distribution for you so you can use a key in multiple AWS Regions without needing to create decoupled copies of a given key.
+ *High availability and low latency keys* - With Multi-Region key replication, you can access your keys in multiple AWS Regions making them highly available, resulting in lower latency.
+ *Key material durability* - Replica Region keys are complete key replicas and can be used independently of their Primary Region key in cryptographic operations. A RRK provides a durable replica in the event of a catastrophic data loss of a PRK.
## How Multi-Region key replication works
When Multi-Region key replication is enabled, the AWS Payment Cryptography service uses secure key distribution mechanisms to copy key material and metadata to the replica AWS Regions you specify. Changes to a Primary Region key metadata, such as key attributes, state, and enablement, are automatically replicated to the Replica Region keys.
## Limitations and considerations
The following are some Multi-Region key replication limitations and considerations.
+ You must enable this feature for either an AWS Region or specific Payment Cryptography keys.
+ If this feature is enabled for an AWS Region, all AWS Payment Cryptography keys created after enablement will be replicate to the specified AWS Region. Keys created in this Region will become Primary Region keys. Existing keys in this Region will not be automatically replicated. You can enable Multi-Region key replication for existing keys within an AWS Region at the key level.
+ Each AWS Region can have unique Multi-Region key replication settings.
+ A key's Multi-Region replication settings takes precedence over the AWS Region Multi-Region key replication setting.
+ A Replica Region key cannot be configured to replicate to other AWS Regions.
+ Multi-Region key replication is available for symmetric Payment Cryptography keys like Triple Data Encryption Standard (3DES), Advanced Encryption Standard (AES), and Hash-based Message Authentication Code (HMAC).
+ Asymmetric Payment Cryptography keys do not support Multi-Region key replication.
+ Replica Region key are read-only keys. All changes to the Primary Region key will be applied to the Replica Region keys.
+ Primary Region key changes are eventually consistent with Replica Region keys.
+ Payment Cryptography keys can only be replicated with the same AWS partition and account.
+ Replica Region key count towards your AWS account level AWS Payment Cryptography limit.
+ The Primary Region key and Replica Region key use the same key identifier which allows you to reference both keys by the same ARN in IAM policies.
+ You must have `CreateKey` permissions in the replica AWS Region for replication to succeed.
## Enabling Multi-Region key replication
There are two ways you can enable Multi-Region key replication for AWS Payment Cryptography keys.
1. **AWS Region**: Multi-Region key replication is applied to all new keys created in that AWS Region when enabled. This method provides consistent replication for all keys.
1. **Specific AWS Payment Cryptography keys**: You can manage Multi-Region key replication for individual keys allowing a more granular level of control.
Once Multi-Region key replication is enabled, your Payment Cryptography keys will replicate to the AWS Regions you specify.
**Important**
Multi-Region key replication cannot be paused. Your keys are automatically replicated to the AWS Regions you specify once replication is enabled. Multi-Region key replication can be [disabled](#disabling-mrr) for a specific AWS Region or Payment Cryptography keys. You must remove the AWS Region as a replication region from the Primary Region key to delete the Replica Region key.
Alternatively, you can call the [https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_StopKeyUsage.html](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_StopKeyUsage.html) API or [https://docs.aws.amazon.com/cli/latest/reference/payment-cryptography/stop-key-usage.html](https://docs.aws.amazon.com/cli/latest/reference/payment-cryptography/stop-key-usage.html) CLI command on your PRK to stop the usage of both the PRK and all associated RRKs. You'll be unable to use these keys in cryptographic operations. Using `StopKeyUsage` API or **stop-key-usage** CLI command will not stop the ongoing Multi-Region key replication enabled for your PRK.
You can check Multi-Region key replication settings for AWS Payment Cryptography keys in a specific AWS Region by calling the `GetDefaultKeyReplicationRegions` API or **get-default-key-replication-regions** CLI command. Keys in the AWS Region where you call this API action or command will become your [PRK](terminology.md#term.prk).
Use the following procedures to enable Multi-Region key replication.
------
#### [ For AWS Region ]
+ Use the following command to enable Multi-Region key replication for an AWS Region you specify. In this example, Multi-Region key replication is enabled in US East (Ohio) and US West (Oregon). To use this command, replace the *italicized placeholder text* in the example command with your own information.
```
aws payment-cryptography enable-default-key-replication-regions \
--replication-regions us-east-2 us-west-2
```
**Note**
Enabling Multi-Region key replication for an AWS Region will not change the replication configuration of any existing AWS Payment Cryptography keys. You can enable this feature for existing keys at the key level. Only keys created after Multi-Region key replication is enabled for an AWS Region will use the region replication settings.
------
#### [ For specific AWS Payment Cryptography keys ]
+ Use the following command to enable Multi-Region key replication for specific Payment Cryptography keys. In this example, Multi-Region key replication is enabled in US East (Ohio). To use this command, replace the *italicized placeholder text* in the example command with your own information.
```
aws payment-cryptography add-key-replication-regions \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \
--replication-regions us-east-2
```
Alternatively, you can [create a new Payment Cryptography key](create-keys.md) with this feature enabled by including the replication AWS Regions in your create key request.
**Note**
The key replication settings takes precedence over the AWS Region replication setting.
------
## Disabling Multi-Region key replication
If you want to disable Multi-Region key replication, you can call either the **disable-default-key-replication** or **remove-key-replication-regions** CLI commands, depending on how Multi-Region key replication is enabled. You'll need to specify the key's ARN and the AWS Region to disable Multi-Region key replication.
**Considerations**
Replication region key deletions are eventually consistent.
You can check Multi-Region key replication settings for AWS Payment Cryptography keys in a specific AWS Region by calling the `GetDefaultKeyReplicationRegions` API or **get-default-key-replication-regions** CLI command.
Use the following procedures to disable Multi-Region key replication.
------
#### [ For AWS Region ]
+ Use the following command to disable Multi-Region key replication for an AWS Region you specify. In this example, Multi-Region key replication is disabled in US East (Ohio). To use this command, replace the *italicized placeholder text* in the example command with your own information.
```
aws payment-cryptography disable-default-key-replication-regions \
--replication-regions us-east-2
```
------
#### [ For specific AWS Payment Cryptography keys ]
+ Use the following command to disable Multi-Region key replication for a specific Payment Cryptography key. In this example, Multi-Region key replication is disabling in US East (Ohio). To use this command, replace the *italicized placeholder text* in the example command with your own information.
```
aws payment-cryptography remove-key-replication-regions \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \
--replication-regions us-east-2
```
------
## Security considerations
The following are security considerations when using Multi-Region key replication for your Payment Cryptography keys. For more information, see [Security best practices for AWS Payment Cryptography](security-best-practices.md).
+ Limit sharing key materials.
+ Follow the principal of least privileges permissions when creating IAM policies.
+ You can't make changes to the Replica Region key as it is a read-only key.
## Best practices
The following are some best practices when using Multi-Region key replication with AWS Payment Cryptography keys.
+ Ensure your application continues to work even if the Multi-Region key replication to the specified AWS Region is not immediate. If you need to know when Multi-Region key replication is complete, you can monitor with the [GetKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_GetKey.html) API action. You can monitor key replication events with [AWS CloudTrail](https://docs.aws.amazon.com//awscloudtrail/latest/userguide/cloudtrail-user-guide.html).
+ Test and implement automated deployment processes in case of fail-over from one AWS Region to another Region.
## Pricing
You're charged for Replica Region keys you create with AWS Payment Cryptography. These keys are charged per AWS Region. For the latest Payment Cryptography pricing information, see the [AWS Payment Cryptography pricing page](https://aws.amazon.com/payment-cryptography/pricing/).
# Deleting keys
Deleting an AWS Payment Cryptography key deletes the key material and all metadata associated with the key and is irreversible unless a copy of the key is available outside of AWS Payment Cryptography. After a key is deleted, you can no longer decrypt the data that was encrypted under that key, which means that data may become unrecoverable. You should delete a key only when you are sure that you don't need to use it anymore and no other parties are utilizing this key. If you are not sure, consider stopping key usage instead of deleting it. You can re-enable a disabled key if you need to use it again later, but you cannot recover a deleted AWS Payment Cryptography key unless you are able to re-import it from another source.
Before deleting a key, you should ensure that you no longer need the key. AWS Payment Cryptography does not store the results of cryptographic operations like CVV2 and is unable to determine if a key is needed for any persistent cryptographic material.
AWS Payment Cryptography never deletes keys belonging to active AWS accounts unless you explicitly schedule them for deletion and the mandatory waiting period expires.
However, you might choose to delete an AWS Payment Cryptography key for one or more of the following reasons:
+ To complete the key lifecycle for a key that you no longer need
+ To avoid the management overhead associated with maintaining unused AWS Payment Cryptography keys
**Note**
If you [close or delete your AWS account](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/close-account.html), your AWS Payment Cryptography key become inaccessible. You do not need to schedule deletion of your AWS Payment Cryptography key separate from closing the account.
AWS Payment Cryptography records an entry in your [AWS CloudTrail](https://console.aws.amazon.com/cloudtrail) log when you schedule deletion of the AWS Payment Cryptography key and when the AWS Payment Cryptography key is actually deleted.
When using Multi-Region key replication, deleting an Payment Cryptography key that is an Primary Region key (PRK), the Replica Region keys (RRK) will also be automatically deleted. A RRK cannot be deleted like a PRK. If you want to delete a RRK, you'll need to [modify the replication regions for your PRK](keys-multi-region-replication.md#disabling-mrr).
## About the waiting period
Because deleting a key is irreversible, AWS Payment Cryptography requires you to set a waiting period of between 3–180 days. The default waiting period is seven days.
However, the actual waiting period might be up to 24 hours longer than the one you scheduled. To get the actual date and time when the AWS Payment Cryptography key will be deleted, use the GetKey operations. Be sure to note the time zone.
During the waiting period, the AWS Payment Cryptography key status and key state is **Pending deletion**.
**Note**
An AWS Payment Cryptography key pending deletion cannot be used in any [cryptographic operations](data-operations.md).
After the waiting period ends, AWS Payment Cryptography deletes the AWS Payment Cryptography key, its aliases, and all related AWS Payment Cryptography metadata.
Use the waiting period to ensure that you don't need the AWS Payment Cryptography key now or in the future. If you find that you do need the key during the waiting period, you can cancel key deletion before the waiting period ends. After the waiting period ends, you cannot cancel key deletion, and the service deletes the key.
**Topics**
**Example**
In this example, a key is requested to be deleted. Besides the basic key information, two relevant fields are that key state has been changed to DELETE\$1PENDING and deletePendingTimestamp represents when the key is currently scheduled to delete.
```
$ aws payment-cryptography delete-key \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h",
"KeyAttributes": {
"KeyUsage": "TR31_V2_VISA_PIN_VERIFICATION_KEY",
"KeyClass": "SYMMETRIC_KEY",
"KeyAlgorithm": "TDES_3KEY",
"KeyModesOfUse": {
"Encrypt": false,
"Decrypt": false,
"Wrap": false,
"Unwrap": false,
"Generate": true,
"Sign": false,
"Verify": true,
"DeriveKey": false,
"NoRestrictions": false
}
},
"KeyCheckValue": "0A3674",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"Enabled": false,
"Exportable": true,
"KeyState": "DELETE_PENDING",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2023-06-05T12:01:29.969000-07:00",
"UsageStopTimestamp": "2023-06-05T14:31:13.399000-07:00",
"DeletePendingTimestamp": "2023-06-12T14:58:32.865000-07:00"
}
}
```
**Example**
In this example, a pending deletion is cancelled. Once completed successfully, a key will no longer be deleted per the previous schedule. The response contains the basic key information; additionally, two relevant fields have changed - `KeyState` and `deletePendingTimestamp`. `KeyState` is returned to a value of CREATE\$1COMPLETE, while `DeletePendingTimestamp` is removed.
```
$ aws payment-cryptography restore-key --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h",
"KeyAttributes": {
"KeyUsage": "TR31_V2_VISA_PIN_VERIFICATION_KEY",
"KeyClass": "SYMMETRIC_KEY",
"KeyAlgorithm": "TDES_3KEY",
"KeyModesOfUse": {
"Encrypt": false,
"Decrypt": false,
"Wrap": false,
"Unwrap": false,
"Generate": true,
"Sign": false,
"Verify": true,
"DeriveKey": false,
"NoRestrictions": false
}
},
"KeyCheckValue": "0A3674",
"KeyCheckValueAlgorithm": "ANSI_X9_24",
"Enabled": false,
"Exportable": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2023-06-08T12:01:29.969000-07:00",
"UsageStopTimestamp": "2023-06-08T14:31:13.399000-07:00"
}
}
```
# Importing and exporting keys
You can import AWS Payment Cryptography keys from other solutions and export them to other solutions, such as HSMs. Many customers exchange keys with service providers using import and export functionality. We designed AWS Payment Cryptography to use a modern, electronic approach to key management that helps you maintain compliance and controls. We recommend using standards-based electronic key exchange instead of paper-based key components.
**Minimum key strengths and the effect on import and export functions**
PCI requires specific minimum key strengths for cryptographic operations, key storage, and key transmission. These requirements can change when PCI standards are revised. The rules specify that wrapping keys used for storage or transport must be at least as strong as the key being protected. We enforce this requirement automatically during export and prevent keys from being protected by weaker keys, as shown in the following table.
The following table shows the supported combinations of wrapping keys, keys to protect, and protection methods.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-importexport.html)
For more information, see [Appendix D - Minimum and Equivalent Key Sizes and Strengths for Approved Algorithms](https://docs-prv.pcisecuritystandards.org/PTS/Derived%20Test%20Requirements/PCI_HSM_DTRs_v4.pdf) in the PCI HSM standards.
**Key Encryption Key (KEK) Exchange**
We recommend using [ANSI X9.24 TR-34](terminology.md#terms.tr34) standard. This initial key type can be called a Key Encryption Key (KEK), Zone Master Key (ZMK), or Zone Control Master Key (ZCMK). If your systems or partners don't support TR-34 yet you can use [RSA Wrap/Unwrap](terminology.md#terms.rsawrap). If your needs include exchanging AES-256 keys, you can use [ECDH](terminology.md#terms.ecdh).
If you need to continue processing paper key components until all partners support electronic key exchange, consider using an offline HSM or utilizing a 3rd party [key custodian as a service](terminology.md#terms.kcaas).
To import your own test keys or to synchronize keys with your existing HSMs, please see the AWS Payment Cryptography sample code on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export).
**Working Key (WK) Exchange**
We use industry standards ([ANSI X9.24 TR 31-2018](terminology.md#terms.tr31) and X9.143) for exchanging working keys. This requires that you've already exchanged a KEK using TR-34, RSA Wrap, ECDH or similar schemes. This approach meets the PCI PIN requirement to cryptographically bind key material to its type and usage at all times. Working keys include acquirer working keys, issuer working keys, BDK, and IPEK.
**Topics**
+ [Import keys](keys-import.md)
+ [Export keys](keys-export.md)
+ [Advanced Topics](keyexchange-advanced.md)
# Import keys
**Important**
Examples require the latest version of the AWS CLI V2. Before getting started, make sure that you've upgraded to the [latest version](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
**Contents**
+ [Introduction to importing keys](#keys-import-introduction)
+ [Importing symmetric keys](#keys-import-symmetric)
+ [Import keys using asymmetric techniques (TR-34)](#keys-import-tr34)
+ [Import keys using asymmetric techniques (ECDH)](#keys-import-ecdh)
+ [Import keys using asymmetric techniques (RSA Unwrap)](#keys-import-rsaunwrap)
+ [Import symmetric keys using a pre-established key exchange key (TR-31)](#keys-import-tr31)
+ [Importing asymmetric (RSA, ECC) public keys](#keys-import-asymmetric)
+ [Importing RSA public keys](#keys-import-rsapublickey)
+ [Importing ECC public keys](#keys-import-eccpublickey)
## Introduction to importing keys
**Note**
When importing keys using X9.143, TR-31 or TR-34 key blocks, AWS Payment Cryptography typically retains (but does not utilize) any optional headers. The HM(HMAC hash type) header is used during cryptographic operations. The KP header (KCV of wrapping key) is specific to the import process and is not retained.
When exchanging keys with a counterparty, it is typically to first exchange a key exchange key (KEK). This key will then be used to protect subsequent keys. Using electronic formats, the KEK may be exchanged use asymmetric techniques such as TR-34, ECDH or RSA wrap. Subsequent keys will be exchanged using a symmetric key exchange such as TR-31. This KEK will be long lived and may only be updated every few years based on policy and its defined crypto period.
If only one or two keys are being exchanged, you may also chose to use asymmetric techniques to directly exchange that key such as a BDK. AWS Payment Cryptography supports both methods of key exchange.
## Importing symmetric keys
### Import keys using asymmetric techniques (TR-34)
![\[AWS Payment Cryptography key encryption key import process\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/images/keyimport-process-kek-import.png)
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](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export). For instructions on how to import/export keys from other platforms, sample code is available on [GitHub](https://github.com/aws-samples/samples-for-payment-cryptography-service/tree/main/key-import-export) 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"
}
```
1.
****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.
1.
****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.
1.
****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.
1.
****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"
}
}
```
1.
****Use imported key for cryptographic operations or subsequent import****
If the imported KeyUsage was TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY, you can use this key for subsequent key imports using TR-31. For other key types (such as TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY), you can use the key directly for cryptographic operations.
### Import keys using asymmetric techniques (ECDH)
![\[AWS Payment Cryptography key encryption key import process using ECDH\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/images/keyimport-ecdh-import.png)
Elliptic Curve Diffie-Hellman (ECDH) uses ECC asymmetric cryptography to establish a shared key between two parties without requiring pre-exchanged keys. ECDH keys are ephemeral, so AWS Payment Cryptography does not store them. In this process, a one-time [KBPK/KEK](terminology.md#terms.kbpk) is derived using ECDH. That derived key is immediately used to wrap the actual key that you want to transfer, which could be another KBPK, an IPEK key, or other key types.
When importing, the sending system is commonly known as Party U (Initiator) and AWS Payment Cryptography is known as Party V (Responder).
**Note**
While ECDH can be used to exchange any symmetric key type, it is the only approach that can securely transfer AES-256 keys.
1.
****Generate ECC Key Pair****
Call `create-key` to create an ECC key pair for this process. This API generates a key pair for key imports or exports. At creation, specify what kind of keys can be derived using this ECC key. When using ECDH to exchange (wrap) other keys, use a value of `TR31_K1_KEY_BLOCK_PROTECTION_KEY`.
**Note**
Although low-level ECDH generates a derived key that can be used for any purpose, AWS Payment Cryptography limits the accidental reuse of a key for multiple purposes by allowing a key to only be used for a single derived-key type.
```
$ 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}' --derive-key-usage "TR31_K1_KEY_BLOCK_PROTECTION_KEY"
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv",
"KeyAttributes": {
"KeyUsage": "TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT",
"KeyClass": "ASYMMETRIC_KEY_PAIR",
"KeyAlgorithm": "ECC_NIST_P256",
"KeyModesOfUse": {
"Encrypt": false,
"Decrypt": false,
"Wrap": false,
"Unwrap": false,
"Generate": false,
"Sign": false,
"Verify": false,
"DeriveKey": true,
"NoRestrictions": false
}
},
"KeyCheckValue": "2432827F",
"KeyCheckValueAlgorithm": "CMAC",
"Enabled": true,
"Exportable": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2025-03-28T22:03:41.087000-07:00",
"UsageStartTimestamp": "2025-03-28T22:03:41.068000-07:00"
}
}
```
1.
****Get Public Key Certificate****
Call `get-public-key-certificate` to receive the public key as an X.509 certificate signed by your account's CA that is specific to AWS Payment Cryptography in a specific region.
**Example**
```
$ aws payment-cryptography get-public-key-certificate \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv
```
```
{
"KeyCertificate": "LS0tLS1CRUdJTi...",
"KeyCertificateChain": "LS0tLS1CRUdJT..."
}
```
1.
****Install public certificate on counterparty system (Party U)****
With many 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. Consult your HSM documentation for more information.
1.
****Generate ECC key pair on source system and provide certificate chain to AWS Payment Cryptography****
In ECDH, each party generates a key pair and agrees on a common key. For AWS Payment Cryptography to derive the key, it needs the counterparty's public key in X.509 public key format.
When transferring keys from an HSM, create a key pair on that HSM. For HSMs that support key blocks, the key header will look similar to `D0144K3EX00E0000`. When creating the certificate, you generally generate a CSR on the HSM and then 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.
1.
****Derive one-time key using ECDH on Party U HSM****
Many HSMs and related systems support establishing keys using ECDH. Specify the public key from step 1 as the public key and the key from step 3 as the private key. For allowable options, such as derivation methods, see the [API guide](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportDiffieHellmanTr31KeyBlock.html).
**Note**
The derivation parameters such as hash type must match exactly on both sides. Otherwise, you will generate a different key.
1.
****Export key from source system****
Finally, export the key you want to transport to AWS Payment Cryptography using standard TR-31 commands. Specify the ECDH derived key as the KBPK. The key to be exported can be any TDES or AES key subject to TR-31 valid combinations, as long as the wrapping key is at least as strong as the key to be exported.
1.
****Call Import Key****
Call the `import-key` API with a KeyMaterialType of `DiffieHellmanTr31KeyBlock`. 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 `public-key-certificate`. Include the private key ARN from step 1.
```
$ aws payment-cryptography import-key \
--key-material='{
"DiffieHellmanTr31KeyBlock": {
"CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/swseahwtq2oj6zi5",
"DerivationData": {
"SharedInformation": "1234567890"
},
"DeriveKeyAlgorithm": "AES_256",
"KeyDerivationFunction": "NIST_SP800",
"KeyDerivationHashAlgorithm": "SHA_256",
"PrivateKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv",
"PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUN....",
"WrappedKeyBlock": "D0112K1TB00E0000D603CCA8ACB71517906600FF8F0F195A38776A7190A0EF0024F088A5342DB98E2735084A7841CB00E16D373A70857E9A"
}
}'
```
```
{
"Key": {
"CreateTimestamp": "2025-03-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": "2025-03-13T16:52:52.859000-04:00"
}
}
```
1.
****Use imported key for cryptographic operations or subsequent import****
If the imported KeyUsage was TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY, you can use this key for subsequent key imports using TR-31. For other key types (such as TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY), 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"
}
```
1.
****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.
1.
****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\$11 v2.2 OAEP (with SHA 256 or SHA 512).
1.
****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"
}
}
```
1.
****Use imported key for cryptographic operations or subsequent import****
If the imported `KeyUsage` was `TR31_K0_KEY_ENCRYPTION_KEY` or `TR31_K1_KEY_BLOCK_PROTECTION_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)
![\[AWS Payment Cryptography symmetric key import process\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/images/keyimport-process-wk-import.png)
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](#keys-import-tr34).
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.
1.
****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.
1.
****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.
1.
****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`.
**Example**
```
$ 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, ECC) public keys
All certificates imported must be at least as strong as their issuing(predecessor) certificate in the chain. This means that a RSA\$12048 CA can only be used to protect a RSA\$12048 leaf certificate and an ECC certificate must be protected by another ECC certificate of equivalent strength. An ECC P384 certificate can only be issued by a P384 or P521 CA. All certificates must be unexpired at the time of import.
### 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:
**Example**
```
$ 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"
}
}
```
1.
****Import Public Key Certificate into AWS Payment Cryptography****
You can now import a public key. As TR-34 and ECDH rely on passing the leaf certificate at run-time, this option is only used when encrypting data using a public key from another system. KeyUsage will be set to TR31\$1D1\$1ASYMMETRIC\$1KEY\$1FOR\$1DATA\$1ENCRYPTION.
**Example**
```
$ 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"
}
}
```
### Importing ECC public keys
AWS Payment Cryptography supports importing public ECC keys as X.509 certificates. To import a certificate, first import its root CA certificate and any intermediate certificates. All certificates must be unexpired at the time of import. The certificate should be in PEM format and base64 encoded.
1.
****Import ECC Root Certificate into AWS Payment Cryptography****
Use the following command to import the root certificate:
**Example**
```
$ aws payment-cryptography import-key \
--key-material='{"RootCertificatePublicKey": { \
"KeyAttributes": { \
"KeyAlgorithm": "ECC_NIST_P521", \
"KeyClass": "PUBLIC_KEY", \
"KeyModesOfUse": { \
"Verify": true}, \
"KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE"}, \
"PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNQekNDQWFDZ0F3SUJBZ0lDSjNVd0NnWUlLb1pJemowRUF3UXdNakVlTUJ3R0ExVUVDd3dWVTJWc1psTnAKWjI1bFpFTmxjblJwWm1sallYUmxNUkF3RGdZRFZRUUREQWRMUkVnZ1EwRXhNQjRYRFRJMU1ETXlPREF3TURBdwpNRm9YRFRJMk1ETXlPREF3TURBd01Gb3dNakVlTUJ3R0ExVUVDd3dWVTJWc1psTnBaMjVsWkVObGNuUnBabWxqCllYUmxNUkF3RGdZRFZRUUREQWRMUkVnZ1EwRXhNSUdiTUJBR0J5cUdTTTQ5QWdFR0JTdUJCQUFqQTRHR0FBUUEKRDVEUXc5RW1Tb1lJVkRnbUpmRm1wL1pzMXp1M0ZobThrdUdkYlA4NWgwNTdydkhHZ3VISW03V3N1aTlpdXNvNApFWEZnV3ZUdy85amhZcVJrMi9yY1RHb0JrS2NpV3Q2UHMxVmpSUVZhVEZmbmxPdjRNTURQUEFEUWthVU45cVNNCkF5MTF0RklKNlFGWDR0aGx3RzBaZkFwd0NMV1ZyMzFrRU45RDJhVUh6Mjg5WlM2all6QmhNQjhHQTFVZEl3UVkKTUJhQUZFMjhnay9QZnZ3NklsNm9yQzNwRmJtK280emxNQjBHQTFVZERnUVdCQlJOdklKUHozNzhPaUplcUt3dAo2Ulc1dnFPTTVUQVBCZ05WSFJNQkFmOEVCVEFEQVFIL01BNEdBMVVkRHdFQi93UUVBd0lDeERBS0JnZ3Foa2pPClBRUURCQU9CakFBd2dZZ0NRZ0ZRRit5VUVSYTZoQ0RwSDVHeVhlaVFYYU0wc25Fd3o2TmlmOHlSTlF1dzJ5MUoKdTNoKzZYa2N6Y3lVT01NSzhaRnhBVDhFOERMVUtpdjM1VmdzSkFDN09RSkNBSWMzdEVNV01tZTVCV3ZXTFVxSQpnV3h5U3UxWDdRSTJrR2dUK1FqRGlhQ2E4b091NVlJTmZscW4reUswR29yNGJzMTBZaUh4SHhpV2t0UVRSdVp4CkhIU3UKLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQo="} \
}'
```
```
{
"Key": {
"CreateTimestamp": "2023-08-08T18:52:01.023000+00:00",
"Enabled": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wv4gb6h3xcqjk6sm",
"KeyAttributes": {
"KeyAlgorithm": "ECC_NIST_P521",
"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": "2025-03-08T18:52:01.023000+00:00"
}
}
```
1.
****Import Intermediate Certificate into AWS Payment Cryptography****
Use the following command to import an intermediate certificate:
**Example**
```
$ aws payment-cryptography import-key \
--key-material='{"TrustedCertificatePublicKey": { \
--certificate-authority-public-key-identifier='"arn:aws:payment-cryptography:us-east-2:111122223333:key/wv4gb6h3xcqjk6sm" \
"KeyAttributes": { \
"KeyAlgorithm": "ECC_NIST_P521", \
"KeyClass": "PUBLIC_KEY", \
"KeyModesOfUse": { \
"Verify": true}, \
"KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE"}, \
"PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUNLekNDQVkyZ0F3SUJBZ0lDVDAwd0NnWUlLb1pJemowRUF3UXdNakVlTUJ3R0ExVUVDd3dWVTJWc1psTnAKWjI1bFpFTmxjblJwWm1sallYUmxNUkF3RGdZRFZRUUREQWRMUkVnZ1EwRXhNQjRYRFRJMU1ETXlPREF3TURBdwpNRm9YRFRJMk1ETXlPREF3TURBd01Gb3dNREVlTUJ3R0ExVUVBd3dWUzBSSUlFbHVkR1Z5YldWa2FXRjBaU0JEClFTQXhNUTR3REFZRFZRUUZFd1V4TURJd01UQ0JtekFRQmdjcWhrak9QUUlCQmdVcmdRUUFJd09CaGdBRUFPOGwKZFM4c09YQlNWQlVINWxmRWZkNTZxYVVIenExZVN3VGZKdnI5eEFmb2hRNTNWZ2hLUlZoNzhNR2tJTjVCNTBJTAozbmhaU1JnUnRoS20xNkxwc084NEFGa1Z0ZEpOaEJpYUlQZlRlYXltOHh6OU44KzFWZ3RMTDZBcTBtNkwwMUFwCkUvUmxzUUJ3NWxoakM4VHVOWU1QaUpMYUNPbjJrZVh6SU5SSm01SjJtR3Q1bzFJd1VEQWZCZ05WSFNNRUdEQVcKZ0JSbklBNi9Vc3RMYUpzTzlpYjg1Zm9DWEcwRk96QWRCZ05WSFE0RUZnUVVaeUFPdjFMTFMyaWJEdlltL09YNgpBbHh0QlRzd0RnWURWUjBQQVFIL0JBUURBZ2JBTUFvR0NDcUdTTTQ5QkFNRUE0R0xBRENCaHdKQ0FmTnJjdXBkClpQd3ZqTGdVeFZiN1NtSXNhY2Z6MVZrNWZFYXZHNlVzdU95Y1lGbHlQQTlJZGgyK0lOcW5jSVg4VEo2cDFJRWkKN3RCTHpPb1l0ZWd2Q1dsL0FrRkRzWHFsWkI5bU93WnNEQy9HZEpEcm5uQ0ZkR29hM1NwZytqbGdhOGdQTmxLbAo1dE9IU0lVZnZxcFhEcWYrdXV6SEc1Z3FjdUhnQU8wOUhuMloyNUc4eVE9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="} \
}'
```
```
{
"Key": {
"CreateTimestamp": "2025-03-20T18:52:01.023000+00:00",
"Enabled": true,
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/swseahwtq2oj6zi5",
"KeyAttributes": {
"KeyAlgorithm": "ECC",
"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": "2025-03-25T18:52:01.023000+00:00"
}
}
```
1.
****Import Public Key Certificate(Leaf) into AWS Payment Cryptography****
Although you can import a leaf ECC certificate, there is currently no defined functions in AWS Payment Cryptography for it besides storage. This is because when using ECDH functions, the leaf certificate is passed at runtime.
# Export keys
**Contents**
+ [Export symmetric keys](#keys-export-symmetric)
+ [Export keys using asymmetric techniques (TR-34)](#keys-export-tr34)
+ [Export keys using asymmetric techniques (ECDH)](#keys-export-ecdh)
+ [Export keys using asymmetric techniques (RSA Wrap)](#keys-export-rsawrap)
+ [Export symmetric keys using a pre-established key exchange key (TR-31)](#keys-export-tr31)
+ [Export DUKPT Initial Keys (IPEK/IK)](#keys-export-ipek)
+ [Specify key block headers for export](#keys-export-optionalheaders)
+ [Common Headers](#keys-export-commonheaders)
+ [Export asymmetric (RSA) keys](#keys-export-publickey)
## Export symmetric keys
**Important**
Make sure you have the latest version of AWS CLI before you begin. To upgrade, see [Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
### Export keys using asymmetric techniques (TR-34)
TR-34 uses RSA asymmetric cryptography to encrypt and sign symmetric keys for exchange. The encryption protects confidentiality, while the signature ensures integrity. When you export keys, AWS Payment Cryptography acts as the key distribution host (KDH), and your target system becomes the key receiving device (KRD).
**Note**
If your HSM supports TR-34 export but not TR-34 import, we recommend that you first establish a shared KEK between your HSM and AWS Payment Cryptography using TR-34. You can then use TR-31 to transfer your remaining keys.
1.
****Initialize the export process****
Run **get-parameters-for-export** to generate a key pair for key exports. We use this key pair to sign the TR-34 payload. In TR-34 terminology, this is the KDH signing certificate. The certificates are short-lived and valid only for the duration specified in `ParametersValidUntilTimestamp`.
**Note**
All certificates are in base64 encoding.
**Example**
```
$ aws payment-cryptography get-parameters-for-export \
--signing-key-algorithm RSA_2048 \
--key-material-type TR34_KEY_BLOCK
```
```
{
"SigningKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV2RENDQXFTZ0F3SUJ...",
"SigningKeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS....",
"SigningKeyAlgorithm": "RSA_2048",
"ExportToken": "export-token-au7pvkbsq4mbup6i",
"ParametersValidUntilTimestamp": "2023-06-13T15:40:24.036000-07:00"
}
```
1.
****Import the AWS Payment Cryptography certificate to your receiving system****
Import the certificate chain from step 1 to your receiving system.
1.
****Set up your receiving system's certificates****
To protect the transmitted payload, the sending party (KDH) encrypts it. Your receiving system (typically your HSM or your partner's HSM) needs to generate a public key and create an X.509 public key certificate. You can use AWS Private CA to generate certificates, but you can use any certificate authority.
After you have the certificate, import the root certificate to AWS Payment Cryptography using the **ImportKey** command. Set `KeyMaterialType` to `RootCertificatePublicKey` and `KeyUsageType` to `TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE`.
We use `TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE` as the `KeyUsageType` because this is the root key that signs the leaf certificate. You don't need to import leaf certificates into AWS Payment Cryptography—you can pass them inline.
**Note**
If you previously imported the root certificate, skip this step. For intermediate certificates, use `TrustedCertificatePublicKey`.
1.
****Export your key****
Call the **ExportKey** API with `KeyMaterialType` set to `TR34_KEY_BLOCK`. You need to provide:
+ The keyARN of the root CA from step 3 as the `CertificateAuthorityPublicKeyIdentifier`
+ The leaf certificate from step 3 as the `WrappingKeyCertificate`
+ The keyARN (or alias) of the key you want to export as the `--export-key-identifier`
+ The export-token from step 1
**Example**
```
$ aws payment-cryptography export-key \
--export-key-identifier "example-export-key" \
--key-material '{"Tr34KeyBlock": { \
"CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/4kd6xud22e64wcbk", \
"ExportToken": "export-token-au7pvkbsq4mbup6i", \
"KeyBlockFormat": "X9_TR34_2012", \
"WrappingKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV2RENDQXFXZ0F3SUJBZ0lSQ..."} \
}'
```
```
{
"WrappedKey": {
"KeyMaterial": "308205A106092A864886F70D010702A08205923082058...",
"WrappedKeyMaterialFormat": "TR34_KEY_BLOCK"
}
}
```
### Export keys using asymmetric techniques (ECDH)
![\[AWS Payment Cryptography key encryption key import process using ECDH\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/images/keyimport-ecdh-export.png)
Elliptic Curve Diffie-Hellman (ECDH) uses ECC asymmetric cryptography to establish a shared key between two parties without requiring pre-exchanged keys. ECDH keys are ephemeral, so AWS Payment Cryptography does not store them. In this process, a one-time [KBPK/KEK](terminology.md#terms.kbpk) is derived using ECDH. That derived key is immediately used to wrap the key you want to transfer, which could be another KBPK, a BDK, an IPEK key, or other key types.
When exporting, AWS Payment Cryptography is referred to as Party U (Initiator) and the receiving system is known as Party V (Responder).
**Note**
ECDH can be used to exchange any symmetric key type, but it is the only approach that can be used to transfer AES-256 keys if a KEK is not already established.
1.
****Generate ECC Key Pair****
Call `create-key` to create an ECC key pair for this process. This API generates a key pair for key imports or exports. At creation, specify what kind of keys can be derived using this ECC key. When using ECDH to exchange (wrap) other keys, use a value of `TR31_K1_KEY_BLOCK_PROTECTION_KEY`.
**Note**
Although low-level ECDH generates a derived key that can be used for any purpose, AWS Payment Cryptography limits the accidental reuse of a key for multiple purposes by allowing a key to only be used for a single derived-key type.
```
$ 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}' --derive-key-usage "TR31_K1_KEY_BLOCK_PROTECTION_KEY"
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv",
"KeyAttributes": {
"KeyUsage": "TR31_K3_ASYMMETRIC_KEY_FOR_KEY_AGREEMENT",
"KeyClass": "ASYMMETRIC_KEY_PAIR",
"KeyAlgorithm": "ECC_NIST_P256",
"KeyModesOfUse": {
"Encrypt": false,
"Decrypt": false,
"Wrap": false,
"Unwrap": false,
"Generate": false,
"Sign": false,
"Verify": false,
"DeriveKey": true,
"NoRestrictions": false
}
},
"KeyCheckValue": "2432827F",
"KeyCheckValueAlgorithm": "CMAC",
"Enabled": true,
"Exportable": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2025-03-28T22:03:41.087000-07:00",
"UsageStartTimestamp": "2025-03-28T22:03:41.068000-07:00"
}
}
```
1.
****Get Public Key Certificate****
Call `get-public-key-certificate` to receive the public key as an X.509 certificate signed by your account's CA that is specific to AWS Payment Cryptography in a specific region.
**Example**
```
$ aws payment-cryptography get-public-key-certificate \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv
```
```
{
"KeyCertificate": "LS0tLS1CRUdJTi...",
"KeyCertificateChain": "LS0tLS1CRUdJT..."
}
```
1.
****Install public certificate on counterparty system (Party V)****
With many HSMs, you need to install, load, or trust the public certificate generated in step 1 to establish keys. This could include the entire certificate chain or just the root certificate, depending on the HSM. Consult your HSM documentation for specific instructions.
1.
****Generate ECC key pair on source system and provide certificate chain to AWS Payment Cryptography****
In ECDH, each party generates a key pair and agrees on a common key. For AWS Payment Cryptography to derive the key, it needs the counterparty's public key in X.509 public key format.
When transferring keys from an HSM, create a key pair on that HSM. For HSMs that support key blocks, the key header will look similar to `D0144K3EX00E0000`. When creating the certificate, you generally generate a CSR on the HSM, and then 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 export commands.
**Note**
Don't import the leaf certificate. Provide it directly during the export command.
1.
****Derive key and export key from AWS Payment Cryptography****
When exporting, the service derives a key using ECDH and then immediately uses it as the [KBPK](terminology.md#terms.kbpk) to wrap the key to export using TR-31. The key to be exported can be any TDES or AES key subject to TR-31 valid combinations, as long as the wrapping key is at least as strong as the key to be exported.
```
$ aws payment-cryptography export-key \
--export-key-identifier arn:aws:payment-cryptography:us-west-2:529027455495:key/e3a65davqhbpjm4h \
--key-material='{
"DiffieHellmanTr31KeyBlock": {
"CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/swseahwtq2oj6zi5",
"DerivationData": {
"SharedInformation": "ADEF567890"
},
"DeriveKeyAlgorithm": "AES_256",
"KeyDerivationFunction": "NIST_SP800",
"KeyDerivationHashAlgorithm": "SHA_256",
"PrivateKeyIdentifier": "arn:aws:payment-cryptography:us-east-2:111122223333:key/wc3rjsssguhxtilv",
"PublicKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUR..."
}
}'
```
```
{
"WrappedKey": {
"WrappedKeyMaterialFormat": "TR31_KEY_BLOCK",
"KeyMaterial": "D0112K1TB00E00007012724C0FAAF64DA50E2FF4F9A94DF50441143294E0E995DB2171554223EAA56D078C4CFCB1C112B33BBF05597EE700",
"KeyCheckValue": "E421AD",
"KeyCheckValueAlgorithm": "ANSI_X9_24"
}
}
```
1.
****Derive one-time key using ECDH on Party V HSM****
Many HSMs and related systems support establishing keys using ECDH. Specify the public key from step 1 as the public key and the key from step 3 as the private key. For allowable options, such as derivation methods, see the [API guide](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ExportDiffieHellmanTr31KeyBlock.html).
**Note**
The derivation parameters such as hash type must match exactly on both sides. Otherwise, you will generate a different key.
1.
****Import key to target system****
Finally, import the key from AWS Payment Cryptography using standard TR-31 commands. Specify the ECDH derived key as the KBPK and use the TR-31 key block that was previously exported from AWS Payment Cryptography.
### Export keys using asymmetric techniques (RSA Wrap)
When TR-34 isn't available, you can use RSA wrap/unwrap for key exchange. Like TR-34, this method uses RSA asymmetric cryptography to encrypt symmetric keys. However, RSA wrap doesn't include:
+ Payload signing by the sending party
+ Key blocks that maintain key metadata integrity during transport
**Note**
You can use RSA wrap to export TDES and AES-128 keys.
1.
****Create an RSA key and certificate on your receiving system****
Create or identify an RSA key for receiving the wrapped key. We require keys to be in X.509 certificate format. Make sure the certificate is signed by a root certificate that you can import into AWS Payment Cryptography.
1.
****Import the root public certificate to AWS Payment Cryptography****
Use **import-key** with the `--key-material` option to import the certificate
```
$ 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"
}
}
```
1.
****Export your key****
Tell AWS Payment Cryptography to export your key using your leaf certificate. You need to specify:
+ The ARN for the root certificate you imported in step 2
+ The leaf certificate for export
+ The symmetric key to export
The output is a hex-encoded binary wrapped (encrypted) version of your symmetric key.
**Example – Exporting a 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": "LS0tLS1CRUdJTiBDEXAMPLE...",
"WrappingSpec": "RSA_OAEP_SHA_256"
}
}
}
```
```
$ aws payment-cryptography export-key \
--cli-input-json file://export-key.json
```
```
{
"WrappedKey": {
"KeyMaterial": "18874746731E9E1C4562E4116D1C2477063FCB08454D757D81854AEAEE0A52B1F9D303FA29C02DC82AE7785353816EFAC8B5F4F79CC29A1DDA80C65F34364373D8C74E5EC67E4CB55DEA7F091210DCACD3C46FE4A5DAA0F0D9CAA7C959CA7144A5E7052F34AAED93EF44C004AE7ABEBD616C955BBA10993C06FB905319F87B9B4E1B7A7C7D17AF15B6154E807B9C574387A43197C31C6E565554437A252EFF8AC81613305760D11F9B53B08A1BA79EC7E7C82C48083C4E2D0B6F86C34AB83647BDD7E85240AD1AF3C0F6CA8C5BF323BB2D3896457C554F978F4C9436513F494130A6FADBC038D51898AAD72E02A89FF256C524E7B5D85B813751B718C4933D9DC6031F2C5B2E13351A54B6021B2DB72AA0C7EA54727FBCD557E67E5E7CC2E165576E39DB4DA33510BA9A3C847313103A18EF3B23A3440471864D58C79C569D5CD2A653AC16043CA9A61E6878F74C18EE15F9AB23754C37A945B68C0437C19F0079F74B573D9B59DAC25A20781DBE8075C947C9EDC76177A1B0794288CBF89567A541E8401C74E85B8E1C3E501860AF702F641CAA04327018A84EF3A82932A2BCF37047AB40FE77E0A6F68D0904C7E60983CD6F871D5E0E27EEF425C97D39E9394E8927EEF5D2EA9388DF3C5C241F99378DF5DADE8D0F0CF453C803BA38BA702B9651685FAFA6DCB4B14333F8D3C57F2D93E0852AA94EEC3AF3217CAE5873EFD9",
"WrappedKeyMaterialFormat": "KEY_CRYPTOGRAM"
}
}
```
1.
****Import the key to your receiving system****
Many HSMs and related systems support importing keys using RSA unwrap (including AWS Payment Cryptography). When importing, specify:
+ The public key from step 1 as the encryption certificate
+ The format as RSA
+ Padding Mode as PKCS\$11 v2.2 OAEP (with SHA 256)
**Note**
We output the wrapped key in hexBinary format. You might need to convert the format if your system requires a different binary representation, such as base64.
### Export symmetric keys using a pre-established key exchange key (TR-31)
When exchanging multiple keys or supporting key rotation, you typically first exchange an initial key encryption key (KEK) using paper key components or, with AWS Payment Cryptography, using [TR-34](#keys-export-tr34). After establishing a KEK, you can use it to transport subsequent keys, including other KEKs. We support this key exchange using ANSI TR-31, which is widely supported by HSM vendors.
1.
****Set up your Key Encryption Key (KEK)****
Make sure you have already exchanged your KEK and have the keyARN (or keyAlias) available.
1.
****Create your key on AWS Payment Cryptography****
Create your key if it doesn't already exist. Alternatively, you can create the key on your other system and use the [import](#keys-export-tr31) command.
1.
****Export your key from AWS Payment Cryptography****
When exporting in TR-31 format, specify the key you want to export and the wrapping key to use.
**Example – Exporting a key using TR31 key block**
```
$ 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"
}
}
```
1.
****Import the key to your system****
Use your system's import key implementation to import the key.
## Export DUKPT Initial Keys (IPEK/IK)
When using [DUKPT](terminology.md#terms.dukpt), you can generate a single Base Derivation Key (BDK) for a fleet of terminals. The terminals don't have direct access to the BDK. Instead, each terminal receives a unique initial terminal key, known as IPEK or Initial Key (IK). Each IPEK is derived from the BDK using a unique Key Serial Number (KSN).
The KSN structure varies by encryption type:
+ For TDES: The 10-byte KSN includes:
+ 24 bits for the Key Set ID
+ 19 bits for the terminal ID
+ 21 bits for the transaction counter
+ For AES: The 12-byte KSN includes:
+ 32 bits for the BDK ID
+ 32 bits for the derivation identifier (ID)
+ 32 bits for the transaction counter
We provide a mechanism to generate and export these initial keys. You can export the generated keys using TR-31, TR-34, or RSA wrap methods. Note that IPEK keys are not persisted and can't be used for subsequent operations on AWS Payment Cryptography.
We don't enforce the split between the first two parts of the KSN. If you want to store the derivation identifier with the BDK, you can use AWS tags.
**Note**
The counter portion of the KSN (32 bits for AES DUKPT) isn't used for IPEK/IK derivation. For example, inputs of 12345678901234560001 and 12345678901234569999 will generate 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"
}
}
```
## Specify key block headers for export
You can modify or append key block information when exporting in ASC TR-31 or TR-34 formats. The following table describes the TR-31 key block format and which elements you can modify during export.
| Key Block Attribute | Purpose | Can you modify during export? | Notes |
| --- | --- | --- | --- |
| Version ID | Defines the method used to protect the key material. The standard includes: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | No | We use version B for TDES wrapping keys and version D for AES wrapping keys. We support versions A and C only for import operations. |
| Key Block Length | Specifies the length of the remaining message | No | We calculate this value automatically. The length might appear incorrect before decrypting the payload because we may add key padding as required by the specification. |
| Key Usage | Defines the permitted purposes for the key, such as: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | No | |
| Algorithm | Specifies the algorithm of the underlying key. We support: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | No | We export this value as-is. |
| Key Usage | Defines allowed operations, such as: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | Yes\$1 | |
| Key Version | Indicates the version number for key replacement/rotation. Defaults to 00 if not specified. | Yes - Can append | |
| Key Exportability | Controls whether the key can be exported: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | Yes\$1 | |
| Optional Key Blocks | Yes - Can append | Optional key blocks are name/value pairs cryptographically bound to the key. For example, KeySetID for DUKPT keys. We automatically calculate the number of blocks, length of each block, and padding block (PB) based on your name/value pair input. | |
*\$1When modifying values, your new value must be more restrictive than the current value in AWS Payment Cryptography.* For example:
+ If the current key mode of use is Generate=True,Verify=True, you can change it to Generate=True,Verify=False
+ If the key is already set to not exportable, you can't change it to exportable
When you export keys, we automatically apply the current values from the key being exported. However, you might want to modify or append those values before sending to the receiving system. Here are some common scenarios:
+ When exporting a key to a payment terminal, set its exportability to `Not Exportable` because terminals typically only import keys and shouldn't export them.
+ When you need to pass associated key metadata to the receiving system, use TR-31 optional headers to cryptographically bind the metadata to the key instead of creating a custom payload.
+ Set the Key Version using the `KeyVersion` field to track key rotation.
TR-31/X9.143 defines common headers, but you can use other headers as long as they meet AWS Payment Cryptography parameters and your receiving system can accept them. For more information about key block headers during export, see [Key Block Headers](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_KeyBlockHeaders.html) in the API Guide.
Here's an example of exporting a BDK key (for instance, to a KIF) with these specifications:
+ Key version: 02
+ KeyExportability: NON\$1EXPORTABLE
+ KeySetID: 00ABCDEFAB (00 indicates TDES key, ABCDEFABCD is the initial key)
Because we don't specify key modes of use, this key inherits the mode of use from arn:aws:payment-cryptography:us-east-2:111122223333:key/5rplquuwozodpwsp (DeriveKey = true).
**Note**
Even when you set exportability to Not Exportable in this example, the [KIF](terminology.md#terms.kif) can still:
Derive keys such as [IPEK/IK](terminology.md#terms.ipek) used in DUKPT
Export these derived keys to install on devices
This is specifically allowed by the standards.
```
$ aws payment-cryptography export-key \
--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": "EXAMPLE_KEY_MATERIAL_TR31",
"KeyCheckValue": "A4C9B3",
"KeyCheckValueAlgorithm": "ANSI_X9_24"
}
}
```
### Common Headers
X9.143 defines certain headers for common use cases. With the exception of the HM(HMAC Hash) header, AWS Payment Cryptography does not parse or utilize these headers.
| Header Name | Purpose | Typical Validation | Notes |
| --- | --- | --- | --- |
| BI | Base Derivation Key Identifier for DUKPT | 2 hex characters (00 for TDES, 11 for AES) then 10 hex characters for TDES KSI or 8 hex characters for BDK ID (AES DUKPT). | Contains the (BDK ID, for AES DUKPT) or the Key Set Identifier (KSI, for TDES DUKPT). Can be used when exchanging the BDK ID or the KSI, but do not need to exchange the other data contained in the IK and KS blocks. Typically BI is used when transmitting to a KIF whereas IK or KS are used when injecting into the terminal itself. |
| HM | Specifies the hash type for HMAC operations | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/payment-cryptography/latest/userguide/keys-export.html) | The service automatically populates this field on export and will parse it on import. Hash types not supported by the service such as SHAKE128 can be imported but may not be usuable for cryptographic functions. |
| IK | Initial Key Serial Number for AES DUKPT | 16 hex characters | This value is used to instantiate the use of the Initial DUKPT key on the receiving device and it identifies the Initial Key derived from a BDK. This field typically contains the derivation data but no counter. Use KS for TDES DUKPT. |
| KS | Initial Key Serial Number for TDES DUKPT | 20 hex characters | This value is used to instantiate the use of the Initial DUKPT key on the receiving device and it identifies the Initial Key derived from a BDK. This field typically contains the derivation data \$1 a zeroized counter value. Use IK for AES DUKPT. |
| KP | [KCV](terminology.md#terms.kcv) of the wrapping key | 2 hex characters represent the KCV method (00 for X9.24 method and 01 for CMAC method). Followed by KCV value which is typically 6 hex characters. For example 010FA329 represents KCV of 0FA329 calculated using 01(CMAC) method. | This value is used to instantiate the use of the Initial DUKPT key on the receiving device and it identifies the Initial Key derived from a BDK. This field typically contains the derivation data \$1 a zeroized counter value. Use IK for AES DUKPT. |
| PB | Padding block | random printable ASCII characters | The service automatically populates this field on export to ensure optional headers are multiples of encryption block length |
## Export asymmetric (RSA) keys
To export a public key in certificate form, use the **get-public-key-certificate** command. This command returns:
+ The certificate
+ The root certificate
Both certificates are in base64 encoding.
**Note**
This operation is not idempotent—subsequent calls might generate different certificates even when using the same underlying key.
**Example**
```
$ aws payment-cryptography get-public-key-certificate \
--key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/5dza7xqd6soanjtb
```
```
{
"KeyCertificate": "LS0tLS1CRUdJTi...",
"KeyCertificateChain": "LS0tLS1CRUdJT..."
}
```
# Advanced Topics
This section covers advanced key exchange scenarios and configurations.
**Topics**
+ [Bring Your Own Certificate Authority (BYOCA)](keyexchange-byoca.md)
# Bring Your Own Certificate Authority (BYOCA)
By default, when a public key certificate is needed for asymmetric(RSA,ECC) keys created within the service, these certificates are issued by a AWS Payment Cryptography and account-unique certificate authority(CA). This is intended to make it simple to use X.509 without the burden of identifying or setting up a CA or managing Certificate Signing Requests(CSR).
AWS Payment Cryptography also provides the ability to use your own CA when it is required for policy or compliance reasons.
## Overview
The BYOCA feature allows you to use your own Certificate Authority anywhere that certificates are used, including TR-34 import/export, RSA Unwrap, and ECDH-based key transfers. This is useful when you need to maintain a consistent certificate chain across your organization or when working with partners who require specific CA certificates. The following example demonstrates the BYOCA workflow using TR-34 key export.
The three key differences compared to the standard TR-34 export flow are:
1. The signing RSA key is explicitly created using [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html). Previously, it was implicitly created via [GetParametersForExport](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GetParametersForExport.html).
1. A new API [GetCertificateSigningRequest](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GetCertificateSigningRequest.html) creates a Certificate Signing Request (CSR) that can be signed by your external CA.
1. The [ExportKey](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_ExportKey.html) API is extended to allow a certificate to be provided at runtime. Previously, this was implicitly provided by `import-token`, which becomes an optional field.
**Important Considerations**
These examples use RSA-2048 keys and wrap a TDES-2KEY key. When exporting AES-128, make sure that all keys are RSA-3072 or RSA-4096.
The most common error is that the key represented by `SigningKeyIdentifier` and `SigningKeyCertificate` do not match.
## BYOCA Workflow
The following steps demonstrate the complete BYOCA workflow for TR-34 export.
**Topics**
+ [Step 1: Create RSA Key](#keyexchange-byoca.create-rsa)
+ [Step 2: Generate Certificate Signing Request](#keyexchange-byoca.generate-csr)
+ [Step 3: Review CSR (Optional)](#keyexchange-byoca.review-csr)
+ [Step 4: Sign the CSR with a Certificate Authority](#keyexchange-byoca.sign-csr)
+ [Step 5: Import CA Certificate](#keyexchange-byoca.import-ca)
+ [Step 6: Get KRD Encryption Certificate](#keyexchange-byoca.get-krd)
+ [Step 7: Export Key with BYOCA](#keyexchange-byoca.export-key)
### Step 1: Create RSA Key
First, create an RSA Key Pair that will ultimately be the KDH Signing Certificate. You can add tags to identify the key's purpose.
**Example Create RSA Key for Signing**
```
$ aws payment-cryptography create-key --exportable \
--key-attributes KeyAlgorithm=RSA_2048,KeyUsage=TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE,KeyClass=ASYMMETRIC_KEY_PAIR,KeyModesOfUse='{Sign=True}'
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-1:111122223333:key/xgmq6fs6uow736uc",
"KeyAttributes": {
"KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE",
"KeyClass": "ASYMMETRIC_KEY_PAIR",
"KeyAlgorithm": "RSA_2048",
"KeyModesOfUse": {
"Sign": true
}
},
"KeyCheckValue": "41E3723C",
"KeyCheckValueAlgorithm": "SHA_1",
"Enabled": true,
"Exportable": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "AWS_PAYMENT_CRYPTOGRAPHY"
}
}
```
Take note of the `KeyArn` as you'll need it in the next step.
### Step 2: Generate Certificate Signing Request
Generate a Certificate Signing Request (CSR) to be signed by your external CA using the [GetCertificateSigningRequest](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GetCertificateSigningRequest.html) API. The output is a base64-encoded PEM file. If you base64 decode the contents and save them, you will have a valid CSR in PEM format.
**Example Generate CSR**
```
$ aws payment-cryptography-data get-certificate-signing-request \
--key-identifier arn:aws:payment-cryptography:us-east-1:111122223333:key/xgmq6fs6uow736uc \
--signing-algorithm SHA512 \
--certificate-subject '{
"CommonName": "MyCertificateAWSUSEAST",
"Organization": "Amazon",
"OrganizationUnit": "PaymentCryptography",
"Country": "US",
"StateOrProvince": "Virginia",
"City": "Arlington"
}'
```
```
{
"CertificateSigningRequest": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..."
}
```
The `CertificateSigningRequest` field contains the base64-encoded CSR that you'll send to your CA for signing.
### Step 3: Review CSR (Optional)
You can optionally use OpenSSL to review the CSR contents and ensure it's valid and as expected.
**Example Review CSR with OpenSSL**
```
$ echo "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..." | base64 -d | openssl req -text
```
### Step 4: Sign the CSR with a Certificate Authority
After generating the CSR, you need to have it signed by a Certificate Authority (CA). In production environments, you would typically use AWS Private CA or your organization's established CA infrastructure. For testing purposes, you can use OpenSSL to create a self-signed certificate.
#### Using AWS Private CA
To sign the CSR using AWS Private CA, first decode the base64-encoded CSR and save it to a file, then use the [IssueCertificate](https://docs.aws.amazon.com/acm-pca/latest/APIReference/API_IssueCertificate.html) API.
**Example Sign CSR with AWS Private CA**
```
$ echo "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..." | base64 -d > csr.pem
$ aws acm-pca issue-certificate \
--certificate-authority-arn arn:aws:acm-pca:us-east-1:111122223333:certificate-authority/12345678-1234-1234-1234-123456789012 \
--csr fileb://csr.pem \
--signing-algorithm SHA256WITHRSA \
--validity Value=365,Type=DAYS
```
```
{
"CertificateArn": "arn:aws:acm-pca:us-east-1:111122223333:certificate-authority/12345678-1234-1234-1234-123456789012/certificate/abcdef1234567890"
}
```
Then retrieve the signed certificate:
**Example Retrieve Signed Certificate**
```
$ aws acm-pca get-certificate \
--certificate-authority-arn arn:aws:acm-pca:us-east-1:111122223333:certificate-authority/12345678-1234-1234-1234-123456789012 \
--certificate-arn arn:aws:acm-pca:us-east-1:111122223333:certificate-authority/12345678-1234-1234-1234-123456789012/certificate/abcdef1234567890
```
```
{
"Certificate": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----",
"CertificateChain": "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
}
```
Save the certificate content for use in the export step. You'll need to base64-encode it when providing it to the `ExportKey` API.
#### Using OpenSSL for Testing
For testing purposes, you can use OpenSSL to create a self-signed CA and sign the CSR. First, create a CA private key and self-signed certificate:
**Example Create Test CA with OpenSSL**
```
$ # Generate CA private key
openssl genrsa -out ca-key.pem 4096
$ # Create self-signed CA certificate
openssl req -new -x509 -days 3650 -key ca-key.pem -out ca-cert.pem \
-subj "/C=US/ST=Virginia/L=Arlington/O=TestOrg/CN=Test CA"
```
Then decode the CSR from the previous step and sign it with your test CA:
**Example Sign CSR with OpenSSL**
```
$ # Decode the base64-encoded CSR
echo "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0..." | base64 -d > csr.pem
$ # Sign the CSR with the CA
openssl x509 -req -in csr.pem -CA ca-cert.pem -CAkey ca-key.pem \
-CAcreateserial -out signed-cert.pem -days 365 -sha512
```
```
Certificate request self-signature ok
subject=C=US, ST=Virginia, L=Arlington, O=Amazon, OU=PaymentCryptography, CN=MyCertificateAWSUSEAST
```
The signed certificate is now in `signed-cert.pem`. You'll need to base64-encode this certificate when providing it to the `ExportKey` API:
**Example Base64 Encode the Signed Certificate**
```
$ cat signed-cert.pem | base64 -w 0
```
### Step 5: Import CA Certificate
Any CA being used needs to be trusted first to prevent arbitrary certificates from being used. Import your external CA's root certificate using the [ImportKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ImportKey.html) API. If using an intermediate CA, call `import-key` again but specify `TrustedPublicKey` instead of `RootCertificatePublicKey` and specify the root CA ARN.
**Example Import Root CA Certificate**
```
$ 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": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
}
}'
```
```
{
"Key": {
"KeyArn": "arn:aws:payment-cryptography:us-east-1:111122223333:key/xivpaqy7qbbm7cdw",
"KeyAttributes": {
"KeyUsage": "TR31_S0_ASYMMETRIC_KEY_FOR_DIGITAL_SIGNATURE",
"KeyClass": "PUBLIC_KEY",
"KeyAlgorithm": "RSA_4096",
"KeyModesOfUse": {
"Verify": true
}
},
"Enabled": true,
"KeyState": "CREATE_COMPLETE",
"KeyOrigin": "EXTERNAL"
}
}
```
Take note of the CA's `KeyArn` for use in the export step.
### Step 6: Get KRD Encryption Certificate
In this example, we're importing back into AWS Payment Cryptography, so we call the service to receive a KRD public key certificate using the [GetParametersForImport](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_GetParametersForImport.html) API. In a real scenario, this would be provided by the other system, like an HSM, an ATM, a payment terminal or payment terminal management system.
**Example Get Parameters for Import**
```
$ aws payment-cryptography-data get-parameters-for-import \
--key-material-type "TR34_KEY_BLOCK" \
--wrapping-key-algorithm RSA_2048
```
```
{
"WrappingKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
"WrappingKeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
"WrappingKeyAlgorithm": "RSA_2048",
"ImportToken": "import-token-v2rxpl6drxeptn7w",
"ParametersValidUntilTimestamp": "2025-11-01T18:45:31.271000-07:00"
}
```
### Step 7: Export Key with BYOCA
Finally, export the key using TR-34 with your own CA-signed certificate using the [ExportKey](https://docs.aws.amazon.com/payment-cryptography/latest/DataAPIReference/API_ExportKey.html) API. Provide the signing certificate that was signed by your external CA.
**Example TR-34 Export with BYOCA**
```
$ aws payment-cryptography-data export-key \
--export-key-identifier arn:aws:payment-cryptography:us-east-1:111122223333:key/iox73p5f4c4yjiod \
--key-material '{
"Tr34KeyBlock": {
"CertificateAuthorityPublicKeyIdentifier": "arn:aws:payment-cryptography:us-east-1:111122223333:key/j625deyfqlwctu57",
"SigningKeyIdentifier": "arn:aws:payment-cryptography:us-east-1:111122223333:key/xgmq6fs6uow736uc",
"SigningKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...",
"KeyBlockFormat": "X9_TR34_2012",
"WrappingKeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t..."
}
}'
```
```
{
"WrappedKey": {
"WrappedKeyMaterialFormat": "TR34_KEY_BLOCK",
"KeyMaterial": "3082055A06092A864886F70D010702A082054B30820547...",
"KeyCheckValue": "3DCA31",
"KeyCheckValueAlgorithm": "ANSI_X9_24"
}
}
```
The exported key block can now be imported by the receiving system using the standard TR-34 import process.
## Additional Notes
+ These examples are shown using the AWS CLI. The same functionality is available in all AWS SDKs including Java, Python, Go, and Rust.
+ If you're testing with a self-signed CA, you can use OpenSSL to create a test CA and sign the CSR. In production, use your organization's established CA infrastructure.
# Using aliases
An *alias* is a friendly name for an AWS Payment Cryptography key. For example, an alias lets you refer to a key as `alias/test-key` instead of `arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h`.
You can use an alias to identify a key in most key management (control plane) operations, and in [cryptographic (data plane) operations](data-operations.md).
You can also allow and deny access to AWS Payment Cryptography key based on their aliases without editing policies or managing grants. This feature is part of the service's support for [attribute-based access control](security.md) (ABAC).
Much of the power of aliases comes from your ability to change the key associated with an alias at any time. Aliases can make your code easier to write and maintain. For example, suppose you use an alias to refer to a particular AWS Payment Cryptography key and you want to change the AWS Payment Cryptography key. In that case, just associate the alias with a different key. You don't need to change your code or application configuration.
Aliases also make it easier to reuse the same code in different AWS Regions. Create aliases with the same name in multiple Regions and associate each alias with an AWS Payment Cryptography key in its Region. When the code runs in each Region, the alias refers to the associated AWS Payment Cryptography key in that Region.
You can create an alias for an AWS Payment Cryptography key by using the `CreateAlias` API.
The AWS Payment Cryptography API provides full control of aliases in each account and Region. The API includes operations to create an alias (CreateAlias), view alias names and the linked keyARN (**list-aliases**), change the AWS Payment Cryptography key associated with an alias (**update-alias**), and delete an alias (**delete-alias**).
**Topics**
+ [About aliases](alias-about.md)
+ [Using aliases in your applications](alias-using.md)
+ [Related APIs](#w2aac12c30c23)
# About aliases
Learn how aliases work in AWS Payment Cryptography.
**An alias is an independent AWS resource**
An alias is not a property of an AWS Payment Cryptography key. The actions that you take on the alias don't affect its associated key. You can create an alias for an AWS Payment Cryptography key and then update the alias so it's associated with a different AWS Payment Cryptography key. You can even delete the alias without any effect on the associated AWS Payment Cryptography key. If you delete a AWS Payment Cryptography key, all aliases associated with that key will become unassigned.
If you specify an alias as the resource in an IAM policy, the policy refers to the alias, not to the associated AWS Payment Cryptography key.
**Each alias has a friendly name**
When you create an alias, you specify the alias name prefixed by `alias/`. For instance `alias/test_1234`
**Each alias is associated with one AWS Payment Cryptography key at a time**
The alias and its AWS Payment Cryptography key must be in the same account and Region.
An AWS Payment Cryptography key can be associated with more than one alias concurrently, but each alias can only be mapped to a single key
For example, this `list-aliases` output shows that the `alias/sampleAlias1` alias is associated with exactly one target AWS Payment Cryptography key, which is represented by the `KeyArn` property.
```
$ aws payment-cryptography list-aliases
```
```
{
"Aliases": [
{
"AliasName": "alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
]
}
```
**Multiple aliases can be associated with the same AWS Payment Cryptography key**
For example, you can associate the `alias/sampleAlias1;` and `alias/sampleAlias2` aliases with the same key.
```
$ aws payment-cryptography list-aliases
```
```
{
"Aliases": [
{
"AliasName": "alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
},
{
"AliasName": "alias/sampleAlias2",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
]
}
```
**An alias must be unique for a given account and Region**
For example, you can have only one `alias/sampleAlias1` alias in each account and Region. Aliases are case-sensitive, but we recommend against using aliases that only differ in capitalization as they can be prone to error. You cannot change an alias name. However, you can delete the alias and create a new alias with the desired name.
**You can create an alias with the same name in different Regions**
For example, you can have alias `alias/sampleAlias2` in US East (N. Virginia) and alias `alias/sampleAlias2` in US West (Oregon). Each alias would be associated with an AWS Payment Cryptography key in its Region. If your code refers to an alias name like `alias/finance-key`, you can run it in multiple Regions. In each Region, it uses a different alias/sampleAlias2. For details, see [Using aliases in your applications](alias-using.md).
**You can change the AWS Payment Cryptography key associated with an alias**
You can use the `UpdateAlias` operation to associate an alias with a different AWS Payment Cryptography key. For example, if the `alias/sampleAlias2` alias is associated with the `arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h ` AWS Payment Cryptography key, you can update it so it is associated with the `arn:aws:payment-cryptography:us-east-2:111122223333:key/tqv5yij6wtxx64pi` key.
AWS Payment Cryptography doesn't validate that the old and new keys have all the same attributes such as key usage. Updating with a different key type may result in problems in your application.
**Some keys don't have aliases**
An alias is an optional feature and not all keys will have aliases unless you choose to operate your environment in this way. Keys can be associated with Aliases using the `create-alias` command. Also, you can use the update-alias operation to change the AWS Payment Cryptography key associated with an alias and the delete-alias operation to delete an alias. As a result, some AWS Payment Cryptography keys might have several aliases, and some might have none.
**Mapping a key to an alias**
You can map a key (represented by an ARN) to one or more aliases using the `create-alias` command. This command is not idempotent - to update an alias, use the update-alias command.
```
$ aws payment-cryptography create-alias --alias-name alias/sampleAlias1 \
--key-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
```
```
{
"Alias": {
"AliasName": "alias/alias/sampleAlias1",
"KeyArn": "arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h"
}
}
```
# Using aliases in your applications
You can use an alias to represent an AWS Payment Cryptography key in your application code. The `key-identifier` parameter in AWS Payment Cryptography [data operations](data-operations.md) as well as other operations like List Keys accepts an alias name or alias ARN.
```
$ aws payment-cryptography-data generate-card-validation-data --key-identifier alias/BIN_123456_CVK --primary-account-number=171234567890123 --generation-attributes CardVerificationValue2={CardExpiryDate=0123}
```
When using an alias ARN, remember that the alias mapping to an AWS Payment Cryptography key is defined in the account that owns the AWS Payment Cryptography key and might differ in each Region.
One of the most powerful uses of aliases is in applications that run in multiple AWS Regions.
You could create a different version of your application in each Region or use a dictionary, configuration or switch statement to select the right AWS Payment Cryptography key for each Region. But it might be easier to create an alias with the same alias name in each Region. Remember that the alias name is case-sensitive.
## Related APIs
**[Tags](tagging-keys.md)**
Tags are key and value pairs that act as metadata for organizing your AWS Payment Cryptography keys. They can be used to flexibly identify keys or group one or more keys together.
# Get keys
An AWS Payment Cryptography key represents a single unit of cryptographic material and can only be used for cryptographic operations for this service. The GetKeys API takes a KeyIdentifier as input and returns key metadata including attributes, state, and timestamps, but does not return actual cryptographic key material.
**Example**
```
$ aws payment-cryptography get-key --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
```
```
{
"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": "AWS_PAYMENT_CRYPTOGRAPHY",
"CreateTimestamp": "2023-06-02T07:38:14.913000-07:00",
"UsageStartTimestamp": "2023-06-02T07:38:14.857000-07:00"
}
}
```
# Get the public key/certificate associated with a key pair
Get Public Key/Certificate returns the public key indicated by the `KeyArn`. This can be the public key portion of a key pair generated on AWS Payment Cryptography or a previously imported public key. The most common use case is to provide the public key to an outside service that will encrypt data. That data can then be passed to an application leveraging AWS Payment Cryptography and the data can be decrypted using the private key secured within AWS Payment Cryptography.
The service returns public keys as a public certificate. The API result contains the CA and the public key certificate. Both data elements are base64 encoded.
**Note**
The public certificate returned is intended to be short lived and is not intended to be idempotent. You may receive a different certificate on each API call even the public key itself is unchanged.
**Example**
```
$ aws payment-cryptography get-public-key-certificate --key-identifier arn:aws:payment-cryptography:us-east-2:111122223333:key/nsq2i3mbg6sn775f
```
```
{
"KeyCertificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUV2VENDQXFXZ0F3SUJBZ0lSQUo1OWd2VkpDd3dlYldMNldYZEpYYkl3RFFZSktvWklodmNOQVFFTkJRQXcKZ1lreEN6QUpCZ05WQkFZVEFsVlRNUmt3RndZRFZRUUtEQkJCVjFNZ1EzSjVjSFJ2WjNKaGNHaDVNU0V3SHdZRApWUVFMREJoQlYxTWdVR0Y1YldWdWRDQkRjbmx3ZEc5bmNtRndhSGt4RVRBUEJnTlZCQWdNQ0ZacGNtZHBibWxoCk1SVXdFd1lEVlFRRERBdzFNamt3TWpjME5UVTBPVFV4RWpBUUJnTlZCQWNNQ1VGeWJHbHVaM1J2YmpBZUZ3MHkKTXpBMk1EWXdNalEzTlRWYUZ3MHlNekE1TURRd016UTNOVFZhTUN3eEZUQVRCZ05WQkFNTUREVXlPVEF5TnpRMQpOVFE1TlRFVE1CRUdBMVVFQlJNS05EUTBPREV4TnpZMU1UQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQCkFEQ0NBUW9DZ2dFQkFOZ0loOS9lckd2azJTbHJ6K1ZaVkl0WXpEMDh3QkoxWVZKaDY1Z1J3NkFzbWJ4RUpYc1cKMjI5b3B1ZjhlOFU5TlBQbXU4TSs1YlRkcUxlbmI0cUowMm5abEtKWmVsdjdpVmQ5YjBmRnV6azlWb1RMMVN4dwpqeTBRd0ZDcTZUUlZveGE2d21PMGRwMHVMV2NBSm9UcENBc2U4ckk4czUxczlFMERaanZqald2cHhwOVRwMUhQClhBNmlzQ2lyUTR2b2FwWlpQNENLTjR6Wm13TE5oaUtuSDVhVnRyWkgyeXBzSll4aGIrTWcwUHZUUnRrRE9VTDcKKzdjb2diUWVlNWx1NDZJWDlyN1ZyRWVTYjEraENrQW5vb1JOL3k1aCtremYySzU4WWxpSWJEdE5aemlYRldIWgpXUnhYK1BWMnhwMFhGMmJUZTVEd2gyVWZ6U1JlNzhqZXlya0NBd0VBQWFOOE1Ib3dDUVlEVlIwVEJBSXdBREFmCkJnTlZIU01FR0RBV2dCUXVpSzJoYkc3VTlOUmYyM0FodTRMVkJtV3QwekFkQmdOVkhRNEVGZ1FVZTFLbWJqby8KOVMwVDZKOUVzT2R2bHRuKzNGb3dEZ1lEVlIwUEFRSC9CQVFEQWdXZ01CMEdBMVVkSlFRV01CUUdDQ3NHQVFVRgpCd01CQmdnckJnRUZCUWNEQWpBTkJna3Foa2lHOXcwQkFRMEZBQU9DQWdFQXNndUZpOVNsZmxCMHVTc2pySXFDCmQ2S3ZSZUdwSmlEZjVjVW4xZmJCeXlzL3NHVzI0dWRkeEc4SDdzQXp0MnlTZnM5L3hTZ1NIOFlqM25sU2l3clkKcS80R2x3Zk5FajBnanY2K1crNk1BazNWK2tjUVhMaUtwZlFrN3Z5OGMvcWRwK2tYd2N2K1pxUG1IUk5yNGl6eQpDSU5zVm04cDl5M0pZWlkwZWZrZU52bDR6enI4RGtNa3hva0liMVcyZVA0cm1BR2w2UHhLYVZmNnNLT1NoYlFXCm1heDBPalg2azdWNWdvbXdSMGVaVEtNQXhTUWpQRU5OSDllMi9kZTRJNG5WVXRFbWU2RjM5SWdiZmZicEhjMEkKNXdsN3FidUMvYnprcnNsNGRzOXB6Q3lQcFVUZjVQOWg5MkVqMzNURzJ1VEZURzRVQm0wMUVMYzFaTjhXbW12WgpWUk92M1VUSWlmQnd2em16OUpjUUZ5R3Nsa2prOTBJdkV0U3lld2psYW52cy9kanRJL2JzRFFPKzI1M2ltOFFRClJkSWVaUTRleWI5YTJxeDVtWDZHOWJ6RDBVRkVxN2JoTlppZlhzNE1YWEFjS051TnpYS1Zja1hKM0trYWt1TUcKVE5BTzc4T01qUUlTWk5NeXE2WmM2MVJVcFBVZ1R1K2Vhd1FGRzBBU0Yxb2w4Wjc4cEFSeE9Oc1lGdkQ5Y3BnUQpzSnlzeDB0Zjl6aTR5Zi80aWNOSkVlWVVNY0lGSXlFKzE0eDBpcFVSRTRGenRad2orYlZFeHdiM0h4aVJQMncyCkJLSnVKeXd4ZGx2L1hTZU1XaDl3UkNCb3lLeXFxWVdWcDcweW15N01oSFlVSERUWEFPL1NJN3B5VnVLaDBReUYKR1pEOHRibi9TR2RqQ0pETEM4bWlmNk09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=",
"KeyCertificateChain": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUY0VENDQThtZ0F3SUJBZ0lSQUtlN2piaHFKZjJPd3FGUWI5c3VuOEV3RFFZSktvWklodmNOQVFFTkJRQXcKZ1lreEN6QUpCZ05WQkFZVEFsVlRNUmt3RndZRFZRUUtEQkJCVjFNZ1EzSjVjSFJ2WjNKaGNHaDVNU0V3SHdZRApWUVFMREJoQlYxTWdVR0Y1YldWdWRDQkRjbmx3ZEc5bmNtRndhSGt4RVRBUEJnTlZCQWdNQ0ZacGNtZHBibWxoCk1SVXdFd1lEVlFRRERBdzFNamt3TWpjME5UVTBPVFV4RWpBUUJnTlZCQWNNQ1VGeWJHbHVaM1J2YmpBZUZ3MHkKTXpBMk1EWXdNalEzTlRKYUZ3MHlPREEyTURZd016UTNOVEphTUlHSk1Rc3dDUVlEVlFRR0V3SlZVekVaTUJjRwpBMVVFQ2d3UVFWZFRJRU55ZVhCMGIyZHlZWEJvZVRFaE1COEdBMVVFQ3d3WVFWZFRJRkJoZVcxbGJuUWdRM0o1CmNIUnZaM0poY0doNU1SRXdEd1lEVlFRSURBaFdhWEpuYVc1cFlURVZNQk1HQTFVRUF3d01OVEk1TURJM05EVTEKTkRrMU1SSXdFQVlEVlFRSERBbEJjbXhwYm1kMGIyNHdnZ0lpTUEwR0NTcUdTSWIzRFFFQkFRVUFBNElDRHdBdwpnZ0lLQW9JQ0FRQzJyMld2eGJxZjJSUHhOem1JUk5ZeWZRQ2labGxYUVBQSDQycnAyQ1VtTk1VMkc2ZzdFRUZBCm5TWnNvRlN6Z1NJaEhUSWU4UDdUd1l3ckpPL3VNcEtka3lac1ppTEhUNGo4M1l1VkNlT1dSVERjdnRWMFV0M1IKaCs5UWVyaHhRQnVrK2dnZkRkT0FFUkR3S1pWckZqM3diT1FFMXY2WnRYSmpVZytWTXZKcEphUTg0WkFvYnpyUgpuY2JaL0hnbFhDM09xampSSk1laGJFaE93ZFJCTU4yQ2dTNHlhWTB3YlBvazhMSlRORVp5ZnkxUEtkaTd1UmxxCm9qeEdjc3pCRHFvdCsvTURBNVdZUjd5NVhiOGdOdSt0alkrMWdQSGRkWHFhRTR2bXV2cEtsQUttcml2SDRYWXQKZk9sa1kzYnRJckVuWDEwQkp1UXVGN0dRNyt3ZjN6TDZ4NFNIcGpiQWxpMDQyUmdXTVpibmlscW15YnhuUkRrUwpjZXZ3aEx2L0tnT09WM05KZlplWlVzT1N6NWNzTmRLME4rM2FCUlZQcVc5b2k3dDJ2dTc5eCtvb1pIS2FibFdiCmJDMDJxR1VDaTE3cHhDQ0JJdUVDZWJiWDhSS3dLa3RwbTRSOUZWYjBXZGFqNUc1ekdudTBsUlRMUVNaZ0QyU1EKSjRmQjh2em9Bb3BYenpSSStMSjNBaC9NcThXSTNHTHFIakhzcm5vdVJzMmNzcjVBYnNMbXUyUTlvMFJmNTd1RApwK1R1cXpKTysrNFpUWDlsb0N3UXdzKzNEZWUyL1pUSmJCNkFCdy9xdnovQjhsL2duY29Wc3lHTFhkaXdleTV1CjJHNnl2NGgrN0FBQldvdjhwWVBPUlRMY1FkanhVdWNDdllRYjJiRXY4ZGh1anN6TWo2ZDBDUUlEQVFBQm8wSXcKUURBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUIwR0ExVWREZ1FXQkJRdWlLMmhiRzdVOU5SZjIzQWh1NExWQm1XdAowekFPQmdOVkhROEJBZjhFQkFNQ0FZWXdEUVlKS29aSWh2Y05BUUVOQlFBRGdnSUJBSS9Ta1NaS0pyMm1JakJ6ClJxQXQ3dmJ4eWNhQXhCU3VqbDlqVSttYkh1RDg4Qyt3TDh4TzNYRHJ1Vm9IZTdYanhrNXpaN0RWMjMza3haQlEKR3BET1hWaGNZdE5UNzk2YXd1K0VNU2kzK3RzTVJBMmMxODJ2ZVNDSE9HQmVseTlRS3FHWkJBZGU2ZGNzTkpMTwpiRE10NlB3NXpiRHNqalJnMGY5SGQrRFZheXV6QzBtdXVGWEZkT0txU0VWZVNmZWVNOUl5KzFMWDMzOFlVd05zCjdhS2ppaFVFSkg4ZkVFU1NEUGE5OGNOSEsyZ0t5UENrRUorMGlNZkJiTi9yUE1CYlhqTUtHYWpXSFFhWWtieDUKalVRUmdvd25ZbStycDRwRnNhalpSTFB0NE9mbkswNWYvRHdCUXVGWUUzUFJ2d2NQSWxJNHpkcWh0NE9ZSVY4RAo2MktleVEzb3R6eTdsVXIxamNrZldkSHpHc3NKVjYxc0xRTTBudVFNUnRTZjlHeEpYTEkyNjFaRWFMYVY5WFduCnY3YnByb090UTNiYk9RbjI0elJDVm5kZ0Z3aCtUVHMzVmFOQjhURmY2QjFoV1R5aTYzOCtoa1FTRnJTbXI1WTcKTXNGUXZXSVZVbjQ2cWNjVGNuNlc2Y2JIUlhyQkRiR0tlWUJiVjVXSkJwRUtSN0JuQ25HNnJCbmxGNjZ5eTUyLwpSbWZLRWZwWG1qbkh0WW94UnlQVlJZWDhPcnkzUFQrYSt0REtlMDBXY1MyM0U3MWl2QTBNdnVrODlwTzJIUVorCjNHUU9xdWJpQ3RMbVppdVFCZC9aN1NGWGlzcUxyTE5aOW52Q2VRSkxTckVDajRpZjV2dmJkWVhLdkozamhtSjkKeVZvc0xZVzA3SklzSFE0aDAwVWphSnhrVjdoWgotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t"
}
```
# Tagging keys
In AWS Payment Cryptography, you can add tags to a AWS Payment Cryptography key when you [create a key](create-keys.md), and tag or untag existing keys unless they are pending deletion. Tags are optional, but they can be very useful.
For general information about tags, including best practices, tagging strategies, and the format and syntax of tags, see [Tagging AWS resources](/tag-editor/latest/userguide/tagging.html) in the *Amazon Web Services General Reference*.
**Topics**
+ [About tags in AWS Payment Cryptography](tags-about.md)
+ [Viewing key tags in the console](manage-tags-console.md)
+ [Managing key tags with API operations](manage-tags-api.md)
+ [Controlling access to tags](tag-permissions.md)
+ [Using tags to control access to keys](tag-authorization.md)
# About tags in AWS Payment Cryptography
A *tag* is an optional metadata label that you can assign (or AWS can assign) to an AWS resource. Each tag consists of a *tag key* and a *tag value*, both of which are case-sensitive strings. The tag value can be an empty (null) string. Each tag on a resource must have a different tag key, but you can add the same tag to multiple AWS resources. Each resource can have up to 50 user-created tags.
Do not include confidential or sensitive information in the tag key or tag value. Tags are accessible to many AWS services, including billing.
In AWS Payment Cryptography, you can add tags to a key when you [create the key](create-keys.md), and tag or untag existing keys unless they are pending deletion. You cannot tag aliases. Tags are optional, but they can be very useful.
For example, you can add a `"Project"="Alpha"` tag to all AWS Payment Cryptography keys and Amazon S3 buckets that you use for the Alpha project. Another example is to add `"BIN"="20130622"` tag to all keys associated to a specific bank identification number(BIN).
```
[
{
"Key": "Project",
"Value": "Alpha"
},
{
"Key": "BIN",
"Value": "20130622"
}
]
```
For general information about tags, including the format and syntax, see [Tagging AWS resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the *Amazon Web Services General Reference*.
Tags help you do the following:
+ Identify and organize your AWS resources. Many AWS services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you can assign the same tag to an AWS Payment Cryptography keys and an Amazon Elastic Block Store (Amazon EBS) volume or AWS Secrets Manager secret. You can also use tags to identify keys for automation.
+ Track your AWS costs. When you add tags to your AWS resources, AWS generates a cost allocation report with usage and costs aggregated by tags. You can use this feature to track AWS Payment Cryptography costs for a project, application, or cost center.
For more information about using tags for cost allocation, see [Using Cost Allocation Tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*. For information about the rules for tag keys and tag values, see [User-Defined Tag Restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) in the *AWS Billing User Guide*.
+ Control access to your AWS resources. Allowing and denying access to keys based on their tags is part of AWS Payment Cryptography support for attribute-based access control (ABAC). For information about controlling access to AWS Payment Cryptography based on their tags, see [Authorization based on AWS Payment Cryptography tags](security_iam_service-with-iam.md#security_iam_service-with-iam-tags). For more general information about using tags to control access to AWS resources, see [Controlling Access to AWS Resources Using Resource Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*.
AWS Payment Cryptography writes an entry to your AWS CloudTrail log when you use the TagResource, UntagResource, or ListTagsForResource operations.
# Viewing key tags in the console
To view tags in the console, you need tagging permission on the key from an IAM policy that includes the key. You need these permissions in addition to the permissions to view keys in the console.
# Managing key tags with API operations
You can use the [AWS Payment Cryptography API](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/Welcome.html) to add, delete, and list tags for the keys that you manage. These examples use the [AWS Command Line Interface (AWS CLI)](https://aws.amazon.com/cli/), but you can use any supported programming language. You cannot tag AWS managed keys.
To add, edit, view, and delete tags for a key, you must have the required permissions. For details, see [Controlling access to tags](tag-permissions.md).
**Topics**
+ [CreateKey: Add tags to a new key](#tagging-keys-create-key)
+ [TagResource: Add or change tags for a key](#tagging-keys-tag-resource)
+ [ListResourceTags: Get the tags for a key](#tagging-keys-list-resource-tags)
+ [UntagResource: Delete tags from a key](#tagging-keys-untag-resource)
## CreateKey: Add tags to a new key
You can add tags when you create a key. To specify the tags, use the `Tags` parameter of the [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) operation.
To add tags when creating a key, the caller must have `payment-cryptography:TagResource` permission in an IAM policy. At a minimum, the permission must cover all keys in the account and Region. For details, see [Controlling access to tags](tag-permissions.md).
The value of the `Tags` parameter of `CreateKey` is a collection of case-sensitive tag key and tag value pairs. Each tag on a key must have a different tag name. The tag value can be a null or empty string.
For example, the following AWS CLI command creates a symmetric encryption key with a `Project:Alpha` tag. When specifying more than one key-value pair, use a space to separate each pair.
```
$ 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}' \
--tags '[{"Key":"Project","Value":"Alpha"},{"Key":"BIN","Value":"123456"}]'
```
When this command is successful, it returns a `Key` object with information about the new key. However, the `Key` does not include tags. To get the tags, use the [ListResourceTags](#tagging-keys-list-resource-tags) operation.
## TagResource: Add or change tags for a key
The [TagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_TagResource.html) operation adds one or more tags to a key. You cannot use this operation to add or edit tags in a different AWS account.
To add a tag, specify a new tag key and a tag value. To edit a tag, specify an existing tag key and a new tag value. Each tag on a key must have a different tag key. The tag value can be a null or empty string.
For example, the following command adds **UseCase** and **BIN** tags to an example key.
```
$ aws payment-cryptography tag-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h --tags '[{"Key":"UseCase","Value":"Acquiring"},{"Key":"BIN","Value":"123456"}]'
```
When this command is successful, it does not return any output. To view the tags on a key, use the [ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html) operation.
You can also use **TagResource** to change the tag value of an existing tag. To replace a tag value, specify the same tag key with a different value. Tags not listed in a modify command are not changed or removed.
For example, this command changes the value of the `Project` tag from `Alpha` to `Noe`.
The command will return http/200 with no content. To see your changes, use `ListTagsForResource`
```
$ aws payment-cryptography tag-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h \
--tags '[{"Key":"Project","Value":"Noe"}]'
```
## ListResourceTags: Get the tags for a key
The [ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html) operation gets the tags for a key. The `ResourceArn` (keyArn or keyAlias) parameter is required. You cannot use this operation to view the tags on keys in a different AWS account.
For example, the following command gets the tags for an example key.
```
$ aws payment-cryptography list-tags-for-resource --resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h
{
"Tags": [
{
"Key": "BIN",
"Value": "20151120"
},
{
"Key": "Project",
"Value": "Production"
}
]
}
```
## UntagResource: Delete tags from a key
The [UntagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_UntagResource.html) operation deletes tags from a key. To identify the tags to delete, specify the tag keys. You cannot use this operation to delete tags from keys a different AWS account.
When it succeeds, the `UntagResource` operation doesn't return any output. Also, if the specified tag key isn't found on the key, it doesn't throw an exception or return a response. To confirm that the operation worked, use the [ListResourceTags](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListTagsForResource.html) operation.
For example, this command deletes the **Purpose** tag and its value from the specified key.
```
$ aws payment-cryptography untag-resource \
--resource-arn arn:aws:payment-cryptography:us-east-2:111122223333:key/kwapwa6qaifllw2h --tag-keys Project
```
# Controlling access to tags
To add, view, and delete tags by using the API, principals need tagging permissions in IAM policies.
You can also limit these permissions by using AWS global condition keys for tags. In AWS Payment Cryptography, these conditions can control access to tagging operations, such as [TagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_TagResource.html) and [UntagResource](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_UntagResource.html).
For example policies and more information, see [Controlling Access Based on Tag Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys) in the *IAM User Guide*.
Permissions to create and manage tags work as follows.
**payment-cryptography:TagResource**
Allows principals to add or edit tags. To add tags while creating a key, the principal must have permission in an IAM policy that isn't restricted to particular keys.
**payment-cryptography:ListTagsForResource**
Allows principals to view tags on keys.
**payment-cryptography:UntagResource**
Allows principals to delete tags from keys.
## Tag permissions in policies
You can provide tagging permissions in a key policy or IAM policy. For example, the following example key policy gives select users tagging permission on the key. It gives all users who can assume the example Administrator or Developer roles permission to view tags.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "example-key-policy",
"Statement": [
{
"Sid": "EnableIAMUserPermissions",
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::111122223333:root"},
"Action": "payment-cryptography:*",
"Resource": "*"
},
{
"Sid": "AllowAllTaggingPermissions",
"Effect": "Allow",
"Principal": {"AWS": [
"arn:aws:iam::111122223333:user/LeadAdmin",
"arn:aws:iam::111122223333:user/SupportLead"
]},
"Action": [
"payment-cryptography:TagResource",
"payment-cryptography:ListTagsForResource",
"payment-cryptography:UntagResource"
],
"Resource": "*"
},
{
"Sid": "Allow roles to view tags",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/Administrator",
"arn:aws:iam::111122223333:role/Developer"
]
},
"Action": "payment-cryptography:ListTagsForResource",
"Resource": "*"
}
]
}
```
------
To give principals tagging permission on multiple keys, you can use an IAM policy. For this policy to be effective, the key policy for each key must allow the account to use IAM policies to control access to the key.
For example, the following IAM policy allows the principals to create keys. It also allows them to create and manage tags on all keys in the specified account. This combination allows the principals to use the tags parameter of the [CreateKey](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_CreateKey.html) operation to add tags to a key while they are creating it.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IAMPolicyCreateKeys",
"Effect": "Allow",
"Action": "payment-cryptography:CreateKey",
"Resource": "*"
},
{
"Sid": "IAMPolicyTags",
"Effect": "Allow",
"Action": [
"payment-cryptography:TagResource",
"payment-cryptography:UntagResource",
"payment-cryptography:ListTagsForResource"
],
"Resource": "arn:aws:payment-cryptography:*:111122223333:key/*"
}
]
}
```
------
## Limiting tag permissions
You can limit tagging permissions by using policy conditions. The following policy conditions can be applied to the `payment-cryptography:TagResource` and `payment-cryptography:UntagResource` permissions. For example, you can use the `aws:RequestTag/tag-key` condition to allow a principal to add only particular tags, or prevent a principal from adding tags with particular tag keys.
+ [aws:RequestTag](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-requesttag)
+ [aws:ResourceTag/*tag-key*](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag) (IAM policies only)
+ [aws:TagKeys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-tag-keys)
As a best practice when you use tags to control access to keys, use the `aws:RequestTag/tag-key` or `aws:TagKeys` condition key to determine which tags (or tag keys) are allowed.
For example, the following IAM policy is similar to the previous one. However, this policy allows the principals to create tags (`TagResource`) and delete tags `UntagResource` only for tags with a `Project` tag key.
Because `TagResource` and `UntagResource` requests can include multiple tags, you must specify a `ForAllValues` or `ForAnyValue` set operator with the [aws:TagKeys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-tagkeys) condition. The `ForAnyValue` operator requires that at least one of the tag keys in the request matches one of the tag keys in the policy. The `ForAllValues` operator requires that all of the tag keys in the request match one of the tag keys in the policy. The `ForAllValues` operator also returns `true` if there are no tags in the request, but TagResource and UntagResource fail when no tags are specified. For details about the set operators, see [Use multiple keys and values](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_multi-value-conditions.html#reference_policies_multi-key-or-value-conditions) in the *IAM User Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IAMPolicyCreateKey",
"Effect": "Allow",
"Action": "payment-cryptography:CreateKey",
"Resource": "*"
},
{
"Sid": "IAMPolicyViewAllTags",
"Effect": "Allow",
"Action": "payment-cryptography:ListTagsForResource",
"Resource": "arn:aws:payment-cryptography:*:111122223333:key/*"
},
{
"Sid": "IAMPolicyManageTags",
"Effect": "Allow",
"Action": [
"payment-cryptography:TagResource",
"payment-cryptography:UntagResource"
],
"Resource": "arn:aws:payment-cryptography:*:111122223333:key/*",
"Condition": {
"ForAllValues:StringEquals": {"aws:TagKeys": "Project"}
}
}
]
}
```
------
# Using tags to control access to keys
You can control access to AWS Payment Cryptography based on the tags on the key. For example, you can write an IAM policy that allows principals to enable and disable only the keys that have a particular tag. Or you can use an IAM policy to prevent principals from using keys in cryptographic operations unless the key has a particular tag.
This feature is part of AWS Payment Cryptography support for attribute-based access control(ABAC). For information about using tags to control access to AWS resources, see [What is ABAC for AWS?](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html) and [Controlling Access to AWS Resources Using Resource Tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*.
AWS Payment Cryptography supports the [aws:ResourceTag/*tag-key*](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resourcetag) global condition context key, which lets you control access to keys based on the tags on the key. Because multiple keys can have the same tag, this feature lets you apply the permission to a select set of keys. You can also easily change the keys in the set by changing their tags.
In AWS Payment Cryptography, the `aws:ResourceTag/tag-key` condition key is supported only in IAM policies. It isn't supported in key policies, which apply only to one key, or on operations that don't use a particular key, such as the [ListKeys](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListKeys.html) or [ListAliases](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_ListAliases.html) operations.
Controlling access with tags provides a simple, scalable, and flexible way to manage permissions. However, if not properly designed and managed, it can allow or deny access to your keys inadvertently. If you are using tags to control access, consider the following practices.
+ Use tags to reinforce the best practice of [least privileged access](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). Give IAM principals only the permissions they need on only the keys they must use or manage. For example, use tags to label the keys used for a project. Then give the project team permission to use only keys with the project tag.
+ Be cautious about giving principals the `payment-cryptography:TagResource` and `payment-cryptography:UntagResource` permissions that let them add, edit, and delete tags. When you use tags to control access to keys, changing a tag can give principals permission to use keys that they didn't otherwise have permission to use. It can also deny access to keys that other principals require to do their jobs. Key administrators who don't have permission to change key policies or create grants can control access to keys if they have permission to manage tags.
Whenever possible, use a policy condition, such as `aws:RequestTag/tag-key` or `aws:TagKeys` to [limit a principal's tagging permissions](tag-permissions.md#tag-permissions-conditions) to particular tags or tag patterns on particular keys.
+ Review the principals in your AWS account that currently have tagging and untagging permissions and adjust them, if necessary. IAM policies might allow tag and untag permissions on all keys. For example, the *Admin* managed policy allows principals to tag, untag, and list tags on all keys.
+ Before setting a policy that depends on a tag, review the tags on the keys in your AWS account. Make sure that your policy applies only to the tags you intend to include. Use [CloudTrail logs](monitoring-cloudtrail.md) and CloudWatch alarms to alert you to tag changes that might affect access to your keys.
+ The tag-based policy conditions use pattern matching; they aren't tied to a particular instance of a tag. A policy that uses tag-based condition keys affects all new and existing tags that match the pattern. If you delete and recreate a tag that matches a policy condition, the condition applies to the new tag, just as it did to the old one.
For example, consider the following IAM policy. It allows the principals to call the [Decrypt](https://docs.aws.amazon.com/payment-cryptography/latest/APIReference/API_Decrypt.html) operations only on keys in your account that are the US East (N. Virginia) Region and have a `"Project"="Alpha"` tag. You might attach this policy to roles in the example Alpha project.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IAMPolicyWithResourceTag",
"Effect": "Allow",
"Action": [
"payment-cryptography:DecryptData"
],
"Resource": "arn:aws:payment-cryptography:us-east-1:111122223333:key/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Project": "Alpha"
}
}
}
]
}
```
------
The following example IAM policy allows the principals to use any key in the account for certain cryptographic operations. But it prohibits the principals from using these cryptographic operations on keys with a `"Type"="Reserved"` tag or no `"Type"` tag.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "IAMAllowCryptographicOperations",
"Effect": "Allow",
"Action": [
"payment-cryptography:EncryptData",
"payment-cryptography:DecryptData",
"payment-cryptography:ReEncrypt*"
],
"Resource": "arn:aws:payment-cryptography:*:111122223333:key/*"
},
{
"Sid": "IAMDenyOnTag",
"Effect": "Deny",
"Action": [
"payment-cryptography:EncryptData",
"payment-cryptography:DecryptData",
"payment-cryptography:ReEncrypt*"
],
"Resource": "arn:aws:payment-cryptography:*:111122223333:key/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/Type": "Reserved"
}
}
},
{
"Sid": "IAMDenyNoTag",
"Effect": "Deny",
"Action": [
"payment-cryptography:EncryptData",
"payment-cryptography:DecryptData",
"payment-cryptography:ReEncrypt*"
],
"Resource": "arn:aws:kms:*:111122223333:key/*",
"Condition": {
"Null": {
"aws:ResourceTag/Type": "true"
}
}
}
]
}
```
------
# Understanding key attributes for AWS Payment Cryptography key
A tenet of proper key management is that keys are appropriately scoped and can only be used for permitted operations. As such, certain keys can only be created with certain key modes of use. Whenever possible, this aligns with the available modes of use as defined by [TR-31](terminology.md#terms.tr31).
Although AWS Payment Cryptography will prevent you from creating invalid keys, valid combinations are provided here for your convenience.
## Symmetric Keys
+ TR31\$1B0\$1BASE\$1DERIVATION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1,\$1 NoRestrictions = true \$1
+ TR31\$1C0\$1CARD\$1VERIFICATION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1D0\$1SYMMETRIC\$1DATA\$1ENCRYPTION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 , \$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1E0\$1EMV\$1MKEY\$1APP\$1CRYPTOGRAMS
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY\$1, AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1E1\$1EMV\$1MKEY\$1CONFIDENTIALITY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY, AES\$1128\$1,AES\$1192\$1,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1E2\$1EMV\$1MKEY\$1INTEGRITY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1E4\$1EMV\$1MKEY\$1DYNAMIC\$1NUMBERS
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1E5\$1EMV\$1MKEY\$1CARD\$1PERSONALIZATION
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1E6\$1EMV\$1MKEY\$1OTHER
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128\$1 ,AES\$1192\$1 ,AES\$1256\$1
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1, \$1 NoRestrictions = true \$1
+ TR31\$1K0\$1KEY\$1ENCRYPTION\$1KEY
+ Recommended to use TR31\$1K1\$1KEY\$1BLOCK\$1PROTECTION\$1KEY. **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 , \$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1K1\$1KEY\$1BLOCK\$1PROTECTION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 , \$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1M1\$1ISO\$19797\$11\$1MAC\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1M3\$1ISO\$19797\$13\$1MAC\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1M6\$1ISO\$19797\$15\$1CMAC\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1M7\$1HMAC\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1P0\$1PIN\$1ENCRYPTION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 ,\$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1V1\$1IBM3624\$1PIN\$1VERIFICATION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
+ TR31\$1V2\$1VISA\$1PIN\$1VERIFICATION\$1KEY
+ **Allowed Key Algorithms**: TDES\$12KEY ,TDES\$13KEY ,AES\$1128 ,AES\$1192 ,AES\$1256
+ **Allowed combination of key modes of use**: \$1 Generate = true \$1 ,\$1 Verify = true \$1 ,\$1 Generate = true, Verify= true \$1 ,\$1 NoRestrictions = true \$1
## Asymmetric Keys
+ TR31\$1D1\$1ASYMMETRIC\$1KEY\$1FOR\$1DATA\$1ENCRYPTION
+ **Allowed Key Algorithms**: RSA\$12048 ,RSA\$13072 ,RSA\$14096
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 ,\$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1
+ **NOTE:**: \$1 Encrypt = true, Wrap = true \$1 is the only valid option when importing a public key that is intended for encrypting data or wrapping a key
+ TR31\$1S0\$1ASYMMETRIC\$1KEY\$1FOR\$1DIGITAL\$1SIGNATURE
+ **Allowed Key Algorithms**: RSA\$12048 ,RSA\$13072 ,RSA\$14096
+ **Allowed combination of key modes of use**: \$1 Sign = true \$1 ,\$1 Verify = true \$1
+ **NOTE:**: \$1 Verify = true \$1 is the only valid option when importing a key meant for signing, such as root certificate, intermediate certificate or signing certificates for TR-34.
+ TR31\$1K3\$1ASYMMETRIC\$1KEY\$1FOR\$1KEY\$1AGREEMENT
+ Used for key agreement algorithms such as ECDH
+ **Allowed Key Algorithms**: ECC\$1NIST\$1P256,ECC\$1NIST\$1P384,ECC\$1NIST\$1P521
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1.
+ **NOTE:**DeriveKeyUsage is used to specify what kind of key will be derived from this base key. This is fixed at key creation/import.
+ TR31\$1K2\$1TR34\$1ASYMMETRIC\$1KEY
+ Asymmetric key used for X9.24 compatible key exchange mechanisms like TR-34
+ **Allowed Key Algorithms**: RSA\$12048,RSA\$13072,RSA\$14096
+ **Allowed combination of key modes of use**: \$1 DeriveKey = true \$1.
+ **Allowed combination of key modes of use**: \$1 Encrypt = true, Decrypt = true, Wrap = true, Unwrap = true \$1 ,\$1 Encrypt = true, Wrap = true \$1 ,\$1 Decrypt = true, Unwrap = true \$1
+ **NOTE:**: \$1 Encrypt = true, Wrap = true \$1 is the only valid option when importing a public key that is intended for encrypting data or wrapping a key
\$1 This algorithm/key type combination is not currently supported by any cryptographic operations