DNSPod-Skill/references/api-auth.md

腾讯云API认证说明

概述

DNSPod API使用腾讯云统一的API v3签名算法,基于HMAC-SHA256进行请求签名认证。

获取密钥

1. 访问API密钥管理页面

https://console.cloud.tencent.com/cam/capi

2. 创建密钥

• 点击「新建密钥」或「访问密钥」
• 系统生成 SecretId 和 SecretKey

3. 保存密钥

⚠️ 重要: SecretKey只在创建时显示一次,请妥善保存!

4. 设置环境变量

Linux/Mac (Bash/Zsh):

# 添加到 ~/.bashrc 或 ~/.zshrc
export TENCENT_SECRET_ID="你的SecretId"
export TENCENT_SECRET_KEY="你的SecretKey"

# 重新加载配置
source ~/.bashrc  # 或 source ~/.zshrc

Windows (PowerShell):

# 添加到环境变量
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_ID', '你的SecretId', 'User')
[System.Environment]::SetEnvironmentVariable('TENCENT_SECRET_KEY', '你的SecretKey', 'User')

# 临时设置(当前会话有效)
$env:TENCENT_SECRET_ID="你的SecretId"
$env:TENCENT_SECRET_KEY="你的SecretKey"

验证环境变量:

# Linux/Mac
echo $TENCENT_SECRET_ID

# Windows PowerShell
echo $env:TENCENT_SECRET_ID

签名算法详解

1. 构造规范请求串

格式:

HTTPRequestMethod + '\n' +
CanonicalURI + '\n' +
CanonicalQueryString + '\n' +
CanonicalHeaders + '\n' +
SignedHeaders + '\n' +
HexEncode(Hash(RequestPayload))

示例:

POST
/
content-type:application/json
host:dnspod.tencentcloudapi.com

content-type;host
356f92b5d0373084a2bc07df8267b0ab

2. 构造待签名字符串

格式:

Algorithm + '\n' +
RequestTimestamp + '\n' +
CredentialScope + '\n' +
HexEncode(Hash(CanonicalRequest))

示例:

TC3-HMAC-SHA256
1666666666
2021-03-23/dnspod/tc3_request
5c9d88e6d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d

3. 计算签名

使用 HMAC-SHA256 算法分三次计算:

secret_date = HMAC_SHA256("TC3" + SecretKey, Date)
secret_service = HMAC_SHA256(secret_date, Service)
secret_signing = HMAC_SHA256(secret_service, "tc3_request")
signature = HMAC_SHA256(secret_signing, StringToSign)

4. 构造Authorization头

格式:

Algorithm Credential={SecretId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

示例:

TC3-HMAC-SHA256 Credential=AKIDxxxxxxxx/2021-03-23/dnspod/tc3_request, SignedHeaders=content-type;host, Signature=5c9d88e6d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d4c4d

完整请求示例

请求头

POST / HTTP/1.1
Host: dnspod.tencentcloudapi.com
Content-Type: application/json
Authorization: TC3-HMAC-SHA256 Credential=AKIDxxxxxxxx/2021-03-23/dnspod/tc3_request, SignedHeaders=content-type;host, Signature=xxxxxxxx
X-TC-Action: DescribeRecordList
X-TC-Timestamp: 1666666666
X-TC-Version: 2021-03-23
X-TC-Region: ap-guangzhou

请求体

{
  "Domain": "example.com"
}

请求参数说明

参数	说明	示例
X-TC-Action	操作名称	CreateRecord
X-TC-Version	API版本	2021-03-23
X-TC-Timestamp	时间戳(秒)	1666666666
X-TC-Region	地域	ap-guangzhou
Authorization	签名信息	见上文

地域说明

DNSPod API支持的地域:

• ap-guangzhou (广州,推荐)
• ap-shanghai (上海)
• ap-beijing (北京)
• ap-chengdu (成都)

建议选择就近地域以降低延迟。

安全建议

1. 密钥安全

• ⚠️ 不要将密钥硬编码在代码中
• ⚠️ 不要在Git仓库中提交密钥
• ✓ 使用环境变量或配置文件
• ✓ 定期轮换密钥

2. 权限管理

• 为不同应用创建独立的子账号
• 只授予必要的权限(最小权限原则)
• 定期审计密钥使用情况

3. IP白名单

• 在腾讯云访问管理(CAM)中设置IP白名单
• 限制只有特定IP才能调用API

参考文档

• API签名文档: https://cloud.tencent.com/document/product/1427/56152
• 访问管理(CAM): https://cloud.tencent.com/document/product/598
• SDK示例: https://cloud.tencent.com/document/sdk