Signature

Signing a PDF in UniPDF is an incremental update. model.PdfAppender copies the original bytes through untouched and appends a new revision containing the signature, so the digest the signature covers stays valid and any earlier signature keeps verifying. That is the reason signing never goes through PdfWriter: a writer rebuilds the file, which invalidates every signature already in it.

Four objects are involved, and it helps to know which one owns what.

appender, err := model.NewPdfAppender(reader)

handler, err := sighandler.NewAdobePKCS7Detached(privateKey, cert)

signature := model.NewPdfSignature(handler)
signature.SetName("Jane Doe")
signature.SetReason("Approval")
signature.SetDate(time.Now(), "")
if err := signature.Initialize(); err != nil {
    return err
}

field, err := annotator.NewSignatureField(signature, lines, opts)
field.T = core.MakeString("Approval signature")

if err := appender.Sign(1, field); err != nil {
    return err
}
return appender.WriteToFile(outputPath)

The handler holds the key and decides the cryptography: which /SubFilter is written, how the digest is computed, and how much space /Contents needs. The signature dictionary holds the metadata a reader displays, name, reason, location and date, plus the certificate chain in /Cert for the handlers that use it. The field is the visible part: a widget annotation with an appearance stream, a rectangle and a page. The appender ties them together and produces the bytes.

Ordering matters in two places. signature.Initialize() must run before the appender writes, because that is what asks the handler to reserve space for the signature, and it is where a handler built without a private key fails. And PdfAppender.Write can only be called once, so a second signature means writing, reopening the result, and starting again.

Choosing a handler

Every constructor also accepts nil for the key and certificate, which produces a validation-only handler. PdfReader.ValidateSignatures picks the first handler in the list whose /Filter and /SubFilter match, so order the list from most specific to least.

Appearance

A signature does not have to be visible. Building the field with model.NewPdfFieldSignature and a zero-sized Rect skips the appearance entirely, which is what a document timestamp wants. When it should be visible, annotator.NewSignatureField builds the appearance stream from a slice of annotator.SignatureLine and a annotator.SignatureFieldOpts, and the styling is entirely independent of the signature: nothing in the box is read back from the signature dictionary.

One PdfSignature can back several fields on several pages. Field names must still be unique, and Sign only auto-names by page number, so set field.T yourself whenever a document gets more than one signature widget.

Where to look

Signing with a key you hold:

The visible appearance:

Encryption, validation and revisions:

Signing with a key you do not hold:

Certifying a document with DocMDP:

Timestamps:

PAdES:

Long-term validation: