ROTATE_WRAPPED_KEYSET - MaxCompute - Alibaba Cloud Documentation Center

You can use MaxCompute with Key Management Service (KMS) to manage keys. This topic describes how to use the ROTATE_WRAPPED_KEYSET function to decrypt a wrapped keyset, implement key rotation, and use a new key to encrypt data.

Background information and prerequisites

You can use MaxCompute with KMS to manage keys. You can generate a wrapped keyset by encrypting a keyset based on a KMS key. The ROTATE_WRAPPED_KEYSET function uses a new KMS key and a new key algorithm to re-encrypt a wrapped keyset that is generated by using the NEW_WRAPPED_KEYSET function. Compared with the REWRAP_KEYSET function, the ROTATE_WRAPPED_KEYSET function can use a new key algorithm for re-encryption.

Before you use the ROTATE_WRAPPED_KEYSET function, make sure that the following prerequisites are met:

A wrapped keyset is generated by using the NEW_WRAPPED_KEYSET function. For more information, see NEW_WRAPPED_KEYSET.
A KMS key is created and the key ARN specified by kms_cmk_arn is obtained. A RAM role is granted permissions to use the new key.

Syntax

binary ROTATE_WRAPPED_KEYSET(string <kms_cmk_arn> , string <role-arn>, string <wrapped_keyset>,string <key_type> [,string description,[string <role_chain>]])

Parameters

kms_cmk_arn: required. This parameter specifies the ARN of the KMS customer master key (CMK) that you want to use to re-encrypt a wrapped keyset. The parameter value is in the format of 'acs:kms:<RegionId>:<UserId>:key/<CmkId>'. RegionId specifies the region ID, UserId specifies the user ID, and CmkId specifies the CMK ID. You can obtain the ARN from the Key Details page in the KMS console.
role_arn: required. This parameter specifies the ARN of the RAM role that has permissions on both the old and new KMS keys. The parameter value is in the format of 'acs:ram:${<userAID>}:role/${<roleName>}'. userAID specifies the user ID, and roleName specifies the role name.
wrapped_keyset: required. This parameter specifies the wrapped keyset that you want to re-encrypt.
key_type: required. This parameter specifies the algorithm type of the key in the newly generated keyset. Valid values: AES-GCM-256, AES-SIV-CMAC-128, and AES-SIV-CMAC-256.
description: optional. This parameter provides a description of the key.
role_chain: optional. This parameter specifies the role chain for user authorization. The parameter value is in the format of 'acs:ram:<userAID>:role/<roleName2>,acs:ram:<userBID>:role/<roleName3>},...'. You can use role chains to call wrapped keysets across Alibaba Cloud accounts.

Return value

A wrapped keyset of the BINARY type is returned. You can use the HEX function to convert the wrapped keyset of the BINARY type into a keyset of the STRING type based on your business requirements. For more information about the HEX function, see HEX.

Examples

Note

The following sample code contains variables. You must run the code in script mode or replace variables with actual values in SQL statements.

Re-encrypt a wrapped keyset.

@kms_resource_keyId := 'acs:kms:${<RegionId>}:${<UserId>}:key/${<CmkId>}';
@role_arn := 'acs:ram:${<UserId>}:role/${<roleName>}';
@origin_key := unhex('<wrapped_keyset>');
select hex(ROTATE_WRAPPED_KEYSET(@kms_resource_keyId, @role_arn, @origin_key, 'AES-GCM-256', 'hello world'));

Re-encrypt a wrapped keyset, and allow other roles to call the wrapped keyset.

@kms_resource_keyId := 'acs:kms:${<RegionId>}:${<UserId>}:key/${<CmkId>}';
@role_arn := 'acs:ram:${<UserId>}:role/${<roleName>}';
@origin_key := unhex('<wrapped_keyset>');
@role_chain := 'acs:ram:${<UserAId>}:role/${<roleName2>},acs:ram:${<UserBId>}:role/${<roleName3>}';
select hex(ROTATE_WRAPPED_KEYSET(@kms_resource_keyId, @role_arn, @origin_key, 'AES-GCM-256', 'hello world', @role_chain));