contentsignature

Documentation

Overview

Package contentsignature provides a type, marshal/unmarshaller, and verifier for the Firefox content signing scheme.

It is intended for use in autograph tools and services without including the rest of autograph and its dependencies.

Prefer [the NSS verifier](https://searchfox.org/mozilla-central/source/security/manager/ssl/nsIContentSignatureVerifier.idl) in Firefox Desktop or [the rust application services component](https://github.com/mozilla/application-services/) in other Mozilla products.

Index

• Constants
• func ParseChain(chain []byte) (certs []*x509.Certificate, err error)
• func Verify(input, certChain []byte, signature string, rootHashes []string) error
• func VerifyChain(rootHashes []string, certs []*x509.Certificate, currentTime time.Time) error
• type ContentSignature
  • func Unmarshal(signature string) (sig *ContentSignature, err error)
  • func (sig *ContentSignature) Marshal() (str string, err error)
  • func (sig *ContentSignature) String() string
  • func (sig *ContentSignature) VerifyData(input []byte, pubKey *ecdsa.PublicKey) bool
  • func (sig *ContentSignature) VerifyHash(hash []byte, pubKey *ecdsa.PublicKey) bool

Constants

const (
	// P256ECDSA defines an ecdsa content signature on the P-256 curve
	P256ECDSA = "p256ecdsa"

	// P256ECDSABYTESIZE defines the bytes length of a P256ECDSA signature
	P256ECDSABYTESIZE = 64

	// P384ECDSA defines an ecdsa content signature on the P-384 curve
	P384ECDSA = "p384ecdsa"

	// P384ECDSABYTESIZE defines the bytes length of a P384ECDSA signature
	P384ECDSABYTESIZE = 96

	// P521ECDSA defines an ecdsa content signature on the P-521 curve
	P521ECDSA = "p521ecdsa"

	// P521ECDSABYTESIZE defines the bytes length of a P521ECDSA signature
	P521ECDSABYTESIZE = 132

	// SignaturePrefix is a string preprended to data prior to signing
	SignaturePrefix = "Content-Signature:\x00"
)

Functions

func ParseChain

func ParseChain(chain []byte) (certs []*x509.Certificate, err error)

ParseChain parses a PEM-encoded certificate chain.

It parses the end entity/leaf then the intermediate then the root cert. It does not validate the certificates or the chain.

It returns the slice of three certs or an empty slice and an error.

func Verify

func Verify(input, certChain []byte, signature string, rootHashes []string) error

Verify validates the signature and certificate chain of a content signature response

It takes:

input data a content signature metadata a PEM-encoded of the cert chain string a rootHash

It parses the certificate chain, verifies input data using the end-entity certificate of the chain, then verifies the cert chain of trust maps to the signed data.

It returns an error if it fails or nil on success.

func VerifyChain

func VerifyChain(rootHashes []string, certs []*x509.Certificate, currentTime time.Time) error

VerifyChain checks certs in a three certificate chain [EE, intermediate, root] are:

1) signed by their parent/issuer/the next cert in the chain or all verifyRoot checks for the root 2) valid for the current time i.e. cert NotBefore < current time < cert NotAfter 3) the chain follows name constraints and extended key usage as checked by x509 Certificate.Verify

Types

type ContentSignature

type ContentSignature struct {
	R, S     *big.Int // fields must be exported for ASN.1 marshalling
	HashName string
	Mode     string
	X5U      string
	ID       string
	Len      int
	Finished bool
}

ContentSignature contains the parsed representation of a signature

func Unmarshal

func Unmarshal(signature string) (sig *ContentSignature, err error)

Unmarshal parses a base64 url encoded content signature and returns it into a ContentSignature structure that can be verified.

Note this function does not set the X5U value of a signature.

func (*ContentSignature) Marshal

func (sig *ContentSignature) Marshal() (str string, err error)

Marshal returns the R||S signature is encoded in base64 URL safe, following DL/ECSSA format spec from IEEE Std 1363-2000.

func (*ContentSignature) String

func (sig *ContentSignature) String() string

func (*ContentSignature) VerifyData

func (sig *ContentSignature) VerifyData(input []byte, pubKey *ecdsa.PublicKey) bool

VerifyData verifies a signatures on its raw, untemplated, input using a public key

func (*ContentSignature) VerifyHash

func (sig *ContentSignature) VerifyHash(hash []byte, pubKey *ecdsa.PublicKey) bool

VerifyHash verifies a signature on its templated hash using a public key