This is an automated email from the ASF dual-hosted git repository.
panjuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new d77e06f445b Update data encryption user manual api document (#19031)
d77e06f445b is described below
commit d77e06f445b7e2f7b9e67e11267617899e5aaacf
Author: Zhengqiang Duan <[email protected]>
AuthorDate: Mon Jul 11 19:37:40 2022 +0800
Update data encryption user manual api document (#19031)
---
.../spring-boot-starter/rules/encrypt.cn.md | 41 +++++++++++-
.../spring-boot-starter/rules/encrypt.en.md | 41 +++++++++++-
.../spring-namespace/rules/encrypt.cn.md | 78 +++++++++++++++++++++-
.../spring-namespace/rules/encrypt.en.md | 78 +++++++++++++++++++++-
.../yaml-config/rules/encrypt.cn.md | 57 +++++++++++++++-
.../yaml-config/rules/encrypt.en.md | 58 +++++++++++++++-
6 files changed, 347 insertions(+), 6 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.cn.md
index b73283d5a98..ed0a3174ced 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.cn.md
@@ -3,7 +3,11 @@ title = "数据加密"
weight = 4
+++
-## 配置项说明
+## 背景信息
+
+数据加密 Spring Boot Starter 配置方式适用于使用 SpringBoot 的业务场景，能够最大程度地利用 SringBoot 配置初始化及
Bean 管理的能力，完成 ShardingSphereDataSource 对象的创建，减少不必要的编码工作。
+
+## 参数解释
```properties
spring.shardingsphere.datasource.names= # 省略数据源配置，请参考使用手册
@@ -22,3 +26,38 @@ spring.shardingsphere.rules.encrypt.queryWithCipherColumn= #
是否使用加密
```
算法类型的详情，请参见[内置加密算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt)。
+
+## 操作步骤
+
+1. 在 SpringBoot 文件中配置数据加密规则，包含数据源、加密规则、全局属性等配置项；
+2. 启动 SpringBoot 程序，会自动加载配置，并初始化 ShardingSphereDataSource。
+
+## 配置示例
+
+```properties
+spring.shardingsphere.datasource.names=ds
+
+spring.shardingsphere.datasource.ds.type=com.zaxxer.hikari.HikariDataSource
+spring.shardingsphere.datasource.ds.driver-class-name=com.mysql.jdbc.Driver
+spring.shardingsphere.datasource.ds.jdbc-url=jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
+spring.shardingsphere.datasource.ds.username=root
+spring.shardingsphere.datasource.ds.password=
+
+spring.shardingsphere.rules.encrypt.encryptors.name-encryptor.type=AES
+spring.shardingsphere.rules.encrypt.encryptors.name-encryptor.props.aes-key-value=123456abc
+spring.shardingsphere.rules.encrypt.encryptors.pwd-encryptor.type=AES
+spring.shardingsphere.rules.encrypt.encryptors.pwd-encryptor.props.aes-key-value=123456abc
+
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.username.cipher-column=username
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.username.encryptor-name=name-encryptor
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.pwd.cipher-column=pwd
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.pwd.encryptor-name=pwd-encryptor
+
+spring.shardingsphere.props.query-with-cipher-column=true
+spring.shardingsphere.props.sql-show=true
+```
+
+## 相关参考
+
+- [数据加密核心特性](/cn/features/encrypt/)
+- [数据加密开发者指南](/cn/dev-manual/encryption/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.en.md
index 42a8594e2ed..606f8ad43e0 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-boot-starter/rules/encrypt.en.md
@@ -3,7 +3,11 @@ title = "Encryption"
weight = 4
+++
-## Configuration Item Explanation
+## Background
+
+The configuration method for Spring Boot Starter Data Encryption is suitable
for business scenarios using SpringBoot and can make the most of SringBoot's
configuration initialization and Bean management capabilities to complete the
creation of ShardingSphereDataSource objects, reducing unnecessary coding work.
+
+## Parameters
```properties
spring.shardingsphere.datasource.names= # Omit the data source configuration,
please refer to the usage
@@ -22,3 +26,38 @@ spring.shardingsphere.rules.encrypt.queryWithCipherColumn= #
Whether query with
```
Please refer to [Built-in Encrypt Algorithm
List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt) for more
details about type of algorithm.
+
+## Procedure
+
+1. Configure the data encryption rules in the SpringBoot file, including the
data source, encryption rules, global properties and other items.
+2. Start the SpringBoot program, which will automatically load the
configuration and initialize the ShardingSphereDataSource.
+
+## Sample
+
+```properties
+spring.shardingsphere.datasource.names=ds
+
+spring.shardingsphere.datasource.ds.type=com.zaxxer.hikari.HikariDataSource
+spring.shardingsphere.datasource.ds.driver-class-name=com.mysql.jdbc.Driver
+spring.shardingsphere.datasource.ds.jdbc-url=jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
+spring.shardingsphere.datasource.ds.username=root
+spring.shardingsphere.datasource.ds.password=
+
+spring.shardingsphere.rules.encrypt.encryptors.name-encryptor.type=AES
+spring.shardingsphere.rules.encrypt.encryptors.name-encryptor.props.aes-key-value=123456abc
+spring.shardingsphere.rules.encrypt.encryptors.pwd-encryptor.type=AES
+spring.shardingsphere.rules.encrypt.encryptors.pwd-encryptor.props.aes-key-value=123456abc
+
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.username.cipher-column=username
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.username.encryptor-name=name-encryptor
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.pwd.cipher-column=pwd
+spring.shardingsphere.rules.encrypt.tables.t_user.columns.pwd.encryptor-name=pwd-encryptor
+
+spring.shardingsphere.props.query-with-cipher-column=true
+spring.shardingsphere.props.sql-show=true
+```
+
+## Related References
+
+- [Core Features of Data Encryption](/en/features/encrypt/)
+- [Developer Guide of Data Encryption](/en/dev-manual/encryption/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.cn.md
index 9a7283ece11..6b41facde23 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.cn.md
@@ -3,7 +3,11 @@ title = "数据加密"
weight = 4
+++
-## 配置项说明
+## 背景信息
+
+数据加密 Spring 命名空间的配置方式，适用于传统的 Spring 项目，通过命名空间 xml 配置文件的方式配置分片规则和属性，由 Spring 完成
ShardingSphereDataSource 对象的创建和管理，避免额外的编码工作。
+
+## 参数解释
命名空间：[http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt-5.1.2.xsd)
@@ -42,3 +46,75 @@ weight = 4
| props (?) | 标签 | 加密算法属性配置 |
算法类型的详情，请参见[内置加密算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt)。
+
+## 操作步骤
+
+1. 在 Spring 命名空间配置文件中配置数据加密规则，包含数据源、加密规则、全局属性等配置项；
+2. 启动 Spring 程序，会自动加载配置，并初始化 ShardingSphereDataSource。
+
+## 配置示例
+
+```xml
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+
xmlns:shardingsphere="http://shardingsphere.apache.org/schema/shardingsphere/datasource";
+ xmlns:context="http://www.springframework.org/schema/context";
+ xmlns:tx="http://www.springframework.org/schema/tx";
+
xmlns:encrypt="http://shardingsphere.apache.org/schema/shardingsphere/encrypt";
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+
http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://www.springframework.org/schema/tx
+
http://www.springframework.org/schema/tx/spring-tx.xsd
+ http://www.springframework.org/schema/context
+
http://www.springframework.org/schema/context/spring-context.xsd
+
http://shardingsphere.apache.org/schema/shardingsphere/datasource
+
http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource.xsd
+
http://shardingsphere.apache.org/schema/shardingsphere/encrypt
+
http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt.xsd
+ ">
+ <context:component-scan
base-package="org.apache.shardingsphere.example.core.mybatis" />
+
+ <bean id="ds" class="com.zaxxer.hikari.HikariDataSource"
destroy-method="close">
+ <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
+ <property name="jdbcUrl"
value="jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8"/>
+ <property name="username" value="root"/>
+ <property name="password" value=""/>
+ </bean>
+
+ <encrypt:encrypt-algorithm id="name_encryptor" type="AES">
+ <props>
+ <prop key="aes-key-value">123456</prop>
+ </props>
+ </encrypt:encrypt-algorithm>
+ <encrypt:encrypt-algorithm id="pwd_encryptor" type="assistedTest" />
+
+ <encrypt:rule id="encryptRule">
+ <encrypt:table name="t_user">
+ <encrypt:column logic-column="username" cipher-column="username"
plain-column="username_plain" encrypt-algorithm-ref="name_encryptor" />
+ <encrypt:column logic-column="pwd" cipher-column="pwd"
assisted-query-column="assisted_query_pwd"
encrypt-algorithm-ref="pwd_encryptor" />
+ </encrypt:table>
+ </encrypt:rule>
+
+ <shardingsphere:data-source id="encryptDataSource" data-source-names="ds"
rule-refs="encryptRule" />
+
+ <bean id="transactionManager"
class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
+ <property name="dataSource" ref="encryptDataSource" />
+ </bean>
+ <tx:annotation-driven />
+
+ <bean id="sqlSessionFactory"
class="org.mybatis.spring.SqlSessionFactoryBean">
+ <property name="dataSource" ref="encryptDataSource"/>
+ <property name="mapperLocations"
value="classpath*:META-INF/mappers/*.xml"/>
+ </bean>
+
+ <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
+ <property name="basePackage"
value="org.apache.shardingsphere.example.core.mybatis.repository"/>
+ <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
+ </bean>
+</beans>
+```
+
+## 相关参考
+
+- [数据加密核心特性](/cn/features/encrypt/)
+- [数据加密开发者指南](/cn/dev-manual/encryption/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.en.md
index e78d4078a8e..d0ece0b8956 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/spring-namespace/rules/encrypt.en.md
@@ -3,7 +3,11 @@ title = "Encryption"
weight = 4
+++
-## Configuration Item Explanation
+## Background
+
+Spring Namespace's data encryption configuration applies to the traditional
Spring projects. Sharding rules and attributes are configured through the XML
configuration file of the namespace. Spring creates and manages the
ShardingSphereDataSource object, reducing unnecessary coding.
+
+## Parameters
Namespace:
[http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt-5.1.2.xsd](http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt-5.1.2.xsd)
@@ -42,3 +46,75 @@ Namespace:
[http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encry
| props (?) | Tag | Encrypt algorithm properties |
Please refer to [Built-in Encrypt Algorithm
List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt) for more
details about type of algorithm.
+
+## Procedure
+
+1. Configure data encryption rules in the Spring namespace configuration file,
including data sources, encryption rules, and global attributes.
+2. Start the Spring program, and it will automatically load the configuration
and initialize the ShardingSphereDataSource.
+
+## Sample
+
+```xml
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+
xmlns:shardingsphere="http://shardingsphere.apache.org/schema/shardingsphere/datasource";
+ xmlns:context="http://www.springframework.org/schema/context";
+ xmlns:tx="http://www.springframework.org/schema/tx";
+
xmlns:encrypt="http://shardingsphere.apache.org/schema/shardingsphere/encrypt";
+ xsi:schemaLocation="http://www.springframework.org/schema/beans
+
http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://www.springframework.org/schema/tx
+
http://www.springframework.org/schema/tx/spring-tx.xsd
+ http://www.springframework.org/schema/context
+
http://www.springframework.org/schema/context/spring-context.xsd
+
http://shardingsphere.apache.org/schema/shardingsphere/datasource
+
http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource.xsd
+
http://shardingsphere.apache.org/schema/shardingsphere/encrypt
+
http://shardingsphere.apache.org/schema/shardingsphere/encrypt/encrypt.xsd
+ ">
+ <context:component-scan
base-package="org.apache.shardingsphere.example.core.mybatis" />
+
+ <bean id="ds" class="com.zaxxer.hikari.HikariDataSource"
destroy-method="close">
+ <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
+ <property name="jdbcUrl"
value="jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8"/>
+ <property name="username" value="root"/>
+ <property name="password" value=""/>
+ </bean>
+
+ <encrypt:encrypt-algorithm id="name_encryptor" type="AES">
+ <props>
+ <prop key="aes-key-value">123456</prop>
+ </props>
+ </encrypt:encrypt-algorithm>
+ <encrypt:encrypt-algorithm id="pwd_encryptor" type="assistedTest" />
+
+ <encrypt:rule id="encryptRule">
+ <encrypt:table name="t_user">
+ <encrypt:column logic-column="username" cipher-column="username"
plain-column="username_plain" encrypt-algorithm-ref="name_encryptor" />
+ <encrypt:column logic-column="pwd" cipher-column="pwd"
assisted-query-column="assisted_query_pwd"
encrypt-algorithm-ref="pwd_encryptor" />
+ </encrypt:table>
+ </encrypt:rule>
+
+ <shardingsphere:data-source id="encryptDataSource" data-source-names="ds"
rule-refs="encryptRule" />
+
+ <bean id="transactionManager"
class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
+ <property name="dataSource" ref="encryptDataSource" />
+ </bean>
+ <tx:annotation-driven />
+
+ <bean id="sqlSessionFactory"
class="org.mybatis.spring.SqlSessionFactoryBean">
+ <property name="dataSource" ref="encryptDataSource"/>
+ <property name="mapperLocations"
value="classpath*:META-INF/mappers/*.xml"/>
+ </bean>
+
+ <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
+ <property name="basePackage"
value="org.apache.shardingsphere.example.core.mybatis.repository"/>
+ <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
+ </bean>
+</beans>
+```
+
+## Related References
+
+- [Core Features of Data Encryption](/en/features/encrypt/)
+- [Developer Guide of Data Encryption](/en/dev-manual/encryption/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.cn.md
index 13d94e07367..6ab7fcc4f69 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.cn.md
@@ -3,7 +3,11 @@ title = "数据加密"
weight = 5
+++
-## 配置项说明
+## 背景信息
+
+数据加密 YAML 配置方式具有非凡的可读性，通过 YAML 格式，能够快速地理解加密规则之间的依赖关系，ShardingSphere 会根据 YAML
配置，自动完成 ShardingSphereDataSource 对象的创建，减少用户不必要的编码工作。
+
+## 参数解释
```yaml
rules:
@@ -29,3 +33,54 @@ rules:
```
算法类型的详情，请参见[内置加密算法列表](/cn/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt)。
+
+## 操作步骤
+
+1. 在 YAML 文件中配置数据加密规则，包含数据源、加密规则、全局属性等配置项；
+2. 调用 YamlShardingSphereDataSourceFactory 对象的 createDataSource 方法，根据 YAML
文件中的配置信息创建 ShardingSphereDataSource。
+
+## 配置示例
+
+数据加密 YAML 配置如下：
+
+```yaml
+dataSources:
+ unique_ds:
+ dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+ driverClassName: com.mysql.jdbc.Driver
+ jdbcUrl:
jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
+ username: root
+ password:
+
+rules:
+- !ENCRYPT
+ tables:
+ t_user:
+ columns:
+ username:
+ plainColumn: username_plain
+ cipherColumn: username
+ encryptorName: name-encryptor
+ pwd:
+ cipherColumn: pwd
+ assistedQueryColumn: assisted_query_pwd
+ encryptorName: pwd_encryptor
+ encryptors:
+ name-encryptor:
+ type: AES
+ props:
+ aes-key-value: 123456abc
+ pwd_encryptor:
+ type: assistedTest
+```
+
+然后通过 YamlShardingSphereDataSourceFactory 的 createDataSource 方法创建数据源。
+
+```java
+YamlShardingSphereDataSourceFactory.createDataSource(getFile());
+```
+
+## 相关参考
+
+- [数据加密核心特性](/cn/features/encrypt/)
+- [数据加密开发者指南](/cn/dev-manual/encryption/)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.en.md
index 1855963d78f..8e26d7c751e 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/rules/encrypt.en.md
@@ -3,7 +3,12 @@ title = "Encryption"
weight = 5
+++
-## Configuration Item Explanation
+## Background
+
+The YAML configuration approach to data encryption is highly readable, with
the YAML format enabling a quick understanding of dependencies between
encryption rules.
+Based on the YAML configuration, ShardingSphere automatically completes the
creation of ShardingSphereDataSource objects, reducing unnecessary coding
efforts for users.
+
+## Parameters
```yaml
rules:
@@ -29,3 +34,54 @@ rules:
```
Please refer to [Built-in Encrypt Algorithm
List](/en/user-manual/shardingsphere-jdbc/builtin-algorithm/encrypt) for more
details about type of algorithm.
+
+## Procedure
+
+1. Configure data encryption rules in the YAML file, including data sources,
encryption rules, global attributes, and other configuration items.
+2. Using the createDataSource of calling the
YamlShardingSphereDataSourceFactory object to create ShardingSphereDataSource
based on the configuration information in the YAML file.
+
+## Sample
+
+The data encryption YAML configurations are as follows:
+
+```yaml
+dataSources:
+ unique_ds:
+ dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+ driverClassName: com.mysql.jdbc.Driver
+ jdbcUrl:
jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
+ username: root
+ password:
+
+rules:
+- !ENCRYPT
+ tables:
+ t_user:
+ columns:
+ username:
+ plainColumn: username_plain
+ cipherColumn: username
+ encryptorName: name-encryptor
+ pwd:
+ cipherColumn: pwd
+ assistedQueryColumn: assisted_query_pwd
+ encryptorName: pwd_encryptor
+ encryptors:
+ name-encryptor:
+ type: AES
+ props:
+ aes-key-value: 123456abc
+ pwd_encryptor:
+ type: assistedTest
+```
+
+Read the YAML configuration to create a data source according to the
createDataSource method of YamlShardingSphereDataSourceFactory.
+
+```java
+YamlShardingSphereDataSourceFactory.createDataSource(getFile());
+```
+
+## Related References
+
+- [Core Features of Data Encryption](/en/features/encrypt/)
+- [Developer Guide of Data Encryption](/en/dev-manual/encryption/)
\ No newline at end of file
