sigv1

Documentation

Index

• Constants
• Variables
• func CreateSignatureHeader(keyPair *KeyPair, headers http.Header, customHeaderNames []string, ...) (string, error)
• func VerifySignature(keyPairs map[string]*KeyPair, headers http.Header, clock core.Clock, ...) error
• type Error
  • func (e *Error) Error() string
• type ErrorCode
• type KeyPair
• type SignatureParts
• type VerifyOptions

Constants

const (
	// SignatureHeaderName is the name of the HTTP header used for
	// Bluelink Signature v1.
	SignatureHeaderName = "Bluelink-Signature-V1"
	// DateHeaderName is the name of the HTTP header used to
	// store the date as a UNIX timestamp in seconds.
	DateHeaderName = "Bluelink-Date"
	// DefaultClockSkew is the default clock skew in seconds
	// used to determine if the request is within the
	// acceptable time window.
	DefaultClockSkew = 300
)

Variables

var (
	// ErrSignatureHeaderMissing is returned when the signature header
	// is not present in the request headers.
	ErrSignatureHeaderMissing = &Error{
		Code: ErrCodeSignatureHeaderMissing,
		Message: "signature verification failed due to the signature header " +
			"not being in the provided request headers",
	}

	// ErrInvalidSignatureHeaderFormat is returned when the signature
	// header is not in the correct format.
	ErrInvalidSignatureHeaderFormat = &Error{
		Code: ErrCodeInvalidSignatureHeaderFormat,
		Message: "signature verification failed due to the signature header " +
			"not being in the correct format, expected " +
			"'keyId=\"{keyId}\", headers=\"{header1} {header2} ...\", signature=\"{signature}\"'",
	}

	// ErrInvalidKeyID is returned when the key ID in the signature
	// header does not match any of the key IDs in the known key pairs.
	ErrInvalidKeyID = &Error{
		Code:    ErrCodeInvalidKeyID,
		Message: "signature verification failed due to an invalid key ID",
	}

	// ErrDateHeaderMissing is returned when the date header is not present
	// in the request headers.
	ErrDateHeaderMissing = &Error{
		Code: ErrCodeDateHeaderMissing,
		Message: "signature verification failed due to the date header " +
			"not being in the provided request headers",
	}

	// ErrInvalidDateHeader is returned when the date header is not
	// a valid unix timestamp that can be parsed as an integer.
	ErrInvalidDateHeader = &Error{
		Code: ErrCodeInvalidDateHeader,
		Message: "signature verification failed due to the date header " +
			"not being a valid unix timestamp",
	}

	// ErrFailedToDecodeSignature is returned when the signature
	// cannot be decoded a basee64 url safe string.
	ErrFailedToDecodeSignature = &Error{
		Code: ErrCodeFailedToDecodeSignature,
		Message: "signature verification failed due to the signature " +
			"being a valid url safe base64 string",
	}

	// ErrInvalidSignature is returned when signature
	// verification fails due to a mismatch between the
	// calculated signature and the signature in the header.
	ErrInvalidSignature = &Error{
		Code: ErrCodeInvalidSignature,
		Message: "signature verification failed due to the signature " +
			"not matching the expected signature",
	}

	// ErrSignatureExpired is returned when the date used in creating
	// the signature is outside of the allowed time window.
	ErrSignatureExpired = &Error{
		Code:    ErrCodeSignatureExpired,
		Message: "signature verification failed due to an expired signature",
	}
)

Functions

func CreateSignatureHeader

func CreateSignatureHeader(
	keyPair *KeyPair,
	headers http.Header,
	customHeaderNames []string,
	clock core.Clock,
) (string, error)

CreateSignatureHeader creates a signature header value to be attached to a request for [Bluelink Signature v1](https://bluelink.dev/docs/auth/signature-v1). This functions will return the value of the signature header that should be set in the `Bluelink-Signature-V1` header of the request.

The `Bluelink-Date` header does not need to be set in the provided headers, as it will be automatically added to the signature message using the provided clock and inserted into the provided headers map. The provided `http.Header` map will be modified to include the `Bluelink-Date` header with the current date in seconds since the epoch if it is not already present.

func VerifySignature

func VerifySignature(
	keyPairs map[string]*KeyPair,
	headers http.Header,
	clock core.Clock,
	options *VerifyOptions,
) error

VerifiySignature verifies a signature header with [Bluelink Signature v1](https://bluelink.dev/docs/auth/signature-v1). Returns nil if the signature is valid, or an error if the signature is invalid or cannot be verified.

If options is nil, the default options are used.

Types

type Error

type Error struct {
	Code    ErrorCode
	Message string
}

Error is a custom error type for verification and signing errors in the sigv1 package.

func (*Error) Error

func (e *Error) Error() string

type ErrorCode

type ErrorCode int

ErrorCode is an integer type that represents different error codes for the sigv1 package.

const (
	// ErrCodeSignatureHeaderMissing is for when the signature header
	// is not present in the request headers.
	ErrCodeSignatureHeaderMissing ErrorCode = iota
	// ErrCodeInvalidSignatureHeaderFormat is for when the signature
	// header is not in the correct format.
	ErrCodeInvalidSignatureHeaderFormat
	// ErrCodeInvalidKeyID is for when
	// the key ID in the signature header does not match any of
	// the key IDs in the known key pairs.
	ErrCodeInvalidKeyID
	// ErrCodeDateHeaderMissing is for when the date header is not
	// present in the request headers.
	ErrCodeDateHeaderMissing
	// ErrCodeInvalidDateHeader is for when the date header is not
	// a valid unix timestamp that can be parsed as an integer.
	ErrCodeInvalidDateHeader
	// ErrCodeCustomHeaderMissing is for when a custom header
	// included in the signature header string is not present
	// in the request headers.
	ErrCodeCustomHeaderMissing
	// ErrCodeFailedToDecodeSignature is for when the signature
	// cannot be decoded as a base64 url safe string.
	ErrCodeFailedToDecodeSignature
	// ErrCodeInvalidSignature is for when signature
	// verification fails due to a mismatch between the
	// calculated signature and the signature in the header.
	ErrCodeInvalidSignature
	// ErrCodeSignatureExpired is for when the date used in creating
	// the signature is outside of the allowed time window.
	ErrCodeSignatureExpired
)

type KeyPair

type KeyPair struct {
	// A public key ID used to identify the key pair.
	KeyID string
	// A secret key that is used to sign and verify messages.
	SecretKey string
}

Kepair for signing and verifying messages.

type SignatureParts

type SignatureParts struct {
	// The public key ID used to identify the key pair.
	KeyID string
	// The signature of the message.
	Signature string
	// The headers that were included in the signature.
	Headers []string
}

SignatureParts contains the components of a signature extracted from a header.

type VerifyOptions

type VerifyOptions struct {
	// The maximum clock skew in seconds.
	ClockSkew int
}

VerifyOptions contains options for verifying a Bluelink Signature v1 signature.