XML signing is a process that involves adding a digital signature to an XML document to ensure its integrity, authenticity, and non-repudiation. By applying a digital signature to an XML document, the signer attests to the authenticity and integrity of the data, making it possible to verify the document’s origin and ensure that it has not been altered during transit or storage.
The digital signature is created using asymmetric encryption techniques, typically based on public-key infrastructure (PKI). The signer generates a private key that is kept securely and a corresponding public key that can be shared with others. The private key is used to encrypt a hash or digest of the XML document, creating the digital signature. The encrypted digest serves as a unique representation of the data and is appended to the XML document.
XML signing is crucial in various domains, including e-commerce, electronic invoicing, supply chain management, and government applications. It enables secure electronic document exchanges, establishes the authenticity of data, and ensures non-repudiation, meaning that the signer cannot later deny their involvement or the integrity of the document.
An Overview of the XML signing process:
- A suitable cryptographic algorithm, such as RSA, DSA, or ECDSA, is chosen by the XML signer to produce the digital signature.
- The XML document to be signed is prepared. This involves ensuring that the document adheres to the required XML syntax and structure.
- XML canonicalization is applied to the document, which ensures that any variations in whitespace, attribute order, or namespace prefixes do not affect the validity of the signature. Canonicalization produces a standardized form of the XML document for signing.
- A digest, also known as a hash, is calculated over the canonicalized XML document. The digest serves as a unique fingerprint of the document and is used in the signing process.
- The digest is encrypted with the private key of the signer, creating the digital signature. The private key is kept securely by the signer and should not be accessible to unauthorized parties.
- The digital signature is inserted into the XML document, typically as an additional element or attribute. This allows the signature to be associated with the signed data.
Encryption Consulting has a CodeSigning solution, “CodeSign Secure,” which can help you with tamper-proof storage for the keys and complete visibility and control of Code Signing activities. The private keys of the code-signing certificate can be stored in an HSM to eliminate the risks associated with stolen, corrupted, or misused keys. Within this solution we offer a utility tool, XML Signer, which can sign XML files. The steps listed below will assist you with using our tool with ease.
Signing an XML file with XML Signer, in short: set the SSL client authentication certificate environment variables, then run
xmlsigner -S <file> -u <username> -k <key_name> -a <algorithm> -c <certificate>. The tool produces a signed copy with a “_signed” suffix; the private key stays server-side and is never handled directly by the CLI.
Key Takeaways
- SHA256 is the default hashing algorithm if
-ais omitted; SHA224 is a weaker option included for compatibility and generally shouldn’t be preferred for new signing workflows. - The SSL client authentication certificate authenticates the CLI to the Encryption Consulting signing server; it is a separate credential from the code signing certificate/key used to actually sign the XML document.
Environment Matrix
| Component | Requirement |
|---|---|
| OS | Windows, macOS, or Linux (xmlsigner.exe on Windows, ./xmlsigner elsewhere) |
| Client authentication | SSL Client Authentication Certificate in PKCS12 format (.p12 or .pfx), obtained from Encryption Consulting |
| Signing credentials | A registered username, key name, and certificate provided by Encryption Consulting |
| Supported hash algorithms | SHA224, SHA256 (default), SHA384, SHA512 |
| Key storage | Server-side; the CLI never handles the raw private key directly |
Prerequisite
In order to use XML Signer, the users must first set environment variables for the SSL Client Authentication Certificate path and certificate password. Ask the Encryption Consulting team if you don’t already have it.
Note: SSL Client Authentication Certificate should be in the PKCS12 format (.p12 or .pfx)
Execute the below commands to set environment variables:
Mac or Linux
$ export SIGNER_SSL_CERT_PFX=path_to_ssl_certificate
$ export SIGNER_SSL_CERT_PFX_PASS=your_client_certificate_password
Windows
$ set SIGNER_SSL_CERT_PFX=path_to_ssl_certificate
$ set SIGNER_SSL_CERT_PFX_PASS=your_client_certificate_password
How to use the XML Signer utility?
Get the version of the XML Signer Utility
Execute the below command
Mac or Linux
$./xmlsigner -v
Windows
$ xmlsigner.exe -v
Get the help of the XML Signer Utility
Execute the below command
Mac or Linux
$./xmlsigner -h or $./xmlsigner --help
Windows
$ xmlsigner.exe -h or $ xmlsigner.exe --help
Sign an XML Document
The Signer utility will generate the signed document with the same name with the postfix “_signed”
Use the sign subcommand to sign an XML document
./xmlsigner -S <file_to_be_signed> -u <user_name> -k <key_name> -a <algorithm> -c <key_certificate> -q
-S: XML document to be signed.
-u: User name. A user name on Encryption Consulting server. Ask the Encryption Consulting team if you don’t already have it.
-k: Key/certificate name for signing/verification provided by Encryption Consulting server. Ask the Encryption Consulting team if you don’t already have it.
-a: Algorithm to be used for signing. One of the following options should be used:
- SHA224
- SHA256 (Default)
- SHA384
- SHA512
If the Algorithm is not provided, it will use SHA256 as a default.
-c: Certificate file provided by Encryption Consulting server.
-q: Execute quietly.
-h: Display help
Examples
Mac or Linux
./xmlsigner -h
./xmlsigner -S file.xml -u admin -k SignCertificateName -a SHA256 -c
<path /to/certificate>
Windows
xmlsigner.exe -h
xmlsigner.exe -S file.xml -u admin -k SignCertificateName -a SHA256 -c
<path /to/certificate>
Verifying the Signature
After signing, confirm the output file (with the “_signed” suffix) contains a valid Signature element before distributing it. Open the signed XML and check for a <Signature> element under the XML-DSig namespace (http://www.w3.org/2000/09/xmldsig#) containing SignedInfo, SignatureValue, and KeyInfo child elements; a missing or malformed Signature block indicates the signing step failed silently rather than succeeded quietly.
Common Errors
| Error | Likely Cause | Fix |
|---|---|---|
| Authentication failure connecting to signing server | SIGNER_SSL_CERT_PFX or SIGNER_SSL_CERT_PFX_PASS environment variables not set, incorrect, or the .p12/.pfx file path is wrong | Re-verify both environment variables are exported in the current shell session, not just set in a script that hasn’t been sourced |
| Key/certificate not found | The value passed to -k doesn’t match a key name registered on the Encryption Consulting server for that username | Confirm the exact key name with the Encryption Consulting team rather than guessing a name |
| Invalid XML / signing fails on the input file | The input file isn’t well-formed XML, or canonicalization fails due to malformed namespaces | Validate the XML is well-formed before signing; malformed XML will not canonicalize correctly regardless of signing tool |
CI/CD Use and Cleanup
For repeated signing in a pipeline, set the SIGNER_SSL_CERT_PFX and SIGNER_SSL_CERT_PFX_PASS environment variables as pipeline secrets rather than hardcoding them in a script, and invoke xmlsigner with the -q flag for quiet, non-interactive execution. Verify idempotency by checking for the expected <Signature> element in the output file immediately after signing and failing the build if it’s absent, rather than assuming the command’s exit code alone confirms success.
For cleanup: if the .p12/.pfx client authentication certificate was copied to a build agent for testing, remove it once the pipeline is confirmed working, and prefer injecting it as a pipeline secret at runtime rather than storing it on the agent’s filesystem long-term.
Frequently Asked Questions
How do I know the signing command actually produced a valid signature?
Check the “_signed” output file for a well-formed <Signature> element under the XML-DSig namespace with SignedInfo, SignatureValue, and KeyInfo present, rather than assuming a zero exit code alone means the signature is valid.
What’s the difference between the SSL client authentication certificate and the signing certificate?
The SSL client certificate (PKCS12/.p12/.pfx) authenticates the CLI tool to the Encryption Consulting signing server. The actual code signing key used to produce the XML signature is a separate, server-managed credential referenced by the -k key name.
Conclusion
XML signing ensures the integrity, authenticity, and non-repudiation of XML documents. It adds a digital signature that verifies the document’s origin and prevents tampering. XML signing is essential for secure data exchange, fostering trust in electronic transactions and reliable communication. It finds applications in e-commerce, invoicing, supply chain management, and more. By using tools and libraries, the XML signing process is simplified and can be integrated into various environments. To get your hands on our tool which can help you with XML Signing process please contact us on [email protected]
