Skip to main content

jwc/
lib.rs

1//! # `jwc` - 国密 JSON Web 密码应用语法规范 (GM/T 0125—2022)
2//!
3//! `jwc` 是一个基于纯 Rust 实现的、严格遵循中华人民共和国密码行业标准 **GM/T 0125—2022** 的 JSON Web 密码应用体系库,
4//! 同时也与国际标准 **RFC 7515 (JWS)**、**RFC 7516 (JWE)**、**RFC 7517 (JWK)**、**RFC 7519 (JWT)** 保持高度兼容。
5//!
6//! ## 核心规范覆盖
7//! - **GM/T 0125.1—2022**: 算法标识 (`SGD_SM3_SM2`, `SGD_SM3_HMAC`, `SGD_SM2_3`, `SGD_SM4_CCM`, `SGD_SM4_GCM` 等)
8//! - **GM/T 0125.2—2022**: 数字签名 (JWS,支持 Compact、Flattened 与 General 序列化)
9//! - **GM/T 0125.3—2022**: 数据加密 (JWE,支持 SM2 密钥封装、SM4-GCM/CCM 认证加密与 DEFLATE 压缩)
10//! - **GM/T 0125.4—2022**: 密钥规范 (JWK 与 JWK Set 集合管理,支持硬件密码机/KMS 回调扩展)
11//!
12//! ## 快速上手
13//!
14//! ### 1. 国密 JWT 签发与校验 (SM2 / SM3-HMAC)
15//! ```rust
16//! use jwc::prelude::*;
17//! use serde::{Serialize, Deserialize};
18//!
19//! #[derive(Serialize, Deserialize, Debug, PartialEq)]
20//! struct UserClaims {
21//!     user_id: String,
22//!     role: String,
23//! }
24//!
25//! # fn main() -> Result<(), JwcError> {
26//! // 生成 SM2 密钥对
27//! let sm2_key = Jwk::generate_sm2()?.with_kid("key-01");
28//! let pub_key = sm2_key.to_public_key();
29//!
30//! // 构造声明并签发 Token
31//! let claims = Claims::new(UserClaims {
32//!     user_id: "admin".into(),
33//!     role: "superuser".into(),
34//! }).with_issuer("https://auth.example.com").with_expires_in(3600);
35//!
36//! let token = Jwt::encode(&claims, &sm2_key)?;
37//!
38//! // 校验并解析 Token
39//! let validation = Validation::new().with_issuer("https://auth.example.com");
40//! let data: TokenData<UserClaims> = Jwt::decode(&token, &pub_key, &validation)?;
41//! assert_eq!(data.claims.custom.user_id, "admin");
42//! # Ok(())
43//! # }
44//! ```
45//!
46//! ### 2. JWC 一键签密 (Sign-then-Encrypt 端到端传输)
47//! ```rust
48//! use jwc::prelude::*;
49//!
50//! # fn main() -> Result<(), JwcError> {
51//! let sender = Jwk::generate_sm2()?.with_kid("sender-key");
52//! let receiver = Jwk::generate_sm2()?.with_kid("receiver-key");
53//!
54//! // 发送方:一键签名 + DEFLATE 压缩 + SM4-GCM 加密
55//! let sealed_token = Jwc::seal(
56//!     b"Confidential Data",
57//!     &sender,
58//!     &receiver.to_public_key(),
59//!     Enc::Sm4Gcm,
60//!     true, // compress
61//!     Format::Compact,
62//! )?;
63//!
64//! // 接收方:一键解密 + 自动解压 + 验签
65//! let original = Jwc::unseal(&sealed_token, &receiver, &sender.to_public_key())?;
66//! assert_eq!(original, b"Confidential Data");
67//! # Ok(())
68//! # }
69//! ```
70
71use base64::Engine;
72use serde::{Deserialize, Serialize};
73
74pub mod crypto {
75    pub use aead::{Aead, KeyInit};
76    pub use ccm::Ccm;
77    pub use hmac::{Hmac, Mac, digest::KeyInit as MacKeyInit};
78    pub use sm2cl;
79    pub use sm2cl::{
80        Ciphertext as Sm2Ciphertext, KeyPair as Sm2KeyPair, PrivateKey as Sm2PrivateKey,
81        PublicKey as Sm2PublicKey, Signature as Sm2Signature, decrypt as sm2_decrypt,
82        encrypt as sm2_encrypt, sign as sm2_sign, verify as sm2_verify,
83    };
84    pub use sm3::{Digest, Sm3};
85    pub use sm4::Sm4;
86
87    pub type HmacSm3 = hmac::Hmac<sm3::Sm3>;
88    pub use crate::algorithms::sm4_gcm::Sm4Gcm;
89    pub type Sm4Ccm = ccm::Ccm<sm4::Sm4, ccm::consts::U16, ccm::consts::U8>;
90
91    /// JWT 签名器 Trait 抽象
92    pub trait JwtSigner: signature::Signer<Vec<u8>> {
93        /// 返回当前签名器对应的算法标识
94        fn algorithm(&self) -> crate::Alg;
95    }
96
97    /// JWT 验签器 Trait 抽象
98    pub trait JwtVerifier: signature::Verifier<Vec<u8>> {
99        /// 返回当前验签器对应的算法标识
100        fn algorithm(&self) -> crate::Alg;
101    }
102}
103
104pub mod algorithms;
105pub mod error;
106mod jwc;
107pub mod jwe;
108pub mod jwk;
109pub mod jws;
110pub mod jwt;
111
112pub use Alg as Algorithm;
113pub use error::JwcError;
114pub use jwc::{Jwc, JwcOutput};
115pub use jwe::{Jwe, JweRecipient};
116pub use jwk::{DecryptFn, Jwk, JwkEc, JwkOct, JwkOkp, JwkSet, JwkSm2, JwkSm9, SignFn, Sm2Key};
117pub use jws::{Jws, JwsSignature};
118pub use jwt::{Claims, Jwt, TokenData, Validation};
119
120pub mod prelude {
121    pub use crate::{
122        Alg, Algorithm, Claims, Curve, DecryptFn, Enc, Format, Jwc, JwcError, JwcOutput, Jwe,
123        JweRecipient, Jwh, Jwk, JwkEc, JwkOct, JwkOkp, JwkSet, JwkSm2, Jws, JwsSignature, Jwt,
124        KeyOp, KeyType, KeyUse, SignFn, TokenData, Validation, Zip, b64url_decode, b64url_encode,
125    };
126}
127
128// ============================================================================
129// 二、通用标准枚举类型定义 (GM/T 0125.1 ~ 0125.4)
130// ============================================================================
131
132/// 密钥类型 (kty) 参数
133///
134/// 规范依据:**GM/T 0125.4—2022 第 5.1 节 (kty 参数)**
135#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
136pub enum KeyType {
137    /// 椭圆曲线密钥 (SM2 / P-256 / P-384)
138    #[serde(rename = "EC")]
139    Ec,
140    /// 对称密钥 (SM4 / SM3-HMAC)
141    #[serde(rename = "oct")]
142    Oct,
143    /// 标识密码密钥 (SM9)
144    #[serde(rename = "IBC")]
145    Ibc,
146    /// 八位字节密钥对 (Ed25519) (RFC 8037)
147    #[serde(rename = "OKP")]
148    Okp,
149}
150
151/// 椭圆曲线标识 (crv) 参数
152///
153/// 规范依据:
154/// - **GM/T 0125.4—2022 第 6.1 节 表 1 (crv 参数)**
155/// - **RFC 7518 第 6.2.1.1 节 (crv 参数)**
156/// - **RFC 8037 第 2 节 (crv 参数)**
157#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
158pub enum Curve {
159    /// SM2 256 位椭圆曲线
160    #[serde(rename = "sm2p256v1")]
161    Sm2p256v1,
162    /// NIST P-256 (secp256r1)
163    #[serde(rename = "P-256")]
164    P256,
165    /// NIST P-384 (secp384r1)
166    #[serde(rename = "P-384")]
167    P384,
168    /// Ed25519 (RFC 8037)
169    #[serde(rename = "Ed25519")]
170    Ed25519,
171}
172
173/// 公钥用法 (use) 参数
174///
175/// 规范依据:**GM/T 0125.4—2022 第 5.3 节 (use 参数)**
176#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
177pub enum KeyUse {
178    /// 签名用途 (数字签名或消息鉴别)
179    #[serde(rename = "sig")]
180    Sig,
181    /// 加密用途 (数据加密或密钥封装)
182    #[serde(rename = "enc")]
183    Enc,
184}
185
186/// 密钥操作 (key_ops) 参数
187///
188/// 规范依据:**GM/T 0125.4—2022 第 5.4 节 (key_ops 参数)**
189#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
190pub enum KeyOp {
191    /// 计算数字签名或消息鉴别码
192    #[serde(rename = "sign")]
193    Sign,
194    /// 验证数字签名或消息鉴别码
195    #[serde(rename = "verify")]
196    Verify,
197    /// 加密内容
198    #[serde(rename = "encrypt")]
199    Encrypt,
200    /// 解密内容并验证解密
201    #[serde(rename = "decrypt")]
202    Decrypt,
203    /// 密钥封装
204    #[serde(rename = "wrapKey")]
205    WrapKey,
206    /// 解密密钥封装并验证解密
207    #[serde(rename = "unwrapKey")]
208    UnwrapKey,
209    /// 派生密钥
210    #[serde(rename = "deriveKey")]
211    DeriveKey,
212    /// 派生不用作密钥的位
213    #[serde(rename = "deriveBits")]
214    DeriveBits,
215}
216
217/// 签名、鉴别与密钥加密算法标识 (alg)
218///
219/// 规范依据:**GM/T 0125.1—2022 第 6~8 节 表 1/表 2/表 3**,**RFC 7518**,**RFC 8037**
220#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
221pub enum Alg {
222    /// 基于 SM3 和 SM2 的数字签名算法 (GM/T 0125.1 表 1)
223    #[serde(rename = "SGD_SM3_SM2")]
224    Sm3Sm2,
225    /// 基于 SM3 算法的消息鉴别算法 (GM/T 0125.1 表 2)
226    #[serde(rename = "SGD_SM3_HMAC")]
227    Sm3Hmac,
228    /// HMAC using SHA-256
229    #[serde(rename = "HS256")]
230    Hs256,
231    /// HMAC using SHA-384
232    #[serde(rename = "HS384")]
233    Hs384,
234    /// HMAC using SHA-512
235    #[serde(rename = "HS512")]
236    Hs512,
237    /// ECDSA using P-256 and SHA-256 (RFC 7518)
238    #[serde(rename = "ES256")]
239    Es256,
240    /// ECDSA using P-384 and SHA-384 (RFC 7518)
241    #[serde(rename = "ES384")]
242    Es384,
243    /// EdDSA using Ed25519 (RFC 8037)
244    #[serde(rename = "EdDSA")]
245    EdDsa,
246    /// SM2 公钥加密算法 (GM/T 0125.1 表 3)
247    #[serde(rename = "SGD_SM2_3")]
248    Sm2_3,
249    /// SM9 加密算法 (GM/T 0125.1 表 3)
250    #[serde(rename = "SGD_SM9_3")]
251    Sm9_3,
252}
253
254/// 内容加密算法标识 (enc)
255///
256/// 规范依据:**GM/T 0125.1—2022 第 9 节 表 4 (内容加密算法标识)**
257#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
258pub enum Enc {
259    /// 基于 SM4 算法的 CCM 认证加密算法 (GM/T 0125.1 表 4)
260    #[serde(rename = "SGD_SM4_CCM")]
261    Sm4Ccm,
262    /// 基于 SM4 算法的 GCM 认证加密算法 (GM/T 0125.1 表 4)
263    #[serde(rename = "SGD_SM4_GCM")]
264    Sm4Gcm,
265}
266
267/// 明文压缩算法标识 (zip)
268///
269/// 规范依据:**GM/T 0125.3—2022 第 6.2.2.10 节 表 2 (zip 参数)**
270#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
271pub enum Zip {
272    /// DEFLATE 压缩算法 (RFC 1951)
273    #[serde(rename = "DEF")]
274    Def,
275}
276
277/// 报文输出序列化格式
278///
279/// 规范依据:
280/// - **GM/T 0125.2—2022 第 12 节**: JWS 序列化 (紧凑、扁平 JSON、通用 JSON)
281/// - **GM/T 0125.3—2022 第 12 节**: JWE 序列化 (紧凑、扁平 JSON、通用 JSON)
282#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
283pub enum Format {
284    /// 紧凑序列化 (Compact): 3段式 (JWS) 或 5段式 (JWE) Base64URL 字符串 (默认最常用)
285    #[default]
286    Compact,
287
288    /// 扁平化 JSON 序列化 (Flattened): 单签名 / 单接收者平铺 JSON
289    Flattened,
290
291    /// 通用 JSON 序列化 (General): 多签名 / 多接收者完整 JSON 数组
292    General,
293}
294
295// ============================================================================
296// 三、标准通用头部结构定义 (JWH - JSON Web Header)
297// ============================================================================
298
299/// JSON Web 头部对象 (JWH)
300///
301/// 统一承载 JWS 头部 (GM/T 0125.2 6.2.2) 与 JWE 头部 (GM/T 0125.3 6.2.2) 的所有标准字段。
302#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq)]
303pub struct Jwh {
304    /// 签名/密钥封装算法标识 (GM/T 0125.2 6.2.2.1 / GM/T 0125.3 6.2.2.1)
305    #[serde(skip_serializing_if = "Option::is_none")]
306    pub alg: Option<Alg>,
307
308    /// 内容加密算法标识 (仅 JWE 使用, GM/T 0125.3 6.2.2.2)
309    #[serde(skip_serializing_if = "Option::is_none")]
310    pub enc: Option<Enc>,
311
312    /// 密钥标识 (可选): 标识具体使用的密钥 (GM/T 0125.2 6.2.2.4 / GM/T 0125.3 6.2.2.4)
313    #[serde(skip_serializing_if = "Option::is_none")]
314    pub kid: Option<String>,
315
316    /// JWK 集合 URL (可选): 指向 JWK Set 资源的 URI (GM/T 0125.2 6.2.2.2 / GM/T 0125.3 6.2.2.2)
317    #[serde(skip_serializing_if = "Option::is_none")]
318    pub jku: Option<String>,
319
320    /// JSON Web 密钥 (可选): 直接嵌入的公钥 (GM/T 0125.2 6.2.2.3 / GM/T 0125.3 6.2.2.3)
321    #[serde(skip_serializing_if = "Option::is_none")]
322    pub jwk: Option<jwk::Jwk>,
323
324    /// X.509 证书 URL (可选): 指向 X.509 证书的 URI (GM/T 0125.2 6.2.2.5 / GM/T 0125.3 6.2.2.5)
325    #[serde(skip_serializing_if = "Option::is_none")]
326    pub x5u: Option<String>,
327
328    /// 证书链 (可选): X.509 证书 DER base64 字符串数组 (GM/T 0125.2 6.2.2.7 / GM/T 0125.3 6.2.2.8)
329    #[serde(skip_serializing_if = "Option::is_none")]
330    pub x5c: Option<Vec<String>>,
331
332    /// 证书 SM3 杂凑值 (可选): base64url 编码 (GM/T 0125.2 6.2.2.8 / GM/T 0125.3 6.2.2.9)
333    #[serde(rename = "x5t#sm3", skip_serializing_if = "Option::is_none")]
334    pub x5t_sm3: Option<String>,
335
336    /// 媒体类型 (可选): 标识整个 JWS/JWE 的媒体类型 (GM/T 0125.2 6.2.2.9 / GM/T 0125.3 6.2.2.11)
337    #[serde(skip_serializing_if = "Option::is_none")]
338    pub typ: Option<String>,
339
340    /// 压缩算法 (可选): "DEF" 表示 DEFLATE 压缩 (GM/T 0125.3 第 6.2.2.10 节 表 2)
341    #[serde(skip_serializing_if = "Option::is_none")]
342    pub zip: Option<Zip>,
343
344    /// 内容类型 (可选): JWS/JWE 有载荷的媒体类型 (GM/T 0125.2 6.2.2.10 / GM/T 0125.3 6.2.2.12)
345    #[serde(skip_serializing_if = "Option::is_none")]
346    pub cty: Option<String>,
347
348    /// 关键头部参数列表 (可选): 必须被理解处理的头部参数名称 (GM/T 0125.2 6.2.2.11 / GM/T 0125.3 6.2.2.13)
349    #[serde(skip_serializing_if = "Option::is_none")]
350    pub crit: Option<Vec<String>>,
351}
352
353// ============================================================================
354// 四、Base64url 编解码辅助函数
355// ============================================================================
356
357#[inline]
358pub fn b64url_encode<I: AsRef<[u8]>>(input: I) -> String {
359    base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(input)
360}
361
362#[inline]
363pub fn b64url_decode<I: AsRef<[u8]>>(input: I) -> Result<Vec<u8>, base64::DecodeError> {
364    base64::engine::general_purpose::URL_SAFE_NO_PAD.decode(input)
365}