tls

web/tls 包 — TLS 配置与加解密工具

所属层级: Infrastructure Layer
设计理念: 安全通信，加密支持

概述

web/tls 包位于 Infrastructure Layer，提供 HTTPS 客户端构建、TLS 证书管理以及通用加解密工具。

核心功能

HTTPS 客户端

NewClient — 创建 HTTPS 客户端

func NewClient(baseURL string, opts ...ClientOption) *net.NetClient

client := https.NewClient("https://api.example.com",
    https.WithTimeout(30*time.Second),
    https.WithDefaultHeader("Authorization", "Bearer token123"),
)
resp, err := client.Get(ctx, "/api/users")

ClientOption

WithTLSConfig

tlsCfg, _ := https.LoadTLSConfig("server.crt", "server.key")
client := https.NewClient("https://example.com",
    https.WithTLSConfig(tlsCfg),
)

WithInsecureTLS

// 仅用于开发测试，跳过证书验证
client := https.NewClient("https://localhost:8443",
    https.WithInsecureTLS(),
)

WithTimeout

client := https.NewClient("https://api.example.com",
    https.WithTimeout(10*time.Second),
)

WithDefaultHeader

client := https.NewClient("https://api.example.com",
    https.WithDefaultHeader("Authorization", "Bearer eyJhbGciOiJ..."),
    https.WithDefaultHeader("X-Request-Id", "uuid-123"),
)

WithTransport

transport := &http.Transport{
    MaxIdleConns:    50,
    IdleConnTimeout: 60 * time.Second,
}
client := https.NewClient("https://api.example.com",
    https.WithTransport(transport),
)

完整使用示例

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/xudefa/enhance/https"
)

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    client := https.NewClient("https://jsonplaceholder.typicode.com",
        https.WithTimeout(10*time.Second),
    )

    ctx := context.Background()

    // GET 请求
    resp, err := client.Get(ctx, "/users/1")
    if err != nil {
        log.Fatal(err)
    }

    if resp.IsSuccess() {
        var user User
        resp.Bind(&user)
        fmt.Printf("用户: %+v\n", user)
    }

    // POST 请求
    newUser := map[string]any{"name": "张三"}
    resp, err = client.Post(ctx, "/users", newUser)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("创建成功:", resp.String())
}

TLS 配置

LoadTLSConfig — 从文件加载 TLS 配置

func LoadTLSConfig(certFile, keyFile string) (*tls.Config, error)

tlsCfg, err := https.LoadTLSConfig("server.crt", "server.key")
if err != nil {
    log.Fatal(err)
}

LoadTLSConfigWithCA — 加载 TLS 配置并启用 CA 验证

func LoadTLSConfigWithCA(certFile, keyFile, caFile string) (*tls.Config, error)

tlsCfg, err := https.LoadTLSConfigWithCA("client.crt", "client.key", "ca.crt")
if err != nil {
    log.Fatal(err)
}

LoadClientTLSConfig — 仅客户端验证（无需客户端证书）

func LoadClientTLSConfig(caFile string) (*tls.Config, error)

tlsCfg, err := https.LoadClientTLSConfig("ca.crt")
if err != nil {
    log.Fatal(err)
}
// 验证服务端证书，但不需要客户端证书

LoadCertFromPEM — 从 PEM 字节数据加载

func LoadCertFromPEM(certPEM, keyPEM []byte) (*tls.Config, error)

certPEM := []byte("-----BEGIN CERTIFICATE-----\n...")
keyPEM := []byte("-----BEGIN RSA PRIVATE KEY-----\n...")
tlsCfg, err := https.LoadCertFromPEM(certPEM, keyPEM)

InsecureTLSConfig — 跳过证书验证

func InsecureTLSConfig() *tls.Config

cfg := https.InsecureTLSConfig()
// cfg.InsecureSkipVerify = true, MinVersion = tls.VersionTLS12

MustLoadTLSConfig — 失败时 panic

func MustLoadTLSConfig(certFile, keyFile string) *tls.Config

cfg := https.MustLoadTLSConfig("server.crt", "server.key")
// 加载失败直接 panic，适用于初始化阶段

AES 加解密

AESEncrypt / AESDecrypt — CBC 模式（带 PKCS7 填充）

func AESEncrypt(plaintext, key, iv []byte) ([]byte, error)
func AESDecrypt(ciphertext, key, iv []byte) ([]byte, error)

• key：16/24/32 字节，对应 AES-128/AES-192/AES-256
• iv：16 字节初始向量

key := []byte("1234567890123456")  // AES-128
iv := []byte("1234567890123456")   // 16 字节

plaintext := []byte("Hello, World!")

ciphertext, err := https.AESEncrypt(plaintext, key, iv)
if err != nil {
    log.Fatal(err)
}

decrypted, err := https.AESDecrypt(ciphertext, key, iv)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(decrypted)) // "Hello, World!"

AESGCMEncrypt / AESGCMDecrypt — GCM 模式（推荐）

func AESGCMEncrypt(plaintext, key, additionalData []byte) ([]byte, error)
func AESGCMDecrypt(ciphertext, key, additionalData []byte) ([]byte, error)

• GCM 模式自带认证标签，能检测密文篡改
• 输出格式：nonce + ciphertext + tag（nonce 为随机生成 12 字节）
• additionalData 为可选的附加认证数据

key := []byte("1234567890123456") // AES-128

plaintext := []byte("Hello, World!")

// 加密
ciphertext, err := https.AESGCMEncrypt(plaintext, key, nil)
if err != nil {
    log.Fatal(err)
}

// 解密
decrypted, err := https.AESGCMDecrypt(ciphertext, key, nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(decrypted)) // "Hello, World!"

// 带附加认证数据
aad := []byte("additional-data")
ciphertext, _ = https.AESGCMEncrypt(plaintext, key, aad)
decrypted, _ = https.AESGCMDecrypt(ciphertext, key, aad)

RSA 加解密

RSAGenerateKey — 生成密钥对

func RSAGenerateKey(bits int) (*rsa.PrivateKey, error)

privateKey, err := https.RSAGenerateKey(2048)
if err != nil {
    log.Fatal(err)
}
publicKey := &privateKey.PublicKey

RSAEncrypt / RSADecrypt — OAEP-SHA256

func RSAEncrypt(publicKey *rsa.PublicKey, plaintext []byte) ([]byte, error)
func RSADecrypt(privateKey *rsa.PrivateKey, ciphertext []byte) ([]byte, error)

privateKey, _ := https.RSAGenerateKey(2048)
publicKey := &privateKey.PublicKey

plaintext := []byte("Hello, RSA!")
ciphertext, err := https.RSAEncrypt(publicKey, plaintext)
if err != nil {
    log.Fatal(err)
}

decrypted, err := https.RSADecrypt(privateKey, ciphertext)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(decrypted)) // "Hello, RSA!"

RSA 签名与验签

RSASign / RSAVerify — PKCS1v15-SHA256

func RSASign(privateKey *rsa.PrivateKey, data []byte) ([]byte, error)
func RSAVerify(publicKey *rsa.PublicKey, data, signature []byte) error

privateKey, _ := https.RSAGenerateKey(2048)
publicKey := &privateKey.PublicKey

data := []byte("待签名的数据")

// 签名
signature, err := https.RSASign(privateKey, data)
if err != nil {
    log.Fatal(err)
}

// 验签
err = https.RSAVerify(publicKey, data, signature)
if err != nil {
    log.Fatal("签名验证失败")
} else {
    fmt.Println("签名验证通过")
}

PEM 编解码

编码

func MarshalRSAPrivateKey(privateKey *rsa.PrivateKey) []byte
func MarshalRSAPublicKey(publicKey *rsa.PublicKey) ([]byte, error)

privateKey, _ := https.RSAGenerateKey(2048)

// 私钥 -> PEM
privPEM := https.MarshalRSAPrivateKey(privateKey)
os.WriteFile("private.pem", privPEM, 0600)

// 公钥 -> PEM
pubPEM, _ := https.MarshalRSAPublicKey(&privateKey.PublicKey)
os.WriteFile("public.pem", pubPEM, 0644)

解码

func ParseRSAPrivateKey(pemData []byte) (*rsa.PrivateKey, error)
func ParseRSAPublicKey(pemData []byte) (*rsa.PublicKey, error)

// 从 PEM 文件读取
pemData, _ := os.ReadFile("private.pem")
privateKey, err := https.ParseRSAPrivateKey(pemData)
if err != nil {
    log.Fatal(err)
}

pemData, _ = os.ReadFile("public.pem")
publicKey, err := https.ParseRSAPublicKey(pemData)
if err != nil {
    log.Fatal(err)
}

完整 API 参考