keygrip

README

keygrip

Keygrip is a module for signing and verifying data (such as cookies or URLs) through a rotating credential system, in which new server keys can be added and old ones removed regularly, without invalidating client credentials. It derives from crypto-utils/keygrip.

Signatures use HMAC-SHA256 and are encoded with base64.RawURLEncoding.

API

kg := keygrip.New(keyList []string)

kg := keygrip.New([]string{
    "key1",
    "key2",
})

For concurrent use (e.g. rotating keys while signing), create with NewRWMutex:

kg := keygrip.NewRWMutex([]string{
    "key1",
    "key2",
})

Sign(data []byte)

Get the base64 digest (RawURLEncoding) using the first key in the key list.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
str := kg.Sign([]byte("tree.xie"))
// lOvR3UDUZm9jkNUsvtOyCnnxVkCn3QOaElodqz54_A8
fmt.Println(string(str))

Verify(data, digest []byte)

Loops through all keys until the digest matches. Returns false if none match or the digest is not valid encoding.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
fmt.Println(kg.Verify([]byte("tree.xie"), []byte("lOvR3UDUZm9jkNUsvtOyCnnxVkCn3QOaElodqz54_A8")))
// true

Index(data, digest []byte)

Returns the index of the matching key, -1 if no key matches, or -2 if the digest is not valid base64.RawURLEncoding.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
fmt.Println(kg.Index([]byte("tree.xie"), []byte("lOvR3UDUZm9jkNUsvtOyCnnxVkCn3QOaElodqz54_A8")))
// 0

AddKey(key string)

Adds a key to the front of the list (preferred for new signatures). Existing keys still verify until removed.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
kg.AddKey("key3")

RemoveKey(key string)

Removes a key from the list. Missing keys are ignored. The last remaining key is never removed (no-op), so Sign always has a credential.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
kg.RemoveKey("key1")

SetKeys(keys []string)

Replaces the entire key list. keys must not be empty (panics if empty).

kg.SetKeys([]string{"new-key-1", "new-key-2"})

Keys()

Returns a copy of the current key list.

kg := keygrip.New([]string{
    "key1",
    "key2",
})
kg.Keys()

test

make test-cover

bench

make bench

Documentation

Index

• type Keygrip
  • func New(keys []string) *Keygrip
  • func NewRWMutex(keys []string) *Keygrip
  • func (kg *Keygrip) AddKey(key string)
  • func (kg *Keygrip) Index(data, digest []byte) int
  • func (kg *Keygrip) Keys() []string
  • func (kg *Keygrip) RemoveKey(key string)
  • func (kg *Keygrip) SetKeys(keys []string)
  • func (kg *Keygrip) Sign(data []byte) []byte
  • func (kg *Keygrip) Verify(data, digest []byte) bool

Types

type Keygrip

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

Keygrip keygrip struct

func New

func New(keys []string) *Keygrip

New returns a new keygrip. keys must not be empty.

func NewRWMutex

func NewRWMutex(keys []string) *Keygrip

NewRWMutex returns a new keygrip protected by an RWMutex for concurrent use.

func (*Keygrip) AddKey

func (kg *Keygrip) AddKey(key string)

AddKey adds the key to the front of the key list (preferred for signing). If the key already exists, this is a no-op.

func (*Keygrip) Index

func (kg *Keygrip) Index(data, digest []byte) int

Index returns the index of the key which matches digest. It returns -2 if the digest is not valid base64.RawURLEncoding. It returns -1 if no key matches the digest (including wrong-length digests).

func (*Keygrip) Keys

func (kg *Keygrip) Keys() []string

Keys returns a copy of the current key list as strings.

func (*Keygrip) RemoveKey

func (kg *Keygrip) RemoveKey(key string)

RemoveKey removes the key from the key list. Missing keys are ignored. The last remaining key is never removed (no-op) so Sign always has a credential.

func (*Keygrip) SetKeys

func (kg *Keygrip) SetKeys(keys []string)

SetKeys replaces the entire key list. keys must not be empty.

func (*Keygrip) Sign

func (kg *Keygrip) Sign(data []byte) []byte

Sign returns the base64.RawURLEncoding digest using the first key.

func (*Keygrip) Verify

func (kg *Keygrip) Verify(data, digest []byte) bool

Verify returns true if the digest was created by one of the current keys.