NEW_WRAPPED_KEYSET-MaxCompute(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 console.
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>}'`
`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