jsonwebtoken

docs.rs上的API文档

安装

将以下内容添加到Cargo.toml

jsonwebtoken = "6"
serde_derive = "1"
serde = "1"

v7版本需要帮助

v6版本作为过渡版本发布，用于更新Ring并添加一些功能，如ES256/384。考虑到所有可能的RSA密钥加载方式，结果并不非常直观。一个可能的解决方案是使用如https://github.com/Keats/jsonwebtoken/issues/76中描述的解码器类型，但我目前没有时间自己实现它。当然，我也欢迎任何更好的想法！

如何使用

完整示例可在examples目录中找到：一个基本的示例和一个带有自定义头的示例。

关于导入和结构体

extern crate jsonwebtoken as jwt;
#[macro_use]
extern crate serde_derive;

use jwt::{encode, decode, Header, Algorithm, Validation};

/// Our claims struct, it needs to derive `Serialize` and/or `Deserialize`
#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    sub: String,
    company: String,
    exp: usize,
}

编码

默认算法为HS256。

let token = encode(&Header::default(), &my_claims, "secret".as_ref())?;

自定义头和更改算法

支持RFC中的所有参数，但默认头只设置了typ和alg。如果您想设置kid参数或更改算法，例如

let mut header = Header::default();
header.kid = Some("blabla".to_owned());
header.alg = Algorithm::HS512;
let token = encode(&header, &my_claims, "secret".as_ref())?;

请查看examples/custom_header.rs以获取完整的工作示例。

解码

let token = decode::<Claims>(&token, "secret".as_ref(), &Validation::default())?;
// token is a struct with 2 params: header and claims

decode可能会因各种原因出错

• 令牌或其签名无效
• 解码base64时出错或解码后的结果不是有效的UTF-8
• 至少一个保留声明的验证失败

在某些情况下，例如如果您不知道使用的算法，您可能只想解码头部

let header = decode_header(&token)?;

这不会对令牌执行任何验证。

验证

如果存在，此库会自动验证exp和nbf声明。您还可以验证sub、iss和aud，但这些需要设置在Validation结构体中的预期值。

由于验证时间字段总是有点棘手，因为时钟偏差，您可以通过设置leeway参数为iat、exp和nbf验证添加一些容差。

最后但同样重要的是，如果您不使用HS256，则需要设置允许此令牌的算法。

use jsonwebtoken::{Validation, Algorithm};

// Default validation: the only algo allowed is HS256
let validation = Validation::default();
// Quick way to setup a validation where only the algorithm changes
let validation = Validation::new(Algorithm::HS512);
// Adding some leeway (in seconds) for exp and nbf checks
let mut validation = Validation {leeway: 60, ..Default::default()};
// Checking issuer
let mut validation = Validation {iss: Some("issuer".to_string()), ..Default::default()};
// Setting audience
let mut validation = Validation::default();
validation.set_audience(&"Me"); // string
validation.set_audience(&["Me", "You"]); // array of strings

算法

此库目前支持以下算法

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512
• ES256
• ES384

RSA

jsonwebtoken 目前只能读取 DER 编码的密钥。如果您已安装 openssl，可以运行以下命令从 PKCS#1 (即以 BEGIN RSA PUBLIC KEY) .pem 获取 DER 密钥。如果您有一个以 BEGIN PUBLIC KEY 开头的 PKCS#8 pem 文件，您需要首先将其转换为 PKCS#1： openssl rsa -pubin -in <filename> -RSAPublicKey_out -out <filename>.

// private key
$ openssl rsa -in private_rsa_key.pem -outform DER -out private_rsa_key.der
// public key
$ openssl rsa -in private_rsa_key.der -inform DER -RSAPublicKey_out -outform DER -out public_key.der

如果您在公钥上遇到错误，请确保您使用上述命令获取，以确保它处于正确的格式。