Cryptographic stamp (XAdES / ECDSA)

By Matheel, from ZATCA's specifications and SDK 3.4.8 · Updated

The ZATCA cryptographic stamp is an XAdES signature over the invoice using ECDSA on secp256k1 with the device's CSID key, proving origin and integrity.

ZATCA defines the cryptographic stamp as an electronic stamp created with cryptographic algorithms that ensures the invoice's origin, the integrity of its content and the identity of its issuer. Technically it is an enveloped XAdES-BES signature using ECDSA with SHA-256 on the secp256k1 curve, made with the private key of the device's CSID.

Location: ext:UBLExtensions/ext:UBLExtension/ext:ExtensionContent/sig:UBLDocumentSignatures/sac:SignatureInformation/ds:Signature, with a cac:Signature element in the invoice header pointing to it. It has two references: the invoice hash, and the hash of xades:SignedProperties (signing time and certificate details).

ZATCA's signature is not standard XMLDSig, and three quirks break most implementations: SignatureValue signs the raw bytes of the invoice hash, not SignedInfo; the SignedProperties and certificate digests are base64 of a hex string; and X509IssuerName uses .NET's reversed order. Rules BR-KSA-28, BR-KSA-29 and BR-KSA-30 check the identifiers and method, and BR-KSA-60 requires the stamp on simplified invoices. Standard invoices also get ZATCA's own stamp at clearance.

Matheel's stamp is built against ZATCA SDK 3.4.8 and matched to the SDK's samples in our tests; it signs every invoice with your device's certificate.

Example

<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
...
<cac:Signature>
    <cbc:ID>urn:oasis:names:specification:ubl:signature:Invoice</cbc:ID>
    <cbc:SignatureMethod>urn:oasis:names:specification:ubl:dsig:enveloped:xades</cbc:SignatureMethod>
</cac:Signature>

FAQ

Which curve does ZATCA use?

secp256k1, with ECDSA and SHA-256. The key is generated with the CSR when the device is onboarded.

Why does my signature verify in an XMLDSig library but ZATCA rejects it?

ZATCA signs the invoice hash itself rather than SignedInfo, and uses a different digest encoding for SignedProperties and the certificate.

Related ZATCA rules

Related terms

Let Matheel handle this for you

Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.

Try Matheel, no signup Matheel API docs