You can use MaxCompute with Key Management Service (KMS) to manage keys. This topic describes the USE_WRAPPED_KEYSET function. The function allows you to convert a wrapped keyset into a basic keyset that is used as a parameter in the encryption or decryption function to encrypt or decrypt data.
Background information and prerequisites
You can use MaxCompute with KMS to manage keys. You can generate a wrapped keyset by encrypting an existing keyset based on a KMS key. The USE_WRAPPED_KEYSET function converts a wrapped keyset generated by using the NEW_WRAPPED_KEYSET function into a basic keyset. The basic keyset is used as a parameter in the encryption or decryption function to encrypt or decrypt data. You can also use the USE_WRAPPED_KEYSET function to obtain the information about a wrapped keyset and save the information for subsequent maintenance.
Before you use the USE_WRAPPED_KEYSET function, make sure that the following prerequisites are met:
A wrapped keyset is generated by using the
NEW_WRAPPED_KEYSETfunction. For more information, see NEW_WRAPPED_KEYSET.A KMS key is created and the Alibaba Cloud Resource Name (ARN) of the key is obtained. The key ARN is specified by kms_cmk_arn. A RAM role is granted permissions to use the new key.
Syntax
binary USE_WRAPPED_KEYSET(string <kms_cmk_arn> , string <role-arn>, string <wrapped_keyset> [,string <role_chain>])Parameters
kms_cmk_arn: required. This parameter specifies the KMS customer master key (CMK) ARN of the keyset that you want to encrypt. 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 KMS. The role needs to be assumed by MaxCompute. 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 an existing wrapped keyset.
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 desensitized keyset of the STRUCT type is returned. You can use the get_json_object function to obtain keyset-related fields based on your business requirements.
Examples
The following sample code contains variables. You must run the code in script mode or replace variables with actual values in SQL statements.
Obtain the key algorithm information of 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');The following result is returned:
+-----+
| _c0 |
+-----+
| AES-GCM-256 |
+-----+