• 标准库
• 网络
• 密码学
• 并发编程

本文基于 cangjie_stdx 仓库中stdx.crypto.x509包的官方示例（英文示例）展开，系统讲解如何使用仓颉（Cangjie）语言完成 X.509 数字证书的读取解析、证书链验证、证书签发以及证书签名请求（CSR）生成四大核心操作。读完本文，你将掌握X509Certificate.decodeFromPem、cert.verify(VerifyOption)、X509Certificate(certInfo, parent, ...)、X509CertificateRequest(...)等关键 API 的完整用法，并理解VerifyOption各字段对验证结果的影响，可直接在业务代码中落地 TLS/HTTPS 场景下的证书处理能力。

一、前置条件与包概览

stdx.crypto.x509包为仓颉程序提供数字证书的完整处理能力，包括：X.509 证书的解析与序列化、证书验证、自签名证书创建、证书链的生成与校验。该包基于 OpenSSL 3 的 crypto 动态库实现，使用前必须确保系统中已正确安装 OpenSSL 3（如 Ubuntu 22.04 上执行sudo apt install libssl-dev），并保证系统安装目录中存在libcrypto.so与libcrypto.so.3（Linux）、libcrypto.dll.a（或libcrypto.lib）与libcrypto-3-x64.dll（Windows）、libcrypto.dylib与libcrypto.3.dylib（macOS）等动态库文件。若 OpenSSL 3 缺失或版本过低，程序会抛出X509Exception: Can not load openssl library or function xxx异常。完整的环境配置说明见 x509 包总览。

包中与本文示例直接相关的核心类型包括：

二、读取与解析证书

2.1 从 PEM 文件加载证书

证书文件需要用户自行准备。X509Certificate.decodeFromPem是静态方法，接收 PEM 格式的字符串，返回Array<X509Certificate>（PEM 中可能包含多个证书，例如证书链文件）：

import std.fs.File import stdx.crypto.x509.* let readPath = "./files/root_rsa.cer" main() { /* Read local certificate */ let pem = String.fromUtf8(File.readFrom(readPath)) let certificates = X509Certificate.decodeFromPem(pem) /* Parse mandatory fields in certificate */ let cert = certificates[0] println(cert) println("Serial Number: ${cert.serialNumber}") println("Issuer: ${cert.issuer}") println("NotBefore: ${cert.notBefore}") println("NotAfter: ${cert.notAfter}") println(cert.signatureAlgorithm) let signature = cert.signature println(signature.hashCode()) println(cert.publicKeyAlgorithm) let pubKey = cert.publicKey println(pubKey.encodeToPem().encode()) /* Parse extended fields in certificate */ println("DNSNames: ${cert.dnsNames}") println("EmailAddresses: ${cert.emailAddresses}") println("IPAddresses: ${cert.IPAddresses}") println("KeyUsage: ${cert.keyUsage}") println("ExtKeyUsage: ${cert.extKeyUsage}") /* Parse subject distinguished name */ println("Subject: ${cert.subject}") return 0 }

2.2 证书字段与对应属性

解析后的证书对象通过属性暴露全部标准字段，均定义在 X509Certificate 类 中：

• 必选字段：serialNumber（序列号）、issuer（颁发者，X509Name类型）、notBefore/notAfter（有效期起止，DateTime类型）、signatureAlgorithm/signature（签名算法与签名）、publicKeyAlgorithm/publicKey（公钥算法与公钥）、subject（使用者）。
• 扩展字段（Subject Alternative Names）：dnsNames（域名列表）、emailAddresses（邮箱列表）、IPAddresses（IP 列表，类型为Array<IP>，IP即Array<Byte>）、keyUsage（密钥用途）、extKeyUsage（扩展密钥用途）。

其中publicKey可通过encodeToPem().encode()导出为 PEM 公钥文本；toString()会生成形如X509Certificate(for=..., valid in ... .. ..., issued by ...)的描述串，包含使用者、有效期与颁发者信息。

下面是一份真实的运行结果（证书由 OpenSSL 生成，-subj '/CN=TestCert'），便于对照字段含义：

序列号: 1F924AA654316B55DAB1DA65FD9E2C8520EF23E3 颁发者: cn=TestCert 生效时间: 2026-07-14T08:12:02Z 失效时间: 2027-07-14T08:12:02Z 签名算法: Signature Algorithm: sha256WithRSAEncryption 签名哈希值: -8087033568281295724 公钥算法: Public Key Algorithm: rsaEncryption 公钥: -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxwJbTrg19PU5JpKYf/UD 83xuRbzAOvvumzOhZcX33ykEbId8TsPz/AjxOCQJgcqcyikLxyIw8YQqK6pzXsEc W6qRBklco98U6cgDsiMB8LmtYDNbK+jrKNcmWyADPrMGHJp0TgW7qFnugKMS/2X7 PiIeWyztKlseKe6EA1PHDTRbcIYCsYyj1YnF71FVPCba750kj/ILc0n/5Tn5iGC8 GescCTj10WrThP8ya3LhZHucTnfQTX0+oJDiJf7n2P/rFDLq9kf16XHeY10F6qkR CeXcgs+JkCXh77zm1zbTdUMAPMLeSrKzfW+6DFc84ShBriFSNQm6z14jW1PUGtr4 AQIDAQAB -----END PUBLIC KEY----- 使用者: cn=TestCert DNS 名称: [] 邮箱地址: [] IP 地址: [] 密钥用途: 扩展密钥用途:

提示：当 PEM 字符串不符合格式，或文件头不满足证书头部标准时，decodeFromPem会抛出 X509Exception。从源码（certificate.cj）看，该方法内部只接收CERTIFICATE与TRUSTED CERTIFICATE标签的 PEM 条目，其余条目会被忽略。

三、读取与验证证书

3.1 验证的三级逻辑

X509Certificate.verify(VerifyOption)是证书验证的核心入口，返回Bool。从源码（certificate.cj）可以看到验证按以下优先级执行：

1. 有效期校验：校验verifyOption.time是否落在[notBefore, notAfter]区间内，不满足直接返回false；
2. DNS 名校验：仅当verifyOption.dnsName非空时执行，支持精确匹配与通配符（*.example.com形式）匹配；
3. 证书链校验：将「目标证书 + 中间证书 + 根证书」作为链，调用底层 OpenSSL 接口完成签名链验证；状态码为 0 表示无效，大于 0 表示有效，内部错误（如内存分配失败）则抛出X509Exception。

3.2 VerifyOption 配置项

VerifyOption结构（见 x509_package_structs.md）包含四个可配置字段：

X509Certificate.systemRootCerts()会返回操作系统内置的根证书（支持 Linux、macOS、Windows）。从源码（certificate.cj）看，Linux 上它会扫描/etc/ssl/certs/、/etc/pki/tls/certs/、/system/etc/security/cacerts/以及ca-bundle.pem等常见系统证书目录与文件；Windows 上则通过系统接口直接读取。

3.3 完整验证示例

下面的示例读取服务端证书、根证书、中间证书三类文件，并展示按时间验证、按域名验证、以及多种证书链组合下的验证结果。证书文件需自行准备，示例假设证书关系如下：

* root[0] root[1] * / \ | * mid[0] mid[1] mid[2] * | | * server[0] server[1]

import std.fs.File import stdx.crypto.x509.* import std.time.DateTime let prefixPath = "./files/" let certFile = "servers.crt" let rootFile = "roots.crt" let middleFile = "middles.crt" func getX509Cert(path: String) { let pem = String.fromUtf8(File.readFrom(path)) X509Certificate.decodeFromPem(pem) } func testVerifyByTime(cert: X509Certificate, roots: Array<X509Certificate>, middles: Array<X509Certificate>) { var opt = VerifyOption() opt.roots = roots opt.intermediates = middles cert.verify(opt) println("Verify result: ${cert.verify(opt)}") opt.time = DateTime.of(year: 2023, month: 7, dayOfMonth: 1) println("Verify result:: ${cert.verify(opt)}") } func testVerifyByDNS(cert: X509Certificate) { var opt = VerifyOption() opt.dnsName = "www.example.com" println("cert DNS names: ${cert.dnsNames}") let res = cert.verify(opt) println("Verify result: ${res}") } func testVerify(cert: X509Certificate, roots: Array<X509Certificate>, middles: Array<X509Certificate>) { var opt = VerifyOption() opt.roots = roots opt.intermediates = middles let res = cert.verify(opt) println("Verify result: ${res}") } main() { /* Two server certificates */ let certs = getX509Cert(prefixPath + certFile) /* Two root certificates */ let roots = getX509Cert(prefixPath + rootFile) /* Three intermediate certificates */ let middles = getX509Cert(prefixPath + middleFile) /* Verify validity period */ testVerifyByTime(certs[0], [roots[0]], [middles[0]]) /* Verify DNS name */ testVerifyByDNS(certs[0]) /* Verify validity based on root and intermediate certificates */ /* cert0 <- root0: false */ testVerify(certs[0], [roots[0]], []) /* cert0 <- middle0 <- root0: true */ testVerify(certs[0], [roots[0]], [middles[0]]) /* cert0 <- (middle0, middle1, middle2) <- (root0, root1) : true */ testVerify(certs[0], roots, middles) /* cert1 <- middle0 <- root0: false */ testVerify(certs[1], [roots[0]], [middles[0]]) /* cert1 <- middle2 <- root1: true */ testVerify(certs[1], [roots[1]], [middles[2]]) /* cert1 <- (middle0, middle1, middle2) <- (root0, root1) : true */ testVerify(certs[1], roots, middles) return 0 }

该示例清晰地展示了证书链验证的关键结论：

• 只有「目标证书 ← 中间证书 ← 根证书」路径完整时，验证才返回true；
• 缺少中间证书、或中间证书不属于该根证书签发的链时，验证返回false；
• 将完整根证书数组与中间证书数组一并传入，系统会自动在所有候选链中寻找可行路径。

3.4 构造可验证证书链的注意事项

如果证书由 OpenSSL 生成且用于验证场景，必须给 CA 证书添加正确的扩展字段，否则链验证会失败。仓库中文示例给出了完整参考：为根证书配置basicConstraints = critical, CA:true与keyUsage = critical, keyCertSign, cRLSign，为中间证书额外添加pathlen:0，为服务端证书配置extendedKeyUsage = serverAuth。一个典型的链式生成流程为：

openssl genrsa -out rootKey.pem 2048 openssl req -new -x509 -key rootKey.pem -out rootCert.pem -days 365 -subj '/CN=TestRootCA' -config openssl.cnf -extensions v3_ca openssl genrsa -out middleKey.pem 2048 openssl req -new -key middleKey.pem -out middle.csr -subj '/CN=TestMiddleCA' openssl x509 -req -in middle.csr -CA rootCert.pem -CAkey rootKey.pem -CAcreateserial -out middleCert.pem -days 365 -extfile openssl.cnf -extensions v3_intermediate openssl genrsa -out serverKey.pem 2048 openssl req -new -key serverKey.pem -out server.csr -subj '/CN=www.example.com' openssl x509 -req -in server.csr -CA middleCert.pem -CAkey middleKey.pem -CAcreateserial -out serverCert.pem -days 365 -extfile openssl.cnf -extensions v3_server

四、创建与解析证书

4.1 核心构造流程

创建一张由父证书签发的数字证书，需要准备四类输入：证书信息（X509CertificateInfo）、签发者证书（parent）、申请者公钥、签发者私钥。其中publicKey仅支持 RSA、ECDSA、DSA 公钥，privateKey仅支持 RSA、ECDSA、DSA 私钥；若私钥类型与签名算法要求的私钥类型不匹配，构造会抛出X509Exception（源码见 certificate.cj）。

import std.fs.* import stdx.crypto.x509.* import stdx.crypto.keys.* import std.time.* import std.io.* main() { let x509Name = X509Name( countryName: "CN", provinceName: "beijing", localityName: "haidian", organizationName: "organization", organizationalUnitName: "organization unit", commonName: "x509", email: "test@email.com" ) let serialNumber = SerialNumber(length: 20) let startTime: DateTime = DateTime.now() let endTime: DateTime = startTime.addYears(1) let ip1: IP = [8, 8, 8, 8] let ip2: IP = [0, 1, 0, 1, 0, 1, 0, 1, 0, 8, 0, 8, 0, 8, 0, 8] let parentCertPem = String.fromUtf8(readToEnd(File("./certificate.pem", Read))) let parentCert = X509Certificate.decodeFromPem(parentCertPem)[0] let parentKeyPem = String.fromUtf8(readToEnd(File("./rsa_private_key.pem", Read))) let parentPrivateKey = GeneralPrivateKey.decodeFromPem(parentKeyPem) let usrKeyPem = String.fromUtf8(readToEnd(File("./ecdsa_public_key.pem", Read))) let usrPublicKey = GeneralPublicKey.decodeFromPem(usrKeyPem) let certInfo = X509CertificateInfo(serialNumber: serialNumber, notBefore: startTime, notAfter: endTime, subject: x509Name, dnsNames: ["b.com"], IPAddresses: [ip1, ip2]); let cert = X509Certificate(certInfo, parent: parentCert, publicKey: usrPublicKey, privateKey: parentPrivateKey) println(cert) println("Serial Number: ${cert.serialNumber}") println("Issuer: ${cert.issuer}") println("Subject: ${cert.subject}") println("NotBefore: ${cert.notBefore}") println("NotAfter: ${cert.notAfter}") println(cert.signatureAlgorithm) println("DNSNames: ${cert.dnsNames}") println("IPAddresses: ${cert.IPAddresses}") return 0 }

注意：示例中certificate.pem（签发者根证书）与rsa_private_key.pem（签发者私钥）、ecdsa_public_key.pem（申请者公钥）均为用户自行准备的本地文件。也可以像中文示例那样用RSAPrivateKey(2048)在程序中直接生成申请者密钥对，从而完全在仓颉代码内完成密钥生成 → 证书签发闭环。

4.2 X509CertificateInfo 与 SerialNumber 的参数细节

X509CertificateInfo的字段全部有默认值（见 certificate_info.cj）：

• serialNumber：默认None时使用 128 位（16 字节）随机序列号；
• notBefore：默认None时取DateTime.nowUTC()；
• notAfter：默认None时为notBefore加 1 年；
• subject：主体 DN，默认None；
• dnsNames/emailAddresses/IPAddresses：默认空数组，其中 IP 地址必须是 4 字节（IPv4）或 16 字节（IPv6），否则抛出X509Exception；
• keyUsage/extKeyUsage：密钥用途，默认None。

SerialNumber(length: 20)用于生成指定字节长度的随机序列号。从源码（serial_number.cj）看，长度必须满足1 ≤ length ≤ 20（依据 RFC 5280，序列号最长 20 字节），为 0 或超过 20 都会抛出X509Exception；序列号内部通过SecureRandom.nextBytes生成安全随机数，toString()输出大写十六进制串。

构造时若未显式指定signatureAlgorithm，默认签名算法为SHA256WithRSA且默认摘要为 SHA256。当前支持的签名算法枚举（见 signature.cj 与 枚举文档）包括：MD2WithRSA、MD5WithRSA、SHA1WithRSA、SHA256WithRSA、SHA384WithRSA、SHA512WithRSA、DSAWithSHA1、DSAWithSHA256、ECDSAWithSHA1、ECDSAWithSHA256、ECDSAWithSHA384、ECDSAWithSHA512。其中MD2WithRSA、MD5WithRSA、SHA1WithRSA、DSAWithSHA1、ECDSAWithSHA1已被证明不安全，需谨慎使用。

4.3 运行结果示例

证书创建成功 序列号: 01C51A6B4C2256F666E043F21035337B700B15DA 颁发者: cn=TestRootCA 使用者: c=CN,st=beijing,l=haidian,o=organization,cn=x509_test 生效时间: 2026-07-14T08:15:25Z 失效时间: 2027-07-14T08:15:25Z 签名算法: Signature Algorithm: sha256WithRSAEncryption DNS 名称: [test.example.com] IP 地址: [[8, 8, 8, 8]]

五、创建与解析证书签名请求（CSR）

5.1 生成 CSR

证书签名请求用于向 CA 申请签发证书，包含申请者的公钥、主体 DN 与可选扩展（域名、IP、邮箱），并由申请者私钥签名。核心 API 为X509CertificateRequest(privateKey, certificateRequestInfo, signatureAlgorithm)，其中私钥仅支持 RSA、ECDSA、DSA 类型；私钥类型与签名算法要求的密钥类型不匹配时抛出X509Exception（源码见 csr.cj）。

import std.fs.* import std.io.* import stdx.crypto.x509.* import stdx.crypto.keys.GeneralPrivateKey main() { let x509Name = X509Name( countryName: "CN", provinceName: "beijing", localityName: "haidian", organizationName: "organization", organizationalUnitName: "organization unit", commonName: "x509", email: "test@email.com" ) let ip1: IP = [8, 8, 8, 8] let ip2: IP = [0, 1, 0, 1, 0, 1, 0, 1, 0, 8, 0, 8, 0, 8, 0, 8] let rsaPem = String.fromUtf8(readToEnd(File("./rsa_private_key.pem", Read))) let rsa = GeneralPrivateKey.decodeFromPem(rsaPem) let csrInfo = X509CertificateRequestInfo(subject: x509Name, dnsNames: ["b.com"], IPAddresses: [ip1, ip2]); let csr = X509CertificateRequest(rsa, certificateRequestInfo: csrInfo, signatureAlgorithm: SHA256WithRSA) println("Subject: ${csr.subject.toString()}") println("IPAddresses: ${csr.IPAddresses}") println("dnsNames: ${csr.dnsNames}") return 0 }

示例运行结果：

证书签名请求创建成功 使用者: c=CN,st=beijing,l=haidian,o=organization,cn=test_csr DNS 名称: [test.example.com]

5.2 CSR 对象的能力

创建出的X509CertificateRequest对象除可读取subject、dnsNames、IPAddresses、emailAddresses、publicKey、publicKeyAlgorithm、signature、signatureAlgorithm等属性外，还支持：

• encodeToPem()/encodeToDer()：将 CSR 编码为 PEM / DER 格式（PEM 标签为CERTIFICATE REQUEST，见 csr.cj），可写入文件后提交给 CA；
• decodeFromPem/decodeFromDer：从 PEM / DER 重新解析 CSR；
• hashCode()/toString()：哈希与字符串化。

六、常见异常与排错建议

整个 x509 包统一抛出X509Exception（继承自Exception，支持无参与带消息两种构造，见 异常文档）。结合上文源码分析，常见触发场景归纳如下：

七、小结

通过本文的四个实战示例，你可以用stdx.crypto.x509包完成数字证书生命周期中的全部核心操作：解析（decodeFromPem+ 属性读取）、验证（verify+VerifyOption的时间、DNS、证书链三级校验）、签发（X509CertificateInfo+ 父证书 + 公私钥构造新证书）以及CSR 生成（X509CertificateRequest）。结合 x509 包 API 文档 与源码（certificate.cj、csr.cj），可以进一步扩展出双向 TLS 认证、证书轮换、内部 CA 体系等生产级能力。

• 标准库
• 网络
• 密码学
• 并发编程