Document Signature Creation

Page describes the the algorithm and shows examples of how signatures for documents submitted should be created.

Process

The overall steps to take when preparing a single document for submission are:

  1. Create document XML or JSON (no signature element yet) for a single document
  2. Create canonical version of the XML or JSON as per algorithm described
  3. Apply sha256 hash on the byte array created from canonical version byte array (using UTF-8)
  4. Sign the hash created using CADES-BES signature (for some implementations like SignedCMS in .NET previous step and this one are done together as part of SignedCMS signing)
  5. Include Base64 encoded CADES-BES signature into original document XML or document JSON in a new element.

Note that to ensure data transfer over network, potential newline symbols or spaces added removed between XML and JSON elements are not changing the signature value, the solution leverages specialized data document canonicalization approach to ensure only significant data (names and values of fields) is used as part of the signature. The algorithm to implement when serializing data to get hash code to sign is described in Document Serialization Approach.

Once multiple documents are prepared as per description above they all need to be added into documents array when JSON is used and into submission/documents element when XML is used. After that the submission is ready to be sent to the e-Invoicing solution by calling Document Submission API.

Step by Step Examples

When going through the process steps defined results of the steps should look as shown in these examples:

  1. After preparing the source document for submission it should look as shown in these examples for JSON and XML.
  2. After creating canonical versions of each document, they should look as shown in these examples for JSON and XML.
  3. After applying hashing of the serialized document 32 byte hash value should be received for the document.
  4. After signing the hash value using eSeal certificate and creating CADES-BES signature it should have structure similar to this parsed structure. Note that parsed structure shows the contents of the CADES-BES, but actual structure is binary ASN.1 encoded block of data.
  5. After including signature data into original document content you should get files similar to these examples for JSON and XML.