CREATE CLIENT MASTER KEY

Description

The encrypted equality query feature adopts a multi-level encryption model. The master key encrypts the column key, and the column key encrypts data. This syntax is used to create a master key object.

Precautions

This syntax is specific to a fully-encrypted database.

When connecting to the database, you need to enable the connection parameters of the encrypted equality query feature on the database driver side before running this syntax.
The master key is provided by an external key manager. This syntax processes only information such as the key source and key ID. The following external key managers are supported:
1. Huawei Cloud KMShuawei_kms
2. Derived key from the user password or provided key user_token
Before using this syntax, set environment variables for the external key manager on the database driver side. For details, see section "Setting Encrypted Equality Query" in Feature Guide.

Syntax

CREATE CLIENT MASTER KEY client_master_key_name WITH (KEY_STORE = key_store_name, KEY_PATH = key_path_value, ALGORITHM = algorithm_type);

Parameters

client_master_key_name
This parameter is used as the name of a key object. In the same namespace, the value of this parameter must be unique.

Value range: a string. It must comply with the naming convention.
KEY_STORE
External key manager. For details about the value, see Table 1.

If KEY_STORE is set to user_token, you do not need to provide the KEY_PATH parameter.
KEY_PATH
Each key is managed by an external key manager and the key path format varies depending on the key manager. The value is a character string. For details, see Table 1. A character string is enclosed in single or double quotation marks. If the length of a character string exceeds 64 characters, only single quotation marks can be used.

ALGORITHM

Encryption algorithm used by the key. For details about the value, see Table 1.

**Table 1** Parameter values for different key managers
KEY_STORE	KEY_PATH	ALGORITHM
huawei_kms	Format: '{KmsApiUrl}/{Key ID}' Reference: 'https://kms.{Project}.myhuaweicloud.com/v1.0/{Project ID}/kms/{Key ID}' Example: 'https://kms.cn-north-4.myhuaweicloud.com/v1.0/00000000000000000000000000000000/kms/00000000-0000-0000-0000-000000000000'	AES_256 SM4
user_token	Users do not need to provide KEY_PATH.	AES_256_CBC AES_256_GCM SM4

Examples

user_token scenario:

-- Decompress the installation package GaussDB-Kernel_Database version number_OS version number_64bit_Gsql.tar.gz to find the gsql_env.sh script.

-- Use the script to automatically configure the environment variables.
source gsql_env.sh

-- Connect to the database, use the privileged account, and create a user, for example, alice.
gsql -p Port number -d postgres -r
gaussdb=# CREATE USER alice PASSWORD '*******';
gaussdb=# \q

-- Connect to the database. The -C parameter must be used.
gsql -p Port number -d postgres -U alice -r -C

-- Set the user password or derived key. gsql can use password=stdin or key_token=stdin for interactive input.
-- Set the user password. The password must contain at least eight characters, including three types of the following: uppercase letters, lowercase letters, digits, and symbols.
gaussdb=> \key_info keyType=user_token,password=*********
-- Alternatively, connect to a key that meets the security strength requirements. The key is a hexadecimal code.
gaussdb=> \key_info keyType=user_token,key_token=********************************

-- Create a master key.
gaussdb=> CREATE CLIENT MASTER KEY alice_cmk WITH ( KEY_STORE = user_token , ALGORITHM = AES_256_GCM );

-- Delete the master key.
gaussdb=> DROP CLIENT MASTER KEY alice_cmk;
gaussdb=> \q

-- Connect to the database, use the privileged account, and delete user alice.
gsql -p Port number -d postgres -r
gaussdb=# DROP USER alice;