全部产品

后端签名密钥说明文档

更新时间:2017-06-07 13:26:11

概述

  • API 网关提供后端 HTTP 服务签名验证功能,创建签名密钥并将签名密钥绑定到 API 即可开启后端签名(请妥善保管此密钥,API 网关会对密钥进行加密存储来保障密钥的安全性)。
  • 开启后端签名后 API 网关到后端HTTP服务的请求将会添加签名信息,后端 HTTP 服务读取 API 网关的签名字符串,然后对收到的请求进行本地签名计算,比对网关与本地签名结果是否一致。
  • 所有您定义的参数都会参与签名,包括您录入的业务参数、您定义的常量系统参数和 API 网关系统参数(如 CaClientIp 等)。
  • 后端对 API 网关的签名字符串校验后,如果校验失败,建议返回 errorcode = 403;errormessage = “InvalidSignature”。
  • 若您的后端服务为VPC环境,且通过内网对接(专属网络VPC环境开放API),您无需使用后端签名,通道自身是安全的。

读取 API 网关签名方法

网关计算的签名保存在 Request 的 Header 中,Header 名称:X-Ca-Proxy-Signature

后端 HTTP 服务加签方法

签名计算的详细 demo(JAVA)请参照链接:https://github.com/aliyun/api-gateway-demo-sign-backend-java

签名计算方法步骤如下:

组织参与加签的数据

  1. String stringToSign=
  2. HTTPMethod + "\n" + //Method全大写
  3. Content-MD5 + "\n" + //Content-MD5 需要判断是否为空,如果为空则跳过,但是为空也需要添加换行符 "\n"
  4. Headers + //Headers 如果为空不需要添加"\n",不为空的Headers中包含了"\n",详见下面组织Headers的描述
  5. Url

计算签名

  1. Mac hmacSha256 = Mac.getInstance("HmacSHA256");
  2. byte[] keyBytes = secret.getBytes("UTF-8");
  3. hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
  4. String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

secret 为绑定到 API 上的签名密钥

补充说明

  • Content-MD5

    Content-MD5 是指 Body 的 MD5 值,只有 HttpMethod 为 PUT 或者 POST 且 Body 为非 Form 表单时才计算 MD5,计算方式为:

    String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes(“UTF-8”)));

  • Headers

    Headers 指所有参与签名计算的 Header的Key、Value。参与签名计算的 Header 的 Key 从 Request Header 中读取,Key为:”X-Ca-Proxy-Signature-Headers”,多个 Key 用英文逗号分割。

  • Headers 组织方法

    先对所有参与签名计算的 Header 的 Key 按照字典排序,然后将 Header 的 Key 转换成小写后按照如下方式拼接:

    String headers = HeaderKey1.toLowerCase() + “:” + HeaderValue1 + “\n”+ HeaderKey2.toLowerCase() + “:” + HeaderValue2 + “\n”+ … HeaderKeyN.toLowerCase() + “:” + HeaderValueN + “\n”

  • Url

    Url指 Path+Query+Body 中 Form 参数,组织方法:如果有 Query 或 Form 参数则加 ?,然后对 Query+Form 参数按照字典对 Key 进行排序后按照如下方法拼接,如果没有 Query 或 Form 参数,则 Url = Path

  1. String url =
  2. Path +
  3. "?" +
  4. Key1 + "=" + Value1 +
  5. "&" + Key2 + "=" + Value2 +
  6. ...
  7. "&" + KeyN + "=" + ValueN
  8. 注意:这里 Query Form 参数的 Value 可能有多个,多个的时候只取第一个 Value 参与签名计算
  • 调试模式

    为了方便后端签名接入与调试,可以开启 Debug 模式进行调试,具体方法如下:

    1. 请求API网关的 Header 中添加 X-Ca-Request-Mode = debug

    2. 后端服务在 Header 中读取 X-Ca-Proxy-Signature-String-To-Sign 即可,因为 HTTP Header 中值不允许有换行符,因此换行符被替换成了 “|”。

      注意:X-Ca-Proxy-Signature-String-To-Sign 不参与后端签名计算。

  • 时间戳校验

    如果后端需要对请求进行时间戳校验,可以在 API 定义中选择系统参数 “CaRequestHandleTime” ,值为网关收到请求的格林威治时间。