signer

README

Signer

Create signed URLs valid for a limited lifespan

Installation

go get github.com/leg100/signer@latest

Usage

package main

import (
	"fmt"
	"time"

	"github.com/leg100/signer"
)

func main() {
	sign := signer.New([]byte("secret_sesame"))

	// Create a signed URL that expires in one hour.
	signed, _ := sign.Sign("https://example.com/a/b/c?foo=bar", time.Hour)
	fmt.Println("signed url:", signed)
	// Outputs something like:
	// https://example.com/signed/pTn2am3eh8Ndz7ZTb6ya2gOMA5XtnFRd-1M__TNQr9o.1664441797/a/b/c?foo=bar

	err := sign.Verify(signed)
	if err != nil {
		fmt.Println("verification failed:", err.Error())
	}
	fmt.Println("verification succeeded")
}

Documentation

Index

• Variables
• type Formatter
• type Option
  • func SkipQuery() Option
• type Signer
  • func New(key []byte, opts ...Option) *Signer
  • func (s *Signer) Sign(u string, lifespan time.Duration) (string, error)
  • func (s *Signer) Verify(u string) error
• type URLPathFormatter
  • func (u *URLPathFormatter) AddExpiry(exp time.Time, data []byte) []byte
  • func (u *URLPathFormatter) AddSignature(sig, payload []byte) []byte
  • func (u *URLPathFormatter) ExtractExpiry(payload []byte) (time.Time, []byte, error)
  • func (u *URLPathFormatter) ExtractSignature(msg []byte) ([]byte, []byte, error)

Variables

var (
	// ErrInvalidSignature is returned when the provided token's
	// signatuire is not valid.
	ErrInvalidSignature = errors.New("invalid signature")
	// ErrInvalidMessageFormat is returned when the message's format is
	// invalid.
	ErrInvalidMessageFormat = errors.New("invalid message format")
	// ErrExpired is returned by when the signed URL's expiry has been
	// exceeded.
	ErrExpired = errors.New("URL has expired")
)

Types

type Formatter

type Formatter interface {
	// AddExpiry adds the expiry to the data, creating a payload for signing
	AddExpiry(exp time.Time, data []byte) []byte
	// AddSignature adds the signature to the payload, creating a signed message
	AddSignature(sig, payload []byte) []byte
	// ExtractSignature extracts the signature from the signed message,
	// returning the signature as well as the signed payload.
	ExtractSignature(msg []byte) ([]byte, []byte, error)
	// ExtractExpiry extracts the expiry from the signed payload, returning the
	// expiry as well as the original data.
	ExtractExpiry(payload []byte) (time.Time, []byte, error)
}

Formatter adds/extracts the signature and expiry to/from a URL according to a specific format

type Option

type Option func(*Signer)

Option permits customising the construction of a Signer

func SkipQuery

func SkipQuery() Option

SkipQuery instructs Signer to skip the query string when calculating the signature. This is useful, say, if you have pagination query parameters but you want to use the same signed URL regardless of their value.

type Signer

type Signer struct {
	Formatter
	// contains filtered or unexported fields
}

Signer is capable of signing and verifying signed URLs with an expiry.

func New

func New(key []byte, opts ...Option) *Signer

New constructs a new signer, performing the one-off task of generating a secure hash from the key. The key must be between 0 and 64 bytes long; anything longer is stripped off.

func (*Signer) Sign

func (s *Signer) Sign(u string, lifespan time.Duration) (string, error)

Sign generates a signed URL with the given lifespan.

func (*Signer) Verify

func (s *Signer) Verify(u string) error

Verify verifies a signed URL

type URLPathFormatter

type URLPathFormatter struct {
	// Prefix message with a string
	//
	// TODO: default to '/'?
	Prefix string
}

URLPathFormatter includes the signature and expiry in a message according to the format: <prefix><sig>.<exp>/<data>. Suitable for URL paths as an alternative to using query parameters.

func (*URLPathFormatter) AddExpiry

func (u *URLPathFormatter) AddExpiry(exp time.Time, data []byte) []byte

AddExpiry adds expiry as a base64 encoded component e.g. /foo/bar -> 390830893/foo/bar

func (*URLPathFormatter) AddSignature

func (u *URLPathFormatter) AddSignature(sig, payload []byte) []byte

AddSignature adds signature as a path component alongside the expiry e.g. abZ3G/foo/bar -> KKLJjd3090fklaJKLJK.abZ3G/foo/bar

func (*URLPathFormatter) ExtractExpiry

func (u *URLPathFormatter) ExtractExpiry(payload []byte) (time.Time, []byte, error)

ExtractExpiry decodes and splits the expiry and data from the payload.

func (*URLPathFormatter) ExtractSignature

func (u *URLPathFormatter) ExtractSignature(msg []byte) ([]byte, []byte, error)

ExtractSignature decodes and splits the signature and payload from the signed message.