trust

Documentation

Index

• func HMACAuthorizationHeader(h HMACFormatter, v any) (string, error)
• func HMACEqual(h HMACFormatter, r *http.Request) error
• type HMAC
  • func (h *HMAC) HTTPHeader(hmac []byte) string
  • func (h *HMAC) ParseHTTPHeader(header string) (HMACFormatter, []byte, error)
  • func (h *HMAC) Version() HMACVersion
  • func (h *HMAC) WriteBytes(b []byte) ([]byte, error)
  • func (h *HMAC) WriteJSON(v any) ([]byte, error)
  • func (h *HMAC) WriteRequest(r *http.Request) ([]byte, error)
• type HMACArgon2
  • func (h *HMACArgon2) HTTPHeader(hmac []byte) string
  • func (h *HMACArgon2) ParseHTTPHeader(header string) (HMACFormatter, []byte, error)
• type HMACConf
  • func NewDefaultHMACConf(version HMACVersion) HMACConf
• type HMACFormatter
  • func NewHMAC(key []byte, conf HMACConf) HMACFormatter
  • func NewHMACArgon2(password []byte, salt []byte, conf HMACConf) (HMACFormatter, error)
• type HMACVersion

Functions

func HMACAuthorizationHeader

func HMACAuthorizationHeader(h HMACFormatter, v any) (string, error)

HMACAuthorizationHeader returns the HMAC as an Authorization header using the given formatter.

func HMACEqual

func HMACEqual(h HMACFormatter, r *http.Request) error

HMACEqual checks whether or not the Authorization header matches the HMAC derived using the given formatter. The formatter indicates the used format together with some basic HMAC configuration (e.g. key and version).

Types

type HMAC

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

HMAC represents the the tooling for creating and validating HMACs.

func (*HMAC) HTTPHeader

func (h *HMAC) HTTPHeader(hmac []byte) string

HTTPHeader returns the actual HMAC together with the used version.

func (*HMAC) ParseHTTPHeader

func (h *HMAC) ParseHTTPHeader(header string) (HMACFormatter, []byte, error)

ParseHTTPHeader parses the given header and returns a new instance of the default formatter together with the actual HMAC. It's using the parent formatter's configuration.

func (*HMAC) Version

func (h *HMAC) Version() HMACVersion

Version returns the used HMAC version.

func (*HMAC) WriteBytes

func (h *HMAC) WriteBytes(b []byte) ([]byte, error)

WriteBytes creates a new HMAC hash using the given bytes.

func (*HMAC) WriteJSON

func (h *HMAC) WriteJSON(v any) ([]byte, error)

WriteJSON creates a new HMAC hash using the given struct.

func (*HMAC) WriteRequest

func (h *HMAC) WriteRequest(r *http.Request) ([]byte, error)

WriteRequest creates a new HMAC hash using the given request. It will extract the requests body.

type HMACArgon2

type HMACArgon2 struct {
	HMAC
	// contains filtered or unexported fields
}

HMACArgon2 represents the tooling for creating and validating HMACs bundled with the key derivation function argon2.

func (*HMACArgon2) HTTPHeader

func (h *HMACArgon2) HTTPHeader(hmac []byte) string

HTTPHeader returns the actual HMAC alongside it's salt together with the used version.

func (*HMACArgon2) ParseHTTPHeader

func (h *HMACArgon2) ParseHTTPHeader(header string) (HMACFormatter, []byte, error)

ParseHTTPHeader parses the given header and returns a new instance of the argon2 formatter together with the actual HMAC. It's using the parent formatter's configuration.

type HMACConf

type HMACConf struct {
	HashFunc func() hash.Hash
	Version  HMACVersion
}

HMACConf represents the HMAC configuration.

func NewDefaultHMACConf

func NewDefaultHMACConf(version HMACVersion) HMACConf

NewDefaultHMACConf returns the default configuration for HMAC.

type HMACFormatter

type HMACFormatter interface {
	// The Write* methods allow the creation of an HMAC based on various inputs.
	WriteBytes(b []byte) ([]byte, error)
	WriteJSON(v any) ([]byte, error)
	WriteRequest(r *http.Request) ([]byte, error)

	// Version returns the current HMAC version set for the format.
	Version() HMACVersion
	// HTTPHeader expects the HMAC computed over the payload and returns the final Authorization header.
	HTTPHeader(hmac []byte) string
	// ParseHTTPHeader expects an Authorization header and returns a new instance of HMACFormatter
	// using the current implementation.
	// This allows parsing an Authorization header based on information which is already set
	// in the parent HMACFormatter like the HMACVersion.
	// Furthermore it returns the actual HMAC.
	ParseHTTPHeader(header string) (HMACFormatter, []byte, error)
}

HMACFormatter represents arbitrary formats to diplay and parse the actual HMAC. For example implementations like argon2 extend the format with an additional salt. Example using argon2: `Authorization: <version> <salt>:<HMAC>`.

func NewHMAC

func NewHMAC(key []byte, conf HMACConf) HMACFormatter

NewHMAC returns a new instance of HMAC.

func NewHMACArgon2

func NewHMACArgon2(password []byte, salt []byte, conf HMACConf) (HMACFormatter, error)

NewHMACArgon2 returns a new HMAC implementation using argon2. If the salt is nil a random one gets generated. Use ParseHTTPHeader to derive a new implementation of argon2 from a request header. It's using the parents configuration such as the password and config. Recommended defaults according to https://www.rfc-editor.org/rfc/rfc9106#section-4-6.2. We use the second recommended option to not require a system having 2 GiB of memory.

type HMACVersion

type HMACVersion string

HMACVersion indicates the version used for the authorization header format. This allows to define a format used by the header so that the scheme can be modified in future implementations without breaking already existing versions. An example version can be `LXD1.0` which indicates that this is version 1.0 of the LXD HMAC authentication scheme. The format used after the version is dependant on the actual implementation: Example: `Authorization: <version> <format including the HMAC>`.