Установка и использование платформы

REST API: обмен конфиденциальными данными и получение информации о группах доступа

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

Подробнее об обмене конфиденциальными данными и группах доступа см. статью Обмен конфиденциальными данными.

Для реализации этих функций при помощи REST API предусмотрен набор методов группы Privacy.

Важно

Методы группы Privacy недоступны при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) методы можно использовать.

Авторизация методов группы Privacy

:opticon:`report, size=24` Авторизация методов группы Privacy:

Для использования методов REST API группы Privacy требуется авторизация по api-key или JWT-токену. Авторизация методов реализована следующим образом:

  • в случае api-key авторизации требуется PrivacyApiKey;

  • в случае OAuth2 авторизации требуется наличие роли Privacy в JWT токене.

Для каждого из методов необходимо передавать следующие данные:

  • policyRecipients — contractAuth | userAuth;

  • policyOwners — userAuth;

  • policyHashes — contractAuth | userAuth;

  • policyItemData — contractAuth | privacyAuth;

  • policyItemLargeData — contractAuth | privacyAuth;

  • policyItemInfo — contractAuth | privacyAuth;

  • policyItemsInfo — contractAuth | privacyAuth;

  • sendData — privacyAuth;

  • sendDataV2 — privacyAuth;

  • forceSync — privacyAuth;

  • forceSyncByPolicyId — privacyAuth;

  • sendLargeData — privacyAuth,

где

  • contractAuth — токен авторизации смарт контракта, передаваемый в заголовке „X-Contract-Api-Token“ к запросу;

  • userAuth — api-key пользователя, передаваемый в заголовке „X-Api-Key“ к запросу ИЛИ передача JWT токена с ролью user в заголовке „Authorization“;

  • privacyAuth — api-key privacy пользователя в заголовке „X-Api-Key“ к запросу ИЛИ передача JWT токена с ролью privacy в заголовке „Authorization“.

Кроме того, авторизация gRPC и REST API настраивается в секции auth конфигурационного файла ноды.

POST /privacy/sendData

Метод предназначен для отправки в блокчейн конфиденциальных данных, доступных только для участников группы доступа, определенной для этих данных.

Примечание

Для отправки данных размером более 20 МБ используйте метод POST /privacy/sendLargeData.

Важно

Метод /privacy/sendData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

Запрос метода POST /privacy/sendData должен содержать следующую информацию:

  • sender – блокчейн-адрес, от которого должны рассылаться данные (соответствуют значению параметра privacy.owner-address в конфигурационном файле ноды);

  • password – пароль для доступа к закрытому ключу keystore ноды;

  • policyId – идентификатор группы, которая будет иметь доступ к отправляемым данным;

  • info – информация об отправляемых данных:

    • filename – имя файла данных,

    • size – размер файла данных,

    • timestamp – временная метка,

    • author – электронный адрес автора отправляемых данных,

    • comment – произвольный комментарий.

  • data – строка, содержащая данные в формате base64;

  • hash – sha256-хэш данных в формате base58;

  • broadcast – если передается значение true, то созданная PolicyDataHash транзакция отправляется в блокчейн, если false, то транзакция и сообщение о наличии данных (Privacy Inventory) не отправляется; подробнее см. ниже.

  • certificates – цепочка сертификатов байтами в формате DER; параметр является обязательным при одновременном соблюдении следующих условий:

    • используется тестовый режим PKI (то есть в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение TEST),

    • новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию.

    В этом случае необходимо в запросе в поле certificates передать цепочку сертификатов пользователя; в других случаях поле certificates является необязательным.

Примечание

При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.

В результате отправки запроса будет сформирована транзакция 114 PolicyDataHash, которая отправит хэш конфиденциальных данных в блокчейн.

Параметр broadcast

Для снижения вероятности ошибок доставки данных рекомендуется установить для параметра broadcast значение false, если после отправки данных с помощью API метода sendData отправляется атомарная транзакция, которая содержит транзакцию CreatePolicy и транзакцию PolicyDataHash.

Примеры запроса и ответа:

POST /privacy/sendData:

Запрос:

{
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"password": "apgJP9atQccdBPA",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"info": {
  "filename":"Service contract #100/5.doc",
  "size": 2048,
  "timestamp": 1000000000,
  "author": "[email protected]",
  "comment": "some comments"
 },
 "data": "TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0aGlzIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1c3Qgb2YgdGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0aGUgY29udGludWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdlLCBleGNlZWRzIHRoZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=",
 "hash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta"
 "broadcast": false
 }

Ответ:

{
"senderPublicKey": "Gt3o1ghh2M2TS65UrHZCTJ82LLcMcBrxuaJyrgsLk5VY",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"dataHash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta",
"proofs": [
"2jM4tw4uDmspuXUBt6492T7opuZskYhFGW9gkbq532BvLYRF6RJn3hVGNLuMLK8JSM61GkVgYvYJg9UscAayEYfc"
],
"fee": 110000000,
"id": "H3bdFTatppjnMmUe38YWh35Lmf4XDYrgsDK1P3KgQ5aa",
"type": 114,
"timestamp": 1571043910570
}

POST /privacy/sendDataV2

Метод POST /privacy/sendDataV2 аналогичен методу POST /privacy/sendData, однако позволяет приложить файл в окне Swagger, не прибегая к его конверсии в формат base64. Метод предоставляет возможность потоковой передачи данных. Поле Data в этой версии метода отсутствует.

Примечание

Для отправки данных размером более 20 МБ используйте метод POST /privacy/sendLargeData.

Примечание

При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.

Примечание

Когда новый пользователь, который не является владельцем ноды (node-owner), в тестовом режиме PKI (параметру node.crypto.pki.mode присвоено значение TEST) делает свою первую транзакцию, ему необходимо в запросе в поле certificates приложить цепочку своих сертификатов. В других случаях поле certificates является необязательным.

Важно

Метод /privacy/sendDataV2 недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

Примеры запроса и ответа:

POST /privacy/sendDataV2:

Запрос:

{
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"password": "apgJP9atQccdBPA",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"info": {
  "filename":"Service contract #100/5.doc",
  "size": 2048,
  "timestamp": 1000000000,
  "author": "[email protected]",
  "comment": "some comments"
 },
 "hash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta"
 "broadcast": false
 }

Ответ:

{
"senderPublicKey": "Gt3o1ghh2M2TS65UrHZCTJ82LLcMcBrxuaJyrgsLk5VY",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"dataHash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta",
"proofs": [
"2jM4tw4uDmspuXUBt6492T7opuZskYhFGW9gkbq532BvLYRF6RJn3hVGNLuMLK8JSM61GkVgYvYJg9UscAayEYfc"
],
"fee": 110000000,
"id": "H3bdFTatppjnMmUe38YWh35Lmf4XDYrgsDK1P3KgQ5aa",
"type": 114,
"timestamp": 1571043910570
}

POST /privacy/sendLargeData

Метод POST /privacy/sendLargeData аналогичен методу POST /privacy/sendDataV2, но используется для отправки данных размером не менее 20 МБ.

Примечание

Для отправки данных размером менее 20 МБ используйте методы POST /privacy/sendData и POST /privacy/sendDataV2.

В конфигурационном файле ноды в секции node.privacy.service можно настроить обратное давление на входящие фрагменты данных: задать максимальный размер для буфера в памяти (по умолчанию – 100 МБ

Примечание

При отправке файлов через Amazon S3/Minio в полях comment, author, filename должны быть ascii символы. Это ограничение Java SDK AWS.

Примечание

Когда новый пользователь, который не является владельцем ноды (node-owner), в тестовом режиме PKI (параметру node.crypto.pki.mode присвоено значение TEST) делает свою первую транзакцию, ему необходимо в запросе в поле certificates приложить цепочку своих сертификатов. В других случаях поле certificates является необязательным.

Важно

Метод /privacy/sendLargeData недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

Примеры запроса и ответа:

POST /privacy/sendLargeData:

Запрос:

{
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"password": "apgJP9atQccdBPA",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"info": {
  "filename":"Service contract #100/5.doc",
  "size": 2048,
  "timestamp": 1000000000,
  "author": "[email protected]",
  "comment": "some comments"
 },
 "hash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta"
 "broadcast": false
 }

Ответ:

{
"senderPublicKey": "Gt3o1ghh2M2TS65UrHZCTJ82LLcMcBrxuaJyrgsLk5VY",
"policyId": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
"sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
"dataHash": "FRog42mnzTA292ukng6PHoEK9Mpx9GZNrEHecfvpwmta",
"proofs": [
"2jM4tw4uDmspuXUBt6492T7opuZskYhFGW9gkbq532BvLYRF6RJn3hVGNLuMLK8JSM61GkVgYvYJg9UscAayEYfc"
],
"fee": 110000000,
"id": "H3bdFTatppjnMmUe38YWh35Lmf4XDYrgsDK1P3KgQ5aa",
"type": 114,
"timestamp": 1571043910570
}

GET /privacy/{policy-id}/recipients

Метод предназначен для получения адресов всех участников, записанных в группу {policy-id}.

В ответе метода возвращается массив строк с адресами участников группы доступа.

Пример ответа:

GET /privacy/{policy-id}/recipients:
[
  "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "3Mx2afTZ2KbRrLNbytyzTtXukZvqEB8SkW7"
]

Важно

Метод GET /privacy/{policy-id}/recipients недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET /privacy/{policy-id}/owners

Метод предназначен для получения адресов владельцев группы доступа {policy-id}.

В ответе метода возвращается массив строк с адресами владельцев группы доступа.

Пример ответа:

GET /privacy/{policy-id}/owners:
[
  "3GCFaCWtvLDnC9yX29YftMbn75gwfdwGsBn",
  "3GGxcmNyq8ZAHzK7or14Ma84khwW8peBohJ",
  "3GRLFi4rz3SniCuC7rbd9UuD2KUZyNh84pn",
  "3GKpShRQRTddF1yYhQ58ZnKMTnp2xdEzKqW"
]

Важно

Метод GET /privacy/{policy-id}/owners недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET /privacy/{policy-id}/hashes

Метод предназначен для получения массива идентификационных хэшей данных, которые привязаны к группе доступа {policy-id}.

В ответе метода возвращается массив строк с идентификационными хэшами данных группы доступа.

Пример ответа:

GET /privacy/{policy-id}/hashes:
[
  "FdfdNBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "eedfdNBVqYXrapgJP9atQccdBPAgJPwHDKkh6A"
]

Важно

Метод GET /privacy/{policy-id}/hashes недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET /privacy/{policyId}​/getData/{policyItemHash}

Метод предназначен для получения пакета конфиденциальных данных группы доступа {policyId} по идентификационному хэшу {policyItemHash}.

В ответе метода возвращается хэш-сумма конфиденциальных данных.

Пример ответа:

GET /privacy/{policyId}​/getData/{policyItemHash}:
c29tZV9iYXNlNjRfZW5jb2RlZF9zdHJpbmc=

Важно

Метод GET /privacy/{policyId}​/getData/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET /privacy/{policyId}/getLargeData/{policyItemHash}

Метод предназначен для получения пакета конфиденциальных данных группы доступа {policyId} по идентификационному хэшу {policyItemHash}.

Метод возвращает стрим, что позволяет пользователю скачать файл с данными неограниченного объёма.

Важно

Метод GET /privacy/{policyId}/getLargeData/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET ​/privacy​/{policyId}​/getInfo​/{policyItemHash}

Метод предназначен для получения метаданных для пакета конфиденциальных данных группы {policyId} по идентификационному хэшу {policyItemHash}.

В ответе метода возвращаются следующие данные:

  • sender – адрес отправителя конфиденциальных данных;

  • policy_id – идентификатор группы доступа;

  • type – тип конфиденциальных данных (file);

  • info – массив данных о файле:

    • filename – имя файла;

    • size – размер файла;

    • timestamp – временная метка размещения файла в формате Unix Timestamp (в миллисекундах);

    • author – автор файла;

    • comment – опциональный комментарий к файлу;

  • hash – идентификационный хэш конфиденциальных данных.

Пример ответа:

GET ​/privacy​/{policyId}​/getInfo​/{policyItemHash}:
{
  "sender": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
  "policy": "4gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaC",
  "type": "file",
  "info": {
    "filename": "Contract №100/5.doc",
    "size": 2048,
    "timestamp": 1000000000,
    "author": "[email protected]",
    "comment": "Comment"
  },
"hash": "e67ad392ab4d933f39d5723aeed96c18c491140e119d590103e7fd6de15623f1"
}

Важно

Метод GET ​/privacy​/{policyId}​/getInfo​/{policyItemHash} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

POST /privacy/forceSync

Метод предназначен для принудительного получения пакета конфиденциальных данных. Применяется в случае, если транзакция с конфиденциальными данными для группы доступа присутствует в блокчейне, но по какой-либо причине эти данные не были записаны в хранилище конфиденциальных данных ноды. В этом случае метод позволяет принудительно скачать отсутствующие данные. Метод синхронизирует данные по всем группам доступа к конфиденциальным данным.

Запрос метода содержит следующие данные:

  • sender – адрес ноды-участника группы доступа, отправляющей запрос;

  • policy – идентификатор группы доступа;

  • source – адрес ноды, с которой должны скачиваться отсутствующие данные. В случае, если нода неизвестна, установите параметр на null или оставьте поле пустым: в этом случае скачивание файла будет произведено из хранилища первой ноды из списка группы доступа.

Ответ метода содержит поле result с результатом получения данных и поле message с текстом возможной ошибки. В случае успешного получения возвращается значение success, конфиденциальные данные записываются в хранилище ноды.

В случае возникновения ошибки возвращается значение error, в поле message приводится описание ошибки.

Примеры запроса и ответа:

POST /privacy/forceSync:

Запрос:

{
  "sender": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "policy": "my_policy"
  "source": "3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
}

Ответ:

{
  "result": "error"
  "message": "Address '3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8' not in policy 'my_policy'"
}

Важно

Метод POST /privacy/forceSync недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

GET /privacy/forceSync/{policyId}

Метод аналогичен методу POST /privacy/forceSync с той разницей, что синхронизирует данные по указанной группе доступа к конфиденциальным данным (policyId).

Важно

Метод GET /privacy/forceSync/{policyId} недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

POST /privacy/getInfos

Метод предназначен для получения массива метаданных конфиденциальных данных по идентификатору группы доступа и идентификационному хэшу.

Запрос метода содержит следующие данные:

  • policiesDataHashes – массив данных с двумя элементами для каждой отдельной группы доступа:

    • policyId – идентификатор группы доступа,

    • datahashes – массив хэшей конфиденциальных данных для получения метаданных по каждому из них.

В ответе метода для каждого отдельного хэша конфиденциальных данных возвращается массив данных, аналогичный ответу метода GET ​/privacy​/{policyId}​/getInfo​/{policyItemHash}.

Примеры запроса и ответа:

POST /privacy/getInfos:

Запрос:

{ "policiesDataHashes":
  [
   {
    "policyId": "somepolicyId_1",
    "datahashes": [ "datahash_1","datahash_2" ]
   },
   {
     "policyId": "somepolicyId_2",
     "datahashes": [ "datahash_3","datahash_4" ]
   }
  ]
 }

Ответ:

{
   "policiesDataInfo":[
      {
         "policyId":"somepolicyId_1",
         "datasInfo":[
            {
               "hash":"e67ad392ab4d933f39d5723aeed96c18c491140e119d590103e7fd6de15623f1",
               "sender":"3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
               "type":"file",
               "info":{
                  "filename":"Contract №100/5.doc",
                  "size":2048,
                  "timestamp":1000000000,
                  "author":"[email protected]",
                  "comment":"Comment"
               }
            },
            {
               "hash":"e67ad392ab4d933f39d5723aeed96c18c491140e119d590103e7fd6de15623f1",
               "sender":"3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
               "type":"file",
               "info":{
                  "filename":"Contract №101/5.doc",
                  "size":"2048",
                  "timestamp":1000000000,
                  "author":"[email protected]",
                  "comment":"Comment"
               }
            }
            }
          ]
      ]
   }

Важно

Метод POST /privacy/getInfos недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

Смотрите также

Методы REST API

Обмен конфиденциальными данными

Тонкая настройка платформы: настройка авторизации для gRPC и REST API