All Products
Search

This Product

    Key Management Service:Manage external keys

    Document Center

    Key Management Service:Manage external keys

    Last Updated:Sep 18, 2026

    Hold Your Own Key (HYOK) lets you associate KMS keys with keys stored in your own external key management infrastructure (KMI). When Alibaba Cloud services encrypt or decrypt data using a KMS external key instance, the actual key material never leaves your KMI. KMS only stores key metadata on its side. This topic describes how to create an external key in a KMS external key instance.

    Note

    Maintaining an external KMI adds substantial operational cost, including security, availability, and stability responsibilities. If a software or hardware key management instance meets your compliance requirements, use those instead.

    How KMS instances communicate with external key management facilities

    KMS external key instances communicate with your key management infrastructure (KMI) through an External Key Instance Proxy Server (XKI Proxy server). The XKI Proxy server relays cryptographic requests from KMS to your KMI and returns the responses.

    KMS supports two connectivity options between the external key instance and the XKI Proxy server:

    • Internet: KMS connects to your XKI Proxy server over the internet. Enable internet access on the XKI Proxy server.

    • VPC endpoint service: KMS connects through a Virtual Private Cloud (VPC) endpoint service provided by PrivateLink, without traversing the public internet.

    Limits

    • External keys must be symmetric keys.

    • If you lose or delete the key in your KMI, any ciphertext encrypted by that key cannot be decrypted.

    • Key material import, key rotation, backup management, and cross-region key synchronization are not supported.

    • Key versions are managed entirely by your KMI. The following KMS API operations are not supported:

    • For cryptographic operations to succeed, all three conditions must be met simultaneously:

      • The KMS key is in the Enabled state.

      • The XKI Proxy server is correctly configured and in the Connected state.

      • The key in the XKI Proxy server is in the ENABLED state.

    Prerequisites

    • Ensure you have purchased and enabled an external key management instance. Purchase and enable a KMS instance.

    • Use the XKI proxy service in your key management infrastructure (KMI) to create a key and record its ID.

    Create an external key

    1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resources > Keys.

    2. On the Keys page, click the Customer Master Keys tab. From the Instance ID drop-down list, select an external key management instance. Then, click Create Key.

    3. In the Create Key panel, configure the parameters and click OK.

      Parameter

      Description

      External Key ID

      The key ID generated by the XKI management service.

      Note

      You can use the same external key ID to create one or more KMS keys.

      Key Specifications

      The specification of the key. Only Aliyun_AES_256 are supported.

      Note

      For supported specifications and algorithms, see Key types and specifications.

      Key Usage

      The purpose of the key.

      ENCRYPT/DECRYPT: Encrypts and decrypts data.

      Key Alias

      An alias to identify the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).

      Tags

      Tags to help you categorize and manage keys. Each tag is a key-value pair.

      Note

      • Format of a tag key and a tag value: A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), at signs (@), and spaces.

      • A tag key cannot start with aliyun or acs:.

      • Each key supports up to 20 tag key-value pairs.

      Description

      A description of the key.

      Advanced Settings

      • Default Policy: Select this policy if the key is used by the current Alibaba Cloud account or an Alibaba Cloud account in a resource share.

        • If the instance is not shared with other accounts: Only the current Alibaba Cloud account can manage and use the key.

        • If the instance is shared with other accounts: For example, Alibaba Cloud account 1 shares KMS instance A with Alibaba Cloud account 2.

          • For a key created by Alibaba Cloud account 1: Only Alibaba Cloud account 1 can manage and use the key.

          • For a key created by Alibaba Cloud account 2: Both Alibaba Cloud account 1 and Alibaba Cloud account 2 can manage and use the key.

      • Custom Policy: Select this policy if you need to authorize RAM users, RAM roles, or other Alibaba Cloud accounts to use the key.

        Important

        • Selecting an administrator or user does not consume Access Management Quantity quota. Selecting users from other accounts consumes the Access Management Quantity quota of the KMS instance, calculated by the number of specified Alibaba Cloud accounts.

        • After you revoke the authorization, the quota is released in about 5 minutes.

        • Administrator: Manages the key but cannot perform cryptographic operations. Select RAM users and RAM roles from your Alibaba Cloud account.

          List of permissions for administrators

          {
	"Statement": [
		{
			"Action": [
				"kms:List*",
				"kms:Describe*",
				"kms:Create*",
				"kms:Enable*",
				"kms:Disable*",
				"kms:Get*",
				"kms:Set*",
				"kms:Update*",
				"kms:Delete*",
				"kms:Cancel*",
				"kms:TagResource",   
				"kms:UntagResource", 
				"kms:ImportKeyMaterial",
				"kms:ScheduleKeyDeletion"
			]
		}
	]
}

        • User: Can only perform cryptographic operations. Select Resource Access Management (RAM) users and RAM roles from your Alibaba Cloud account. Multiple consumers within the same cloud service instance (for example, AI Gateway) under the same Alibaba Cloud account can all reference the same KMS key. This approach is commonly used for centralized credential management or to simplify key rotation workflows.

          List of permissions for users

           {
    "Statement": [
        {
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
		"kms:GenerateDataKey",
		"kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
		"kms:TagResource"
            ]
        }
    ]
}

        • Users from other accounts: Can encrypt and decrypt with the key. Specify RAM users or RAM roles from other Alibaba Cloud accounts.

          List of permissions for users from other accounts

           {
    "Statement": [
        {
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
		"kms:GenerateDataKey",
		"kms:GenerateAndExportDataKey",
                "kms:AsymmetricEncrypt",
                "kms:AsymmetricDecrypt",
                "kms:DescribeKey",
                "kms:DescribeKeyVersion",
                "kms:ListKeyVersions",
                "kms:ListAliasesByKeyId",
	        "kms:TagResource"
            ]
        }
    ]
}

    Related operations

    To disable a key, enable key deletion protection, schedule key deletion, check key associations, configure a key alias, or add tags to an external key, see Manage a key.