sign

package
v0.0.0-...-f985856 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: MPL-2.0 Imports: 24 Imported by: 0

Documentation

Overview

This file signs and verifies PDF CMS signatures.

Package sign provides PDF signing and verification APIs.

Source-PDF signing intentionally supports unencrypted classic-xref PDFs with no existing AcroForm and a direct page annotation array. Unsupported source structures return an error matching ErrUnsupportedPDF. Verification also requires a supported classic xref chain, follows the current catalog's AcroForm field tree, and ignores unreferenced signature dictionaries. ExtractSingleSignature is available when callers require exactly one reachable signature.

Index

Constants

View Source 
const (

	// DefaultMaxSourceBytes bounds PDF inputs accepted by signing APIs.
	DefaultMaxSourceBytes int64 = 128 * 1024 * 1024
	// DefaultMaxXrefChainLength bounds incremental PDF revision chains.
	DefaultMaxXrefChainLength = 128
	// DefaultMaxXrefEntries bounds the declared/scanned objects in one xref table.
	DefaultMaxXrefEntries = 1_000_000
)
View Source 
const (
	// SubFilterETSI_CAdESDetached advertises a CAdES detached PDF signature.
	SubFilterETSI_CAdESDetached = "ETSI.CAdES.detached"
	// SubFilterAdobePKCS7Detached advertises a detached PKCS#7/CMS PDF signature.
	SubFilterAdobePKCS7Detached = "adbe.pkcs7.detached"
)

Variables

View Source 
var (
	// ErrMissingInput is returned when a PDF input path or byte slice is empty.
	ErrMissingInput = errors.New("pdfsigning: input is required")
	// ErrMissingOutput is returned when the signed PDF output path is empty.
	ErrMissingOutput = errors.New("pdfsigning: output is required")
	// ErrMissingSigner is returned when no signing key is configured.
	ErrMissingSigner = errors.New("pdfsigning: signer is required")
	// ErrMissingCertificate is returned when no signing certificate is configured.
	ErrMissingCertificate = errors.New("pdfsigning: certificate is required")
	// ErrUnsupportedPDF is returned when a source PDF uses a structure that the
	// intentionally narrow signing parser cannot preserve safely.
	ErrUnsupportedPDF = errors.New("pdfsigning: unsupported PDF structure")
)
View Source 
var ErrTrustStoreRequired = errors.New("pdfsigning: trust store is required")

ErrTrustStoreRequired is returned by trusted verification APIs when no root certificate pool is supplied.

Functions

func AdobeRevocationInfoArchivalOID 

func AdobeRevocationInfoArchivalOID() asn1.ObjectIdentifier

AdobeRevocationInfoArchivalOID returns Adobe's revocation-info archival OID.

func AppendBytes 

func AppendBytes(input []byte, options Options) ([]byte, error)

AppendBytes signs a PDF byte slice and may reuse input's backing array for the returned signed PDF. Callers must not use input after calling AppendBytes.

func AppendBytesContext 

func AppendBytesContext(ctx context.Context, input []byte, options Options) ([]byte, error)

AppendBytesContext signs a PDF byte slice and checks ctx around parsing and signing. Cancellation during a crypto.Signer implementation depends on that signer returning.

func ByteRangeFromInts 

func ByteRangeFromInts(byteRange []int) ([4]int64, error)

ByteRangeFromInts converts a parsed ByteRange into a fixed int64 tuple.

func ByteRangeToInts 

func ByteRangeToInts(byteRange [4]int64) ([]int, error)

ByteRangeToInts converts a fixed int64 ByteRange tuple into parser indexes.

func Bytes 

func Bytes(input []byte, options Options) ([]byte, error)

Bytes signs a PDF byte slice and returns a new signed PDF.

func BytesContext 

func BytesContext(ctx context.Context, input []byte, options Options) ([]byte, error)

BytesContext signs a PDF byte slice and checks ctx around parsing and signing. Cancellation during a crypto.Signer implementation depends on that signer returning.

func CreateCMS 

func CreateCMS(content []byte, options CMSOptions) ([]byte, error)

CreateCMS creates CMS SignedData using this package's own DER encoder.

func DecodeCMS 

func DecodeCMS(value string) ([]byte, string, error)

DecodeCMS decodes a CMS payload from PEM, data URL base64, or base64 text.

The returned encoding string is intended for diagnostics.

func DigestHex 

func DigestHex(input []byte, digest crypto.Hash) (string, error)

DigestHex returns the hex digest of the PDF bytes covered by /ByteRange.

func DigestHexForByteRange 

func DigestHexForByteRange(input []byte, byteRange [4]int64, digest crypto.Hash) (string, error)

DigestHexForByteRange returns the hex digest of the PDF bytes covered by byteRange.

func EmbedDetachedCMS 

func EmbedDetachedCMS(input, signature []byte) ([]byte, error)

EmbedDetachedCMS replaces the PDF /Contents hex string with signature.

func ExtractByteRange 

func ExtractByteRange(input []byte) ([]int, error)

ExtractByteRange returns the latest supported PDF signature ByteRange.

func File 

func File(inputPath, outputPath string, options Options) error

File signs inputPath and writes the signed PDF to outputPath.

func FileContext 

func FileContext(ctx context.Context, inputPath, outputPath string, options Options) error

FileContext signs inputPath with bounded reads and context cancellation, then writes the signed PDF to outputPath.

func SignatureCount 

func SignatureCount(input []byte) int

SignatureCount returns the number of supported signature values reachable through the current catalog's AcroForm field tree. Names in strings, comments, stream data, unrelated dictionaries, and unreferenced objects are ignored.

func SignedAttributeValues 

func SignedAttributeValues(signature []byte, oid asn1.ObjectIdentifier) ([]asn1.RawValue, error)

SignedAttributeValues returns values for the first CMS signed attribute matching oid.

func SignedContent 

func SignedContent(input []byte, byteRange []int) ([]byte, error)

SignedContent returns the PDF bytes covered by byteRange.

func SignedContentForByteRange 

func SignedContentForByteRange(input []byte, byteRange [4]int64) ([]byte, error)

SignedContentForByteRange returns the PDF bytes covered by byteRange.

func SignerCertificate 

func SignerCertificate(signature []byte) (*x509.Certificate, error)

SignerCertificate returns the certificate referenced by the first SignerInfo.

Types

type CMSInfo 

type CMSInfo struct {
	// Certificates contains certificates embedded in the CMS payload.
	Certificates []*x509.Certificate
	// Signer is the certificate referenced by the first SignerInfo.
	Signer *x509.Certificate
	// SignedAttributes contains signed attributes from the first SignerInfo.
	SignedAttributes []SignedAttribute
}

CMSInfo contains CMS metadata useful for policy checks.

func InspectCMS 

func InspectCMS(signature []byte) (*CMSInfo, error)

InspectCMS parses CMS metadata without verifying the signature.

type CMSOptions 

type CMSOptions struct {
	// Signer signs the CMS signed attributes.
	Signer crypto.Signer
	// Certificate is the signing certificate and must match Signer.
	Certificate *x509.Certificate
	// CertificateChain contains optional intermediate certificates to include.
	CertificateChain []*x509.Certificate
	// DigestAlgorithm selects the message digest. A zero value uses SHA-256.
	DigestAlgorithm crypto.Hash
	// Detached omits the signed content from the CMS payload when true.
	Detached bool
	// SigningTime sets the CMS signingTime attribute. A zero value uses now.
	SigningTime time.Time
}

CMSOptions configures CMS SignedData creation.

type CMSVerifyResult 

type CMSVerifyResult struct {
	// Certificates contains the certificates embedded in the CMS payload.
	Certificates []*x509.Certificate
	// Signer is the certificate that produced the verified signature.
	Signer *x509.Certificate
	// Digest is the digest algorithm used by the signer.
	Digest crypto.Hash
	// Detached reports whether the CMS payload is detached from its content.
	Detached bool
	// Content contains the verified content.
	Content []byte
	// SigningTime is the optional signingTime attribute from the CMS payload.
	SigningTime *time.Time
	// ValidSignature reports whether the CMS signature was cryptographically valid.
	ValidSignature bool
	// TrustedSigner reports whether the signer chained to the supplied truststore.
	TrustedSigner bool
}

CMSVerifyResult contains the relevant result of a CMS verification.

func VerifyCMS 

func VerifyCMS(signature []byte, truststore *x509.CertPool) (*CMSVerifyResult, error)

VerifyCMS verifies attached CMS SignedData containing exactly one signer.

func VerifyCMSIntegrity 

func VerifyCMSIntegrity(signature []byte) (*CMSVerifyResult, error)

VerifyCMSIntegrity verifies one signer's CMS cryptographic integrity without establishing signer trust. Multi-signer packages are rejected. Callers must not use this as an authorization decision.

func VerifyDetachedCMS 

func VerifyDetachedCMS(signature, content []byte, truststore *x509.CertPool) (*CMSVerifyResult, error)

VerifyDetachedCMS verifies detached CMS SignedData containing exactly one signer against content.

func VerifyDetachedCMSIntegrity 

func VerifyDetachedCMSIntegrity(signature, content []byte) (*CMSVerifyResult, error)

VerifyDetachedCMSIntegrity verifies detached CMS cryptographic integrity for exactly one signer without establishing signer trust.

type Credentials 

type Credentials struct {
	Signer           crypto.Signer
	Certificate      *x509.Certificate
	CertificateChain []*x509.Certificate
}

Credentials contains a PDF signer and its X.509 certificate chain. Signer may be replaced by an HSM, KMS, PKCS#11, or operating-system-backed crypto.Signer without exposing private-key bytes to Paper documents.

func LoadPEMCredentials 

func LoadPEMCredentials(certificateFile, privateKeyFile string, chainFiles []string) (Credentials, error)

LoadPEMCredentials loads one leaf certificate, optional intermediate certificates, and an unencrypted PKCS#8, PKCS#1, or SEC1 private key.

Passwords and private-key bytes are intentionally not accepted as string arguments. Production servers should prefer injecting a managed crypto.Signer; PEM loading is intended for explicitly protected local or mounted secret files.

type Options 

type Options struct {
	// Signer signs the CMS payload for the PDF signature.
	Signer crypto.Signer
	// Certificate is the signing certificate and must match Signer.
	Certificate *x509.Certificate
	// CertificateChain contains optional intermediate certificates to include.
	CertificateChain []*x509.Certificate
	// DigestAlgorithm selects the message digest. A zero value uses SHA-256.
	DigestAlgorithm crypto.Hash
	// Name is the signer name stored in the PDF signature dictionary.
	Name string
	// Location is the signing location stored in the PDF signature dictionary.
	Location string
	// Reason is the signing reason stored in the PDF signature dictionary.
	Reason string
	// ContactInfo is signer contact information stored in the signature dictionary.
	ContactInfo string
	// SubFilter selects the PDF signature SubFilter. A zero value uses
	// ETSI.CAdES.detached for backward-compatible PAdES-oriented output.
	SubFilter string
	// FieldName is the PDF signature field name. A zero value uses "Signature1".
	FieldName string
	// SigningTime sets the signature timestamp. A zero value uses now.
	SigningTime time.Time
	// SignatureSize is the reserved CMS signature size in bytes.
	SignatureSize int
	// MaxSourceBytes bounds the source PDF. Zero uses DefaultMaxSourceBytes.
	MaxSourceBytes int64
	// MaxXrefChainLength bounds incremental xref revisions. Zero uses
	// DefaultMaxXrefChainLength.
	MaxXrefChainLength int
	// MaxXrefEntries bounds declared and scanned classic xref entries. Zero uses
	// DefaultMaxXrefEntries.
	MaxXrefEntries int
}

Options configures a PDF signature.

type OtherRevocation 

type OtherRevocation struct {
	// Type identifies the revocation evidence type.
	Type asn1.ObjectIdentifier
	// Value contains DER-encoded revocation evidence.
	Value []byte
}

OtherRevocation contains non-CRL and non-OCSP revocation evidence.

type PDFSignature 

type PDFSignature struct {
	// ByteRange is the signed byte range declared by the PDF signature.
	ByteRange []int
	// CMS contains the verified CMS signature details.
	CMS *CMSVerifyResult
}

PDFSignature contains a verified PDF signature summary.

func Verify 

func Verify(input []byte, truststore *x509.CertPool) (*PDFSignature, error)

Verify verifies the latest supported CMS signature found in a signed PDF.

func VerifyIntegrity 

func VerifyIntegrity(input []byte) (*PDFSignature, error)

VerifyIntegrity verifies the latest supported CMS signature's cryptographic integrity without establishing signer trust. It must not be used for authorization.

type PDFSignatureContents 

type PDFSignatureContents struct {
	// ByteRange is the signed byte range declared by the PDF signature.
	ByteRange []int
	// ContentsStart is the byte offset of the /Contents opening "<".
	ContentsStart int
	// ContentsEnd is the byte offset immediately after the /Contents closing ">".
	ContentsEnd int
	// CMS is the DER CMS signature from /Contents, without zero padding.
	CMS []byte
	// SignedContent is the concatenated PDF bytes covered by ByteRange.
	SignedContent []byte
}

PDFSignatureContents contains the raw signature bytes and the signed content selected by a PDF signature dictionary.

func ExtractSignature 

func ExtractSignature(input []byte) (*PDFSignatureContents, error)

ExtractSignature extracts a PDF signature dictionary's CMS bytes and signed content.

func ExtractSingleSignature 

func ExtractSingleSignature(input []byte) (*PDFSignatureContents, error)

ExtractSingleSignature extracts a PDF signature when exactly one ByteRange exists.

func (*PDFSignatureContents) ByteRange64 

func (contents *PDFSignatureContents) ByteRange64() ([4]int64, error)

ByteRange64 returns ByteRange as the fixed-width int64 tuple used by many APIs.

func (*PDFSignatureContents) ContentsHexLen 

func (contents *PDFSignatureContents) ContentsHexLen() int

ContentsHexLen returns the reserved /Contents hex-string length.

func (*PDFSignatureContents) MaxSignatureBytes 

func (contents *PDFSignatureContents) MaxSignatureBytes() int

MaxSignatureBytes returns the maximum DER CMS size that fits in /Contents.

type RevocationInfo 

type RevocationInfo struct {
	// CRL contains DER-encoded certificate revocation lists.
	CRL []asn1.RawValue `asn1:"tag:0,optional,explicit"`
	// OCSP contains DER-encoded OCSP responses.
	OCSP []asn1.RawValue `asn1:"tag:1,optional,explicit"`
	// Other contains additional DER-encoded revocation evidence.
	Other []OtherRevocation `asn1:"tag:2,optional,explicit"`
}

RevocationInfo contains Adobe revocation-info archival evidence carried in a CMS signed attribute for PAdES workflows.

func DecodeAdobeRevocationInfo 

func DecodeAdobeRevocationInfo(value asn1.RawValue) (RevocationInfo, error)

DecodeAdobeRevocationInfo decodes one Adobe revocation-info archival signed attribute value.

func ExtractAdobeRevocationInfo 

func ExtractAdobeRevocationInfo(signature []byte) (RevocationInfo, error)

ExtractAdobeRevocationInfo extracts Adobe revocation-info archival data from CMS SignedData.

func (*RevocationInfo) AddCRL 

func (r *RevocationInfo) AddCRL(value []byte) error

AddCRL appends DER-encoded CRL evidence.

func (*RevocationInfo) AddOCSP 

func (r *RevocationInfo) AddOCSP(value []byte) error

AddOCSP appends DER-encoded OCSP evidence.

type SignedAttribute 

type SignedAttribute struct {
	// OID identifies the signed attribute.
	OID asn1.ObjectIdentifier
	// Values contains the attribute set values as raw ASN.1 values.
	Values []asn1.RawValue
}

SignedAttribute is one CMS signed attribute and its ASN.1 values.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.