Storage Encryption

TimechoDB supports encrypting configuration files, permission files, and TsFile data files, reducing the risk of sensitive configurations, authorization information, and business data being stored on disk in plaintext.

The features described on this page are available starting from V2.0.11.1. Before enabling them, please read the feature limitations on this page and confirm whether your existing backup, restoration, and data import processes support encrypted data.

1. Encryption Scope

Encryption Target	Protected Content	Configuration Entry
Configuration files	System configurations of ConfigNode and DataNode	enable_encrypt_config_file
Permission files	Persistent files related to users, roles, and permissions	enable_encrypt_permission_file
TsFile data files	Time-series data written by the database	encrypt_type and data encryption token environment variables

2. System File Encryption

TimechoDB can encrypt node configuration files and permission files separately. Both features can be enabled independently.

2.1 Configuration File Encryption

2.1.1 Configuration Parameters

Set the following parameter in iotdb-system.properties:

Parameter	Default Value	Description
enable_encrypt_config_file	false	Whether to encrypt configuration files. true means enabled, false means disabled. The encryption algorithm is system-specified and requires no additional configuration.

Configuration example:

enable_encrypt_config_file=true

2.1.2 Behavior After Enabling

Before enabling for the first time, please complete the configuration in the plaintext iotdb-system.properties. After the node starts successfully, the system will delete the plaintext file and generate the encrypted configuration file for the corresponding node:

• ConfigNode: .cn.iotdb-system.properties.encrypted

• DataNode: .dn.iotdb-system.properties.encrypted

The encrypted configuration file cannot be directly viewed or restored to plaintext. The original plaintext configuration file will be deleted after the node starts successfully.

Please confirm that the initial configuration is correct before enabling. After enabling, please use SET CONFIGURATION to modify configurations; you cannot recover the original configuration content by reading the encrypted file.

2.1.3 Modifying Configuration

After the configuration file is encrypted, please use SET CONFIGURATION to modify configurations. Whether a configuration takes effect immediately depends on the specific parameter; parameters that require a restart should be followed by restarting the corresponding node.

SET CONFIGURATION "key1" = "value1";

When modifying a specific node, you can specify the node ID in the statement. For the complete syntax and parameter effectiveness, please refer to Updating Configuration Items in the maintenance statements.

2.2 Permission File Encryption

2.2.1 Configuration Parameters

Set the following parameter in iotdb-system.properties:

Parameter	Default Value	Description
enable_encrypt_permission_file	false	Whether to encrypt permission files. true means enabled, false means disabled. The encryption algorithm is system-specified and requires no additional configuration.

Configuration example:

enable_encrypt_permission_file=true

After enabling permission file encryption, ConfigNode will encrypt user, role, and permission files at startup.

2.2.2 Notes

• All ConfigNodes in the cluster must use a consistent permission file encryption configuration.

3. TsFile Data Encryption

After enabling TsFile encryption, newly written data will be automatically encrypted, and automatically decrypted during queries. Existing business applications do not need to modify SQL or data read/write code.

3.1 Configuration Parameters

Set encrypt_type in iotdb-system.properties:

Configuration Value	Description
org.apache.tsfile.encrypt.UNENCRYPTED	No encryption, this is the default value.
com.timecho.iotdb.commons.encrypt.AES128.AES128	Use AES-128 encryption implementation.
com.timecho.iotdb.commons.encrypt.SM4128.SM4128	Use SM4-128 national cryptographic encryption implementation.

3.2 Token Environment Variables

Environment Variable	Required	Description
user_encrypt_token	Yes	The token used to encrypt and read TsFile data. It must be set before each node startup and must be consistent with the value used when encryption was first enabled.
user_encrypt_token_hint	No	Optional token hint. When the user_encrypt_token provided at startup is incorrect, the system displays this hint to help the user confirm the correct token.

Warning: You must back up and securely store user_encrypt_token. If this token is lost or entered incorrectly, the node will not be able to read existing encrypted data, and the token cannot be recovered from the encrypted file.

3.3 Enabling Steps

1. Configure the encryption algorithm in iotdb-system.properties.

2. Set the data encryption token and optional hint in the runtime environment where TimechoDB is started.

3. Start TimechoDB, write a set of test data, and execute a query. Then restart the node and confirm that the data can still be read when using the same user_encrypt_token.

AES-128 configuration example:

encrypt_type=com.timecho.iotdb.commons.encrypt.AES128.AES128

Linux Bash environment variable example:

export user_encrypt_token="<encryption_token>"
export user_encrypt_token_hint="<token_hint>"

Windows PowerShell environment variable example:

$env:user_encrypt_token = "<encryption_token>"
$env:user_encrypt_token_hint = "<token_hint>"

Environment variables only take effect for the current terminal and its spawned processes. Please start TimechoDB in the same terminal where the environment variables are set.

3.4 Feature Limitations

• After enabling TsFile data encryption, Pipe cannot be created or executed.

• After enabling TsFile data encryption, LOAD cannot be used to import TsFile.

• Each time a node is started, the user_encrypt_token used when encryption was first enabled must be provided. If the token is inconsistent, the node cannot read existing encrypted data.