Use USE_WRAPPED_KEYSET to convert a wrapped keyset for encryption and decryption - MaxCompute

USE_WRAPPED_KEYSET converts a wrapped keyset generated by NEW_WRAPPED_KEYSET into a basic keyset. Pass the result directly to an encryption or decryption function as the keyset parameter, or use get_json_object to inspect keyset metadata for maintenance purposes.

Prerequisites

Before you begin, ensure that you have:

A wrapped keyset generated by NEW_WRAPPED_KEYSET
A KMS key created in Key Management Service (KMS) and its Alibaba Cloud Resource Name (ARN) available
A RAM role with permissions to use the KMS key, assumed by MaxCompute

Syntax

binary USE_WRAPPED_KEYSET(string <kms_cmk_arn>, string <role_arn>, string <wrapped_keyset> [, string <role_chain>])

Parameters

Parameter	Required	Description
`kms_cmk_arn`	Yes	ARN of the KMS customer master key (CMK) used to encrypt the keyset. 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`	Yes	ARN of the RAM role with KMS permissions, assumed by MaxCompute. Format: `'acs:ram:${<userAID>}:role/${<roleName>}'`For more information about how to obtain the ARN of a RAM role, see the "Activate KMS and grant permissions on KMS" section in Use keysets..
`wrapped_keyset`	Yes	An existing wrapped keyset.
`role_chain`	No	Role chain for cross-account authorization. Format: `'acs:ram:<userAID>:role/<roleName2>,acs:ram:<userBID>:role/<roleName3>,...'`. Use this when the wrapped keyset belongs to a different Alibaba Cloud account.

Return value

Returns a desensitized keyset of the STRUCT type. Use get_json_object to obtain keyset-related fields based on your business requirements.

Usage notes

Run the example code in script mode, or replace all variables with actual values before running in standard SQL mode.
The wrapped keyset passed to this function must have been generated by NEW_WRAPPED_KEYSET.
Use role_chain only for cross-account scenarios where the KMS key and the MaxCompute project belong to different Alibaba Cloud accounts.

Examples

The following examples use variables and must run in script mode, or you must replace each variable with an actual value.

Inspect the key algorithm of a wrapped keyset

Use get_json_object to extract the key algorithm from a 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>}';
@use_keyset_new := USE_WRAPPED_KEYSET(@kms_resource_keyId, @role_arn, @origin_key, @role_chain);

SELECT get_json_object(get_json_object(use_keyset_new.wrapped_keyset_info, '$.masked_keyset'), '$.key[0].key_meta_data.type');

Expected output:

+-------------+
| _c0         |
+-------------+
| AES-GCM-256 |
+-------------+

相关文档

文档	说明
密钥集（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）。
ROTATE_WRAPPED_KEYSET	解密已有的加密密钥集（KEYSET），并进行密钥轮转，然后通过新密钥加密。
ENHANCED_SYM_ENCRYPT	指定密钥集进行数据加密。
ENHANCED_SYM_DECRYPT	指定密钥集进行数据解密。

What's next

NEW_WRAPPED_KEYSET — generate a wrapped keyset from an existing keyset using a KMS key