From d54f4f4f943f50e9a411d5db0a5d9c8e19bd8022 Mon Sep 17 00:00:00 2001 From: Yang Keao Date: Mon, 11 Aug 2025 17:20:42 +0800 Subject: [PATCH] add SEM configuration document Signed-off-by: Yang Keao --- TOC.md | 1 + basic-features.md | 2 +- security-enhanced-mode.md | 178 +++++++++++++++++++++++++++++++++++++ system-variables.md | 6 +- tidb-configuration-file.md | 8 +- 5 files changed, 191 insertions(+), 4 deletions(-) create mode 100644 security-enhanced-mode.md diff --git a/TOC.md b/TOC.md index 4bb2b637b50d0..b2033ee457877 100644 --- a/TOC.md +++ b/TOC.md @@ -763,6 +763,7 @@ - [TiDB Password Management](/password-management.md) - [Role-Based Access Control](/role-based-access-control.md) - [Certificate-Based Authentication](/certificate-authentication.md) + - [Security Enhanced Mode](/security-enhanced-mode.md) - SQL - SQL Language Structure and Syntax - Attributes diff --git a/basic-features.md b/basic-features.md index 5caec3ae3ce6c..0efedd921cf92 100644 --- a/basic-features.md +++ b/basic-features.md @@ -209,7 +209,7 @@ You can try out TiDB features on [TiDB Playground](https://play.tidbcloud.com/?u | [Password management](/password-management.md) | Y | Y | Y | Y | Y | N | N | N | N | N | | [MySQL compatible `GRANT` system](/privilege-management.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | | [Dynamic Privileges](/privilege-management.md#dynamic-privileges) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | -| [Security Enhanced Mode](/system-variables.md#tidb_enable_enhanced_security) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | +| [Security Enhanced Mode](/security-enhanced-mode.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | | [Redacted Log Files](/log-redaction.md) | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | ## Data import and export diff --git a/security-enhanced-mode.md b/security-enhanced-mode.md new file mode 100644 index 0000000000000..02046b28fc31f --- /dev/null +++ b/security-enhanced-mode.md @@ -0,0 +1,178 @@ +# TiDB Security Enhanced Mode (SEM) + +## Overview and Purpose + +Security Enhanced Mode (SEM) provides a mandatory access control layer that operates on top of TiDB's standard privilege system. Its primary purpose is to limit the capabilities of all users, including the `root` user. + +This feature is especially critical in Database-as-a-Service (DBaaS) environments. Service providers can offer tenants `root` access to their databases—ensuring compatibility with applications—while simultaneously preventing them from executing commands that could compromise the underlying cluster's security, stability, or data isolation. + +You can enable SEM in two ways: a default mode with a predefined set of restrictions, or a custom mode that uses a configuration file for a highly detailed security policy. + +## Enabling and Configuring SEM + +You enable SEM by setting `security.enable-sem = true` in your TiDB server's configuration file (`tidb.toml`). The specific behavior of SEM depends on whether you also provide a configuration file. + +You can verify which mode is active by checking the `tidb_enable_enhanced_security` system variable. + +```sql +SHOW VARIABLES LIKE 'tidb_enable_enhanced_security'; +``` + +### Mode 1: Default Restrictions + +This mode provides a baseline set of security enhancements that primarily reduce the broad power of the `SUPER` privilege, replacing it with fine-grained privileges. + + * Activation: Set `enable-sem = true` in `tidb.toml` without setting the `sem-config` path. + * System Variable: `tidb_enable_enhanced_security` will be `ON`. + +In this mode, TiDB enforces the following restrictions: + +| Restricted Action | Required Privilege for Exemption | +| :------------------------------------------------------------------------------------------------------------ | :------------------------------- | +| Writing data to system tables in the `mysql` schema and viewing sensitive columns in `information_schema` tables. | `RESTRICTED_TABLES_ADMIN` | +| Viewing sensitive variables in `SHOW STATUS`. | `RESTRICTED_STATUS_ADMIN` | +| Viewing and setting sensitive system variables. | `RESTRICTED_VARIABLES_ADMIN` | +| Dropping or modifying a user account that holds the `RESTRICTED_USER_ADMIN` privilege. | `RESTRICTED_USER_ADMIN` | + +### Mode 2: Custom Restrictions via Configuration File + +This mode enables a fully customizable security policy defined in a JSON file. It offers granular control over tables, variables, privileges, and SQL commands. + + * Activation: Set both `enable-sem = true` and `sem-config = '/path/to/your/sem-policy.json'` in `tidb.toml`. + * System Variable: `tidb_enable_enhanced_security` will be `CONFIG`. + +You must restart your TiDB cluster for any configuration changes to take effect. + +## Custom Policy Feature Reference (Mode 2) + +The following sections detail the features available when using a custom configuration file (Mode 2). + +### Restricting Access to Tables and Databases + +This feature prevents access to specified databases or individual tables. + + * Configuration: + * `restricted_databases`: An array of database names. All tables within these databases become inaccessible. + * `restricted_tables`: An array of objects specifying a `schema` and `name`. The optional `"hidden": true` flag makes the table invisible. + * Exemption Privilege: `RESTRICTED_TABLES_ADMIN` + * Configuration Example: + ```json + { + "version": "1", "tidb_version": "9.0.0", + "restricted_databases": ["mysql"], + "restricted_tables": [{"schema": "information_schema", "name": "columns", "hidden": true}] + } + ``` + As a restricted user (e.g., `root`): + ``` + mysql> select * from information_schema.columns; + ERROR 1142 (42000): SELECT command denied to user 'root'@'%' for table 'columns' + mysql> use mysql; + ERROR 1044 (42000): Access denied for user 'root'@'%' to database 'mysql' + ``` + +### Restricting System Variables + +This feature controls interaction with system variables by hiding them, making them read-only, or masking their values. + + * Configuration: The `restricted_variables` key contains an array of variable objects with a control flag: + * `"hidden": true`: The variable is inaccessible. + * `"readonly": true`: The variable can be read but not modified. + * `"value": "string"`: Overrides the variable's return value. Note: This option is only supported for local read-only variables. + * Exemption Privilege: `RESTRICTED_VARIABLES_ADMIN` + * Configuration Example: + ```json + { + "version": "1", "tidb_version": "9.0.0", + "restricted_variables": [ + {"name": "tidb_config", "hidden": true}, + {"name": "hostname", "hidden": false, "value": "testhostname"} + ] + } + ``` + As a restricted user (e.g., `root`): + ``` + mysql> SELECT @@tidb_config; + ERROR 1227 (42000): Access denied; you need (at least one of) the RESTRICTED_VARIABLES_ADMIN privilege(s) for this operation + mysql> SELECT @@hostname; + +--------------+ + | @@hostname | + +--------------+ + | testhostname | + +--------------+ + 1 row in set (0.00 sec) + ``` + +### Restricting Privileges and User Management + +This feature prevents powerful privileges from being granted and protects administrative accounts from being altered or dropped. + + * Configuration: The `restricted_privileges` key contains an array of privilege names. Once listed, a privilege cannot be granted. Listing `RESTRICTED_USER_ADMIN` itself protects users who hold that privilege. + * Exemption Privilege: `RESTRICTED_PRIV_ADMIN` + * Configuration Example: + ```json + { + "version": "1", "tidb_version": "9.0.0", + "restricted_privileges": ["FILE"] + } + ``` + As a restricted user (e.g., `root`): + ``` + mysql> GRANT FILE ON *.* TO 'some_user'@'%'; + ERROR 1227 (42000): Access denied; you need (at least one of) the RESTRICTED_PRIV_ADMIN privilege(s) for this operation + -- Assuming 'sem_admin' has the RESTRICTED_USER_ADMIN privilege, attempt to drop the user + mysql> DROP USER 'sem_admin'@'%'; + ERROR 1227 (42000): Access denied; you need (at least one of) the RESTRICTED_USER_ADMIN privilege(s) for this operation + ``` + +### Restricting Status Variables + +This feature filters sensitive operational data from the output of `SHOW STATUS`. + + * Configuration: + * `restricted_status_variables`: An array of status variable names to hide from `SHOW STATUS`. + * Exemption Privilege: `RESTRICTED_STATUS_ADMIN` + * Configuration Example: + ```json + { + "version": "1", "tidb_version": "9.0.0", + "restricted_status_variables": ["tidb_gc_leader_desc"] + } + ``` + As a restricted user (e.g., `root`): + ``` + mysql> SHOW STATUS LIKE 'tidb_gc_leader_desc'; + Empty set (0.01 sec) + ``` + +### Restricting SQL Commands + +This feature blocks the execution of specific SQL statements or entire classes of commands. + + * Configuration: + * `restricted_sql`: An object containing two arrays: + * `sql`: A list of specific SQL commands to block (e.g., `BACKUP`, `RESTORE`). + * `rule`: A list of predefined rule names that block specific classes of statements. Supported rules are: + * `time_to_live`: Blocks DDL statements related to Table TTL. + * `alter_table_attributes`: Blocks the `ALTER TABLE ... ATTRIBUTES="..."` statement. + * `import_with_external_id`: Blocks `IMPORT INTO` statements that use an S3 `EXTERNAL_ID`. + * `select_into_file`: Blocks `SELECT ... INTO OUTFILE` statements. + * `import_from_local`: Blocks `LOAD DATA LOCAL INFILE` and `IMPORT INTO` from a local file path. + * Exemption Privilege: `RESTRICTED_SQL_ADMIN` + * Configuration Example: + ```json + { + "version": "1", "tidb_version": "9.0.0", + "restricted_sql": { + "rule": ["time_to_live"], + "sql": ["BACKUP"] + } + } + ``` + As a restricted user (e.g., `root`): + ``` + mysql> BACKUP DATABASE `test` TO 's3://bucket/backup'; + ERROR 8132 (HY000): Feature 'BACKUP DATABASE `test` TO 's3://bucket/backup'' is not supported when security enhanced mode is enabled + mysql> CREATE TABLE test.t1 (id INT, created_at TIMESTAMP) TTL = `created_at` + INTERVAL 1 DAY; + ERROR 8132 (HY000): Feature 'CREATE TABLE test.t1 (id INT, created_at TIMESTAMP) TTL = `created_at` + INTERVAL 1 DAY' is not supported when security enhanced mode is enabled + ``` diff --git a/system-variables.md b/system-variables.md index 6d1e2fd125559..ea2f4f4ec74f4 100644 --- a/system-variables.md +++ b/system-variables.md @@ -2062,12 +2062,13 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - Scope: NONE - Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No -- Type: Boolean +- Type: String - Default value: `OFF` -- This variable indicates whether the TiDB server you are connected to has the Security Enhanced Mode (SEM) enabled. To change its value, you need to modify the value of `enable-sem` in your TiDB server configuration file and restart the TiDB server. +- Possible values: `OFF`, `ON`, `CONFIG` +- This variable indicates whether the TiDB server you are connected to has the Security Enhanced Mode (SEM) enabled. To change its value, you need to modify the value of `enable-sem` and `sem-config` in your TiDB server [configuration file](/tidb-configuration-file.md) and restart the TiDB server. @@ -2083,6 +2084,7 @@ mysql> SELECT job_info FROM mysql.analyze_jobs ORDER BY end_time DESC LIMIT 1; - `RESTRICTED_STATUS_ADMIN`: The ability to see sensitive variables in the command `SHOW STATUS`. - `RESTRICTED_VARIABLES_ADMIN`: The ability to see and set sensitive variables in `SHOW [GLOBAL] VARIABLES` and `SET`. - `RESTRICTED_USER_ADMIN`: The ability to prevent other users from making changes or dropping a user account. +- For detailed configuration, see [Security Enhanced Mode documentation](/security-enhanced-mode.md). ### tidb_enable_exchange_partition diff --git a/tidb-configuration-file.md b/tidb-configuration-file.md index d7970037d1de7..581e9ba559f98 100644 --- a/tidb-configuration-file.md +++ b/tidb-configuration-file.md @@ -385,10 +385,16 @@ Configuration items related to security. ### `enable-sem` -- Enables the Security Enhanced Mode (SEM). +- Enables the [Security Enhanced Mode (SEM)](/security-enhanced-mode.md). - Default value: `false` - The status of SEM is available via the system variable [`tidb_enable_enhanced_security`](/system-variables.md#tidb_enable_enhanced_security). +### `sem-config` + +- Specifies the path to the JSON configuration file for custom [Security Enhanced Mode (SEM)](/security-enhanced-mode.md) restrictions. +- Default value: `""` +- The status of SEM is available via the system variable [`tidb_enable_enhanced_security`](/system-variables.md#tidb_enable_enhanced_security). + ### `ssl-ca` - The file path of the trusted CA certificate in the PEM format.