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.
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
This configuration requires a server with a Linux operating system.
The commands show belown are suitable for CentOS. 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.
sudo yum install -y yum-utils
sudo yum-config-manager \
--add-repo \
https://download.docker.com/linux/centos/docker-ce.repo
sudo yum 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.
cd /opt/signbox_optimizer
Docker-compose.yml settings file:
STEP 4: Load SignBox Docker image.
Run the following commands:
cd /opt/signbox_optimizer
docker image load -i signbox.tar
Remove image file:
rm -rf /opt/signbox_optimizer/signbox.tar
STEP 5: Launch the service.
Run:
docker-compose up -d --scale api=4 --scale cryptosvc=8
Check service status:
docker-compose ps
Name Command State Ports
----------------------------------------------------------------------------------------------------------------------
signbox_optimizer_nginx_1 /docker-entrypoint.sh ngin ... Up 0.0.0.0:443->443/tcp,:::443->443/tcp,
0.0.0.0:80->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.
STEP 1: Import SignBox Optimizer (VM) in the virtual environment.
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:
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:
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):
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:
< 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:
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:
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:
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:
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:
alias.ini
file with all image parametersimage_filename.argb
fileBoth files must be moved to the /img directory in SignBox Optimizer (see image folders path)
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:
id=104.2
Error response:
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:
{host}/result_{filename}
The urlback parameter is defined as:
{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
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
<?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);
?>
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 or your mapped volume:
/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
docker compose down
Followed by
docker compose up -d
STEP 1: Load certificates in the optimizer
Load the PEM files in the following path:
/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
systemctl stop bit4-de.api.service bit4-de.cryptosvc.service nginx
Followed by
systemctl start bit4-de.api.service bit4-de.cryptosvc.service nginx
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:
docker-compose logs
To read logs in OVA version of SignBox Optimizer you can find logfile in this path:
/var/log/de
A postman collection is available as a support for a quick start.
It is only required to edit host
variable in Postman environment with the IP or domain of SignBox Optimizer.
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.
The Docker Optimizer configuration requires a SignBox Optimizer image package and a server using Linux Operating System with Internet access. Please check our documentation.
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 | Non existent timestamping |
Method | Endpoint | Action |
---|---|---|
GET | /api/echo | Checks service availability |
POST | /api/sign | Signs a local or a remote hosted file |
POST | /api/generate_otp | Send an otp code by sms to the signer |
Signs a local or a remote hosted file.
file_in required | string <binary> Local path of the file to be signed.
|
url_in required | string Url where to get the document to be signed.
|
url_out required | string Url where to send signed file. See description and sample code in Webhooks configuration |
urlback required | string Url where to send signing process log. See description and sample code in Webhooks configuration |
env required | string Reference environment for sandbox or production |
format | string Default: "pades" Types of supported signature profiles:
|
username required | string Digital identity username |
password required | string Digital identity password |
pin required | string Digital identity PIN |
level | string Default: "BES" Specify the level of the signature. Must consider that LTVLITE is a LTV signature lighter and efficient in comparison with the standard LTV level. The allowed values are:
|
identifier | string Location of the token. If the certificate used is a renewed certificate use DS1 |
tsa_bookmark | string Timestamp service alias name. This field is required for signatures with levels T, LTV or XL |
billing_username required | string Billing account username |
billing_password required | string Billing account password |
reason | string Reason about the signature |
location | string Geographic location about the signature |
npage | string Default: 0 Page number where the image signature is placed. The first page starts in 0
|
otp | string The OTP code previously sent to the user. This parameter is only required and available for specific digital identities |
metadata | string Optional metadata information associated to the signed document |
metadata_oid | string OID identifier associated to the metadata |
metadata_enveloped | string Set to 0 if metadata is in DER format, or 1 (default) for ASN1 Octet String enveloping |
img_bookmark | string Signature image alias name corresponding to a previously stored image in the Optimizer
|
img | string Base64 preconverted image string |
img_size | string The original image size in pixels. (Example: 200,140) Any mismatch will cause wrong adjustments of the image or it would simply not appear. |
position | string The image rectangle bottom-left & top-right corner coordinates in pixels corresponding to 72DPI resolution. For an A4 document page, X-Y values ranges from 0-595 and 0-842 pixels respectively. (Example: 300,100,500,150) |
paragraph_format | string Identifying text with the signer's associated data. See description |
The sign request was executed
curl -i -X POST \ 'https://signbox.developers.uanataca.com/api/sign' \ -H 'Content-Type: multipart/form-data' \ -F file_in=@sample_folder/document.pdf \ -F url_in=http://example.com/document.pdf \ -F url_out=https://example.com/result \ -F urlback=https://example.com/log \ -F env=sandbox \ -F format=pades \ -F username=1122338 \ -F password=7T8xdGBN \ -F pin=w98nZZDR \ -F level=T \ -F tsa_bookmark=uanataca \ -F billing_username=billing_user@domain \ -F billing_password=z5qNqkfB \ -F reason=Signature test \ -F location='Barcelona, Spain' \ -F npage=2 \ -F otp=123123 \ -F metadata='Tm9tYnJlOiBEb2N1bWVudG8gU...' \ -F metadata_oid='1.3.6.1.5.5.7.20' \ -F metadata_enveloped=1 \ -F img_bookmark=uanataca \ -F img='iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAY...' \ -F img_size='200,140' \ -F position='300,100,500,150' \ -F paragraph_format='[{ "font" : ["Universal-Bold",15],"align":"right","data_format" : { "timezone":"Europe/Madrid", "strtime":"%d/%m/%Y %H:%M:%S%z"},"format": ["Firmado por:","$(CN)s","$(serialNumber)s","Fecha: $(date)s"]}]'
id=14.1
Generates an otp for the specified digital identity.
⚠This method is only required and available for specific digital identities
Successful Response
curl -i -X POST \ 'https://signbox.developers.uanataca.com/api/generate_otp' \ -H 'Content-Type: multipart/form-data' \ -F env=prod \ -F password=7T8xdGBN \ -F username=1122338 \ -F uses=10
generated
Method | Endpoint | Action |
---|---|---|
GET | /api/job/{id} | Gets the state of a job |
GET | /api/result/{id} | Gets the signed file |
Gets the state of a signature request by its job id.
⚠This method is only used for testing purpose. In a production environment is required to use urlback
service.
Successful Response
Bad Gateway. Incorrect job id
curl -i -X GET 'https://signbox.developers.uanataca.com/api/job/14.1'
state=done&type=sign
Returns the signed file of a signature request by its job id.
⚠This method is only used for testing purpose. In a production environment is required to useurl_out
service The signed file is only available ifurl_out
is not specified in sign call
Successful Response
Bad Gateway. Incorrect job id
or failed signature.
curl -i -X GET 'https://signbox.developers.uanataca.com/api/result/14.1'
%PDF-1.7 %���� 1 0 obj <</Type/Catalog/Pages 2 0 R/Lang(es-ES) /StructTreeRoot 10 0 R/MarkInfo<</Marked true>>/Metadata 26 0 R/ViewerPreferences 27 0 R>> endobj 2 0 obj <</Type/Pages/Count 1/Kids[ 3 0 R] >> endobj 3 0 obj <</Type/Page/Parent 2 0 R/Resources<</Font<</F1 5 0 R>>/ExtGState<</GS7 7 0 R/GS8 8 0 R>>/ProcSet[/PDF/Text/ImageB/ImageC/ImageI] >>/MediaBox[ 0 0 595.32 841.92] /Contents 4 0 R/Group<</Type/Group/S/Transparency/CS/DeviceRGB>>/Tabs/S/StructParents 0>> endobj (...)