Use ROTATE_WRAPPED_KEYSET to re-encrypt a wrapped keyset with a new key algorithm - MaxCompute

Re-encrypts a wrapped keyset using a new KMS key and a new key algorithm, enabling key rotation for data encrypted with MaxCompute's envelope encryption model. Unlike REWRAP_KEYSET, this function lets you change the key algorithm during re-encryption.

Prerequisites

Before you begin, ensure that you have:

A wrapped keyset generated by NEW_WRAPPED_KEYSET. See NEW_WRAPPED_KEYSET
A KMS key created, with its ARN available for the kms_cmk_arn parameter
A RAM role granted permissions to use the new KMS 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

Required:

kms_cmk_arnFor more information, see the "Activate KMS and grant permissions on KMS" section in Use keysets. : The ARN of the KMS customer master key (CMK) to use for re-encryption. Format: 'acs:kms:<RegionId>:<UserId>:key/<CmkId>'. Get the ARN from the Key Details page in the KMS consoleFor more information about how to obtain the KMS CMK ARN, see the "Activate KMS and grant permissions on KMS" section in Use keysets..
role_arn: The ARN of the RAM role that has permissions on both the old and new KMS keys. Format: 'acs:ram:${<userAID>}:role/${<roleName>}'For more information about how to obtain the ARN, see the "Activate KMS and grant permissions on KMS" section in Use keysets. .
wrapped_keyset: The wrapped keyset to re-encrypt.
key_type: The algorithm for the key in the newly generated keyset. Valid values: AES-GCM-256, AES-SIV-CMAC-128, AES-SIV-CMAC-256.

Optional:

description: A description of the key.
role_chain: A role chain for cross-account authorization. Format: 'acs:ram:<userAID>:role/<roleName2>,acs:ram:<userBID>:role/<roleName3>,...'. Use this parameter to call wrapped keysets across Alibaba Cloud accounts.

Return value

Returns a wrapped keyset of the BINARY type. To store or pass the result as a string, convert it with the HEX function.

Usage notes

Run the examples below in script mode, or replace the variables with actual values in your SQL statements.

Examples

Basic re-encryption

Re-encrypt a wrapped keyset with a new KMS key and the AES-GCM-256 algorithm:

@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'));

Cross-account re-encryption with a role chain

Re-encrypt a wrapped keyset and grant additional roles access to the result:

@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));

Replace the placeholders with actual values:

Placeholder	Description	Example
`<RegionId>`	Region ID	`cn-hangzhou`
`<UserId>`	Alibaba Cloud account ID	`123456789`
`<CmkId>`	CMK ID	`key-xxxxxxx`
`<roleName>`	RAM role name	`MyEncryptionRole`
`<wrapped_keyset>`	Hex-encoded wrapped keyset from `NEW_WRAPPED_KEYSET`	—
`<UserAId>`, `<UserBId>`	Account IDs for cross-account roles	—
`<roleName2>`, `<roleName3>`	Role names for cross-account access	—

相关文档

文档	说明
密钥集（KEYSET）使用说明	Keyset加密函数的使用说明。
NEW_KEYSET	根据指定的算法类型，创建对应的密钥Keyset。
Syntax	在Keyset中新增密钥，并将新增的密钥设置为主密钥。
KEYSET_TO_JSON	将BINARY类型的密钥Keyset转化为可读的JSON格式，以便查看密钥Keyset详情。
KEYSET_FROM_JSON	将JSON类型的keyset转化为BINARY类型。
ROTATE_KEYSET	系统自动生产一个新密钥并将新密钥设置为主密钥。
NEW_WRAPPED_KEYSET	将有权使用KMS用户主密钥资源名称（kms_cmk_arn）角色的`role_arn`授权给MaxCompute，用来新建一个封装密钥集（KEYSET），也可通过角色链（`role_chain`）方式授权给其他阿里云账号解密KEYSET的权限。
REWRAP_KEYSET	通过指定的KMS密钥重新加密封装密钥集（KEYSET）。
USE_WRAPPED_KEYSET	将封装密钥集转换为基础密钥集，作为加解密函数的参数使用，您也可通过此函数，获得封装密钥集相关的信息，并保存起来，便于维护。
ENHANCED_SYM_ENCRYPT	指定密钥集进行数据加密。
ENHANCED_SYM_DECRYPT	指定密钥集进行数据解密。

What's next

NEW_WRAPPED_KEYSET: Generate a wrapped keyset to use as input for this function
HEX: Convert the BINARY return value to a STRING for storage or transmission