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

gRPC: работа с конфиденциальными данными

Для работы с конфиденциальными данными (privacy) предусмотрены gRPC сервисы PrivacyEventsService и PrivacyPublicService.

Важно

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

Примечание

Для работы с конфиденциальными данными также можно использовать REST методы группы Privacy.

PrivacyEventsService

У сервиса PrivacyEventsService есть один метод SubscribeOn, описанный в protobuf-файле privacy_events_service.proto. Используйте этот метод для получения потока (стрима) событий по получению или удалению конфиденциальных данных, которые поступают в gRPC-интерфейс ноды. Для этого отправьте запрос SubscribeOn (SubscribeOnRequest), который инициализирует подписку на стрим.

Информация о получении или удалении конфиденциальных данных

После успешной отправки запроса на gRPC-интерфейс будут приходить следующие данные:

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

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

  • event_type – тип события; доступны следующие типы:

    • DATA_ACQUIRED – данные сохранены в БД;

    • DATA_INVALIDATED – данные помечены на удаление в связи с отсутствием активности по ним или при роллбэке (откате).

PrivacyPublicService

У сервиса PrivacyPublicService есть следующие методы, описанные в protobuf-файле privacy_public_service.proto:

Важно

Типы данных полей для запросов и ответов указаны в protobuf-файле.

Примечание

Для работы с конфиденциальными данными также можно использовать REST методы группы Privacy.

Получение хэш-суммы конфиденциальных данных

Используйте метод GetPolicyItemData для получения пакета конфиденциальных данных группы доступа по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается хэш-сумма конфиденциальных данных.

Скачивание из ноды больших данных

Используйте метод GetDataLarge для скачивания из ноды больших данных, которые были отправлены с помощью метода SendLargeData. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается поток PolicyItemDataResponse с данными.

Получение метаданных для пакета конфиденциальных данных

Используйте метод GetPolicyItemInfo для получения метаданных для пакета конфиденциальных данных группы по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращаются следующие данные:

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

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

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

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

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

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

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

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

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

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

Проверка существования пакета конфиденциальных данных

Используйте метод PolicyItemDataExists для получения информации о наличии пакета конфиденциальных данных группы доступа по идентификационному хэшу. Метод требует ввода параметров запроса policy_id (идентификатор группы доступа) и data_hash (идентификационный хэш). После успешной отправки запроса на gRPC-интерфейс возвращается true, если данные в наличии, или false, если данные отсутствуют.

Отправка в блокчейн конфиденциальных данных

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

Примечание

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

Примечание

Для отправки в блокчейн потока конфиденциальных данных используйте метод SendLargeData.

Важно

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

Метод требует ввода следующих параметров запроса:

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

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

  • data_hash – идентификационный sha256-хэш конфиденциальных данных в формате base58;

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

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

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

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

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

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

  • fee – комиссия за транзакции;

  • fee_asset_id – поле опционально и используется только для смарт-контрактов с поддержкой gRPC;

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

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

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

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

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

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

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

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

Примечание

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

После успешной отправки запроса на gRPC-интерфейс будут приходить следующие данные:

  • tx_version – версия транзакции;

  • tx – созданная PolicyDataHash транзакция.

Параметр broadcast_tx

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

Отправка в блокчейн потока конфиденциальных данных

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

Примечание

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

Важно

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

Метод принимает в запросе поток данных в следующем формате:

  • metadata – метаданные для пакета конфиденциальных данных, аналогичные входным данным метода SendData;

  • content – массив байт, представляющих собой пакет конфиденциальных данных.

После успешной отправки запроса на gRPC-интерфейс будут приходить те же данные, что и для метода SendData.

Получение адресов всех участников группы доступа к конфиденциальным данным

Используйте метод Recipients для получения адресов всех участников группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id – идентификатор группы доступа. В ответе метод возвращает массив строк с адресами участников группы доступа.

Получение адресов владельцев группы доступа к конфиденциальным данным

Используйте метод Owners для получения адресов владельцев группы доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа). В ответе метод возвращает массив строк с адресами владельцев группы доступа.

Получение массива идентификационных хэшей данных

Используйте метод Hashes для получения массива идентификационных хэшей данных, которые привязаны к группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа). В ответе метод возвращает массив строк с идентификационными хэшами данных группы доступа.

Синхронизация данных по указанной группе доступа к конфиденциальным данным

Используйте метод forceSync для синхронизации данных по указанной группе доступа к конфиденциальным данным. Метод требует ввода параметра запроса policy_id (идентификатор группы доступа).

В результате выполнения метода нода запускает процесс синхронизации и возвращает размер конфиденциальных данных в Мб. Если синхронизацию не удалось запустить, нода возвращает и описание ошибки.

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