fpast2l

README

fpast2l

PASETO is a specification for secure, stateless authentication tokens. fpast2l is Go implementation of only the secret/symmetric part of version 2 of the PASETO spec.

There exists at least one implementation: o1egl/paseto, that covers the complete PASETO specification, is probably better written and better documenting. You should be using that instead.

The aim of fpast2l is not to be a complete or compatible implementation of the entire PASETO standard. It is written to meet specific needs and has no ambition for any sort of general use.

The key aim is to implement fast v2.local token generation in pure-Go with the least amount of garbage possible. It is currently not completely garbage free, which is what the roadmap will focus on. It is, however, slightly faster than o1egl's implementation and produces less garbage.

Documentation

Index

• Constants
• Variables
• func Decrypt(K, p []byte, s string) ([]byte, error)
• func Encrypt(K, b []byte, f string) string
• type Engine
  • func New(K []byte) (eng Engine)
  • func (eng Engine) Decrypt(p []byte, s string) (b []byte, err error)
  • func (eng Engine) Encrypt(b []byte) string
  • func (eng Engine) WithFooter(f string) Engine
• type Error
  • func AsError(err error) Error
  • func (e Error) Error() string
  • func (e Error) Internal() bool
  • func (e Error) String() string
  • func (e Error) Unwrap() error

Constants

const KeySize = chacha20poly1305.KeySize

KeySize is the required length of the encryption key.

Variables

var (
	ErrBadKeySize        = Error{errors.New("bad key size")}
	ErrBadHeader         = Error{errors.New("bad header")}
	ErrBadEncoding       = Error{errors.New("bad encoding")}
	ErrBadEncryption     = Error{errors.New("decryption failed")}
	ErrEngNotInitialized = Error{errors.New("eng not properly initialized")}
)

Errors.

Functions

func Decrypt

func Decrypt(K, p []byte, s string) ([]byte, error)

Decrypt is a shorthand for creating a new Engine with K as decryption key and f as footer, decoding and decrypting s as a PASETO v2 local token appending the resulting payload to p and returning it.

It is recommended to use Engine unless this is a one-time operation.

func Encrypt

func Encrypt(K, b []byte, f string) string

Encrypt is a shorthand for creating a new Engine with K as encryption key and f as footer, encrypting and encoding b and returning the PASETO v2 local token.

It is recommended to use Engine unless this is a one-time operation.

Types

type Engine

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

Engine is a PASETO generator. It can be reused concurrently to generate multiple v2 local tokens as long as the encryption key and footer stay the same.

To facilitate concurrency, Engine should not mutate. Make copies (e.g. WithFooter), avoid references.

func New

func New(K []byte) (eng Engine)

New constructs and returns a new Engine, with the encryption key K. New will panic if len(K) is not exactly KeySize bytes.

func (Engine) Decrypt

func (eng Engine) Decrypt(p []byte, s string) (b []byte, err error)

Decrypt parses and decrypt s as a PASETO v2 local token. If successful, resulting plaintext is appended to p and returned.

Extra capacity of p, if available, is used for computation. Even if the encryption is unsuccessful, p should be overwritten or thrown away.

func (Engine) Encrypt

func (eng Engine) Encrypt(b []byte) string

Encrypt creates and returns a new PASETO v2 local token from the payload contained in b. b is encrypted in-place, meaning the contents of b will be overwritten with raw ciphertext. It is safe to reuse b or throw it away.

func (Engine) WithFooter

func (eng Engine) WithFooter(f string) Engine

WithFooter returns a copy of Engine with the footer in the copy set to f.

type Error

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

Error is an error returned by this package.

func AsError

func AsError(err error) Error

AsError wraps err in a Error unless err is itself a Error then it returns err.

func (Error) Error

func (e Error) Error() string

Error implements the builtin error interface. It returns the string representation of the Error.

func (Error) Internal

func (e Error) Internal() bool

Internal returns whether Error was a package-internal error. Package-internal errors are worst-case and typically should not leak outside of this package.

func (Error) String

func (e Error) String() string

String implements fmt.Stringer interface. It returns the string representation of the error that is wrapped by the Error e.

func (Error) Unwrap

func (e Error) Unwrap() error

Unwrap facilitates the errors.Unwrap function. It returns the error wrapped by Error e.