UANATACA SIGNCLOUD API DOCUMENTATION (1.0)

What it is

SignCloud is a solution to perform remote RSA transactions. Cryptographic operations are done in Uanataca Trusted Service Center side, where signature keys are stored in a Qualified Electronic Signature Creation Device (QSCD) system.

How it works

An http RESTful API is exposed directly from Uanataca Trusted Service Center.

For the execution of signature requests, the hash of the document to be signed must be sent along with the credentials of the SignCloud account that should perform the signature.

In case of authentication, the cyphertext that must be decrypted must be sent along with the credentials of the SignCloud account that is required to perform the authentication.

Additionally, client applications like Signature Creation Application (SCA) can be interfaced with the remote RSA objects using and extended middleware library that implements the standard cryptographic interfaces for each operating system (PKCS#11, MS CSP, TokenD).


Endpoint URLs

In order to use SignCloud API, every url must be composed as follows:

https://{signcloudhost}/api/{resource}

The {signcloudhost} changes according to the environment:

  • signcloud.access.bit4id.org:13035/json if the environment is test
  • cryptoapi.uanataca.com if the environment is production

and {resource} is the name of the resource of our interest.

Example:

https://cryptoapi.uanataca.com/api/sign_rsa

Requests

Every request made to SignCloud must have as content type header "application/json", so the request body must be a JSON object.

Example

A simple HTTP POST request made with curl.

1 | curl -H "Content-Type: application/json" -d @params.json -X POST https://{signcloudhost}/api/sign_rsa

Responses

The response of each api call is a JSON object with just 2 keys:

resultIn case of success it is setted to True or contains some other values. Otherwise it is None
error In case of success its value is null. Otherwise it is a JSON object containing the error occured. This object has three keys: "msg" the error message, "code" the HTTP status code and "details" which can contain some extra info about the error.

Examples

Here are listed some example responses returned by SignCloud

1 | {
2 |     "result": "fp+6Ull5WbTRqbMtW5R80DVhX+Qcoev0OqiDcIwy3sJYtmBP2RtC6NgukFIALpbUR
3 |     Dd3izbmjqx8GVF8/BO/vAaqIE5H+xzA553OCvBijXr4KV1W/VY70yEfS1u25xogjZjRj4tg9qEKu
4 |     mvdA62qT5S0bgxpyL5ESBlrWY9oVaAiamIwfsw3VJQC6Lft/JJuE067oqd4DkvOy6RE1DMzk/imq
5 |     ffCTfG+LG1fRV/JL3l7gMPO+mAcsTVeUOSC1hpZEDgahdQJmv3ec7wJazc+7eArulCmPQHsAJS4O
6 |     2AkXOb08/3XH5fH5b4B8vbLiWZG0SPT0adpfRI0euCXirDMBw==",
7 |     "error": null
8 | }

1 | {
2 |     "result": None,
3 |     "error": {
4 |         "msg": "Token locked",
5 |         "code": 403,
6 |         "details": ""
7 |     }
8 | }

1 | {
2 |     "result": null,
3 |     "error": {
4 |         "msg": "Missing parameter",
5 |         "code": 412,
6 |         "details": "'puk'"
7 |     }
8 | }

1 | {
2 |     "result": None,
3 |     "error": {
4 |         "msg": "Pin invalid",
5 |         "code": 403,
6 |         "details": ""
7 |     }
8 | }

HTTP Status Codes

Below a list of HTTP codes, and their description, that can be returned by SignCloud

CodeDescription
401Invalid Credentials
403Token Not Found
403Pin Invalid
403Token Locked
407Authentication Refused
412Missing Parameter
500Internal Server Error

Postman collection

A postman collection is available as a support for a quick start.

SignCloud Postman collection download

API Reference

Token

A virtual token is a cloud certificate associated to a SignCloud account.
MethodEndpointAction
POST/verify_pinVerify if the virtual token PIN is valid
POST/change_pinChange a virtual token PIN
POST/unlock_pinUnlock the PIN of a locked virtual token
POST/get_objectsRetrieve the public key and certificate of a specified SignCloud account

VERIFY PIN

Verifies if the specified PIN is valid.

Request
Request Body schema: application/json
username
required
string

SignCloud account username

password
required
string

SignCloud account password

pin
required
string

SignCloud account PIN

Responses
200

Successful Response

401

Invalid Credentials

403

Invalid username or pin , User locked

412

Missing parameter in JSON object

420

Authentication refused (after 3 failed attempts)

post/api/verify_pin
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "pin": "string"
}
Response samples
application/json
{
  • "result": true,
  • "error": null
}

CHANGE PIN

Changes a token PIN.

Request
Request Body schema: application/json
username
required
string

SignCloud account username

password
required
string

SignCloud account password

pin
required
string

SignCloud account PIN

newpin
required
string

The new SignCloud account PIN

Responses
200

Successful Response

401

Invalid password

403

Invalid username or pin , User locked

412

Missing parameter in JSON object

420

Authentication refused (after 3 failed attempts)

500

Internal Server Error

post/api/change_pin
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "pin": "string",
  • "newpin": "string"
}
Response samples
application/json
{
  • "result": true,
  • "error": null
}

UNLOCK PIN

Unlocks the PIN of a locked token.

Request
Request Body schema: application/json
username
required
string

SignCloud account username

password
required
string

SignCloud account password

newpin
required
string

The new SignCloud account PIN

puk
required
string

The token PUK

Responses
200

Successful Response

401

Invalid password

403

Invalid username or puk

412

Missing parameter in JSON object

420

Authentication refused (after 3 failed attempts)

post/api/unlock_pin
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "newpin": "string",
  • "puk": "string"
}
Response samples
application/json
{
  • "result": true,
  • "error": null
}

GET OBJECTS

Retrieves the public key or the certificate of a specified SignCloud account.

Request
Request Body schema: application/json

JSON object that includes the user credentials for verification.

username
required
string

SignCloud account username

password
required
string

SignCloud account password

type
required
string

The object type. Allowed values are: PublicKey = 3; Certificate = 4; Both = null

Enum: "null" "3" "4"
identifier
required
string
Default: "DS0"

Identifier of the pair of keys. Null value retrieves all the objects that the token contains.

Enum: "DS0" "DS1" "null"
Responses
200

Successful Response

401

Invalid password

403

Invalid username , User locked

412

Missing parameter in JSON object

420

Authentication refused (after 3 failed attempts)

500

Internal Server Error. identifier or mechanism not supported

post/api/get_objects
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "type": "null",
  • "identifier": "DS0"
}
Response samples
application/json
{
  • "result": [
    ],
  • "error": null
}

RSA

Sign and decrypt Base64 buffers or get objects associated to a SignCloud account.
MethodEndpointAction
POST/generate_otpGenerates an otp for the specified digital identity
POST/sign_rsaSign a base64 encoded buffer
POST/decrypt_rsaDecrypt a base64 buffer

OTP

Generates an otp for the specified digital identity.

⚠This method is only required and available for specific digital identities

Request
Request Body schema: application/json

JSON object that includes the user credentials for verification.

username
required
string

SignCloud account username

password
required
string

SignCloud account password

uses
required
number

Given uses to OTP

Responses
200

Successful Response

post/api/generate_otp
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "uses": 0
}
Response samples
application/json
{
  • "result": {
    },
  • "error": null
}

SIGN RSA

Signs a base64 encoded buffer.

Request
Request Body schema: application/json

JSON object that includes the user credentials for verification.

username
required
string

SignCloud account username

password
required
string

SignCloud account password

pin
required
string

SignCloud account PIN

identifier
required
string
Default: "DS0"

Identifier of the pair of keys

mechanism
required
string

Algorithm used for signing. Supported algorithms are: RSAMD5; RSASHA1; RSASHA256; RSASHA512; RSARAW;

plaintext
required
string

Base64 encoded buffer for signing

billing_username
required
string

Billing account username

billing_password
required
string

Billing account password

otp
string

The OTP code previously sent to the user. This parameter is only required and available for specific digital identities

Responses
200

Successful Response

401

Invalid password

403

Invalid username or pin , User locked

412

Missing parameter in JSON object

420

Authentication refused (after 3 failed attempts)

500

Internal Server Error. Wrong identifier or mechanism or billing_username or billing_password

post/api/sign_rsa
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "pin": "string",
  • "identifier": "DS0",
  • "mechanism": "string",
  • "plaintext": "string",
  • "billing_username": "string",
  • "billing_password": "string",
  • "otp": "string"
}
Response samples
application/json
{
  • "result": "iaJp+O8CxSOPlPL4Eg4KBnlXDG+6g16wgp4ihVLIu3tJDIWFUFUHNgF/8+R1x3TJg4dCpKk6h3Tf+PapnJjGBgxnLeIA5nvdvKFu99Zlm0mS0Y6yjy6wMCEocWFtV+UBVpgXeDHae3XuiSHFu8c9TM7zdlnfmPRkZNHlb+HgafczuMAOfVsPepYsI4qlFIjS76v/6IczeGHV/aeSOa24jyNQsuVgBmbhHqqB8XQS9hHf+rQhvAgFv1o35HRgVDoNr93lkTflT88cjY+ip8ndc2QyY2nuuZmE4OR0ElGUV+9h+6/HMpl0hkHTX/NGRSdipHnZ93bNAahRRVK4okQLRQ==",
  • "error": null
}

DECRYPT RSA

Decrypts a base64 buffer.

Request
Request Body schema: application/json

JSON object that includes the user credentials for verification.

username
required
string

SignCloud account username

password
required
string

SignCloud account password

pin
required
string

SignCloud account PIN

identifier
required
string
Default: "DS0"

Identifier of the pair of keys

ciphertext
required
string

Text to decrypt

Responses
200

Successful Response

401

Invalid password

403

User locked or Invalid username or pin

420

Authentication refused (after 3 failed attempts)

500

Internal Server Error

post/api/decrypt_rsa
Request samples
application/json
{
  • "username": "string",
  • "password": "string",
  • "pin": "string",
  • "identifier": "DS0",
  • "ciphertext": "string"
}
Response samples
application/json
{
  • "result": "Decrypted output",
  • "error": null
}