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
- func Canonical(b []byte) ([]byte, error)
- func CanonicalValue(v any) ([]byte, error)
- func ParseCertificates(b []byte) ([]*x509.Certificate, error)
- func ParsePEM(keyPEM, certPEM []byte) (crypto.Signer, []*x509.Certificate, error)
- type Document
- type Options
- type Payload
- type Signature
- type VerifyOptions
Constants ¶
const (
MaxSignatures = 64
)
Limits of the signatures of a document.
const SplitFile = "signatures.json"
SplitFile is the file of the signatures of the split form.
const Version = 1
Version is the version of the signed document (bdf-signature).
Variables ¶
This section is empty.
Functions ¶
func CanonicalValue ¶
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.
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 (*Document) Sign ¶
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 ¶
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 ¶
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.