From 93fa11604acacb5a4dcc5381501425a550f47857 Mon Sep 17 00:00:00 2001 From: W1y1r <2730956796@qq.com> Date: Fri, 25 Apr 2025 16:14:56 +0800 Subject: [PATCH] Add data security document --- .../latest-Table/User-Manual/Data-Security.md | 332 ++++++++++++++++++ .../latest/User-Manual/Data-Security.md | 332 ++++++++++++++++++ 2 files changed, 664 insertions(+) create mode 100644 src/zh/UserGuide/latest-Table/User-Manual/Data-Security.md create mode 100644 src/zh/UserGuide/latest/User-Manual/Data-Security.md diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Data-Security.md b/src/zh/UserGuide/latest-Table/User-Manual/Data-Security.md new file mode 100644 index 000000000..c34c439eb --- /dev/null +++ b/src/zh/UserGuide/latest-Table/User-Manual/Data-Security.md @@ -0,0 +1,332 @@ + + +# 数据安全 + +## 1. 数据存储加密 +### 1.1 概述 + +IoTDB 通过内置的透明加密引擎支持对数据文件 TsFile 的加密防护。启用加密功能后，即可实现数据在写入时实时加密、读取时无缝解密的全流程自动化处理，保证落盘文件数据安全。该过程完全融入数据库内核，业务应用无感知且无需进行任何代码改造或查询逻辑调整。 + +### 1.2 参数配置 + +IoTDB 配置文件` ${IOTDB_HOME}/${IOTDB_CONF}/iotdb-system.properties`中数据加密相关的参数如下所示： + +| 参数 | 注释 | +| :----------------- | :----------------------------------------------------------- | +| `encrypt flag` | `true`为开启加密 | +| `encrypt_key_path` | 文件导入的主密钥文件路径 | +| `encrypt type` | 加密方式，例如"`org.apache.tsfile.encrypt.UNENCRYPTED`"。目前包括`AES128`和`UNENCRYPTED(SM4128)`。 | + +### 1.3 使用流程 + +1. 获取 加密算法 Jar 包 +2. 将 Jar 包放置于 IoTDB 部署路径下 lib 文件夹中，即 `${IOTDB_HOME}/lib` +3. 修改配置文件 ` ${IOTDB_HOME}/${IOTDB_CONF}/iotdb-system.properties` + +```Properties +encrypt_flag=true +encrypt_type=org.example.encrypt.AES128.AES128 +# encrypt_type=org.example.encrypt.SM4128.5M41283 +encrypt_key_path=...... +``` + +4. 启动 IoTDB 即可使用对应加密算法对 TsFile 文件进行加密。 + +### 1.4 注意事项 + +- 开启加密后，对合并功能无影响。但不支持系统内存在与配置不同的加密文件，以免触发合并时发生冲突。 +- 开启加密后禁用 Pipe。 +- 开启加密后禁用 Load TsFile。 +- 建议对主密钥文件路径进行一定的保护，例如存放在特定权限才能访问的磁盘上等。 + +## 2. 数据传输加密 + +### 2.1 概述 + +在某些客户的生产环境中，对于数据传输的安全性要求更高，希望有更安全的传输方式，因此扩展了 Datanode 的 Client RPC 以支持数据传输加密。以下是支持数据传输加密的方式： + +1. Thrift 除了普通模式与压缩模式外，增加 SSL 模式 +2. SessionPool(java) 与 Session(java) 支持使用 SSL 模式连接 +3. JDBC 支持使用 SSL 模式连接 +4. CLI 支持使用 SSL 模式连接 +5. 支持压缩模式 +6. 支持 RSA ECDSA 证书 + 1. RSA证书：算法为RSA，签名算法为SHA256withRSA + 2. ECDSA 证书：算法为EC，签名算法为SHA256withECDSA + +### 2.2 Server端配置 + +iotdb-datanode.properties 的默认配置，默认 ssl 是关闭状态。 + +#### 2.2.1 默认配置示例： + +```Properties +#iotdb-datanode.properties的默认配置 +....... +# is SSL enabled +#enable_thrift_ssl=false + +# SSL key store path +#key_store_path= + +# SSL key store password +#key_store_pwd= +....... +``` + +#### 2.2.2 启用 ssl 配置步骤： + +1. 在iotdb/conf/iotdb-datanode.properties 配置文件中找到enable_thrift_ssl 配置默认是false,修改成true +2. 修改key_store_path，添加生成的keystore路径 +3. 修改key_store_pwd为生成keystore的密码（秘钥库口令） +4. 启动iotdb服务 + +启用 ssl 配置后，需重启 iotdb 服务。同时，对应的使用到 dn_rpc_port 接口的客户端都需要使用 ssl 方式访问，否则不能访问。 + +```SQL +# is SSL enabled +enable_thrift_ssl=true + +# SSL key store path +key_store_path=/Users/keystore/.keystore + +# SSL key store password +key_store_pwd=123456 +``` + +### 2.3 Java SessionPool + +SessionPool 客户端配置ssl 需要配置useSSL、trustStore、trustStorePwd。 + +- useSSL ：是否开启ssl +- trustStore ：truststore的证书路径 +- trustStorePwd：truststore的证书密码（秘钥库口令） + +#### 2.3.1 代码示例： + +```SQL + sessionPool = + new SessionPool.Builder() + .nodeUrls(nodeUrls) +.user("root") +.password("root") +.maxSize(3) +.useSSL(true) +.trustStore("/Users/key/.truststore") + .trustStorePwd("123456") + .build(); +``` + +### 2.4 Java Session + +Session 客户端配置ssl 需要配置useSSL、trustStore、trustStorePwd 代码示例 + +- useSSL ：是否开启ssl +- trustStore ：truststore的证书路径 +- trustStorePwd：truststore的证书密码（秘钥库口令） + +#### 2.4.1 代码示例： + +```SQL +session = + new Session.Builder() + .host(LOCAL_HOST) + .port(6667) + .username("root") + .password("root") + .version(Version.V_1_0) + .useSSL(true) + .trustStore("/Users/key/.truststore") + .trustStorePwd("123456") + .build(); +``` + +### 2.5 JDBC + +jdbc 支持两种方式的ssl 配置，需要配置use_ssl、trust_store、trust_store_pwd。 + +- use_ssl:是否开启ssl 默认是false +- trust_store:truststore的证书路径 +- trust_store_pwd:truststore证书的密码（秘钥库口令） + +#### 2.5.1 代码示例： + +**方式一、在jdbc 的url 中配置使用** + +jdbc:iotdb://ip:port?use_ssl=true&trust_store_pwd=123456&trust_store=/Users/keystore/.truststore + +```SQL +try (Connection connection = + DriverManager.getConnection( + "jdbc:iotdb://127.0.0.1:6667?version=V_1_0&use_ssl=true&trust_store_pwd=123456&trust_store=/Users/keystore/.truststore", + "root", + "root");Statement statement = connection.createStatement(){ + // 代码逻辑 + + }catch (IoTDBSQLException e) { + logger.error("IoTDB Jdbc example error", e); + } +``` + +**方式二、使用Properties 来配置使用** + +```SQL +java.util.Properties info = new Properties(); +info.setProperty("use_ssl", "true"); +info.setProperty("user", "root"); +info.setProperty("password", "root"); +info.setProperty("trust_store", "/Users/keystore/.truststore"); +info.setProperty("trust_store_pwd","123456"); +try (Connection connection = + DriverManager.getConnection("jdbc:iotdb://127.0.0.1:6667?version=V_1_0", info); + Statement statement = connection.createStatement()) { + // 代码逻辑 + +}catch (IoTDBSQLException e) { + logger.error("IoTDB Jdbc example error", e); +} +``` + +### 2.6 CLI + +```SQL +./start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -usessl true -ts /Users/keystore/.truststore -tpw 123456 +``` + +### 2.7 SSL证书生成方式 + +需安装 JDK、测试jdk8和jdk11生成证书未发现问题 + +1. 创建私钥（.keystore） + +```SQL +keytool -genkeypair -alias mykey -keyalg RSA -validity 7 -keystore .keystore +``` + +2. 导出对应的证书 + +```SQL +keytool -export -alias mykey -keystore .keystore -rfc -file certificate.cer +``` + +3. 将该证书导入到客户端信任库（公钥：.truststore） + +```SQL +keytool -import -alias mykey -file certificate.cer -keystore .truststore +``` + +4. 创建 ECDSA 证书 + +提示:FIPS标准规定使用 RSA、ECDSA 或 EdDSA(23年刚支持) + +```Bash +keytool -genkeypair -alias mykey -keyalg EC -validity 7 -keystore aa.keystore + +keytool -export -alias mykey -keystore aa.keystore -rfc -file certificate.cer + +keytool -import -alias mykey -file certificate.cer -keystore aa.truststore +``` + +### 2.8 性能测试 + +#### 2.8.1 插入测试 + +使用session 的inserttablet方法，使用100 设备*100测点，每批 100 行 loop 100 次，测试3遍，三次插入使用不同的设备名字，测试环境：1c1d，mac 16G，Intel Core i5。 + +**代码示例：** + +```Properties +for(int i=0;i<100;i++){ + insertTablet(i+""); +} +private static void insertTablet(String d) throws IoTDBConnectionException, StatementExecutionException { + List schemaList = new ArrayList<>(); + for(int i=1;i<=100;i++){ + schemaList.add(new MeasurementSchema("s"+i, TSDataType.INT64)); + } + + Tablet tablet = new Tablet(ROOT_SG1_D1+d, schemaList, 100); + long timestamp = System.currentTimeMillis(); + + for (long row = 0; row < 100; row++) { + int rowIndex = tablet.rowSize++; + tablet.addTimestamp(rowIndex, timestamp); + for (int s = 0; s < 100; s++) { + long value = random.nextLong(); + tablet.addValue(schemaList.get(s).getMeasurementId(), rowIndex, value); + } + if (tablet.rowSize == tablet.getMaxRowNumber()) { + session.insertTablet(tablet, true); + tablet.reset(); + } + timestamp++; + } + + if (tablet.rowSize != 0) { + session.insertTablet(tablet); + tablet.reset(); + } + +} +``` + +**插入测试结果:** + +| | ssl（单位ms） | 非ssl（单位ms） | +| ------ | ------------- | --------------- | +| 第一次 | 13611 | 14099 | +| 第二次 | 11938 | 10236 | +| 第三次 | 13801 | 13663 | + +**测试结论：** + +根据ssl 三次取平均值为13117ms、非ssl取平均值12666ms，综合测试结果可以看出非ssl 插入速度略快ssl(`3.5%`) + +#### 2.8.2 查询测试 + +使用session 的executeQueryStatement方法、循环100次查询不同设备的测点，测试3遍，查询完后修改ssl重启iotdb，三次查询使用不同的设备名字，测试环境：1c1d，mac 16G，Intel Core i5 + +**代码示例：** + +```Properties +private static void query(String d) throws IoTDBConnectionException, StatementExecutionException { + try (SessionDataSet dataSet = session.executeQueryStatement("select * from root.sg1.d9"+d)) { + System.out.println(dataSet.getColumnNames()); + dataSet.setFetchSize(1024); // default is 10000 + while (dataSet.hasNext()) { + System.out.println(dataSet.next()); + } + } +} +``` + +**查询测试结果:** + +| | ssl（单位ms） | 非ssl（单位ms） | +| ------ | ------------- | --------------- | +| 第一次 | 7101 | 6111 | +| 第二次 | 3109 | 2162 | +| 第三次 | 3594 | 3032 | + +**测试结论：** + +根据ssl 三次取平均值为4601ms、非ssl取平均值3768ms，综合测试结果可以看出非ssl 插入速度略快ssl（`22%`） \ No newline at end of file diff --git a/src/zh/UserGuide/latest/User-Manual/Data-Security.md b/src/zh/UserGuide/latest/User-Manual/Data-Security.md new file mode 100644 index 000000000..c34c439eb --- /dev/null +++ b/src/zh/UserGuide/latest/User-Manual/Data-Security.md @@ -0,0 +1,332 @@ + + +# 数据安全 + +## 1. 数据存储加密 +### 1.1 概述 + +IoTDB 通过内置的透明加密引擎支持对数据文件 TsFile 的加密防护。启用加密功能后，即可实现数据在写入时实时加密、读取时无缝解密的全流程自动化处理，保证落盘文件数据安全。该过程完全融入数据库内核，业务应用无感知且无需进行任何代码改造或查询逻辑调整。 + +### 1.2 参数配置 + +IoTDB 配置文件` ${IOTDB_HOME}/${IOTDB_CONF}/iotdb-system.properties`中数据加密相关的参数如下所示： + +| 参数 | 注释 | +| :----------------- | :----------------------------------------------------------- | +| `encrypt flag` | `true`为开启加密 | +| `encrypt_key_path` | 文件导入的主密钥文件路径 | +| `encrypt type` | 加密方式，例如"`org.apache.tsfile.encrypt.UNENCRYPTED`"。目前包括`AES128`和`UNENCRYPTED(SM4128)`。 | + +### 1.3 使用流程 + +1. 获取 加密算法 Jar 包 +2. 将 Jar 包放置于 IoTDB 部署路径下 lib 文件夹中，即 `${IOTDB_HOME}/lib` +3. 修改配置文件 ` ${IOTDB_HOME}/${IOTDB_CONF}/iotdb-system.properties` + +```Properties +encrypt_flag=true +encrypt_type=org.example.encrypt.AES128.AES128 +# encrypt_type=org.example.encrypt.SM4128.5M41283 +encrypt_key_path=...... +``` + +4. 启动 IoTDB 即可使用对应加密算法对 TsFile 文件进行加密。 + +### 1.4 注意事项 + +- 开启加密后，对合并功能无影响。但不支持系统内存在与配置不同的加密文件，以免触发合并时发生冲突。 +- 开启加密后禁用 Pipe。 +- 开启加密后禁用 Load TsFile。 +- 建议对主密钥文件路径进行一定的保护，例如存放在特定权限才能访问的磁盘上等。 + +## 2. 数据传输加密 + +### 2.1 概述 + +在某些客户的生产环境中，对于数据传输的安全性要求更高，希望有更安全的传输方式，因此扩展了 Datanode 的 Client RPC 以支持数据传输加密。以下是支持数据传输加密的方式： + +1. Thrift 除了普通模式与压缩模式外，增加 SSL 模式 +2. SessionPool(java) 与 Session(java) 支持使用 SSL 模式连接 +3. JDBC 支持使用 SSL 模式连接 +4. CLI 支持使用 SSL 模式连接 +5. 支持压缩模式 +6. 支持 RSA ECDSA 证书 + 1. RSA证书：算法为RSA，签名算法为SHA256withRSA + 2. ECDSA 证书：算法为EC，签名算法为SHA256withECDSA + +### 2.2 Server端配置 + +iotdb-datanode.properties 的默认配置，默认 ssl 是关闭状态。 + +#### 2.2.1 默认配置示例： + +```Properties +#iotdb-datanode.properties的默认配置 +....... +# is SSL enabled +#enable_thrift_ssl=false + +# SSL key store path +#key_store_path= + +# SSL key store password +#key_store_pwd= +....... +``` + +#### 2.2.2 启用 ssl 配置步骤： + +1. 在iotdb/conf/iotdb-datanode.properties 配置文件中找到enable_thrift_ssl 配置默认是false,修改成true +2. 修改key_store_path，添加生成的keystore路径 +3. 修改key_store_pwd为生成keystore的密码（秘钥库口令） +4. 启动iotdb服务 + +启用 ssl 配置后，需重启 iotdb 服务。同时，对应的使用到 dn_rpc_port 接口的客户端都需要使用 ssl 方式访问，否则不能访问。 + +```SQL +# is SSL enabled +enable_thrift_ssl=true + +# SSL key store path +key_store_path=/Users/keystore/.keystore + +# SSL key store password +key_store_pwd=123456 +``` + +### 2.3 Java SessionPool + +SessionPool 客户端配置ssl 需要配置useSSL、trustStore、trustStorePwd。 + +- useSSL ：是否开启ssl +- trustStore ：truststore的证书路径 +- trustStorePwd：truststore的证书密码（秘钥库口令） + +#### 2.3.1 代码示例： + +```SQL + sessionPool = + new SessionPool.Builder() + .nodeUrls(nodeUrls) +.user("root") +.password("root") +.maxSize(3) +.useSSL(true) +.trustStore("/Users/key/.truststore") + .trustStorePwd("123456") + .build(); +``` + +### 2.4 Java Session + +Session 客户端配置ssl 需要配置useSSL、trustStore、trustStorePwd 代码示例 + +- useSSL ：是否开启ssl +- trustStore ：truststore的证书路径 +- trustStorePwd：truststore的证书密码（秘钥库口令） + +#### 2.4.1 代码示例： + +```SQL +session = + new Session.Builder() + .host(LOCAL_HOST) + .port(6667) + .username("root") + .password("root") + .version(Version.V_1_0) + .useSSL(true) + .trustStore("/Users/key/.truststore") + .trustStorePwd("123456") + .build(); +``` + +### 2.5 JDBC + +jdbc 支持两种方式的ssl 配置，需要配置use_ssl、trust_store、trust_store_pwd。 + +- use_ssl:是否开启ssl 默认是false +- trust_store:truststore的证书路径 +- trust_store_pwd:truststore证书的密码（秘钥库口令） + +#### 2.5.1 代码示例： + +**方式一、在jdbc 的url 中配置使用** + +jdbc:iotdb://ip:port?use_ssl=true&trust_store_pwd=123456&trust_store=/Users/keystore/.truststore + +```SQL +try (Connection connection = + DriverManager.getConnection( + "jdbc:iotdb://127.0.0.1:6667?version=V_1_0&use_ssl=true&trust_store_pwd=123456&trust_store=/Users/keystore/.truststore", + "root", + "root");Statement statement = connection.createStatement(){ + // 代码逻辑 + + }catch (IoTDBSQLException e) { + logger.error("IoTDB Jdbc example error", e); + } +``` + +**方式二、使用Properties 来配置使用** + +```SQL +java.util.Properties info = new Properties(); +info.setProperty("use_ssl", "true"); +info.setProperty("user", "root"); +info.setProperty("password", "root"); +info.setProperty("trust_store", "/Users/keystore/.truststore"); +info.setProperty("trust_store_pwd","123456"); +try (Connection connection = + DriverManager.getConnection("jdbc:iotdb://127.0.0.1:6667?version=V_1_0", info); + Statement statement = connection.createStatement()) { + // 代码逻辑 + +}catch (IoTDBSQLException e) { + logger.error("IoTDB Jdbc example error", e); +} +``` + +### 2.6 CLI + +```SQL +./start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -usessl true -ts /Users/keystore/.truststore -tpw 123456 +``` + +### 2.7 SSL证书生成方式 + +需安装 JDK、测试jdk8和jdk11生成证书未发现问题 + +1. 创建私钥（.keystore） + +```SQL +keytool -genkeypair -alias mykey -keyalg RSA -validity 7 -keystore .keystore +``` + +2. 导出对应的证书 + +```SQL +keytool -export -alias mykey -keystore .keystore -rfc -file certificate.cer +``` + +3. 将该证书导入到客户端信任库（公钥：.truststore） + +```SQL +keytool -import -alias mykey -file certificate.cer -keystore .truststore +``` + +4. 创建 ECDSA 证书 + +提示:FIPS标准规定使用 RSA、ECDSA 或 EdDSA(23年刚支持) + +```Bash +keytool -genkeypair -alias mykey -keyalg EC -validity 7 -keystore aa.keystore + +keytool -export -alias mykey -keystore aa.keystore -rfc -file certificate.cer + +keytool -import -alias mykey -file certificate.cer -keystore aa.truststore +``` + +### 2.8 性能测试 + +#### 2.8.1 插入测试 + +使用session 的inserttablet方法，使用100 设备*100测点，每批 100 行 loop 100 次，测试3遍，三次插入使用不同的设备名字，测试环境：1c1d，mac 16G，Intel Core i5。 + +**代码示例：** + +```Properties +for(int i=0;i<100;i++){ + insertTablet(i+""); +} +private static void insertTablet(String d) throws IoTDBConnectionException, StatementExecutionException { + List schemaList = new ArrayList<>(); + for(int i=1;i<=100;i++){ + schemaList.add(new MeasurementSchema("s"+i, TSDataType.INT64)); + } + + Tablet tablet = new Tablet(ROOT_SG1_D1+d, schemaList, 100); + long timestamp = System.currentTimeMillis(); + + for (long row = 0; row < 100; row++) { + int rowIndex = tablet.rowSize++; + tablet.addTimestamp(rowIndex, timestamp); + for (int s = 0; s < 100; s++) { + long value = random.nextLong(); + tablet.addValue(schemaList.get(s).getMeasurementId(), rowIndex, value); + } + if (tablet.rowSize == tablet.getMaxRowNumber()) { + session.insertTablet(tablet, true); + tablet.reset(); + } + timestamp++; + } + + if (tablet.rowSize != 0) { + session.insertTablet(tablet); + tablet.reset(); + } + +} +``` + +**插入测试结果:** + +| | ssl（单位ms） | 非ssl（单位ms） | +| ------ | ------------- | --------------- | +| 第一次 | 13611 | 14099 | +| 第二次 | 11938 | 10236 | +| 第三次 | 13801 | 13663 | + +**测试结论：** + +根据ssl 三次取平均值为13117ms、非ssl取平均值12666ms，综合测试结果可以看出非ssl 插入速度略快ssl(`3.5%`) + +#### 2.8.2 查询测试 + +使用session 的executeQueryStatement方法、循环100次查询不同设备的测点，测试3遍，查询完后修改ssl重启iotdb，三次查询使用不同的设备名字，测试环境：1c1d，mac 16G，Intel Core i5 + +**代码示例：** + +```Properties +private static void query(String d) throws IoTDBConnectionException, StatementExecutionException { + try (SessionDataSet dataSet = session.executeQueryStatement("select * from root.sg1.d9"+d)) { + System.out.println(dataSet.getColumnNames()); + dataSet.setFetchSize(1024); // default is 10000 + while (dataSet.hasNext()) { + System.out.println(dataSet.next()); + } + } +} +``` + +**查询测试结果:** + +| | ssl（单位ms） | 非ssl（单位ms） | +| ------ | ------------- | --------------- | +| 第一次 | 7101 | 6111 | +| 第二次 | 3109 | 2162 | +| 第三次 | 3594 | 3032 | + +**测试结论：** + +根据ssl 三次取平均值为4601ms、非ssl取平均值3768ms，综合测试结果可以看出非ssl 插入速度略快ssl（`22%`） \ No newline at end of file