221 lines
10 KiB
Markdown
221 lines
10 KiB
Markdown
加解密方案说明
|
||
概述
|
||
企业微信在推送消息给企业时，会对消息内容做AES加密，以XML格式POST到企业应用的URL上。
|
||
企业在被动响应时，也需要对数据加密，以XML格式返回给企业微信。
|
||
本章节即是对加解密方法的说明。
|
||
阅读本章节前，需要了解以下术语：
|
||
|
||
msg_signature： 消息签名，用于验证请求是否来自企业微信（防止攻击者伪造）。
|
||
EncodingAESKey：用于消息体的加密，长度固定为43个字符，从a-z, A-Z, 0-9共62个字符中选取，是AESKey的Base64编码。解码后即为32字节长的AESKey
|
||
|
||
AESKey=Base64_Decode(EncodingAESKey + “=”)
|
||
AESKey：AES算法的密钥，长度为32字节。
|
||
AES采用CBC模式，数据采用PKCS#7填充至32字节的倍数；IV初始向量大小为16字节，取AESKey前16字节，详见：http://tools.ietf.org/html/rfc2315
|
||
msg：为消息体明文，格式为XML/JSON
|
||
msg_encrypt：明文消息msg加密处理后的Base64编码。
|
||
使用已有库
|
||
鉴于加解密算法相对复杂，企业微信提供了算法库。
|
||
目前已有c++/python/php/java/golang/c#等语言版本。均提供了解密、加密、验证URL三个接口，企业可根据自身需要下载，下载地址。
|
||
|
||
使用现有库，用户不必细究加解密原理。对于找不到相应语言库的用户，请阅读后文原理详解自行实现。欢迎大家分享~
|
||
以c++为例，使用示例见下载的文件夹中的Sample.cpp, 此处做简单说明。
|
||
|
||
初始化加解密类
|
||
回调xml示例：
|
||
|
||
WXBizMsgCrypt wxcpt(sToken,sEncodingAESKey,sReceiveId);
|
||
回调json示例
|
||
|
||
WXBizJsonMsgCrypt wxcpt(sToken,sEncodingAESKey,sReceiveId);
|
||
要求传参数sToken,sEncodingAESKey,sReceiveId。
|
||
sToken,sEncodingAESKey即设置接收消息的参数章节所述配置的Token、EncodingAESKey。
|
||
特别注意, sReceiveId 在不同场景下有不同含义，见附注。
|
||
|
||
验证URL函数
|
||
本函数实现：
|
||
|
||
签名校验
|
||
解密数据包，得到明文消息内容
|
||
int VerifyURL(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sEchoStr, string &sReplyEchoStr);
|
||
参数说明
|
||
参数 必须 说明
|
||
sMsgSignature 是 从接收消息的URL中获取的msg_signature参数
|
||
sTimeStamp 是 从接收消息的URL中获取的timestamp参数
|
||
sNonce 是 从接收消息的URL中获取的nonce参数
|
||
sEchoStr 是 从接收消息的URL中获取的echostr参数。注意，此参数必须是urldecode后的值
|
||
sReplyEchoStr 是 解密后的明文消息内容，用于回包。注意，必须原样返回，不要做加引号或其它处理
|
||
|
||
|
||
解密函数
|
||
本函数实现：
|
||
|
||
签名校验
|
||
解密数据包，得到明文消息结构体
|
||
int DecryptMsg(const string &sMsgSignature, const string &sTimeStamp, const string &sNonce, const string &sPostData, string &sMsg);
|
||
参数说明
|
||
参数 必须 说明
|
||
sMsgSignature 是 从接收消息的URL中获取的msg_signature参数
|
||
sTimeStamp 是 从接收消息的URL中获取的timestamp参数
|
||
sNonce 是 从接收消息的URL中获取的nonce参数
|
||
sPostData 是 从接收消息的URL中获取的整个post数据
|
||
sMsg 是 用于返回解密后的msg，以xml组织，参见普通消息格式和事件消息格式
|
||
|
||
|
||
加密函数
|
||
本函数实现：
|
||
|
||
加密明文消息结构体
|
||
生成签名
|
||
构造被动响应包
|
||
int EncryptMsg(const string &sReplyMsg, const string &sTimeStamp, const string &sNonce, string &sEncryptMsg);
|
||
参数说明
|
||
参数 必须 说明
|
||
sReplyMsg 是 返回的消息体原文
|
||
sTimeStamp 是 时间戳，调用方生成
|
||
sNonce 是 随机数，调用方生成
|
||
sEncryptMsg 是 用于返回的密文，以xml组织，参见被动回复消息格式
|
||
|
||
|
||
原理详解
|
||
目前官方已提供了php、python、c++等版本的加解密库，如果开发者需要进行别的语言的开发，需要自行根据加解密原理实现算法。
|
||
|
||
消息体签名校验
|
||
为了让企业确认调用来自企业微信，企业微信在回调给接收消息url时会带上消息签名，以参数msg_signature标识，企业需要验证此参数的正确性后再解密。
|
||
验证步骤如下：
|
||
|
||
计算签名
|
||
dev_msg_signature=sha1(sort(token、timestamp、nonce、msg_encrypt))。
|
||
|
||
|
||
sort的含义是将参数值按照字母字典排序，然后从小到大拼接成一个字符串
|
||
sha1处理结果要编码为可见字符，编码的方式是把每字节散列值打印为%02x（即16进制，C printf语法）格式，全部小写
|
||
比较dev_msg_signature和msg_signature是否相等，相等则表示验证通过
|
||
在被动响应消息时，企业同样需要用如上方法生成签名并传给企业微信
|
||
|
||
|
||
明文msg的加密过程
|
||
拼接明文字符串
|
||
rand_msg = random(16B) + msg_len(4B) + msg + receiveid
|
||
|
||
|
||
明文字符串由16个字节的随机字符串、4个字节的msg长度、明文msg和receiveid拼接组成。其中msg_len为msg的字节数，网络字节序；sReceiveId 在不同场景下有不同含义，见附注
|
||
明文字符串
|
||
对明文字符串加密并Base64编码
|
||
msg_encrypt = Base64_Encode(AES_Encrypt(rand_msg))
|
||
|
||
|
||
将明文字符串AESKey加密后，再进行Base64编码，即获得密文msg_encrypt。
|
||
密文解密得到msg的过程
|
||
对密文BASE64解码
|
||
|
||
aes_msg=Base64_Decode(msg_encrypt)
|
||
|
||
使用AESKey做AES-256-CBC解密
|
||
|
||
rand_msg=AES_Decrypt(aes_msg)
|
||
|
||
去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
|
||
验证解密后的receiveid、msg_len。注意，receiveid在不同场景含义不同。
|
||
举例说明
|
||
假设在服务商管理端为某个套件有如下配置参数：
|
||
|
||
corpId = "wx5823bf96d3bd56c7"
|
||
token = "QDG6eK"
|
||
encodingAesKey = "jWmYm7qr5nMoAUwZRjGtBxmz3KA1tkAj3ykkR6q2B2C"
|
||
收到来自企业微信的回调为：
|
||
xml请求示例：
|
||
|
||
POST /cgi-bin/wxpush?msg_signature=477715d11cdb4164915debcba66cb864d751f3e6×tamp=1409659813&nonce=1372623149 HTTP/1.1
|
||
Host: qy.weixin.qq.com
|
||
Content-Length: 603
|
||
<xml>
|
||
<ToUserName><![CDATA[wx5823bf96d3bd56c7]]></ToUserName>
|
||
<Encrypt><![CDATA[RypEvHKD8QQKFhvQ6QleEB4J58tiPdvo+rtK1I9qca6aM/wvqnLSV5zEPeusUiX5L5X/0lWfrf0QADHHhGd3QczcdCUpj911L3vg3W/sYYvuJTs3TUUkSUXxaccAS0qhxchrRYt66wiSpGLYL42aM6A8dTT+6k4aSknmPj48kzJs8qLjvd4Xgpue06DOdnLxAUHzM6+kDZ+HMZfJYuR+LtwGc2hgf5gsijff0ekUNXZiqATP7PF5mZxZ3Izoun1s4zG4LUMnvw2r+KqCKIw+3IQH03v+BCA9nMELNqbSf6tiWSrXJB3LAVGUcallcrw8V2t9EL4EhzJWrQUax5wLVMNS0+rUPA3k22Ncx4XXZS9o0MBH27Bo6BpNelZpS+/uh9KsNlY6bHCmJU9p8g7m3fVKn28H3KDYA5Pl/T8Z1ptDAVe0lXdQ2YoyyH2uyPIGHBZZIs2pDBS8R07+qN+E7Q==]]></Encrypt>
|
||
<AgentID><![CDATA[218]]></AgentID>
|
||
</xml>
|
||
json请求示例：
|
||
注意这里的 tousername，encrypt，agentid均为小写
|
||
|
||
POST /cgi-bin/wxpush?msg_signature=477715d11cdb4164915debcba66cb864d751f3e6×tamp=1409659813&nonce=1372623149 HTTP/1.1
|
||
Host: qy.weixin.qq.com
|
||
Content-Length: 364
|
||
{
|
||
"tousername": "wx5823bf96d3bd56c7",
|
||
"encrypt": "No8isRLoXqFMhLlpe7R/DA7UbJ88DKJxDhJH/UVG3o1ib0Fhzdd3qWYHH/KL1mITv5qOCp2FbyILqfI7zazrp/ARgSHR177OCrv8O9UrMHWdnOaMXaz+mLd5X5VWm5r2J3Qpm+NdTQRPhHbce88frKF3wqTaZunKW7ae87bRZUfaq5tLFnyTsf6aiy0su3SsQ06dQGKPcHfYHY3upB881008Q9t9xeAZ/uqfXpYQgSLQfaX+fk/K/FQEl4QpLk94eD1YjluFY3uLnKp40zDyxgeWRAmgTtmx1eLwediVqZ8=",
|
||
"agentid": "218"
|
||
}
|
||
第一步：准备相关参数
|
||
|
||
AESKey = Base64_Decode(EncodingAESKey + "=")
|
||
signature = "477715d11cdb4164915debcba66cb864d751f3e6";
|
||
timestamps = "1409659813";
|
||
nonce = "1372623149";
|
||
msg_encrypt = "RypEvHKD8QQKFhvQ6QleEB4J58tiPdvo+rtK1I9qca6aM/wvqnLSV5zEPeusUiX5L5X/0lWfrf0QADHHhGd3QczcdCUpj911L3vg3W/sYYvuJTs3TUUkSUXxaccAS0qhxchrRYt66wiSpGLYL42aM6A8dTT+6k4aSknmPj48kzJs8qLjvd4Xgpue06DOdnLxAUHzM6+kDZ+HMZfJYuR+LtwGc2hgf5gsijff0ekUNXZiqATP7PF5mZxZ3Izoun1s4zG4LUMnvw2r+KqCKIw+3IQH03v+BCA9nMELNqbSf6tiWSrXJB3LAVGUcallcrw8V2t9EL4EhzJWrQUax5wLVMNS0+rUPA3k22Ncx4XXZS9o0MBH27Bo6BpNelZpS+/uh9KsNlY6bHCmJU9p8g7m3fVKn28H3KDYA5Pl/T8Z1ptDAVe0lXdQ2YoyyH2uyPIGHBZZIs2pDBS8R07+qN+E7Q==";
|
||
第二步：校验签名
|
||
|
||
token、timestamp、nonce、msg_encrypt 这四个参数按照字典序排序
|
||
|
||
"1372623149"
|
||
"1409659813"
|
||
"QDG6eK"
|
||
"RypEvHKD8QQKFhvQ6QleEB4J58tiPdvo+rtK1I9qca6aM/wvqnLSV5zEPeusUiX5L5X/0lWfrf0QADHHhGd3QczcdCUpj911L3vg3W/sYYvuJTs3TUUkSUXxaccAS0qhxchrRYt66wiSpGLYL42aM6A8dTT+6k4aSknmPj48kzJs8qLjvd4Xgpue06DOdnLxAUHzM6+kDZ+HMZfJYuR+LtwGc2hgf5gsijff0ekUNXZiqATP7PF5mZxZ3Izoun1s4zG4LUMnvw2r+KqCKIw+3IQH03v+BCA9nMELNqbSf6tiWSrXJB3LAVGUcallcrw8V2t9EL4EhzJWrQUax5wLVMNS0+rUPA3k22Ncx4XXZS9o0MBH27Bo6BpNelZpS+/uh9KsNlY6bHCmJU9p8g7m3fVKn28H3KDYA5Pl/T8Z1ptDAVe0lXdQ2YoyyH2uyPIGHBZZIs2pDBS8R07+qN+E7Q=="
|
||
|
||
拼接为一个字符串
|
||
|
||
sort_str = "13726231491409659813QDG6eKRypEvHKD8QQKFhvQ6QleEB4J58tiPdvo+rtK1I9qca6aM/wvqnLSV5zEPeusUiX5L5X/0lWfrf0QADHHhGd3QczcdCUpj911L3vg3W/sYYvuJTs3TUUkSUXxaccAS0qhxchrRYt66wiSpGLYL42aM6A8dTT+6k4aSknmPj48kzJs8qLjvd4Xgpue06DOdnLxAUHzM6+kDZ+HMZfJYuR+LtwGc2hgf5gsijff0ekUNXZiqATP7PF5mZxZ3Izoun1s4zG4LUMnvw2r+KqCKIw+3IQH03v+BCA9nMELNqbSf6tiWSrXJB3LAVGUcallcrw8V2t9EL4EhzJWrQUax5wLVMNS0+rUPA3k22Ncx4XXZS9o0MBH27Bo6BpNelZpS+/uh9KsNlY6bHCmJU9p8g7m3fVKn28H3KDYA5Pl/T8Z1ptDAVe0lXdQ2YoyyH2uyPIGHBZZIs2pDBS8R07+qN+E7Q=="
|
||
|
||
对该字符串进行sha1计算得到签名
|
||
|
||
signature = sha1(sort_str) = "477715d11cdb4164915debcba66cb864d751f3e6"
|
||
|
||
对比从URL得到的签名，发现两者一致，签名通过，说明没被篡改，是安全的
|
||
第三步： 解密消息
|
||
|
||
对密文base64解码
|
||
|
||
aes_msg = base64_decode(msg_encrypt)
|
||
|
||
使用AESKey做AES解密（注意，不是EncodingAESKey）
|
||
|
||
rand_msg = aes_decrypt(aes_msg, AESKey)
|
||
|
||
去掉rand_msg头部的16个随机字节和4个字节的msg_len，截取msg_len长度的部分即为msg，剩下的为尾部的receiveid
|
||
下面为类似python的伪代码
|
||
|
||
content = rand_msg[16:] # 去掉前16随机字节
|
||
msg_len = str_to_uint(content[0:4]) # 取出4字节的msg_len
|
||
msg = content[4:msg_len+4] # 截取msg_len 长度的msg
|
||
receiveid = content[msg_len+4:] = "wx5823bf96d3bd56c7" # 剩余字节为receiveid
|
||
|
||
|
||
对于回调xml解密后得到明文为：
|
||
|
||
<xml>
|
||
<ToUserName><![CDATA[wx5823bf96d3bd56c7]]></ToUserName>
|
||
<FromUserName><![CDATA[mycreate]]></FromUserName>
|
||
<CreateTime>1409659813</CreateTime>
|
||
<MsgType><![CDATA[text]]></MsgType>
|
||
<Content><![CDATA[hello]]></Content>
|
||
<MsgId>4561255354251345929</MsgId>
|
||
<AgentID>218</AgentID>
|
||
</xml>
|
||
|
||
对于回调json解密后的明文为：
|
||
{
|
||
"ToUserName": "wx5823bf96d3bd56c7",
|
||
"FromUserName": "mycreate",
|
||
"CreateTime": "1409659813",
|
||
"MsgType": "text",
|
||
"Content": "hello",
|
||
"MsgId": "4561255354251345929",
|
||
"AgentID": "218"
|
||
}
|
||
|
||
|
||
根据明文中的MsgType可知，此为应用消息回调，因此receiveid应该为corpid，对比receiveid与corpid是否一致。
|
||
附注：ReceiveId 含义
|
||
加解密库里，ReceiveId 在各个场景的含义不同：
|
||
|
||
企业应用的回调，表示corpid
|
||
第三方事件的回调，表示suiteid
|
||
机器人场景的回调，是一个空字符串 |