# tim-api-encrypt-middleware

**Repository Path**: mangoT/tim-api-encrypt-middleware

## Basic Information

- **Project Name**: tim-api-encrypt-middleware
- **Description**: 国产化改造，轻量级 API 加密 SM4， 向下兼容 springboot2.x 和 springboot3.x，兼容 AES。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tim-api-encrypt-middleware

> API 加解密中间件 - 支持 Spring Boot 2.x 和 3.x，提供 AES 和 SM4 国密算法

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Maven Central](https://img.shields.io/badge/Maven%20Central-2.1.0.RELEASE-green.svg)](https://gitee.com/mangoT/tim-api-encrypt-middleware)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.x%20%7C%203.x-brightgreen.svg)]()

---

## 📖 项目简介

本项目是从 [monkey-api-encrypt](https://gitee.com/mangoT/monkey-api-encrypt) 项目中提取的**纯中间件版本**，专注于提供轻量级的 API 加解密能力，不包含管理平台功能。

### 主要特性

- ✅ **双版本支持**: 同时支持 Spring Boot 2.x 和 3.x（Jakarta EE 9+）
- ✅ **国密算法**: 支持 SM4 国密算法（CBC 模式，PKCS7 填充）
- ✅ **标准算法**: 支持 AES 算法（CBC 模式，PKCS7 填充）
- ✅ **模块化设计**: 按需引入，最小化依赖
- ✅ **简单易用**: 注解驱动，零侵入集成
- ✅ **安全加固**: 修复所有已知安全漏洞（CVE）

---

## 🚀 快速开始

### Maven 依赖

```xml
<!-- Spring Boot 3.x 用户 -->
<dependency>
    <groupId>com.tim</groupId>
    <artifactId>tim-api-encrypt-starter</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

<!-- Spring Boot 2.x 用户 -->
<dependency>
    <groupId>com.tim</groupId>
    <artifactId>tim-api-encrypt-spring-boot2</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>
```

### 配置示例

```yaml
spring:
  encrypt:
    enabled: true              # 是否启用加密
    key: your-16-byte-key      # 加密密钥（16 字节）
    algorithm: AES             # 算法：AES 或 SM4
    debug: false               # 调试模式（关闭加解密）

    # 请求解密配置
    request:
      decrypt-uris:            # 需要解密的 URI
        - /api/**

    # 响应加密配置
    response:
      encrypt-uris:            # 需要加密的 URI
        - /api/**
```

### 注解使用

```java
import com.tim.encrypt.annotation.Encrypt;
import com.tim.encrypt.annotation.Decrypt;

@RestController
public class DemoController {

    @Encrypt
    @PostMapping("/api/save")
    public Result save(@RequestBody User user) {
        // 响应数据会自动加密
        return Result.success(user);
    }

    @Decrypt
    @PostMapping("/api/update")
    public Result update(@RequestBody User user) {
        // 请求数据会自动解密
        return Result.success(user);
    }
}
```

---

## 📦 模块说明

| 模块 | 说明 |
|------|------|
| **tim-api-encrypt-core** | 核心加解密引擎（Filter、配置、算法接口） |
| **tim-api-encrypt-sm4** | SM4 国密算法实现（Bouncy Castle） |
| **tim-api-encrypt-spring-boot2** | Spring Boot 2.x 自动配置 |
| **tim-api-encrypt-spring-boot3** | Spring Boot 3.x 自动配置 |
| **tim-api-encrypt-starter** | 统一 Starter（推荐使用） |

---

## 🔧 算法支持

### AES 算法

- **模式**: CBC
- **填充**: PKCS7
- **密钥长度**: 128 位
- **依赖**: JDK 内置

### SM4 算法

- **模式**: CBC
- **填充**: PKCS7
- **密钥长度**: 128 位
- **依赖**: Bouncy Castle (bcprov-jdk18on)

---

## 📚 示例代码

### 后端示例

项目提供了完整的后端示例代码：

- **tim-api-encrypt-springboot-example**: Spring Boot 2.x 示例
- **tim-api-encrypt-springboot3-example**: Spring Boot 3.x 示例（独立）
- **tim-api-encrypt-springmvc-example**: Spring MVC 示例

运行示例：

```bash
cd tim-api-encrypt-springboot-example
mvn spring-boot:run
```

### 前端测试工具

项目包含一个完整的 Vue 3 前端测试工具，用于测试加解密功能：

**技术栈**：
- Vue 3.4+ / TypeScript 5.3+
- Element Plus 2.5+
- Vite 5.4+
- sm-crypto（国密 SM4）
- crypto-js（AES）

**功能特性**：
- ✅ SM4 加密测试
- ✅ AES 加密测试
- ✅ API 交互测试
- ✅ 用户管理演示
- ✅ 中间件配置查看

**快速启动**：

```bash
cd tim-api-encrypt-frontend

# 安装依赖
npm install
# 或
pnpm install

# 配置后端地址
# 编辑 .env.development
# VITE_API_BASE_URL=http://localhost:8080
# VITE_ENCRYPTION_KEY=d86d7bab3d6ac01ad9dc6a897652f2d2

# 启动开发服务器
npm run dev
```

访问 http://localhost:5173

---

## 🛡️ 安全特性

本中间件已修复以下已知安全漏洞：

| CVE | 描述 | 修复版本 |
|-----|------|---------|
| CVE-2018-11771 | Apache Commons Codec | 1.17.1 |
| CVE-2021-29425 | Apache Commons IO | 2.17.0 |
| CVE-2022-45868 | SLF4J | 2.0.16 |

---

## 📋 版本说明

### v2.1.0.RELEASE (2025-02-04)

- ✅ 添加 Spring Boot 3.x 支持
- ✅ 添加 SM4 国密算法支持
- ✅ 修复所有已知安全漏洞
- ✅ 优化代码结构和文档

### v1.2.x (原版本)

- 基础加解密功能
- Spring Boot 2.x 支持

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

---

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 开源协议。

---

## 👥 作者

- **原作者**: [yinjihuan](https://github.com/yinjihuan)
- **当前维护**: [tim.luo](https://gitee.com/mangoT)

---

## ⚠️ 注意事项

1. **密钥安全**: 生产环境严禁在配置文件中明文存储密钥，请使用环境变量或密钥管理服务
2. **调试模式**: `debug=true` 会关闭所有加解密，仅用于开发环境
3. **密钥长度**: AES 和 SM4 密钥长度必须为 16 字节（128 位）

---

## 📞 联系方式

- **邮箱**: 513754103@qq.com
- **Gitee**: https://gitee.com/mangoT/tim-api-encrypt-middleware
- **Issues**: https://gitee.com/mangoT/tim-api-encrypt-middleware/issues

---

⭐ 如果这个项目对你有帮助，请点个 Star 支持一下！