josekit

JOSE (Javascript Object Signing and Encryption: JWT, JWS, JWE, JWA, JWK) library based on OpenSSL for Rust.

Install

toml [dependencies] josekit = "0.7.2"

This library depends on OpenSSL 1.1.1 DLL. Read more about Crate openssl.

Build

sh sudo apt install build-essential pkg-config libssl-dev cd josekit-rs cargo build --release

Supported signing algorithms

Supported encryption algorithms

Supported key formats

Private Key

Public Key

Usage

Signing a JWT by HMAC

HMAC is used to verify the integrity of a message by common secret key. Three algorithms are available for HMAC: HS256, HS384, and HS512.

You can use any bytes as the key. But the key length must be larger than or equal to the output hash size.

```rust use josekit::{JoseError, jws::{JwsHeader, HS256}, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let key = b"0123456789ABCDEF0123456789ABCDEF";

// Signing JWT
let signer = HS256.signer_from_bytes(key)?;
let jwt = jwt::encode_with_signer(&payload, &header, &signer)?;

// Verifing JWT
let verifier = HS256.verifier_from_bytes(key)?;
let (payload, header) = jwt::decode_with_verifier(&jwt, &verifier)?;

Ok(())

} ```

Signing a JWT by RSASSA

RSASSA is used to verify the integrity of a message by two keys: public and private. Three algorithms are available for RSASSA: RS256, RS384, and RS512.

You can generate the keys by executing openssl command.

```sh

Generate a new private key. Keygen bits must be 2048 or more.

openssl openssl genpkey -algorithm RSA -pkeyopt rsakeygenbits:2048 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jws::{JwsHeader, RS256}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA2048bitprivate.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA2048bitpublic.pem");

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Signing JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let signer = RS256.signer_from_pem(&private_key)?;
let jwt = jwt::encode_with_signer(&payload, &header, &signer)?;

// Verifing JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let verifier = RS256.verifier_from_pem(&public_key)?;
let (payload, header) = jwt::decode_with_verifier(&jwt, &verifier)?;

Ok(())

} ```

Signing a JWT by RSASSA-PSS

RSASSA-PSS is used to verify the integrity of a message by two keys: public and private.

The raw key format of RSASSA-PSS is the same as RSASSA. So you should use a PKCS#8 wrapped key. It contains some optional attributes.

Three algorithms are available for RSASSA-PSS: PS256, PS384, and PS512. You can generate the keys by executing openssl command.

```sh

Generate a new private key

for PS256

openssl genpkey -algorithm RSA-PSS -pkeyopt rsakeygenbits:2048 -pkeyopt rsapsskeygenmd:sha256 -pkeyopt rsapsskeygenmgf1md:sha256 -pkeyopt rsapsskeygensaltlen:32 -out private.pem

for PS384

openssl genpkey -algorithm RSA-PSS -pkeyopt rsakeygenbits:2048 -pkeyopt rsapsskeygenmd:sha384 -pkeyopt rsapsskeygenmgf1md:sha384 -pkeyopt rsapsskeygensaltlen:48 -out private.pem

for PS512

openssl genpkey -algorithm RSA-PSS -pkeyopt rsakeygenbits:2048 -pkeyopt rsapsskeygenmd:sha512 -pkeyopt rsapsskeygenmgf1md:sha512 -pkeyopt rsapsskeygensaltlen:64 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jws::{JwsHeader, PS256}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA-PSS2048bitSHA-256private.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA-PSS2048bitSHA-256public.pem");

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Signing JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let signer = PS256.signer_from_pem(&private_key)?;
let jwt = jwt::encode_with_signer(&payload, &header, &signer)?;

// Verifing JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let verifier = PS256.verifier_from_pem(&public_key)?;
let (payload, header) = jwt::decode_with_verifier(&jwt, &verifier)?;

Ok(())

} ```

Signing a JWT by ECDSA

ECDSA is used to verify the integrity of a message by two keys: public and private. Four algorithms are available for ECDSA: ES256, ES384, ES512 and ES256K.

You can generate the keys by executing openssl command.

```sh

Generate a new private key

for ES256

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-256 -out private.pem

for ES384

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-384 -out private.pem

for ES512

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-521 -out private.pem

for ES256K

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:secp256k1 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jws::{JwsHeader, ES256}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ECP-256private.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ECP-256public.pem");

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Signing JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let signer = ES256.signer_from_pem(&private_key)?;
let jwt = jwt::encode_with_signer(&payload, &header, &signer)?;

// Verifing JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let verifier = ES256.verifier_from_pem(&public_key)?;
let (payload, header) = jwt::decode_with_verifier(&jwt, &verifier)?;

Ok(())

} ```

Signing a JWT by EdDSA

EdDSA is used to verify the integrity of a message by two keys: public and private. A algorithm is only available "EdDSA" for EdDSA. But it has two curve types: Ed25519, Ed448.

You can generate the keys by executing openssl command.

```sh

Generate a new private key

for Ed25519

openssl genpkey -algorithm ED25519 -out private.pem

for Ed448

openssl genpkey -algorithm ED448 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jws::{JwsHeader, EdDSA}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ED25519private.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ED25519public.pem");

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Signing JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let signer = EdDSA.signer_from_pem(&private_key)?;
let jwt = jwt::encode_with_signer(&payload, &header, &signer)?;

// Verifing JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let verifier = EdDSA.verifier_from_pem(&public_key)?;
let (payload, header) = jwt::decode_with_verifier(&jwt, &verifier)?;

Ok(())

} ```

Encrypting a JWT by a Direct method

A "Direct" method is used to encrypt a message by CEK (content encryption key). The algorithm name is "dir" only.

You can use any bytes as the key. But the length must be the same as the length of the CEK.

```rust use josekit::{JoseError, jwe::{JweHeader, Dir}, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let key = b"0123456789ABCDEF0123456789ABCDEF";

// Encrypting JWT
let encrypter = Dir.encrypter_from_bytes(key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let decrypter = Dir.decrypter_from_bytes(key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;

Ok(())

} ```

Encrypting a JWT by ECDH-ES

ECDH-ES is used to encrypt a message a message by random bytes as CEK (content encryption key) and the CEK is delivered safely by two keys: public and private. Four algorithms are available for ECDH-ES: ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW.

The types of key are available both EC and ECX. The EC key has four curve types: P-256, P-384, P-521 and secp256k1. The ECX key has two curve types: X25519 and X448.

You can generate the keys by executing openssl command.

```sh

Generate a new private key

for P-256 EC key

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-256 -out private.pem

for P-384 EC key

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-384 -out private.pem

for P-521 EC key

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:P-521 -out private.pem

for secp256k1 EC key

openssl genpkey -algorithm EC -pkeyopt ecparamgencurve:secp256k1 -out private.pem

for X25519 ECX key

openssl genpkey -algorithm X25519 -out private.pem

for X448 ECX key

openssl genpkey -algorithm X448 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jwe::{JweHeader, ECDH_ES}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ECP-256private.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/ECP-256public.pem");

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Encrypting JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let encrypter = ECDH_ES.encrypter_from_pem(&public_key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let decrypter = ECDH_ES.decrypter_from_pem(&private_key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;

Ok(())

} ```

Encrypting a JWT by AESKW

AES is used to encrypt a message by random bytes as CEK (content encryption key) and the CEK is wrapping by common secret key. Three algorithms are available for AES: A128KW, A192KW and A256KW.

You can use any bytes as the key. But the length must be AES key size.

```rust use josekit::{JoseError, jwe::{JweHeader, A128KW}, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let key = b"0123456789ABCDEF";

// Encrypting JWT
let encrypter = A128KW.encrypter_from_bytes(key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let decrypter = A128KW.decrypter_from_bytes(key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;
Ok(())

} ```

Encrypting a JWT by AES-GCM

AES-GCM is used to encrypt a message by random bytes as CEK (content encryption key) and the CEK is wrapping by common secret key. Three algorithms are available for AES-GCM: A128GCMKW, A192GCMKW and A256GCMKW.

You can use any bytes as the key. But the length must be AES key size.

```rust use josekit::{JoseError, jwe::{JweHeader, A128GCMKW}, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let key = b"0123456789ABCDEF";

// Encrypting JWT
let encrypter = A128GCMKW.encrypter_from_bytes(key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let decrypter = A128GCMKW.decrypter_from_bytes(key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;
Ok(())

} ```

Encrypting a JWT by PBES2-HMAC+AESKW

PBES2-HMAC+AES is used to encrypt a message by random bytes as CEK (content encryption key) and the CEK is wrapping by common secret key. Three algorithms are available for AES-GCM: PBES2-HS256+A128KW, PBES2-HS384+A192KW and PBES2-HS512+A256KW.

You can use any bytes as the key. But a password is recommended that the length is no shorter than AES key size and no longer than 128 octets.

```rust use josekit::{JoseError, jwe::{JweHeader, PBES2HS256A128KW}, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let key = b"01234567";

// Encrypting JWT
let encrypter = PBES2_HS256_A128KW.encrypter_from_bytes(key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let decrypter = PBES2_HS256_A128KW.decrypter_from_bytes(key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;
Ok(())

} ```

Encrypting a JWT by RSAES

RSAES is used to encrypt a message a message by random bytes as CEK (content encryption key) and the CEK is delivered safely by two keys: public and private. Two algorithms are available for now: RSA1_5, RSA-OAEP.

You can generate the keys by executing openssl command.

```sh

Generate a new private key. Keygen bits must be 2048 or more.

openssl openssl genpkey -algorithm RSA -pkeyopt rsakeygenbits:2048 -out private.pem

Generate a public key from the private key.

openssl pkey -in private.pem -pubout -out public.pem ```

```rust use josekit::{JoseError, jwe::{JweHeader, RSA_OAEP}, jwt::{self, JwtPayload}};

const PRIVATEKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA2048bitprivate.pem"); const PUBLICKEY: &str = concat!(env!("CARGOMANIFESTDIR"), "/data/pem/RSA2048bitpublic.pem");

fn main() -> Result<(), JoseError> { let mut header = JweHeader::new(); header.settokentype("JWT"); header.setcontentencryption("A128CBC-HS256");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

// Encrypting JWT
let public_key = std::fs::read(PUBLIC_KEY).unwrap();
let encrypter = RSA_OAEP.encrypter_from_pem(&public_key)?;
let jwt = jwt::encode_with_encrypter(&payload, &header, &encrypter)?;

// Decrypting JWT
let private_key = std::fs::read(PRIVATE_KEY).unwrap();
let decrypter = RSA_OAEP.decrypter_from_pem(&private_key)?;
let (payload, header) = jwt::decode_with_decrypter(&jwt, &decrypter)?;
Ok(())

} ```

Unsecured JWT

```rust use josekit::{JoseError, jws::JwsHeader, jwt::{self, JwtPayload}};

fn main() -> Result<(), JoseError> { let mut header = JwsHeader::new(); header.settokentype("JWT");

let mut payload = JwtPayload::new();
payload.set_subject("subject");

let jwt = jwt::encode_unsecured(&payload, &header)?;
let (payload, header) = jwt::decode_unsecured(&jwt)?;
Ok(())

} ```

Validate payload

```rust,should_panic use josekit::{JoseError, jwt::{JwtPayload, JwtPayloadValidator}}; use std::time::{Duration, SystemTime};

fn main() -> Result<(), JoseError> { let mut validator = JwtPayloadValidator::new(); // value based validation validator.setissuer("http://example.com"); validator.setaudience("user1"); validator.setjwtid("550e8400-e29b-41d4-a716-446655440000");

// time based validation: not_before <= base_time < expires_at
validator.set_base_time(SystemTime::now() + Duration::from_secs(30));

// issued time based validation: min_issued_time <= issued_time <= max_issued_time
validator.set_min_issued_time(SystemTime::now() - Duration::from_secs(48 * 60));
validator.set_max_issued_time(SystemTime::now() + Duration::from_secs(24 * 60));

let mut payload = JwtPayload::new();

validator.validate(&payload)?;

Ok(())

} ```

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

References

• RFC7515: JSON Web Signature (JWS)
• RFC7516: JSON Web Encryption (JWE)
• RFC7517: JSON Web Key (JWK)
• RFC7518: JSON Web Algorithms (JWA)
• RFC7519: JSON Web Token (JWT)
• RFC7797: JSON Web Signature (JWS) Unencoded Payload Option
• RFC8017: PKCS #1: RSA Cryptography Specifications Version 2.2
• RFC5208: PKCS #8: Private-Key Information Syntax Specification Version 1.2
• RFC5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
• RFC5480: Elliptic Curve Cryptography Subject Public Key Information
• RFC5915: Elliptic Curve Private Key Structure
• RFC6979: Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)
• RFC8410: Algorithm Identifiers for Ed25519, Ed448, X25519, and X448 for Use in the Internet X.509 Public Key Infrastructure
• RFC8037: CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures in JSON Object Signing and Encryption (JOSE)
• RFC7468: Textual Encodings of PKIX, PKCS, and CMS Structures