edit-icon download-icon

Alias Instructions

Last Updated: Mar 30, 2018

An alias is an optional identifier for a Customer Master Key (CMK).

An alias must be unique to an Alibaba Cloud account and region. You can use the same alias for the same account in different regions. Each alias can point to only one CMK in the same region, but each CMK can have multiple aliases.

Though it must point to a CMK, an alias is a resource that exists independently of the CMK. As such, an alias has the following features:

  • You can change the alias associated with a CMK using UpdateAlias without affecting the CMK.
  • If you delete an alias, the associated CMK is not deleted.
  • To use a sub-account for alias operations, you must have the relevant authorization for alias resources. For further details, see Use RAM for KMS resource authorization.
  • Aliases cannot be changed. If you want to change an alias, create a new one for a CMK and delete the old one.

If an alias is associated with a CMK, in the following operation, you can replace the key ID in the access parameter with an alias:

  • DescribeKey
  • Encrypt
  • GenerateDataKey

If the sub-account uses the alias instead of the key ID for the operation, the sub-account needs the permission of the corresponding key. It does not need the corresponding alias permission.

The following operations can be performed on aliases:

  • Create an alias
  • Update an alias
  • Delete an alias
  • List aliases
  • List aliases associated with a specific key

You always need to use the full alias, containing the prefix “alias/“ followed by the alias name itself.

  1. //a complete alias containing the prefix "alias/"
  2. alias/example

Create an alias

  • An alias must have the prefix “alias/“. In addition to the prefix, the alias can contain letters, numbers, and characters such as underscores (_), hyphens (-), and slashes (/). Not including the prefix, the minimum length of an alias is 1 and the maximum length is 255.
  • For a sub-account to create an alias, permissions are required for both the alias and its associated key.
  • Creating new aliases for the same CMK does not affect existing aliases.
  • The API for creating an alias is CreateAlias
  1. //RAM Policy example for creating an alias: user 123456 can create the alias "alias/example" for the key "08ec3bb9-034f-485b-b1cd-3459baa889c7".
  2. {
  3. "Version": "1",
  4. "Statement": [
  5. {
  6. "Effect": "Allow",
  7. "Action": [
  8. "kms:CreateAlias"
  9. ],
  10. "Resource": [
  11. "acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa889c7",
  12. "acs:kms:cn-hangzhou:123456:alias/example"
  13. ]
  14. }
  15. ]
  16. }
  17. //Create an alias
  18. aliyuncli kms CreateAlias --KeyId 08ec3bb9-034f-485b-b1cd-3459baa889c7 --AliasName alias/example

Update an alias

  • Updating aliases involves associating them with other CMKs. The API is UpdateAlias
  • For a sub-account to update an alias, access is required to the raw key, target key, and the alias, and permissions are required for all three.
  1. //RAM Policy example for updating an alias: user 123456 can manage the alias "alias/example", associating the key "08ec3bb9-034f-485b-b1cd-3459baa889c7" with the new key "127d2f84-ee5f-4f4d-9d41-dbc1aca28788".
  2. {
  3. "Version": "1",
  4. "Statement": [
  5. {
  6. "Effect": "Allow",
  7. "Action": [
  8. "kms:UpdateAlias"
  9. ],
  10. "Resource": [
  11. "acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa889c7",
  12. "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788",
  13. "acs:kms:cn-hangzhou:123456:alias/example"
  14. ]
  15. }
  16. ]
  17. }
  18. //Update an alias
  19. aliyuncli kms UpdateAlias --AliasName alias/example --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca28788

Delete an alias

  • Deleting aliases does not affect the keys with which they are associated. The API is DeleteAlias
  • For a sub-account to delete an alias, access is required to both the alias and its associated keys and permissions are required for both.
  1. //RAM Policy example for deleting an alias: user 123456 can delete the alias "alias/example". Its associated key is 127d2f84-ee5f-4f4d-9d41-dbc1aca28788.
  2. {
  3. "Version": "1",
  4. "Statement": [
  5. {
  6. "Effect": "Allow",
  7. "Action": [
  8. "kms:DeleteAlias"
  9. ],
  10. "Resource": [
  11. "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788",
  12. "acs:kms:cn-hangzhou:123456:alias/example"
  13. ]
  14. }
  15. ]
  16. }
  17. //Delete keys
  18. aliyuncli kms DeleteAlias --AliasName alias/example

List aliases

  • Listing aliases provides you with information about them. The API is ListAliases
  • For a sub-account to list aliases, access and permissions are required for the alias resource types.
  1. //RAM Policy examples for listing aliases
  2. {
  3. "Version": "1",
  4. "Statement": [
  5. {
  6. "Effect": "Allow",
  7. "Action": [
  8. "kms:ListeAliases"
  9. ],
  10. "Resource": [
  11. "acs:kms:cn-hangzhou:123456:alias"
  12. ]
  13. }
  14. ]
  15. }
  16. //List aliases
  17. aliyuncli kms ListAliases

List aliases associated with a specific key

  • Unlike with ListAliases, this operation displays only information about the aliases associated with a specified key. The API is ListAliasesByKeyId
  • For a sub-account to list aliases associated with a specific key, only access and permission for the specified key is required.
  1. //RAM Policy example for listing aliases associated with a specific key: list all the associated aliases of the key "127d2f84-ee5f-4f4d-9d41-dbc1aca28788".
  2. {
  3. "Version": "1",
  4. "Statement": [
  5. {
  6. "Effect": "Allow",
  7. "Action": [
  8. "kms:DeleteAlias"
  9. ],
  10. "Resource": [
  11. "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788"
  12. ]
  13. }
  14. ]
  15. }
  16. //List aliases associated with a specific key
  17. aliyuncli kms ListAliasesByKeyId --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca28788
Thank you! We've received your feedback.