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

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) методы можно использовать.

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": "AIvanov@org.com",
  "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": "AIvanov@org.com",
  "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": "AIvanov@org.com",
  "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": "AIvanov@org.com",
    "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":"AIvanov@org.com",
                  "comment":"Comment"
               }
            },
            {
               "hash":"e67ad392ab4d933f39d5723aeed96c18c491140e119d590103e7fd6de15623f1",
               "sender":"3HYW75PpAeVukmbYo9PQ3mzSHdKUgEytUUz",
               "type":"file",
               "info":{
                  "filename":"Contract №101/5.doc",
                  "size":"2048",
                  "timestamp":1000000000,
                  "author":"AIvanov@org.com",
                  "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