Signed Document Download and Verification Manual
Last updated
Was this helpful?
Last updated
Was this helpful?
X-ROAD 7
Version: 1.10 Doc. ID: UG-SIGDOC
18.06.2015
0.1
Initial version
Ilja Kromonov
03.07.2015
0.2
Corrections Kristo
Heero
19.08.2015
0.3
References updated
Kristo Heero
09.09.2015
1.0
Editorial changes made
Imbi Nõgisto
17.09.2015
1.1
Download URL of the asicverifier added
Kristo Heero
25.09.2015
1.2
„Forcing missing timestamps” added
Ilja Kromonov
15.02.2016
1.3
Parameter subsystemCode is mandatory also
Kristo Heero
02.05.2016
1.4
Signed documents are available by default 30 days.
Kristo Heero
03.11.2018
1.5
Convert from Word to Markdown. Asicverifier supports extracting messages when verification fails
Petteri Kivimäki
07.01.2019
1.6
Asicverifier version option. Updated asicverifier usage and jar name
Caro Hautamäki
07.03.2019
1.7
REST support modifications
Jarkko Hyöty
25.08.2021
1.8
Update X-Road references from version 6 to 7
Caro Hautamäki
03.09.2021
1.9
Minor updates
Ilkka Seppälä
08.10.2021
1.10
Updates about encryption
Jarkko Hyöty
This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/
Messages exchanged between the X-Road security servers are signed and encrypted. For every regular request and response, the security server produces a signed document. The signatures are time-stamped either synchronously, immediately after the message has been processed by the security server, or asynchronously in periodic batches for a better performance.
This document describes the retrieving and verification process of the signed and time-stamped document [PR-SIGDOC].
[PR-SIGDOC] Freudenthal, M. Profile for High-Perfomance Digital Signature. T-4-23, 2015. https://cyber.ee/research/reports/
[UG-SS] Security Server User Guide. Document ID: UG-SS
The security server offers the asic web service for downloading its signed documents. The service is used via HTTP GET requests to the service URL:
where SECURITYSERVER is the actual address of the security server.
Signed documents are available via the service until they are archived and removed from the message log database (by default 30 days). This time period is configurable in the security server (messagelog parameter keep-records-for). If messagelog parameter archive-encryption-enabled is true, the messages are returned in encrypted format (OpenPGP/GnuPG, see [UG-SS] for archive encryption details).
The service requires the identifier of the corresponding message and the X-Road client identifier to determine which signed documents to return. These can be provided with the following mandatory parameters:
queryId – the X-Road message transaction identifier, which is a part of the SOAP message header;
xRoadInstance – the X-Road instance of the client identifier;
memberClass – the member class of the client identifier;
memberCode – the member code of the client identifier;
subsystemCode – the subsystem code of the client identifier.
Thus, in order to retrieve the signed document for a message with transaction identifier abc12345 exchanged by security server sec1.gov by client EE/ENT/CLIENT1/SUB, the request URL is
If a message with the given identifier was indeed exchanged by the security server and by the specified client, the server would respond with a ZIP archive (content-type application/zip, filename queryId.zip), which contains signed documents for all requests and responses that match the specified parameters.
The signed documents provided by the asic service are named queryId-request-Z.asice[.gpg] and queryId-response-Z.asice.[gpg] for requests and responses, respectively, where queryId is the identifier (URL encoded) of the message and Z is a up to 13-character alphanumeric string. The .gpg suffix is added if the file is encrypted.
Should the user only desire the request or response then additional mutually exclusive parameters are available:
requestOnly – only include signed documents for request messages (response filename is queryId-request.zip[.gpg]);
responseOnly – only include signed documents for response messages (response filename is queryId-response.zip[.gpg]).
The aforementioned parameters make the service return a (possibly encrypted) ZIP archive, which may contain either one or more signed documents (depending if the provided queryId is unique). If only a single signed document is expected then the request can be further be constrained by adding the following parameter:
unique – specifies that the only a single signed document is expected in the response, must be used in combination with either requestOnly or responseOnly parameter.
If this parameter is used and, indeed, the query identifier is unique, then the security server responds with a single signed document (content-type application/vnd.etsi.asic-e+zip, or application/octet-stream if the archive is encrypted) which represents the corresponding message.
If the security server was configured to timestamp messages asynchronously it may be possible that there is no timestamp associated with one or more signatures of the requested documents. In this case the request will fail with an internal error and return an appropriate error message string - "Some message signatures have not been timestamped yet!" (or "Message signature has not been timestamped yet!" if requesting a single document only).
If this behavior is not desired the following parameter can be used:
force – specifies that the timestamping procedure should be executed explicitly in case any of the requested document signatures have no associated timestamps.
Thus, in order to retrieve the signed document for a message with transaction identifier abc12345 exchanged by the security server sec1.gov by the client EE/ENT/CLIENT1/SUB and force any missing timestamps to be created, the request URL is
Should there be no working time-stamping provider available to the security server, the signed document retrieval service will respond with the error message "Failed to get timestamp from any time-stamping providers".
In case the security server administrator has configured the connection between the service client and the security server to require authentication, requests to the asic service would need to be made via HTTPS.
The security server would need the certificate of the service client to be provided as part of the session, when the user makes the request to download a signed document for a message associated with this service client.
The asic service responds with the HTTP error code and plain text error message if error occurs. The possible error codes are:
400 Bad Request – the combination of received parameters is invalid or some required parameter is missing.
401 Unauthorized – the connection was made via HTTPS and the user failed to provide the correct certificate.
404 Not Found – no signed documents matching the provided parameters were found. Also, the signed document may be not time-stamped yet.
500 Internal Server Error – an unexpected internal error occurred (e.g., the provided service client identifier does not match any registered client on the security server).
Verification of signed documents is done by the asicverifier utility tool. The tool is written in the Java programming language and therefore requires Java 8 Runtime Environment (JRE) to be installed on the user's workstation. On Unix-like operating systems the JRE can be installed using package management software or downloaded from the Oracle website.
The asicverifier utility is shipped with security server and it is located in the following directory:
The asicverifier utility is run as follows:
where <signed document> is the path to the signed document being verified and <configuration path> is the path to the verification configuration for this container (see Section 3.2 ). You can check the version of the asicverifier tool with the --version option.
If verification is successful the output will be similar to:
As can be seen from the example above, the asicverifier tool will optionally extract the signed files to the working directory. In the case of REST message, the request/response line and headers are in message.xml and the REST body (if logged) is present in a file attachment1.
Should the verification fail, the reason for failure will be presented to the user in an error message. For example:
In case of verification failure, the asicverifier tool will optionally extract the signed files to the working directory.
Notice that when messagelog.message-body-logging property is set to false, the verification always fails with the error message:
The asicverifier tool requires the proper verification configuration containing certificates needed by the verification process. The verification configuration can be downloaded from the same security server by making a HTTP GET request to the URL:
where SECURITYSERVER is the actual address of the security server.
The verificationconf service has no parameters and responds with a ZIP archive (content-type application/zip, filename verificationconf.zip). This archive needs to be extracted and the location of it's contents used as an argument to the asicverifier tool.
A convenient way to download the verification configuration is with the web browser or use of the curl tool:
