Skip to content

Latest commit

 

History

History
167 lines (107 loc) · 4.35 KB

README.md

File metadata and controls

167 lines (107 loc) · 4.35 KB

Zig-jwt

A JWT (JSON Web Token) library for zig.

Env

  • Zig >= 0.14.0-dev.2851+b074fb7dd

What the heck is a JWT?

JWT.io has a great introduction to JSON Web Tokens.

In short, it's a signed JSON object that does something useful (for example, authentication). It's commonly used for Bearer tokens in Oauth 2. A token is made of three parts, separated by .'s. The first two parts are JSON objects, that have been base64url encoded. The last part is the signature, encoded the same way.

The first part is called the header. It contains the necessary information for verifying the last part, the signature. For example, which encryption method was used for signing and what key was used.

The part in the middle is the interesting bit. It's called the Claims and contains the actual stuff you care about. Refer to RFC 7519 for information about reserved keys and the proper way to add your own.

What's in the box?

This library supports the parsing and verification as well as the generation and signing of JWTs. Current supported signing algorithms are HMAC SHA, RSA, RSA-PSS, and ECDSA, though hooks are present for adding your own.

Adding zig-jwt as a dependency

Add the dependency to your project:

zig fetch --save=zig-jwt git+https://github.com/deatil/zig-jwt#main

or use local path to add dependency at build.zig.zon file

.{
    .dependencies = .{
        .@"zig-jwt" = .{
            .path = "./lib/zig-jwt",
        },
        ...
    }
}

And the following to your build.zig file:

const zig_jwt_dep = b.dependency("zig-jwt", .{});
exe.root_module.addImport("zig-jwt", zig_jwt_dep.module("zig-jwt"));

The zig-jwt structure can be imported in your application with:

const zig_jwt = @import("zig-jwt");

Get Starting

const std = @import("std");
const jwt = @import("zig-jwt");

pub fn main() !void {
    const alloc = std.heap.page_allocator;

    const kp = jwt.eddsa.Ed25519.KeyPair.generate();

    const claims = .{
        .aud = "example.com",
        .sub = "foo",
    };

    const s = jwt.SigningMethodEdDSA.init(alloc);
    const token_string = try s.sign(claims, kp.secret_key);
    
    // output: 
    // make jwt: eyJ0eXAiOiJKV1QiLCJhbGciOiJFZERTQSJ9.eyJhdWQiOiJleGFtcGxlLmNvbSIsInN1YiI6ImZvbyJ9.8aYTV-9_Z1RQUPepUlut9gvniX_Cx_z8P60Z5FbnMMgNLPNP29ZtNG3k6pcU2TY_O3DkSsdxbN2HkmgvjDUPBg
    std.debug.print("make jwt: {s} \n", .{token_string});

    const p = jwt.SigningMethodEdDSA.init(alloc);
    var parsed = try p.parse(token_string, kp.public_key);
    
    // output: 
    // claims aud: example.com
    const claims2 = try parsed.getClaims();
    std.debug.print("claims aud: {s} \n", .{claims2.object.get("aud").?.string});
}

Signing Methods

The JWT library have signing methods:

  • RS256: jwt.SigningMethodRS256

  • RS384: jwt.SigningMethodRS384

  • RS512: jwt.SigningMethodRS512

  • PS256: jwt.SigningMethodPS256

  • PS384: jwt.SigningMethodPS384

  • PS512: jwt.SigningMethodPS512

  • ES256: jwt.SigningMethodES256

  • ES384: jwt.SigningMethodES384

  • EdDSA: jwt.SigningMethodEdDSA

  • ED25519: jwt.SigningMethodED25519

  • HS256: jwt.SigningMethodHS256

  • HS384: jwt.SigningMethodHS384

  • HS512: jwt.SigningMethodHS512

  • none: jwt.SigningMethodNone

Sign PublicKey

RSA PublicKey:

const secret_key = jwt.crypto_rsa.SecretKey;
const public_key = jwt.crypto_rsa.PublicKey;

// rsa no generate

ECDSA PublicKey:

const ecdsa = std.crypto.sign.ecdsa;

const p256_secret_key = ecdsa.EcdsaP256Sha256.SecretKey;
const p256_public_key = ecdsa.EcdsaP256Sha256.PublicKey;

const p384_secret_key = ecdsa.EcdsaP384Sha384.SecretKey;
const p384_public_key = ecdsa.EcdsaP384Sha384.PublicKey;

// generate p256 public key
const p256_kp = ecdsa.EcdsaP256Sha256.KeyPair.generate();

// generate p384 public key
const p384_kp = ecdsa.EcdsaP384Sha384.KeyPair.generate();

EdDSA PublicKey:

const Ed25519 = std.crypto.sign.Ed25519;

const secret_key = Ed25519.SecretKey;
const public_key = Ed25519.PublicKey;

// generate public key
const kp = Ed25519.KeyPair.generate();

LICENSE

  • The library LICENSE is Apache2, using the library need keep the LICENSE.

Copyright