token

README

token

Package token provides a custom access token implementation signed by Ed25519.

Usage Example

The below example is missing error handling.

pub, prv, _ := ed25519.GenerateKey(rand.Reader)

token := NewToken()
token.AddClaim("userID", "1234")
token.AddScope("create")

token.Sign(prv)
tokenStr, _ := token1.Serialize()

Documentation

Index

• Variables
• type Token
  • func NewToken() *Token
  • func Parse(serializedToken string) (*Token, error)
  • func (t *Token) AddClaim(name string, value interface{})
  • func (t *Token) AddScope(scope string)
  • func (t *Token) GetClaim(name string) interface{}
  • func (t *Token) GetStringClaim(name string) string
  • func (t *Token) HasClaim(name string) bool
  • func (t *Token) HasScope(scope string) bool
  • func (t *Token) IsSigned() bool
  • func (t *Token) RemoveClaim(name string)
  • func (t *Token) RemoveScope(scope string)
  • func (t *Token) RemoveSignature()
  • func (t *Token) Serialize() (string, error)
  • func (t *Token) SetClaim(name string, value interface{})
  • func (t *Token) Sign(privateKey ed25519.PrivateKey) error
  • func (t *Token) Verify(publicKey ed25519.PublicKey) bool

Variables

var ErrImmutableState = errors.New("the token is signed and is therefore immutable")

ErrImmutableState is returned if an operation cannot complete due to the token being signed and therefore immutable.

var ErrInvalidState = errors.New("the token is in an invalid state and cannot be mutated or operated on")

ErrInvalidState is returned when the token is in an invalid state and should be discarded.

var ErrNotSigned = errors.New("the token either does not have a signature, or the signature on it is invalid")

ErrNotSigned is returned if an operation requires that the token is signed before it can be called.

Types

type Token

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

Token represents a structured and potentially signed collection of claims and scopes. A token becomes immutable after it is signed. The only operation that can be called on a signed token is RemoveSignature.

Methods that deal with claims and scopes intentionally do not return an error, but they will ultimately do nothing if the token is signed. Use IsSigned to determine if the token is immutable.

func NewToken

func NewToken() *Token

NewToken creates a new, empty token.

func Parse

func Parse(serializedToken string) (*Token, error)

Parse takes an existing serialized token string and reverts it back into a structured instance of Token.

func (*Token) AddClaim

func (t *Token) AddClaim(name string, value interface{})

AddClaim adds a claim to the token. It will not override an existing claim.

func (*Token) AddScope

func (t *Token) AddScope(scope string)

AddScope adds a scope to the token.

func (*Token) GetClaim

func (t *Token) GetClaim(name string) interface{}

GetClaim returns the value of a claim from the token.

func (*Token) GetStringClaim

func (t *Token) GetStringClaim(name string) string

GetStringClaim returns the value of a claim as a string. This call will return an empty string if the claim does not exist or if the value is not a string.

func (*Token) HasClaim

func (t *Token) HasClaim(name string) bool

HasClaim returns true if a token has the provided claim, false otherwise.

func (*Token) HasScope

func (t *Token) HasScope(scope string) bool

HasScope returns true if a token has the provided scope, false otherwise.

func (*Token) IsSigned

func (t *Token) IsSigned() bool

IsSigned returns true if the token has a signature, false otherwise. It does not provide any information about the validity of the signature.

func (*Token) RemoveClaim

func (t *Token) RemoveClaim(name string)

RemoveClaim removes a claim from the token if it is present.

func (*Token) RemoveScope

func (t *Token) RemoveScope(scope string)

RemoveScope removes a scope from the token if it is present.

func (*Token) RemoveSignature

func (t *Token) RemoveSignature()

RemoveSignature will remove a signature on the token, if it exists.

func (*Token) Serialize

func (t *Token) Serialize() (string, error)

Serialize produces the URL safe base64 string of the signed token.

func (*Token) SetClaim

func (t *Token) SetClaim(name string, value interface{})

SetClaim sets a claim in the token. It will override an existing claim.

func (*Token) Sign

func (t *Token) Sign(privateKey ed25519.PrivateKey) error

Sign signs the token. If it is already signed, an error is returned.

func (*Token) Verify

func (t *Token) Verify(publicKey ed25519.PublicKey) bool

Verify verifies that the signature on the token matches the contents.