httpsig

package module
v0.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 17, 2024 License: BSD-3-Clause Imports: 23 Imported by: 0

README

httpsig

Standards-based HTTP request signing and verification for Go

Go Reference Alpha Quality Build Status BSD license codecov Go Report Card


Introduction

httpsig provides support for signing and verifying HTTP requests according to the HTTP Message Signatures draft standard. This standard focuses on signing headers and request paths, and you probably want to sign the request body too, so body digest calculation according to Digest Headers is included.

Signed HTTP requests are ideal for scenarios like sending webhooks, allowing recievers to securely verify the request came from your server, mitigate replay attacks, etc.

Contrary to the commonly-used x-hub-signature, The standards implemented by this package provide a signature of the entire request, including HTTP headers and the request path.

Usage

Standalone Signing and Verification

To sign a request, first instantiate a Signer using your preferred key and signing algorithm:

// Create a signer
signer := httpsig.NewSigner(httpsig.WithSignEcdsaP256Sha256("key1", privKey))

// Create a request
req, _ := http.NewRequest("GET", "https://some-url.com", nil)

// Sign the request
header, _ := signer.Sign(httpsig.MessageFromRequest(req))

// Add the signature to the request
req.Header = header

To verify a response, instantiate a Verifier using your preferred key and signing algorithm:

// Receive a response from server
resp, _ := client.Post("https://some-url.com", "application/json", &buf)

// Create a verifier
verifier := httpsig.NewVerifier(httpsig.WithVerifyEcdsaP256Sha256("key1", pubKey))

// Verify the response
err := verifier.Verify(httpsig.MessageFromResponse(resp))

Signing HTTP Requests in Clients

To sign HTTP requests from a client, wrap an http.Client's transport with NewSignTransport:

client := http.Client{
	// Wrap the transport:
	Transport: httpsig.NewSignTransport(http.DefaultTransport,
		httpsig.WithSignEcdsaP256Sha256("key1", privKey)),
}

var buf bytes.Buffer

// construct body, etc
// ...

resp, err := client.Post("https://some-url.com", "application/json", &buf)
if err != nil {
	return
}
defer resp.Body.Close()

// ...

Verifying HTTP Requests in Servers

To verify HTTP requests on the server, wrap the http.Handlers you wish to protect with NewVerifyMiddleware. NewVerifyMiddleware returns the wrapping func, so you can reuse configuration across multiple handlers.

h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/plain")
	io.WriteString(w, "Your request has an valid signature!")
})

middleware := httpsig.NewVerifyMiddleware(httpsig.WithVerifyEcdsaP256Sha256("key1", pubkey))
http.Handle("/", middleware(h))

For more usage examples and documentation, see the godoc refernce

The Big Feature Matrix

This implementation is based on version 19 of HTTP Message Signatures (draft-ietf-htttpbis-message-signatures-19 from 26 July 2023). Digest computation is based on version 13 of Digest Headers (draft-ietf-httpbis-digest-headers-13 from 10 July 2023).

Feature Notes
sign requests ✅
verify requests ✅
sign responses ✅
verify responses ✅
add expires to signature ✅
enforce expires in verify ✅
@method component ✅
@authority component ✅
@scheme component ✅
@target-uri component ✅
@path component ✅
@query component ✅ Encoding handling is missing.
@query-params component ✅
@status component ✅
request-response binding ✅
Accept-Signature header ❌
create multiple signatures ✅
verify from multiple signatures ✅
rsa-pss-sha512 ✅
rsa-v1_5-sha256 ✅
hmac-sha256 ✅
ecdsa-p256-sha256 ✅
ecdsa-p384-sha384 ✅
ed25519 ✅
JSON Web Signatures ❌ JWS doesn't support any additional algs, but it is part of the spec
Signature-Input as trailer ❌ Trailers can be dropped. accept for verification only.
Signature as trailer ❌ Trailers can be dropped. accept for verification only.
multiple digests ✅
digest: sha-256 ✅
digest: sha-512 ✅

Contributing

We would love your help!

httpsig is still a work in progress. You can help by:

  • Opening a pull request to resolve an open issue.
  • Adding a feature or enhancement of your own! If it might be big, please open an issue first so we can discuss it.
  • Improving this README or adding other documentation to httpsig.

Documentation

Overview

Package httpsig signs and verifies HTTP requests (with body digests) according to the "HTTP Message Signatures" draft standard https://datatracker.ietf.org/doc/draft-ietf-httpbis-message-signatures/

Example (Round_trip) 
// BSD 3-Clause License

// Copyright (c) 2021, James Bowes
// Copyright (c) 2023, Alexander Taraymovich, OffBlocks
// All rights reserved.

// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are met:

// 1. Redistributions of source code must retain the above copyright notice, this
//    list of conditions and the following disclaimer.

// 2. Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.

// 3. Neither the name of the copyright holder nor the names of its
//    contributors may be used to endorse or promote products derived from
//    this software without specific prior written permission.

// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
// OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package main

import (
	"fmt"
	"io"
	"net/http"
	"time"

	"github.com/offblocks/httpsig"
)

const secret = "support-your-local-cat-bonnet-store"

func main() {
	h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/plain")
		_, _ = io.WriteString(w, "Your request has a valid signature!")
	})

	middleware := httpsig.NewVerifyMiddleware(httpsig.WithHmacSha256("key1", []byte(secret)))
	http.Handle("/", middleware(h))
	go func() { _ = http.ListenAndServe("127.0.0.1:1234", http.DefaultServeMux) }()

	// Give the server time to sleep. Terrible, I know.
	time.Sleep(100 * time.Millisecond)

	client := http.Client{
		// Wrap the transport:
		Transport: httpsig.NewSignTransport(http.DefaultTransport,
			httpsig.WithHmacSha256("key1", []byte(secret))),
	}

	resp, err := client.Get("http://127.0.0.1:1234/")
	if err != nil {
		fmt.Println("got err: ", err)
		return
	}
	defer resp.Body.Close()

	fmt.Println(resp.Status)

}

Output:

200 OK

Index

Examples

Constants

View Source 
const (
	SignatureHeader      = "Signature"
	SignatureInputHeader = "Signature-Input"
	ContentDigestHeader  = "Content-Digest"
)

Variables

This section is empty.

Functions

func NewSignTransport 

func NewSignTransport(transport http.RoundTripper, opts ...signOption) http.RoundTripper

NewSignTransport returns a new client transport that wraps the provided transport with http message signing and body digest creation.

Use the various `WithSign*` option funcs to configure signature algorithms with their provided key ids. You must provide at least one signing option. A signature for every provided key id is included on each request. Multiple included signatures allow you to gracefully introduce stronger algorithms, rotate keys, etc.

func NewVerifyMiddleware 

func NewVerifyMiddleware(opts ...verifyOption) func(http.Handler) http.Handler

NewVerifyMiddleware returns a configured http server middleware that can be used to wrap multiple handlers for http message signature and digest verification.

Use the `WithVerify*` option funcs to configure signature verification algorithms and verification parameters.

Requests with missing signatures, malformed signature headers, expired signatures, or invalid signatures are rejected with a `400` response. Only one valid signature is required from the known key ids by default.

func WithDigestAlgorithms added in v0.4.0 

func WithDigestAlgorithms(algorithms ...DigestAlgorithm) digestOption

WithDigestAlgorithms sets the digest algorithms to use for signing or signature verification. default: sha-256

func WithHmacSha256 

func WithHmacSha256(keyID string, secret []byte) signOrVerifyOption

WithHmacSha256 adds signing or signature verification using `hmac-sha256` with the given shared secret using the given key id.

func WithSignEcdsaP256Sha256 

func WithSignEcdsaP256Sha256(keyID string, pk *ecdsa.PrivateKey) signOption

WithSignEcdsaP256Sha256 adds signing using `ecdsa-p256-sha256` with the given private key using the given key id.

func WithSignEcdsaP384Sha384 

func WithSignEcdsaP384Sha384(keyID string, pk *ecdsa.PrivateKey) signOption

WithSignEcdsaP384Sha384 adds signing using `ecdsa-p384-sha384` with the given private key using the given key id.

func WithSignEd25519 

func WithSignEd25519(keyID string, pk ed25519.PrivateKey) signOption

WithSignEd25519 adds signing using `ed25519` with the given private key using the given key id.

func WithSignFields added in v0.4.0 

func WithSignFields(fields ...string) signOption

WithSignFields sets the HTTP fields / derived component names to be included in signing. default: none

func WithSignName added in v0.4.0 

func WithSignName(name string) signOption

WithSignName sets the name of the signature to be used for signing. default: "sig"

func WithSignParamValues added in v0.4.0 

func WithSignParamValues(params *SignatureParameters) signOption

WithSignParamValues sets the signature parameters to be included in signing.

func WithSignParams added in v0.4.0 

func WithSignParams(params ...Param) signOption

WithSignParams sets the signature parameters to be included in signing. default: created, keyid, alg

func WithSignRsaPkcs1v15Sha256 

func WithSignRsaPkcs1v15Sha256(keyID string, pk *rsa.PrivateKey) signOption

WithSignRsaPkcs1v15Sha256 adds signing using `rsa-v1_5-sha256` with the given private key using the given key id.

func WithSignRsaPssSha512 

func WithSignRsaPssSha512(keyID string, pk *rsa.PrivateKey) signOption

WithSignRsaPssSha512 adds signing using `rsa-pss-sha512` with the given private key using the given key id.

func WithVerifyAll added in v0.4.0 

func WithVerifyAll(all bool) verifyOption

WithVerifyAll sets whether all signatures must be valid. default: false

func WithVerifyEcdsaP256Sha256 

func WithVerifyEcdsaP256Sha256(keyID string, pk *ecdsa.PublicKey) verifyOption

WithVerifyEcdsaP256Sha256 adds signature verification using `ecdsa-p256-sha256` with the given public key using the given key id.

func WithVerifyEcdsaP384Sha384 

func WithVerifyEcdsaP384Sha384(keyID string, pk *ecdsa.PublicKey) verifyOption

WithVerifyEcdsaP384Sha384 adds signature verification using `ecdsa-p384-sha384` with the given public key using the given key id.

func WithVerifyEd25519 

func WithVerifyEd25519(keyID string, pk ed25519.PublicKey) verifyOption

WithVerifyEd25519 adds signature verification using `ed25519` with the given public key using the given key id.

func WithVerifyMaxAge added in v0.4.0 

func WithVerifyMaxAge(d time.Duration) verifyOption

WithVerifyMaxAge sets the maximum age of a signature. default: 0

func WithVerifyNotAfter added in v0.4.0 

func WithVerifyNotAfter(t time.Time) verifyOption

WithVerifyNotAfter sets the time after which signatures are considered expired. default: time.Now() + 5 mins

func WithVerifyRequiredFields added in v0.4.0 

func WithVerifyRequiredFields(fields ...string) verifyOption

WithVerifyRequiredFields sets the required HTTP fields / derived component names. default: []

func WithVerifyRequiredParams added in v0.4.0 

func WithVerifyRequiredParams(params ...string) verifyOption

WithVerifyRequiredParams sets the required signature parameters. default: []

func WithVerifyRsaPkcs1v15Sha256 

func WithVerifyRsaPkcs1v15Sha256(keyID string, pk *rsa.PublicKey) verifyOption

WithVerifyRsaPkcs1v15Sha256 adds signature verification using `rsa-v1_5-sha256` with the given public key using the given key id.

func WithVerifyRsaPssSha512 

func WithVerifyRsaPssSha512(keyID string, pk *rsa.PublicKey) verifyOption

WithVerifyRsaPssSha512 adds signature verification using `rsa-pss-sha512` with the given public key using the given key id.

func WithVerifyTolerance added in v0.4.0 

func WithVerifyTolerance(d time.Duration) verifyOption

WithVerifyTolerance sets the clock tolerance for verifying created and expires times. default: 0

func WithVerifyingKeyResolver 

func WithVerifyingKeyResolver(resolver VerifyingKeyResolver) verifyOption

WithVerifyingKeyResolver sets the resolver to use for verifying keys.

Types

type Algorithm added in v0.3.0 

type Algorithm string

Algorithm is the signature algorithm to use. Available algorithms are: - RSASSA-PKCS1-v1_5 using SHA-256 (rsa-v1_5-sha256) - RSASSA-PSS using SHA-512 (rsa-pss-sha512) - ECDSA using curve P-256 DSS and SHA-256 (ecdsa-p256-sha256) - ECDSA using curve P-384 DSS and SHA-384 (ecdsa-p384-sha384) - EdDSA using curve edwards25519 (ed25519) - HMAC using SHA-256 (hmac-sha256) 

const (
	AlgorithmRsaPkcs1v15Sha256 Algorithm = "rsa-v1_5-sha256"
	AlgorithmRsaPssSha512      Algorithm = "rsa-pss-sha512"
	AlgorithmEcdsaP256Sha256   Algorithm = "ecdsa-p256-sha256"
	AlgorithmEcdsaP384Sha384   Algorithm = "ecdsa-p384-sha384"
	AlgorithmEd25519           Algorithm = "ed25519"
	AlgorithmHmacSha256        Algorithm = "hmac-sha256"
)

type DigestAlgorithm added in v0.4.0 

type DigestAlgorithm string

DigestAlgorithm is the digest algorithm to use. Available algorithms are: - SHA-256 (sha-256) - SHA-512 (sha-512) 

const (
	DigestAlgorithmSha256 DigestAlgorithm = "sha-256"
	DigestAlgorithmSha512 DigestAlgorithm = "sha-512"
)

type DigestConfig added in v0.4.0 

type DigestConfig struct {
	// List of digest algorithms to use when creating a digest header.
	// default: sha-256
	Algorithms []DigestAlgorithm
}

type Digestor added in v0.4.0 

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

func NewDigestor added in v0.4.0 

func NewDigestor(opts ...digestOption) *Digestor

NewDigestor creates a new digestor with the given options

func (*Digestor) Digest added in v0.4.0 

func (d *Digestor) Digest(body []byte) (http.Header, error)

Digest creates a digest header for the given body

func (Digestor) Verify added in v0.7.0 

func (d Digestor) Verify(body []byte, header http.Header) error

type EcdsaP256SigningKey added in v0.3.0 

type EcdsaP256SigningKey struct {
	*ecdsa.PrivateKey
	KeyID string
}

func (*EcdsaP256SigningKey) GetAlgorithm added in v0.4.0 

func (k *EcdsaP256SigningKey) GetAlgorithm() Algorithm

func (*EcdsaP256SigningKey) GetKeyID added in v0.4.0 

func (k *EcdsaP256SigningKey) GetKeyID() string

func (*EcdsaP256SigningKey) Sign added in v0.3.0 

func (k *EcdsaP256SigningKey) Sign(data []byte) ([]byte, error)

type EcdsaP256VerifyingKey added in v0.3.0 

type EcdsaP256VerifyingKey struct {
	*ecdsa.PublicKey
	KeyID string
}

func (*EcdsaP256VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *EcdsaP256VerifyingKey) GetAlgorithm() Algorithm

func (*EcdsaP256VerifyingKey) GetKeyID added in v0.4.0 

func (k *EcdsaP256VerifyingKey) GetKeyID() string

func (*EcdsaP256VerifyingKey) Verify added in v0.3.0 

func (k *EcdsaP256VerifyingKey) Verify(data []byte, signature []byte) error

type EcdsaP384SigningKey added in v0.3.0 

type EcdsaP384SigningKey struct {
	*ecdsa.PrivateKey
	KeyID string
}

func (*EcdsaP384SigningKey) GetAlgorithm added in v0.4.0 

func (k *EcdsaP384SigningKey) GetAlgorithm() Algorithm

func (*EcdsaP384SigningKey) GetKeyID added in v0.4.0 

func (k *EcdsaP384SigningKey) GetKeyID() string

func (*EcdsaP384SigningKey) Sign added in v0.3.0 

func (k *EcdsaP384SigningKey) Sign(data []byte) ([]byte, error)

type EcdsaP384VerifyingKey added in v0.3.0 

type EcdsaP384VerifyingKey struct {
	*ecdsa.PublicKey
	KeyID string
}

func (*EcdsaP384VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *EcdsaP384VerifyingKey) GetAlgorithm() Algorithm

func (*EcdsaP384VerifyingKey) GetKeyID added in v0.4.0 

func (k *EcdsaP384VerifyingKey) GetKeyID() string

func (*EcdsaP384VerifyingKey) Verify added in v0.3.0 

func (k *EcdsaP384VerifyingKey) Verify(data []byte, signature []byte) error

type Ed25519SigningKey added in v0.3.0 

type Ed25519SigningKey struct {
	ed25519.PrivateKey
	KeyID string
}

func (*Ed25519SigningKey) GetAlgorithm added in v0.4.0 

func (k *Ed25519SigningKey) GetAlgorithm() Algorithm

func (*Ed25519SigningKey) GetKeyID added in v0.4.0 

func (k *Ed25519SigningKey) GetKeyID() string

func (*Ed25519SigningKey) Sign added in v0.3.0 

func (k *Ed25519SigningKey) Sign(data []byte) ([]byte, error)

type Ed25519VerifyingKey added in v0.3.0 

type Ed25519VerifyingKey struct {
	ed25519.PublicKey
	KeyID string
}

func (*Ed25519VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *Ed25519VerifyingKey) GetAlgorithm() Algorithm

func (*Ed25519VerifyingKey) GetKeyID added in v0.4.0 

func (k *Ed25519VerifyingKey) GetKeyID() string

func (*Ed25519VerifyingKey) Verify added in v0.3.0 

func (k *Ed25519VerifyingKey) Verify(data []byte, signature []byte) error

type HmacSha256SigningKey added in v0.3.0 

type HmacSha256SigningKey struct {
	Secret []byte
	KeyID  string
}

func (*HmacSha256SigningKey) GetAlgorithm added in v0.4.0 

func (k *HmacSha256SigningKey) GetAlgorithm() Algorithm

func (*HmacSha256SigningKey) GetKeyID added in v0.4.0 

func (k *HmacSha256SigningKey) GetKeyID() string

func (*HmacSha256SigningKey) Sign added in v0.3.0 

func (k *HmacSha256SigningKey) Sign(data []byte) ([]byte, error)

type HmacSha256VerifyingKey added in v0.3.0 

type HmacSha256VerifyingKey struct {
	Secret []byte
	KeyID  string
}

func (*HmacSha256VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *HmacSha256VerifyingKey) GetAlgorithm() Algorithm

func (*HmacSha256VerifyingKey) GetKeyID added in v0.4.0 

func (k *HmacSha256VerifyingKey) GetKeyID() string

func (*HmacSha256VerifyingKey) Verify added in v0.3.0 

func (k *HmacSha256VerifyingKey) Verify(data []byte, signature []byte) error

type Message added in v0.4.0 

type Message struct {
	Method        string
	Authority     string
	URL           *url.URL
	Header        http.Header
	StatusCode    int
	RequestHeader *http.Header
	IsRequest     bool
	Context       context.Context
}

message is a minimal representation of an HTTP request or response, containing the values needed to construct a signature.

func MessageFromRequest added in v0.4.0 

func MessageFromRequest(r *http.Request) *Message

func MessageFromResponse added in v0.4.0 

func MessageFromResponse(r *http.Response) *Message

type Param added in v0.4.0 

type Param string
const (
	ParamKeyID   Param = "keyid"
	ParamAlg     Param = "alg"
	ParamCreated Param = "created"
	ParamExpires Param = "expires"
	ParamNonce   Param = "nonce"
	ParamTag     Param = "tag"
)

type RsaPkcs1v15Sha256SigningKey added in v0.3.0 

type RsaPkcs1v15Sha256SigningKey struct {
	*rsa.PrivateKey
	KeyID string
}

func (*RsaPkcs1v15Sha256SigningKey) GetAlgorithm added in v0.4.0 

func (k *RsaPkcs1v15Sha256SigningKey) GetAlgorithm() Algorithm

func (*RsaPkcs1v15Sha256SigningKey) GetKeyID added in v0.4.0 

func (k *RsaPkcs1v15Sha256SigningKey) GetKeyID() string

func (*RsaPkcs1v15Sha256SigningKey) Sign added in v0.3.0 

func (k *RsaPkcs1v15Sha256SigningKey) Sign(data []byte) ([]byte, error)

type RsaPkcs1v15Sha256VerifyingKey added in v0.3.0 

type RsaPkcs1v15Sha256VerifyingKey struct {
	*rsa.PublicKey
	KeyID string
}

func (*RsaPkcs1v15Sha256VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *RsaPkcs1v15Sha256VerifyingKey) GetAlgorithm() Algorithm

func (*RsaPkcs1v15Sha256VerifyingKey) GetKeyID added in v0.4.0 

func (k *RsaPkcs1v15Sha256VerifyingKey) GetKeyID() string

func (*RsaPkcs1v15Sha256VerifyingKey) Verify added in v0.3.0 

func (k *RsaPkcs1v15Sha256VerifyingKey) Verify(data []byte, signature []byte) error

type RsaPssSha512SigningKey added in v0.3.0 

type RsaPssSha512SigningKey struct {
	*rsa.PrivateKey
	KeyID string
}

func (*RsaPssSha512SigningKey) GetAlgorithm added in v0.4.0 

func (k *RsaPssSha512SigningKey) GetAlgorithm() Algorithm

func (*RsaPssSha512SigningKey) GetKeyID added in v0.4.0 

func (k *RsaPssSha512SigningKey) GetKeyID() string

func (*RsaPssSha512SigningKey) Sign added in v0.3.0 

func (k *RsaPssSha512SigningKey) Sign(data []byte) ([]byte, error)

type RsaPssSha512VerifyingKey added in v0.3.0 

type RsaPssSha512VerifyingKey struct {
	*rsa.PublicKey
	KeyID string
}

func (*RsaPssSha512VerifyingKey) GetAlgorithm added in v0.4.0 

func (k *RsaPssSha512VerifyingKey) GetAlgorithm() Algorithm

func (*RsaPssSha512VerifyingKey) GetKeyID added in v0.4.0 

func (k *RsaPssSha512VerifyingKey) GetKeyID() string

func (*RsaPssSha512VerifyingKey) Verify added in v0.3.0 

func (k *RsaPssSha512VerifyingKey) Verify(data []byte, signature []byte) error

type SignConfig added in v0.4.0 

type SignConfig struct {
	// The key to use for signing
	Key SigningKey

	// The name to try to use for the signature
	// Default: 'sig'
	Name *string

	// The parameters to add to the signature
	// Default: see defaultParams
	Params []Param

	// The HTTP fields / derived component names to sign
	// Default: none
	Fields []string

	// Specified parameter values to use (eg: created time, expires time, etc)
	// This can be used by consumers to override the default expiration time or explicitly opt-out
	// of adding creation time (by setting `created: nil`)
	ParamValues *SignatureParameters
}

SignConfig is the configuration for a signer

type SignatureParameters added in v0.4.0 

type SignatureParameters struct {
	// The created time for the signature. `nil` indicates not to populate the `created` time
	// default: time.Now()
	Created *time.Time

	// The time the signature should be deemed to have expired
	// default: time.Now() + 5 mins
	Expires *time.Time

	// A nonce for the request
	Nonce *string

	// The algorithm the signature is signed with (overrides the alg provided by the signing key)
	Alg *Algorithm

	// The key id the signature is signed with (overrides the keyid provided by the signing key)
	KeyID *string

	// A tag parameter for the signature
	Tag *string
}

The signature parameters to include in signing

type Signer 

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

func NewSigner 

func NewSigner(opts ...signOption) *Signer

NewSigner creates a new signer with the given options

Use the `WithSign*` option funcs to configure signing algorithms and parameters.

func (*Signer) Sign 

func (s *Signer) Sign(m *Message) (http.Header, error)

Sign signs the given message and returns updated request headers

type SigningKey added in v0.3.0 

type SigningKey interface {
	Sign(data []byte) ([]byte, error)
	GetKeyID() string
	GetAlgorithm() Algorithm
}

The key to use for signing

type Verifier 

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

func NewVerifier 

func NewVerifier(opts ...verifyOption) *Verifier

NewVerifier creates a new verifier with the given options

Use the `WithVerify*` option funcs to configure signature verification algorithms and verification parameters.

func (*Verifier) Verify 

func (v *Verifier) Verify(m *Message) error

Verify verifies the given message

type VerifyConfig added in v0.4.0 

type VerifyConfig struct {
	// The keys to use for signing
	Keys map[string]VerifyingKey

	// Resolver for verifying keys
	KeyResolver VerifyingKeyResolver

	// A date that the signature can't have been marked as `created` after
	// Default: time.Now() + tolerance
	NotAfter *time.Time

	// The maximum age of the signature - this effectively overrides the `expires` value for the
	// signature (unless the expires age is less than the maxAge specified) if provided
	MaxAge *time.Duration

	// A clock tolerance when verifying created/expires times
	// Default: 0
	Tolerance *time.Duration

	// Any parameters that *must* be in the signature (eg: require a created time)
	// Default: []
	RequiredParams []string

	// Any fields that *must* be in the signature (eg: Authorization, Digest, etc)
	// Default: []
	RequiredFields []string

	// Verify every signature in the request. By default, only 1 signature will need to be valid
	// for the verification to pass.
	// Default: false
	All bool
}

VerifyConfig is the configuration for a verifier

type VerifyingKey 

type VerifyingKey interface {
	Verify(data []byte, signature []byte) error
	GetKeyID() string
	GetAlgorithm() Algorithm
}

VerifyingKey is the key to use for verifying a signature

type VerifyingKeyResolver 

type VerifyingKeyResolver interface {
	Resolve(ctx context.Context, keyID string) (VerifyingKey, error)
}

VerifyingKeyResolver is used to resolve a key id to a verifying key

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.