搭建查券公众号后台：微信 XML 消息加解密与 AES 容错机制深度踩坑记录-编程实验室

搭建查券公众号后台：微信 XML 消息加解密与 AES 容错机制深度踩坑记录

大家好，我是微赚淘客系统3.0 的研发者省赚客！

在接入微信公众号“消息加解密”模式（安全模式）时，我们遭遇了大量因AES/CBC/PKCS7Padding实现差异、Base64 编码不一致、XML 特殊字符转义等问题导致的验签失败。本文复盘真实生产环境中的典型坑点，并给出基于 JDK 原生加密库的完整容错实现。

一、微信加解密流程回顾

用户发送消息 → 微信服务器使用AES 加密（CBC 模式 + PKCS7 填充）；
推送至开发者服务器，携带msg_signature、timestamp、nonce、encrypt_type；
开发者需：
- 用token、timestamp、nonce、msg_encrypt生成 SHA1 签名；
- 验证签名一致后，解密 msg_encrypt得到原始 XML；
回复消息也需加密并返回。

关键参数：

EncodingAESKey：43 字节 Base64 字符串（实际为 32 字节 AES 密钥 + 1 字节随机填充）；
AppID：用于验证解密内容完整性。

二、JDK 原生 AES 解密实现（含 PKCS7）

Java 默认不支持 PKCS7，但PKCS5 与 PKCS7 在 16 字节块下等价，可直接使用：

packagejuwatech.cn.wx.crypto;importjavax.crypto.Cipher;importjavax.crypto.spec.IvParameterSpec;importjavax.crypto.spec.SecretKeySpec;importjava.nio.charset.StandardCharsets;importjava.util.Arrays;publicclassWxAesDecryptor{publicstaticStringdecrypt(StringencryptedMsg,StringencodingAesKey,StringappId){byte[]aesKey=Base64.getDecoder().decode(encodingAesKey+"=");// 补齐 Base64 paddingif(aesKey.length!=32){thrownewIllegalArgumentException("AES key must be 32 bytes");}byte[]encryptedData=Base64.getDecoder().decode(encryptedMsg);SecretKeySpeckeySpec=newSecretKeySpec(aesKey,"AES");IvParameterSpeciv=newIvParameterSpec(Arrays.copyOfRange(aesKey,0,16));try{Ciphercipher=Cipher.getInstance("AES/CBC/NoPadding");// 注意：不能用 PKCS5Paddingcipher.init(Cipher.DECRYPT_MODE,keySpec,iv);byte[]decrypted=cipher.doFinal(encryptedData);// 手动去除 PKCS7 填充intpad=decrypted[decrypted.length-1]&0xFF;if(pad<1||pad>32){thrownewRuntimeException("Invalid PKCS7 padding");}decrypted=Arrays.copyOfRange(decrypted,0,decrypted.length-pad);// 提取明文结构：[16B random][xmlLen(4B)][xml][appId]intxmlLen=bytesToIntBigEndian(decrypted,16);StringxmlContent=newString(decrypted,20,xmlLen,StandardCharsets.UTF_8);StringextractedAppId=newString(decrypted,20+xmlLen,decrypted.length-20-xmlLen,StandardCharsets.UTF_8);if(!extractedAppId.equals(appId)){thrownewRuntimeException("AppID mismatch: expected="+appId+", got="+extractedAppId);}returnxmlContent;}catch(Exceptione){thrownewRuntimeException("AES decrypt failed",e);}}privatestaticintbytesToIntBigEndian(byte[]src,intoffset){return((src[offset]&0xFF)<<24)|((src[offset+1]&0xFF)<<16)|((src[offset+2]&0xFF)<<8)|(src[offset+3]&0xFF);}}

踩坑点 1：Cipher.getInstance("AES/CBC/PKCS5Padding")会导致解密后多出 16 字节乱码，因为微信使用的是NoPadding + 手动 PKCS7，必须手动去填充。

三、Base64 编码兼容性处理

微信官方 SDK 使用Apache Commons Codec的 Base64，而 JDK 的Base64.getDecoder()对缺失 padding（=）敏感。

踩坑点 2：EncodingAESKey 是 43 字节字符串（无=），直接解码会抛IllegalArgumentException。

解决方案：自动补全 padding：

privatestaticStringensureBase64Padding(Stringinput){intmod=input.length()%4;if(mod==0)returninput;returninput+"==".substring(mod);}

调用时：

byte[]aesKey=Base64.getDecoder().decode(ensureBase64Padding(encodingAesKey));

四、XML 特殊字符转义容错

用户输入可能包含<,>,&等字符，微信加密前会进行 XML 转义，但部分第三方工具未转义，导致解密后解析失败。

踩坑点 3：解密得到的 XML 包含未转义的&，DOM 解析报错The entity name must immediately follow the '&' in the entity reference。

容错方案：预处理非法字符：

publicstaticStringsanitizeXml(Stringxml){returnxml.replace("&","&amp;").replace("<","&lt;").replace(">","&gt;").replace("\"","&quot;").replace("'","&apos;");}

但注意：仅在确定原始内容未转义时使用，否则会双重转义。更安全的做法是捕获解析异常后重试：

Documentdoc;try{doc=DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(newInputSource(newStringReader(xml)));}catch(SAXParseExceptione){// 尝试修复StringfixedXml=xml.replaceAll("&(?!(amp|lt|gt|quot|apos);)","&amp;");doc=DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(newInputSource(newStringReader(fixedXml)));}

五、签名验证容错

微信计算msg_signature的顺序为：sha1(sort(token, timestamp, nonce, msg_encrypt))。

踩坑点 4：msg_encrypt是 Base64 字符串，但部分开发者误传原始字节数组的 Hex 或 URL 编码。

正确实现：

publicstaticbooleanverifySignature(Stringtoken,Stringtimestamp,Stringnonce,StringmsgEncrypt,Stringsignature){String[]arr=newString[]{token,timestamp,nonce,msgEncrypt};Arrays.sort(arr);Stringcontent=String.join("",arr);StringcalcSig=DigestUtils.sha1Hex(content);returncalcSig.equals(signature);}

其中msgEncrypt必须是微信 POST 中的<Encrypt>标签内的原始 Base64 字符串（含换行需 trim）。

六、完整 Controller 示例

@RestControllerpublicclassWxMessageController{@PostMapping("/wx/callback")publicStringhandleWxMessage(@RequestParamStringsignature,@RequestParamStringtimestamp,@RequestParamStringnonce,@RequestParamStringencrypt_type,@RequestBodyStringrequestBody){if(!"aes".equals(encrypt_type)){thrownewIllegalArgumentException("Only aes supported");}// 1. 提取 <Encrypt> 内容StringencryptedMsg=extractTagValue(requestBody,"Encrypt");// 2. 验签if(!WxSignatureUtil.verifySignature("your_token",timestamp,nonce,encryptedMsg,signature)){thrownewSecurityException("Invalid signature");}// 3. 解密Stringxml=WxAesDecryptor.decrypt(encryptedMsg,"your_encoding_aes_key","your_appid");// 4. 处理业务（如查券）Stringreply=CouponService.handle(xml);// 5. 加密回复（略，对称流程）returnbuildEncryptedResponse(reply);}privateStringextractTagValue(Stringxml,StringtagName){intstart=xml.indexOf("<"+tagName+">")+tagName.length()+2;intend=xml.indexOf("</"+tagName+">");returnxml.substring(start,end).trim();}}