tokenizer

README

Tokenizer

The tokenizer package provides encoding for tokens that can carry user data in a secure way.

Tokens generated with this tokenizer consist of:

token = base64url(iv,aes(pkcs7(ts,data)),hmac)

All tokens embed the time they were created, and that information is available when the token is decoded. Time is always in UTC, with 1s precision.

Usage

Download:

go get github.com/go-web/tokenizer

See the example for details.

Documentation

Overview

Package tokenizer provides encoding for tokens that can carry user data.

Tokens are made up of base64url(iv,aes(pkcs7(ts,data)),hmac) where the iv is random, and hmac signs iv,aes(...).

Index

• Variables
• func NewKey(size int) []byte
• type T
  • func New(aesKey, hmacKey []byte, f func() hash.Hash) (*T, error)
  • func (tok *T) Decode(token []byte) (data []byte, creation time.Time, err error)
  • func (tok *T) Encode(data []byte) (token []byte, err error)

Examples

• T

Variables

var (
	// ErrInvalidBlockSize indicates hash blocksize <= 0.
	ErrInvalidBlockSize = errors.New("invalid blocksize")

	// ErrInvalidPKCS7Data indicates bad input to PKCS7 pad or unpad.
	ErrInvalidPKCS7Data = errors.New("invalid PKCS7 data (empty or not padded)")

	// ErrInvalidPKCS7Padding indicates PKCS7 unpad fails to bad input.
	ErrInvalidPKCS7Padding = errors.New("invalid padding on input")
)

PKCS7 errors.

var (
	// ErrInvalidToken indicates the input to Decode
	// is invalid.
	ErrInvalidToken = errors.New("tokenizer: invalid token")

	// ErrInvalidTokenSignature indicates the input to Decode
	// contains an invalid signature.
	ErrInvalidTokenSignature = errors.New("tokenizer: invalid token signature")
)

Tokenizer errors.

Functions

func NewKey

func NewKey(size int) []byte

NewKey creates a new random key of the given size.

Types

type T

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

T provides a cryptographic token that can carry user data. Tokens consist of user-data encrypted with AES, an HMAC signature and a UTC timestamp with second precision.

Example

package main

import (
	"crypto/aes"
	"crypto/sha256"
	"fmt"
	"log"
	"time"

	"github.com/go-web/tokenizer"
)

func main() {
	aesKey := tokenizer.NewKey(aes.BlockSize)
	hmacKey := tokenizer.NewKey(sha256.BlockSize)
	t, err := tokenizer.New(aesKey, hmacKey, nil)
	if err != nil {
		log.Fatal(err)
	}
	token, err := t.Encode([]byte("hello world"))
	if err != nil {
		log.Fatal(err)
	}
	data, created, err := t.Decode(token)
	if err != nil {
		log.Fatal(err)
	}
	elapsed := time.Since(created)
	fmt.Printf("%s from %ds ago", data, int(elapsed.Seconds()))
}

Output:
hello world from 0s ago

func New

func New(aesKey, hmacKey []byte, f func() hash.Hash) (*T, error)

New creates and initializes a new tokenizer T. sha256.New is used for HMAC in case f is nil.

func (*T) Decode

func (tok *T) Decode(token []byte) (data []byte, creation time.Time, err error)

Decode decodes the given token and return its data and creation time in UTC.

func (*T) Encode

func (tok *T) Encode(data []byte) (token []byte, err error)

Encode encodes the given byte slice and returns a token.