Installation and usage of the platform

REST API: confidential data exchange and obtaining of information about confidential data groups

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

Use the Privacy group methods to handle confidential data using the REST API.

Learn more about confidential data exchange and access groups in the Confidential data exchange article.

Note

You can also use the gRPC methods of the PrivacyEventsService and PrivacyPublicService to handle confidential data.

Privacy group methods authorization

Privacy methods group authorization:

Authentication by api-key or JWT-token is required to use REST API methods of the Privacy group. The authentication (authorization) 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:

  • 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,

where

  • contractAuth — smart contract authorization token passed in the ‘X-Contract-Api-Token’ header to the request;

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

  • privacyAuth — privacy user api-key in the ‘X-Api-Key’ header to the request 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.

POST /privacy/sendData

The method is designed to send sensitive data (available only to the members of the access group defined for this data) to the blockchain.

Note

Use the POST /privacy/sendLargeData method to send data larger than 20 MB.

The POST /privacy/sendData method request must contain the following information:

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

  • policyId – identifier of a group that will have access to the data to be forwarded;

  • type – the type of confidential data being transmitted (for example file);

  • data – string in base64 format containing the confidential data;

  • hash – data sha256-hash in base58 format;

  • info – information about the confidential data being sent:

    • filename – name of a file,

    • size – file size,

    • timestamp – data timestamp,

    • author – the email of the data author,

    • comment – optional comment to the data.

  • fee – PolicyDataHash transaction fee;

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

  • timestamp – the parameter is not used – optional parameter;

  • atomicBadge – information required to send an atomic transaction – optional parameter:

    • trustedSender – the trusted address of the transaction sender to add to the atomic transaction container.

Note

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

Sending the request will generate a 114 PolicyDataHash transaction, which will send a hash of sensitive data to the blockchain.

broadcast parameter

In addition to the parameters that are passed in the body of the request, the POST /privacy/sendData method may receive the broadcast query parameter. It can have the following values:

  • true – in this case the created PolicyDataHash transaction is sent to the blockchain;

  • false – the PolicyDataHash transaction and the Privacy Inventory message are not sent to the blockchain.

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

Important

If the broadcast field is set to false, the subsequent broadcast of the received transaction to the blockchain must be done through the same node to which the sendData request was sent. As a consequence, this restricts the use of a non-empty atomicBadge field in the PolicyDataHash Transaction.

Examples of a query and a response:

POST /privacy/sendData:

Query:

{
"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
 }

Response:

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

Note

You can also use the gRPC SendData method to send confidential data to the blockchain.

POST /privacy/sendDataV2

The POST /privacy/sendDataV2 method is similar to the POST /privacy/sendData method but allows you to attach a file in the Swagger window without having to convert it to base64 format. The method provides the ability to stream data. The Data field is missing in this version of the method.

Note

Use the POST /privacy/sendLargeData method to send data larger than 20 MB.

Note

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

Examples of a query and a response:

POST /privacy/sendDataV2:

Query:

{
"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
 }

Response:

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

Note

You can also use the gRPC SendLargeData method to send confidential data stream to the blockchain.

POST /privacy/sendLargeData

The POST /privacy/sendLargeData method is similar to the POST /privacy/sendDataV2 method, but is used to send data of at least 20 MB in size.

Note

Use the POST /privacy/sendData and POST /privacy/sendDataV2 methods to send data less than 20 MB.

You can configure the backpressure on incoming data chunks in the node configuration file in the node.privacy.service section: set the maximum size for the buffer in the memory (the default is 100 MB).

Note

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

Examples of a query and a response:

POST /privacy/sendLargeData:

Query:

{
"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
 }

Response:

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

Note

You can also use the gRPC SendLargeData method to send confidential data stream to the blockchain.

GET /privacy/{policy-id}/recipients

The method is designed to get the addresses of all members recorded in group {policy-id}.

The response of the method returns an array of strings with the addresses of the members of the access group.

Response example:

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

Note

You can also use the gRPC Recipients method to retrieve the addresses of the confidential data access group members.

GET /privacy/{policy-id}/owners

The method is designed to get the addresses of the owners of access group {policy-id}.

The response of the method returns an array of strings with the addresses of the owners of the access group.

Response example:

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

Note

You can also use the gRPC Owners method to retrieve the addresses of the confidential data access group owners.

GET /privacy/{policy-id}/hashes

The method is designed to get an array of identification hashes of data bound to the {policy-id} access group.

The response of the method returns an array of strings with the identity hashes of the access group data.

Response example:

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

Note

You can also use the GetPolicyItemData gRPC method to retrieve an access group’s confidential data package by its identifying hash.

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

The method is designed to retrieve a packet of confidential data of {policyId} access group by the identification hash {policyItemHash}.

The response of the method returns the hash sum of the confidential data.

Response example:

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

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

The method is designed to retrieve a packet of confidential data of {policyId} access group by the identification hash {policyItemHash}.

The method returns data stream, which allows the user to download a data file of unlimited size.

GET /privacy/%policyId%/transactions

The method is designed to get the transactions of the {policyId} access group owners.

The method returns a list of transaction IDs of 114 PolicyDataHash type for the access group specified in the request.

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

The method is designed to retrieve the confidential data packet metadata of {policyId} access group by the identification hash {policyItemHash}.

The method response returns the following data:

  • sender – an address of confidential data sender;

  • policy_id – a confidential data group identifier;

  • type – type of confidential data (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.

Response example:

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"
}

POST /privacy/forceSync

The method is designed to force a packet of confidential data. It is used if a transaction with confidential data for an access group is present in the blockchain, but for some reason this data was not written to the node’s confidential data repository. In this case, the method allows to forcibly download the missing data. The method synchronizes data across all sensitive data access groups.

The response includes the following data:

  • sender – address of the node participating in the access group that sends the request;

  • policy – a confidential data group identifier;

  • source – address of the node from which the missing data should be downloaded. In case the node is unknown, set the parameter to null or leave the field empty: in this case the file will be downloaded from the storage of the first node in the access group list.

Method response contains a result field with data retrieval result and a message field with possible error text. In case of successful reception, success is returned, confidential data is written to node storage.

If an error occurs, error is returned, the message field contains a description of the error.

Examples of a query and a response:

POST /privacy/forceSync:

Query:

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

Response:

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

Note

You can also use the gRPC forceSync method to synchronise data on the specified confidential data access group.

GET /privacy/forceSync/{policyId}

The method is similar to the POST /privacy/forceSync method with the difference that it synchronizes data by the specified privacy access group (policyId).

Note

You can also use the gRPC forceSync method to synchronise data on the specified confidential data access group.

POST /privacy/getInfos

The method is designed to obtain an array of confidential data metadata by access group identifier and identification hash.

The response includes the following data:

  • policiesDataHashes – an array of data with two elements for each individual access group:

    • policy_id – a confidential data group identifier,

    • datahashes – an array of sensitive data hashes to get metadata for each of them.

The method response returns an array of data for each individual hash of sensitive data, similar to the response of the GET /privacy/{policyId}/getInfo/{policyItemHash} method.

Examples of a query and a response:

POST /privacy/getInfos:

Query:

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

Response:

{
   "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"
               }
            }
            }
          ]
      ]
   }
See also

REST API methods

Confidential data exchange

Precise platform configuration: gRPC and REST API authorization