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

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

A set of methods from the Privacy group is provided to implement these functions using the REST API:

POST /privacy/sendData

The method is designed to send sensitive data to the blockchain, available only to members of the access group defined for this data. The method request contains 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);

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

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

  • info - information about data being sent;

  • data - string containing data in base64 format;

  • hash - sha256-hash data in base58 format.

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

Response:

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

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 Data field is missing in this version of the method.

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

Response:

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

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

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

GET /privacy/{policy-id}/hashes

The method is designed to get an array of identification hashes of data that are 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"
]

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

The method is designed to retrieve a packet of confidential data of access group {policyId} 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}​/getInfo​/{policyItemHash}

The method is designed to retrieve a packet of confidential data of access group {policyId} 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 - a Unix Timestamp of file uploading (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 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 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'"
}

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: policyId - access 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