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:

  • cryptoapi.access.bit4id.org:13035 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

VERIFY PIN

Verifies if the specified PIN is valid.

Request Body schema: application/json
username
required
string

SignCloud account username

password
required
string

SignCloud account password

pin
required
string

SignCloud account PIN

Responses

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/verify_pin \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "pin": "w98nZZDR"
  }'

Response samples

Content type
application/json
{
  • "result": true,
  • "error": null
}

CHANGE PIN

Changes a token PIN.

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

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/change_pin \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "pin": "w98nZZDR",
    "newpin": "newpin12"
  }'

Response samples

Content type
application/json
{
  • "result": true,
  • "error": null
}

UNLOCK PIN

Unlocks the PIN of a locked token.

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

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/unlock_pin \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "newpin": "w98nZZDR",
    "puk": "b5UGHR2u"
  }'

Response samples

Content type
application/json
{
  • "result": true,
  • "error": null
}

RSA

Sign and decrypt Base64 buffers or get objects associated to a SignCloud account.
MethodEndpointAction
POST/get_objectsRetrieve the public key and certificate of a specified SignCloud account
POST/sign_rsaSign a base64 encoded buffer
POST/decrypt_rsaDecrypt a base64 buffer

GET OBJECTS

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

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.

Responses

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/get_objects \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "type": "null",
    "identifier": "DS0"
  }'

Response samples

Content type
application/json
{
  • "result": [
    ],
  • "error": null
}

SIGN RSA

Signs a base64 encoded buffer.

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

Responses

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/sign_rsa \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "pin": "w98nZZDR",
    "identifier": "DS0",
    "mechanism": "RSARAW",
    "plaintext": "T3V0IG1lc3NhZ2UK",
    "billing_username": "billing_user@domain",
    "billing_password": "z5qNqkfB"
  }'

Response samples

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

billing_username
required
string

Billing account username

billing_password
required
string

Billing account password

Responses

Request samples

curl -i -X POST \
  https://cryptoapi.access.bit4id.org:13035/api/sign_rsa \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "1122338",
    "password": "7T8xdGBN",
    "pin": "w98nZZDR",
    "identifier": "DS0",
    "mechanism": "RSARAW",
    "plaintext": "T3V0IG1lc3NhZ2UK",
    "billing_username": "billing_user@domain",
    "billing_password": "z5qNqkfB"
  }'

Response samples

Content type
application/json
{
  • "result": "T3VyIG1lc3NhZ2UK",
  • "error": null
}