The Human-Readable Signature: Inside duplicati/jsonsignature

How a zero-dependency C# library uses stream concatenation and JSON comments to bypass the complexity of JWS.

6 min read • View on GitHub • More from duplicati

A split illustration showing a frustrated archivist looking at an opaque stone block on the left, and happily reading a clear paper ledger with a wax seal on the right. — The core tension of signed JSON is readability versus security.

Key Takeaways

The standard JSON Web Signature protocol destroys human readability by wrapping payloads in Base64 envelopes.
The duplicati/jsonsignature library implements SIGJSON to embed cryptographic signatures inside standard JSON comments.
A custom stream concatenator allows the library to sign gigabyte-scale configuration files with near-zero memory overhead.

The Base64 Envelope Problem

Developers love JSON because they can open it in a text editor and immediately understand the configuration. But securing that file against tampering usually means adopting JSON Web Signatures. JWS encodes the payload into a massive Base64 string. The developer loses the ability to quickly audit or debug the file visually.

The Pragmatic Comment Hack

Instead of wrapping the document, the jsonsignature library simply prepends a signature as a standard code comment. Standard JSON parsers either ignore comments or can be configured to do so. The underlying data remains perfectly intact and human-readable.

//SIGJSONv1: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
{
  "backup_target": "s3://my-bucket",
  "retention_days": 30
}

The Architecture of the Virtual Stream

Appending a comment to a small file is easy. Prepending a signature to a 20-gigabyte backup configuration file without triggering an OutOfMemoryException is hard. The library solves this with a custom System.IO.Stream implementation that queues multiple streams and reads them sequentially.

The CombinedStream architecture projects the illusion of a single contiguous file without loading the bulk data into RAM.

Zero-Dependency Performance

The library relies solely on the standard System.Security.Cryptography namespace. It pre-calculates Base64 headers to avoid repeated string allocation during rapid stream scanning. This makes it ideal for the Duplicati backup engine.

Feature	JWS Standard	SIGJSON (jsonsignature)	Raw HMAC
Human Readable	No	Yes	Yes (if detached)
Memory Overhead (Large Files)	High	Near Zero	Variable
Language Support	Universal	C# (.NET)	Universal