Installation and usage of the platform

REST API: generation and checking of data digital signatures

https://img.shields.io/badge/auth-required-orange.svg

On the networks using GOST cryptography, you can use the REST API interface to form a detached electronic signature for transmitted data, as well as to verify it. To form and verify electronic signature, use the pki group methods: POST /pki/sign and POST /pki/verify.

All methods of the group are available only for networks with GOST cryptography.

GET ​/pki​/keystoreAliases

The method returns a list with the names of all available signature private key storages.

Response example:

GET ​/pki​/keystoreAliases:
{
   [
    "3Mq9crNkTFf8oRPyisgtf4TjBvZxo4BL2ax",
    "e19a135e-11f7-4f0c-9109-a3d1c09812e3"
   ]
 }

POST /pki/sign

The method generates a disconnected DS for the data transmitted in the request.

Important

The /pki/sign method is not available when PKI is used, that is, when the node configuration file parameter node.crypto.pki.mode is set to ON. The method can be used in PKI test mode (node.crypto.pki.mode = TEST) or with PKI disabled (node.crypto.pki.mode = OFF).

The POST /pki/sign method request consists of the following fields:

  • inputData – data for which a DS is required (as an array of bytes in base64 encoding);

  • keystoreAlias – name of the storage for the DS private key;

  • password – a password for the private key storage;

  • sigType – DS format. Supported formats:

    • 1 – CAdES-BES;

    • 2 – CAdES-X Long Type 1;

    • 3 – CAdES-T.

    Query example:

    POST /pki/sign:
    {
  "inputData" : "SGVsbG8gd29ybGQh",
  "keystoreAlias" : "key1",
  "password" : "password",
  "sigType" : 1,
}

The method returns the signature field containing the generated disconnected DS.

Response example:

POST /pki/sign:
{
  "signature" : "c2RmZ3NkZmZoZ2ZkZ2hmZGpkZ2ZoamhnZmtqaGdmamtkZmdoZmdkc2doZmQjsndjfvnksdnjfn="
}

POST /pki/verify

The method is designed to verify the disconnected DS for the data transmitted in the request. The request consists of the following fields:

  • inputData – data, signed by a DS, as an array of bytes in base64 encoding;

  • signature – digital signature in the form of an array of bytes in base64 encoding;

  • sigType – DS format. Supported formats:

    • 1 – CAdES-BES;

    • 2 – CAdES-X Long Type 1;

    • 3 – CAdES-T;

  • extendedKeyUsageList – optional field to pass a list of object identifiers (OIDs) of cryptographic algorithms that are used in DS generation, in the method request.

Query example:

POST /pki/verify:
{
 "inputData" : "SGVsbG8gd29ybGQh",
 "signature" : "c2RmZ3NkZmZoZ2ZkZ2hmZGpkZ2ZoamhnZmtqaGdmamtkZmdoZmdkc2doZmQ=",
 "sigType" : "CAdES_X_Long_Type_1",
 "extendedKeyUsageList": [
 "1.2.643.7.1.1.1.1",
 "1.2.643.2.2.35.2"
 ]
 }

Method’s response contains a sigStatus field with boolean data type: true – signature is valid, false – signature is compromised.

Response example:

POST /pki/verify:
{
  "sigStatus" : "true"
}

Verifying an advanced qualified digital signature

The POST /pki/verify method has the ability to verify an advanced qualified digital signature. To verify the AQDS correctly, install the root AQDS certificate of the certification authority (CA) on your node, which will be used to validate the signature.

The root certificate is installed in the cacerts certificate storage of the Java virtual machine (JVM) you are using the keytool utility:

sudo keytool -import -alias certificate_alias -keystore path_to_your_JVM/lib/security/cacerts -file path_to_the_certificate/cert.cer

After the -alias flag, specify your preferred certificate name in the repository.

The cacerts certificate storage is located in the /lib/security/ subdirectory of your Java virtual machine. To find out the path to the virtual machine on Linux, use the following command:

readlink -f /usr/bin/java | sed "s:bin/java::"

Then add /lib/security/cacerts to the resulting path and paste the resulting absolute path to cacerts after the ` -keystore` flag.

After the -file flag, specify the absolute or relative path to the received EDS certificate of the Certification Authority.

The default password for cacerts is changeit. If necessary, you can change it using the keytool utility:

sudo keytool -keystore cacerts -storepasswd
See also

REST API methods

Cryptography