Uanataca RA API allows the generation and distribution of digital certificates, either by integrating the issuance and management into a business application.
The Registration Authority is composed of people and processes, with the main function of identifying applicants of digital certificates and sending verified data for the issuance of the certificate.
Digital certificates are created and used as part of a life-cycle that includes three fundamental stages:
The complete flow is explained in the next section Flow chart
As part of the paperless procedure, every Request has its own digital contract that has to be electronically signed by the RA Operator (in charge of approving the Request) and the certificate subscriber, each one with their respective digital certificates.
List of entities and names used to describe UANATACA's services
Certification Authority (CA)
The CA is the issuer of the certificates requested by the Registration Authority.
Registration Authority (RA)
The RA manages the entire life-cycle of digital identities, from the certificate issuance to suspension, reactivation, renewal and revocation of the PKI credentials. Reuests are generated and verified by a Registration Authority Officer.
Registration Authority Officer (RAO)
The RAO follows strict guidelines and policies defined to ensure the trust of the CA. RAO is responsible for managing the requests for digital certificates and verifying the content of the requests as well as identifying people requesting them.
API User
The Account having access to the APIs provided by the system. It is generally used for a server to server interaction.
Certificate Request (Request)
It is a request to issue a new certificate. A request can be associated with only one RA and has a status attribute to monitor the progress of the application:
CREATED: The request has been created and associated to an RA, but the content of the request has not been validated yet. In this state, data can also be inconsistent, the system will not throw an error. The content of the request can be edited at any moment to make it valid.
ENROLLREADY: The certificates are ready to be issued. The request arrives at this stage, if it has been approved and signed by a RAO, who is part of the RA in charge of the request.
ISSUED: The certificate is issued by the user's self-service page on the platform. The user must first set a PIN code or a password regarding the secure element.
RENEWED: The certificate is renewed by the user's self-service page on the platform.
CANCELLED: The request is cancelled and the digital certificate can not be issued.
Scratchcard
It is a virtual scratch card containing the secret codes of the user.
The card contains:
It is important to notice that a scratchcard can be used only once. Every request must be associated with a different scratchcard.
The common digital certificate generation process involves the following steps:
1) CREATION OF A REQUEST
2) UPLOAD DOCUMENTS
3) REQUEST APPROVAL
4) CLOUD/SOFTWARE ENROLLMENT
STEP 1: CREATION OF A REQUEST
API reference: Create Request
This call must include enough information to identify the requester user. The full description of the arguments accepted by this endpoint can be found in the API call detailed documentation.
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
"profile": "PFnubeAFCiudadano",
"scratchcard": "5053311",
"secure_element": "2",
"registration_authority": "116",
"country_name": "ES",
"serial_number": "12345678A",
"id_document_country": "ES",
"id_document_type": "IDC",
"given_name": "Name",
"surname_1": "Surname1",
"surname_2" "Surname2"
"email": "mail@domain.com",
"mobile_phone_number": "+34611223344",
"paperless_mode": 1
}'The response is a JSON containing info from the created request. One of the most important parameters from this JSON is the pk which represents the request unique identifier and is used for every operation related to this request.
{
"pk": 11223,
"given_name": "Name",
"surname_1": "Surname1",
"surname_2": "Surname2",
"sex": null,
"id_document_type": "IDC",
"id_document_country": "ES",
"serial_number": "12345678A",
"country_name": "ES",
"citizenship": null,
"residence": null,
"organization_email": null,
"email": "mail@domain.com",
"title": null,
"organization_name": null,
"organizational_unit_1": null,
...
}STEP 2: UPLOAD DOCUMENTS
API reference: Upload Document
The created request needs documents, so we can query with an HTTP POST request to upload the files.
The required documents for every request are:
document_front : The photo of the front side of the requester ID card
document_rear : The photo of the rear side of the requester ID card
extra_document : If necessary, it is possibile to upload extra documents that represents additional requester information
Additionally a selfie of the requester showing the ID card under the chin can be uploaded as an evidence under the type document_owner.
Note that this endpoint has to be queried for every document type that the Request needs.
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/11223/pl_upload_document/' \
--cert 'cer.pem' --key 'key.pem'
-H 'Content-Type: multipart/form-data' \
-F document=@/idc_front.jpg \
-F type=document_frontThe response contains the uploaded document unique identifier associated to the request.
{
"pk": 11314,
"type": "document_front"
}STEP 3: REQUEST APPROVAL
If all information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate. These calls are shown below:
API Reference: Generate RAO Declaration
curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/generates_tbs_receipt/ \
-H 'Content-Type: application/json' \
-d '{
"rao": "1400",
"type": "APPROVE"
}'The following JSON object contains the receipt:
{
"serial_number": "3ef3696d2939241d",
"receipt": "El operador RAO_Name RAO_Surname1 con número de identificación 12345678P\r\nactuando en calidad de operador autorizado de registro del prestador de servicios\r\n
de confianza UANATACA, S.A. con NIF A66721499, (UANATACA en lo sucesivo)\r\n\r\nDECLARA\r\n\r\nQue previa verificación de acuerdo a la Declaración de Prácticas de
UANATACA\r\npublicadas en www.uanataca.com, la información detallada a continuación es\r\ncorrecta y será incluida (donde aplicable) en la solicitud de
certificados\r\ncualificados:\r\n\r\n- Datos de Identificación de la solicitud de certificados: 36893\r\n- Nombre y Apellidos del Firmante: Name Surname1 Surname2\r\n- DNI/
NIE/PASAPORTE del Firmante: 11111111B\r\n- Dirección de correo electrónico del Firmante: mail@domain.com\r\n\r\n\r\n18/03/
2021\r\n\r\n\r\n\r\n--------------------------------------------------------------------\r\nFdo. User Admin\r\nOperador autorizado de registro"
}Similarly, it is necessary to retrieve the service contract and present it to the RAO before approval.
API Reference: Generate Contract (type: contract)
curl -i -X POST https://api.uanataca.com/api/v1/requests/25139/pl_get_document/ \
-H 'Content-Type: application/json' \
-d '{
"type": "contract"
"rao_id": "1400"
}'The response consists in a JSON structure containing the contract in Base64 format.
[
{
"document": "JVBERi0xLjQKJZOMi54gUmVwb3J0TGFiIEdlbmVyYXRlZCBQREYgZG9jdW1lbnQgaHR0cDovL3d3\ndy5yZXBvcnRsYWIuY29tCjEgMCBvYmoKPDwKL0YxIDIgMCBSCj4 (...)\n",
"type": "contract"
}
]API reference: Approve Request
A Registration Authority Officer must first validate the request data and documentation. If the information is correct, the RAO will approve the request by signing the receipt and contract with his or her own cloud certificate.
In order to approve a Request, this must be in the status of CREATED and must have at least the required documents (document_front and document_rear).
curl -i -X POST 'https://api.uanataca.com/api/v1/requests/' \
-H 'Content-Type: application/json' \
--cert 'cer.pem' --key 'key.pem'
-d '{
"username": "1000279",
"password": "3DPTm:N4",
"pin": "23bYQq9a",
"rao_id": 123
}'STEP 4: CLOUD/SOFTWARE ENROLLMENT
In this step, the service contract must be presented to the signer before enrollment.
API Reference: Generate Contract (Body type: contract)
There are different endpoints to enroll a request depending on the secure element chosen. The next action involves sending an otp code to the requester using the calls shown below. Software and cloud certificates use the same call to send the otp code, as cloud-qscd certificates use a different one.
API Reference: Generate OTP (Cloud or Software)
API Reference: Generate OTP (Cloud or QSCD)
SOFTWARE
API reference: Software Enroll
For the Software enrollemnt the parameters required are the secret OTP code send to the requester and the p12password set by the requester to import the generated p12:
{
"secret": "000000",
"p12password": "password12"
}At the end of the enrollment the server replies with the P12 generated in PEM format.
CLOUD
API reference: Cloud Enroll
For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:
{
"secret": "000000",
"pin": "pincode12"
}At the end of the enrollment the server replies with a JSON containing all requesta data.
CLOUD-QSCD
API reference: Cloud-QSCD Enroll
For the cloud enrollemnt the parameters required are the secret OTP code send to the requester and the PIN code set by the requester to use the generated certificate:
{
"secret": "000000",
"pin": "pincode12"
}At the end of enrollment the server replies with a JSON containing all request data.
PROCESS COMPLETION
For correct process completion, the following information must be delivered to the requester:
The certificate in .p12 format (Software Enroll)
The certificate set of credentials (Cloud Enroll)
The contract signed by both parties. Available when executing the Get Signed Contract call (Body type: signed_contract)
OPTIONAL
API Reference: Get Request