跳到主要内容

签名认证

合作方调用 Hub API 时，需要在每个请求中携带 Authorization header，使用 SEAYOO-HMAC-SHA256 签名算法进行身份认证。

前置准备​

合作方已从世游侧获取到 Partner ID 和 Secret Key。这两个值是签名认证的必要参数。

原语函数​

以下是签名计算过程中用到的原语函数，各编程语言的标准库通常都有提供。

FunctionDescription
Hex()小写的十六进制编码。参见 Hexadecimal
SHA256Hash()SHA-256 安全哈希算法。参见 SHA-2
HMAC-SHA256()使用指定密钥的 HMAC-SHA256 消息认证码算法。参见 HMAC

生成签名​

步骤一：构造待签名字符串 StringToSign​

待签名字符串 StringToSign 由以下部分用换行符 \n（ASCII 0x0A）拼接而成：

SEAYOO-HMAC-SHA256\n
<HTTPMethod>\n
<RequestURI>\n
<Timestamp>\n
<HashedPayload>

HTTPMethod 是 HTTP 请求方法，例如 GET、POST。

RequestURI 是 HTTP 请求的 URI 部分，不包含协议与域名。如果有 Query String 需要一并包含。示例：

/v1/request-bind
/v1/query-binding?game_id=goose_duck&partner_user_id=user_98765432

Timestamp 是发起请求时的系统秒级时间戳，使用 UTC 时区的 ISO 8601 格式。示例：

20250601T100000Z

HashedPayload 是对 HTTP Request Body 计算 SHA-256 哈希后的十六进制结果：

Hex(SHA256Hash(<RequestBody>))

如果请求没有 Body（如 GET 请求），则对空字符串计算哈希，此时结果固定为：

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

步骤二：计算签名​

使用合作方的 Secret Key 作为签名密钥，对步骤一构造出的 StringToSign 计算 HMAC-SHA256：

Hex(HMAC-SHA256(SecretKey, StringToSign))

步骤三：添加 Authorization Header​

将签名结果添加到 HTTP 请求的 Authorization header 中：

Authorization: SEAYOO-HMAC-SHA256 Partner=<PartnerId>, Timestamp=<Timestamp>, Signature=<Signature>
  • Partner 为世游分配的 Partner ID
  • Timestamp 为步骤一中使用的时间戳
  • Signature 为步骤二中计算出的签名

签名验证规则​

世游服务端收到请求后，按以下顺序验证签名：

  1. 解析 Authorization header，提取 Partner、Timestamp、Signature。如果缺少任一字段，返回 invalid_signature 错误。
  2. 验证 Timestamp 与服务器当前时间的偏差不超过 15 分钟，否则返回 timestamp_expired 错误。
  3. 验证 Partner 对应的合作方存在且已启用，否则返回 invalid_signature 或 partner_disabled 错误。
  4. 使用合作方的 Secret Key 重新计算签名，与请求中的 Signature 对比，不一致则返回 invalid_signature 错误。

完整示例​

假定输入数据如下：

  • Partner ID 为 my_partner
  • Secret Key 为 sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  • HTTPMethod 为 POST
  • HTTP URL 为 https://hub-api.seayoo.com/v1/grant-reward
  • HTTP Request Body 为：
{"game_id":"example_game","event_id":1001,"partner_user_id":"user_12345","server_id":10001,"role_id":"1054832","reward_bundle_id":"bundle_spring_gift","partner_grant_reward_id":"grant_67890"}
  • 签名时的 Timestamp 为 20250115T080000Z

则签名过程如下：

1. HTTP URL 对应的 RequestURI 为：

/v1/grant-reward

2. HTTP Request Body 对应的 HashedPayload 为：

5df5b88effbbe34e7df7d7527ff78df3e6654a350c833151b210798d4c38b25d

3. 待签名的字符串 StringToSign 为：

SEAYOO-HMAC-SHA256
POST
/v1/grant-reward
20250115T080000Z
5df5b88effbbe34e7df7d7527ff78df3e6654a350c833151b210798d4c38b25d

4. 计算出的签名 Signature 为：

83640dd0f3befe4aac30f67097ee1c51385c8343dd72af7f9466c5f8387c8bd5

5. 添加到 HTTP 请求的 Authorization header 为：

Authorization: SEAYOO-HMAC-SHA256 Partner=my_partner, Timestamp=20250115T080000Z, Signature=83640dd0f3befe4aac30f67097ee1c51385c8343dd72af7f9466c5f8387c8bd5
提示

建议合作方在实现签名算法后，使用上述示例数据验证计算结果是否一致，以确认实现的正确性。

最后于 更新