# free-ssl-api

**Repository Path**: luckythc/free-ssl-api

## Basic Information

- **Project Name**: free-ssl-api
- **Description**: 免费证书申请API服务
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSL 证书服务 API

这是一个基于 Node.js 和 Express 开发的 SSL 证书服务 API，提供证书申请、状态查询和下载功能。

## 文档

- **项目说明**：本 README.md 提供项目概述和快速开始指南
- **详细API使用手册**：请参考 <mcfile name="api_usage_guide.md" path="doc/api_usage_guide.md"></mcfile> 文件，包含完整的API接口说明、HMAC签名算法详解和各种语言的示例代码

## 功能特点

- ✅ 真实Let's Encrypt证书申请
- ✅ DNS验证支持（阿里云、百度云、华为云、腾讯云、Cloudflare、Google DNS）
- ✅ DNS凭证预先验证
- ✅ 证书状态查询接口  
- ✅ 证书下载接口
- ✅ 参数验证
- ✅ 错误处理
- ✅ 日志记录
- ✅ 回调通知
- ✅ 证书存在性检查
- ✅ API接口认证（HMAC签名验证）

## 项目结构

```directory
api/
├── config/          # 配置文件
├── controllers/     # 控制器
├── middlewares/     # 中间件
├── routes/          # 路由
├── services/        # 业务逻辑层
├── utils/           # 工具函数
├── app.js           # Express 应用配置
├── index.js         # 应用入口
├── package.json     # 项目配置
└── README.md        # 项目说明
```

## 安装依赖

```bash
npm install
```

### 核心依赖

- `express`: Web框架
- `express-validator`: 参数验证
- `winston`: 日志记录
- `axios`: HTTP请求（用于回调通知）
- `greenlock-express`: Let's Encrypt客户端
- `le-acme-core`: ACME协议核心功能
- `uuid`: 生成唯一标识符
- `@alicloud/pop-core`: 阿里云SDK
- `tencentcloud-sdk-nodejs`: 腾讯云SDK
- `@huaweicloud/huaweicloud-sdk-core`: 华为云SDK核心
- `@huaweicloud/huaweicloud-sdk-dns`: 华为云DNS SDK
- `cloudflare`: Cloudflare API客户端
- `@google-cloud/dns`: Google DNS API客户端

## 启动服务

### 使用NPM命令启动

```bash
# 启动服务
npm start

# 开发模式启动
npm run dev
```

### 使用启动脚本

```bash
# Windows环境
./start.bat

# Linux/Mac环境
chmod +x start.sh
./start.sh
```

服务默认运行在 <http://localhost:3000>

## 环境变量

- `PORT`: 服务端口，默认3000
- `NODE_ENV`: 运行环境，默认development
- `LETSENCRYPT_EMAIL`: Let's Encrypt账户邮箱
- `LETSENCRYPT_SERVER`: Let's Encrypt服务器地址
  - 测试环境: `https://acme-staging-v02.api.letsencrypt.org/directory` (默认)
  - 生产环境: `https://acme-v02.api.letsencrypt.org/directory`
- `CERT_STORAGE_PATH`: 证书存储路径，默认`./certificates`

## API 接口

### 1. 注册API访问凭证

**请求路径**: `POST /api/auth/register`

**请求参数**:

```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应**: 成功时返回token和secretKey

```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "token": "your-token",
    "secretKey": "your-secret-key",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}
```

**说明**:

- 使用用户名和密码获取API访问凭证
- 返回的token和secretKey用于后续接口的HMAC签名认证
- 每个用户只生成一对token和secretKey（重复注册返回已有凭证）

### 2. 申请证书

**请求路径**: `POST /api/certificate/apply`

**请求头**:

- `x-token`: 注册时获取的token
- `x-signature`: HMAC-SHA256签名
- `x-timestamp`: 当前时间戳（秒）

**请求参数**:

```json
{
  "domain": "example.com",
  "dnsProvider": {
    "id": "aliyun", // 可选值: aliyun, baidu, huawei, tencent, cloudflare, google
    // 以下为阿里云配置示例
    "accessKeyId": "your_access_key_id",
    "accessKeySecret": "your_access_key_secret"
  },
  "certificateProvider": "letsencrypt", // 可选，默认为 letsencrypt
  "callbackUrl": "https://your-server.com/callback" // 可选
}
```

**各DNS提供者配置说明**:

1. **阿里云**:

```json
{
  "id": "aliyun",
  "accessKey": "your_access_key_id",
  "secretKey": "your_access_key_secret"
}
```

2. **百度云**:

```json
{
  "id": "baidu",
  "accessKey": "your_baidu_ak",
  "secretKey": "your_baidu_sk"
}
```

3. **华为云**:

```json
{
  "id": "huawei",
  "projectId": "your_project_id",
  "accessKey": "your_huawei_ak",
  "secretKey": "your_huawei_sk"
}
```

4. **腾讯云**:

```json
{
  "id": "tencent",
  "accessKey": "your_secret_id",
  "secretKey": "your_secret_key"
}
```

5. **Cloudflare** (支持两种认证方式):

```json
// 方式1: API Token (推荐)
{
  "id": "cloudflare",
  "apiToken": "your_cloudflare_api_token"
}

// 方式2: API Token + Email
  ```json
  {
    "id": "cloudflare",
    "apiToken": "your_cloudflare_api_token",
    "email": "your_cloudflare_email"
  }
  ```

6. **Google DNS**:

```json
{
  "id": "google",
  "credentials": {"type":"service_account", ...},
  "projectId": "your-project-id"
}
```

**说明**:

- 系统会先验证DNS凭证（AccessKeyId和AccessKeySecret）的正确性
- 凭证无效时会立即返回错误信息
- 系统会检查证书是否已存在，如存在则直接返回
- 不存在时会通过Let's Encrypt API申请新证书
- 申请过程中会执行DNS验证
- 证书成功后会自动保存在配置的存储路径中

**响应**: 成功时返回请求ID

```json
{
  "code": 200,
  "message": "证书申请已提交",
  "data": {
    "requestId": "uuid-request-id"
  }
}
```

### 2. 查询请求状态

**请求路径**: `GET /api/certificate/status?requestId=uuid-request-id`

**请求头**:

- `x-token`: 注册时获取的token
- `x-signature`: HMAC-SHA256签名
- `x-timestamp`: 当前时间戳（秒）

**响应**:

```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "requestId": "uuid-request-id",
    "domain": "example.com",
    "status": "success", // pending, processing, success, failed
    "certificateId": "uuid-certificate-id", // 成功时返回
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}
```

### 3. 下载证书

**请求路径**: `GET /api/certificate/download/:certificateId`

**请求头**:

- `x-token`: 注册时获取的token
- `x-signature`: HMAC-SHA256签名
- `x-timestamp`: 当前时间戳（秒）

**响应**: 返回二进制证书数据（包含证书和私钥）

## 健康检查

**请求路径**: `GET /health`

**响应**:

```json
{
  "code": 200,
  "message": "服务运行正常",
  "data": {
    "timestamp": "2024-01-01T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

## 错误响应格式

```json
{
  "code": 错误码,
  "message": "错误消息",
  "data": 错误详情
}
```

## 日志

- `error.log`: 错误日志
- `combined.log`: 所有日志

## HMAC签名计算方法

所有需要认证的接口都需要在请求头中提供以下参数：

```headers
x-token: 注册获取的token
x-signature: HMAC-SHA256签名
x-timestamp: 当前时间戳（秒）
```

签名计算步骤：

1. 构建签名字符串：`{method}\n{path}\n{timestamp}[\n{body}]`
   - method: HTTP请求方法（大写）
   - path: 请求路径（如/api/certificate/apply）
   - timestamp: 请求头中的x-timestamp值
   - body: 如果有请求体，需要序列化为JSON字符串
2. 使用注册时获取的secretKey作为密钥，计算HMAC-SHA256哈希值
3. 将计算结果作为x-signature请求头的值

示例代码（Node.js）：

```javascript
const crypto = require('crypto');

function generateSignature(method, path, timestamp, body, secretKey) {
  let dataToSign = `${method}\n${path}\n${timestamp}`;
  
  if (body && Object.keys(body).length > 0) {
    dataToSign += `\n${JSON.stringify(body)}`;
  }
  
  return crypto.createHmac('sha256', secretKey)
    .update(dataToSign)
    .digest('hex');
}
```

## 注意事项

1. 本项目目前使用内存和文件系统存储请求和证书信息，生产环境建议使用数据库
2. 证书申请是异步处理的，需要通过状态查询接口获取处理结果
3. 如果提供了 callbackUrl，证书申请成功后会向该地址发送通知
4. 本项目仅作为示例，实际生产环境需要添加更多安全措施
5. 当前支持的DNS提供者：aliyun、baidu、huawei、tencent、cloudflare、google
6. 当前支持的证书提供者：letsencrypt
7. HMAC签名验证提供了防重放保护，时间戳与服务器时间偏差不应超过5分钟
8. 除了健康检查接口和认证注册接口外，所有其他接口都需要HMAC认证