All Products
Search

This Product

    Key Management Service:Manage external keys

    Document Center

    Key Management Service:Manage external keys

    Last Updated:Apr 30, 2024

    External key management instances of Key Management Service (KMS external key instances) allow you to associate KMS keys with keys that are stored in external key management infrastructures (KMIs). Alibaba Cloud services or applications reference key IDs on KMS external key instances to encrypt or decrypt data. During the encryption and decryption operations, keys in external KMIs do not cross the boundaries of KMIs. This feature is called Hold Your Own Key (HYOK). This topic describes how to create an external key in an KMS external key instance.

    Note

    You must maintain external KMIs and assume the maintenance cost to ensure the security, availability, and stability of external KMIs. If software key management instances and hardware key management instances of KMS can meet your security and management requirements, we recommend that you use software key management instances or hardware key management instances.

    How KMS external key instances communicate with external KMIs

    KMS external key instances are connected to external KMIs by using External Key Instance Proxy Servers (XKI Proxy servers). XKI Proxy servers transfer requests from KMS external key instances to external KMIs and return responses from external KMIs to KMS external key instances. For more information, see XKI Proxy servers.

    KMS external key instances can be connected to XKI Proxy servers by using the Internet or Virtual Private Cloud (VPC) endpoint services.

    • Use the Internet: KMS external key instances are connected to XKI Proxy servers over the Internet. The Internet access feature must be enabled for the XKI Proxy servers.

    • Use VPC endpoint services: KMS external key instances use VPC endpoint services provided by PrivateLink to connect to XKI Proxy servers.

    Precautions

    • KMS external keys must be symmetric keys.

    • If you forget or delete the KMS external keys that are stored in KMIs, the ciphertexts encrypted by the external keys cannot be decrypted.

    • KMS external key instances do not support key material import, key rotation, backup management, or cross-region key synchronization.

    • The keys on KMS external key instances are stored in external KMIs, and only the metadata of the keys is stored on KMS external key instances. The versions of the keys are also managed by external KMIs. Therefore, you cannot call KMS API operations that are related to key versions. The KMS API operations include:

    • If you want to perform cryptographic operations on KMS external key instances, the following requirements must be met:

      • The keys on the KMS external key instances must be in the Enabled state.

      • The XKI Proxy servers must run as expected, and are correctly configured and in the Connected state.

      • The keys in the XKI Proxy servers must be in the ENABLED state.

    Prerequisites

    • Make sure that you have purchased and enabled an external KMS instance. For more information, see Purchase and enable a KMS instance.

    • Create a key in the key management facility and record the key ID in advance through the XKI Proxy proxy service. For more information, see KMS documentation.

    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 Resource > Keys.

    2. On the Keys page, click the Keys tab, select an external key management instance for Instance ID, and then click Create Key.

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

      Parameter

      Description

      External Key ID

      The key ID of the key 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. For more information about key specifications and key algorithms, see Key management types and key specifications.

      Aliyun_AES_256

      Key Usage

      The usage of the key.

      ENCRYPT/DECRYPT: encrypts or decrypts data.

      Key Alias

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

      Label

      The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair.

      Note

      • The format of the tag key and 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 (:), and at signs (@).

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

      • You can configure up to 20 key-value pairs for each key.

      Description

      The description of the key.

      Advanced Settings

      • Default Policy: If the key is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy.

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

        • If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1.

          • Keys created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the keys.

          • Keys created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the keys.

      • Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the key, select Custom Policy.

        Important

        Administrators and users do not consume Access Management Quota. If you select another account, the quota of Access Management of the KMS instance is consumed. The quota is calculated based on the number of primary accounts. If you cancel the authorization, wait about 5 minutes and then check the quota. The quota is refunded.

        • An administrator can manage the key. Cryptographic operations are not supported. You can select RAM users and RAM roles within the current Alibaba Cloud account.

          Permissions supported by 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"
			]
		}
	]
}

        • A user can use the key to perform cryptographic operations. You can select RAM users and RAM roles within the current Alibaba Cloud account.

          Permissions supported by 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"
            ]
        }
    ]
}

        • A cross-account user can use the key for encryption and decryption. You can select RAM users and RAM roles within other Alibaba Cloud accounts.

          • RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: acs:ram::119285303511****:user/testpolicyuser.

          • RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole.

            Note

            After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the key in RAM. Then, the RAM user or RAM role can use the key.

            For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role.

          Permissions supported by 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"
            ]
        }
    ]
}

    Related operations

    For information about how to disable a key, enable key deletion protection, schedule the deletion of a key, check key association, configure an alias for an external key, and bind a tag to an external key, see Manage a key.