UANATACA ONE-SHOT SIGNATURE API DOCUMENTATION (v1)
| Table of Contents | ||
|---|---|---|
|
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.
...
Electronic signatures include a time stamp, providing a document signature with a reliable date and time.
How it works
The API is given with a module called One-Shot Optimizer, a server system that exposes our One-Shot HTTP RESTful API through which business applications are able to process their electronic signature requests.
...
The electronic signatures are performed on Uanataca Trusted Service Center side, where signature keys are generated and stored in a Qualified Electronic Signature Creation Device (QSCD) system.
Sandbox environment
For testing purposes, Uanataca provides integrators of a pre-configured test-mode One-Shot Optimizer accessible at the following URL:
...
Want to configure your own test-mode Optimizer? Find instructions in the configuration section.
Classic Workflow
In a common One-Shot Signature service, an OTP (One-Time Password) code is sent via SMS to the end user, directly from Uanataca services. The OTP verification method is used to trigger the issuance of the single-use digital signature certificate, which is inmediately used to sign the request associated documents e.g. the service contract.
...
| Code Block |
|---|
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464 |
Alternative Workflows
Hash signature flow
Our software nowadays is capable of performing a hash signature with the return of a p7m structure (CMS object) instead of building and returning a whole built document. It's important to mention that this modality needs a specific extracted message digest. These would be the objects that the hash should contain to be introduced into the optimizer.
...
| Code Block |
|---|
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464 |
# Video ID Workflows
eIDAS VideoID
This workflow defines the complete process of issuing eIDAS certificates.
...
| Code Block |
|---|
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464 |
External Mode
In External mode Video ID, digital evidences are uploaded to an independent Video ID platform.
...
| Code Block |
|---|
curl -X DELETE https://one-shot.developers.uanataca.com/api/v1/documents/1464 |
Configuration
One-Shot Optimizer can be supplied as a Docker or as a Virtual Machine image. See the configuration description in:
One-Shot Optimizer on Docker
One-Shot Optimizer on Virtual Machine
Hardware requirements
CPU: modern multicore (minimum 4 core)
RAM: 8GB
HDD: 200 GB
One-Shot Optimizer on Docker
This configuration requires a server with a Linux operating system.
...
See service settings configuration section.
Update One-
...
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.
...
shot
Run the following commands:
| Code Block |
|---|
cd /opt/oneshot_optimizer
docker-compose down |
List all Docker images to find the image ID or name.and then remove the image.
| Code Block |
|---|
docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
nginx latest 66f8bdd3810c 7 weeks ago 192MB
oneshot_optimizer 0.2.8 ec613a792ac5 13 months ago 156MB
oneshot_imgconverter 0.1.18 b694fdda9066 4 years ago 143MB |
Then remove the image.
| Code Block |
|---|
docker rmi nginx:latest
docker rmi oneshot_optimizer:0.2.8
docker rmi oneshot_imgconverter:0.1.18 |
Load the new Signbox Docker image.
| Code Block |
|---|
docker image load -i oneshot_optimizer.tar
docker image load -i oneshot_imgconverter.tar
docker-compose up -d |
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.
...
| Code Block |
|---|
-----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.
...
| Code Block |
|---|
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
| Code Block |
|---|
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
| 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/oneshot_optimizer/rootstore/cert |
...
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 that must be located at /opt/bit4id/oneshot_optimizer INSIDE the container, this can be done through
| Code Block |
|---|
docker exec -it <container_id> ./generaterootstoredockergeneraterootstore.sh |
STEP 34: 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
| Code Block |
|---|
systemctldocker stop optimizer imgconverter nginxcompose down |
Followed by
| Code Block |
|---|
systemctldocker startcompose optimizer imgconverter nginxup -d |
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.
...
| Code Block |
|---|
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.
...
| Code Block |
|---|
<?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.
...
| Code Block |
|---|
/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