MaxCompute:NEW_WRAPPED_KEYSET - MaxCompute

NEW_WRAPPED_KEYSET creates a wrapped keyset by encrypting a keyset with a Key Management Service (KMS) customer master key (CMK). Use wrapped keysets when you need KMS-managed key protection for column-level encryption and decryption in MaxCompute.

Prerequisites

Before you begin, ensure that you have:

An active KMS instance with a KMS key created. Get the key ARN (Alibaba Cloud Resource Name) 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..
A RAM role that grants MaxCompute access to KMS. Get the RAM role ARN after creating the role and completing the authorization.

Syntax

binary NEW_WRAPPED_KEYSET(string <kms_cmk_arn>, string <role_arn>, string <key_type>
[, string <description>, [string <role_chain>]])

Parameters

Parameter	Required	Description
`kms_cmk_arn`	Yes	ARN of the KMS CMK used to encrypt the keyset. Format: `'acs:kms:<RegionId>:<UserId>:key/<CmkId>'`
`role_arn`	Yes	ARN of the RAM role that MaxCompute assumes to access KMS. 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.
`key_type`	Yes	Encryption algorithm for the key in the new keyset. Valid values: `AES-GCM-256`, `AES-SIV-CMAC-128`, `AES-SIV-CMAC-256`
`description`	No	A description of the key
`role_chain`	No	Role chain for cross-account authorization. Format: `'acs:ram:<userAID>:role/<roleName2>,acs:ram:<userBID>:role/<roleName3>,...'`

Return value

Returns a wrapped keyset of the BINARY type. The wrapped keyset is the KMS CMK-encrypted form of a plaintext keyset — the system generates all keys automatically, and the original plaintext key is never exposed.

After generating a wrapped keyset, record and store it manually. You need the stored value for all subsequent encryption and decryption operations.

To convert the BINARY result to a STRING for storage or display, wrap the call with the HEX function.

Usage notes

NEW_WRAPPED_KEYSET creates the wrapped keyset, but you cannot pass it directly to encryption functions. The typical call chain is:

Call NEW_WRAPPED_KEYSET once to create the wrapped keyset. Store the result.
Call USE_WRAPPED_KEYSET at query time to convert the stored wrapped keyset into a usable keyset.
Pass the result of USE_WRAPPED_KEYSET to ENHANCED_SYM_ENCRYPT or ENHANCED_SYM_DECRYPT.

To rotate the keys in an existing wrapped keyset, use ROTATE_WRAPPED_KEYSET instead of creating a new one.

Examples

Create a wrapped keyset

SELECT HEX(NEW_WRAPPED_KEYSET(
    'acs:kms:cn-hangzhou:1**************7:key/key-hzz****************1t',
    'acs:ram::1**************7:role/kms',
    'AES-GCM-256',
    'hello'
));

Result:

+-----+
| _c0 |
+-----+
| 613256354C576836656A59314D6D59344E7A6B7A624452754D6D3434627A49786443317A655859786358426F4E6A4D774348373434582F54756C5A547A4E69337562786F4B3543412F616655573262786D345A41306B464C674A2F5758324F4E514E346746306F303236376D35335A6471797237366E57565A6836387A52687A4A673945784B6E677568794A376E6F4A68573677684B5A555A42786E4A383742536C4D46326A374F71474F4C414A6B665779694557394D58664876576E306C6D49777052746A77325643707A4259517277327944354343396C50586F31346A4351506253612F3044394C4C6E6E622F747A6B57316E4F564A6C5359354B35526130537565584F33507856773D |
+-----+

Create a wrapped keyset with cross-account access

Use the role_chain parameter to grant other Alibaba Cloud accounts access to the wrapped keyset.

SELECT HEX(NEW_WRAPPED_KEYSET(
    'acs:kms:cn-hangzhou:1**************7:key/key-hzz****************1t',
    'acs:ram::1**************7:role/kms',
    'AES-GCM-256',
    'hello',
    'acs:ram::1**************7:role/kms1'
));

Result:

+-----+
| _c0 |
+-----+
| 613256354C576836656A59314D6D59344E7A6B7A624452754D6D3434627A49786443317A655859786358426F4E6A4D784D59716D4C767954716B3562444779574C7A387965774966432F516B4A59616F57623648364A546A62434F7A7A42634F517A687A6E526F36543866714E4E63555546566874696C4A3947713556667A2F7851757A55686467504C517A2B6C433337485A535449744B53714E396B6639587666487A4D7957643842334D3179392F67423774726835437A556F786A74614571612F5A3543447668524A7731426566525647796A77574974476243475A4E594550714E767963532B333432743347396B714777626C54336F57706939706E437A667A4E4D6F4C63714F453D |
+-----+

What's next

Topic	Description
Use keysets	End-to-end guide on using keyset functions for encryption and decryption
USE_WRAPPED_KEYSET	Convert a stored wrapped keyset into a keyset for use in encryption functions
ROTATE_WRAPPED_KEYSET	Rotate the keys in an existing wrapped keyset
ENHANCED_SYM_ENCRYPT	Encrypt data using a keyset
ENHANCED_SYM_DECRYPT	Decrypt data using a keyset
NEW_KEYSET	Create a keyset without KMS wrapping
ADD_KEY_TO_KEYSET	Add a key to an existing keyset
KEYSET_TO_JSON	Convert a BINARY keyset to a readable JSON string
KEYSET_FROM_JSON	Convert a JSON keyset back to BINARY
ROTATE_KEYSET	Rotate keys in a non-wrapped keyset
NEW_WRAPPED_KEYSET	Describes the NEW_WRAPPED_KEYSET function. The function is used to assume the Alibaba Cloud Resource Name (ARN) of a role that can use Key Management Service (KMS) customer master key (CMK) ARNs to MaxCompute and create a wrapped keyset. The role ARN is specified by `role_arn`. The KMS CMK ARN is specified by kms_cmk_arn. The function is also used to grant other Alibaba Cloud accounts the permissions to decrypt a keyset based on `role_chain`.