open-api/mes/认证方式.md

### 认证方式

除了少部分的查询接口以外，大部分开放接口都需要认证，认证失败时候无法获取内容。

目前已启用的认证方式有：
- 基本认证
- 请求体签名认证

---

### 基本认证

基本认证使用固定的明文在网络中传输认证信息，存在被劫持的风险，因此不建议使用。

基本认证仅需使用一个 `token` 参数，加入 HTTP 头部即可，以下为 HTTP 请求示例：

```
POST /open/checked HTTP/1.1     
Host: 127.0.0.1
Content-Type: application/json
Content-Length: 30
Token: token1

{ "data": { "strict": true } }
```

认证成功时响应内容由接口控制；认证失败时会得到以下响应体：

```
{
  "status": "exception",
  "message": "令牌不存在。",
  "data": {}
}
```

---

### 请求体签名认证

使用请求体签名认证方式时，所有请求必须是 POST 方法，应用注册后可取到两个值：
- token：请求令牌，此值为固定值，需明文传输
- secret：哈希盐，此值用于计算哈希时加盐

HTTP 请求中与认证有关的字段有 3 个：
- token：请求令牌，此参数为固定值
- stamp：当前 UTC 毫秒时间戳
- signature：签名，此参数为动态值

#### 签名步骤

根据当前时钟生成 UTC 时毫秒间戳，获取字符串：

```
// JavaScript 生成时间戳
var stamp = String(Number(new Date()));

// C# 生成时间戳
var stamp = Convert.ToInt64((DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc)).TotalMilliseconds).ToString();
```

获取请求体的字符串：

```
{ "data": { "strict": true } }
```

使用 UTF-8 对请求体的文本进行编码，获取到 30 个字节，这与 HTTP 请求头中的 `Content-Length: 30` 一致，计算 SHA256，获取小写的十六进制：

```
// sha256
bd1f3e0163a759712739476ef49425ea93753fe690f5edd589c0e43bd0d1f653
```

将请求体哈希、时间戳和 secret 使用换行符拼接成一个字符串：

```
var secret = "secret3";
var stamp = "1687723200000";
var sha256 = "bd1f3e0163a759712739476ef49425ea93753fe690f5edd589c0e43bd0d1f653";
var sample = secret + "\n" + stamp + "\n" + sha256;
```

拼接后，得到待签名字符串：

```
secret3
1687723200000
bd1f3e0163a759712739476ef49425ea93753fe690f5edd589c0e43bd0d1f653
```

对待签名字符串进行 UTF-8 编码后，计算 SHA256，即为签名：

```
64235f1ae5900039b5e5c370aebbe8081b8b24b08b2bc3806a9a359304fc1e3b
```

#### 请求示例

将令牌（Token）、时间戳（Stamp）和签名（Signature）加入 HTTP 请求头中，即可发起请求。

```
POST /open/checked HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json
Content-Length: 30
Token: token3
Stamp: 1687723200000
Signature: 64235f1ae5900039b5e5c370aebbe8081b8b24b08b2bc3806a9a359304fc1e3b

{ "data": { "strict": true } }
```

认证成功时响应内容由接口控制；认证失败时会得到以下响应体：

```
{
  "status": "exception",
  "message": "令牌不存在。",
  "data": {}
}
```