Add a Timestamp to a Signature

The date on a signature is whatever the signer’s machine claimed at the time. A document timestamp replaces that with an assertion from a timestamp authority: a signature of subfilter ETSI.RFC3161 over everything written so far, proving the document existed in that form at a time the signer did not choose. Over a PAdES B-B signature, a document timestamp is one way to reach PAdES B-T.

The timestamp has to go in its own revision, since it has to cover the revision that holds the signature, and an appender can only be written once.

Doing it

Write the signed revision to a buffer, then start again over those bytes:

outDoc := bytes.NewBuffer(nil)
if err = appender.Write(outDoc); err != nil {
    return err
}

reader, err := model.NewPdfReader(bytes.NewReader(outDoc.Bytes()))
if err != nil {
    return err
}

appender, err = model.NewPdfAppender(reader)
if err != nil {
    return err
}

handler, err = sighandler.NewDocTimeStamp("https://freetsa.org/tsr", crypto.SHA512)
if err != nil {
    return err
}

signature = model.NewPdfSignature(handler)
signature.SetName("Document Timestamp")
signature.SetReason("RFC 3161 document timestamp")
signature.SetDate(time.Now(), "")

if err := signature.Initialize(); err != nil {
    return err
}

sigField := model.NewPdfFieldSignature(signature)
sigField.T = core.MakeString("Document Timestamp")
sigField.Rect = core.MakeArray(core.MakeInteger(0), core.MakeInteger(0),
    core.MakeInteger(0), core.MakeInteger(0))

if err = appender.Sign(1, sigField); err != nil {
    return err
}

return appender.WriteToFile(outputPath)

bytes.NewReader matters: model.NewPdfAppender returns an error unless the reader’s source satisfies both io.ReadSeeker and io.ReaderAt, and a *bytes.Buffer satisfies neither.

There is no signer and nothing to display, so the field is built with model.NewPdfFieldSignature and a zero rectangle rather than through annotator.NewSignatureField. The example still sets a name, reason and date on the signature dictionary. A validator reports them, but the timestamp’s own time is the GeneralizedTime inside the token.

Limitations

NewDocTimeStamp makes a mock Sign call while initializing the signature to find out how large the token is, so every timestamp costs two requests to the timestamp authority. Use NewDocTimeStampWithOpts to state the size up front:

handler, err := sighandler.NewDocTimeStampWithOpts("https://freetsa.org/tsr", crypto.SHA512,
    &sighandler.DocTimeStampOpts{SignatureSize: 8192})

SignatureSize defaults to 4192 when zero, which is smaller than a SHA-512 token from freetsa.org. If the token comes back larger than the reserved space, signing fails with model.ErrSignNotEnoughSpace (insufficient space allocated for the signature contents). Client in the same options struct replaces the default sigutil.TimestampClient, which is where a proxy or an authenticated TSA fits.

Supported hash algorithms are crypto.SHA1, crypto.SHA256, crypto.SHA384 and crypto.SHA512. Others fail when the response is parsed.

Timestamping is a live HTTP request, so this cannot run offline, and the default client gives the TSA 5 seconds to answer.

The timestamp only proves existence, not validity. Keeping it verifiable in the long run means putting its own certificate chain in the DSS as well, which is what LTV enable with a document timestamp covers.

Run the example

main does both revisions in sequence: sign with sighandler.NewAdobePKCS7Detached from a PKCS12 file, then add the ETSI.RFC3161 document timestamp in a second revision. The timestamp comes from freetsa.org, so the example needs network access, and it exits with Fail: and the error if the TSA request fails.

git clone https://github.com/unidoc/unipdf-examples.git
cd unipdf-examples/signatures/signing
go run pdf_sign_timestamp.go <FILE.p12> <PASSWORD> <INPUT_PDF_PATH> <OUTPUT_PDF_PATH>

If this is your first time using UniPDF, follow the getting started guide to create an API key and set up your development environment.