何使用示例代碼接入加解密及技術方案
如何使用示例代碼接入加解密,參考本文檔并使用示例代碼,加解密的接入將非常簡單。若想進一步的了解細節,請查看技術方案。 微信公眾平臺提供了C++、php、Java、Python和C# 5種語言的示例代碼,每種語言的類名和接口名均一致,下面以C++為例說明:
函數說明
構造函數
- // @param sToken: 公眾平臺上,開發者設置的Token
- // @param sEncodingAESKey: 公眾平臺上,開發者設置的EncodingAESKey
- // @param sAppid: 公眾號的appid
- WXBizMsgCrypt(const std::string &sToken,
- const std::string &sEncodingAESKey,
- const std::string &sAppid);
解密函數
- // 檢驗消息的真實性,并且獲取解密后的明文
- // @param sMsgSignature: 簽名串,對應URL參數的msg_signature
- // @param sTimeStamp: 時間戳,對應URL參數的timestamp
- // @param sNonce: 隨機串,對應URL參數的nonce
- // @param sPostData: 密文,對應POST請求的數據
- // @param sMsg: 解密后的明文,當return返回0時有效
- // @return: 成功0,失敗返回對應的錯誤碼
- int DecryptMsg(const std::string &sMsgSignature,
- const std::string &sTimeStamp,
- const std::string &sNonce,
- const std::string &sPostData,
- std::string &sMsg);
加密函數
- //將公眾號回復用戶的消息加密打包
- // @param sReplyMsg:公眾號待回復用戶的消息,xml格式的字符串
- // @param sTimeStamp: 時間戳,可以自己生成,也可以用URL參數的timestamp
- // @param sNonce: 隨機串,可以自己生成,也可以用URL參數的nonce
- // @param sEncryptMsg: 加密后的可以直接回復用戶的密文,包括msg_signature, timestamp, nonce, encrypt的xml格式的字符串,當return返回0時有效
- // return:成功0,失敗返回對應的錯誤碼
- int EncryptMsg(const std::string &sReplyMsg,
- const std::string &sTimeStamp,
- const std::string &sNonce,
- std::string &sEncryptMsg);
使用方法
在安全模式或兼容模式下,url上會新增兩個參數encrypt_type和msg_signature。encrypt_type表示加密類型,msg_signature:表示對消息體的簽名。 url上無encrypt_type參數或者其值為raw時表示為不加密;encrypt_type為aes時,表示aes加密(暫時只有raw和aes兩種值)。公眾帳號開發者根據此參數來判斷微信公眾平臺發送的消息是否加密。
兼容模式和安全模式加解密的方法完全一樣,兼容模式的xml消息體比安全模式多了幾個明文字段,具體請查看《消息加解密詳細技術方案》。
實例化對象
使用構造函數,實例化一個對象,傳入公眾帳號的token, appid, EncodingAESKey。
解密
安全模式或者兼容模式下,公眾號收到以下帶密文消息體(“……”表示兼容模式下的明文字段):
- encrypt_msg =
- <xml>
- <ToUserName><![CDATA[gh_10f6c3c3ac5a]]></ToUserName>
- ……
- <Encrypt><![CDATA[hQM/NS0ujPGbF+/8yVe61E3mUVWVO1izRlZdyv26zrVUSE3zUEBdcXITxjbjiHH38kexVdpQLCnRfbrqny1yGvgqqKTGKxJWWQ9D5WiiUKxavHRNzYVzAjYkp7esNGy7HJcl/P3BGarQF3+AWyNQ5w7xax5GbOwiXD54yri7xmNMHBOHapDzBslbnTFiEy+8sjSl4asNbn2+ZVBpqGsyKDv0ZG+DlSlXlW+gNPVLP+YxeUhJcyfp91qoa0FJagRNlkNul4mGz+sZXJs0WF7lPx6lslDGW3J66crvIIx/klpl0oa/tC6n/9c8OFQ9pp8hrLq7B9EaAGFlIyz5UhVLiWPN97JkL6JCfxVooVMEKcKRrrlRDGe8RWVM3EW/nxk9Ic37lYY5j97YZfq375AoTBdGDtoPFZsvv3Upyut1i6G0JRogUsMPlyZl9B8Pl/wcA7k7i4LYMr2yK4SxNFrBUw==]]></Encrypt>
- </xml>
調用DecryptMsg接口,傳入收到的url上的參數:msg_signature(注意:不是signature,而是msg_signature), timestamp, nonce和接收到的encrypt_msg,若調用成功,sMsg則為輸出結果,其內容為如下的明文的xml消息體:
- <xml>
- <ToUserName><![CDATA[gh_10f6c3c3ac5a]]></ToUserName>
- <FromUserName><![CDATA[oyORnuP8q7ou2gfYjqLzSIWZf0rs]]></FromUserName>
- <CreateTime>1411035097</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[this is a test message]]></Content>
- <MsgId>6060349595123187712</MsgId>
- </xml>
#p#
公眾帳號處理消息
生成需要回復給微信公眾平臺的xml消息體,假設回復以下內容:
- res_msg =
- <xml>
- <ToUserName><![CDATA[oyORnuP8q7ou2gfYjqLzSIWZf0rs]]></ToUserName>
- <FromUserName><![CDATA[gh_10f6c3c3ac5a]]></FromUserName>
- <CreateTime>1411034505</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[Welcome to join us!]]></Content>
- <FuncFlag>0</FuncFlag>
- </xml>
回包加密
調用EncryptMsg接口,傳入需要回復給微信公眾平臺的res_msg, timestamp, nonce,若加密成功,則sEncryptMsg為密文消息體,內容如下:
- <xml>
- <Encrypt><![CDATA[LDFAmKFr7U/RMmwRbsR676wjym90byw7+hhh226e8bu6KVYy00HheIsVER4eMgz/VBtofSaeXXQBz6fVdkN2CzBUaTtjJeTCXEIDfTBNxpw/QRLGLqqMZHA3I+JiBxrrSzd2yXuXst7TdkVgY4lZEHQcWk85x1niT79XLaWQog+OnBV31eZbXGPPv8dZciKqGo0meTYi+fkMEJdyS8OE7NjO79vpIyIw7hMBtEXPBK/tJGN5m5SoAS6I4rRZ8Zl8umKxXqgr7N8ZOs6DB9tokpvSl9wT9T3E62rufaKP5EL1imJUd1pngxy09EP24O8Th4bCrdUcZpJio2l11vE6bWK2s5WrLuO0cKY2GP2unQ4fDxh0L4ePmNOVFJwp9Hyvd0BAsleXA4jWeOMw5nH3Vn49/Q/ZAQ2HN3dB0bMA+6KJYLvIzTz/Iz6vEjk8ZkK+AbhW5eldnyRDXP/OWfZH2P3WQZUwc/G/LGmS3ekqMwQThhS2Eg5t4yHv0mAIei07Lknip8nnwgEeF4R9hOGutE9ETsGG4CP1LHTQ4fgYchOMfB3wANOjIt9xendbhHbu51Z4OKnA0F+MlgZomiqweT1v/+LUxcsFAZ1J+Vtt0FQXElDKg+YyQnRCiLl3I+GJ/cxSj86XwClZC3NNhAkVU11SvxcXEYh9smckV/qRP2Acsvdls0UqZVWnPtzgx8hc8QBZaeH+JeiaPQD88frNvA==]]></Encrypt>
- <MsgSignature><![CDATA[8d9521e63f84b2cd2e0daa124eb7eb0c34b6204a]]></MsgSignature>
- <TimeStamp>1411034505</TimeStamp>
- <Nonce><![CDATA[1351554359]]></Nonce>
- </xml>
注意事項
EncodingAESKey長度固定為43個字符,從a-z,A-Z,0-9共62個字符中選取。 公眾帳號可以在公眾平臺的開發者中心的服務器配置修改
出于安全考慮,公眾平臺網站提供了修改EncodingAESKey的功能(在EncodingAESKey可能泄漏時進行修改),所以建議公眾賬號保存當前的和上一次的EncodinAESKey,若當前EncodingAESKey解密失敗,則嘗試用上一次的EncodingAESKey的解密?;匕鼤r,用哪個Key解密成功,則用此Key加密對應的回包
兼容模式消息體同時存在明文和密文,消息體會增至以前的3倍左右,開發者注意檢查系統,防止因消息變長和URL參數增加而出現接收錯誤
如果url上無encrypt_type參數或者其值為raw,則回復明文,否則回復密文。兼容模式期間公眾賬號回復明文或密文均可(不要兩種類型都回)
函數錯誤返回碼
#p#
示例代碼下載
微信公眾平臺為開發者提供了5種語言的示例代碼(包括C++、php、Java、Python和C#版本) 點擊下載 ../static/assets/a5a22f38cb60228cb32ab61d9e4c414b.zip
微信公眾平臺接口調試工具
點擊進入 http://mp.weixin.qq.com/debug
技術方案
1. EncodingAESKey長度固定為43個字符,從a-z,A-Z,0-9共62個字符中選取,公眾帳號可以在公眾平臺的開發者中心的服務器配置修改;
2. AES密鑰:AESKey=Base64_Decode(EncodingAESKey + “=”),EncodingAESKey尾部填充一個字符的“=”, 用Base64_Decode生成32個字節的AESKey;
3. AES采用CBC模式,秘鑰長度為32個字節,數據采用PKCS#7填充;PKCS#7:K為秘鑰字節數(采用32),buf為待加密的內容,N為其字節數。Buf需要被填充為K的整數倍。在buf的尾部填充(K-N%K)個字節,每個字節的內容是(K- N%K);
具體詳見:http://tools.ietf.org/html/rfc2315
5. 出于安全考慮,公眾平臺網站提供了修改EncodingAESKey的功能(在EncodingAESKey可能泄漏時進行修改),所以建議公眾賬號保存當前的和上一次的EncodingAESKey,若當前EncodingAESKey生成的AESKey解密失敗,則嘗試用上一次的AESKey的解密?;匕鼤r,用哪個AESKey解密成功,則用此AESKey加密對應的回包;
6. 兼容模式消息體同時存在明文和密文,消息體會增至以前的3倍左右,開發者注意檢查系統,防止因消息變長和URL參數增加而出現接收錯誤;
7. 微信團隊提供了多種語言的示例代碼(包括php、Java、C++、Python、C#),請開發者盡量使用示例代碼。(../static/assets/a5a22f38cb60228cb32ab61d9e4c414b.zip )
下面以普通文本消息為例,詳細說明公眾平臺對消息體加解密的方法和流程,其它普通消息和事件消息的加解密可以此類推。
公眾賬號接收用戶消息
消息體加密
現有消息為明文,格式如下:
- msg =
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1348831860</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[this is a test]]></Content>
- <MsgId>1234567890123456</MsgId>
- </xml>
兼容模式期間同時保留明文和密文,消息格式如下:
- new_msg=
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>1348831860</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[this is a test]]></Content>
- <MsgId>1234567890123456</MsgId>
- <Encrypt><![CDATA[msg_encrypt]]</Encrypt>
- </xml>
安全模式下,消息體只有密文,格式如下:
- new_msg=
- <xml>
- <ToUserName><![CDATA[toUser]]</ToUserName>
- <Encrypt><![CDATA[msg_encrypt]]</Encrypt>
- </xml>
- 其中,msg_encrypt = Base64_Encode( AES_Encrypt[ random(16B) + msg_len(4B) + msg + $AppId] )
AES加密的buf由16個字節的隨機字符串、4個字節的msg_len(網絡字節序)、msg和$AppId組成,其中msg_len為msg的長度,$AppId為公眾帳號的AppId
AESKey =Base64_Decode(EncodingAESKey + “=”),32個字節
url上增加參數encrypt_type,encrypt_type的值為raw時表示為不加密,encrypt_type的值為aes時,表示aes加密(暫時只有raw和aes兩種值),無encrypt_type參數同樣表示不加密
消息體簽名
為了驗證消息體的合法性,公眾平臺新增消息體簽名,開發者可用以驗證消息體的真實性,并對驗證通過的消息體進行解密
在url上增加參數:msg_signature
msg_signature=sha1(sort(Token、timestamp、nonce, msg_encrypt))
消息體驗證和解密
開發者先驗證消息體簽名的正確性,驗證通過后,再對消息體進行解密。
驗證方式
1. 開發者計算簽名,dev_msg_signature=sha1(sort(Token、timestamp、nonce, msg_encrypt))
2. 比較dev_msg_signature和URL上帶的msg_signature是否相等,相等則表示驗證通過
解密方式如下:
- 1. aes_msg=Base64_Decode(msg_encrypt)
- 2. rand_msg=AES_Decrypt(aes_msg)
- 3. 驗證尾部$AppId是否是自己的AppId,相同則表示消息沒有被篡改,這里進一步加強了消息簽名驗證
- 4. 去掉rand_msg頭部的16個隨機字節,4個字節的msg_len,和尾部的$AppId即為最終的xml消息體
公眾賬號向用戶回復消息
如果url上無encrypt_type或者其值為raw,則回復明文,否則按照上述的加密算法加密回復密文。兼容模式期間公眾賬號回復明文或密文均可(不要兩種類型都回)
回復消息體的簽名與加密
現有消息格式:
- msg=
- <xml>
- <ToUserName><![CDATA[toUser]]></ToUserName>
- <FromUserName><![CDATA[fromUser]]></FromUserName>
- <CreateTime>12345678</CreateTime>
- <MsgType><![CDATA[text]]></MsgType>
- <Content><![CDATA[你好]]></Content>
- </xml>
加密后消息格式:
- new_msg=
- <xml>
- <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
- <MsgSignature><![CDATA[msg_signature]]></MsgSignature>
- <TimeStamp>timestamp</TimeStamp>
- <Nonce><![CDATA[nonce]]></Nonce>
- </xml>
其中,msg_encrypt=Base64_Encode(AES_Encrypt [random(16B)+ msg_len(4B) + msg + $AppId])
random(16B)為16字節的隨機字符串;msg_len為msg長度,占4個字節(網絡字節序),$AppId為公眾賬號的AppId
AESKey =Base64_Decode(EncodingAESKey + “=”),32個字節
msg_signature=sha1(sort(Token、timestamp、nonce, msg_encrypt))
timestamp、nonce回填請求中的值或者重新生成均可