Documentation
¶
Overview ¶
Package signing implements Baseplate's message signing protocol.
Example ¶
package main
import (
"errors"
"time"
"github.com/fizx/baseplate.go/metricsbp"
"github.com/fizx/baseplate.go/secrets"
"github.com/fizx/baseplate.go/signing"
)
func main() {
// Should be properly initialized in production code.
var (
store *secrets.Store
secretPath string
)
secret, _ := store.GetVersionedSecret(secretPath)
const msg = "Hello, world!"
// Sign
signature, _ := signing.Sign(signing.SignArgs{
Message: []byte(msg),
Key: secret.Current,
ExpiresIn: time.Hour,
})
// Verify
err := signing.Verify([]byte(msg), signature, secret.GetAll()...)
if err != nil {
metricsbp.M.Counter("invalid-signature").Add(1)
var e signing.VerifyError
if errors.As(err, &e) {
switch e.Reason {
case signing.VerifyErrorReasonExpired:
metricsbp.M.Counter("signature-expired").Add(1)
}
}
}
}
Output:
Index ¶
Examples ¶
Constants ¶
const ( // The length of the raw, pre-base64-encoding message header. V1HeaderLength = 7 // The length of the raw, pre-base64-encoding signature. V1SignatureRawLength = V1HeaderLength + sha256.Size // The length of the base64 encoded signature. V1SignatureLength = V1SignatureRawLength / 3 * 4 )
Fixed lengths regarding v1 signatures.
Variables ¶
This section is empty.
Functions ¶
func Verify ¶
Verify auto chooses the correct version and verifies the signature with the version implementation.
Unrecognized versions will be rejected.
signature should be urlsafe base64 encoded signature, instead of the raw one.
keys should contain at least one non-empty secret. multiple keys will be tried in the order they are passed in.
If this function returns an error, it will be in the type of VerifyError.
Types ¶
type Interface ¶
type Interface interface {
// Sign a message. Returns urlsafe base64 encoded signature.
Sign(args SignArgs) (string, error)
// Verify a signature.
//
// signature should be urlsafe base64 encoded signature, instead of the raw
// one.
//
// keys should contain at least one non-empty secret.
// multiple keys will be tried in the order they are passed in.
//
// If this function returns an error, it will be in the type of VerifyError.
Verify(message []byte, signature string, keys ...secrets.Secret) error
}
The Interface of a concrete version of Baseplate message signing spec.
var V1 Interface = v1{}
V1 implementation.
type SignArgs ¶
type SignArgs struct {
// The message to sign. Required.
Message []byte
// The secret used to sign the message. Required.
Key secrets.Secret
// Signature expiring time.
//
// V1: If ExpiresAt is non-zero, it will be used.
// Otherwise time.Now().Add(ExpiresIn) will be used.
// Note that V1 only defined second precision,
// any sub-second precision in ExpiresIn or ExpiresAt will be dropped and
// rounded down.
ExpiresAt time.Time
ExpiresIn time.Duration
}
SignArgs are the args passed into Version.Sign function.
type VerifyError ¶
type VerifyError struct {
// The underlying error, could be nil.
Cause error
// The reason of the error.
Reason VerifyErrorReason
// The additional data to the error, could be empty.
Data interface{}
}
VerifyError is the error type returned by Version.Verify.
func (VerifyError) Error ¶
func (e VerifyError) Error() string
func (VerifyError) Unwrap ¶
func (e VerifyError) Unwrap() error
Unwrap returns the underlying error, if any.
type VerifyErrorReason ¶
type VerifyErrorReason int
VerifyErrorReason is an enum type for common reasons in VerifyError.
const ( // A catch-all reason not belong to any of the other reasons below. VerifyErrorReasonOther VerifyErrorReason = iota // The signature is in an unknown version. VerifyErrorReasonUnknownVersion // Base64 decoding of the signature failed. VerifyErrorReasonBase64 // The signature has expired. // Note that this does not necessarily mean the signature matches. VerifyErrorReasonExpired // The signature doesn't match. VerifyErrorReasonMismatch )
VerifyErrorReason values
Source Files