httpsig

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jan 9, 2024 License: BSD-3-Clause Imports: 20 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

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 06 of HTTP Message Signatures (draft-ietf-htttpbis-message-signatures-05 from 8 June 2021). Digest computation is based on version 05 of Digest Headers (draft-ietf-httpbis-digest-headers-05 from 13 April 2021).

Feature Notes
sign requests ✅
verify requests ✅
sign responses ❌
verify responses ❌
add expires to signature ❌ sorely needed
enforce expires in verify ✅
@method component ✅
@authority component ✅
@scheme component ❌
@target-uri component ❌
@request-target component ❌ Semantics changed in draft-06, no longer recommented for use.
@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 ✅
custom signature formats ❌ eddsa is not part of the spec, so custom support here would be nice!
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.
request digests ✅
response digests ❌ Tricky to support for signature use according to the spec
multiple digests ❌
digest: sha-256 ❌
digest: sha-512 ✅ ❌
digest: md5 ❌ Deprecated in the spec. Unlikely to be supported.
digest: sha ❌ Deprecated in the spec. Unlikely to be supported.
digest: unixsum ❌
digest: unixcksum ❌
digest: id-sha-512 ❌
digest: id-sha-256 ❌
custom digest formats ❌

Contributing

I 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.
  • Letting me know if you're using 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) 
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
Example (Round_trip_resolver) 
package main

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

	"github.com/offblocks/httpsig"
)

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

type testKeyResolver struct{}

func (r *testKeyResolver) Resolve(keyID string, alg httpsig.Algorithm) (httpsig.VerifyingKey, error) {
	return &httpsig.HmacSha256VerifyingKey{Secret: []byte(secret)}, nil
}

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.WithVerifyingKeyResolver(&testKeyResolver{}))
	http.Handle("/resolver", 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

This section is empty.

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 that map to their provided key ids.

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. However, only the first known key id is checked.

func WithHeaders 

func WithHeaders(hdr ...string) signOption

WithHeaders sets the list of headers that will be included in the signature. The Digest header is always included (and the digest calculated).

If not provided, the default headers `content-type, content-length, host` are used.

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 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 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 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 WithVerifyingKeyResolver 

func WithVerifyingKeyResolver(resolver VerifyingKeyResolver) verifyOption

Types

type Algorithm added in v0.3.0 

type Algorithm string
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 EcdsaP256SigningKey added in v0.3.0 

type EcdsaP256SigningKey struct {
	*ecdsa.PrivateKey
}

func (*EcdsaP256SigningKey) Algorithm added in v0.3.0 

func (k *EcdsaP256SigningKey) Algorithm() Algorithm

func (*EcdsaP256SigningKey) Nonce added in v0.3.0 

func (k *EcdsaP256SigningKey) Nonce() *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
}

func (*EcdsaP256VerifyingKey) Algorithm added in v0.3.0 

func (k *EcdsaP256VerifyingKey) Algorithm() Algorithm

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
}

func (*EcdsaP384SigningKey) Algorithm added in v0.3.0 

func (k *EcdsaP384SigningKey) Algorithm() Algorithm

func (*EcdsaP384SigningKey) Nonce added in v0.3.0 

func (k *EcdsaP384SigningKey) Nonce() *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
}

func (*EcdsaP384VerifyingKey) Algorithm added in v0.3.0 

func (k *EcdsaP384VerifyingKey) Algorithm() Algorithm

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
}

func (*Ed25519SigningKey) Algorithm added in v0.3.0 

func (k *Ed25519SigningKey) Algorithm() Algorithm

func (*Ed25519SigningKey) Nonce added in v0.3.0 

func (k *Ed25519SigningKey) Nonce() *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
}

func (*Ed25519VerifyingKey) Algorithm added in v0.3.0 

func (k *Ed25519VerifyingKey) Algorithm() Algorithm

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
}

func (*HmacSha256SigningKey) Algorithm added in v0.3.0 

func (k *HmacSha256SigningKey) Algorithm() Algorithm

func (*HmacSha256SigningKey) Nonce added in v0.3.0 

func (k *HmacSha256SigningKey) Nonce() *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
}

func (*HmacSha256VerifyingKey) Algorithm added in v0.3.0 

func (k *HmacSha256VerifyingKey) Algorithm() Algorithm

func (*HmacSha256VerifyingKey) Verify added in v0.3.0 

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

type RsaPkcs1v15Sha256SigningKey added in v0.3.0 

type RsaPkcs1v15Sha256SigningKey struct {
	*rsa.PrivateKey
}

func (*RsaPkcs1v15Sha256SigningKey) Algorithm added in v0.3.0 

func (k *RsaPkcs1v15Sha256SigningKey) Algorithm() Algorithm

func (*RsaPkcs1v15Sha256SigningKey) Nonce added in v0.3.0 

func (k *RsaPkcs1v15Sha256SigningKey) Nonce() *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
}

func (*RsaPkcs1v15Sha256VerifyingKey) Algorithm added in v0.3.0 

func (k *RsaPkcs1v15Sha256VerifyingKey) Algorithm() Algorithm

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
}

func (*RsaPssSha512SigningKey) Algorithm added in v0.3.0 

func (k *RsaPssSha512SigningKey) Algorithm() Algorithm

func (*RsaPssSha512SigningKey) Nonce added in v0.3.0 

func (k *RsaPssSha512SigningKey) Nonce() *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
}

func (*RsaPssSha512VerifyingKey) Algorithm added in v0.3.0 

func (k *RsaPssSha512VerifyingKey) Algorithm() Algorithm

func (*RsaPssSha512VerifyingKey) Verify added in v0.3.0 

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

type Signer 

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

func NewSigner 

func NewSigner(opts ...signOption) *Signer

func (*Signer) Sign 

func (s *Signer) Sign(r *http.Request) error

type SigningKey added in v0.3.0 

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

type Verifier 

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

func NewVerifier 

func NewVerifier(opts ...verifyOption) *Verifier

func (Verifier) ResolveKey 

func (v Verifier) ResolveKey(keyID string, alg Algorithm) (VerifyingKey, error)

func (*Verifier) Verify 

func (v *Verifier) Verify(r *http.Request) (keyID string, err error)

type VerifyingKey 

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

type VerifyingKeyResolver 

type VerifyingKeyResolver interface {
	Resolve(keyID string, alg Algorithm) (VerifyingKey, error)
}

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.