Updated on 2024-06-03 GMT+08:00

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 KMS huawei_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;

Helpful Links

DROP CLIENT MASTER KEY