---
title: "验证消息认证码"
description: "使用消息认证码中记录的历史密钥版本验证数据，不匹配时仍返回 HTTP 200 和 valid=false。"
---

> 文档索引
> 完整文档索引：http://127.0.0.1:4321/docs/llms.txt

# 验证消息认证码

使用消息认证码中记录的历史密钥版本验证数据，不匹配时仍返回 HTTP 200 和 valid=false。

**POST /api/v1/kms/keys/{key_id}/verify-hmac**

- 模块：密钥管理服务（KMS）
- 认证：使用 App Header 签名或 App Secret
- 系统状态：需要 unsealed

## 请求示例

```bash
curl --request POST \
  'http://127.0.0.1:7770/api/v1/kms/keys/019fb1b5-7bb6-7eaf-9bf0-a1b2c3d4e5f6/verify-hmac' \
  --header 'X-QK-AppID: $APP_ID' \
  --header 'X-QK-Timestamp: $TIMESTAMP' \
  --header 'X-QK-Nonce: $NONCE' \
  --header 'X-QK-Signature: $SIGNATURE' \
  --header 'Content-Type: application/json' \
  --data '{
  "data": "SGVsbG8sIHdvcmxkIQ",
  "mac": "qk:v4:<opaque-mac>"
}'
```

## Path 参数

| 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `key_id` | `string` | 是 | 否 | — | 密钥 ID |

## Query 参数

无。

## Body 参数

| 名称 | 类型 | 必填 | 敏感 | 默认值 | 说明 |
| --- | --- | --- | --- | --- | --- |
| `data` | `string` | 是 | 是 | — | 采用无填充 Base64URL 编码的原始数据 |
| `mac` | `string` | 是 | 是 | — | HMAC 接口返回的 qk:v<密钥版本>:<不透明载荷> 消息认证码 |

## 成功响应

### HTTP 200

操作成功

```json
{
  "data": {
    "result": {
      "algorithm": "hmac-sm3",
      "key_version": 4,
      "valid": true
    }
  },
  "error": null,
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

## 失败响应

按 HTTP status 与 `error.code` 区分失败原因；响应始终使用统一 envelope。

### HTTP 400 · `invalid_request`

请求参数或 JSON 请求体无效

```json
{
  "data": null,
  "error": {
    "code": "invalid_request",
    "details": {},
    "message": "请求参数或 JSON 请求体无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 400 · `kms_invalid_result`

密文、签名或消息认证码格式无效

```json
{
  "data": null,
  "error": {
    "code": "kms_invalid_result",
    "details": {},
    "message": "密文、签名或消息认证码格式无效"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 400 · `kms_purpose_mismatch`

密钥用途不支持该操作

```json
{
  "data": null,
  "error": {
    "code": "kms_purpose_mismatch",
    "details": {},
    "message": "密钥用途不支持该操作"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 400 · `not_initialized`

系统尚未初始化

```json
{
  "data": null,
  "error": {
    "code": "not_initialized",
    "details": {},
    "message": "系统尚未初始化"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 401 · `replayed_request`

签名请求的 nonce 已被使用

```json
{
  "data": null,
  "error": {
    "code": "replayed_request",
    "details": {},
    "message": "签名请求的 nonce 已被使用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 401 · `unauthorized`

App ID、App Secret 或签名无效，或者凭据已过期

```json
{
  "data": null,
  "error": {
    "code": "unauthorized",
    "details": {},
    "message": "App ID、App Secret 或签名无效，或者凭据已过期"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 403 · `forbidden`

App 没有访问目标资源所需的权限

```json
{
  "data": null,
  "error": {
    "code": "forbidden",
    "details": {},
    "message": "App 没有访问目标资源所需的权限"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 404 · `kms_key_not_found`

密钥不存在

```json
{
  "data": null,
  "error": {
    "code": "kms_key_not_found",
    "details": {},
    "message": "密钥不存在"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 409 · `kms_key_disabled`

密钥已禁用

```json
{
  "data": null,
  "error": {
    "code": "kms_key_disabled",
    "details": {},
    "message": "密钥已禁用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 409 · `kms_key_retired`

密钥已退役

```json
{
  "data": null,
  "error": {
    "code": "kms_key_retired",
    "details": {},
    "message": "密钥已退役"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 409 · `kms_version_disallowed`

结果引用的历史密钥版本已不允许读取

```json
{
  "data": null,
  "error": {
    "code": "kms_version_disallowed",
    "details": {},
    "message": "结果引用的历史密钥版本已不允许读取"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 413 · `kms_input_too_large`

输入数据超过 KMS 限制

```json
{
  "data": null,
  "error": {
    "code": "kms_input_too_large",
    "details": {},
    "message": "输入数据超过 KMS 限制"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 413 · `request_body_too_large`

请求体超过服务端限制

```json
{
  "data": null,
  "error": {
    "code": "request_body_too_large",
    "details": {},
    "message": "请求体超过服务端限制"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 423 · `sealed`

系统处于封印状态

```json
{
  "data": null,
  "error": {
    "code": "sealed",
    "details": {},
    "message": "系统处于封印状态"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 500 · `internal_error`

服务端无法完成请求

```json
{
  "data": null,
  "error": {
    "code": "internal_error",
    "details": {},
    "message": "服务端无法完成请求"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 503 · `crypto_unavailable`

密码服务暂不可用

```json
{
  "data": null,
  "error": {
    "code": "crypto_unavailable",
    "details": {},
    "message": "密码服务暂不可用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 503 · `leader_unavailable`

高可用集群的 Leader 暂不可用

```json
{
  "data": null,
  "error": {
    "code": "leader_unavailable",
    "details": {},
    "message": "高可用集群的 Leader 暂不可用"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

### HTTP 503 · `maintenance_mode`

系统处于维护模式

```json
{
  "data": null,
  "error": {
    "code": "maintenance_mode",
    "details": {},
    "message": "系统处于维护模式"
  },
  "request_id": "019fb18d-6b45-7e2d-a3b4-c5d6e7f80910"
}
```

Source: http://127.0.0.1:4321/docs/api/kms/post-keys-by-key-id-verify-hmac/