This topic describes the mechanism, limits, and procedure to encrypt data in Hologres.

Background information

Hologres allows you to use Key Management Service (KMS) to encrypt data for storage. This way, Hologres can provide static data protection to meet the requirements for enterprise governance and security compliance. After data encryption is enabled, query and write performance is affected due to the encryption and decryption operations. The performance loss is about 20% to 40%. The specific performance loss depends on the query characteristics.


  • Only Hologres V1.1 and later support data encryption for storage. If the version of your instance is earlier than V1.1, submit a ticket or join the Hologres DingTalk group for technical support.
  • Background configurations are required to use this feature. To configure the background, submit a ticket.
  • Your operations such as the disable and delete operations on your customer master keys (CMKs) in KMS may affect data encryption and decryption in Hologres. Hologres caches historical configurations. Your operations in KMS take effect in a delayed manner within 24 hours.
  • You can encrypt data for storage only if data encryption for storage is enabled. Data in the tables that are created before this feature is enabled cannot be encrypted for storage.

Data encryption mechanism

Hologres uses CMKs in KMS to encrypt and decrypt data based on the following data encryption mechanism:
  • Hologres uses CMKs in KMS to encrypt or decrypt data. The data encryption feature is enabled for a database, not a Hologres instance or specific tables. Before you use the data encryption feature, make sure that KMS is activated in the region in which your Hologres instance resides.
  • KMS generates and manages CMKs and ensures CMK security.
  • Hologres supports the following encryption algorithms: AES-256, AES-CTR, RC4, and SM4.
  • Hologres allows you to use only CMKs created based on the bring your own key (BYOK) feature to encrypt or decrypt data.
    • You can create a CMK in KMS and use this CMK for data encryption in Hologres. For more information about how to create a CMK in KMS, see Create a CMK.
    • You must use Resource Access Management (RAM) to grant the required permissions to Hologres so that Hologres can create instances that use BYOK.
  • When you read or write data, Hologres calls KMS API operations to obtain key information. By default, the key information is retained for 24 hours. As a result, you are charged for using KMS when you use the data encryption feature. For more information about KMS billing, see Billing.


  1. Create a custom policy.
    1. Log on to the Resource Access Management (RAM) console. In the left-side navigation pane, choose Permissions > Policies. On the page that appears, click Create Policy.
    2. On the Create Policy page, set the Policy Name parameter to AliyunHologresEncryptionDefaultRolePolicy, select Script for the Configuration Mode parameter, and then enter the following script in the Policy Document section.
      Create a policy
          "Version": "1",
          "Statement": [
                  "Action": [
                  "Resource": "acs:kms:*:*:*/*",
                  "Effect": "Allow"
    3. Click OK to create the policy.
  2. Create a RAM role and grant permissions to the RAM role.
    1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Roles.
    2. On the Roles page, click Create Role. In the Select Role Type step of the Create Role panel, select Alibaba Cloud Service for the Select Trusted Entity parameter.
    3. Click Next. In the Configure Role step, set the Role Type parameter to Normal Service Role, enter AliyunHologresEncryptionDefaultRole in the RAM Role Name field, select Hologres from the Select Trusted Service drop-down list, and then click OK. Create a role
    4. In the Finish step, click Add Permissions to RAM Role.
    5. In the Add Permissions panel, set the Authorized Scope parameter to Alibaba Cloud Account. In the Select Policy section, click the Custom Policy tab and select AliyunHologresEncryptionDefaultRolePolicy that you created in Step 1. Grant permissions
    6. Click OK to create the RAM role and grant permissions to the RAM role.
      After the RAM role is created, click the name of the role. On the Trust Policy Management tab, check whether the trust policy settings are the same as those in the following figure. Trust policy
  3. Create a CMK.
    1. Log on to the KMS console.
    2. In the top navigation bar, select the region in which you want to create a CMK.
    3. In the left-side navigation pane, click Keys.
    4. Click Create Key. In the Create Key dialog box, configure the parameters described in the following table.
      Parameter Description
      KMS Instance The KMS instance that you use.
      Key Spec The type of the CMK. Valid values:
      • Symmetric:
        • Aliyun_AES_256
        • Aliyun_SM4
      • Asymmetric:
        • RSA_2048
        • RSA_3072
        • EC_P256
        • EC_P256K
        • EC_SM2
      • The Aliyun_SM4 and EC_SM2 types are supported only for regions in the Chinese mainland in which managed hardware security modules (HSMs) are used.
      • The RSA_3072 type is supported only by a dedicated KMS instance.
      Purpose The purpose of the CMK. Valid values:
      • Encrypt/Decrypt: encrypts or decrypts data.
      • Sign/Verify: generates or verifies a digital signature.
      Alias Name The alias of the CMK, which helps identify the CMK. Aliases are optional to CMKs.

      For more information, see Overview

      Protection Level The protection level of the CMK. Valid values:
      • Software: The CMK is protected by using a software module.
      • Hsm: The CMK is managed in an HSM, and the HSM safeguards the CMK.
      Description The description of the CMK.
      Rotation Period The interval of automatic rotation. Valid values:
      • 30 Days.
      • 90 Days.
      • 180 Days.
      • 365 Days.
      • Disable: Automatic rotation is disabled.
      • Customize: You can specify a custom interval that ranges from 7 days to 730 days.
      Note You can set this parameter only if you set the Key Spec parameter to Aliyun_AES_256 or Aliyun_SM4.
  4. Enable data encryption for a database.
    1. Log on to the database for which you want to enable data encryption. For more information about how to log on to a database, see Log on to a database.
    2. On the Ad-hoc Query tab, select the instance to which the database belongs from the Instance drop-down list and select the database from the Database drop-down list. Enter the following statement in the SQL editor and click Run.

      This SQL statement is used to enable data encryption for the database.

      ALTER DATABASE <db_name> SET hg_experimental_encryption_options='<encryption_type>,<cmk_id>,<ram_role>,<uid>';
      The following table describes the parameters in the preceding statement.
      Parameter Description
      db_name The name of the database for which you want to enable data encryption.
      encryption_type The encryption algorithm. Valid values: AES256, AESCTR, RC4, and SM4.
      cmk_id The ID of the CMK. You can obtain the ID of the CMK on the CMK details page in the KMS console.
      ram_role The RAM role that is assigned to Hologres.
      uid The ID of your Alibaba Cloud account. For more information, see Account IDs.
    The following sample statements show how to enable data encryption for a database, create a table in the database, and then query the table:
    ALTER DATABASE hoxxxx set hg_experimental_encryption_options='AES256,623c26ee-xxxx-xxxx-xxxx-91d323cc4855,AliyunHologresEncryptionDefaultRole,187xxxxxxxxxxxxx';
    CREATE TABLE a(id int);
    INSERT INTO a values(1);
    SELECT hg_admin_command('flush');-- This statement is used only for testing. It allows query results to be immediately displayed.
    SELECT * FROM a;
    The following figure shows the result. Sample resultIf you disable KMS and restart the Hologres instance, an error is reported when you query the data in the a table. If you do not restart the Hologres instance immediately after KMS is disabled, you can query the data in the a table within 24 hours. After 24 hours, an error is reported when you query the data in the a table.