Encryption

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

  1. rules:
  2. - !ENCRYPT
  3.   tables:
  4.     <table_name> (+): # Encrypt table name
  5.       columns:
  6.         <column_name> (+): # Encrypt logic column name
  7.           cipher:
  8.             name: # Cipher column name
  9.             encryptorName: # Cipher encrypt algorithm name
  10.           assistedQuery (?):
  11.             name: # Assisted query column name
  12.             encryptorName:  # Assisted query encrypt algorithm name
  13.           likeQuery (?):
  14.             name: # Like query column name
  15.             encryptorName:  # Like query encrypt algorithm name 
  17.   # Encrypt algorithm configuration
  18.   encryptors:
  19.     <encrypt_algorithm_name> (+): # Encrypt algorithm name
  20.       type: # Encrypt algorithm type
  21.       props: # Encrypt algorithm properties
  22.         # ...

Please refer to Built-in Encrypt Algorithm List 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:

  1. dataSources:
  2.   unique_ds:
  3.     dataSourceClassName: com.zaxxer.hikari.HikariDataSource
  4.     driverClassName: com.mysql.jdbc.Driver
  5.     jdbcUrl: jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
  6.     username: root
  7.     password:
  9. rules:
  10. - !ENCRYPT
  11.   tables:
  12.     t_user:
  13.       columns:
  14.         username:
  15.           cipher:
  16.             name: username
  17.             encryptorName: aes_encryptor
  18.           assistedQuery:
  19.             name: assisted_query_username
  20.             encryptorName: assisted_encryptor
  21.           likeQuery:
  22.             name: like_query_username
  23.             encryptorName: like_encryptor
  24.         pwd:
  25.           cipher:
  26.             name: pwd
  27.             encryptorName: aes_encryptor
  28.           assistedQuery:
  29.             name: assisted_query_pwd
  30.             encryptorName: assisted_encryptor
  31.   encryptors:
  32.     aes_encryptor:
  33.       type: AES
  34.       props:
  35.         aes-key-value: 123456abc
  36.     assisted_encryptor:
  37.       type: MD5
  38.     like_encryptor:
  39.       type: CHAR_DIGEST_LIKE

Read the YAML configuration to create a data source according to the createDataSource method of YamlShardingSphereDataSourceFactory.

  1. YamlShardingSphereDataSourceFactory.createDataSource(getFile());

In order to keep compatibility with earlier YAML configuration, ShardingSphere provides following compatible configuration through ‘COMPATIBLE_ENCRYPT’, which will be removed in future versions, and it is recommended to upgrade latest YAML configuration.

  1. dataSources:
  2.   unique_ds:
  3.     dataSourceClassName: com.zaxxer.hikari.HikariDataSource
  4.     driverClassName: com.mysql.jdbc.Driver
  5.     jdbcUrl: jdbc:mysql://localhost:3306/demo_ds?serverTimezone=UTC&useSSL=false&useUnicode=true&characterEncoding=UTF-8
  6.     username: root
  7.     password:
  9. rules:
  10. - !COMPATIBLE_ENCRYPT
  11.   tables:
  12.     t_user:
  13.       columns:
  14.         username:
  15.           cipherColumn: username
  16.           encryptorName: aes_encryptor
  17.           assistedQueryColumn: assisted_query_username
  18.           assistedQueryEncryptorName: assisted_encryptor
  19.           likeQueryColumn: like_query_username
  20.           likeQueryEncryptorName: like_encryptor
  21.         pwd:
  22.           cipherColumn: pwd
  23.           encryptorName: aes_encryptor
  24.           assistedQueryColumn: assisted_query_pwd
  25.           assistedQueryEncryptorName: assisted_encryptor
  26.   encryptors:
  27.     aes_encryptor:
  28.       type: AES
  29.       props:
  30.         aes-key-value: 123456abc
  31.     assisted_encryptor:
  32.       type: MD5
  33.     like_encryptor:
  34.       type: CHAR_DIGEST_LIKE