签名方法
最近更新时间：2024.01.15 14:09:25
首次发布时间：2021.02.25 21:02:47
本文介绍调用 OpenAPI 的签名机制。签名用于对请求参数进行加密处理，保证请求在传输过程中不被篡改。
签名自动生成
推荐使用API Explorer的签名自动生成功能，您只需输入ak、sk、服务地址等信息，将会自动生成请求签名和可执行的curl命令，分步骤展示签名的生成过程。。
说明
- 签名串生成工具不会对输入AK、SK、host做准确性校验，请务必确保信息准确，否则生成的签名串将无法正常使用。
- 密钥为敏感信息，请勿泄露相关数据。
签名构造方法
火山引擎在 SDK 中提供了签名函数或方法，开发者只需要在请求中提供访问密钥等信息， SDK 会自动计算请求签名，并将签名结果添加到请求中。这种方法简化了签名过程，降低了开发难度，尤其适用于不熟悉签名算法的开发者。
您也可以使用火山引擎开发者工具API Explorer在线发起调用，快速获取调用结果。
当您不可避免地需要自行编码构造签名时，可参考下方签名机制介绍，自行编码构造签名时，我们也为您提供了签名Demo示例：
若您在使用过程中遇到问题，可随时通过提交工单与我们的技术工程师沟通，我们将第一时间协助您解决问题。
签名机制
注意
签名需要对请求参数进行一系列处理，包括排序、拼接、加密等步骤。这种方法提供了更大的灵活性和可定制性，适用于开发者对签名算法有深入理解的情况。然而，手动签名需要开发者编写额外的代码来实现签名过程，可能会增加开发难度和出错的可能性，因此我们依然建议您使用SDK来调用API，尽量避免自行编写签名代码。若您需要了解签名计算的原理和具体过程，可参考以下文档。
火山引擎手动签名机制要求请求者对请求参数进行哈希值计算，经过加密后同 API 请求一起发送到服务器中，服务器将以同样的机制对收到的请求进行签名计算，并将其与请求者传来的签名进行比对，若签名未通过验证，请求将被拒绝。
开发者需按流程完成以下操作：
获取访问密钥（Access Key）
访问密钥（Access Key）是请求火山引擎OpenAPI的安全凭证，参考 Access Key 管理获取账户的 Access Key ID 和 Secret Access Key。
构建规范请求字符串（CanonicalRequest）
在签名之前，首先需要将请求规范化，目的是让签名计算过程无异议。
构建规范化请求字符串，具体过程及伪代码如下：
CanonicalRequest = HTTPRequestMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HexEncode(Hash(RequestPayload))
说明
Hash 代指 SHA256 算法，HexEncode代指转 16 进制编码，HMAC指代HMAC_SHA256。
| 字段 | 解释 |
|---|---|
HTTPRequestMethod | 指代 HTTP 请求的方法，例如：GET、POST 等。 |
CanonicalURI | 指代规范化后的 URI。如果 URI 为空，那么使用"/"作为绝对路径。在火山引擎中绝大多数接口的 URI 都为"/"。如果是复杂的 path，请通过 RFC3986 规范进行编码。 |
| 指代规范化后的 Query String。对于 Query String 的规范化大致的过程如下：
|
| 指代规范化后的Header。其中伪代码如下： 注意 特别注意：最后需要添加 "\n" 的换行符，Header 的顺序是以 headerName 的小写后 ASCII 排序。 |
SignedHeaders | 指参与签名的 Header，和 CanonicalHeaders 包含的 Header 是一一对应的，目的是指明哪些 Header 参与签名计算，从而忽略请求被 proxy 添加的额外 Header，其中 host、x-date 如果存在 Header 中则必选参与，伪代码如下：SignedHeaders = Lowercase(HeaderName0) + ';' + Lowercase(HeaderName1) + ";" + ... + Lowercase(HeaderNameN) |
RequestPayload | 指代完整的请求的 Body。 |
构建待签名字符串（StringToSign）
签名字符串主要包含请求以及规范化请求的元数据信息，由签名算法、请求日期、信任状和规范化请求哈希值连接组成。
构建待签名字符串，伪代码如下：
StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))
| 字段 | 解释 |
|---|---|
| Algorithm | 指代签名的算法，目前火山引擎仅支持 HMAC-SHA256 的签名算法。 |
| RequestDate | 指代请求 UTC 时间，即请求头公共参数中 X-Date 的取值，使用遵循 ISO 8601 标准的格式：YYYYMMDD'T'HHMMSS'Z' ，例如：20201103T104027Z |
| CredentialScope | 指代信任状，格式为： ${YYYYMMDD}/${region}/${service}/request，其中${YYYYMMDD}取 X-Date 中的日期，${region}和${service} 参考公共参数的 Region 及 Service 取值，request为固定值。 |
| CanonicalRequest | 指构建规范请求字符串的结果。 |
计算签名密钥（kSigning）
在计算签名前，首先需使用访问密钥的Secret Access Key派生出签名密钥（kSigning）。
说明
访问密钥（Access Key）是请求火山引擎OpenAPI的安全凭证，参考 Access Key 管理获取账户的 Access Key ID 和 Secret Access Key。
计算派生签名密钥，计算过程及伪代码如下：
kSecret = *Your Secret Access Key* kDate = HMAC(kSecret, Date) kRegion = HMAC(kDate, Region) kService = HMAC(kRegion, Service) kSigning = HMAC(kService, "request")
说明
其中 Date 精确到日，与 RequestDate 中 YYYYMMDD 部分相同。
计算签名（Signature）
计算签名，伪代码如下：
Signature = HexEncode(HMAC(kSigning, StringToSign))
构建 Authorization
按如下格式构建 Header 的 Authorization 参数：
Authorization: HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}