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_KEYSETA KMS key created, with its ARN available for the
kms_cmk_arnparameterA 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_arn: 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 console.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>}'.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 |
| Region ID |
|
| Alibaba Cloud account ID |
|
| CMK ID |
|
| RAM role name |
|
| Hex-encoded wrapped keyset from | — |
| Account IDs for cross-account roles | — |
| Role names for cross-account access | — |
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