diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index 82cdc33..3da9422 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -13,13 +13,13 @@ jobs: strategy: matrix: go: + - "1.22" + - "1.21" + - "1.20" - "1.19" - "1.18" - "1.17" - "1.16" - - "1.15" - - "1.14" - - "1.13" steps: - uses: actions/checkout@v2 @@ -39,10 +39,10 @@ jobs: - name: Set up Go uses: actions/setup-go@v2 with: - go-version: "1.16" + go-version: "1.19" - name: staticcheck run: | - go get -u honnef.co/go/tools/cmd/staticcheck@v0.2.2 && + go install honnef.co/go/tools/cmd/staticcheck@latest && $HOME/go/bin/staticcheck ./... - name: Revive Action uses: morphy2k/revive-action@v2.1.1 diff --git a/README.md b/README.md index 4d93df4..313bfdd 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 微信支付 API v3 Go SDK + [![GoDoc](http://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/wechatpay-apiv3/wechatpay-go) -[![huntr](https://cdn.huntr.dev/huntr_security_badge_mono.svg)](https://huntr.dev) [![licence](https://badgen.net/github/license/wechatpay-apiv3/wechatpay-go)](https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/LICENSE) [微信支付 APIv3](https://wechatpay-api.gitbook.io/wechatpay-api-v3/) 官方Go语言客户端代码库。 @@ -28,10 +28,12 @@ go mod init ``` -#### 2、无需 clone 仓库中的代码，直接在项目目录中执行： +#### 2、无需 clone 仓库中的代码，直接在项目目录中执行 + ```shell go get -u github.com/wechatpay-apiv3/wechatpay-go ``` + 来添加依赖，完成 `go.mod` 修改与 SDK 下载。 ### 发送请求 @@ -89,8 +91,11 @@ func main() { #### 名词解释 + **商户 API 证书**，是用来证实商户身份的。证书中包含商户号、证书序列号、证书有效期等信息，由证书授权机构（Certificate Authority ，简称 CA）签发，以防证书被伪造或篡改。如何获取请见 [商户 API 证书](https://wechatpay-api.gitbook.io/wechatpay-api-v3/ren-zheng/zheng-shu#shang-hu-api-zheng-shu) 。 + + **商户 API 私钥**。商户申请商户 API 证书时，会生成商户私钥，并保存在本地证书文件夹的文件 apiclient_key.pem 中。 + > :warning: 不要把私钥文件暴露在公共场合，如上传到 Github，写在客户端代码等。 + + **微信支付平台证书**。微信支付平台证书是指由微信支付负责申请的，包含微信支付平台标识、公钥信息的证书。商户使用微信支付平台证书中的公钥验证应答签名。获取微信支付平台证书需通过 [获取平台证书列表](https://wechatpay-api.gitbook.io/wechatpay-api-v3/ren-zheng/zheng-shu#ping-tai-zheng-shu) 接口下载。 + **证书序列号**。每个证书都有一个由 CA 颁发的唯一编号，即证书序列号。扩展阅读 [如何查看证书序列号](https://wechatpay-api.gitbook.io/wechatpay-api-v3/chang-jian-wen-ti/zheng-shu-xiang-guan#ru-he-cha-kan-zheng-shu-xu-lie-hao) 。 + **微信支付 APIv3 密钥**，是在回调通知和微信支付平台证书下载接口中，为加强数据安全，对关键信息 `AES-256-GCM` 加密时使用的对称加密密钥。 @@ -156,7 +161,8 @@ if err == nil { ``` -### 以 [图片上传API](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter2_1_1.shtml) 为例： +### 以 [图片上传API](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter2_1_1.shtml) 为例 + ```go import ( "os" @@ -199,10 +205,10 @@ result, err := client.Get(ctx, "https://api.mch.weixin.qq.com/v3/certificates") 以下情况，SDK 发送请求会返回 `error`： -- HTTP 网络错误，如应答接收超时或网络连接失败 -- 客户端失败，如生成签名失败 -- 服务器端返回了**非** `2xx` HTTP 状态码 -- 应答签名验证失败 ++ HTTP 网络错误，如应答接收超时或网络连接失败 ++ 客户端失败，如生成签名失败 ++ 服务器端返回了**非** `2xx` HTTP 状态码 ++ 应答签名验证失败 为了方便使用，SDK 将服务器返回的 `4xx` 和 `5xx` 错误，转换成了 `APIError`。 @@ -223,6 +229,7 @@ if err != nil { 2. 调用 `handler.ParseNotifyRequest` 验签，并解密报文。 ### 初始化 + + 方法一（大多数场景）：先手动注册下载器，再获取微信平台证书访问器。 适用场景： 仅需要对回调通知验证签名并解密的场景。例如，基础支付的回调通知。 @@ -291,7 +298,6 @@ fmt.Println(transaction.TransactionId) 将 SDK 未支持的回调消息体，解析至 `map[string]interface{}`。 - ```go content := make(map[string]interface{}) notifyReq, err := handler.ParseNotifyRequest(context.Background(), request, &content) @@ -453,6 +459,35 @@ func NewCustomClient(ctx context.Context, mchID string) (*core.Client, error) { } ``` +### 使用公钥验证微信支付签名 + +如果你的商户是全新入驻，且仅可使用微信支付的公钥验证应答和回调的签名，请使用微信支付公钥和公钥 ID 初始化。 + +```go +var ( + wechatpayPublicKeyID string = "00000000000000000000000000000000" // 微信支付公钥ID +) + +wechatpayPublicKey, err = utils.LoadPublicKeyWithPath("/path/to/wechatpay/pub_key.pem") +if err != nil { + panic(fmt.Errorf("load wechatpay public key err:%s", err.Error())) +} + +// 初始化 Client +opts := []core.ClientOption{ + option.WithWechatPayPublicKeyAuthCipher( + mchID, + mchCertificateSerialNumber, mchPrivateKey, + wechatpayPublicKeyID, wechatpayPublicKey), +} +client, err := core.NewClient(ctx, opts...) + +// 初始化 notify.Handler +handler := notify.NewNotifyHandler( + mchAPIv3Key, + verifiers.NewSHA256WithRSAPubkeyVerifier(wechatpayPublicKeyID, *wechatPayPublicKey)) +``` + ## 常见问题 常见问题请见 [FAQ.md](FAQ.md)。 @@ -461,10 +496,10 @@ func NewCustomClient(ctx context.Context, mchID string) (*core.Client, error) { 微信支付欢迎来自社区的开发者贡献你们的想法和代码。请你在提交 PR 之前，先提一个对应的 issue 说明以下内容： -- 背景（如，遇到的问题）和目的 -- **着重**说明你的想法 -- 通过代码或者其他方式，简要的说明是如何实现的，或者它会是如何使用 -- 是否影响现有的接口 ++ 背景（如，遇到的问题）和目的 ++ **着重**说明你的想法 ++ 通过代码或者其他方式，简要的说明是如何实现的，或者它会是如何使用 ++ 是否影响现有的接口 [#35](https://github.com/wechatpay-apiv3/wechatpay-go/issues/35) 是一个很好的参考。 @@ -485,6 +520,7 @@ go test -gcflags=all=-l ./... ``` ## 联系微信支付 + 如果你发现了 BUG，或者需要的功能还未支持，或者有任何疑问、建议，欢迎通过 [issue](https://github.com/wechatpay-apiv3/wechatpay-go/issues) 反馈。 也欢迎访问微信支付的 [开发者社区](https://developers.weixin.qq.com/community/pay)。 diff --git a/core/auth/verifiers/sha256withrsa_pubkey_verifier.go b/core/auth/verifiers/sha256withrsa_pubkey_verifier.go new file mode 100644 index 0000000..4dede5d --- /dev/null +++ b/core/auth/verifiers/sha256withrsa_pubkey_verifier.go @@ -0,0 +1,45 @@ +// Copyright 2024 Tencent Inc. All rights reserved. + +// Package verifiers 微信支付 API v3 Go SDK 数字签名验证器 +package verifiers + +import ( + "context" + "crypto" + "crypto/rsa" + "crypto/sha256" + "encoding/base64" + "fmt" +) + +// SHA256WithRSAPubkeyVerifier 数字签名验证器,使用微信支付提供的公钥验证签名 +type SHA256WithRSAPubkeyVerifier struct { + keyID string + publicKey rsa.PublicKey +} + +// Verify 使用微信支付提供的公钥验证签名 +func (v *SHA256WithRSAPubkeyVerifier) Verify(ctx context.Context, serialNumber, message, signature string) error { + if ctx == nil { + return fmt.Errorf("verify failed: context is nil") + } + if v.keyID != serialNumber { + return fmt.Errorf("verify failed: key-id[%s] does not match serial number[%s]", v.keyID, serialNumber) + } + + sigBytes, err := base64.StdEncoding.DecodeString(signature) + if err != nil { + return fmt.Errorf("verify failed: signature is not base64 encoded") + } + hashed := sha256.Sum256([]byte(message)) + err = rsa.VerifyPKCS1v15(&v.publicKey, crypto.SHA256, hashed[:], sigBytes) + if err != nil { + return fmt.Errorf("verify signature with public key error:%s", err.Error()) + } + return nil +} + +// NewSHA256WithRSAPubkeyVerifier 使用 rsa.PublicKey 初始化验签器 +func NewSHA256WithRSAPubkeyVerifier(keyID string, publicKey rsa.PublicKey) *SHA256WithRSAPubkeyVerifier { + return &SHA256WithRSAPubkeyVerifier{keyID: keyID, publicKey: publicKey} +} diff --git a/core/auth/verifiers/sha256withrsa_pubkey_verifier_test.go b/core/auth/verifiers/sha256withrsa_pubkey_verifier_test.go new file mode 100644 index 0000000..64bac98 --- /dev/null +++ b/core/auth/verifiers/sha256withrsa_pubkey_verifier_test.go @@ -0,0 +1,154 @@ +// Copyright 2021 Tencent Inc. All rights reserved. + +package verifiers + +import ( + "context" + "crypto/rsa" + "testing" + + "github.com/wechatpay-apiv3/wechatpay-go/utils" +) + +const ( + testPubKeyID = "F5765756002FDD77" + testPubKey = `-----BEGIN PUBLIC KEY----- +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2VCTd91fnUn73Xy9DLvt +/V62TVxRTEEstVdeRaZ3B3leO0pldE806mXO4RwdHXagHQ4vGeZN0yqm++rDsGK+ +U3AH7kejyD2pXshNP9Cq5YwbptiLGtjcquw4HNxJQUOmDeJf2vg6byms9RUipiq4 +SzbJKqJFlUpbuIPDpSpWz10PYmyCNeDGUUK65E5h2B834uxl1zNLYQCrkdBzb8oU +xwYeP5a2DNxmjL5lsJML7DGr5znsevnoqGRwTm9fxCGfy8wus7hwKz6clt3Whmmd +a7UAdb1c08hEQFVRbF14AR73xbnd8N0obCWJPCbzMCtkaSef4FdEEgEXJiw0VAJT +8wIDAQAB +-----END PUBLIC KEY-----` + // testExpectedSignature = "BKyAfU4iMCuvXMXS0Wzam3V/cnxZ+JaqigPM5OhljS2iOT95OO6Fsuml2JkFANJU9" + + // "K6q9bLlDhPXuoVz+pp4hAm6pHU4ld815U4jsKu1RkyaII+1CYBUYC8TK0XtJ8FwUXXz8vZHh58rrAVN1XwNyv" + + // "D1vfpxrMT4SL536GLwvpUHlCqIMzoZUguLli/K8V29QiOhuH6IEqLNJn8e9b3nwNcQ7be3CzYGpDAKBfDGPCq" + + // "Cv8Rw5zndhlffk2FEA70G4hvMwe51qMN/RAJbknXG23bSlObuTCN7Ndj1aJGH6/L+hdwfLpUtJm4QYVazzW7D" + + // "FD27EpSQEqA8bX9+8m1rLg==" +) + +var ( + pubKey *rsa.PublicKey +) + +func init() { + var err error + pubKey, err = utils.LoadPublicKey(testPubKey) + if err != nil { + panic(err) + } +} + +func TestWechatPayPubKeyVerifier(t *testing.T) { + type args struct { + ctx context.Context + serialNumber string + message string + signature string + } + tests := []struct { + name string + fields *rsa.PublicKey + args args + wantErr bool + }{ + { + name: "verify success", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: testPubKeyID, + signature: testExpectedSignature, + message: "source", + }, + wantErr: false, + }, + { + name: "verify failed", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: testPubKeyID, + signature: testExpectedSignature, + message: "wrong source", + }, + wantErr: true, + }, + { + name: "verify failed with null context", + fields: pubKey, + args: args{ + ctx: nil, + serialNumber: testWechatPayVerifierPlatformSerialNumber, + signature: testExpectedSignature, + message: "source", + }, + wantErr: true, + }, + { + name: "verify failed with empty keyId", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: "", + signature: testExpectedSignature, + message: "source", + }, + wantErr: true, + }, + { + name: "verify failed with empty message", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: testPubKeyID, + signature: testExpectedSignature, + message: "", + }, + wantErr: true, + }, + { + name: "verify failed with empty signature", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: testPubKeyID, + signature: "", + message: "source", + }, + wantErr: true, + }, + { + name: "verify failed with non-base64 signature", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: testPubKeyID, + signature: "invalid base64 signature", + message: "source", + }, + wantErr: true, + }, + { + name: "verify failed with no corresponding pubkey", + fields: pubKey, + args: args{ + ctx: context.Background(), + serialNumber: "invalid serial number", + signature: testExpectedSignature, + message: "source", + }, + wantErr: true, + }, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + var verifier = NewSHA256WithRSAPubkeyVerifier(testPubKeyID, *tt.fields) + if err := verifier.Verify(tt.args.ctx, tt.args.serialNumber, tt.args.message, + tt.args.signature); (err != nil) != tt.wantErr { + t.Errorf("Verify() error = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} diff --git a/core/cipher/encryptors/wechat_pay_encryptor.go b/core/cipher/encryptors/wechat_pay_encryptor.go index d5984ea..6e7cbd9 100644 --- a/core/cipher/encryptors/wechat_pay_encryptor.go +++ b/core/cipher/encryptors/wechat_pay_encryptor.go @@ -10,7 +10,7 @@ import ( "github.com/wechatpay-apiv3/wechatpay-go/utils" ) -// WechatPayEncryptor 微信支付字符串加密器 +// WechatPayEncryptor 微信支付字符串加密器，使用微信支付平台证书 type WechatPayEncryptor struct { // 微信支付平台证书提供器 certGetter core.CertificateGetter @@ -34,7 +34,8 @@ func (e *WechatPayEncryptor) SelectCertificate(ctx context.Context) (serial stri } // Encrypt 对字符串加密 -func (e *WechatPayEncryptor) Encrypt(ctx context.Context, serial, plaintext string) (ciphertext string, err error) { +func (e *WechatPayEncryptor) Encrypt( + ctx context.Context, serial, plaintext string) (ciphertext string, err error) { cert, ok := e.certGetter.Get(ctx, serial) if !ok { diff --git a/core/cipher/encryptors/wechat_pay_encryptor_test.go b/core/cipher/encryptors/wechat_pay_encryptor_test.go index 6fada36..19f1e77 100644 --- a/core/cipher/encryptors/wechat_pay_encryptor_test.go +++ b/core/cipher/encryptors/wechat_pay_encryptor_test.go @@ -88,6 +88,16 @@ jWNRBmvvftZhY59PILHO2X5vO4FXh7suEjy6VIh0gsnK36mmRboYIBGsNuDHjXLe BDa+8mDLkWu5nHEhOxy2JJZl -----END TESTING KEY-----` +const publicKeyStr = `-----BEGIN PUBLIC KEY----- +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2VCTd91fnUn73Xy9DLvt +/V62TVxRTEEstVdeRaZ3B3leO0pldE806mXO4RwdHXagHQ4vGeZN0yqm++rDsGK+ +U3AH7kejyD2pXshNP9Cq5YwbptiLGtjcquw4HNxJQUOmDeJf2vg6byms9RUipiq4 +SzbJKqJFlUpbuIPDpSpWz10PYmyCNeDGUUK65E5h2B834uxl1zNLYQCrkdBzb8oU +xwYeP5a2DNxmjL5lsJML7DGr5znsevnoqGRwTm9fxCGfy8wus7hwKz6clt3Whmmd +a7UAdb1c08hEQFVRbF14AR73xbnd8N0obCWJPCbzMCtkaSef4FdEEgEXJiw0VAJT +8wIDAQAB +-----END PUBLIC KEY-----` + func testingKey(s string) string { return strings.ReplaceAll(s, "TESTING KEY", "PRIVATE KEY") } func initWechatPayEncryptor() (*WechatPayEncryptor, error) { @@ -103,7 +113,7 @@ func initWechatPayEncryptor() (*WechatPayEncryptor, error) { return NewWechatPayEncryptor(core.NewCertificateMapWithList(l)), nil } -func TestWechatPayEncryptor_SelectCertificate(t *testing.T) { +func TestWechatPayEncryptorSelectCertificate(t *testing.T) { e, err := initWechatPayEncryptor() require.NoError(t, err) @@ -112,7 +122,7 @@ func TestWechatPayEncryptor_SelectCertificate(t *testing.T) { assert.Equal(t, "D7CE59D1F522D701", serial) } -func TestWechatPayEncryptor_Encrypt(t *testing.T) { +func TestWechatPayEncryptorEncrypt(t *testing.T) { e, err := initWechatPayEncryptor() require.NoError(t, err) @@ -130,7 +140,7 @@ func TestWechatPayEncryptor_Encrypt(t *testing.T) { assert.Equal(t, newPlainText, plaintext) } -func TestWechatPayEncryptor_EncryptEmpty(t *testing.T) { +func TestWechatPayEncryptorEncryptEmpty(t *testing.T) { e, err := initWechatPayEncryptor() require.NoError(t, err) @@ -142,7 +152,7 @@ func TestWechatPayEncryptor_EncryptEmpty(t *testing.T) { assert.Equal(t, "", ciphertext) } -func TestWechatPayEncryptor_EncryptWithWrongSerial(t *testing.T) { +func TestWechatPayEncryptorEncryptWithWrongSerial(t *testing.T) { e, err := initWechatPayEncryptor() require.NoError(t, err) @@ -153,7 +163,7 @@ func TestWechatPayEncryptor_EncryptWithWrongSerial(t *testing.T) { require.Error(t, err) } -func TestMockEncryptor_Encrypt(t *testing.T) { +func TestMockEncryptorEncrypt(t *testing.T) { e := MockEncryptor{Serial: "F5765756002FDD77"} cipertext, err := e.Encrypt(context.Background(), "F5765756002FDD77", "hehe") @@ -161,9 +171,23 @@ func TestMockEncryptor_Encrypt(t *testing.T) { assert.Equal(t, "Encryptedhehe", cipertext) } -func TestMockEncryptor_EncryptWithWrontSerial(t *testing.T) { +func TestMockEncryptorEncryptWithWrontSerial(t *testing.T) { e := MockEncryptor{Serial: "F5765756002FDD77"} _, err := e.Encrypt(context.Background(), "wrong serial", "hehe") require.Error(t, err) } + +func TestPublicEncryptorEncrypt(t *testing.T) { + publicKey, _ := utils.LoadPublicKey(publicKeyStr) + e := NewWechatPayPubKeyEncryptor("F5765756002FDD77", *publicKey) + + plaintext := "hehe" + ciphertext, err := e.Encrypt(context.Background(), "F5765756002FDD77", plaintext) + require.NoError(t, err) + + privateKey, _ := utils.LoadPrivateKey(testingKey(privateKeyStr)) + newPlainText, err := utils.DecryptOAEP(ciphertext, privateKey) + require.NoError(t, err) + assert.Equal(t, newPlainText, plaintext) +} diff --git a/core/cipher/encryptors/wechat_pay_pubkey_encryptor.go b/core/cipher/encryptors/wechat_pay_pubkey_encryptor.go new file mode 100644 index 0000000..f274c29 --- /dev/null +++ b/core/cipher/encryptors/wechat_pay_pubkey_encryptor.go @@ -0,0 +1,44 @@ +// Copyright 2024 Tencent Inc. All rights reserved. + +package encryptors + +import ( + "context" + "crypto/rsa" + "fmt" + + "github.com/wechatpay-apiv3/wechatpay-go/utils" +) + +// WechatPayPubKeyEncryptor 微信支付字符串加密器，使用微信支付公钥 +type WechatPayPubKeyEncryptor struct { + // 微信支付公钥 + publicKey rsa.PublicKey + // 公钥 ID + keyID string +} + +// NewWechatPayPubKeyEncryptor 新建一个 WechatPayPubKeyEncryptor +func NewWechatPayPubKeyEncryptor(keyID string, publicKey rsa.PublicKey) *WechatPayPubKeyEncryptor { + return &WechatPayPubKeyEncryptor{publicKey: publicKey, keyID: keyID} +} + +// SelectCertificate 选择合适的微信支付平台证书用于加密 +// 返回公钥对应的 KeyId 作为证书序列号 +func (e *WechatPayPubKeyEncryptor) SelectCertificate(ctx context.Context) (serial string, err error) { + return e.keyID, nil +} + +// Encrypt 对字符串加密 +func (e *WechatPayPubKeyEncryptor) Encrypt(ctx context.Context, serial, plaintext string) (ciphertext string, err error) { + if serial != e.keyID { + return "", fmt.Errorf("serial %v not match key-id %v", serial, e.keyID) + } + + // 不需要对空串进行加密 + if plaintext == "" { + return "", nil + } + + return utils.EncryptOAEPWithPublicKey(plaintext, &e.publicKey) +} diff --git a/core/option/auth_cipher_option.go b/core/option/auth_cipher_option.go index 8bab742..1e159f3 100644 --- a/core/option/auth_cipher_option.go +++ b/core/option/auth_cipher_option.go @@ -28,6 +28,7 @@ func (w withAuthCipherOption) Apply(o *core.DialSettings) error { } // WithWechatPayAuthCipher 一键初始化 Client，使其具备「签名/验签/敏感字段加解密」能力 +// Deprecated: 使用 WithWechatPayAutoAuthCipher 或 WithWechatPayPublicKeyAuthCipher 代替 func WithWechatPayAuthCipher( mchID string, certificateSerialNo string, privateKey *rsa.PrivateKey, certificateList []*x509.Certificate, ) core.ClientOption { @@ -91,3 +92,28 @@ func WithWechatPayAutoAuthCipherUsingDownloaderMgr( }, } } + +// WithWechatPayPublicKeyAuthCipher 一键初始化 Client，使其具备「签名/验签/敏感字段加解密」能力。 +// 使用微信支付提供的公钥验签 +func WithWechatPayPublicKeyAuthCipher( + mchID, certificateSerialNo string, privateKey *rsa.PrivateKey, publicKeyID string, publicKey *rsa.PublicKey, +) core.ClientOption { + return withAuthCipherOption{ + settings: core.DialSettings{ + Signer: &signers.SHA256WithRSASigner{ + MchID: mchID, + CertificateSerialNo: certificateSerialNo, + PrivateKey: privateKey, + }, + Validator: validators.NewWechatPayResponseValidator( + verifiers.NewSHA256WithRSAPubkeyVerifier( + publicKeyID, + *publicKey, + )), + Cipher: ciphers.NewWechatPayCipher( + encryptors.NewWechatPayPubKeyEncryptor(publicKeyID, *publicKey), + decryptors.NewWechatPayDecryptor(privateKey), + ), + }, + } +}