signing

Documentation

Overview

Package signing implements deferred (remote-hash) PAdES signing of PDFs.

The caller supplies the PDF bytes and the signer's certificate; the package prepares the signature, surfaces the SHA-256 digest of the CMS signed attributes, and parks the signing operation until the caller delivers the raw signature produced elsewhere (typically by a smart card on the user's workstation). The returned signature is verified against the certificate before it is embedded.

A Manager holds the in-flight sessions. Sessions are tagged with an Owner string chosen by the caller (a tenant identity, a user, or an application-specific key); Complete and Cancel require the same owner, and per-owner concurrency can be capped.

NIST 800-53r5: this package is the primary implementation point for AU-10 (non-repudiation) — documents are bound to the signer's PKI identity via PAdES digital signatures — and SC-13 (cryptographic protection: SHA-256 digests, RSA/ECDSA verification via Go stdlib crypto). Per-control annotations appear at the enforcing functions; see docs/nist-800-53-mapping.md for the consolidated ATO matrix.

Index

• Variables
• func LoadCertPool(path string) (*x509.CertPool, error)
• func SanitizeLogField(s string) string
• func ValidateCert(cert *x509.Certificate, roots *x509.CertPool) error
• func ValidateTSAURL(raw string, allowInsecure bool) error
• type Manager
  • func NewManager(ttl time.Duration, maxPerOwner int, onExpire func(token, owner string)) *Manager
  • func (m *Manager) Cancel(token, owner string) error
  • func (m *Manager) Complete(token, owner string, signature []byte) ([]byte, error)
  • func (m *Manager) Owner(token string) (string, bool)
  • func (m *Manager) Prepare(pdfBytes []byte, cert *x509.Certificate, opts Options) (*Session, error)
• type Options
• type Session

Variables

var ErrNotFound = errors.New("unknown or expired signing session")

ErrNotFound is returned by Complete and Cancel when no session matches the token/owner pair (unknown, expired, or owned by someone else).

Functions

func LoadCertPool

func LoadCertPool(path string) (*x509.CertPool, error)

LoadCertPool reads a PEM bundle into a certificate pool.

func SanitizeLogField

func SanitizeLogField(s string) string

newToken generates the session identifier.

NIST 800-53r5 SC-23(3) (unique system-generated session identifiers): 128 bits from crypto/rand; identifiers are single-use (takeOwned removes them) and expire at the session TTL. SanitizeLogField strips control characters (CR/LF/tabs and other non-printables) from a value before it is written to a log line. Certificate CNs are attacker-influenceable up to the issuing CA's policy; sanitizing prevents forged or split audit records (AU-9: audit information integrity).

func ValidateCert

func ValidateCert(cert *x509.Certificate, roots *x509.CertPool) error

ValidateCert enforces the certificate policy for signing: digital signature key usage, and (when roots is non-nil) a chain to a trusted CA.

NIST 800-53r5 IA-5(2) (PKI-based authentication): certification-path validation to organization-configured trust anchors before any signing work is performed. SC-17 (PKI certificates): the trust anchors are the organization's approved CAs supplied via -sign-ca.

func ValidateTSAURL

func ValidateTSAURL(raw string, allowInsecure bool) error

ValidateTSAURL checks that a Time Stamping Authority URL is well-formed and, unless allowInsecure is set, uses HTTPS. The pdfsign TSA client runs without TLS by default, so a plaintext TSA over http:// exposes the timestamp exchange to a network attacker who could stall or bloat the response (SC-8: transmission confidentiality/integrity; SC-5: DoS).

Types

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager tracks in-flight sessions and expires abandoned ones.

func NewManager

func NewManager(ttl time.Duration, maxPerOwner int, onExpire func(token, owner string)) *Manager

NewManager creates a Manager and starts its expiry janitor. ttl bounds how long a prepared session may wait for its signature; onExpire (may be nil) lets the caller release any state keyed to the session.

NIST 800-53r5 AC-12 (session termination): abandoned signing sessions are terminated automatically at ttl. SC-5(2) (resource availability): maxPerOwner caps concurrent sessions — and therefore parked goroutines and in-memory documents — per owner/tenant.

func (*Manager) Cancel

func (m *Manager) Cancel(token, owner string) error

Cancel aborts an in-flight session.

func (*Manager) Complete

func (m *Manager) Complete(token, owner string, signature []byte) ([]byte, error)

Complete verifies the signature against the session's certificate, resumes the parked signing operation, and returns the signed PDF. On any error the session is closed; the caller's document is untouched because all work happens on in-memory copies.

func (*Manager) Owner

func (m *Manager) Owner(token string) (string, bool)

Owner reports the owner of an active session, so callers that key state by owner can resolve a bare token.

func (*Manager) Prepare

func (m *Manager) Prepare(pdfBytes []byte, cert *x509.Certificate, opts Options) (*Session, error)

Prepare starts a deferred signature over pdfBytes and returns once the digest to be signed is known. The session stays open until Complete, Cancel, or expiry.

type Options

type Options struct {
	Owner    string // required for multi-tenant use; must be repeated on Complete/Cancel
	Name     string // signer name shown in the PDF signature dictionary
	Reason   string
	Location string

	// TSAURL, when set, obtains an RFC 3161 timestamp for the signature
	// from this Time Stamping Authority during Complete (PAdES-T).
	//
	// NIST 800-53r5 AU-10 (non-repudiation): a trusted timestamp proves
	// when the signature was made and keeps it verifiable after the
	// signer's certificate expires.
	TSAURL string
}

Options configures one signing session.

type Session

type Session struct {
	Token     string
	Owner     string
	Digest    []byte // SHA-256 of the CMS signed attributes; sign this
	ExpiresAt time.Time
	// contains filtered or unexported fields
}

Session is an in-flight deferred signature.