Create and use an external key - Key Management Service - Alibaba Cloud Documentation Center

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.

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 it works

KMS external key instances communicate with your 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. See XKI Proxy servers.

Two connectivity options are available:

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.

Limitations

Before creating an external key, note the following constraints:

External keys must be symmetric keys.
Key versions are managed entirely by your KMI. The following KMS API operations are not supported:
- UpdateRotationPolicy
- CreateKeyVersion
Key material import, key rotation, backup management, and cross-region key synchronization are not supported.
If you lose or delete the key in your KMI, any ciphertext encrypted by that key cannot be decrypted.

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.

Create an external key

Prerequisites

Before you begin, make sure that you have:

A KMS instance of the external key management type. See Purchase and enable a KMS instance.
A key created in your KMI through the XKI Proxy, with the key ID recorded.

Steps

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.KMS console
On the Keys page, click the Customer Master Keys tab. Select your external key management instance from the Instance ID drop-down list, then click Create Key.
In the Create Key panel, configure the parameters described below, then click OK.

Key parameters:

Parameter	Description
External Key ID	The key ID generated by your XKI Proxy. You can use the same external key ID to create one or more KMS keys.
Key Specifications	The specification of the key. For more information about the standards that key specifications follow and key algorithms, see Key management types and key specifications. `Aliyun_AES_256`
Key Usage	Encrypt/Decrypt: data encryption and decryption.
Key Alias	An alias for the key. Accepts letters, digits, underscores (`_`), hyphens (`-`), and forward slashes (`/`).
Tag	Key-value pairs for classifying and managing keys. See tag constraints below.
Description	A description of the key.
Advanced Settings	Access policy configuration. See Access policy options below.

Tag constraints:

Each tag key or value can be up to 128 characters.
Accepted characters: letters, digits, /, \, _, -, ., +, =, :, @, spaces.
Tag keys cannot start with aliyun or acs:.
Up to 20 tags per key.

Access policy options

Default policy

Select Default Policy when the key is used by the current Alibaba Cloud account or an account in a resource share.

Scenario	Access
KMS instance not shared	Only the current Alibaba Cloud account can manage and use the key.
KMS instance shared (Account 1 shares with Account 2)	Keys created by Account 1: only Account 1 can manage and use them. Keys created by Account 2: both Account 1 and Account 2 can manage and use them.

Custom policy

Select Custom Policy to grant access to RAM users, RAM roles, or other Alibaba Cloud accounts.

Important

Selecting administrators or users does not consume the Access Management Quantity quota. Granting access to cross-account users consumes the quota, counted by the number of Alibaba Cloud accounts. After revoking cross-account access, wait approximately 5 minutes for the quota to be returned.

Three principal types are available:

Administrator — can manage the key but cannot perform cryptographic operations. Select RAM users or RAM roles within the current account.

Permissions granted to 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 perform cryptographic operations. Select RAM users or RAM roles within the current account.

Permissions granted to 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"
            ]
        }
    ]
}

Cross-account user — can use the key for encryption and decryption. Select RAM users or RAM roles from other Alibaba Cloud accounts.

Specify principals in the following formats:

RAM user: acs:ram::<userId>:user/<ramuser> — for example, acs:ram::119285303511****:user/testpolicyuser
RAM role: acs:ram::<userId>:role/<ramrole> — for example, acs:ram::119285303511****:role/testpolicyrole

After granting permissions here, the Alibaba Cloud account that owns the RAM user or RAM role must also grant that principal the necessary KMS permissions through RAM. For details, see Custom policy references for Key Management Service. For instructions on granting RAM permissions, see Grant permissions to a RAM user or Grant permissions to a RAM role.

Permissions granted to cross-account 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"
            ]
        }
    ]
}

What's next

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.