UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)

...

What it is

One-Shot represents the solution for electronic signatures based on a single-use certificate issuance. One-Shot API is the solution for Uanataca One-Shot Signature service, a complete option that can be implemented as part of your application or web.

...

See service settings configuration section.

One-Shot Optimizer on Virtual Machine

The Virtual Machine is supplied in an OVA file. One-Shot Optimizer image is compatible with common virtual environments such as VMWare, AWS, Azure or VirtualBox.

STEP 1: Import One-Shot 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 in the file ifcfg-ens33, 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.

Then restart network services with command service network restart.

Example:

...

STEP 3: Service settings.

See service settings configuration section.

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

Docker

Prior to following the steps, you must have a mapped volume with rootstore folder and a mapped volume with 'dockergeneraterootstore.sh' file.

In case you don't have this volumes, below you can find an example showing how to define them.

    optimizer:
        image: oneshot_optimizer:0.2.8
        environment:
            - OPTIMIZER_BIND=socket
            - TZ=Europe/Madrid
        networks:
            oneshot-optimizer:
                aliases:
                    - optimizer.oneshot-optimizer.loc
        volumes:
            # Rootstore files
            # - [your_folder]:/opt/bit4id/oneshot_optimizer/rootstore:rw
            - ./common/etc/rootstore:/opt/bit4id/oneshot_optimizer/rootstore:rw

            # Script file
            # - [your_folder]:/opt/bit4id/oneshot_optimizer/rootstore:rw
            - ./common/etc/dockergeneraterootstore.sh:/dockergeneraterootstore.sh:rw

STEP 1: Load certificates in the optimizer

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

/oneshot_optimizer/common/etc/rootstore/cert

STEP 2: Set settings.ini (only for latest versions where this param is already in the file)

Set rootstore parameter with "manual" value

1 |[general]
2 |environment = sandbox
3 |usepdfclean = false
4 |configuration = default
5 |rootstore = manual
6 |
7 |[tsa]
8 |tsa_url = https://tsa.uanataca.com/tsa/tss03
9 |
10|[billing]
11|billing_username = user@uanataca.com
12|billing_password = ejVxTnFrZkaI=
13|
14|[request]
15|default_profile = PFnubeQAFCiudadano
16|default_ra = 1000
17|
18|[proxy]
19|useproxy = false
20|proxy_host = 192.168.1.34
21|proxy_port = 8888
22|proxy_protocol = http
23|proxy_username = user
24|proxy_password = password
25|useproxycredentials = true

STEP 3: Execute the script

It is needed the execution of the script INSIDE the container, this can be done through

docker exec -it <container_id> ./dockergeneraterootstore.sh

STEP 4: Restart the service

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

docker compose down

Followed by

docker compose up -d

OVA

STEP 1: Load certificates in the optimizer

Load the PEM files in the following path:

/opt/bit4id/oneshot_optimizer/rootstore/cert

STEP 2: Execute the script

It is needed the execution of the script that must be located at /opt/bit4id/oneshot_optimizer , this can be done through

./generaterootstore.sh

STEP 3: Restart the service

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

systemctl stop optimizer imgconverter nginx

Followed by

systemctl start optimizer imgconverter nginx

Service settings

Requirements:

• Billing credentials for the selected environment.

• Credentials or token generated from these belonging to the authorized operator.

• Certificate (.cer) and key (.key) files for connection to the selected environment.

• The Id number for the Registration Authority that will issue the certificates.

This steps are for both sandbox or production environment.

You should have received a certificate (.cer) and a key (.key) file to be used to identify your application in communications with Uanataca signature services. Place both files in the certificates folder.

settings.ini file location:

/opt/oneshot_optimizer/common/etc/certs/<sandbox/prod> or custom mapped volume (Docker)
/opt/bit4id/oneshot_optimizer/etc/certs/<sandbox/prod> (Virtual Machine)

...

This is the file that contains all the optimizer setting variables, here you can set values that will be taken as default in case that they did not get sent directly through the api call. There are some shared values between the API call and this file, and some regarding background configurations. You can find a brief explanation below.

Important: If billing password is specified, it must be previously converted into Base64 format. Run the following command to convert your password to base64:

echo -n <<billing_password>> | base64

The following is a view of the settings.ini file:

1 |[general]
2 |environment = sandbox
3 |usepdfclean = false
4 |configuration = default
5 |rootstore = uanataca
6 |
7 |[tsa]
8 |tsa_url = https://tsa.uanataca.com/tsa/tss03
9 |
10|[billing]
11|billing_username = user@uanataca.com
12|billing_password = ejVxTnFrZkaI=
13|
14|[request]
15|default_profile = PFnubeQAFCiudadano
16|default_ra = 1000
17|
18|[proxy]
19|useproxy = false
20|proxy_host = 192.168.1.34
21|proxy_port = 8888
22|proxy_protocol = http
23|proxy_username = user
24|proxy_password = password
25|useproxycredentials = true

environment: Work environment of the optimizer, taken as default if not send through API
usepdfclean: Enables sanitization of loaded documents. If the document contains multiple signatures this process would remove the previous signatures that the document has as they got treaten like an external structure to PDF standard
configuration: Configuration preset, only for determinated use-cases
rootstore: Chains of trust that the optimizer will work with, the value can be set with the customer name, only for determinated use-cases
tsa_url: Timestamping to apply on signatures
billing_username: Billing username of the desired environment
billing_password: Billing password codified in base64
default_profile: Certificate profile to issue, taken as default if not sent through API
default_ra: Registration Authority in which to issue, taken as default if not send through API

The file settings.ini contains default parameters that can also be adjusted via API using the Update Settings call.

Except by tsa_url, all parameters shown below are replaced every time the Create Video ID Request call is executed.

Once you are done editing the file, restart the One-Shot Optimizer service to changes take effect.

Virtual Machine:

systemctl restart optimizer

Docker:

cd /opt/oneshot_optimizer
docker-compose restart optimizer

Webhook Configuration

One-Shot API requires a Webhook implemented on customer business side to manage our service callbacks. Every request status change will trigger a simple event-notification via HTTP POST, consisting on a JSON object to an URL that must be explicitly included as an optional parameter in the Create Video ID Request call. Keep in mind that the webhook passed as parameter will be only for testing purposes, the definitive webhook has to be set in your belonging RA by Operations Department.

The following is a sample view of the JSON object that is sent as a callback at every status change:

{
    "status": "VIDEOINCOMPLETE", 
    "date": "2021-07-20T08:08:21.132394", 
    "previous_status": "VIDEOPENDING", 
    "request": 46760, 
    "registration_authority": 139
}

Where: status is the most recent status, this is, the status that triggered the notification.
date is the date of the request status change in datetime format.
previous_status is the status inmediately previous to last change.
request is the request unique id.
registration_authority is the Registration Authority id number the request is associated.

Sample code

In this sample, every JSON object is stored in a file named 'videoid'.

The webhook parameter used in the Create Video ID Request call is defined as:

{host}/videoid

where {host} is the IP or domain from the server exposing the webhook.

Python

import web
import datetime

urls = (
        '/videoid, 'videoid',
        )

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

class video:
    def POST(self):
        data = web.data()
        f = open("status.json",'a+')
        f.write(data)
        f.close()
        return ''

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

PHP

<?php

//videoid.json

$post = file_get_contents('php://input',true);
$file_handle = fopen('/videoid/status.json', 'w');
fwrite($file_handle, $post);
fclose($file_handle);

?>

Logs

Service logs file optimizer.log is stored in a One-Shot Optimizer local folder.

Docker:

/opt/oneshot_optimizer/common/logs or custom mapped volume
Command 'docker-compose logs > log.txt'

Virtual Machine:

/opt/bit4id/oneshot_optimizer/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 One-Shot Optimizer.

One-Shot Postman collection download

API Reference