nonce

Documentation

Overview

Package nonce implements a service for generating and redeeming nonces. To generate a nonce, it encrypts a monotonically increasing counter (latest) using an authenticated cipher. To redeem a nonce, it checks that the nonce decrypts to a valid integer between the earliest and latest counter values, and that it's not on the cross-off list. To avoid a constantly growing cross-off list, the nonce service periodically retires the oldest counter values by finding the lowest counter value in the cross-off list, deleting it, and setting "earliest" to its value. To make this efficient, the cross-off list is represented two ways: Once as a map, for quick lookup of a given value, and once as a heap, to quickly find the lowest value. The MaxUsed value determines how long a generated nonce can be used before it is forgotten. To calculate that period, divide the MaxUsed value by average redemption rate (valid POSTs per second).

Index

• Constants
• func DerivePrefix(grpcAddr string, key []byte) string
• type Getter
  • func NewGetter(cc grpc.ClientConnInterface) Getter
• type HMACKeyCtxKey
• type NonceService
  • func NewNonceService(stats prometheus.Registerer, maxUsed int, prefix string) (*NonceService, error)
  • func (ns *NonceService) Nonce(_ context.Context, _ *emptypb.Empty) (*noncepb.NonceMessage, error)
  • func (ns *NonceService) Redeem(ctx context.Context, msg *noncepb.NonceMessage) (*noncepb.ValidMessage, error)
• type PrefixCtxKey
• type Redeemer
  • func NewRedeemer(cc grpc.ClientConnInterface) Redeemer

Constants

const (
	// PrefixLen is the character length of a nonce prefix.
	PrefixLen = 8

	// NonceLen is the character length of a nonce, excluding the prefix.
	NonceLen = 32
)

Functions

func DerivePrefix

func DerivePrefix(grpcAddr string, key []byte) string

DerivePrefix derives a nonce prefix from the provided listening address and key. The prefix is derived by take the first 8 characters of the base64url encoded HMAC-SHA256 hash of the listening address using the provided key.

Types

type Getter

type Getter interface {
	Nonce(ctx context.Context, in *emptypb.Empty, opts ...grpc.CallOption) (*noncepb.NonceMessage, error)
}

Getter is an interface for an RPC client that can get a nonce.

func NewGetter

func NewGetter(cc grpc.ClientConnInterface) Getter

NewGetter returns a new noncepb.NonceServiceClient which can only be used to get nonces.

type HMACKeyCtxKey

type HMACKeyCtxKey struct{}

HMACKeyCtxKey is exported for use as a key in a context.Context.

type NonceService

type NonceService struct {
	noncepb.UnsafeNonceServiceServer
	// contains filtered or unexported fields
}

NonceService generates, cancels, and tracks Nonces.

func NewNonceService

func NewNonceService(stats prometheus.Registerer, maxUsed int, prefix string) (*NonceService, error)

NewNonceService constructs a NonceService with defaults

func (*NonceService) Nonce

func (ns *NonceService) Nonce(_ context.Context, _ *emptypb.Empty) (*noncepb.NonceMessage, error)

Nonce generates a nonce and sends it to a gRPC client.

func (*NonceService) Redeem

func (ns *NonceService) Redeem(ctx context.Context, msg *noncepb.NonceMessage) (*noncepb.ValidMessage, error)

Redeem accepts a nonce from a gRPC client and redeems it using the inner nonce service.

type PrefixCtxKey

type PrefixCtxKey struct{}

PrefixCtxKey is exported for use as a key in a context.Context.

type Redeemer

type Redeemer interface {
	Redeem(ctx context.Context, in *noncepb.NonceMessage, opts ...grpc.CallOption) (*noncepb.ValidMessage, error)
}

Redeemer is an interface for an RPC client that can redeem a nonce.

func NewRedeemer

func NewRedeemer(cc grpc.ClientConnInterface) Redeemer

NewRedeemer returns a new noncepb.NonceServiceClient which can only be used to redeem nonces.