PHP开发者必看：招商银行SM2国密支付对接实战（附完整代码）

原创

于 2026-03-06 05:39:29 发布 · 358 阅读

标签

PHP开发者实战指南：深入解析招商银行国密支付对接的核心技术与避坑实践

最近在对接招商银行的支付接口时，我遇到了一个让很多PHP开发者头疼的问题——国密算法SM2的实现。不同于常见的RSA加密，SM2作为国家密码管理局发布的非对称加密算法，在金融领域应用越来越广泛，但PHP生态中的支持却相对薄弱。经过几周的摸索和调试，我整理出了一套完整的解决方案，希望能帮助正在或即将面临同样挑战的开发者。

招商银行的支付接口采用了SM2withSM3签名算法，这种组合在安全性上比传统的RSA更强，但实现起来也确实更复杂。最大的难点在于，银行提供的示例代码通常是Java或C#版本，而PHP社区中可用的国密库相对较少，且文档不够完善。更让人头疼的是，不同银行对SM2的实现细节还有差异，直接套用通用库往往无法通过银行的验签。

1. 环境准备与依赖选择

在开始编码之前，我们需要确保开发环境满足国密算法的基础要求。虽然PHP 7.2以上版本理论上可以支持，但我建议使用PHP 7.4或更高版本，因为某些扩展在低版本中可能存在兼容性问题。

1.1 系统依赖检查

首先检查系统是否安装了GMP扩展，这是处理大整数运算的基础：

php -m | grep gmp

如果没有输出，需要安装GMP扩展。在Ubuntu/Debian系统中：

sudo apt-get install php-gmp

在CentOS/RHEL系统中：

sudo yum install php-gmp

1.2 Composer包选择

经过多次尝试，我发现lpilp/guomi是目前最稳定的PHP国密算法库。虽然它还有一些小问题，但社区活跃度相对较高，而且有开发者专门为招商银行的对接做了适配。

composer require lpilp/guomi

安装完成后，检查依赖是否完整：

<?php
require 'vendor/autoload.php';

// 测试SM2是否可用
if (class_exists('Rtgm\sm\RtSm2')) {
    echo "SM2类加载成功\n";
} else {
    echo "SM2类加载失败，请检查安装\n";
}

// 测试SM4是否可用  
if (class_exists('Rtgm\sm\RtSm4')) {
    echo "SM4类加载成功\n";
} else {
    echo "SM4类加载失败，请检查安装\n";
}

注意：有些服务器环境可能需要额外安装php-bcmath扩展来处理大数运算，如果遇到数字精度问题，记得检查这个扩展。

1.3 密钥格式处理

招商银行提供的密钥通常是Base64编码格式，但不同的接口可能要求不同的格式。这是我踩过的第一个坑——密钥格式处理不当会导致签名验证失败。

银行提供的密钥通常长这样：

私钥：NBtl7WnuUtA2v5FaebEkU0/Jj1IodLGT6lQqwkzmd2E=
公钥：BNsIe9U0x8IeSe4h/dxUzVEz9pie0hDSfMRINRXc7s1UIXfkExnYECF4QqJ2SnHxLv3z/99gsfDQrQ6dzN5lZj0=

但lpilp/guomi库在处理时需要特别注意格式转换。公钥通常包含一个标准头，需要正确处理：

function processPublicKey($base64PublicKey) {
    // Base64解码
    $decoded = base64_decode($base64PublicKey);
    
    // 转换为十六进制
    $hex = bin2hex($decoded);
    
    // 招商银行的公钥通常是138位十六进制字符串
    // 前22字节（44个十六进制字符）是标准头，需要去掉
    if (strlen($hex) === 138) {
        // 去掉前44个字符（22字节）的标准头
        $actualKey = substr($hex, 44);
    } else {
        // 如果不是138位，可能是其他格式
        $actualKey = $hex;
    }
    
    return $actualKey;
}

// 使用示例
$publicKey = 'BNsIe9U0x8IeSe4h/dxUzVEz9pie0hDSfMRINRXc7s1UIXfkExnYECF4QqJ2SnHxLv3z/99gsfDQrQ6dzN5lZj0=';
$processedKey = processPublicKey($publicKey);
echo "处理后的公钥（十六进制）：" . $processedKey . "\n";

2. SM2签名生成：从理论到实践

SM2签名与RSA签名在流程上有很大不同。SM2是基于椭圆曲线密码学（ECC）的算法，而RSA是基于大数分解。SM2withSM3意味着先用SM3算法对数据进行哈希，然后用SM2私钥对哈希值进行签名。

2.1 签名前的数据准备

招商银行对签名字符串有严格的要求，必须按照ASCII码顺序对参数进行排序，并去除空格和换行符：

function buildSignString($data) {
    if (is_array($data)) {
        // 按照键名ASCII码升序排序
        ksort($data);
        
        $parts = [];
        foreach ($data as $key => $value) {
            if ($value === null || $value === '') {
                continue;
            }
            
            if (is_array($value)) {
                // 递归处理嵌套数组
                $value = buildSignString($value);
            }
            
            $parts[] = $key . '=' . $value;
        }
        
        return implode('&', $parts);
    }
    
    // 如果是JSON字符串，先解码再处理
    if (is_string($data) && $data[0] === '{') {
        $decoded = json_decode($data, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            return buildSignString($decoded);
        }
    }
    
    return $data;
}

// 示例数据
$requestData = [
    'request' => [
        'head' => [
            'funcode' => 'NTDUMADD',
            'reqid' => '202206021511010000001',
            'userid' => 'B000001631'
        ],
        'body' => [
            'ntbusmody' => [
                ['busmod' => '00001']
            ],
            'ntdumaddx1' => [
                [
                    'bbknbr' => '75',
                    'dyanam' => '招商测试',
                    'dyanbr' => '11111111111',
                    'eftdat' => '20220602',
                    'inbacc' => '755936020410404',
                    'ovrctl' => 'N',
                    'yurref' => '596620626253316098'
                ]
            ]
        ]
    ],
    'signature' => [
        'sigdat' => '__signature_sigdat__',
        'sigtim' => '20220602161503'
    ]
];

$signString = buildSignString($requestData);
echo "待签名字符串：" . $signString . "\n";

2.2 用户ID处理

SM2签名需要一个用户ID参数，招商银行要求使用16字节的用户ID。如果用户ID不足16字节，需要用0填充；如果超过16字节，需要截断：

function formatUserId($userId) {
    // 确保用户ID为16字节
    if (strlen($userId) < 16) {
        // 右侧填充0
        return str_pad($userId, 16, "\0", STR_PAD_RIGHT);
    } elseif (strlen($userId) > 16) {
        // 截断到16字节
        return substr($userId, 0, 16);
    }
    
    return $userId;
}

// 实际使用中，招商银行通常要求这样处理
$originalUserId = 'B000001631';
$formattedUserId = $originalUserId . str_repeat('0', 16 - strlen($originalUserId));
echo "格式化后的用户ID：" . bin2hex($formattedUserId) . "\n";

2.3 完整的签名生成流程

现在我们把所有步骤组合起来，生成SM2签名：

function generateSM2Signature($data, $privateKey, $userId) {
    // 1. 准备待签名字符串
    $signString = buildSignString($data);
    
    // 2. 格式化用户ID
    $formattedUserId = formatUserId($userId);
    
    // 3. 处理私钥
    $privateKey = base64_decode($privateKey);
    $privateKeyHex = bin2hex($privateKey);
    
    // 4. 创建SM2实例
    $sm2 = new \Rtgm\sm\RtSm2('base64');
    
    // 5. 生成签名
    $signature = $sm2->doSign($signString, $privateKeyHex, $formattedUserId);
    
    // 6. 处理签名结果
    // SM2签名结果是ASN.1 DER编码，需要转换为招商银行要求的格式
    $decodedSignature = base64_decode($signature);
    $asnObject = \FG\ASN1\ASNObject::fromBinary($decodedSignature)->getChildren();
    
    // 提取r和s值
    $r = $asnObject[0]->getContent();
    $s = $asnObject[1]->getContent();
    
    // 转换为64字节的十六进制字符串
    $rHex = gmp_strval(gmp_init($r, 10), 16);
    $sHex = gmp_strval(gmp_init($s, 10), 16);
    
    // 确保每个部分都是64个十六进制字符（32字节）
    $rHex = str_pad($rHex, 64, '0', STR_PAD_LEFT);
    $sHex = str_pad($sHex, 64, '0', STR_PAD_LEFT);
    
    // 合并并转换为Base64
    $combinedHex = $rHex . $sHex;
    $finalSignature =

最低0.47元/天解锁文章