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

Hardware requirements

CPU: modern multicore (minimum 4 core)

...

The commands show belown are suitable for CentOSUbuntu. Each Linux distribution will require it's own commands.Image Removed Watch on video!

STEP 1: Install Docker and Docker-Compose.

...

Run the following commands in this order.

Code Block

sudo yum install -y yum-utils

sudo yum-config-manager \
--add-repo \
https# 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/centos/ubuntu/gpg -o /etc/apt/keyrings/docker-ce.repo
asc
sudo yumchmod 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 signbox_optimizer_docker.zip content in a local folder.

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

Code Block
cd /opt/signbox_optimizer

Docker-compose.yml settings file:

...

STEP 4: Load SignBox Docker image.

Run the following commands:

Code Block
cd /opt/signbox_optimizer docker image load -i signbox.tar

Remove image file:

Code Block
rm -rf /opt/signbox_optimizer/signbox.tar

STEP 5: Launch the service.

Run:

Code Block
docker-compose up -d --scale api=4 --scale cryptosvc=8

Check service status:

Code Block

docker-compose ps

             Name                                 Command                State                 Ports
----------------------------------------------------------------------------------------------------------------------
signbox_optimizer_nginx_1a+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.

Code Block
cd /opt/uanataca_optimizer

Docker-compose.yml settings file:

...

STEP 4: Load SignBox Docker image.

Run the following commands:

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

Remove image file:

Code Block
rm -rf /opt/uanataca_optimizer_docker/uanatacaoptimizer.tar

STEP 5: Launch the service.

Run:

Code Block
docker-compose up -d

Check service status:

Code Block

docker-compose ps

NAME                                    IMAGE                   COMMAND                 /docker-entrypoint.sh ngin ... SERVICE    Up CREATED     0.0.0.0:443->443/tcp,:::443->443/tcp,     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:806379->80/tcp,:::80->80/tcp
signbox_optimizer_signbox_api_1         signbox start                    Up
signbox_optimizer_signbox_cryptosvc_1   signbox start                    Up

All services must be UP.

SignBox Optimizer on Virtual Machine (OVA)

The Virtual Machine is supplied in an OVA file. SignBox Optimizer image is compatible with common virtual environments like VMWare, AWS, Azure or VirtualBox.

STEP 1: Import SignBox Optimizer (VM) in the virtual environment.

Adjust the system requirements for optimal usage considering host terminal resources described in hardware requirements.

STEP 2: Network configuration.

The network settings are configured on the file ifcfg-ens160, which can be found in the path /etc/sysconfig/network-scripts. Edit the file and insert the correct IP address, network mask, gateway and DNS for your network.

Example:

...

Restart network services with command:

Code Block
service network restart

Proxy network settings

The Proxy settings are configured in the file settings.ini which can be found in path /opt/bit4id/de/etc. Edit the file and insert proxy address, port and credentials if are needed.

It is possible to include url exceptions for services that don't use proxy network. Exceptions must be included in regular expression format.

Example:

...

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 parameters can be adjusted on the alias.ini file which is located at:

/opt/signbox_optimizer/img or custom mapped volume (Docker)

/opt/bit4id/de/etc/img (Virtual Machine)

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.

Parameter	Description	Example
[alias]	img_bookmark parameter in SIGN Call	uanataca
x1	Left X Coordinate (measured from page left side)	150
y1	Bottom Y Coordinate (measured from page bottom)	80
x2	Right X Coordinate (measured from page left side)	500
y2	Top Y Coordinate (measured from page bottom)	180
img	Image argb filename	uanataca.argb
size_x	Horizontal image size in pt	512
size_y	Vertical image size in pt	512
paragraph_format	Text details structure. See description	[{ "font" : ["Universal-Bold", 50]...

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:

Code Block
[{ "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:

Code Block

[{ "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:

...

ARGB Tool

ARGB Tool is a Windows software that converts a PNG or JPG image to ARGB image type and generates the settings to include in the alias.ini file.

Download: ARGB Tool

STEP 1: Extract zip content

Extract the zip content in a local folder.

STEP 2: Convert image and create alias settings

The ARGB Tool is performed through an executable file that is accessible in a Windows terminal at:
..\argb-graphic_signature\argb-tool\bin

It just requires to copy the original image to this path and open a command prompt. Then run this command with the position <x1,y1,x2,y2> coordenates:

Code Block
argb utils make-ini image_filename.png [--out-dir folder_name] [--alias your_alias_name] [--position 80,80,380,230]

The result of this command will consist in two files:

An alias.ini file with all image parameters
A image_filename.argb file

Both files must be moved to the /img directory in SignBox Optimizer (see image folders path)

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. Each signature generates a single string composed by the error message and the signature job identifier. For a successful signature the string only contains the job id.

Successful response:

Code Block
id=104.2

Error response:

Code Block
message=Error%3A+Pin+invalid&exception=Error&id=980.4

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.

Sample code

In this sample, signed files are saved with the original filename in a folder named 'signbox-files'. For the logs, a new log file is generated everyday containing daily logs. Log files are saved in a folder name 'logs', inside signbox-files folder.

The url_out parameter is defined as:

Code Block
{host}/result_{filename}

The urlback parameter is defined as:

Code Block
{host}/servicelogs

where {filename} is the filename of the document to be signed, and {host} is the IP or domaing from the server exposing the webhook.

Python

Code Block

import web
import os

urls = (
        '/result_(.+), 'url_out',
        '/servicelogs', 'urlback'
        )

app = web.application(urls, globals())
app = app.wsgifunc()

class url_out:
    def POST(self, name):
        data = web.data()
        os.chdir('/signbox-files')
        f = open("%s" % name,'w')
        f.write(data)
        f.close()
        return ''

class urlback:
    def POST(self,name):
        data = web.data()
        os.chdir('/signbox-files/logs')
        f = open("%Y%m%d.txt" % name, 'a+')
        f.write(str(data))
        f.write(str("\n"))
        f.close()
        return ''

if __name__ == "__main__":
    app.run()

PHP

Code Block

<?php

//url_out

$post = file_get_contents('php://input',true);
$file_handle = fopen('/signbox-files/', 'w');
fwrite($file_handle, $post);
fclose($file_handle);


//urlback

$post = file_get_contents('php://input');
$line = $post.PHP_EOL;
$myfile = fopen("/signbox-files/logs/%Y%m%d.txt", "a") or die("Unable to open file!");
fwrite($myfile, $line );
fclose($myfile);

?>

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.

Code Block

Docker

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path or your mapped volume:

Code Block
/signbox_optimizer/etc/trusted_roots/certs

STEP 2: Restart the service

After all the desired certificates have been loaded into the optimizer, we must fully restart the services with

Code Block
docker compose down

Followed by

Code Block
docker compose up -d

OVA

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path:

Code Block
/opt/bit4id/de/etc/trusted_roots/certs

STEP 2: Restart the service

After all the desired certificates have been loaded into the optimizer, we must fully restart the services with

Code Block
systemctl stop bit4-de.api.service bit4-de.cryptosvc.service nginx

Followed by

Code Block
systemctl start bit4-de.api.service bit4-de.cryptosvc.service nginx

Logs

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

To read logs in Docker version of SignBox Optimizer run this command:

Code Block
docker-compose logs

To read logs in OVA version of SignBox Optimizer you can find logfile in this path:

/var/log/de

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

Video tutorials

Need a better understanding of SignBox API? Check the video tutorials below and follow step-by-step instructions! They will guarantee you use our API efficiently for the best experience in document signatures.

Docker Optimizer Configuration

The Docker Optimizer configuration requires a SignBox Optimizer image package and a server using Linux Operating System with Internet access. Please check our documentation.

...

Error codes

...

Message

...

Reason

...

ProcessTerminated: process ended with exit code X

...

Webhook malfunctioning

...

Token not found

...

Non existent certificate

...

Invalid credentials

...

Incorrect credentials

...

PasswordProtected

...

Input PDF protected with password

...

Error: Pin invalid

...

Incorrect pin value

...

Error: Token locked

...

Certificate credentials locked

...

Error: Invalid Otp

...

Wrong or expired OTP code

...

Exception: Invalid Environment. Supported values are: []

...

Incorrect environment value

...

Exception: Remote Signature Failed: 401 Unauthorized

...

Wrong billing credentials

...

Exception: Invalid TSA alias

...

Incorrect timestamping alias

...

Exception: Invalid Image alias

...

Incorrect image alias

...

Exception: Remote Signature Failed: 400 Bad Request

...

Insufficient credits

...

Exception: Need tsa_bookmark for ltv signature

...

Performing LTV with timestamping disabled

...

Exception: UnknownIssuer

...

Certificate of any hierarchy missing

...

Exception: Time Stamping Failed: 400 Bad Request

...

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

Parameter	Description	Example
[alias]	img_bookmark parameter in SIGN Call	uanataca
x1	Left X Coordinate (measured from page left side)	150
y1	Bottom Y Coordinate (measured from page bottom)	80
x2	Right X Coordinate (measured from page left side)	500
y2	Top Y Coordinate (measured from page bottom)	180
img	Image argb filename	uanataca.argb
size_x	Horizontal image size in pt	512
size_y	Vertical image size in pt	512
paragraph_format	Text details structure. See description	[{ "font" : ["Universal-Bold", 50]...

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:

Code Block
[{ "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:

Code Block

[{ "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:

Code Block

{
  "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:

Code Block

{
  "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.

Code Block

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path:

Code Block
/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

Code Block
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:

Code Block
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

Version	Old Version 1	New Version 2
Changes made by	Wilter Torres Enriquez	Wilter Torres Enriquez
Saved on	10 Dec 2024	12 Dec 2024

Versions Compared

Key

Hardware requirements

SignBox Optimizer on Virtual Machine (OVA)

Signature Image Configuration

Paragraph format

ARGB Tool

Webhooks

Rootstore configuration

Docker

OVA

Logs

Postman collection

Video tutorials

Docker Optimizer Configuration

Error codes

Signature Image Configuration

Paragraph format

Webhooks

Rootstore configuration

Logs

Postman collection

API Reference

Content Comparison

Versions Compared

Key

Hardware requirements

SignBox Optimizer on Virtual Machine (OVA)

Signature Image Configuration

Paragraph format

ARGB Tool

Webhooks

Rootstore configuration

Docker

OVA

Logs

Postman collection

Video tutorials

Docker Optimizer Configuration

Error codes

Signature Image Configuration

Paragraph format

Webhooks

Rootstore configuration

Logs

Postman collection

API Reference