sign

package
v0.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package sign signs BDF documents and verifies their signatures, so that a change made to a document after it was signed is found (spec §3.7).

A signature is a CMS SignedData (RFC 5652) with an X.509 certificate of its signer. What it signs is a small JSON document of its own, which it holds: the SHA-256 of the canonical JSON (RFC 8785) of the manifest, the SHA-256 of each part as it is stored, in the order of the manifest, the SHA-256 of each signature before it, and the claims of the signer (who signs, in what role). The whole digests of SHA-256 are signed, not the names of the parts, which are 16 bytes of them.

The signatures of a single-file document follow its parts, in a block with a footer of 16 bytes (readers that do not know of them read the document as it is); those of the split form are signatures.json beside manifest.json. They are added one after another: a later signature covers the ones before it, so that one cannot be taken away unseen.

A signature finds changes; it does not prevent them, and it says nothing of whether what was signed was true. A drawn signature in a form (form, tag.InputSignature) is a picture, not a signature of this package.

Index

Constants

View Source
const (
	MaxSignatures = 64
)

Limits of the signatures of a document.

View Source
const SplitFile = "signatures.json"

SplitFile is the file of the signatures of the split form.

View Source
const Version = 1

Version is the version of the signed document (bdf-signature).

Variables

This section is empty.

Functions

func Canonical

func Canonical(b []byte) ([]byte, error)

Canonical writes the canonical JSON of JSON.

func CanonicalValue

func CanonicalValue(v any) ([]byte, error)

CanonicalValue writes the canonical JSON of a value of JSON (as encoding/json decodes it, with json.Number or float64 numbers).

func ParseCertificates

func ParseCertificates(b []byte) ([]*x509.Certificate, error)

ParseCertificates reads the certificates of PEM.

func ParsePEM

func ParsePEM(keyPEM, certPEM []byte) (crypto.Signer, []*x509.Certificate, error)

ParsePEM reads a private key (PKCS #8, EC or PKCS #1, in PEM) and the certificates of its chain (PEM, the key's first), as the bdf command and the manager of documents take them.

Types

type Document

type Document struct {
	// Reader reads the document.
	Reader *bdf.Reader
	// Size is the size of the single-file document without its signatures.
	Size int64
	// Signatures are the DER of its signatures, in their order.
	Signatures [][]byte
	// contains filtered or unexported fields
}

Document is a document with its signatures, as Read reads it.

func Read

func Read(r io.ReaderAt, size int64) (*Document, error)

Read reads a single-file document and its signatures.

func ReadSplit

func ReadSplit(dir string) (*Document, error)

ReadSplit reads a document of the split form and its signatures.

func (*Document) Sign

func (d *Document) Sign(key crypto.Signer, chain []*x509.Certificate, o *Options) ([]byte, error)

Sign makes a signature of a document after the signatures it has: the DER of a SignedData. Add writes the document with it.

func (*Document) Verify

func (d *Document) Verify(o *VerifyOptions) ([]*Signature, error)

Verify checks every signature of a document. It fails only when the document cannot be read; what it finds of each signature is in its Signature.

func (*Document) WriteSingle

func (d *Document) WriteSingle(w io.Writer, more ...[]byte) error

WriteSingle writes a single-file document with its signatures and more (Sign). The bytes of the document are copied as they are.

func (*Document) WriteSplit

func (d *Document) WriteSplit(more ...[]byte) error

WriteSplit writes the signatures of a document of the split form, with more, to its signatures.json.

type Options

type Options struct {
	// Claims are signed with the document (Payload.Claims).
	Claims map[string]any
	// Time is the signing time (the clock when zero). It is the signer's
	// word; a time-stamp is the word of a TSA.
	Time time.Time
	// TSA is the URL of a time-stamp authority (RFC 3161) that stamps the
	// signature, and Client the client that asks it (nil:
	// http.DefaultClient).
	TSA    string
	Client *http.Client
	// Hash is the digest of the signature (SHA-256 when 0). The digests of
	// the payload are SHA-256 always.
	Hash crypto.Hash
}

Options are the options of a signature.

type Payload

type Payload struct {
	Version int `json:"bdf-signature"`
	// Manifest is the SHA-256 (hex) of the canonical JSON of the stored
	// manifest, without the offsets of its parts.
	Manifest string `json:"manifest"`
	// Parts are the SHA-256 (hex) of the stored bytes of the parts, in the
	// order of the manifest.
	Parts []string `json:"parts"`
	// Previous are the SHA-256 (hex) of the DER of the signatures before
	// this one, in their order.
	Previous []string `json:"previous"`
	// Claims are what the signer says of the signature: its role
	// ("author", "counterparty", "witness" …), and what a witness saw (who
	// did what, when). They are signed with the document.
	Claims map[string]any `json:"claims,omitempty"`
}

Payload is what a signature signs.

type Signature

type Signature struct {
	// Index is the place of the signature among those of the document.
	Index int
	// Certificate is the certificate of the signer, and Chain its chain
	// to a trusted root (none when it is not trusted).
	Certificate *x509.Certificate
	Chain       []*x509.Certificate
	// SigningTime is the time the signer says; TimeStamp the time a TSA
	// stamped the signature at (zero without one), and TSA its
	// certificate.
	SigningTime time.Time
	TimeStamp   time.Time
	TSA         *x509.Certificate
	// Claims are the claims of the signer.
	Claims map[string]any
	// Covers tells what the signature covers: the whole of the document
	// with the signatures before it.
	Payload *Payload
	// Err is why the signature does not hold for the document (nil: it
	// does): the document or a signature before it changed after it was
	// signed, or the signature is damaged. TrustErr is why its
	// certificate is not trusted, while the signature itself holds.
	Err      error
	TrustErr error
}

Signature is what Verify finds of a signature.

func (*Signature) Valid

func (s *Signature) Valid() bool

Valid reports whether the signature holds and its certificate is trusted.

type VerifyOptions

type VerifyOptions struct {
	// Roots are the certificates trusted (nil: those of the system).
	Roots *x509.CertPool
	// Now is the time to check certificates at when a signature has no
	// time-stamp (the clock when zero).
	Now time.Time
}

VerifyOptions are the options of Verify.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL