Enable the always-confidential database - PolarDB - Alibaba Cloud Documentation Center

You can configure and manage the always-confidential database feature for PolarDB-X in Data Security Center (DSC), not in the PolarDB-X console. This approach provides a centralized and consistent data security administration experience. The process involves granting permissions to DSC, connecting to database assets, and defining encryption rules.

Prerequisites

Instance version: polardb-2.5.0_5.4.20-20250714_xcluster8.4.20-20250703 or later.
Note
- For information about the instance version naming rules, see Release notes.
- For information about how to view the version of an instance, see View and update the version of an instance.

Instance region:

Region Type	Region Name
The Chinese mainland	China (Qingdao), China (Beijing), China (Zhangjiakou), China (Hohhot), China (Hangzhou), China (Shanghai), China (Shenzhen), China (Guangzhou), and China (Chengdu).
Outside the Chinese mainland	China (Hong Kong), Singapore (Singapore), Malaysia (Kuala Lumpur), Indonesia (Jakarta), and Germany (Frankfurt).

Billing overview

The always-confidential database feature is free of charge.

However, this feature relies on Data Security Center (DSC) for encryption configuration and management. You must purchase DSC and ensure that you have a sufficient quota for column encryption authorization. For more information about billing, see Billing overview.

Feature overview

The always-confidential database feature for PolarDB-X is provided by DSC. It corresponds to the Column Encryption feature in DSC. It uses the AES-128-GCM and SM4-128-GCM encryption algorithms and local keys. You can configure encryption for sensitive data columns in your database. This ensures that sensitive data is stored as ciphertext. Authorized users can use an always-confidential client to decrypt the ciphertext and access the plaintext data. You can select and modify the scope of PolarDB-X instances, databases, tables, and columns to be encrypted.

Preparations

Before you can enable column encryption, you must complete the following steps: activate or upgrade DSC, grant DSC permissions to access cloud resources, grant permissions to database assets, connect to the database, and run a sensitive data detection task.

1. Activate or upgrade DSC

If you have not used Data Security Center, activate DSC

After you activate the DSC service and enable the column encryption feature, you receive a free quota for column encryption. You can purchase a larger quota if needed. The column encryption feature is available only in the Data Security Center (DSC) Free Edition, Enterprise Edition and Value-added Service Only Edition.

Edition	Free quotas (unit: columns)
Free Edition	1
Enterprise Edition	1
Value-added Service Only Edition	1

Purchase an additional column encryption quota

Log on to your Alibaba Cloud account, and go to the Data Security Center buy page.
Select an edition, and enable column encryption.
Click Buy Now and complete the payment.
You can view the feature specifications of your purchased edition on the Overview page.

If you already use Data Security Center, check your DSC edition and column encryption quota, and upgrade DSC as needed

Check your DSC edition and column encryption quota

Log on to the Data Security Center console. On the Overview page, check your DSC edition and column encryption quota:

DSC edition: The column encryption feature is available only for the Free Edition, Enterprise Editionand Value-added Service Only editions.
Column encryption quota: Check whether the quota meets your business requirements.

Upgrade DSC

If your DSC edition is not supported or your column encryption quota is insufficient, you can upgrade DSC to obtain a larger quota.

Currently, you can only upgrade from the upgrade module capabilities within the same edition, such as increasing the number of supported encrypted columns. You cannot upgrade other editions. To change your edition, you can use one of the following methods:

Free Edition: You can purchase a paid edition, such as Enterprise Edition, or Value-added Service Only, while keeping your Free Edition resources.
Enterprise Edition or Value-added Service Only: You must first request a refund and then purchase a different edition. The instance and data of the original edition will be released.
You cannot change the subscription duration when you upgrade an instance configuration. The remaining service duration of the current instance stays the same.

Log on to the Data Security Center console.
On the Overview page, click Upgrade.
Upgrade the specification of the current version.
The upgrade page shows your current specifications. Upgrade this edition either by enabling new features such as Data Detection and Response, Column Encryption, and Log Storage, or by increasing protection and encryption quotas.
Click Buy Now and complete the payment.
You can view the updated feature specifications on the Overview page.

2. Grant DSC permissions to access cloud resources

After you grant the permissions, the DSC instance can access resources of Alibaba Cloud services such as PolarDB, RDS, OSS, and MaxCompute.

Log on to the Data Security Center console.
In the RAM Authorization dialog box, click Authorize Now.
Note
If the RAM Authorization dialog box does not appear, you have already granted DSC permissions to access cloud resources.

3. Grant permissions to database assets

Before you use DSC to detect sensitive data in cloud products, including PolarDB and RDS, or audit database activities, you must grant permissions to the asset instances.

Log on to the Data Security Center console. In the navigation pane on the left, choose Asset Center.
On the Authorization Management tab, click Asset Authorization Management.
In the product navigation pane on the left of the Asset Authorization Management page, select the data type to which you want to grant permissions, and then click Asset synchronization.
Note
When you first log on to the console after you purchase a DSC instance, a task to sync the list of your cloud assets runs immediately. You do not need to sync assets manually at this time. DSC scans for new data assets every day at midnight and automatically adds them to the unauthorized list for the corresponding asset type. If you are an existing user, you must go to the Asset Authorization Management page on the Asset Center > Authorization Management tab and manually click Asset synchronization.
In the Actions column of the target asset, click Authorization.
Note
To grant permissions in a batch, select the target assets and click Batch Authorize.

4. Connect to the database and run a sensitive data detection task

One-click connection

In the navigation pane on the left, choose Asset Center.
On the Authorization Management tab, click Connect in the Actions column of the target asset instance.
In the dialog box, select Scan assets and identify sensitive data now., and then click OK.
Important
- If you select Scan assets and identify sensitive data now., DSC automatically creates and runs a default system detection task. The task reads data from the database and consumes read performance. We recommend that you perform the one-click connection during off-peak hours.
- If you do not select Scan assets and identify sensitive data now., you can go to Classification and Grading > Tasks in the navigation pane. On the Identification Tasks tab, find the task in the Default Tasks list and click Rescan to run it manually.
Click the icon to the left of the database instance to view the connection status and feature status of the database.

Credential-based connection

When you use a credential-based connection, follow the principle of least privilege. Use a dedicated database account and password.

In the navigation pane on the left, choose Asset Center.
On the Authorization Management tab, click Account Logon in the Operation column for the target asset instance.
In the Account Logon panel, click Add Credential in the Operation column for the target database.
In the Add Credential dialog box, select a credential, select or clear Scan assets and identify sensitive data now., and click OK.
If you have not created a credential, click the Create Credential tab in the Add Credential dialog box. Configure the Credential Name, Username, Password, and Credential Type for the database logon credential, and then click OK.
Important
- If you select Scan assets and identify sensitive data now., DSC automatically creates and runs a default system detection task. The task reads data from the database and consumes read performance. We recommend that you perform the one-click connection during off-peak hours.
- If you do not select Scan assets and identify sensitive data now., you can go to Classification and Grading > Tasks in the navigation pane. On the Identification Tasks tab, find the task in the Default Tasks list and click Rescan to run it manually.
Click the icon to the left of the database instance to view the connection status and feature status of the database.

Enable column encryption

Log on to the Data Security Center console. In the navigation pane on the left, choose Risk Governance > Column Encryption.
Important
You can enable and configure column encryption for a database only if the Encryption Check column shows Passed. If it shows Failed, the database's major or minor engine version may not support column encryption. For more information, see the FAQ section in this topic.
Click Rapid Encryption above the list of database instances to configure column encryption for all unencrypted columns.
Alternatively, click Rapid Encryption in the Actions column of a target database instance to configure column encryption for that instance.
In the Encryption Configuration panel, select the Asset Type, Instance name, and Plaintext Permission Accounts. Then, select the target Databases, Table, and Column for which you want to configure column encryption, and click OK. Note the following:
- DSC supports multiple encryption algorithms. However, PolarDB-X currently supports only the AES-128-GCM and SM4-128-GCM algorithms with local encryption.
- After you configure encryption, PolarDB-X database accounts have Ciphertext Permission (JDBC Decryption) by default. These accounts access the ciphertext of encrypted columns by default. You can use client code with a local key to decrypt the data and view the original plaintext.
- To access plaintext data directly, add the corresponding database account to the Plaintext Permission Accounts list. This account will have plaintext permission and can directly access the plaintext data of encrypted columns.
  Important
  To classify and categorize the latest data in your database, the database account used as the credential (the account used to connect DSC to the PolarDB-X cluster) must have plaintext permission.

Modify the column encryption configuration

Modify the scope of encrypted columns

After you enable column encryption, you can modify its scope by enabling or disabling the feature for specific columns in a database instance.

Log on to the Data Security Center console. In the navigation pane on the left, choose Risk Governance > Column Encryption.
Expand the target instance in the instance list. In the database list, find the target Databases, Table, and Column name. Click Enable Encryption or Disable Encryption to configure encryption for a single column.

Modify database account permissions

Except for accounts that are set to have Plaintext Permissions, all other accounts in the database instance have Ciphertext Permission (JDBC Decryption). You can change an account's permission to Plaintext Permissions or Ciphertext Permission (JDBC Decryption) based on your business scenario.

Log on to the Data Security Center console.
On the Risk Governance > Column Encryption page, click Permission Settings in the Accounts area.
Alternatively, click Edit in the Actions column of the instance list. In the Edit panel, click Configure for Account Permissions.
In the Permission Settings panel, search for the target instance and account to view the current permissions.
Note
If a newly added database account is not in the list, you can perform an Asset synchronization and then check again.
In the Actions column of the target account, click Modify Permissions.
You can also select multiple target accounts that have the same permission and click Batch Modify Permissions below the list.
In the Modify Permission dialog box, select the target permission and click OK.

Verify the column encryption results

You can verify data access for encrypted columns based on the configured column encryption and database account permissions.

Note

The column encryption feature is not fully compatible with third-party clients. For example, viewing encrypted data through Data Management (DMS) may cause exceptions. We recommend that you use the column encryption driver (JDBC) client to access encrypted data.

For example, the birth_date column of the students01 table in a test PolarDB-X cluster is encrypted. One database account in the cluster is granted Plaintext Permissions, while another account retains Ciphertext Permission (JDBC Decryption).

Connect to the database using the account with Ciphertext Permission (JDBC Decryption). Run the SELECT * FROM students01; statement to view the data table. The query returns ciphertext for the encrypted column.
Connect to the database using the account with Plaintext Permissions. Run the SELECT * FROM students01; statement to view the data table. The query returns plaintext for the encrypted column.

Client usage instructions

If your database account has Ciphertext Permission (JDBC Decryption), you can use the column encryption driver (JDBC) to connect to the target database. This allows your Java application to access the encrypted data. The JDBC driver automatically decrypts the ciphertext and returns plaintext in a process that is transparent to the application. For more information, see Column encryption driver (JDBC).

FAQ

What do I do if the encryption check for a PolarDB cluster fails?

First, confirm that the PolarDB-X cluster is in the Running state. You cannot configure column encryption for clusters that are not running.

Second, if the version of the authorized PolarDB-X instance is earlier than polardb-2.5.0_5.4.20-20250714_xcluster8.4.20-20250703, the Encryption Check column shows Failed.

Solutions

To configure column encryption for the target PolarDB cluster, you can Upgrade the Minor Engine Version on the instance details page. For detailed instructions and notes, see View and upgrade the instance version. After you upgrade the database kernel, you can enable column encryption for the PolarDB database.
After you upgrade the minor engine version, you must sync assets in the Data Security Center console to obtain the latest database information.
1. Log on to the Data Security Center console. In the navigation pane on the left, choose Asset Center. On the Authorization Management tab, click Asset Authorization Management.
2. In the product navigation pane on the left of the Asset Authorization Management panel, click the target cluster type.
3. In the Asset Authorization Management panel, click Sync Assets.

PolarDB:Enable the always-confidential database