auth

README

Auth

Package auth provides utility functions for authorization.

HMAC authorization (server to server)

HMAC

The following functions are available:

• HMACSign and HMACVerify functions for creating and verifying hex-encoded sha-512 HMAC signatures for a specified secret and a payload.

• SetHMACHeaders and GetHMACHeaders functions for setting and getting custom HTTP requests headers to be used for authorization.

• HTTPMiddleware function which creates an HTTP middleware for authorizing requests using the signatures and headers mentioned above.

💡 See hmac_test.go for examples on how to use these.

How to sign HTTP requests

ℹ This section is especially useful for services written in languages other than Go.

To sign an HTTP request (so that it passes the HMAC authorization checks) the following 4 headers need to be set on it:

• X-Auth-App-ID

  • This is the ID of the application sending the request. Needs to be configured also on the receiving server, together with it's corresponding shared secret.
  • Example value: Dispoman

• X-Auth-Nonce

  • This is some random value (e.g. a UUID or a number) that must be unique among all requests that the server application receives within a certain duration (e.g. for Abfallpass API server this duration is 2 minutes).

• X-Auth-Timestamp

  • The time at which the request is sent as number of seconds since UNIX epoch start time (i.e. since January 1st, 1970 at 00:00:00 UTC). It must not be older than a certain duration (the same duration that is used for checking the validity of the X-Auth-Nonce header mentioned above - e.g. for Abfallpass API server this duration is 2 minutes).

• X-Auth-Signature

  • This is the signature itself.
  • It's value needs to be computed like this (pseudocode): HEX( HMAC( SHA512, nonce+timestamp, shared-secret ) ).
    • Or, to put it in words, it must be the hexadecimal encoding of an SHA 512 HMAC hash of the concatenated nonce and timestamp (in this order - nonce immediately followed by the timestamp, without any other character between them) created using the shared secret.

Documentation

Index

• Constants
• func GetHMACHeaders(r *http.Request) (appID, nonce, timestamp, signature string)
• func HMACMiddleware(secretsPerAppIDs map[string][]byte, nonceCache HMACNonceCache, ...) func(next http.Handler) http.Handler
• func HMACSign(secret, payload []byte) string
• func HMACVerify(secret, payload []byte, signature string) error
• func SetHMACHeaders(r *http.Request, appID, nonce, timestamp, signature string)
• type HMACNonceCache

Constants

const (
	HMACHeaderAppID     = "X-Auth-App-ID"
	HMACHeaderSignature = "X-Auth-Signature"
	HMACHeaderNonce     = "X-Auth-Nonce"
	HMACHeaderTimestamp = "X-Auth-Timestamp"
)

Request headers required for HMAC authorization.

Functions

func GetHMACHeaders

func GetHMACHeaders(r *http.Request) (appID, nonce, timestamp, signature string)

GetHMACHeaders returns the HMAC auth headers from an HTTP request.

func HMACMiddleware

func HMACMiddleware(
	secretsPerAppIDs map[string][]byte,
	nonceCache HMACNonceCache,
	nonceExpiration time.Duration,
	requestLogger func(r *http.Request) *zap.Logger,
) func(next http.Handler) http.Handler

HMACMiddleware validates the signature header which is a HEX-encoded SHA512 HMAC of nonce, timestamp and secret. Signature timestamp is considered valid for nonceExpiration duration and nonce values must be unique within this timeframe.

func HMACSign

func HMACSign(secret, payload []byte) string

HMACSign creates a new hex-encoded SHA512 HMAC signature for the specified secret and payload.

func HMACVerify

func HMACVerify(secret, payload []byte, signature string) error

HMACVerify verifies the given hex-encoded SHA512 HMAC signature for the specified secret and payload.

func SetHMACHeaders

func SetHMACHeaders(r *http.Request, appID, nonce, timestamp, signature string)

SetHMACHeaders sets the specified HMAC auth headers on an HTTP request.

Types

type HMACNonceCache

type HMACNonceCache interface {
	Get(string) (interface{}, bool)
	Set(string, interface{}, time.Duration)
}

HMACNonceCache is an interface abstracting away the cache implementation for caching nonces used for HMAC authorization.