UANATACA SIGNBOX API DOCUMENTATION (1.0)

What it is

The high-performance solution for Bulk, Interactive and LTV signature service. Our best option for signing large number of documents and transactions.

SignBox API is an enterprise-grade solution for automated electronic signature of any type of file or document. A turnkey system that can be easily integrated with any business application without altering the user experience and guaranteeing the legal security of your electronically signed documents. SignBox API is a high-level web API based on the http RESTful paradigm.

How it works

The API is given with SignBox Optimizer that is a server system exposing http RESTful API by means of which, business applications are enabled to require the electronic signature of large number of documents.

SignBox Optimizer performs the most computationally expensive workload of the signature process, thus reducing the data traffic on the local network and make the most of the cryptographic hardware acceleration. The documents to be signed are processed in the customer business layer and are not send to Uanataca Services, instead is sent a hash of the document created using a hash algorithm. For environments demanding high performance, SignBox can be coupled with a pool of SignBox Optimizer.

The system provides options for several electronic signature formats including time stamping and long term validation. The electronic signatures are performed in Uanataca Trusted Service Center side, where signature keys are stored in a Qualified Electronic Signature Creation Device (QSCD) system.

Sandbox Environment

For testing purposes, Uanataca provides integrators of a pre-configured test-mode SignBox Optimizer accessible at the following URL:

https://signbox.developers.uanataca.com

Want to configure your own test-mode Optimizer? Find instructions in the configuration section.

Configuration

SignBox Optimizer can be supplied as a Docker image. See the configuration description in:
SignBox Optimizer on Docker

Hardware requirements

CPU: modern multicore (minimum 4 core)

RAM: 8GB

HDD: 200 GB

SignBox Optimizer on Docker

This configuration requires a server with a Linux operating system.

The commands show belown are suitable for Ubuntu. Each Linux distribution will require it's own commands.

STEP 1: Install Docker and Docker-Compose.

Docker and Docker-Compose

Run the following commands in this order.

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker

Run command sudo docker run hello-world to check the installation.

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

Extract all optimizer_docker.zip content in a local folder.

Move uanataca_optimizer folder to the path /opt in the server.

The outcome should look like this:

STEP 3: Mapping volumes (for environments with a pool of SignBox Optimizer).

In high performance environments with a pool of SignBox Optimizer, service settings and logs must be stored in a shared volume outside Optimizer servers. These volumes must be defined in docker-compose.yml file in each SignBox Optimizer.

cd /opt/uanataca_optimizer

Docker-compose.yml settings file:

STEP 4: Load SignBox Docker image.

Run the following commands:

cd /opt/uanataca_optimizer_docker/
docker image load -i uanatacaoptimizer.tar 

Remove image file:

rm -rf /opt/uanataca_optimizer_docker/uanatacaoptimizer.tar

STEP 5: Launch the service.

Run:

docker-compose up -d

Check service status:

docker-compose ps

NAME                                    IMAGE                   COMMAND                  SERVICE     CREATED          STATUS          PORTS
uanataca_optimizer_docker-optimizer-1   uanatacaoptimizer:1.0   "/docker-entrypoint.…"   optimizer   49 minutes ago   Up 49 minutes   0.0.0.0:5678->5678/tcp, 0.0.0.0:16100->16100/tcp
uanataca_optimizer_docker-redis-1       redis                   "docker-entrypoint.s…"   redis       49 minutes ago   Up 49 minutes   0.0.0.0:6379->6379/tcp

All services must be UP.

Signature Image Configuration

A visual signature can be placed as an image in the signed document. The visual signature is composed by an image and text. SignBox allows to create and store multiple templates.

The alias.ini file contains templates with size parameters of each stored image as well as the signature associated text, all represented by an "alias" which is included as a parameter in the SIGN API call.

Image .argb files must be locateed in the same /img directory where alias.ini is placed. Those files are created from the .png or .jpg files by using the ARGB Tool.

This is how the alias.ini file should look like (three different images are stored in this example):

Paragraph format

The signature image permits the addition of identifying text with the signer's associated data. This parameter allows to define the style and the content of the signature image, according to the following JSON object:

[{ "font": [< FONTFAMILY >,< FONTSIZE >],"align" : < ALIGNVALUE >, "format": [< LINE1 >,< LINE2 >,...,< LINEN > ]}]

font (optional): defines the text format to include in the signature image. The parameters < FONTFAMILY > and < FONTSIZE > correspond to the font style and size respectively. The supported styles are the following:

• Universal (default): This style belongs to the Sans-Serif category (normal)

• Univeral-Bold: Universal font in bold

• Univeral-Italic: Universal font in italic

• Universal-BoldItalic: Universal font in bold and italic

• Times: This style belongs to the Serif category

• Times-Bold: Times font in bold

• Times-Italic: Times font in italic

• Times-BoldItalic: Times font in bold and italic

< FONTSIZE > specifies the character size, defined as points. The sofware adjusts automatically the font size according to the dimensions of the signature image.

align (optional): defines the text alignment related to an image (if exists). It can assume the following values:

• right: right text alignment (default)

• left: left text alignment

• middle: overlapped text

format: defines the text lines that will appear on the signature image. These lines can be created from static text and information included in the signer's digital certificate:

• $(CN)s : CommonName

• $(L)s : Locality

• $(S)s : stateOrProvinceName

• $(OU)s : organizationalUnitName

• $(E)s : email

• $(Email)s : email included in the Subject Alternative Name

• $(Issuer)s : Certificate CA Issuer Common Name

• $(date)s : Date and time of the signature. Compliant to ISO 8601 standard.

• $(reason)s : “bit4-reason” parameter value

• $(location)s : “bit4-location” parameter value

Example:

[{ "font" : [" Universal ",50]," align ":" right","format ": [" Digitally Signed by $(CN)s","O=$(O)s","C=$(C)s","S=$(S)s","Date: $(date)s","CustomField1: CustomValue1 ","CustomField2: CustomValue1 ","CustomField3: CustomValue3 "]}]

From this configuration, the image paragraph should look like as shown below:

Webhooks

SignBox API requires that the customer business develop a webhook to manage the service callbacks. There are two callbacks in the service that must be set in the parameters url_out and urlback of the SIGN API call.

urlback

The service logs are sent as a string in a HTTP POST request to the webhook url defined in this parameter.

Below you can see message samples.

Successful response:

{
  "status": "success",
  "message": "Signature for job 25d07648-1d35-4263-a1c0-3336eb947560 completed",
  "detail": {
    "status": "completed",
    "format": "PADES",
    "env": "sandbox",
    "jobid": "25d07648-1d35-4263-a1c0-3336eb947560"
  }
}

Error response:

{
  "status": "error",
  "message": "Error ocurred while signing document fcb54705-ea0e-46ad-9bb6-8ea6240a876f: 401 Unauthorized",
  "detail": {
    "status": "error",
    "format": "PADES",
    "env": "sandbox",
    "jobid": "fcb54705-ea0e-46ad-9bb6-8ea6240a876f"
  }
}

url_out

In a successful signature process, the result signed file is sent as a binary file in a HTTP POST request to the webhoook url defined in this parameter.

Rootstore configuration

As a requirement for LTV/LTVLITE signature level, we must add to the optimizer every chain of trust for each certificate that is involved in the signature.

In case that you don't make use of LTV/LVTLITE signature level, this process is NOT necessary.

This process vary depending on the selected optimizer install method.

Every certificate introduced in the optimizer regarding the rootstore needs to be formatted as a PEM file and introduced in a specific folder. Below an example of the general structure that is needed.

Note: Number of lines below the header are not representative of a real certificate.

-----BEGIN CERTIFICATE-----
MIIIWjCCBkKgAwIBAgIIICfKLtFjrRMwDQYJKoZIhvcNAQELBQAwgbkxCzAJBgNV
BAYTAkVTMUQwQgYDVQQHDDtCYXJjZWxvbmEgKHNlZSBjdXJyZW50IGFkZHJlc3Mg
YXQgd3d3LnVhbmF0YWNhLmNvbS9hZGRyZXNzKTEWMBQGA1UECgwNVUFOQVRBQ0Eg
Uy5BLjEVMBMGA1UECwwMVFNQLVVBTkFUQUNBMRswGQYDVQQDDBJVQU5BVEFDQSBS
K+0fx83luCN81YLsUpdpc3e0URG7eDMKNG54WvtW
-----END CERTIFICATE-----

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path:

/opt/uanataca_optimizer_docker/optimizer_data/localstore/

STEP 2: Restart the service

After all the desired certificates have been loaded into the optimizer, we must execute the following command on the container

docker compose exec optimizer python -m optimizer generate-rootstore

Logs

Service logs files are stored in a local folder in OVA or stored inside the containers.

To read logs run this command:

docker-compose logs

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 SignBox Optimizer.

SignBox Postman collection download

API Reference