Generate a tenant master key (Oracle mode)

This topic describes how to generate a tenant master key in an Oracle mode tenant. After the tenant master key is generated, you can use the transparent data encryption (TDE) and column encryption features.

Prerequisites

• You have created an Oracle mode tenant.
• You are logged in as the administrator of the tenant.

Generate a tenant master key

The tde_method parameter specifies the key storage method. The default value is none, which indicates that encryption is disabled. You can set the value to any value other than none to enable TDE. This topic provides examples of the internal and obcloud methods. The steps for the two methods are different. Choose a method based on your business requirements. For more information about the tde_method parameter, see tde_method.

Example: Use the internal method

The internal method stores the tenant master key in internal tables. To avoid cyclic dependencies during log replay, the clog is not encrypted in this method. The steps are as follows:

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

   ALTER SYSTEM SET tde_method='internal';
   

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

   SHOW PARAMETERS LIKE 'tde_method';
   

3. Create a keystore.

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

4. Enable the keystore.

   -- password is the password of the keystore.
   ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
   

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

   -- password is the password of the keystore.
   ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password;
   

Example: Use the obcloud method

The following example shows how to use the obcloud method. If you want to use an external key management service (KMS), set the tde_method parameter to obcloud and configure the external_kms_info parameter.

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

   ALTER SYSTEM SET tde_method='obcloud';
   

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

   Notice

   This statement can be executed only when the value of the tde_method parameter is 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 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 completed, the tenant automatically retrieves the tenant master key from the configured KMS. You do not need to manually create a keystore and generate a tenant master key as in the internal method.

   In the obcloud method, the tenant master key is generated and managed by OCP or OceanBase Cloud KMS. The database connects to the KMS by using the external_kms_info parameter and retrieves the tenant master key as needed. The key creation, storage, and rotation are completed on the KMS side. Therefore, you do not need to create a keystore or execute the key generation operation in the database.

Rotate a tenant master key

To enhance security, we recommend that you rotate the tenant master key regularly. After the tenant master key is rotated, new data is encrypted by using the new key, while old data can still be decrypted by using the old key.

• Internal method: Execute the following statement to rotate the tenant master key:

  ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY password;
  

• obcloud method: The tenant master key is managed by OCP or OceanBase Cloud KMS. For more information, see Manage TDE in OCP or Authorize a cloud account.

What to do next

After you generate a tenant master key, you can use TDE: see Enable transparent encryption for a new table.

References

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