签名算法

修订记录

2018-09-19：合成开放平台的说明到本地文档。

签名生成总体说明

  1. 本文档仅适用于QQ轻游戏后台openapi接口的签名生成，由于是通用说明，本文中仅以/openapi/apollo_verify_openid_openkey的签名生成作为示例。
  3. 签名值sig是将请求源串以及密钥根据一定签名方法生成的签名值，用来提高传输过程参数的防篡改性。
  4. 签名值的生成共有3个步骤：构造源串，构造密钥，生成签名值。详见下面的描述。

Step 1. 构造源串

源串是由3部分内容用“&”拼接起来的： HTTP请求方式 & urlencode(uri) & urlencode(a=x&b=y&…)

源串构造步骤如下：第1步：将请求的URI路径进行URL编码（URI不含host，URI示例：/openapi/apollo_verify_openid_openkey）。请开发者关注：URL编码注意事项，否则容易导致后面签名不能通过验证。

第2步：将除“sig”外的所有参数按key进行字典升序排列。 注：除文档中特别标注了某参数不参与签名，否则除sig外的所有参数都要参与签名。

第3步：将第2步中排序后的参数(key=value)用&拼接起来，并进行URL编码。URLENCODE时，要求对字符串中除了“-”、“_”、“.”之外的所有非字母数字字符都替换成百分号(%)后跟两位十六进制数。十六进制数中字母必须为大写。否则会导致校验不过。

第4步：将HTTP请求方式（目前只支持POST）以及第1步和第3步中的字符串用&拼接起来。

源串构造示例如下（由于是通用说明，这里以/openapi/apollo_verify_openid_openkey作为示例，且示例中的请求串不可直接复制访问）

  1. 1. 原始请求信息：
  2. appkey：228bf094169a40a3
  4. HTTP请求方式：POST
  6. 请求的URI路径（不含HOST）：/openapi/apollo_verify_openid_openkey
  8. 请求参数：appid=1&gameid=2017&openid=222&openkey=1111&rnd=1512981097&sig=xxxxxxxx&ts=1111
  10. 2. 下面开始构造源串： 
  11. 第1步：将请求的URI路径进行URL编码，得到： %2Fopenapi%2Fapollo_verify_openid_openkey
  14. 第2步：将除“sig”外的所有参数按key进行字典升序排列，排列结果为：appid，gameid，openid，openkey，rnd，ts 
  17. 第3步：将第2步中排序后的参数(key=value)用&拼接起来：
  18. appid=1&gameid=2017&openid=222&openkey=1111&rnd=1512981097&ts=1111 
  19. 然后进行URL编码（ 编码时请关注URL编码注意事项，否则容易导致后面签名不能通过验证），编码结果为：
  20. appid%3D1%26gameid%3D2017%26openid%3D222%26openkey%3D1111%26rnd%3D1512981097%26ts%3D1111
  23. 第4步：将HTTP请求方式，第1步以及第3步中的到的字符串用&拼接起来，得到源串：
  25. POST&%2Fopenapi%2Fapollo_verify_openid_openkey&appid%3D1%26gameid%3D2017%26openid%3D222%26openkey%3D1111%26rnd%3D1512981097%26ts%3D1111

Step 2. 构造密钥

得到密钥的方式：在应用的appkey末尾加上一个字节的“&”，即appkey&，例如：

  1. 228bf094169a40a3&

Step 3. 生成签名值

  • 使用HMAC-SHA1加密算法，使用Step2中得到的密钥对Step1中得到的源串加密。 （注：一般程序语言中会内置HMAC-SHA1加密算法的函数，例如PHP5.1.2之后的版本可直接调用hash_hmac函数，注意输出格式要选择二进制输出）

  • 然后将加密后的字符串经过Base64编码。 （注：一般程序语言中会内置Base64编码函数，例如PHP中可直接调用 base64_encode() 函数。）

  • 得到的签名值结果如下：

  1. UUkRyyx0NVfIinwB8P/saj00df8=

C++签名样例

依赖的库

  • openssl

    使用GetSignByHttpParamsSha1接口获取签名，注意strSecKey传入前在尾部加"&"

  • UrlEncode

    1. std::string URLEncode(const std::string & sIn)
    2. {
    3.   std::string sOut;
    4.   for (size_t ix = 0; ix < sIn.size(); ix++)
    5.   {
    6.       unsigned char buf[4];
    7.       memset(buf, 0, 4);
    8.       if (isalnum((unsigned char)sIn[ix]))
    9.       {
    10.           buf[0] = sIn[ix];
    11.       }
    12.       else if (sIn[ix] == '.' || sIn[ix] == '-' || sIn[ix] == '_')
    13.       {
    14.           buf[0] = sIn[ix];
    15.       }
    16.       else if (isspace((unsigned char)sIn[ix]))
    17.       {
    18.           buf[0] = '+';
    19.       }
    20.       else
    21.       {
    22.           buf[0] = '%';
    23.           buf[1] = toHex((unsigned char)sIn[ix] >> 4);
    24.           buf[2] = toHex((unsigned char)sIn[ix] % 16);
    25.       }
    26.       sOut += (char *)buf;
    27.   }
    28.   return sOut;
    29. }

  • Base64Encode

    1. int Base64Encode(const unsigned char * buffer, unsigned int length, char ** b64text, unsigned int & outlen)
    2. {
    3.   int iRet = 0;
    5.   //Encodes a binary safe base 64 string
    6.   BIO *bio, *b64;
    7.   BUF_MEM *bufferPtr;
    9.   b64 = BIO_new(BIO_f_base64());
    10.   bio = BIO_new(BIO_s_mem());
    11.   bio = BIO_push(b64, bio);
    13.   BIO_set_flags(bio, BIO_FLAGS_BASE64_NO_NL); 
    14.   iRet = BIO_write(bio, buffer, length);
    15.   iRet = BIO_flush(bio);
    16.   BIO_get_mem_ptr(bio, &bufferPtr);
    17.   iRet = BIO_set_close(bio, BIO_NOCLOSE);
    19.   *b64text = new char[((bufferPtr->length + 1) * sizeof(char))];
    20.   memcpy(*b64text, bufferPtr->data, bufferPtr->length);
    21.   (*b64text)[bufferPtr->length] = '\0';
    23.   outlen = bufferPtr->length;
    25.   BIO_free_all(bio);
    27.   return (0); 
    28. }

  • GetSignByHttpParamsSha1

    1. int GetSignByHttpParamsSha1(const string & strMethod, const string & strCgi,
    2.                           const map<string, string> & mapParam, const string & strSecKey,
    3.                           string & strSign)
    4. {
    5.   stringstream ssParam;
    7.   // 将请求参数组装成key1=value1&key2=value2的形式
    8.   for (map<string , string>::const_iterator iter = mapParam.begin(); iter != mapParam.end(); ++iter)
    9.   {
    10.       ssParam << iter->first << "=" << iter->second << "&";
    11.   }
    13.   // 组装方法名和域名
    14.   // 这里的strMethod是"POST"
    15.   // strCgi是api名称，比如"/openapi/apollo_game_item_proxy"或"/openapi/apollo_verify_openid_openkey"
    16.   stringstream ss;
    17.   ss << strMethod << "&" << URLEncode(strCgi)
    18.      << "&" << URLEncode(ssParam.str().substr(0, ssParam.str().size() - 1));
    20.   string strBuff = ss.str();
    22.   // 计算HMAC_HASH，采用SHA1
    23.   HMAC_CTX ctx;
    24.   HMAC_CTX_init(&ctx);
    26.   // 初始化
    27.   const EVP_MD * engine = EVP_sha1();
    28.   HMAC_Init_ex(&ctx, strSecKey.c_str(), strSecKey.size(), engine, NULL);
    30.   // 扣除最后一个&字符
    31.   HMAC_Update(&ctx, (const unsigned char *)strBuff.data(), strBuff.size());
    33.   // 计算结果
    34.   unsigned int uiLen = MAX_SIGN_RESULT_LEN;
    35.   unsigned char * ucResult = new unsigned char[uiLen];
    36.   memset(ucResult, 0x00, uiLen);
    38.   HMAC_Final(&ctx, ucResult, &uiLen);    
    40.   unsigned int uiBaseLen = 0;
    41.   char * cstrResult = NULL;
    42.   Base64Encode(ucResult, uiLen, &cstrResult, uiBaseLen);
    44.   strSign.clear();
    45.   strSign.assign(cstrResult, uiBaseLen);
    47.   HMAC_CTX_cleanup(&ctx);
    49.   delete [] cstrResult;
    50.   delete [] ucResult;
    52.   return 0;
    53. }

php签名样例

php签名类，引用自腾讯开放平台的openapi接口，使用makeSig接口获取签名，注意secret传入前在尾部加"&"

  1. <?php
  2. /**
  3.  * 生成签名类
  4.  *
  5.  * @version 3.0.3
  6.  * @author open.qq.com
  7.  * @copyright © 2012, Tencent Corporation. All rights reserved.
  8.  * @ History:
  9.  *               3.0.3 | nemozhang | 2012-08-28 16:40:20 | support cpay callback sig verifictaion.
  10.  *               3.0.2 | sparkeli | 2012-03-06 17:58:20 | add statistic fuction which can report API's access time and number to background server
  11.  *               3.0.1 | nemozhang | 2012-02-14 17:58:20 | resolve a bug: at line 108, change  'post' to  $method
  12.  *               3.0.0 | nemozhang | 2011-12-12 11:11:11 | initialization
  13.  */
  17. /**
  18.  * 生成签名类
  19.  */
  20. class SnsSigCheck
  21. {
  22.     /**
  23.      * 生成签名
  24.      *
  25.      * @param string     $method 请求方法 "POST"
  26.      * @param string     $url_path 
  27.      * @param array     $params 表单参数
  28.      * @param string     $secret 密钥
  29.      */
  30.     static public function makeSig($method, $url_path, $params, $secret) 
  31.     {
  32.         $mk = self::makeSource($method, $url_path, $params);
  33.         $my_sign = hash_hmac("sha1", $mk, strtr($secret, '-_', '+/'), true);
  34.         $my_sign = base64_encode($my_sign);
  36.         return $my_sign;
  37.     }
  39.     static private function makeSource($method, $url_path, $params) 
  40.     {
  41.         $strs = strtoupper($method) . '&' . rawurlencode($url_path) . '&';
  43.         ksort($params);
  44.         $query_string = array();
  45.         foreach ($params as $key => $val ) 
  46.         { 
  47.             array_push($query_string, $key . '=' . $val);
  48.         }   
  49.         $query_string = join('&', $query_string);
  51.         return $strs . str_replace('~', '%7E', rawurlencode($query_string));
  52.     }
  54.     /**
  55.      * 验证URL的签名 (注意和普通的OpenAPI签名算法不一样，详见@refer的说明)
  56.      *
  57.      * @param string     $method 请求方法 "get" or "post"
  58.      * @param string     $url_path 
  59.      * @param array     $params 腾讯调用发货回调URL携带的请求参数
  60.      * @param string     $secret 密钥
  61.      * @param string     $sig 腾讯调用发货回调URL时传递的签名
  62.      *
  63.      * @refer 
  64.      *  http://wiki.open.qq.com/wiki/%E5%9B%9E%E8%B0%83%E5%8F%91%E8%B4%A7URL%E7%9A%84%E5%8D%8F%E8%AE%AE%E8%AF%B4%E6%98%8E_V3
  65.      */
  66.     static public function verifySig($method, $url_path, $params, $secret, $sig) 
  67.     {
  68.         unset($params['sig']);
  70.         // 先使用专用的编码规则对value编码
  71.         foreach ($params as $k => $v)
  72.         {
  73.             $params[$k] = self::encodeValue($v);
  74.         }
  76.         // 再计算签名
  77.         $sig_new = self::makeSig($method, $url_path, $params, $secret);
  79.         return $sig_new == $sig;
  80.     }
  82.     /**
  83.      * URL专用的编码算法
  84.      *  编码规则为：除了 0~9 a~z A~Z !*()之外其他字符按其ASCII码的十六进制加%进行表示，例如"-"编码为"%2D"
  85.      * @refer 
  86.      *  http://wiki.open.qq.com/wiki/%E5%9B%9E%E8%B0%83%E5%8F%91%E8%B4%A7URL%E7%9A%84%E5%8D%8F%E8%AE%AE%E8%AF%B4%E6%98%8E_V3
  87.      */
  88.     static private function encodeValue($value) 
  89.     {
  90.         $rst = '';
  92.         $len = strlen($value);
  94.         for ($i=0; $i<$len; $i++)
  95.         {
  96.             $c = $value[$i];
  97.             if (preg_match ("/[a-zA-Z0-9!\(\)*]{1,1}/", $c))
  98.             {
  99.                 $rst .= $c;
  100.             }
  101.             else
  102.             {
  103.                 $rst .= ("%" . sprintf("%02X", ord($c)));                                                                                                                
  104.             }   
  105.         }   
  107.         return $rst;
  108.     } 
  109. }
  111. // end of script

原文: https://hudong.qq.com/docs/engine/server/thrid/api_doc/sig.html