AWS Crypto Tools . Amazon AWS Amazon AWS 20 August 2022 aws-kms-key-arn aws-kms-key-arn Abstract The aws-kms-key-arn specification for the AWS Encryption SDK. Table of Contents 1. Conventions and Definitions 2. AWS KMS Key ARN 2.1. Version 2.1.1. Changelog 2.2. Implementations 2.3. Overview 2.4. Definitions 2.4.1. Conventions used in this document 2.5. A valid AWS KMS ARN 2.6. A valid AWS KMS identifier 2.7. AWS KMS multi-Region keys 2.8. Identifying an an AWS KMS multi-Region ARN 2.9. Identifying an an AWS KMS multi-Region identifier 3. Normative References Acknowledgments Author's Address 1. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 2. AWS KMS Key ARN 2.1. Version 0.2.2 2.1.1. Changelog * 0.2.2 - Initial record 2.2. Implementations | Language | Confirmed Compatible with Spec Version | Minimum Version Confirmed | Implementation | | -------- | -------------------------------------- | ------------------------- | -------------- | 2.3. Overview arn:partition:service:region:account-id:resource-type:resource-id AWS KMS Key ARNs generally follow the AWS ARN syntax (https://docs.aws.amazon.com/general/latest/gr/aws-arns-and- namespaces.html) but there are a few subtle differences. This is NOT the authoritative source for these rules, it is just a specification for how the ESDK processes AWS KMS CMK ARNs. 2.4. Definitions 2.4.1. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (https://tools.ietf.org/html/rfc2119). 2.5. A valid AWS KMS ARN An AWS KMS Key ARN is a string in the form: arn:partition:service:region:account:resource-type/resource-id A valid AWS KMS ARN is a string with 5 ":" that MUST delimit the following 6 parts: 1. It MUST start with string "arn" 2. The partition MUST be a non-empty 3. The service MUST be the string "kms" 4. The region MUST be a non-empty string 5. The account MUST be a non-empty string 6. The resource section MUST be non-empty. It MUST be split by a single "/", with any any additional "/" included in the resource id 1. The resource type MUST be either "alias" or "key" 2. The resource id MUST be a non-empty string 2.6. A valid AWS KMS identifier An AWS KMS identifier can be any of the following * A valid AWS KMS ARN * AWS KMS alias, consisting of only the resource section of an AWS KMS alias ARN * AWS KMS key id, consisting of only the resource id of an AWS KMS key ARN 2.7. AWS KMS multi-Region keys AWS KMS multi-Region keys can be distinguished from a single-Region key because the key id begins with "mrk-". AWS KMS MRK aware components can take as input any AWS KMS identifier: * AWS KMS key ARN ("arn:aws:kms:us-east- 1:2222222222222:key/1234abcd-12ab-34cd-56ef-1234567890ab") * AWS KMS multi-Region key ARN ("arn:aws:kms:us-east- 1:2222222222222:key/mrk-4321abcd12ab34cd56ef1234567890ab") * AWS KMS alias ARN ("arn:aws:kms:us-west-2:111122223333:alias/test- key") * AWS KMS key id ("1234abcd-12ab-34cd-56ef-1234567890ab") * AWS KMS multi-Region key id ("mrk- 4321abcd12ab34cd56ef1234567890ab") * AWS KMS alias ("alias/test-key") Since the alias can be any string a customer can create an alias that started with "mrk-". But an alias is not a multi-Region key. 2.8. Identifying an an AWS KMS multi-Region ARN This function MUST take a single AWS KMS ARN If the input is an invalid AWS KMS ARN this function MUST error. If resource type is "alias", this is an AWS KMS alias ARN and MUST return false. If the resource type is "key" and the resource ID starts with "mrk-", this is a AWS KMS multi-Region key ARN and MUST return true. If the resource type is "key" and the resource ID does not start with "mrk-", this is a (single-region) AWS KMS key ARN and MUST return false. 2.9. Identifying an AWS KMS multi-Region identifier This function MUST take a single AWS KMS identifier If the input starts with "arn:", this MUST return the output of identifying an an AWS KMS multi-Region ARN (Section 2.8) called with this input. If the input starts with "alias/", this an AWS KMS alias and not a multi-Region key id and MUST return false. If the input starts with "mrk-", this is a multi-Region key id and MUST return true. If the input does not start with any of the above, this is not a multi- Region key id and MUST return false. 3. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . Acknowledgments Author's Address Amazon AWS Amazon AWS Email: cryptools+rfc@amazon.com