All Products
Search

This Product

    MaxCompute:USE_WRAPPED_KEYSET

    Document Center

    MaxCompute:USE_WRAPPED_KEYSET

    Last Updated:Jun 26, 2026

    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 console.

    role_arn

    Yes

    ARN of the RAM role with KMS permissions, assumed by MaxCompute. Format: 'acs:ram:${<userAID>}:role/${<roleName>}'.

    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 |
+-------------+

    What's next