jst

README

JSON Secure Token (JST)

JST_SECRET := base64(crypto.randBytes(64))
secret := base64Decode(JST_SECRET)
encryptionKey := secret[:32]
auhtKey := secret[32:]

prefix := "jst.v1.local."

header.nonce := crypto.randBytes(24)
encodedHeader := Base64Url(JSON(header))

encryptedPayload := XChaCha20-Poly1305.encrypt(key=encryptionKey, data=JSON(payload), nonce=nonce)
encodedPayload := Base64Url(encryptedPayload)

signature := HMAC-SHA-256(auhtKey, prefix || encodedHeader || "." || encodedPayload)
encodedSignature := Base64Url(signature)

Token := prefix || encodedHeader || "." || encodedPayload || "." || encodedSignature

encryptionContext := "jst-v1 2023-12-31 23:59:59:999 encryption-key"
authenticationContext := "jst-v1 2024-01-01 00:00:00:000 authentication-key"

jst_master_key := crypto.randBytes(32)

nonce := crypto.randBytes(24)
encryptionKey := BLAKE3.deriveKey(encryptionContext, jst_master_key)
authenticationKey := BLAKE3.deriveKey(authenticationContext, nonce || jst_master_key)

encryptedPayload := XChaCha20.encrypt(encryptionKey, nonce, payload)

signature := BLAKE3.keyed(authenticationKey, [TODO])

tokenSignature := extractSignature(Token)
signature := HMAC-SHA-256(auhtKey, prefix || encodedHeader || "." || encodedPayload)

if constantTimeCompare(tokenSignature, signature) == false {
    return error;
}

header := Base64UrlDecode(encodedHeader)

encryptedPayload := base64UrlDecode(encodedPayload)
decryptedPayload := XChaCha20-Poly1305.decrypt(key=encryptionKey, data=encryptedPayload, nonce=header.nonce)

Documentation

Index

• Constants
• Variables
• type HeaderV1
• type KeyProvider
• type KeyProviderMemory
  • func NewKeyProviderMemory(keys map[string][]byte) *KeyProviderMemory
  • func (provider *KeyProviderMemory) GetKey(keyId string) (key []byte, err error)
• type Provider
  • func NewProvider(keyProvider KeyProvider, defaultKey string) (provider *Provider, err error)
  • func (provider *Provider) IssueToken(payload any, expiresAt *time.Time, options *TokenOptions) (token string, err error)
  • func (provider *Provider) VerifyToken(token string, data any) (header HeaderV1, err error)
• type TokenOptions

Constants

const (
	V1KeySize = 32
)

Variables

var (
	ErrTokenIsNotValid     = errors.New("jst: token is not valid")
	ErrSignatureIsNotValid = errors.New("jst: signature is not valid")
	ErrTokenHasExpired     = errors.New("jst: token has expired")
)

var (
	ErrKeyNotFound = func(keyId string) error {
		return fmt.Errorf("key (%s) not found", keyId)
	}
)

Types

type HeaderV1

type HeaderV1 struct {
	ExpiresAt   *time.Time `json:"expires_at,omitempty"`
	NotBefore   *time.Time `json:"not_before,omitempty"`
	IssuedAt    *time.Time `json:"issued_at,omitempty"`
	KeyID       string     `json:"key_id,omitempty"`
	Compression string     `json:"compression,omitempty"`
	Nonce       []byte     `json:"nonce"`
}

type KeyProvider

type KeyProvider interface {
	GetKey(keyId string) (key []byte, err error)
}

type KeyProviderMemory

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

func NewKeyProviderMemory

func NewKeyProviderMemory(keys map[string][]byte) *KeyProviderMemory

func (*KeyProviderMemory) GetKey

func (provider *KeyProviderMemory) GetKey(keyId string) (key []byte, err error)

type Provider

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

func NewProvider

func NewProvider(keyProvider KeyProvider, defaultKey string) (provider *Provider, err error)

func (*Provider) IssueToken

func (provider *Provider) IssueToken(payload any, expiresAt *time.Time, options *TokenOptions) (token string, err error)

func (*Provider) VerifyToken

func (provider *Provider) VerifyToken(token string, data any) (header HeaderV1, err error)

type TokenOptions

type TokenOptions struct {
	NotBefore   *time.Time
	IssuedAt    *time.Time
	KeyID       string
	Compression string
}