Secure Your Data with ShardingSphere: Quick Start Guide for Spring Encryption

Background

Many production systems store personally identifiable information (e.g., ID numbers, bank cards, names, phone numbers). Compliance regulations require that such data be persisted in encrypted form.

Pain Points

Developers often embed encryption/decryption calls directly in SQL statements, which tightly couples business logic with security concerns and makes the code hard to maintain.

Legacy applications that were launched without encryption need a migration path that adds encrypted columns, migrates existing data, and adds compatibility code—an error‑prone and time‑consuming process.

ShardingSphere Data Encryption Module

Apache ShardingSphere provides a transparent encryption layer. It parses incoming SQL, rewrites column references according to a user‑defined encryption rule, and automatically encrypts values on INSERT/UPDATE and decrypts them on SELECT. This removes the need for manual cryptographic code in the application.

Quick Start – Spring XML Namespace Configuration

1. Maven Dependency

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-spring-namespace</artifactId>
    <version>${sharding-sphere.version}</version>
</dependency>

2. Build EncryptRuleConfiguration

Create a configuration object before the data source is instantiated. The example below defines an AES encryptor and configures three columns in the card_info table and one column in the pay_order table.

private EncryptRuleConfiguration getEncryptRuleConfiguration() {
    Properties props = new Properties();
    // AES requires a secret key
    props.setProperty("aes.key.value", aesKey);
    EncryptorRuleConfiguration aesEncryptor = new EncryptorRuleConfiguration("AES", props);

    EncryptRuleConfiguration ruleConfig = new EncryptRuleConfiguration();
    ruleConfig.getEncryptors().put("aes", aesEncryptor);

    // ----- card_info table -----
    Map<String, EncryptColumnRuleConfiguration> cardInfoCols = new HashMap<>();
    cardInfoCols.put("name", new EncryptColumnRuleConfiguration("", "name", "", "aes"));
    cardInfoCols.put("id_no", new EncryptColumnRuleConfiguration("", "id_no", "", "aes"));
    cardInfoCols.put("finshell_card_no", new EncryptColumnRuleConfiguration("", "finshell_card_no", "", "aes"));
    ruleConfig.getTables().put("card_info", new EncryptTableRuleConfiguration(cardInfoCols));

    // ----- pay_order table -----
    Map<String, EncryptColumnRuleConfiguration> payOrderCols = new HashMap<>();
    payOrderCols.put("card_no", new EncryptColumnRuleConfiguration("", "card_no", "", "aes"));
    ruleConfig.getTables().put("pay_order", new EncryptTableRuleConfiguration(payOrderCols));

    return ruleConfig;
}

Explanation EncryptColumnRuleConfiguration takes four arguments: plainColumn, cipherColumn, a placeholder (reserved for future use), and the encryptor name. For new applications only the cipher column is needed, so plainColumn is left empty. EncryptTableRuleConfiguration receives a map that links a logical column name (the name used in SQL) to its column rule. ShardingSphere rewrites SQL so that the logical column is mapped to the cipher column during write operations and to the plain column during read operations.

3. Wrap the Original DataSource

@Bean("tradePlatformDataSource")
public DataSource dataSource(@Qualifier("druidDataSource") DataSource ds) throws SQLException {
    return EncryptDataSourceFactory.createDataSource(ds, getEncryptRuleConfiguration(), new Properties());
}

Quick Start – Spring Boot Configuration

1. Maven Dependencies

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-spring-boot-starter</artifactId>
    <version>${sharding-sphere.version}</version>
</dependency>

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-spring-namespace</artifactId>
    <version>${sharding-sphere.version}</version>
</dependency>

2. application.properties Configuration

# ----------------------------------------------------------------
# DataSource definition (replace host, port, db, user, password)
# ----------------------------------------------------------------
spring.shardingsphere.datasource.name=ds
spring.shardingsphere.datasource.ds.type=com.alibaba.druid.pool.DruidDataSource
spring.shardingsphere.datasource.ds.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds.url=jdbc:mysql://host:port/db
spring.shardingsphere.datasource.ds.username=root
spring.shardingsphere.datasource.ds.password=secret

# ----------------------------------------------------------------
# AES encryptor definition (the same key must be used for encryption/decryption)
# ----------------------------------------------------------------
spring.shardingsphere.encrypt.encryptors.encryptor_aes.type=aes
spring.shardingsphere.encrypt.encryptors.encryptor_aes.props.aes.key.value=YOUR_AES_KEY_HERE

# ----------------------------------------------------------------
# Table‑level encryption rules
# ----------------------------------------------------------------
# card_info table
spring.shardingsphere.encrypt.tables.card_info.columns.name.cipherColumn=name
spring.shardingsphere.encrypt.tables.card_info.columns.name.encryptor=encryptor_aes
spring.shardingsphere.encrypt.tables.card_info.columns.id_no.cipherColumn=id_no
spring.shardingsphere.encrypt.tables.card_info.columns.id_no.encryptor=encryptor_aes
spring.shardingsphere.encrypt.tables.card_info.columns.finshell_card_no.cipherColumn=finshell_card_no
spring.shardingsphere.encrypt.tables.card_info.columns.finshell_card_no.encryptor=encryptor_aes

# pay_order table
spring.shardingsphere.encrypt.tables.pay_order.columns.card_no.cipherColumn=card_no
spring.shardingsphere.encrypt.tables.pay_order.columns.card_no.encryptor=encryptor_aes

With the above configuration ShardingSphere automatically encrypts the specified columns when data is written and decrypts them when queried, allowing the application code to work with clear‑text values while the database stores only ciphertext.