jwt

README

Go JWT

The JLINC protocol uses JSON WebTokens of type JWS as a compact standards-based way to transmit SISAs and SISA Events between servers.

This package supports HS256 and EdDSA/Ed25519 algorithms only and tries to be a simple as possible to enable comprehensive security audit.

Expected Usage

Installation and Usage

import "github.com/jlinclabs/go-jwt"
// then install it into your app
go mod tidy

Sign with HMAC/SHA256

/*
PayloadJSON must be a JSON string. For compatibility it should be created
without unnecessary spaces, as is done by encoding/json.Marshal or
javascript's JSON.stringify().

SecretString can be any string. For security it should be a long random string.
*/

jwt.SignHmac(PayloadJSON, SecretString string) (jsonWebtoken string, err error)

Sign with EdDSA/Ed25519

/*
PayloadJSON must be a JSON string. For compatibility it should be created
without unnecessary spaces, as is done by encoding/json.Marshal or
javascript's JSON.stringify().

PublicKey and SecretKey are an Ed25519 keypair as created for example by
crypto/ed25519.GenerateKey or libsodium's crypto_sign_keypair.

The DIDKeyUrl argument is expected to be a DID url of the form {DID}#signing 
and is placed in the JWT header under jwk.kid, i.e. a JSON-WebKey key-ID
(https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4).
*/

jwt.SignEdDsa(PayloadJSON, publicKey, privateKey, didKeyUrl string) (jsonWebtoken string, err error)

Verify a HMAC/SHA256 signed JWT

/*
Presented with a valid HMAC/SHA256 signed JWT and the secret it was signed with,
returns the JSON string payload.
*/

jwt.VerifyHmac(signedJwt string, secret []byte) (payloadJson string, err error)

Verify an EdDSA/Ed25519 signed JWT

/*
JWTs created with this package's SignEdDsa method will contain the public key that
validates the signature in the JWT's header under the jwk.x key.
See https://tools.ietf.org/html/rfc8037#section-2.

If the public key is not available that way, perhaps because the JWT was created
by a different application, then it must be supplied by the second argument.
Otherwise the publicKey argument must be nil. 
If the public key is present in both places, the supplied argument will be used.

On success returns the JSON string payload.
*/

jwt.VerifyEdDsa(signedJwt string, publicKey []byte) (payloadJson string, err error)

Documentation

Index

• func SignEdDsa(payload, publicKey, privateKey, didKeyUrl string) (signedJwt string, err error)
• func SignHmac(payload string, secret string) (signedJwt string, err error)
• func VerifyEdDsa(signedJwt string, publicKey []byte) (payloadJson string, err error)
• func VerifyHmac(signedJwt string, secret []byte) (payloadJson string, err error)
• type EdDsaHeader
• type EdDsaJwt
• type Header
• type Jwk
• type Jwt

Functions

func SignEdDsa

func SignEdDsa(payload, publicKey, privateKey, didKeyUrl string) (signedJwt string, err error)

func SignHmac

func SignHmac(payload string, secret string) (signedJwt string, err error)

func VerifyEdDsa

func VerifyEdDsa(signedJwt string, publicKey []byte) (payloadJson string, err error)

func VerifyHmac

func VerifyHmac(signedJwt string, secret []byte) (payloadJson string, err error)

Types

type EdDsaHeader

type EdDsaHeader struct {
	Algorithm string `json:"alg"`
	Type      string `json:"typ"`
	JWK       Jwk    `json:"jwk"`
}

type EdDsaJwt

type EdDsaJwt struct {
	Head      EdDsaHeader
	Payload   map[string]interface{}
	Signature []byte
}

type Header

type Header struct {
	Algorithm string `json:"alg"`
	Type      string `json:"typ"`
}

type Jwk

type Jwk struct {
	Kty string `json:"kty"`
	Crv string `json:"crv"`
	X   string `json:"x"`
	Kid string `json:"kid"`
}

type Jwt

type Jwt struct {
	Head      Header
	Payload   map[string]interface{}
	Signature []byte
}