Seven Data Security

Seven Data Security is a comprehensive Spring Boot library for MyBatis that provides transparent data encryption, desensitization, and fine-grained data scope control for enterprise applications. It seamlessly integrates with MyBatis/MyBatis-Plus to automatically handle sensitive data protection without modifying business logic.

✨ Features

🔐 Automatic Data Encryption

Transparent encryption/decryption via annotations
Multiple encryption algorithms support (DES, AES, custom algorithms)
Zero business logic impact - encryption handled by interceptors
Type-safe Encrypt wrapper type for explicit encryption

🔍 Query Parameter Encryption

Automatic parameter detection and encryption
Support for multiple parameter types: Map, Object, MyBatis-Plus QueryWrapper
Smart field matching with camelCase and snake_case conversion
Thread-safe parameter restoration after SQL execution

🎯 Data Scope Control

Row-level data filtering based on user permissions
Flexible strategy pattern for custom access rules
SQL rewriting with JOIN and WHERE conditions
Multi-tenant support for SaaS applications

📊 Development Tools

SQL statement printing with actual parameter values
Execution time tracking for performance monitoring
Environment-aware (disabled in production)

🔄 SQL Processing

Single table query optimization with automatic table prefix
SQL rewriting for data scope injection
Smart column detection and processing

🏗️ Enterprise-Grade Design

Thread-safe operations with ThreadLocal context
Lazy initialization with caching for performance
Spring Boot auto-configuration
Extensible architecture via interfaces and abstract classes

🏛️ Architecture

seven-data-security
├── config                  # Auto-configuration classes
│   ├── JacksonConfig              # JSON serialization config
│   ├── MaskAutoConfig             # Main auto-config
│   └── MyBatisInterceptorAutoConfig  # MyBatis interceptors setup
├── domain                  # Core domain models
│   ├── AnnotatedField             # Field annotation metadata
│   ├── Encrypt                    # Encryption wrapper type
│   ├── EncryptInfo                # Parameter encryption context
│   └── RestoreInfo                # Parameter restoration context
├── encrypt                 # Encryption subsystem
│   ├── annotation                 # @EncryptField annotation
│   ├── container                  # Algorithm and metadata containers
│   ├── context                    # Encryption context management
│   ├── jackson                    # JSON serialization support
│   ├── processor                  # Encryption/decryption processors
│   │   ├── DecryptProcessor       # Result decryption
│   │   ├── EncryptProcessor       # Parameter encryption
│   │   └── SingleSelectProcessor  # Single table SELECT optimization
│   ├── shield                     # Encryption algorithm implementations
│   └── type/handler               # MyBatis type handler
├── interceptor             # MyBatis interceptors
│   ├── DecryptInterceptor         # Result decryption
│   ├── SqlPrintInterceptor        # SQL logging
│   └── SqlRewriteInterceptor      # Parameter encryption & data scope
├── kit                     # Utility classes
│   ├── ClazzUtil                  # Reflection utilities
│   ├── FieldMatchUtil             # Field matching logic
│   ├── ParamUtil                  # Parameter processing
│   ├── SpringContextUtil          # Spring context access
│   ├── SqlPrint                   # SQL formatting
│   └── StringUtil                 # String operations
├── scope                   # Data scope subsystem
│   ├── DataScopeHelper            # Scope context management
│   ├── DataScopeStrategy          # Strategy interface
│   ├── EmptyDataScopeStrategy     # Empty strategy implementation
│   ├── container                  # Strategy container
│   └── processor                  # SQL rewriting processor
└── exception               # Exception hierarchy
    ├── DataSecurityException      # Base exception
    └── JacksonException           # JSON-related exception

🚀 Quick Start

1. Add Dependency

Maven:

<dependency>
    <groupId>io.github.qwzhang01</groupId>
    <artifactId>seven-data-security</artifactId>
    <version>1.2.21</version>
</dependency>

Gradle:

implementation 'io.github.qwzhang01:seven-data-security:1.2.21'

2. Define Entity with Encryption

@Data
@TableName("user")
public class User {
    @TableId
    private Long id;
    
    private String username;
    
    // Automatically encrypted/decrypted
    @EncryptField
    private String phoneNumber;
    
    @EncryptField
    private String email;
    
    // Custom encryption algorithm
    @EncryptField(CustomAesAlgo.class)
    private String socialSecurityNumber;
}

3. Use in Service

@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    
    // Data is automatically encrypted before insert
    public void createUser(User user) {
        userMapper.insert(user);
    }
    
    // Data is automatically decrypted after query
    public User getUser(Long id) {
        return userMapper.selectById(id);
    }
    
    // Query parameters are automatically encrypted
    public List<User> findByPhone(String phone) {
        return userMapper.selectList(
            new QueryWrapper<User>().eq("phone_number", phone)
        );
    }
}

That's it! No additional code changes are required. The library automatically handles encryption and decryption.

🔑 Core Functionality

Field Encryption

Using @EncryptField Annotation

@Data
@TableName("customer")
public class Customer {
    @TableId
    private Long id;
    
    // Use default encryption algorithm
    @EncryptField
    private String phoneNumber;
    
    // Specify custom encryption algorithm
    @EncryptField(AesEncryptionAlgo.class)
    private String creditCard;
    
    private String name;
}

Using Encrypt Type Wrapper

@Data
@TableName("sensitive_data")
public class SensitiveData {
    @TableId
    private Long id;
    
    // Type-safe encryption wrapper
    private Encrypt secretData;
    
    // Getter returns plain text
    public String getSecretData() {
        return secretData.getValue();
    }
    
    // Setter accepts plain text
    public void setSecretData(String value) {
        this.secretData = new Encrypt(value);
    }
}

Custom Encryption Algorithm

public class AesEncryptionAlgo implements EncryptionAlgo {
    private static final String KEY = "YourSecretKey123"; // Use environment variable in production
    
    @Override
    public String encrypt(String value) {
        if (value == null) return null;
        // Implement AES encryption
        return AesUtils.encrypt(value, KEY);
    }
    
    @Override
    public String decrypt(String value) {
        if (value == null) return null;
        // Implement AES decryption
        return AesUtils.decrypt(value, KEY);
    }
}

Register Custom Algorithm

@Configuration
public class SecurityConfig {
    
    @Bean
    public AesEncryptionAlgo aesEncryptionAlgo() {
        return new AesEncryptionAlgo();
    }
}

Query Parameter Encryption

The library automatically encrypts query parameters that match encrypted fields:

// All these queries automatically encrypt the phone parameter
public class UserService {
    
    // Map parameters
    public List<User> findByPhone(String phone) {
        Map<String, Object> params = new HashMap<>();
        params.put("phoneNumber", phone);
        return userMapper.selectByMap(params);
    }
    
    // Object parameters
    public List<User> findUsers(UserQuery query) {
        return userMapper.selectList(query); // query.phoneNumber is auto-encrypted
    }
    
    // QueryWrapper parameters (MyBatis-Plus)
    public List<User> findWithWrapper(String phone) {
        return userMapper.selectList(
            new QueryWrapper<User>().eq("phone_number", phone) // auto-encrypted
        );
    }
    
    // XML Mapper parameters
    public List<User> findInXml(String phone) {
        return userMapper.findByPhone(phone); // auto-encrypted
    }
}

XML Mapper Example:

<select id="findByPhone" resultType="User">
    SELECT * FROM user WHERE phone_number = #{phoneNumber}
    <!-- phoneNumber is automatically encrypted before execution -->
</select>

Single Table Query Processing

The library automatically adds table prefix to columns in single-table SELECT queries, which helps prevent column name conflicts when used with data scope SQL rewriting:

// Original query
String sql = "SELECT id, name FROM user WHERE status = 1";

// After processing
String processedSql = "SELECT user.id, user.name FROM user WHERE user.status = 1";

Features:

✅ Automatically detects single-table SELECT queries
✅ Adds table prefix to SELECT columns, WHERE conditions, ORDER BY, GROUP BY, HAVING
✅ Handles SELECT * → SELECT table.* conversion
✅ Respects table aliases
✅ Skips queries with JOIN clauses (not single-table)

Use Cases:

Prevent ambiguous column names when data scope adds JOIN clauses
Improve SQL compatibility with complex query rewrites
Ensure consistent column references across different query types

Data Scope Control

Implement fine-grained data access control based on user permissions:

1. Define Data Scope Strategy

@Component
public class DepartmentDataScopeStrategy implements DataScopeStrategy<Long> {
    
    @Autowired
    private UserContext userContext;
    
    @Override
    public String join() {
        // Add JOIN clause if needed
        return "LEFT JOIN department d ON t.dept_id = d.id";
    }
    
    @Override
    public String where() {
        // Add WHERE clause for permission filtering
        List<Long> deptIds = userContext.getUserDepartmentIds();
        return "d.id IN (" + StringUtils.join(deptIds, ",") + ")";
    }
    
    @Override
    public void validDs(List<Long> validRights) {
        // Validate permissions for INSERT/UPDATE/DELETE
        Long currentDeptId = userContext.getCurrentDepartmentId();
        if (!validRights.contains(currentDeptId)) {
            throw new PermissionDeniedException("No permission for this department");
        }
    }
    
    @Override
    public void validDs(List<Long> validRights, List<Long> withoutRights) {
        // Whitelist support: if in whitelist, skip validation
        Long currentDeptId = userContext.getCurrentDepartmentId();
        if (withoutRights.contains(currentDeptId)) {
            return;
        }
        validDs(validRights);
    }
}

2. Apply Data Scope to Query

@Service
public class EmployeeService {
    
    @Autowired
    private EmployeeMapper employeeMapper;
    
    // Apply department-level data scope
    public List<Employee> getEmployees() {
        return DataScopeHelper
            .strategy(DepartmentDataScopeStrategy.class)
            .setSearchRight(getCurrentUserDeptIds())
            .execute(() -> employeeMapper.selectAll());
    }
    
    // Apply with validation for update
    public void updateEmployee(Employee employee) {
        DataScopeHelper
            .strategy(DepartmentDataScopeStrategy.class)
            .setValidRights(employee.getDeptId())
            .execute(() -> {
                employeeMapper.updateById(employee);
                return null;
            });
    }
    
    // Complex scenario with whitelist
    public void updateWithWhitelist(Employee employee) {
        List<Long> adminDepts = getAdminDepartments();
        DataScopeHelper
            .strategy(DepartmentDataScopeStrategy.class)
            .setValidRights(employee.getDeptId())
            .setWithoutRights(adminDepts) // Admin depts bypass validation
            .execute(() -> {
                employeeMapper.updateById(employee);
                return null;
            });
    }
}

Before Data Scope:

SELECT * FROM employee

After Data Scope Applied:

SELECT * FROM employee t 
LEFT JOIN department d ON t.dept_id = d.id
WHERE d.id IN (10, 20, 30)

SQL Printing

The library includes a powerful SQL printing feature for debugging:

# application-dev.yml (automatically enabled in non-prod environments)
spring:
  profiles:
    active: dev

Console Output:

=== SQL Execution ===
Method: com.example.mapper.UserMapper.selectById
SQL: SELECT * FROM user WHERE id = 1 AND phone_number = '_sensitive_start_EnCrYpTeD123='
Time: 15 ms
Returned: 1 rows

Features:

✅ Shows actual parameter values (not placeholders)
✅ Displays execution time
✅ Shows affected/returned row counts
✅ Automatically disabled in production (profile containing "prod")

⚙️ Configuration

Default Configuration

The library works out of the box with zero configuration. Default settings:

# These are implicit defaults, no need to configure
seven:
  data-security:
    encryption:
      algorithm: DES  # Default encryption algorithm
      key: "key12345678"  # Default key (change in production!)
    sql-print:
      enabled: true  # Enabled in non-production environments

Custom Configuration

Application Properties

spring:
  profiles:
    active: dev
  
# Custom encryption settings
seven:
  data-security:
    encryption:
      enabled: true
      algorithm: AES

Override Default Encryption Algorithm

@Configuration
public class EncryptionConfig {
    
    @Bean
    @Primary  // Make this the default algorithm
    public EncryptionAlgo defaultEncryptionAlgo() {
        return new MyCustomEncryptionAlgo();
    }
}

Disable SQL Printing

@Configuration
public class SqlPrintConfig {
    
    @Bean
    @ConditionalOnProperty(name = "sql.print.enabled", havingValue = "false")
    public ConfigurationCustomizer disableSqlPrint() {
        return configuration -> {
            // SQL printing will not be configured
        };
    }
}

🎓 Advanced Usage

Nested Object Encryption

@Data
public class Order {
    @TableId
    private Long id;
    
    // Nested object encryption
    private Customer customer;
    
    @Data
    public static class Customer {
        @EncryptField
        private String phone;
        
        @EncryptField
        private String email;
        
        private Address address;
        
        @Data
        public static class Address {
            @EncryptField
            private String street;
            
            private String city;
        }
    }
}

Collection Field Encryption

@Data
public class Company {
    @TableId
    private Long id;
    
    // List of encrypted fields
    private List<Employee> employees;
    
    @Data
    public static class Employee {
        @EncryptField
        private String socialSecurityNumber;
        
        private String name;
    }
}

Multi-Level Data Scope

// Combine multiple data scope strategies
public List<Document> getDocuments() {
    return DataScopeHelper
        .strategy(DepartmentDataScopeStrategy.class)
        .setSearchRight(userDeptIds)
        .execute(() -> 
            DataScopeHelper
                .strategy(ProjectDataScopeStrategy.class)
                .setSearchRight(userProjectIds)
                .execute(() -> documentMapper.selectAll())
        );
}

JSON Serialization

The library automatically handles Encrypt type serialization:

@RestController
public class UserController {
    
    @GetMapping("/user/{id}")
    public User getUser(@PathVariable Long id) {
        // Encrypt type fields are automatically serialized as plain strings
        return userService.getById(id);
    }
}

JSON Output:

{
  "id": 1,
  "username": "john",
  "phoneNumber": "13800138000",
  "email": "john@example.com"
}

🎨 Design Patterns

1. Strategy Pattern

EncryptionAlgo interface for pluggable encryption algorithms
DataScopeStrategy interface for customizable access control rules

2. Factory Pattern

AbstractEncryptAlgoContainer for algorithm instance creation and caching
Lazy initialization with Spring bean integration

3. Template Method Pattern

AbstractEncryptAlgoContainer provides template for algorithm resolution
Subclasses implement specific default algorithm logic

4. Singleton Pattern

DecryptProcessor and EncryptProcessor use Holder pattern for thread-safe singletons
SqlPrint utility uses inner Holder class

5. Interceptor Pattern

MyBatis Plugin mechanism for transparent encryption/decryption
Chain of responsibility for multiple interceptors

6. Observer Pattern

ObjectMapperEnhancer listens to ContextRefreshedEvent for Jackson configuration

7. Flyweight Pattern

Field metadata caching in ClazzUtil reduces reflection overhead
Algorithm instance caching in containers

⚡ Performance Considerations

Caching Mechanisms

Reflection Cache: Field metadata cached in ConcurrentHashMap
Algorithm Cache: Encryption algorithm instances cached
Table Metadata Cache: MyBatis-Plus table info cached

Optimization Tips

// ✅ Good: Use @EncryptField for automatic encryption
@EncryptField
private String phoneNumber;

// ❌ Avoid: Manual encryption in business logic
private String phoneNumber;
public void setPhoneNumber(String phone) {
    this.phoneNumber = encryptionService.encrypt(phone); // Not recommended
}

// ✅ Good: Batch operations are efficiently handled
userMapper.insertBatch(users); // Encryption happens in single intercept call

// ✅ Good: QueryWrapper parameters are optimized
new QueryWrapper<User>().in("phone_number", phoneList); // Batch encryption

// ⚠️ Note: Disable encryption for non-sensitive fields
private String publicInfo; // No @EncryptField = No overhead

Performance Metrics

Encryption Overhead: ~1-2ms per field (DES algorithm)
Reflection Overhead: Negligible after first access (cached)
SQL Rewrite Overhead: < 1ms for data scope application

🧪 Testing

Unit Test Example

@SpringBootTest
class UserServiceTest {
    
    @Autowired
    private UserService userService;
    
    @Autowired
    private UserMapper userMapper;
    
    @Test
    void testEncryption() {
        // Create user with sensitive data
        User user = new User();
        user.setUsername("test");
        user.setPhoneNumber("13800138000");
        
        // Save user (encryption happens automatically)
        userService.createUser(user);
        
        // Query directly from database to verify encryption
        User dbUser = userMapper.selectById(user.getId());
        
        // Phone number should be decrypted automatically
        assertEquals("13800138000", dbUser.getPhoneNumber());
        
        // Verify data is encrypted in database
        String encryptedPhone = jdbcTemplate.queryForObject(
            "SELECT phone_number FROM user WHERE id = ?", 
            String.class, 
            user.getId()
        );
        assertTrue(encryptedPhone.startsWith("_sensitive_start_"));
    }
    
    @Test
    void testDataScope() {
        // Set up data scope context
        List<Employee> employees = DataScopeHelper
            .strategy(DepartmentDataScopeStrategy.class)
            .setSearchRight(Arrays.asList(10L, 20L))
            .execute(() -> employeeMapper.selectAll());
        
        // Verify only employees from departments 10 and 20 are returned
        assertTrue(employees.stream()
            .allMatch(e -> Arrays.asList(10L, 20L).contains(e.getDeptId())));
    }
}

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -am 'Add new feature'
Push to the branch: git push origin feature/your-feature
Submit a pull request

Development Setup

# Clone repository
git clone https://github.com/qwzhang01/seven-data-security.git
cd seven-data-security

# Build project
mvn clean install

# Run tests
mvn test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Contact & Support

Author: avinzhang
Email: avinzhang@tencent.com
GitHub: https://github.com/qwzhang01/seven-data-security
Issues: Report Issues

🙏 Acknowledgments

Thanks to the Spring Boot and MyBatis teams for their excellent frameworks
Thanks to all contributors who have helped improve this library

📚 Additional Resources

Star ⭐ this repository if you find it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
.github		.github
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README_ZH.md		README_ZH.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation

Seven Data Security

📋 Table of Contents

✨ Features

🔐 Automatic Data Encryption

🔍 Query Parameter Encryption

🎯 Data Scope Control

📊 Development Tools

🔄 SQL Processing

🏗️ Enterprise-Grade Design

🏛️ Architecture

🚀 Quick Start

1. Add Dependency

2. Define Entity with Encryption

3. Use in Service

🔑 Core Functionality

Field Encryption

Using @EncryptField Annotation

Using Encrypt Type Wrapper

Custom Encryption Algorithm

Register Custom Algorithm

Query Parameter Encryption

Single Table Query Processing

Data Scope Control

1. Define Data Scope Strategy

2. Apply Data Scope to Query

SQL Printing

⚙️ Configuration

Default Configuration

Custom Configuration

Application Properties

Override Default Encryption Algorithm

Disable SQL Printing

🎓 Advanced Usage

Nested Object Encryption

Collection Field Encryption

Multi-Level Data Scope

JSON Serialization

🎨 Design Patterns

1. Strategy Pattern

2. Factory Pattern

3. Template Method Pattern

4. Singleton Pattern

5. Interceptor Pattern

6. Observer Pattern

7. Flyweight Pattern

⚡ Performance Considerations

Caching Mechanisms

Optimization Tips

Performance Metrics

🧪 Testing

Unit Test Example

🤝 Contributing

Development Setup

📄 License

📞 Contact & Support

🙏 Acknowledgments

📚 Additional Resources

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages