UANATACA VOL API DOCUMENTATION (v1)

What it is

The high-performance solution for electronic signature Validation and Verification service, providing detailed information of the result.

Uanataca VOL API is a turnkey system that can be easily integrated with any business application or web thanks to its high-level web API based on the http RESTful paradigm.

How it works

The solution is given with VOL Optimizer that is a server system exposing http RESTful APIs by means of which, business applications are enabled to require the electronic signature validation of documents.

VOL Optimizer performs the most computationally expensive workload of the validation and verification process, thus reducing the data traffic on the local network. The signed documents to be validated are processed in the customer business layer and are not send to Uanataca Services.

The system performs the validation and verification on all the signatures contained in a document, including timestamps. The validation consists on:

• Verify that the certificate is issued by a Trusted Service Provider (TSP).

• Verify that the certificate was valid at the time of signing. It means that the certificate was not expired or revoked at that moment.

• Verify the integrity of the document, verifying that no changes were done to the document after the signature.

The verification of the digital certificate is carried out through OCSP and CRL queries to the corresponding TSP issuer.

Open

Configuration

VOL Optimizer is supplied as a Docker image.

Hardware requirements

CPU: modern multicore (minimum 4 core)

RAM: 8GB

HDD: 200 GB

VOL Optimizer on Docker

This configuration requires a server with a Linux CentOS operating system.

STEP 1: Install Docker and Docker-Compose.

Docker

Run the following commands in this order.

Docker-Compose

Run the following commands in this order.

Run command docker-compose version to check the installation. The outcome should show this information:

Open

STEP 2: Extract and copy VOL Optimizer zip content to the server.

Extract all vol_optimizer_docker.zip content in a local folder.

Move VOL Optimizer folder to the path /opt in the server.

The outcome should look like this:

STEP 3: Load One-Shot Docker images.

Run the following commands:

Remove image files:

STEP 4: Launch the service.

Run this command:

STEP 5: Service settings.

See service settings configuration section.

Service settings

Uanataca VOL exposes a custom website to validate documents. The website requires an SSL certificate and Billing credentials. Both requirements are also needed to use the service through API.

Requirements:

• Billing credentials for Uanataca production environment.

• SSL Certificate (.cer) and key (.key) files.

STEP 1: SSL Certificate.

The SSL certificates are required to expose the validation web. If the web is not exposed, the SSL certificate demo files provided in the vol_optimizer_docker.zip can be used.

Consider the following server path:

Please copy SSL certificate files here. If you don't have your own certificate, the provided demo certificate can be used. They are located at /opt/vol_optimizer/demo_SSL_certificate in the server.

STEP 2: Billing credentials.

Copy vol-gui-passwd.tar file to the path /home/bit4id/ in the server. Extract the content:

Run the script to insert your client Billing credentials (username and password):

STEP 3: Launch the service.

Run the following commands:

Check service status:

All services must be UP.

STEP 4: Contact Uanataca support team.

The last step before document validation requires additional settings that may vary for each client server. Please contact our support team for assistance.

Endpoint URLs

The URL exposing the API is composed as follows:

host

The {host} is the IP or domain from the VOL Optimizer.

resource

It is the name of the resource of our interest.

Each resource can also have path parameters and sub-resources that are defined in the API Reference below.

This is an example of endpoint:

Authentication

VOL service requires authentication with the provided Billing credentials.

Each endpoint requires an authentication header before performing the requested action. The header must containt the type (Basic) and a Base64 string that contains the Billing credentials in the format username:password in Base64.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

This is an example with cURL:

JSON validation response

The validation response is a JSON object containig the following schema:

where the objects attributes are:

report

Contains general information about the signatures.

• now [string]: date & time from the verification

• type [string]: electronic signature profile under the European eIDAS regulation

  • Enum: [PAdES, XAdES, CAdES]

• document_uri [string]: uploaded document uri

• annotations [array]: array containing data objects from each signature and timestamp

Signature object:

• type [string]: signature

  • Enum: [signature, timestamp]

• name [string]: signer's name

• reason [string]: reason of the signature

• location [string]: location where the signature is performed

• signature_time [string]: date & time of the signature

• signature [object]: See signature structure

Timestamp object:

• type [string]: timestamp

  • Enum: [signature, timestamp]

• tst_info [object]: timestamp information

• content_digest [string]: timestamp content digest

• signature [object]: See signature structure

errors

List of errors found in the validation process. Each error is composed by:

• where [string]: reference where the error was found

• what [string]: identifier of the error message. See list of messages

data

Report and document information.

• lang [string]: date & time from the verification

• upload_time [string]: date & time from the document upload

• outformat [string]: response format

  • Enum: [json]

• filename [string]: uploadded file name

• headers [object]: header used in the HTTP POST request

• document_hash_type [string]: hash algorithm used

• template [string]: validation response template

  • Enum: [report]

• report_uri [string]: path to retrieve the validation report

• verification_date [string]: date & time from the validation (optional)

• documentid [string]: document identifier

• document_hash [string]: complete document hash regarding the algorithm used

messages

List of message descriptions. The complete list is included in every validation response.

TIMESTAMP_VERIFIED: "The document has not been modified after the application of the timestamp",
INVALID_CONTENT_TYPE_ATTRIBUTE: "Digital signature attribute is not compliant (contentType)",
MULTIPLE_SIGNING_TIME_ATTRIBUTE: "Verification date is declared multiple times (signingTime)",
REVOKED: "Certificate revoked",
SIGNATURE_TIMESTAMP_OK: "Valid timestamp",
UNKNOWN_REVOCATION_INFO: "Revocation information is not available",
UNSUPPORTED_ALGORITHM: "Unsupported signing algorithm",
UNTRUSTED: "Untrusted CA certificate",
CE2011130EU: "Signature complies with EC Decision 2011/130/EU",
NOT_YET_VALID: "Certificate is not yet valid",
NOTCE2011130EU: "Signature not complies with EC Decision 2011/130/EU",
UNKNOWN_ISSUER: "Certificate issued by an unknown authority",
CONTENT_TIMESTAMP_OK: "Valid timestamp",
INVALID_CERTIFICATE_REF: "References to certificates are incorrect",
SIGNATURE_TIMESTAMP_ERROR: "Invalid timestamp",
SIGNING_KEY_LESS_THAN_2048_BITS: "The signature key has a length of less than 2048 bits",
NO_CA_BASIC_CONSTRAINTS: "Certificate root without attributes of CA",
INDETERMINATE_VALIDATION_TIME: "Verification date is undetermined",
SIGNED_DATA_NOT_FOUND: "Signed data is not present",
NO_OCSP_SIGNING_USAGE: "Certificate used to sign OCSP response is not suitable for the purpose",
SIGNATURE_VERIFIED: "The document has not been modified after signature",
INVALID_TIMESTAMP: "Invalid timestamp",
CONTENT_TIMESTAMP_ERROR: "Invalid timestamp",
NO_CERTIFICATE_SIGNING_USAGE: "Certificate issued by a CA not suitable for the purpose",
XML_SCHEMA_MISMATCH: "The XML file does not respect the XAdES/XMLDSIG schema",
SIGNING_CERTIFICATE_V1: "The reference to the signature certificate uses an obsolete format (signingCertificate 1)",
NO_TIMESTAMPING_USAGE: "The TSA certificate used to issue the timestamp is not suitable for the purpose",
NO_CRL_SIGNING_USAGE: "Certificate used to sign the CRL is not suitable for the purpose",
INVALID_SIGNATURE: "Invalid digital signature",
TRUSTED: "Trusted CA certificate",
SUSPENDED: "Certificate suspended",
INVALID_SIGNING_CERTIFICATE_REF: "Reference to the signature certificate is incorrect",
WEAK_HASHING_ALGORITHM"The document digest was calculated using an weak algorithm",
NO_SIGNING_CERTIFICATE: "Signing certificate is not present",
EXPIRED: "Certificate expired",
NO_SIGNING_CERTIFICATE_REF: "Signing certificate reference is not present",
SIGNING_CERTIFICATE_REF_FOUND: "Reference to the signature certificate is valid"

validation

Contains validations results for each signature and timestamp.

• signatures [array]: contains the results of the signtaure validations. See signature validation structure

• timestamps [array]: contains the results of the timestamp validations. See timestamp validation structure

• result [string]: validation result

  • Enum: [SUCCESS, ERROR]

profile

Profile used in the validation.

• type [string]: electronic signature profile, under the European eIDAS regulation, used in the validation

  • Enum: [PAdES, XAdES, CAdES]

• name [string]: profile name

• description [string]: profile description

Example of a validation response:

Signature validation structure

• data [string]: JSON path where the signature is located

• type [string]: signature or timestamp

  • Enum: [signature]

• status [object]: validation status for each signature and timestamp included in a signature.

• time [string]: date & time from the verification

• timestamps [array]: timestamps inluded in a signature. See timestamp validation structure

• certificate_refs [object]: JSON path where the certificates used for signing are located, ordered by the version number

• certificates [array]: list of all certificates used

• signing_certificate [string]: certificate used in this signature

• index [number]: index of this signature in the list of all file signature, starting from 0

• name [string]: signer's name

• reason [string]: reason of the signature

• location [string]: location where the signature is performed

• level [string]: electronic signature level under the European eIDAS regulation

  • Enum: [PADES-BASIC, PADES-T, PADES-LT, XAdES-BASIC, XAdES-T, XAdES-XL, CAdES-BASIC, CAdES-T]

Timestamp validation structure

• data [string]: JSON path where the signature is located

• type [string]: signature or timestamp

  • Enum: [timestamp]

• status [object]: validation status for each signature and timestamp included in a signature.

• time [string]: date & time of the timestamp

• tst_info [string]: timestamp information

• certificate_refs [object]: JSON path where the certificates used for signing are located, ordered by the version number

• certificates [array]: list of all certificates used

• signing_certificate [string]: certificate used in this signature

• index [number] : index of this signature in the list of all file signature, starting from 0

Signature structure

• version [number]: JSON path where the signature is located

• digest_algorithm_identifiers [array]:

• signatures [array]: contains information about signature algorithm used and the digests

• certificates [array]: contains all the information from the signer certificates

• crls [array]: contains all the information from the CRLs

• ocsps [array]: contains all the information from the OCSP certificates

Postman collection

A postman collection is available as a support for a quick start.
It is only required to edit hostvariable in Postman environment with the IP or domain of VOL Optimizer.

VOL Postman collection download

API Reference

https://cdn.developers.uanataca.com/vol/vol.html