Digital Certicates verifier, RESTful Web services API

[EN] User Manual

“X.509 verifier” is a RESTful Web service that can serve to validate the X.509 certificates and signed PDF files as well as to check compliance of the contents of certificates with the Republic of Serbia legislative.

“X.509 verifier” RESTful Web service consists of 2 REST APIs located on the host:

Description of the HTTP server request

RANDOM_STRING_BOUNDARY is a string which needs to have a different and, if possible, a unique value on every new request. For example, in JavaScript, good practice for acquiring RANDOM_STRING_BOUNDARY would be:

var boundary = Math.random().toString().substr(2);

[FILE_BINARY_DATA] is a binary content of the chosen ‘file_name.pem’ file.

[JSON_ENCODED_PARAMETERS] are JSON encoded parameters which have to fulfil following format:

{

“operation”: “verify”,

“user_id”: 123,

“security_token”: “”

}

and the good practice is to this JSON encoded string don’t contains whitespace characters i.e. to be formed, in JavaScript, for example, using the following code:

var params, json;

params= { operation: “verify”, user_id: 123, security_token: “” };

json = JSON.stringify(params);

Parameters are:

“operation”: “verify” – Operation “verify” is the only operation currently supported.

“user_id”: 123 – numeric parameter, integer type, represent the user identification number (it is not utilised in API version 1.0 but it is mandatory and reserved for the future use). In API version 1.0 can be 0.

“security_token”: “” – string which should contain pairs of the hexadecimal digits without a so called delimiter (it is not utilised in API version 1.0 but it is mandatory and reserved for the future use). In API version 1.0 can be an empty string.

Anyway, in JavaScript it is not necessary to directly manage the Content, i.e. HTTP body. We recommend using of the FormData class as in example which you can download from the git repository on the following URL:

{“status”:”STATUS_STRING”,”msg”:”MESSAGE_STRING”}

HTTP/1.1 200 OK

…

Content-Type: application/json

{“status”:”Error: wrong POST parameters.”,”msg”:””}

If the verification is successful, STATUS_STRING must be:

“OK”

while the MESSAGE_STRING will contain a validly formatted record, which contains html formatting tags, as well as html tags for a new line, so this message can be directly placed in any html container (eg <div>).

Any response whose STATUS_STRING is different from “OK” is counted as a check whose result is unsuccessful and, in this case, if STATUS_STRING is different from the “Error: wrong POST parameters.”, MESSAGE_STRING will contain details of the certificate scrutiny that should be displayed.

REST API: pdf-sgn-verifier

API version: 1.0

PDF file, whose contents must be signed PDF document, is sent to this API. Signature formats can be “PKCS#7 – Detached” or “CAdES Equivalent”. After checking signed file, the API returns result of the verification in the JSON encoded string.

Description of the HTTP server request

RANDOM_STRING_BOUNDARY is a string which needs to have a different and, if possible, a unique value on every new request. For example, in JavaScript, good practice for acquiring RANDOM_STRING_BOUNDARY would be:

var boundary = Math.random().toString().substr(2);

[FILE_BINARY_DATA] is a binary content of the chosen ‘file_name.pdf’ file.

[JSON_ENCODED_PARAMETERS] are JSON encoded parameters which have to fulfil following format:

{

“operation”: “verify”,

“user_id”: 123,

“security_token”: “”

}

and the good practice is to this JSON encoded string don’t contains whitespace characters i.e. to be formed, in JavaScript, for example, using the following code:

var params, json;

params= { operation: “verify”, user_id: 123, security_token: “” };

json = JSON.stringify(params);

Parameters are:

“operation”: “verify” – Operation “verify” is the only operation currently supported.

“user_id”: 123 – numeric parameter, integer type, represent the user identification number (it is not utilised in API version 1.0 but it is mandatory and reserved for the future use). In API version 1.0 can be 0.

“security_token”: “” – string which should contain pairs of the hexadecimal digits without so called delimiter (it is not utilised in API version 1.0 but it is mandatory and reserved for the future use). In API version 1.0 can be an empty string.

Anyway, in JavaScript it is not necessary to directly manage the Content, i.e. HTTP body. We recommend using of the FormData class as in example which you can download from the git repository on the following URL:

HTTP Server Response

After verification of the PDF file and contains signature, server will return JSON encoded string which (in API version 1.0) contains 2 arguments:

{“status”:”STATUS_STRING”,”msg”:”MESSAGE_STRING”}

On invalid request, server response will be:

HTTP/1.1 200 OK

…

Content-Type: application/json

{“status”:”Error: wrong POST parameters.”,”msg”:””}

If the verification is successful, STATUS_STRING must be:

“PDF Signature is VALID”

while the MESSAGE_STRING will contain a validly formatted record, which contains html formatting tags, as well as html tags for a new line, so this message can be directly placed in any html container (eg <div>).

In contrary to the x509-verifier API, here we have responses with STATUS_STRING different from the “PDF Signature is VALID”, which counted as a unsuccessful verification result but in these cases MESSAGE_STRING doesn’t contain details. These are the cases when:

STATUS_STRING = “Info: PDF file doesn’t contain digital signature”

STATUS_STRING = “Digital signature validation FAILED”

meaning that is verification of the PDF file and contains signature entirely completed but the result is unsuccessful. In this case the MESSAGE_STRING always contain details of the scrutiny that should be displayed. In this case MESSAGE_STRING will contain a validly formatted record, which contains html formatting tags, as well as html tags for a new line, so this message can be directly placed in any html container (eg <div>).

The accompanying part of this manual also includes JSON files that contain profiles for the “Google Chrome” extension “Restlet Client”. These files are x509-verifier.json and pdf-sgn-verifier.json and contain profiles for REST APIs x509-verifier and pdf-sgn-verifier respectively. They can be used after installing “Restlet client” “Google Chrome” extensions.

“Restlet Client” have known bug which manifests itself by always, on profile loading, change the body form parameter type from “File” to “Text”. The workaround is to switch changed type back to “File” and then to chose the wanted file.

Company Information

Our website uses cookies to provide the users with more user-friendly services that would otherwise not be possible. Cookies help the website function and improve the user browser experience. By clicking "I accept" you agree with our Privacy Policy and Cookie usage.

Privacy Preference Center

Consent Management

Cookies

Our website uses cookies to provide the users with more user-friendly services that would otherwise not be possible without them. Cookies help the website function and improve the user browser experience. You can disable cookies for our site if you not agree with cookie usage.