sri

README

Subresource Integrity computation and verification

This module provides hash.Hash implementation that can be used to compute and verify subresource integrity digests. See https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity for an application of this.

Generating SRI hashes

package main

import (
	"os"

	"github.com/nguyengg/xy3/sri"
)

func main() {
	// create a new SHA-256 hash function.
	h := sri.NewSha256()

	// h implements hash.Hash which implements io.Writer so just pipes an entire file to it.
	f, _ := os.Open("path/to/file")
	_, _ = f.WriteTo(h)
	_ = f.Close()

	// SumToString will produce a digest in format sha256-aOZWslHmfoNYvvhIOrDVHGYZ8+ehqfDnWDjUH/No9yg for example.
	h.SumToString(nil)
}

Verifying SRI hashes

package main

import (
	"log"
	"os"
	"strings"

	"github.com/nguyengg/xy3/sri"
)

func main() {
	// per https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity#using_subresource_integrity,
	// an integrity value may contain multiple hashes separated by whitespace.
	//
	// NewVerifier accepts a number of hashes that the returned hash.Hash can verify against.
	//
	// unknown is a string slice containing hashes with unknown hash function. This module only supports SHA hash
	// functions out of the boxes; use Register to register more.
	h, unknown := sri.NewVerifier(
		"sha256-aOZWslHmfoNYvvhIOrDVHGYZ8+ehqfDnWDjUH/No9yg",
		"sha384-b58jhCXsokOe1Fgawf20X8djeef7qUvAp2JPo+erHsNwG0v83aN2ynVRkub0XypO",
		"sha512-bCYYNY2gfIMLiMWvjDU1CA6OYDyIuJECiiWczbmsgC0PwBcMmdWK/88AeGzhiPxddT6MZiivIHHDJw1QRFxLHA")
	if len(unknown) > 0 {
		log.Printf("unknown hash functions: %s", strings.Join(unknown, " "))
	}

	// h, once again, implements hash.Hash which implements io.Writer so just pipes an entire file to it.
	f, _ := os.Open("path/to/file")
	_, _ = f.WriteTo(h)
	_ = f.Close()

	// SumAndVerify will return true if and only if the resulting hash matches against one of the hashes given by
	// NewVerifier.
	if matches := h.SumAndVerify(nil); matches {
		// integrity matches! the file should be accepted.
	}
}

Documentation

Index

• func Register(name string, hashNewFn func() hash.Hash)
• type DigestVerifier
  • func NewVerifier(primary string, additional ...string) (DigestVerifier, []string)
• type Hash
  • func NewSha1() Hash
  • func NewSha224() Hash
  • func NewSha256() Hash
  • func NewSha384() Hash
  • func NewSha512() Hash

Functions

func Register

func Register(name string, hashNewFn func() hash.Hash)

Register can be used to register additional hash functions not supported out of the box.

Types

type DigestVerifier

type DigestVerifier interface {
	Hash

	// SumAndVerify calls [hash.Hash.Sum] passing b and matches the resulting slice against the original set of
	// candidates.
	//
	// SumAndVerify returns true if and only if the hash matches at least one match candidate.
	SumAndVerify(b []byte) bool
}

DigestVerifier extends Hash with SumAndVerify to verify the hash against a set of precomputed digests.

Using Subresource Integrity allow for multiple digests to be given as match candidates. As a result, NewVerifier supports being given several precomputed digests to match against. If the precomputed digests use different hash functions, the function of the first digest will be the one that is used as the primary Hash function.

func NewVerifier

func NewVerifier(primary string, additional ...string) (DigestVerifier, []string)

NewVerifier returns a new DigestVerifier that will match against the given set of digest candidates.

The hash function of the first (primary) digest will be used as the primary hash function. Digests with unknown hash function are returned as the second value. If all digests are unrecognised, a nil DigestVerifier is returned. Call Register if you are expecting custom hash functions.

type Hash

type Hash interface {
	hash.Hash

	// Name returns the name of the hash function.
	Name() string

	// SumToString calls [hash.Hash.Sum] passing b and encodes the returned slice as a string prefixed with the hash
	// name.
	//
	// See [Subresource Integrity] for example usages of such strings in <script> and <link> tags such as
	//  <script
	//   src="https://example.com/example-framework.js"
	//   integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
	//   crossorigin="anonymous"></script>
	//
	// [Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
	SumToString(b []byte) string
}

Hash extends hash.Hash with SumToString to generate the base64-encoded cryptographic hash that can be used to verify Subresource Integrity.

func NewSha1

func NewSha1() Hash

NewSha1 returns a new Hash using sha1 as the hash function.

func NewSha224

func NewSha224() Hash

NewSha224 returns a new Hash using sha224 as the hash function.

func NewSha256

func NewSha256() Hash

NewSha256 returns a new Hash using sha256 as the hash function.

func NewSha384

func NewSha384() Hash

NewSha384 returns a new Hash using sha384 as the hash function.

func NewSha512

func NewSha512() Hash

NewSha512 returns a new Hash using sha512 as the hash function.