openSzigno
A safe, agent-friendly command-line tool for inspecting, listing, structurally
validating, verifying, extracting, creating, signing, and timestamping
Hungarian Microsec e-Szignó e-dossiers (.es3).
Security boundary:
openszigno verifychecks XMLDSig canonicalization, reference digests, signature values, the e-dossier reference-scope rules, the XAdES signedSigningCertificatebinding, RFC 3161 signature timestamps, certificate paths, and revocation, all against trust material you supply. It reports a signaturevalidonly when every check it makes passed at the stated validation time; short of that the verdict isindeterminate, which means "nothing failed", not "this is trustworthy". No command determines a document's legal effect, and parsing or extracting a dossier is never evidence that it is authentic, signed, or legally valid.
Why and for whom
.es3 dossiers are XML containers that arrive from untrusted parties and are
usually opened with a desktop application. openSzigno is the other option: a
single binary that reads a dossier, verifies its signatures against material
you choose, and writes the payloads to disk without trusting the input.
- Agents and automation. Every command accepts
--jsonand emits exactly one JSON object on stdout, with a stable envelope, stable error and warning codes, and stable exit statuses. Diagnostics go to stderr and never contaminate stdout. - People. Without
--jsonthe same commands print short, readable terminal output that always states the verification boundary.inspectandlistreport the dossier's own account of itself and verify nothing, which is why their output carries"verified": false;verifyis the only command that gives a cryptographic answer. - Hostile input. Input is bounded at every stage: file size, XML depth and node count, Base64 length, decoded payload size, ZIP member count and compression ratio, aggregate extraction size. DTDs and entity declarations are rejected outright, and extraction never overwrites an existing file or follows a symlink out of the output directory.
Installation
Every channel ships the same binary, openszigno. Prebuilt archives cover
five targets and carry SHA-256 checksums.
# Homebrew, on macOS and Linuxbrew
# Cargo: the prebuilt archive, or a build from source (Rust 1.88 or newer)
Shell and PowerShell installers, for a machine with no Rust toolchain:
|
powershell -ExecutionPolicy Bypass -c "irm https://github.com/watt-mind/openSzigno/releases/download/v0.9.0/openszigno-cli-installer.ps1 | iex"
Container image (linux/amd64 and linux/arm64), for CI and sandboxed
pipelines. It is FROM scratch and runs as the numeric user 65532:
Otherwise take an archive and the .sha256 file beside it from the
releases page, check it
with sha256sum --check, and unpack it. See
docs/releasing.md for how releases are produced.
Quick start
Human mode. openszigno list tests/fixtures/plain-base64.es3 prints:
Unsigned synthetic plain fixture
[0] hello.txt | text/plain | 41 B | ["base64"]
Signatures/timestamps are listed by presence only; none were verified.
Agent mode. openszigno inspect tests/fixtures/plain-base64.es3 --json
writes one compact object; this one is pretty-printed and trimmed:
Verification. A run needs trust material you supply, here a trust store
holding the repository's own synthetic anchor, and --at to pin the
validation time:
Verification verdict: indeterminate
Validation time: 2027-01-01T00:00:00Z
Signatures: 1
...
[0] document signature: indeterminate
validation time: 2027-01-01T00:00:00Z (source: at_flag)
...
signature_value_ok: passed
xades_absent: skipped
...
cert_path_ok: passed
...
revocation_status_unknown: unknown
Revocation policy: offline. A verdict of `valid` means every check passed at the stated validation time; it is not a legal opinion.
Exit status 7: nothing failed, but this fixture carries no XAdES properties,
no signature timestamp and no revocation data, so nothing reaches valid.
Adding --online would let the run fetch the revocation data it lacks from
the URLs the certificates themselves publish.
Commands
| Command | Purpose | Exit statuses |
|---|---|---|
inspect FILE |
Identify the dossier and report its metadata, the unverified signature inventory, the active limits, and capability flags. | 0, 2, 3, 4 |
list FILE |
List document records in source XML order, with type, size, OBJREF, and transform chain. |
0, 2, 3, 4 |
validate-structure FILE |
Apply the strict structural rules and report valid_structure and any conformance warnings. |
0, 2, 3, 4 |
extract FILE --output DIR |
Decode supported payloads into DIR, expanding embedded dossiers, never overwriting a file. --document SEL --stdout writes one payload to stdout instead. |
0, 2, 3, 4, 5 |
verify FILE |
Verify every ds:Signature against the trust material you supply and report a per-signature verdict of valid, invalid, or indeterminate. |
0, 2, 3, 4, 6, 7 |
create --output FILE --title TITLE |
Build one new, unsigned dossier from files on disk, with --document, --zip, --embed, --encrypt-for, and --created. Never overwrites the output. |
0, 2, 3, 4, 5 |
sign FILE --output FILE --key KEY |
Write a signed copy of a dossier: one enveloped XMLDSig/XAdES signature per document, or one over the dossier with --scope dossier, optionally timestamped with --tsa, and with --csc instead of --key signed by a remote qualified certificate. Never overwrites the output. |
0, 2, 3, 4, 5 |
timestamp FILE --output FILE --tsa URL |
Write a copy of a dossier carrying a container es:TimeStamp: an RFC 3161 token over the dossier, or over each selected document with --scope document, and no signature. Never overwrites the output. |
0, 2, 3, 4, 5 |
csc login CONFIG.toml |
Run the OAuth 2.0 authorization-code round a Cloud Signature Consortium service needs and store the tokens sign --csc reads. Prints one URL, waits for the browser on a loopback listener, and prints no token. |
0, 2, 3, 4, 5 |
skill |
Write the embedded agent skill (SKILL.md) to stdout and nothing else. Takes no FILE and no --json. |
0, 2, 3 |
create is the writing side: it builds a new dossier from files on disk,
in the shape this tool reads back, and does nothing else to it. The output
is deterministic, so the same inputs with the same --created produce a
byte-identical file; every limit that bounds reading bounds writing too; an
existing output file is an error rather than an overwrite; and the dossier
it writes carries no signature, which every run says out loud.
--encrypt-for CERT.pem encrypts every --document payload for that
recipient certificate as CMS EnvelopedData, which extract --decrypt-key
reads back; it is the one thing that makes the output non-deterministic,
because a content key must be random. Signing a dossier is sign, below,
and timestamp writes a container es:TimeStamp over a dossier without
signing it: one RFC 3161 token, no key of any kind, refused rather than
written where it would break something already in the file. See
The timestamp command.
Every command except create, csc login and skill takes - in place of
the path and reads the dossier from standard input. Every flag, the JSON
envelope, the stable error, warning and check codes, the exit statuses, and
the parser limits are specified in docs/architecture.md.
Verification
verify reports valid only when every check it makes passed at the stated
validation time, which needs a trust anchor, a fully verified signature
timestamp, and fresh revocation data for every certificate in the chains;
anything missing yields indeterminate. You supply that material yourself:
--trust-store for anchors, --trust-list and --lotl with
--trust-list-signer for ETSI TS 119 612 lists, --revocation-store for CRLs
and OCSP responses. --online is the only thing that makes openSzigno touch
the network, and then only for the CRL and OCSP URLs published by certificates
on a path to a configured anchor, under fixed timeouts and size caps, with
loopback, private and cloud-metadata destinations refused; trust material is
never fetched. docs/trust.md explains how to obtain, pin, and
lay out all of it.
Signing
sign is the other writing side: it takes a dossier and a key you supply and
writes a signed copy, with the reference scope, the XAdES signed properties
and the placement verify requires, and optionally an RFC 3161 timestamp from
a --tsa you name. The key, its certificate and its passphrase come from
files, never from the command line.
--csc CONFIG.toml signs through a Cloud Signature Consortium API v2 service
instead of a local key, so a qualified certificate held by a remote signature
creation device signs the same structure and only the digest ever leaves the
machine; see
Signing through a CSC service.
Run openszigno csc login CONFIG.toml first: it completes the OAuth 2.0
authorization-code round with PKCE on a loopback redirect, stores the token
chmod 600 where the configuration says, and refreshes it later rather than
letting it expire mid-run.
Writing is not verification. sign produces a signature and checks
nothing: not the key, not the certificate, not the chain, and it says so on
every run, and timestamp says the same about the token it embeds.
Whether what either wrote holds is a question for verify, against
trust material you supply; and a valid verdict over a chain you built
yourself means only that the chain you chose to trust verified. It is not a
statement about anybody's identity, not a legal opinion, and not a qualified
electronic signature: a qualified signature needs a key on a qualified device,
which by construction is not a key this process can hold. See
docs/remote-signing.md.
Documentation
-
Documentation index, which lists everything else
-
Agent skill: how an AI agent should drive the CLI to inspect, extract, decrypt, sign and verify dossiers. The binary carries it, so no checkout is needed to install it:
Use
.codex/skills/openszigno/for Codex, or~/.claude/skills/openszigno/to install it for every project instead of one.
Contributing
develop is the default integration branch and master is the stable one, so
open pull requests against develop. CONTRIBUTING.md has
the branch model, commit conventions, and required checks;
SECURITY.md has the threat model and how to report a
vulnerability.
LEGAL
openSzigno independently implements the publicly documented Microsec e-dossier format for interoperability, so that users can inspect and process their own documents with an open-source tool.
EU copyright law distinguishes a program's protected expression from its functionality and underlying ideas. In SAS Institute v World Programming (C-406/10), the Court of Justice held that functionality and data-file formats are not, as such, protected by copyright in computer programs. That supports independent compatible implementations; it is not permission to copy another program's source code or documentation. Third-party specifications, schemas, reference documents, and software remain subject to their own rights and licenses: public availability does not itself grant redistribution rights, and this project's MIT license does not relicense third-party material.
This is general information, not legal advice or a guarantee of legal clearance in any jurisdiction. As the security boundary above states, openSzigno does not determine a document's legal effect and is not a certified validation service; see the verification boundary.
License and trademarks
Licensed under the MIT License; test fixtures under
tests/fixtures/ are dedicated under CC0-1.0. e-Szignó, Microsec, and
related marks belong to their respective owners. openSzigno is an independent
project, maintained by Watt-Mind, and is not affiliated with, endorsed by, or
certified by Microsec.