ADoc Long-term signature validity with Documents Gateway and Documents API
For most document formats – PDFs, ASiCs, BDocs and EDocs – Dokobit integrated solutions ensure XAdES-XL and PAdES-LT level security. This is achieved by including the timestamp and the signature revocation data during the document signing. It means that e-signatures on your documents will be valid until it is officially announced that the used signing hash algorithms are no longer secure. The European Union Agency for Cybersecurity (ENISA) is responsible for announcing this information.
If you work with the ADoc document format in your integration, you must take additional actions to achieve the required e-signature security level.
Due to the ADOC-V1.0 specification, e-signatures are first created with the XAdES-T security level. Uplift to XAdES-XL can happen after a 24-hour grace period. It is the time period during which the certificate revocation information is propagated through the revocation process to relying parties. If the certificate is not revoked during the grace period, the e-signature is valid and can be uplifted to the XAdES-XL security level. The e-signature will then be valid until the expiration date of the timestamp certificate, which is usually 4 years.
Therefore, a mechanism for periodic timestamp renewal is required to ensure the long-term validity of ADoc e-signatures.
In this article:
Uplift ADoc e-signature levels with Documents Gateway
There are three options for preparing ADoc document's e-signatures for long-term validity with Documents Gateway:
Option 1
Use adoc[level]
attribute with xades-xl
value when initiating ADoc signing with POST /api/signing/create.json method.
After the 24 grace period, we will send the signing_archived
webhook to your provided postback_url
. The job runs once every hour.
{ "action": "signing_archived", "token": "ki6mi9j7rxget94kye2xwq6a38mzxwxdnzh3thmq", "status": "ok", "file": "https://gateway-sandbox.dokobit.com/api/signing/ki6mi9j7rxget94kye2xwq6a38mzxwxdnzh3thmq/download", "file_digest": "d969pnd8qxvynpm2xerx2c5ah7bcazjijgrve6q5mfj4bzwudtxpzavhejyjgzya", "valid_to": "2026-01-01T00:00:01+02:00", "additionalPostbackData": [] }
Webhook details will include the URL to download the signed ADoc with XAdES-XL security level and the expiration date of the timestamp certificate.
If your integration is not using postback_url
, you could check the status of the signing with GET /api/signing/{token}/status.json method not sooner than 24 hours after the ADoc document was signed.
You will find the URL to download the document with the XAdES-XL security level and the expiration date of the timestamp certificate.
Option 2
Use the POST /api/archive.json method no sooner than 24 hours after the ADoc document was signed.
The file can be uploaded through POST /api/file/upload.json request or provided as Base64 encoded file content.
After a successful request, you will receive the ADoc document with XAdES-XL and the expiration date of the timestamp certificate.
If the grace period has not passed, you will receive an exception together with an indication of the grace period end:
"Document can be archived only when grace period ends (24 hours).Your signature "META-INF/signatures/signatures0.xml#signature_0" timestamp is created on 2021-08-02T05:11:32+00:00. Grace period will end on 2021-08-03T05:11:32+00:00."<br>
Repeat the request after the grace period has ended, and the e-signature will be uplifted to the XAdES-XL security level.
Option 3
Use POST /api/signing/{token}/archive.json method if the signed ADoc document needs to be prepared for long term validity and it is available in Documents Gateway. You will receive a "signing_archived"
postback notification to the given postback URL. Information will be sent after the 24 hour grace period. The job runs once every hour.
The ADoc document can be downloaded from the URLs in the postback information or the GET /api/signing/{token}/status.json response. The expiration date of the timestamp certificate will also be indicated.
Uplift ADoc e-signature levels with Documents API
Documents API supports the POST /archive.json method. It can be used no sooner than 24 hours after the ADoc document was signed.
The signed ADoc should be provided as Base64 encoded file content. You will receive the ADoc document with XAdES-XL and the expiration date of the timestamp certificate in the response.
Periodic timestamp renewal
A few months before the timestamp certificate expiration date or a safe time according to your document storage requirements, use the POST /api/archive.json or POST /archive.json method to uplift the security level to XAdES-A.
Check and prepare incoming documents
If your document management system accepts signed documents from 3rd parties, it is crucial to ensure that the e-signatures are valid.
Documents Gateway can validate e-signatures by using the POST /api/file/check.json method. In the response, you will receive e-signature information, validation results and error messages informing you about any e-signature flaws.
By default, e-signatures are validated using the Qualified Electronic Signatures policy (qes
). This means that only Qualified Electronic Signatures will be accepted as valid.
Advanced Electronic Signatures and Advanced e-Seals can be accepted as valid when the validation_policy
attribute is added to your call with aes
value.
The same can be achieved with Documents API's POST /check.json method.
Responses from the POST /api/file/check.json and POST /check.json methods will also inform you about the timestamp certificate's expiration date.
You can use this information with POST /api/archive.json and POST /archive.json methods to help you prepare incoming document e-signatures for long-term validity.
POST /api/file/check.json and POST /check.json responses also provide an e-signature ID.
In some cases, you might need to uplift the level of a specific e-signature on the document. This can be done by providing the signatures[id]
attribute when calling POST /api/archive.json and POST /archive.json methods.