Skip to content

v0.16.0

Latest
Latest

Choose a tag to compare

View all tags
@hhrutter hhrutter released this 28 Sep 21:31
v0.16.0
d4effbd
This commit was signed with the committer’s verified signature. The key has expired.
hhrutter Horst Rutter
GPG key ID: 3535854A58720AFD
Expired
Verified
Learn about vigilant mode.

v0.16.0

This release updates the Go API and configuration model, improves automation and PDF validation, and includes processing fixes and security hardening.

Changes since v0.16.0-rc.1

  • Protect image buffer allocations against integer overflow and enforce resource limits before decoding each TIFF page.
  • Fix default-configuration handling (#1492): synchronize access to the cached default configuration and return independent clones to callers.

Security advisories

This release includes fixes covered by six security advisories.

Highlights

  • Updated Go API — Explicit contexts for long-running operations, optional progress reporting, and reusable caller-owned configuration.
  • Configuration redesign — Schema-aware loading, explicit initialization and reset, plus read-only and stateless operation.
  • Automation and container preparation — Signal cancellation, safer output replacement, password-file inputs, and verified execution under arbitrary user IDs.
  • Stronger PDF validation — Improved malformed-input handling, graph-traversal safeguards, and compatibility warnings for selected relaxed-validation decisions.
  • Clearer signature validation — Separate reporting of document integrity, certificate trust, revocation, and timestamp evidence.
  • PDF processing fixes — Improved resize orientation, rotated watermarks, form appearances, image handling, and LZW decoding.
  • Smaller Go module — Approximately 94% smaller in the original packaging comparison. Samples and test fixtures remain in Git but are excluded from module downloads.

Requirements and installation

Go applications require Go 1.26 or later and updates to affected API calls. Existing file-backed configurations from v0.15 or earlier require an explicit configuration reset.

go get github.com/pdfcpu/pdfcpu@v0.16.0

Before upgrading

Reset legacy file-backed configuration

Existing v0.15 and older config.yml files do not contain the new configuration schema identifier. pdfcpu preserves the
file and reports that a reset is required instead of rewriting it automatically.

If the configuration is not customized, run:

pdfcpu config reset
pdfcpu config validate

For an explicit configuration root, use the same root for every command:

pdfcpu --conf /srv/pdfcpu config reset
pdfcpu --conf /srv/pdfcpu config validate
pdfcpu --conf /srv/pdfcpu config inspect

Before resetting, back up any customized config.yml. After resetting, reapply your settings.
Installed user fonts and trusted certificates are preserved.

New installations and stateless operation with --conf disable need no migration.

See the v0.16 configuration upgrade guide.

Update Go API callers

Change Required action
Long-running operations require a context.Context Pass the request or job context, or context.Background() when cancellation is not needed. Nil contexts are rejected.
Validation and optimization operations take a final *api.ProgressOptions Pass nil when progress events are not needed.
LoadConfiguration() now takes options and returns an error Call api.LoadConfiguration(api.ConfigurationOptions{}) and handle the error.
Context-free and interim WithContext/WithOptions variants were consolidated Use the canonical operation name.

Configurations supplied by an application remain caller-owned and can be reused after an operation. Clone a configuration
before applying different settings for another job; do not mutate it concurrently while operations use it.
Passing nil loads the default configuration and may initialize files on disk. For stateless
applications, explicitly load api.ConfigurationModeStateless and pass the returned configuration.

See API installation and usage and the
v0.16 migration guide for before/after examples.

Configuration and runtime

Explicit configuration modes

  • Automatic discovers or initializes file-backed configuration for normal CLI and API use.
  • Read-only loads a prepared configuration tree without modifying it.
  • Stateless uses built-in settings and the 14 core PDF fonts without accessing configuration files, user fonts or the
    local certificate store.

The CLI selects stateless mode with --conf disable.

Applications select a mode through api.ConfigurationOptions.

Configuration root precedence is the explicit flag, PDFCPU_CONFIG_ROOT, then the operating-system default.
Normal CLI PDF
commands have no read-only-mode flag: prepare the complete tree first and mount it read-only.
Go applications can select api.ConfigurationModeReadOnly to load existing configuration without modifying files.

The new commands are:

pdfcpu config init
pdfcpu config list
pdfcpu config inspect [--json]
pdfcpu config validate
pdfcpu config reset

Use
pdfcpu config inspect for configuration paths and effective policy.

Cancellation and transactional output

The CLI responds to Ctrl+C, SIGINT and SIGTERM. The first signal requests a clean stop; a second signal terminates
immediately. Go callers control cancellation through the context passed to the operation.

Cancellation is cooperative, so a large operation may take a moment to reach a safe stopping point. File-producing
operations stage output before publication. When cancellation or an ordinary write failure occurs before publication,
an existing destination is preserved and unfinished temporary output is removed.

Stdin PDF input and merged form multi-fill output to stdout use the operating-system temporary directory. Replacement
files are staged beside their destination. On supported Unix systems, replacement preserves the destination group or
fails before publication.

Password files

Use --upw-file or --opw-file wherever the corresponding literal password flag is accepted. Supply a password either
directly or through a file, not both. Password files cannot use stdin.

One trailing LF or CRLF is ignored. Other spaces and line endings remain part of the password. An empty file supplies an
empty password, except where a non-empty owner password is required.

Password changes can replace their positional old/new password pair with:

Command Old password New password
changeupw --upwold-file --upwnew-file
changeopw --opwold-file --opwnew-file

Both file options for a password change must be supplied together.

Resource and network policy

  • maxInputBytes optionally limits each PDF input, including stdin spooling. Zero remains unlimited.
  • maxObjectBytes exposes the existing per-object reader buffer limit. Its default remains 64 MiB.
  • Offline mode now consistently covers remote images, link validation and live CRL/OCSP requests.
  • Outbound image and revocation requests reject loopback, private, link-local, multicast, unspecified and selected
    special-purpose destinations by default. Trusted private revocation hosts can be configured explicitly.

These settings limit individual inputs or operations; they are not a total memory, disk or job-time budget.

Validation

Compatibility warnings

Compatibility-warning coverage has substantially expanded. Relaxed validation reports selected conditions that strict validation would reject, indicating whether content was accepted, skipped or repaired in memory. These warnings are available through the CLI and structured API reports; --quiet suppresses CLI warnings.

Go callers can obtain the same ordered report through ValidateWithReport, ValidateFileWithReport and
ValidateContextWithReport. Existing error-only validation APIs remain available.

Warning coverage is partial and will expand over time. Some relaxed-validation fallbacks produce no notice, so silence
does not imply strict validation.

Strict validation describes the checks pdfcpu currently implements; it does not certify complete ISO 32000 compliance
or prove that no bounded low-level reader recovery occurred.

Expanded validation and malformed-input handling

Stronger validation and safer handling of malformed PDFs, including improved bounds checks, cycle detection and error reporting. Relaxed mode adds targeted compatibility exceptions while strict validation retains its requirements.

Signature-validation evidence

Signature validation now clearly separates integrity, certificate trust, revocation and timestamp evidence from the
overall local assessment. See the signature-validation guide for output examples,
supported checks and current limitations.

Distribution and constrained environments

The Go module now excludes samples and test fixtures while retaining all runtime resources (#1449).

This release prepares pdfcpu for container deployment; an official image is planned for v0.17.

Compatibility summary

  • Existing v0.15 and older file-backed configuration requires an explicit reset.
  • Long-running Go APIs require a non-nil context under their canonical names.
  • Validation and optimization APIs listed above require the final progress argument.
  • Strict validation may reject malformed structures that earlier releases did not check.
  • Relaxed compatibility warnings do not yet cover every pre-existing fallback.
  • Cancellation takes effect at checkpoints, so some operations may not stop immediately.

Fixed issues

#1407,
#1444,
#1449,
#1457,
#1460,
#1461,
#1465,
#1466,
#1467,
#1470,
#1472,
#1473,
#1474,
#1477,
#1479,
#1484,
#1485,
#1487,
#1492.

Assets 21
Loading