Generate a tenant master key (Oracle-compatible mode)

This topic describes how to generate a tenant master key in an Oracle-compatible tenant. After you generate a tenant master key, you can use transparent data encryption (TDE) and column encryption.

Prerequisites

• An Oracle-compatible tenant has been created.
• You are logged in as an administrator user.

Generate a master key

The tde_method parameter is used to set the master key storage method. The default value is none, which means encryption is disabled. You can set this parameter to any value other than none to enable transparent data encryption (TDE). This topic provides examples of the internal and obcloud methods. The steps for these two methods are different. Choose the method that meets your business requirements. For more information about the tde_method parameter, see tde_method.

Example of the internal method

In the internal method, the master key is stored internally, and the encrypted information is managed in internal tables. To avoid cyclic dependencies during log replay, encryption is not performed on clogs in this method. The steps are as follows:

1. Execute the following statement to enable encryption using the internal method.

   ALTER SYSTEM SET tde_method='internal';
   

2. Execute the following statement to verify that the tde_method parameter is set to internal on all OBServer nodes of the tenant.

   SHOW PARAMETERS LIKE 'tde_method';
   

3. Create a keystore.

   -- Replace keystore_name and password with actual values.
   ADMINISTER KEY MANAGEMENT CREATE KEYSTORE keystore_name IDENTIFIED BY password;
   

4. Open the keystore.

   -- Replace password with the password set in the previous step.
   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
   

5. Execute the following statement to generate the master key.

   -- Replace password with the password set in the previous step.
   ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password;
   

Example of the obcloud method

The following example shows how to use the obcloud method. To use an external KMS service, set the tde_method parameter to obcloud and configure the external_kms_info parameter.

1. Execute the following statement to enable encryption using the obcloud method.

   ALTER SYSTEM SET tde_method='obcloud';
   

2. Execute the following statement to verify that the tde_method parameter is set to obcloud on all OBServer nodes of the tenant.

   Notice

   This statement can only be executed successfully if the `tde_method` parameter is set to `obcloud` on all OBServer nodes of the tenant.

   SHOW PARAMETERS LIKE 'tde_method';
   

3. Execute the following statement to configure the key management information.

   For more information about the external_kms_info parameter, see external_kms_info.

   -- The following example is for reference only. Replace the key management information with the actual values.
   ALTER SYSTEM SET external_kms_info='{
            "KMS_HOST": "kms.ob.com:443",
            "ROOT_CERT": "******",
            "PRIVATE_KEY": "******",
            "PRIVATE_KEY_PHRASE": "ob2025",
            "SCENE": "ANT",
            "KEY_NAME": "ob_cluster_key",
            "CALLER": "oceanbase_admin"}';
   

4. After the configuration is complete, the tenant will obtain the master key from the configured KMS, without the need to manually create a keystore and generate a master key as required in the internal method.

   In the obcloud method, the master key is generated and managed by OCP or OceanBase Cloud KMS. The database connects to the KMS using the external_kms_info configuration and retrieves the master key as needed. Key creation, storage, and rotation are all handled by the KMS, so there is no need to create a keystore or generate a master key within the database.

Rotate the master key

To improve security, it is recommended to regularly rotate the master key. After the master key is rotated, new data will be encrypted using the new key, while old data can still be decrypted using the old key.

• In internal mode: Execute the following statement to rotate the master key:

  ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password;
  

• In obcloud mode: The master key is managed by OCP or OceanBase Cloud KMS. For more information, see Manage Transparent Data Encryption (TDE) or Authorize cloud vendor accounts.

What to do next

After you generate the master key, you can use transparent data encryption. For more information, see Set up transparent encryption for newly created tables

References

• Overview of tenant master keys
• Generate a tenant master key (MySQL-compatible mode)