Signotaur signs PDF, XML and other data documents using the AdES family of advanced electronic signature formats. As with code signing, the private key never leaves the Signotaur server: the client sends only a digest, and the server signs it.
Use AdES rather than Authenticode or plain CMS when you are signing a document rather than software, and especially when the signature has to be checked by a document viewer such as Adobe Acrobat, or has to stay verifiable for years.
Producing a document signature needs a Signotaur server with an Enterprise licence: the same licence that unlocks the Managed CA features. Code signing works under a Standard licence, but document signing does not. See Licensing below.
There are three formats, one per kind of content. Two are chosen for you by file extension.
| Format | Signs | How it is selected |
|---|---|---|
| PAdES | PDF files | Automatically for .pdf |
| XAdES | XML files | Automatically for .xml |
| CAdES | Any other data: CSV, JSON, images, invoices, archives | Only with --format cades |
The default is --format Auto, which routes .xml to XAdES and .pdf to PAdES and leaves every other file to the usual code-signing pipeline. CAdES has no file extension of its own, so it can only be selected explicitly.
Setting --format to anything other than Auto forces that format for every input file, so --format cades CAdES-signs a .pdf too.
A signature can carry more than the signature itself. The --level (--lv) option chooses how much, in plain language. Each level includes everything below it.
--level |
Also accepts | What it adds | Needs |
|---|---|---|---|
baseline |
B |
The signature and the signer's certificate. The default. | Nothing |
timestamped |
T |
A trusted timestamp proving when the signature was made. | --timestamp-server |
long-term |
LT |
The certificate chain and revocation evidence, embedded in the signature. | --timestamp-server, and revocation data the signer can reach |
archival |
LTA |
An archival timestamp over the whole signature, so it survives the ageing of the earlier timestamps' algorithms. | As above |
Values are case-insensitive, and hyphens and underscores are ignored, so long-term, long_term and LONGTERM are all accepted.
Asking for timestamped or above without --timestamp-server is an error, and nothing is signed.
--level applies to whichever AdES format each file uses, and overrides the per-format --cades-level, --xades-level and --pades-level options. Prefer it: the per-format options exist for fine control and use ETSI spellings such as B_LT. On a non-AdES file such as an .exe, --level is ignored with a warning for that file.
The signature is written inside the PDF as an incremental update, so the original content is left byte-for-byte intact and the file keeps working in every reader.
sign against the PDF. No --format is needed.SignotaurTool.exe sign -a <APIKey> -s <SignServer> -t <Thumbprint> contract.pdf
For a timestamped signature:
SignotaurTool.exe sign -a <APIKey> -s <SignServer> -t <Thumbprint> ^
--level timestamped --tr http://timestamp.example.com contract.pdf
contract.pdf is rewritten with the signature appended. Keep a copy of the unsigned original if you need one.
By default the signature is invisible: it is present and verifiable, but nothing is drawn on the page. Add --pades-visible (--pv) to draw a signature appearance box.
SignotaurTool.exe sign -a <APIKey> -s <SignServer> -t <Thumbprint> ^
--pades-visible --pades-page 1 --pades-rect "36,36,220,64" ^
--pades-reason "Approved for release" --pades-location "London, UK" ^
contract.pdf
| Option | Default | Notes |
|---|---|---|
--pades-visible (--pv) |
Off | Draws the appearance box. |
--pades-page (--pp) |
1 |
The page to draw on, counting from 1. |
--pades-rect (--pr) |
36,36,220,64 |
The box as "x,y,width,height" in PDF points, measured from the bottom-left corner of the page. |
--pades-reason (--prsn) |
None | Reason text drawn in the box. |
--pades-location (--ploc) |
None | Location text drawn in the box. |
--pades-font (--pfont) |
None | Path to a TrueType or OpenType font to embed. Required for text outside the Latin-1 character set. |
--pades-image (--pimg) |
None | Path to a JPEG or PNG drawn in the box, such as a logo. |
To sign a PDF protected by the standard security handler, supply its open password with --pades-password (--ppwd).
--pades-xref (--px) controls how the incremental update writes its cross-reference: Auto (the default) matches whatever the original PDF used, Classic always writes a table, and Stream always writes a cross-reference stream. Leave it on Auto unless a downstream tool insists.
An .xml file is signed as XAdES automatically. There are three placements, chosen with --xades-placement (--xp):
| Placement | Result | Output |
|---|---|---|
Enveloped (default) |
The signature is added inside the XML document, alongside the content it signs. | The .xml is rewritten in place. |
Enveloping |
A copy of the XML content is wrapped inside the signature. | The .xml is rewritten in place. |
Detached |
The signature is a separate document that refers to the content by name. | <file>.sig is written; the original is untouched. |
--detached also selects the detached placement, so you rarely need --xades-placement directly.
SignotaurTool.exe sign -a <APIKey> -s <SignServer> -t <Thumbprint> invoice.xml
Each run produces one signature. Signing an already-signed XML file replaces rather than adds.
CAdES signs any file as opaque bytes. Select it with --format cades.
--cades-mode (--cm) |
Result | Output |
|---|---|---|
Detached (default) |
The content stays in the original file. | A .p7s signature file beside it; the original is untouched. |
Enveloping |
A copy of the content is carried inside the signature. | A single new file with the .p7m extension. |
--cades-encoding (--ce) chooses Der (binary, the default, and what e-invoicing and archival workflows usually require) or Base64 (text, convenient inside an XML or JSON envelope).
SignotaurTool.exe sign -a <APIKey> -s <SignServer> -t <Thumbprint> ^
--format cades --level long-term --tr http://timestamp.example.com invoice.csv
--signature-file (--sf) overrides where a detached signature is written, and accepts the {name}, {name-no-ext} and {rel-path} placeholders for batch signing. See the sign command.
At sign time Signotaur checks the certificate's Enhanced Key Usage (EKU) extension against what is being signed. Signing a document format requires a usage that covers document signing: the Microsoft, Adobe or RFC 9336 document-signing OID, or Email Protection. If the certificate has none of them, nothing is signed and the run ends with exit code 34.
Email Protection counts because it was the usual marking for document signing before RFC 9336 defined a dedicated usage, and Adobe Acrobat still accepts it from a signer. See Document-Signing Certificates.
A certificate with no EKU extension, or with the Any Purpose usage, is treated as valid for every purpose and therefore always passes this check.
If a certificate is refused, the message lists its permitted usages, so you do not need to inspect the certificate yourself. To sign anyway, use --warn-wrong-purpose (--wp) to turn the refusal into a warning.
The check applies in both directions. For example, signing an .exe with a certificate that permits only document signing is also refused.
Apple configuration and provisioning profiles (.mobileconfig, .mobileprovision, .provisionprofile) are the exception: their signature asserts no particular purpose, so either a code-signing or a document-signing certificate is accepted, and only a certificate marked for neither is refused. A batch mixing a profile with an .exe is still judged by the stricter file.
A certificate with no EKU extension normally passes for any format. The exception is a certificate whose Key Usage extension permits Non-Repudiation but not Digital Signature. This is the ETSI document-signing profile: it permits document signing, but its key is not authorised to sign software.
A basic signature proves who signed the content and that it has not changed. By itself, however, it does not preserve enough evidence to prove that the signing certificate was valid and unrevoked at the time of signing.
A long-term signature embeds this evidence:
An archival signature also timestamps the complete signature package. This protects the embedded evidence as the algorithms used by earlier signatures and timestamps age.
Signotaur collects the evidence while signing. It prefers OCSP and falls back to a CRL. Where it can retrieve neither, it displays a warning naming the certificate but still signs. The resulting signature is valid, but lacks the embedded evidence needed for reliable offline verification or verification after the signing certificate expires.
Signotaur may be unable to retrieve revocation data because:
--allow-untrusted-crl to accept the certificate for that signing run. It applies to signing only: verification has no equivalent option, because that check runs through the operating system's own certificate handling. The preferred solution is for the CA to publish over plain http://.If signatures will be verified outside your network, their revocation addresses must also be accessible from outside the network.
Document signing requires a Signotaur server with an Enterprise licence. Code signing works under a Standard licence, but a Standard server refuses to document-sign.
The client asks the server whether document signing is permitted and fails closed. It produces a document signature only when the server explicitly confirms it may. A server too old to report the capability is treated exactly like one without an Enterprise licence, so upgrade the server if its licence already covers document signing.
When a run is refused:
87 (DocumentSigningNotLicensed).The server enforces the same rule at the signing endpoint itself, answering with HTTP 423 (Locked), so the gate also holds for REST and gRPC integrations and for a dual-purpose certificate the client would otherwise accept.
See Editions & Licensing.
No extra option is needed. verify detects an AdES signature from the file itself: a signed .pdf verifies as PAdES, a .sig sidecar or a signed .xml as XAdES, and a .p7m as CAdES.
SignotaurTool.exe verify contract.pdf invoice.xml invoice.csv.p7s
See the verify command.
PAdES has no detached form: a PDF signature can only live inside the PDF. So under --format Auto, a .pdf in a batch that requests detached output (through --detached or --signature-file) is not signed as PAdES at all. Instead:
--level, it is written as a detached CAdES .p7s over the file's bytes;.p7s.Either way the client warns that no PDF reader will show a signature. Drop the detached request if you want an embedded, viewer-visible PAdES signature.
Combining --detached with an explicit --format pades is a straight error rather than a downgrade, because there is no sensible way to honour it.
How much a signature is worth to whoever receives it depends on the certificate you sign with, not on Signotaur. Signotaur signs with whatever registered certificate you choose, and it accepts certificates from any issuer. Two separate things follow from that choice, and they are easy to confuse.
Trusted means the viewer recognises the certificate's issuer and shows the signature as valid, rather than warning about an unknown signer. A certificate from a publicly trusted or Adobe-approved CA gives you this on machines you do not control. A certificate from the Internal CA gives you the same thing inside your own organisation, once you distribute the root to the machines that verify the signatures.
Qualified is a specific legal status under the EU eIDAS regulation, and it is not something a trusted certificate alone confers.
A qualified electronic signature (QES) requires both a qualified certificate, issued by a qualified trust service provider listed on an EU Member State Trusted List, and a qualified signature creation device. Signotaur supplies neither: it is not a qualified trust service provider, and it is not a certified qualified signature creation device.
Signotaur also holds the signing key on the server rather than in the signatory's personal possession. Whether a particular arrangement meets eIDAS's sole-control requirement is a question for your trust service provider and your own legal advice, not one this documentation can answer.
Do not present a Signotaur signature as legally equivalent to a qualified signature. If you need qualified signatures, speak to a qualified trust service provider about their remote signing service.
Certificates issued by Signotaur's own Internal CA are a further step removed: they are self-asserted, carry no external audit, and appear on no public trust list. They are the right choice for signing inside an organisation that distributes its own root, and the wrong choice for documents sent to people outside it.