# 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" } } } ] } ``` ------