WeChat Enterprise Account Development: Encryption Scheme and Global Return Code Description

This article includes the detailed scheme for encryption and decryption when the enterprise account calls back to the enterprise, the download of libraries and sample codes, and the error codes returned by the enterprise account API interface.

1. Detailed description of encryption and decryption scheme

1. Terminology and description

When enabling callback mode, there are the following terms to understand:

1) msg_signature is a signature used to verify the legitimacy of the caller

2) EncodingAESKey is used to encrypt the message body. The length is fixed at 43 characters. It is selected from az, AZ, 0-9, a total of 62 characters. It is the Base64 encoding of AESKey. After decoding, it is a 32-byte AESKey.

3) AESKey = Base64_Decode (EncodingAESKey + "="), which is the key of the AES algorithm, with a length of 32 bytes. AES uses CBC mode, and the data is padded with PKCS#7; the size of the IV initial vector is 16 bytes, which is the first 16 bytes of AESKey. For details, see: http://tools.ietf.org/html/rfc2315

4) msg ​​is the plain text of the message body, in XML format

5) msg_encrypt = Base64_Encode( AES_Encrypt[random(16B) + msg_len(4B) + msg + $CorpID] ), is the Base64 encoding of the encrypted plaintext message msg

2. Message body signature

In order to verify the legitimacy of the caller, WeChat adds a message signature to the callback URL, marked by the parameter msg_signature. Enterprises need to verify the correctness of this parameter before decrypting it. Verification steps:

1) Enterprise calculation signature: dev_msg_signature = sha1(sort(Token, timestamp, nonce, msg_encrypt)). The meaning of sort is to sort the parameters in alphabetical order and then concatenate them into a string from small to large.

2) Compare dev_msg_signature and msg_signature to see if they are equal. If they are equal, verification is successful.

3. Encryption and decryption scheme description

• The process of encrypting the plaintext msg is as follows:

msg_encrypt = Base64_Encode( AES_Encrypt[random(16B) + msg_len(4B) + msg + $CorpID] )

The AES encrypted buf consists of a 16-byte random string, a 4-byte msg length, plain text msg, and $CorpID. Among them, msg_len is the number of bytes of msg, in network byte order; $CorpID is the CorpID of the enterprise number. After being encrypted by AESKey, it is then Base64 encoded to obtain the ciphertext msg_encrypt.

• Corresponding to the encryption scheme, the decryption scheme is as follows:

1) Decode the ciphertext BASE64: aes_msg=Base64_Decode(msg_encrypt)

2) Use AESKey to do AES decryption: rand_msg = AES_Decrypt(aes_msg)

3) Verify the decrypted $CorpID, msg_len

4) Remove the 16 random bytes at the head of rand_msg, the 4 bytes of msg_len, and the $CorpID at the end to get the final message body msg.

#p#

2. Download encryption and decryption library and return code

1. Return code of encryption and decryption library

2. Download encryption and decryption library and examples

• C++ library (click to download)

Note:

1) WXBizMsgCrypt.h declares the WXBizMsgCrypt class, which provides three interfaces for users to access WeChat for Business. The WXBizMsgCrypt.cpp file provides the implementation of the three interfaces. The Sample.cpp file provides examples of how to use the three interfaces.

2) The WXBizMsgCrypt class encapsulates the three interfaces of VerifyURL, DecryptMsg, and EncryptMsg, which are used by developers to verify the callback URL, decrypt the user's reply message, and encrypt the developer's reply message. For usage, please refer to the Sample.cpp file.

3) For the encryption and decryption protocols, please refer to the official WeChat Enterprise documentation.

4) The encryption and decryption process uses the open source openssl and tinyxml2 libraries. Developers are requested to install them before use.

*The version number of openssl is openssl-1.0.1h, http://www.openssl.org/

*The version number of tinyxml2 is tinyxml2-2.1.0, https://github.com/leethomason/tinyxml2

• Python library (click to download)

Note:

1) The WXBizMsgCrypt.py file encapsulates the WXBizMsgCrypt interface class and provides three interfaces for users to access WeChat for Business. The Sample.py file provides examples of how to use these three interfaces, and ierror.py provides error codes.

2) WXBizMsgCrypt encapsulates the three interfaces of VerifyURL, DecryptMsg, and EncryptMsg, which are used by developers to verify the callback URL, decrypt received messages, and encrypt developer reply messages. For usage, please refer to the Sample.py file.

3) This code uses the pycrypto third-party library. Developers are requested to install this library before using it.

• PHP library (click to download)

Note:

1) The WXBizMsgCrypt.php file provides the implementation of the WXBizMsgCrypt class, which is the interface class for users to access enterprise WeChat. Sample.php provides examples for developers to refer to. errorCode.php, pkcs7Encoder.php, sha1.php, xmlparse.php files are auxiliary classes for implementing this class, and developers do not need to care about their specific implementation.

2) The WXBizMsgCrypt class encapsulates the three interfaces of VerifyURL, DecryptMsg, and EncryptMsg, which are used by developers to verify the callback URL, decrypt received messages, and encrypt developer reply messages. For usage, please refer to the Sample.php file.

• Java library (click to download)

Note:

1) The com\qq\weixin\mp\aes directory contains the interfaces that users need to use to access WeChat for Business. The WXBizMsgCrypt class provided by the WXBizMsgCrypt.java file encapsulates the three interfaces for users to access WeChat for Business. Other class files are used by users to implement encryption and decryption, and users do not need to care about them. The sample.java file provides examples of how to use the interface.

2) WXBizMsgCrypt encapsulates the three interfaces of VerifyURL, DecryptMsg, and EncryptMsg, which are used by developers to verify the callback URL, decrypt received messages, and encrypt developer reply messages. For usage, please refer to the Sample.java file.

3) Developers are requested to use jdk1.7 or above. For org.apache.commons.codec.binary.Base64, you need to import the jar package commons-codec-1.9 (or other versions such as commons-codec-1.8), which we have provided. The official download address is:

http://commons.apache.org/proper/commons-codec/download_codec.cgi

4) Solution to the exception java.security.InvalidKeyException:illegal Key Size:

Download the JCE unlimited permissions policy file from the official website (download address for JDK7:

http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

After downloading and unzipping, you can see local_policy.jar, US_export_policy.jar and readme.txt. If JRE is installed, put the two jar files in the %JRE_HOME%\lib\security directory to overwrite the original files. If JDK is installed, put the two jar files in the %JDK_HOME%\jre\lib\security directory to overwrite the original files.

• C# library (click to download)

Note:

1) The Cryptography.cs file encapsulates the AES encryption and decryption process, and users do not need to care about the specific implementation. The WXBizMsgCrypt.cs file provides three interfaces for users to access WeChat for Business, and the Sample.cs file provides examples of how to use these three interfaces.

2) WXBizMsgCrypt.cs encapsulates the three interfaces of VerifyURL, DecryptMsg, and EncryptMsg, which are used by developers to verify the callback URL, decrypt the received message, and encrypt the developer's reply message. For usage, please refer to the Sample.cs file.

#p#

3. Global return code description

Each time an enterprise calls an interface, it may get a correct or incorrect return code. The enterprise can debug the interface and troubleshoot errors based on the return code information.

The global return codes are described as follows: