Use PolarDB Always-confidential

Updated at:

The fully-encrypted database feature of PolarDB for MySQL encrypts query results on the fly at the database proxy layer, so that only authorized applications that use a specific encryption driver can decrypt and access sensitive data. Use the feature when high-privilege roles such as DBAs and developers maintain a production database that holds sensitive data, such as user identity information and transaction records. The feature reduces the risk of data leaks and helps you meet compliance requirements with only minor changes to your application code.

How it works

The fully-encrypted database feature takes effect at the database proxy layer. When an SQL query matches an encryption policy, the proxy encrypts the data in the specified columns before it returns the query results to the client. Whether a client reads plaintext or ciphertext depends on the role that you assign to the database account:

  • Super Account — Query results are always in plaintext and are not affected by encryption policies. Assign this role to the management or audit accounts that must read plaintext data.

  • Standard Account — Query results are ciphertext. To decrypt the data on the client, the account must use a specific encryption driver, such as the EncJDBC driver or the GoLang driver, together with the correct key. Assign this role to the application accounts that connect through one of these drivers.

  • Other users — Any database account that you do not add to the Super Account or Standard Account role. Query results are ciphertext and cannot be decrypted, even if the user has the key.

Limits

Review the following limits before you rely on the fully-encrypted database feature to meet a compliance requirement:

  • Encryption scope — The feature encrypts the query results that the database proxy returns. It does not change how data is physically stored in the database. The data remains in plaintext in operating system (OS) files and on cloud disks.

  • Supported key type — Only the Customer Master Key (CMK) key type in Key Management Service (KMS) is supported. The Default Key type is not supported. For more information, see Key Service Overview.

  • Self-managed key risks — Self-managed keys can be lost or leaked, and key updates are not supported. If a self-managed key is lost, the data that was encrypted with the key cannot be decrypted.

Prerequisites

  • Cluster — The database proxy of your PolarDB for MySQL cluster is version 2.9.12 or later. To view the current database proxy version of the cluster, choose Settings and Management > Version Control.

  • Key — To use a key that KMS manages, purchase and enable a KMS instance, and then create a customer master key in the instance. For instructions, see Step 1: Configure a key.

  • Application — Applications that must read the encrypted columns in plaintext connect to the cluster through an encryption driver that integrates the fully-encrypted database feature. For the available drivers, see Next steps.

Note

If the database proxy version is earlier than 2.9.12 but later than 2.8.18, the configuration page for encryption policies is merged with the dynamic data masking feature. For feature independence and the best experience, upgrade the database proxy to version 2.9.12 or later.

Configure the fully-encrypted database feature

To encrypt sensitive columns, complete three configuration steps in the PolarDB console: configure a key, define role permissions, and create an encryption policy. Then verify that the encryption takes effect. You perform all steps on the Encrypt tab of the cluster.

To open the Encryption tab

  1. Log on to the PolarDB console. In the left-side navigation pane, click Clusters, select the region in which the cluster resides, and then click the ID of the target cluster to go to the cluster details page.

  2. In the left-side navigation pane, choose Settings and Management > Security, and then click the Encrypt tab.

Step 1: Configure a key

On the Encrypt page, turn on the Key Management switch to configure the key that the application uses for encryption and decryption. The following table compares the two key management modes.

ItemKMS key (recommended)Self-managed key
Key custodyKMS provides and manages the key.You generate, distribute, and store the key.
Key rotationSupported. Keys are updated automatically.Not supported.
Risk containmentIf the AccessKey pair that accesses KMS is leaked, you can disable the AccessKey pair or tighten the access policy. The key itself is not leaked.Keys can be lost or leaked. Data that is encrypted with a lost key cannot be decrypted.
How the mode appliesApplies after you select a customer master key.Applies by default if you do not configure KMS.

Use a KMS key (recommended)

Alibaba Cloud Key Management Service (KMS) provides managed keys and supports key rotation, which automatically updates keys. This mode provides high security and maintainability.

To configure a KMS customer master key

  1. Purchase and enable a KMS instance.

  2. Create a customer master key.

  3. Return to the PolarDB console, select the customer master key, and then click OK.

Use a self-managed key

If you do not configure KMS, the system uses the self-managed key mode by default. In this mode, you generate, distribute, and store the keys. Establish strict security procedures to manage the keys.

Step 2: Define role permissions

Assign each database account to a role so that the account reads plaintext or ciphertext as described in How it works.

  1. On the Encrypt page, click the Role Policy Settings tab, and then click Create Role Permission Policy.

  2. In the Role Permission Settings dialog box, set the policy name and the database accounts of each role:

    • Policy Name — Specify the policy name. The name cannot exceed 64 characters.

    • Super Account — Select the check boxes of the database accounts whose query results are always in plaintext. You can select multiple accounts.

    • Standard Account — Select the check boxes of the database accounts that decrypt query results with an encryption driver and key. You can select multiple accounts.

    Any database account that you do not add to either list becomes an Other users account and receives ciphertext that cannot be decrypted.
Important

The Super Account role has the highest permissions. Add only the required management or audit accounts to this list, and strictly control their use.

Step 3: Create an encryption policy

Warning

An encryption policy is enabled by default when you create it, and the setting cannot be changed during creation. As soon as the policy exists, every database account that is not in the Super Account list receives ciphertext for the columns that the policy covers, and clients that do not use an encryption driver cannot decrypt the results.

  1. On the Encrypt page, click the Encryption Policy Settings tab, and then click Create Encryption Policy.

  2. In the dialog box that appears, configure the policy parameters as described in the following table.

  3. Click OK to complete the creation.

ParameterDescription
Rule NameRequired. The unique identifier of the policy, such as encrypt-user-email. The value cannot exceed 64 characters.
DescriptionOptional. The detailed description of the policy, such as Encrypt the email column in the user table. The value cannot exceed 64 characters.
Enable/Disable RuleNot configurable during creation. The switch controls whether the policy takes effect. The policy is enabled by default when you create it. To change the setting, modify the policy after you create it.
Associate Permission PolicyRequired. Select the role permissions that you defined in Step 2.
DatabaseOptional. The databases to which the policy applies. Valid values: (Default) All databases, which applies the policy to all databases in the cluster; Specify databases, which applies the policy only to the specified databases. Separate multiple database names with commas (,).
Table NameOptional. The tables to which the policy applies. Valid values: (Default) All tables, which applies the policy to all tables in the specified databases; Specify tables, which applies the policy only to the specified tables. Separate multiple table names with commas (,).
Column NameRequired. The names of the columns to encrypt. Separate multiple column names with commas (,).
Encryption AlgorithmRequired. The algorithm used for encryption. Valid values: the SM4 series (SM4-128-CBC, SM4-128-ECB, SM4-128-GCM, and SM4-128-GTR), the AES-128 series (AES-128-CBC, AES-128-ECB, AES-128-GCM, and AES-128-GTR), and the AES-256 series (AES-256-CBC, AES-256-ECB, AES-256-GCM, and AES-256-GTR).
Important

Specify a precise encryption scope: always specify the database name, table name, and column name. Do not apply a policy to all databases or all tables, to avoid affecting unrelated workloads.

Verify that encryption takes effect

After you create the policy, the policy appears on the Encryption Policy Settings tab with the Enable/Disable Rule switch turned on. To confirm that the database proxy encrypts the query results:

  1. Use a database account that is not in the Super Account list to connect to the database with a standard MySQL client, such as the command line or Navicat.

  2. Query a column that the encryption policy covers.

    If the client returns ciphertext, the database proxy encrypts the query results on the fly.

Manage encryption policies

On the Encrypt page, click the Encryption Policy Settings tab to manage the policies that you created in the policy list.

  • Modify a policy — Find the policy and click Modify in the Actions column.

  • Delete a policy — Find the policy, click Delete in the Actions column, and then click OK in the dialog box that appears.

  • Enable or disable a policy — Find the policy and click the switch in the Enable/Disable Rule column.

Restrict permissions and apply security hardening

To prevent DBAs or developers who have console permissions from modifying or deleting encryption policies, harden permissions with Resource Access Management (RAM). Create a separate RAM user for each person involved, grant the user the permissions to manage PolarDB, and explicitly deny the permissions to modify or delete encryption policies.

Create a RAM policy that denies changes to encryption policies

  1. Log on to the Resource Access Management (RAM) console. In the left-side navigation pane, choose Permissions > Policies, and then click Create Policy to create a custom policy.

  2. On the visual editor tab, configure the following settings:

    • Effect — Select Deny.

    • Service — Select PolarDB.

    • Actions — Select Specify Actions, and then select polardb:ModifyMaskingRules and polardb:DeleteMaskingRules under Write operations.

    • Resource and Condition — Specify the objects that the policy authorizes and the conditions in which the policy takes effect. For more information, see Basic elements of a policy.

  3. Click OK, and then set Policy Name and Remarks in the Create Policy dialog box.

Attach the deny policy to the RAM user

  1. Log on to the RAM console. In the left-side navigation pane, choose Identities > Users, find the target RAM user, and then click Add Permissions in the Actions column.

  2. In the Policies section, select the deny policy that you created, and then click OK.

Verify the hardening result

When a restricted RAM user attempts to modify or delete an encryption policy, the console displays a No Permission error, which indicates that the operation is explicitly denied. The error provides the following details:

  • Error code — Forbidden.RAM

  • Authenticated action — polardb:ModifyMaskingRules

  • Policy type — An identity-based policy at the account level

  • Permission decision — Explicit deny

    To perform the operation, the RAM user must contact the account administrator to obtain the required permissions.

Next steps

After you configure the encryption policies, your application must read and write the encrypted data through a driver that integrates the fully-encrypted database feature: the EncJDBC driver or the GoLang driver.

FAQ

Why does a database client still return plaintext after I create an encryption policy?

Check the role of the account that you use to connect to the database. Query results are always in plaintext for accounts in the Super Account list. Test again with an account that is configured as a Standard Account to see ciphertext results.

How do I verify that encryption takes effect?

Follow the steps in Verify that encryption takes effect.

What are the risks of the Super Account role?

The Super Account role reads plaintext data directly and bypasses encryption protection. Use the role only temporarily in strictly necessary scenarios, such as data correction, migration, or auditing. Remove the accounts from the role immediately after use, and keep a complete audit trail of the operations.