Installation and usage of the platform

gRPC: handling confidential data

Use the PrivacyEventsService and PrivacyPublicService gRPC services to handle confidential data (privacy).

Note

You can also use REST methods of the Privacy group to handle confidential data.

PrivacyEventsService and PrivacyPublicService methods authorization

PrivacyEventsService and PrivacyPublicService methods authorization:

To use the methods of gRPC API PrivacyEventsService and PrivacyPublicService services, authorization by api-key or JWT-token is required. Authorization of the methods is implemented as follows:

  • in case of api-key authorization, PrivacyApiKey is required;

  • in case of OAuth2 authorization, the Privacy role in the JWT token is required.

For each of the methods, you must provide the following data:

  • Recipients — userAuth;

  • Owners — userAuth;

  • Hashes — userAuth;

  • GetPolicyItemData — privacyAuth;

  • GetPolicyItemInfo — privacyAuth;

  • SendData — privacyAuth;

  • SendLargeData — privacyAuth,

  • forceSync — privacyAuth.

where

  • userAuth — user api-key passed in the ‘X-Api-Key’ request header OR a JWT token with the user role in the ‘Authorization’ header;

  • privacyAuth — privacy user api-key in the ‘X-Api-Key’ request header OR a JWT token with the privacy role in the ‘Authorization’ header.

Оn top of that gRPC and REST API authorization is configured in the auth section of the node configuration file.

PrivacyEventsService

The PrivacyEventsService has one method SubscribeOn, described in the privacy_events_service.proto protobuf file. Use this method to get the stream of events related to receiving or deleting confidential data that comes to the node gRPC interface. To do this, send a SubscribeOn (SubscribeOnRequest) request that initializes the subscription to the stream.

Information on receiving or deleting confidential data

After a successful request is sent to the gRPC interface, the following data will be received:

  • policy_id – confidential data group id;

  • data_hash – confidential data identifying hash;

  • event_type – event type; the following types are available:

    • DATA_ACQUIRED – the data is saved in the database;

    • DATA_INVALIDATED – the data is marked for deletion due to lack of activity on it or at rollback.

PrivacyPublicService

The PrivacyPublicService service has the following methods, described in the protobuf file privacy_public_service.proto:

Important

The field data types for the request and response are specified in the protobuf file.

Note

You can also use REST methods of the Privacy group to handle confidential data.

Retrieving confidential data hash sum

Use the GetPolicyItemData method to retrieve the policy’s confidential data package by the identifying hash. The method requires the following query parameters: policy_id (confidential data group id) and data_hash (identifying hash). After the request is successfully sent to the gRPC-interface, the hash sum of confidential data is returned.

Note

You can also use the REST GET /privacy/{policy-id}/hashes method to retrieve an array of identification hashes of data that are bound to the access group {policy-id}.

Downloading big data from a node

Use the GetDataLarge method to download big data uploaded using SendLargeData from a node. The method requires the following query parameters: policy_id (confidential data group id) and data_hash (identifying hash). After the successful request the PolicyItemDataResponse data stream is received by the gRPC interface.

Retrieving metadata for a confidential data package

Use the GetPolicyItemInfo method to retrieve metadata for the policy’s confidential data package by identifying hash. The method requires the following query parameters: policy_id (confidential data group id) and data_hash (identifying hash). After the successful request the following data will be sent to the gRPC interface:

  • sender – confidential data sender address;

  • policy_id – a confidential data group identifier;

  • type – confidential data type (file);

  • info – file data array:

    • filename – name of a file;

    • size – file size;

    • timestamp – the file placement Unix Timestamp (in milliseconds);

    • author – file author;

    • comment – optional comment to the file;

  • hash – confidential data identifying hash.

Confidential data package existence verification

Use the PolicyItemDataExists method to get information about the presence of the policy’s confidential data package packet by the identifying hash. The method requires the following query parameters: policy_id (confidential data group id) and data_hash (identifying hash). After the successful request, true will be sent to the gRPC interface in case the data exists, or false will be sent, if the data does not exist.

Sending confidential data to the blockchain

Use the SendData method to send confidential data (that will be available only to the policy members defined for that data) to the blockchain.

Note

Use the SendLargeData method to send data larger than 20 MB.

Note

Use the SendLargeData method to send sensitive data stream to the blockchain.

The method requires the following query parameters:

  • sender_address – blockchain address from which the data should be sent (corresponds to the value of the “privacy.owner-address” parameter in the node configuration file);

  • policy_id – identifier of the confidential data access group that will have access to the data being sent;

  • data_hash – identifying sha256-hash of confidential data in base58 format;

  • info – information about data being sent:

    • filename – name of a file,

    • size – file size,

    • timestamp – data timestamp,

    • author – email of the data author,

    • comment – optional comment to the file.

  • fee – transaction fees;

  • fee_asset_id – optional field used for smart contracts only;

  • atomic_badge – a label field indicating that the transaction is supported by the atomic transaction;

  • password – password to access the private key in the node keystore;

  • broadcast_tx – if true is passed, the created PolicyDataHash transaction is sent to the blockchain, if false is passed, the transaction and Privacy Inventory are not sent; see below for details;

  • data – string containing data in base64 format.

Note

When sending files via Amazon S3/Minio, the fields comment, author, filename must have ascii characters. This is a Java SDK AWS limitation.

After a successful request is sent to the gRPC interface, the following data will be received:

  • tx_version – transaction version;

  • tx – the created PolicyDataHash transaction.

broadcast_tx parameter

To reduce the probability of data delivery errors, it is recommended to set the broadcast_tx parameter to false if after sending data using SendData API method an atomic transaction which contains a CreatePolicy and a PolicyDataHash is sent.

Note

You can also use the POST /privacy/sendData REST method to send confidential data to the blockchain.

Sending confidential data stream to the blockchain

Use the SendLargeData method to send a stream of confidential data to the blockchain. The data will only be available to the members of the confidential data access group defined for that data.

Note

Use the SendData method to send data smaller than 20 MB.

The method accepts a data stream in the following format as the request:

  • metadata – metadata for the confidential data package, similar to the input data of the SendData method;

  • content – an array of bytes representing a confidential data package.

After a successful request is sent, the gRPC interface will receive the same data as from the SendData method.

Note

You can also use the POST /privacy/sendDataV2 and POST /privacy/sendLargeData REST methods to send confidential data stream or data larger that 20 MB to the blockchain.

Obtaining the addresses of all the members of a confidential data access group

Use the Recipients method to get the addresses of all the members of a confidential data access group. The method requires the policy_id query parameter – access group identifier. In response, the method returns an array of strings with addresses of the access group members.

Note

You can also use the GET /privacy/{policy-id}/recipients REST method to retrieve the addresses of the confidential data access group members.

Obtaining the addresses of the owners of a confidential data access group

Use the Owners method to get the addresses of confidential data access group owners. The method requires the policy_id query parameter (access group identifier). In response, the method returns an array of strings with addresses of access group owners.

Note

You can also use the GET /privacy/{policy-id}/owners REST method to retrieve the addresses of the confidential data access group owners.

Obtaining an array of identification hashes

Use the Hashes method to get an array of identification hashes of data that are bound to a confidential data access group. The method requires entering the policy_id query parameter (access group identifier). In response, the method returns an array of strings with identity hashes of access group data.

Synchronization of data on the specified confidential data access group

Use the forceSync method to synchronize data on the specified sensitive data access group. The method requires the policy_id query parameter – access group identifier.

As a result of the method execution, the node starts the synchronization process and returns the size of confidential data in MB. If synchronization fails to start, the node returns an error description.

Note

You can also use POST /privacy/forceSync and GET /privacy/forceSync/{policyId} REST methods to force a confidential data package retrieval.

See also