fwt

package module
v2.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2025 License: MIT Imports: 20 Imported by: 0

README

Fast Web Token

Build Status Go Reference Go Report Card

A lightweight, high-performance JWT alternative leveraging CBOR serialization with multiple secure signing options.

Features

  • Multiple secure signing options (EdDSA, HMAC, Blake2b, Blake3)
  • Compact binary format using CBOR
  • High-performance implementation
  • Post-quantum resistant signatures (Ed448)
  • Customizable CBOR encoding
  • Lightweight design

Installation

go get github.com/DeltaLaboratory/fwt/v2

Quick Start

Create and Sign a Token
package main

import (
	"time"

	"github.com/DeltaLaboratory/fwt/v2"
)

func main() {
	signer, err := fwt.NewSigner(fwt.NewBlake3Signer([]byte("somekeyhere")))
	
	if err != nil {
		panic(err)
	}

	payload := map[string]any{
		"user_id": 123,
		"exp":     time.Now().Add(time.Hour).Unix(),
	}

	token, err := signer.Sign(payload)
	if err != nil {
		panic(err)
	}
}
Verify a Token
package main

import "github.com/DeltaLaboratory/fwt/v2"

func verifyToken(token []byte) {
	verifier, err := fwt.NewVerifier(fwt.NewBlake3Verifier([]byte("somekey")))
	
	if err != nil {
		panic(err)
	}
	
	var payload map[string]any
	if err := verifier.VerifyAndUnmarshal(token, &payload); err != nil {
		panic(err)
	}
}

For more example, see test code.

Token Structure

FWT uses a compact binary structure:

Section Size Description
Header 2 ~ 10 bytes (vary) Type + Payload Size
Payload Variable (CBOR) Token Data
Signature 32/64/114 bytes Cryptographic Signature

Supported Algorithms

Algorithm Signature Size (bytes)
Ed25519 64
Ed448 114
HMACSha256 32
HMACSha512 64
Blake2b256 32
Blake2b512 64
Blake3 32

Supported Encryption Algorithms

Algorithm Type
XChaCha20-Poly1305 AEAD
AES-GCM AEAD
AES-CBC Block Cipher
AES-CTR Stream Cipher
HPKE Hybrid
AES-ECB Block Cipher

Advanced Usage

Custom CBOR Encoding
// Set custom encoder
fwt.SetEncoder(customEncoder)

// Set custom decoder
fwt.SetDecoder(customDecoder)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrCreateSigner     = errors.New("failed to create signer")
	ErrCreateEncryptor  = errors.New("failed to create encryptor")
	ErrCreateVerifier   = errors.New("failed to create verifier")
	ErrCreateDecrypter  = errors.New("failed to create decrypter")
	ErrMarshalData      = errors.New("failed to marshal data")
	ErrSignData         = errors.New("failed to sign data")
	ErrEncodeVLQ        = errors.New("failed to encode VLQ")
	ErrEncryptData      = errors.New("failed to encrypt data")
	ErrDecodeToken      = errors.New("failed to decode token")
	ErrDecryptData      = errors.New("failed to decrypt data")
	ErrTokenTooShort    = errors.New("invalid token: too short")
	ErrInvalidSigType   = errors.New("invalid token: invalid signature type")
	ErrDecodeVLQ        = errors.New("failed to decode VLQ")
	ErrInvalidLength    = errors.New("invalid token: invalid marshaled length")
	ErrInvalidSignature = errors.New("invalid signature")
	ErrVerifySignature  = errors.New("failed to verify signature")
	ErrUnmarshalData    = errors.New("failed to unmarshal data")
)
View Source 
var (
	ErrEmptyBuffer      = errors.New("empty buffer")
	ErrIncompleteNumber = errors.New("incomplete VLQ number")
	ErrBufferTooSmall   = errors.New("buffer too small")
	ErrValueTooLarge    = errors.New("value too large to encode")
)

Functions

func NewHPKEDecrypter 

func NewHPKEDecrypter(key kem.PrivateKey, suite hpke.Suite, info ...string) func([]byte) ([]byte, error)

NewHPKEDecrypter creates a new decrypter using HPKE. Experimental, not recommended for production use.

func NewHPKEEncryptor 

func NewHPKEEncryptor(key kem.PublicKey, suite hpke.Suite, info ...string) func([]byte) ([]byte, error)

NewHPKEEncryptor creates a new encryptor using HPKE. Experimental, not recommended for production use.

func SetDecoder 

func SetDecoder(dec cbor.DecMode)

SetDecoder set custom cbor decoder.

func SetEncoder 

func SetEncoder(enc cbor.EncMode)

SetEncoder set custom cbor encoder.

Types

type DecrypterFactory 

type DecrypterFactory func() (DecrypterFunc, error)

func NewAESCBCDecrypter 

func NewAESCBCDecrypter(key []byte) DecrypterFactory

NewAESCBCDecrypter creates a new decrypter using AES-CBC.

func NewAESCTRDecrypter 

func NewAESCTRDecrypter(key []byte) DecrypterFactory

NewAESCTRDecrypter creates a new decrypter using AES-CTR.

func NewAESECBDecrypter 

func NewAESECBDecrypter(key []byte) DecrypterFactory

NewAESECBDecrypter creates a new decrypter using AES-ECB. Disclaimer: ECB is not secure, it must not be used in production. Please use AES-CBC or AES-GCM instead. See https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB).

func NewAESGCMDecrypter 

func NewAESGCMDecrypter(key []byte) DecrypterFactory

NewAESGCMDecrypter creates a new decrypter using AES-GCM.

func NewXChaCha20PolyDecrypter 

func NewXChaCha20PolyDecrypter(key []byte) DecrypterFactory

NewXChaCha20PolyDecrypter creates a new decrypter using XChaCha20-Poly1305.

type DecrypterFunc 

type DecrypterFunc func([]byte) ([]byte, error)

type EncryptorFactory 

type EncryptorFactory func() (EncryptorFunc, error)

func NewAESCBCEncryptor 

func NewAESCBCEncryptor(key []byte, randPool ...io.Reader) EncryptorFactory

NewAESCBCEncryptor creates a new encryptor using AES-CBC.

func NewAESCTREncryptor 

func NewAESCTREncryptor(key []byte, randPool ...io.Reader) EncryptorFactory

NewAESCTREncryptor creates a new encryptor using AES-CTR.

func NewAESECBEncryptor 

func NewAESECBEncryptor(key []byte) EncryptorFactory

NewAESECBEncryptor creates a new encryptor using AES-ECB. Disclaimer: ECB is not secure, it must not be used in production. Please use AES-CBC or AES-GCM instead. See https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_codebook_(ECB).

func NewAESGCMEncryptor 

func NewAESGCMEncryptor(key []byte, randPool ...io.Reader) EncryptorFactory

NewAESGCMEncryptor creates a new encryptor using AES-GCM.

func NewXChaCha20PolyEncryptor 

func NewXChaCha20PolyEncryptor(key []byte, randPool ...io.Reader) EncryptorFactory

NewXChaCha20PolyEncryptor creates a new encryptor using XChaCha20-Poly1305.

type EncryptorFunc 

type EncryptorFunc func([]byte) ([]byte, error)

type SignatureType 

type SignatureType int

SignatureType is the type of signature. 

const (
	// SignatureTypeEd25519 is the signature type of Ed25519.
	SignatureTypeEd25519 SignatureType = iota
	// SignatureTypeEd448 is the signature type of Ed448.
	SignatureTypeEd448
	// SignatureTypeHMACSha256 is the signature type of HMAC-SHA256.
	SignatureTypeHMACSha256
	// SignatureTypeHMACSha512 is the signature type of HMAC-SHA512.
	SignatureTypeHMACSha512
	// SignatureTypeBlake2b256 is the signature type of blake2b-256.
	SignatureTypeBlake2b256
	// SignatureTypeBlake2b512 is the signature type of blake2b-512.
	SignatureTypeBlake2b512
	// SignatureTypeBlake3 is the signature type of blake3.
	SignatureTypeBlake3
)

Signature types.

type Signer 

type Signer struct {
	// contains filtered or unexported fields
}

Signer is a token factory & signer.

func NewSigner 

func NewSigner(signer SignerFactory, encryptor ...EncryptorFactory) (*Signer, error)

NewSigner creates a new signer. signer is a function that takes a marshaled data and returns a signature. encryptor is an optional function that takes a token and returns an encrypted token. signatureType is the type of signature, must be matched with the signer.

func (*Signer) Sign 

func (s *Signer) Sign(data any) (string, error)

Sign signs the data and returns a signed token. If encryptor is set, the token will be encrypted.

Example 
HMACKey := []byte("00000000000000000000000000000000")
signer, err := NewSigner(NewBlake3Signer(HMACKey), nil)
if err != nil {
	panic(err)
}
token, err := signer.Sign(testStruct)
if err != nil {
	panic(err)
}
fmt.Println(token)

Output:
BkikARgqAngvdGhlIGFuc3dlciB0byBsaWZlLCB0aGUgdW5pdmVyc2UgYW5kIGV2ZXJ5dGhpbmcDGkr58HAESnNvbWUgYnl0ZXMsbJnJZYZek95hXQommFdPRk0x_cpPMq850WOW3KUqgg

type SignerFactory 

type SignerFactory func() (SignatureType, SignerFunc, error)

func NewBlake2b256Signer 

func NewBlake2b256Signer(key []byte) SignerFactory

NewBlake2b256Signer creates a new signer using blake2b-256 with a key.

func NewBlake2b512Signer 

func NewBlake2b512Signer(key []byte) SignerFactory

NewBlake2b512Signer creates a new signer using blake2b-512 with a key.

func NewBlake3Signer 

func NewBlake3Signer(key []byte) SignerFactory

NewBlake3Signer creates a new signer using blake3 with a key.

func NewEd448Signer 

func NewEd448Signer(key []byte, context ...string) SignerFactory

NewEd448Signer creates a new signer using Ed448 with ed448.PrivateKey. context is optional and defaults to empty string. please refer to https://tools.ietf.org/html/rfc8032#section-5.2.6 for more information.

func NewEd25519Signer 

func NewEd25519Signer(key []byte) SignerFactory

NewEd25519Signer creates a new signer using Ed25519 with 32 bytes seed.

func NewHMACSha256Signer 

func NewHMACSha256Signer(key []byte) SignerFactory

NewHMACSha256Signer creates a new signer using HMAC-SHA256 with a key.

func NewHMACSha512Signer 

func NewHMACSha512Signer(key []byte) SignerFactory

NewHMACSha512Signer creates a new signer using HMAC-SHA512 with a key.

type SignerFunc 

type SignerFunc func([]byte) ([]byte, error)

type Verifier 

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier is a token verifier.

func NewVerifier 

func NewVerifier(verifier VerifierFactory, decrypter ...DecrypterFactory) (*Verifier, error)

NewVerifier creates a new verifier. verifier is a function that takes a marshaled data and a signature and returns an error if the signature is invalid. decrypter is an optional function that takes a token and returns a decrypted token. signatureType is the type of signature, must be matched with the verifier.

func (*Verifier) Verify 

func (v *Verifier) Verify(token string) error

Verify verifies the token.

Example 
HMACKey := []byte("00000000000000000000000000000000")
verifier, err := NewVerifier(NewBlake3Verifier(HMACKey), nil)
if err != nil {
	panic(err)
}
if err := verifier.Verify("BkikARgqAngvdGhlIGFuc3dlciB0byBsaWZlLCB0aGUgdW5pdmVyc2UgYW5kIGV2ZXJ5dGhpbmcDGkr58HAESnNvbWUgYnl0ZXMsbJnJZYZek95hXQommFdPRk0x_cpPMq850WOW3KUqgg"); err != nil {
	panic(err)
}
fmt.Println("token is valid")

Output:
token is valid

func (*Verifier) VerifyAndUnmarshal 

func (v *Verifier) VerifyAndUnmarshal(token string, dst any) error

VerifyAndUnmarshal verifies the token and unmarshal the data into dst.

Example 
HMACKey := []byte("00000000000000000000000000000000")
verifier, err := NewVerifier(NewBlake3Verifier(HMACKey), nil)
if err != nil {
	panic(err)
}
result := new(TestStruct)
if err := verifier.VerifyAndUnmarshal("BkikARgqAngvdGhlIGFuc3dlciB0byBsaWZlLCB0aGUgdW5pdmVyc2UgYW5kIGV2ZXJ5dGhpbmcDGkr58HAESnNvbWUgYnl0ZXMsbJnJZYZek95hXQommFdPRk0x_cpPMq850WOW3KUqgg", result); err != nil {
	panic(err)
}
fmt.Printf("A: %d, B: %s, C: %s, D: %s", result.A, result.B, result.C.UTC().Format("2006-01-02"), result.D)

Output:
A: 42, B: the answer to life, the universe and everything, C: 2009-11-10, D: some bytes

type VerifierFactory 

type VerifierFactory func() (SignatureType, VerifierFunc, error)

func NewBlake2b256Verifier 

func NewBlake2b256Verifier(key []byte) VerifierFactory

NewBlake2b256Verifier creates a new verifier using blake2b-256 with a key.

func NewBlake2b512Verifier 

func NewBlake2b512Verifier(key []byte) VerifierFactory

NewBlake2b512Verifier creates a new verifier using blake2b-512 with a key.

func NewBlake3Verifier 

func NewBlake3Verifier(key []byte) VerifierFactory

NewBlake3Verifier creates a new verifier using blake3 with a key.

func NewEd448Verifier 

func NewEd448Verifier(key []byte, context ...string) VerifierFactory

NewEd448Verifier creates a new verifier using Ed448 with ed448.PublicKey. context is optional and defaults to empty string. please refer to https://tools.ietf.org/html/rfc8032#section-5.2.6 for more information.

func NewEd25519Verifier 

func NewEd25519Verifier(key []byte) VerifierFactory

NewEd25519Verifier creates a new verifier using Ed25519 with ed25519.PublicKey

func NewHMACSha256Verifier 

func NewHMACSha256Verifier(key []byte) VerifierFactory

NewHMACSha256Verifier creates a new verifier using HMAC-SHA256 with a key.

func NewHMACSha512Verifier 

func NewHMACSha512Verifier(key []byte) VerifierFactory

NewHMACSha512Verifier creates a new verifier using HMAC-SHA512 with a key.

type VerifierFunc 

type VerifierFunc func([]byte, []byte) error

Source Files

View all Source files

Directories

Path Synopsis
internal
memory
pkcs7

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.