Brance - JWT的可靠替代令牌格式

包	文档	许可证	CI

Brance是JWT的可靠替代令牌格式。此实现完全用Rust编写，并使用XChaCha20-Poly1305 AEAD（带关联数据的认证加密）流密码生成可认证和加密的防篡改令牌。有关Branca令牌规范更详细的信息，请参阅branca-spec。

安全性

注意：Brance使用Orion作为其密码学原语，由于Orion没有接受任何正式的安全审计，因此如果将其用于生产环境，则与Orion相同的所有安全风险也适用于此Brance实现。有关涉及的安全风险，请参阅Orion wiki。

⚠️自行承担风险⚠️

要求

• Rust 1.52
• Cargo

安装

将以下行添加到Cargo.toml中的依赖部分

[dependencies]
branca = "^0.10.0"
getrandom = "^0.2.3"

然后您可以使用以下行将包导入到您的项目中

extern crate getrandom;
extern crate branca;
use branca::{Branca, encode, decode};

示例用法

使用此包最简单的方法是在下面的示例中使用Branca::new()

    let mut key = [0u8; 32];
    getrandom::getrandom(&mut key).unwrap();

    let mut token = Branca::new(&key).unwrap();
    let ciphertext = token.encode(b"Hello World!").unwrap();

    let payload = token.decode(ciphertext.as_str(), 0).unwrap();
    println!("{}", payload); // "Hello World!"

请参阅Branca结构体和文档部分中的设置字段的更多示例。

不使用Brance构建器的直接使用

编码

let mut key = [0u8; 32];
getrandom::getrandom(&mut key).unwrap();

let message = b"Hello world!";
let timestamp = 123206400;
let branca_token = encode(message, &key, timestamp).unwrap();

// branca_token = 875GH233T7.......

解码

let ciphertext = branca_token.as_str();
let ttl = 0; // The ttl can be used to determine if the supplied token has expired or not.
let decoded = decode(ciphertext, &key, ttl);

if decoded.is_err() {
    // Error
} else {
    let msg = decoded.unwrap(); 
    // msg = "Hello world!"
}

使用Serde对任意数据结构进行编码/解码。

由于Brance能够与任何格式在有效载荷中的数据一起工作，因此有效载荷可以是JSON对象、纯文本、原始字节、协议缓冲区，甚至是JWT。

以下是一个使用Branca通过serde_json编码/解码典型JSON对象的示例。

将以下内容添加到您的Cargo.toml文件中

[dependencies]
branca = "^0.10.0"
serde_json = "^1.0"
serde_derive = "1.0.97"

#[macro_use]
extern crate serde_json;
#[macro_use]
extern crate serde_derive;
extern crate branca;
extern crate getrandom;

use branca::{encode, decode};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    user: String,
    scope: Vec<String>,
}

fn main(){

    let message = json!({
        "user" : "[email protected]",
        "scope":["read", "write", "delete"],
    }).to_string();

    let mut key = [0u8; 32];
    getrandom::getrandom(&mut key).unwrap();
    
    let mut token = Branca::new(&key).unwrap();
    
    // Encode Message
    let branca_token = token.encode(message.as_bytes()).unwrap();
    
    // Decode Message
    let payload = token.decode(branca_token.as_str(), 0).unwrap();

    let json: User = serde_json::from_str(payload.as_str()).unwrap();

    println!("{}", branca_token);
    println!("{}", payload);
    println!("{:?}", json);
}

Brancia 使用 Orion 在使用 encode() 和构建方法时生成安全的随机数。默认情况下，Brancia 不允许直接设置数，因为这存在用户可能会重复使用它的风险，这是一种危险的行为。

生成的数长度必须是 24 字节。 密钥长度必须是 32 字节。

构建

cargobuild

测试

cargotest

贡献

欢迎贡献和补丁！请 Fork 此仓库，添加您的更改并发送 PR。

在您发送 PR 之前，请确保先运行 cargo test 以检查您的更改是否通过了测试。

如果您想修复错误或添加增强功能，请在问题部分进行，并提供关于您的更改的简要描述。

许可证

MIT