Aliases are an optional parameter used to identify Customer Master Keys (CMKs).

Aliases must be unique within a region for each Alibaba Cloud account. Different regions can contain identical aliases. An alias can be bound to a single CMK within a region, but a CMK can have multiple bound aliases.

Although aliases are bound to CMKs, aliases are resources independent from the CMKs to which they are bound. Aliases have the following characteristics:

  • You can call the UpdateAlias API operation to bind an alias to a different CMK. This operation will not affect the CMK.
  • Deleting an alias will not delete the CMK that it is bound to.
  • A RAM user must be authorized before it can perform operations on an alias. For more information, see Use RAM to authorize KMS resources.
  • Aliases cannot be modified. To change the alias of a CMK, you must delete the old alias and create a new one for the CMK.

You can replace the CMK ID with a bound alias in the following API operations:

  • DescribeKey
  • Encrypt
  • GenerateDataKey
  • GenerateDataKeyWithoutPlaintext

To call the preceding API operations, the RAM user must have the relevant permissions on the CMK. The RAM user does not need to have permission on the aliases.

You can perform the following alias-related operations:

For all of the preceding operations, you must specify a complete alias with the alias/ prefix.

//The example alias with the alias/ prefix
alias/example

Create an alias

  • Aliases must contain the alias/ prefix. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/). Excluding the prefix, the alias must be 1 to 255 characters in length.
  • To create an alias, a RAM user must have permissions on both the alias and the CMK that the alias is bound to.
  • Creating a new alias for a CMK will not affect the existing aliases of the CMK.
  • You can call the CreateAlias API operation to create an alias.
//A sample RAM policy used to create an alias: The 123456 RAM user can create the alias/example alias for the 08ec3bb9-034f-485b-b1cd-3459baa889c7 CMK
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateAlias"
      ],
      "Resource": [
        "acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa889c7",
        "acs:kms:cn-hangzhou:123456:alias/example"
      ]
    }
  ]
}
//Create an alias
aliyuncli kms CreateAlias --KeyId 08ec3bb9-034f-485b-b1cd-3459baa889c7 --AliasName alias/example

Update an alias

  • This operation changes the bound CMK of an alias to a different CMK. You can call the UpdateAliasAPI operation to create an alias.
  • To update an alias, a RAM user must have permissions on the source and destination CMKs as well as the alias.
//A sample RAM policy used to update an alias: The 123456 RAM user can bind the alias/example alias that has been bound to the 08ec3bb9-034f-485b-b1cd-3459baa889c7 CMK to the 127d2f84-ee5f-4f4d-9d41-dbc1aca28788 CMK
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:UpdateAlias"
      ],
      "Resource": [
        "acs:kms:cn-hangzhou:123456:key/08ec3bb9-034f-485b-b1cd-3459baa889c7",
        "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788",
        "acs:kms:cn-hangzhou:123456:alias/example"
      ]
    }
  ]
}
//Update an alias
aliyuncli kms UpdateAlias --AliasName alias/example --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca28788

Delete an alias

  • Deleting an alias will not affect the CMK that alias is bound to. You can call the DeleteAlias API operation to delete an alias.
  • To delete an alias, a RAM user must have permissions on both the alias and the CMK that the alias is bound to.
//A sample RAM policy used to delete an alias: The 123456 RAM user can delete the alias/example alias of the 127d2f84-ee5f-4f4d-9d41-dbc1aca28788 CMK
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:DeleteAlias"
      ],
      "Resource": [
        "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788",
        "acs:kms:cn-hangzhou:123456:alias/example"
      ]
    }
  ]
}
//Delete an alias
aliyuncli kms DeleteAlias --AliasName alias/example

List aliases

  • This operation lists information of all aliases. You can call the ListAliases API operation to list aliases.
  • To list all aliases, a RAM user must have the permissions on alias resources.
//A sample RAM policy used to list aliases
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:ListeAliases"
      ],
      "Resource": [
        "acs:kms:cn-hangzhou:123456:alias"
      ]
    }
  ]
}
//List aliases
aliyuncli kms ListAliases

List aliases bound to a specified CMK

  • This operation lists information of the aliases bound to a specified CMK. You can call the ListAliasesByKeyId API operation to list the aliases bound to a specified CMK.
  • To list the aliases bound to a specified CMK, a RAM user must have the permissions on the specified CMK.
//A sample RAM policy used to list the aliases bound to a specified CMK: List all aliases bound to the 127d2f84-ee5f-4f4d-9d41-dbc1aca28788 CMK
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:DeleteAlias"
      ],
      "Resource": [
        "acs:kms:cn-hangzhou:123456:key/127d2f84-ee5f-4f4d-9d41-dbc1aca28788"
      ]
    }
  ]
}
//List aliases bound to a specified CMK
aliyuncli kms ListAliasesByKeyId --KeyId 127d2f84-ee5f-4f4d-9d41-dbc1aca28788