Skip to content

Commit 5e3a718

Browse files
lacabralacabra
authored
DOC: Client documentation
1 parent 7094bf3 commit 5e3a718

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎client/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Client interface to SafeTrace
2+
3+
This folder contains sample Javascript code to interface with the enclave via a JSON RPC Server. At the time of this writing
4+
there is a live instance of the enclave + JSON RPC Server that you can interact with at https://safetrace.enigma.co.
5+
6+
If you visit https://safetrace.enigma.co with your browser, you'll get a `405 Error: Method not allowed` because it does not
7+
accept GET requests like the ones that regular browsers make. Instead, you have to POST properly formatted JSON-RPC requests:
8+
9+
The client code in this folder is meant to be used as a reference and adapted for your own client. It has not been packaged
10+
as a library yet, but you should be able to copy/paste the relevant functions into your code. You can run:
11+
12+
```bash
13+
node index.js
14+
```
15+
16+
to see an example of working code that submits data for two users into the enclave, and later queries for a match between the
17+
two datasets, returning one match.
18+
19+
Below are included example requests and responses for each endpoint using [curl](https://curl.haxx.se/) from the command line.
20+
21+
## getEnclaveReport
22+
23+
* Request
24+
25+
```bash
26+
$ curl -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id":1, "method":"getEnclaveReport", "params": {}}' https://safetrace.enigma.co
27+
```
28+
29+
* Response
30+
```bash
31+
{
32+
"jsonrpc":"2.0",
33+
"id":1,
34+
"result": {
35+
"id":"ed88a0a1f7",
36+
"type":"GetEnclaveReport",
37+
"result": {
38+
"signingKey":"5b4a6ba4809d94f3b0cccbaf43e17dea5d3bdba8",
39+
"report":"7b226964223a22353239313235363835323730343032363337353238343539303132303
40+
9363930353931343134222c2274696d657374616d70223a22323032302d30342d30315431343a3236
41+
3a30322e343737353631222c2276657273696f6e223a332c22697376456e636c61766551756f74655
42+
37461747573223a2247524f55505f4f55545f4f465f44415445222c22706c6174666f726d496e666f
43+
426c6f62223a223135303230303635303430303037303030303044304430323034303130313033303
44+
030303030303030303030303030303030304130303030304230303030303030323030303030303030
45+
303030303041433742453139303731323337303543343031394435363630433744443835313733313
46+
737304138343538414441344332433445354441334545363230463932433139424538383639434441
47+
353237374141333537353737363232304246323544303332313631383038443146463738334238393
48+
14532394434303238383344393534222c22697376456e636c61766551756f7465426f6479223a2241
49+
674141414d634b414141494141634141414141414c417a58394f38484d715067453635696d5167575
50+
331314d722f377379626b4251555851493072707947694167372f42502f2f41414141414141414141
51+
414141414141414141414141414141414141414141414141414141414141414141414141414141414
52+
14141414141427741414141414141414148414141414141414141466d644f7251736445764a434665
53+
624b7232454536637638444d5a314d64492b4b6f7858517a4956385a4941414141414141414141414
54+
1414141414141414141414141414141414141414141414141414141414141434431786e6e6665724b
55+
4648443275765971545864444138695a32326b434435787737683338434d664f6e674141414141414
56+
141414141414141414141414141414141414141414141414141414141414141414141414141414141
57+
414141414141414141414141414141414141414141414141414141414141414141414141414141414
58+
141414141414141414141414141414141414141414141414141414141414141414141414141414141
59+
414141414141414141414141414141414141414141414141414141414141414141414141414141414
60+
141414141414141414141414141414141414141414141414141414141414141414141414141414141
61+
4141414262536d756b674a32553837444d79363944345833715854766271414141414141414141414
62+
141414141414141414141414141414141414141414141414141414141414141414141414141414141
63+
4141414141414141227d",
64+
"signature":"981fc554b5a92149c0b5cfc07ae8c82cdfa213b1405ee867f2dce49ff77f219c8419
65+
3fe67363255cf371a4404b5f62cf85f06361fec00327409e302973a1043d17b76b0ef0b32f95974d4
66+
e612702c1d618f3035a37fa56883a2bb0ee485e8c3b7f85d1305be58490c393de178cdb2a91006b26
67+
6c3225ec3b244c2373bbc2c5e206d372d754142527e5c75893ebb2384d3f3844ca63d91367833cce8
68+
031b6f8f8666f9e93bf5897fc9248839e51cff80f0c455ea217a51befbe4942ea077bc4cf29e87693
69+
3d170778285fa043fd91fb9391b340a607d47a6a0fbee9c5d7ee1818b4899e41020b3de91e5b1b33f
70+
abc36449b35f22a403635b6ab9e429cdc542654"
71+
}
72+
}
73+
}
74+
```
75+
76+
## newTaskEncryptionKey
77+
78+
* Request
79+
80+
```bash
81+
{"jsonrpc":"2.0","id":1,"result":{"id":"5708a053c9","type":"NewTaskEncryptionKey","result":{"taskPubKey":"1a75beafbc32c5a4ba881dcca795fb0f87b4b473e5689592db942366b763d52466922a7103a6975be699cf6f3b499294f5dd92cbe5a2e15470dd03bc971c770d","sig":"1994e259d3befd9fab06c6b9f00c4f892bb6c6d54f6449ccd0b42df79ceeb7ae057aa85b3fe2d070c21775a5cac60274bf1ac8e3c0e104872601a136c978deeb1b"}}}
82+
```
83+
84+
* Response
85+
86+
```json
87+
{
88+
"jsonrpc":"2.0",
89+
"id":1,
90+
"result": {
91+
"id":"5708a053c9",
92+
"type":"NewTaskEncryptionKey",
93+
"result": {
94+
"taskPubKey":"1a75beafbc32c5a4ba881dcca795fb0f87b4b473e5689592db942366b763d52466922a7
95+
103a6975be699cf6f3b499294f5dd92cbe5a2e15470dd03bc971c770d","sig":"1994e259d3befd9fab0
96+
6c6b9f00c4f892bb6c6d54f6449ccd0b42df79ceeb7ae057aa85b3fe2d070c21775a5cac60274bf1ac8e3
97+
c0e104872601a136c978deeb1b"
98+
}
99+
}
100+
}
101+
```
102+
103+
## newTaskEncryptionKey
104+
105+
* Request
106+
107+
```bash
108+
curl -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id":1, "method":"addPersonalData", "params": {"encryptedUserId":"15806c56ed8fb37a9a45c8c3efa227a98a406c5787bf3ff90f0c89fde8ad3d6fdd", "encryptedData": "85d6f1e75cd29d761e291f9c8fd3e8dc5ac289df327960a39938a0934bcaee41f7b17c61ec450b7a8fc01474e9495d12d6d07754d01217c88774b678c03032e3085155ba65f9cf9617de36a538c30c6664e05c3f07f812a3cf10b23ca90fc765912f82bfddd864ba4d4f7e6ab41c11f6d43006b2aee150ddef72215f2baeadd1957fdeac9d2f582e779e79cabc604a3ba50f9c870952239ee4a2437d54952f891090a677b3c38972a2982a739bd43c911c14f67c80cd53b34001285a5091c4525f1d68cef4d89ebb805181a3a11d8c52e57ba4e802e7", "userPubKey": "cc955077ff7aeb67e544bb0dfad0a5ac1d3117f4115c528d38da9c2337cb033ec08f1d12a580d2ccfed02144e70d961c72e28e92ef48b9056c08137918c5ab2d"}}' https://safetrace.enigma.co
109+
```
110+
111+
*NOTE: The parameters `encryptedUserId` and `encryptedData` are encrypted with an ephemeral Diffie-Hellman key, so you need
112+
to run the method `newTaskEncryptionKey` everytime to be able to derive that key, and use it to encrypt these parameters. This
113+
also means that the encrypted values will change every time.*
114+
115+
* Response
116+
117+
```json
118+
{
119+
"jsonrpc":"2.0",
120+
"id":1,
121+
"result": {
122+
"id":"eb2f102370",
123+
"type":"AddPersonalData",
124+
"addPersonalData": {
125+
"status":0
126+
}
127+
}
128+
}
129+
```
130+
131+
## findMatch
132+
133+
* Request
134+
135+
```bash
136+
curl -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id":1, "method":"findMatch", "params": {"encryptedUserId":"15806c56ed8fb37a9a45c8c3efa227a98a406c5787bf3ff90f0c89fde8ad3d6fdd", "userPubKey": "cc955077ff7aeb67e544bb0dfad0a5ac1d3117f4115c528d38da9c2337cb033ec08f1d12a580d2ccfed02144e70d961c72e28e92ef48b9056c08137918c5ab2d"}}' https://safetrace.enigma.co
137+
```
138+
139+
* Response
140+
141+
```json
142+
{
143+
"jsonrpc":"2.0",
144+
"id":1,
145+
"result": {
146+
"id": "d23d723a6a",
147+
"type": "FindMatch",
148+
"findMatch": {
149+
"status": 0,
150+
"encryptedOutput": "45c90f568a5bb096fc39ae8429c3e05cd29f40c30c0f89e8c0395cf431f5c2934d
151+
232cff4eb3c27b18e9704790e65b0bdecdcd02d6e8b5b668991d3e53b804c23b24c7f5d9e5d1a2c322036a
152+
3068991ddc0ebd7a56ddd1b90a7d857c790844f5233b22aad906bea938c77d24882b1043d2e84b2c8d959d
153+
d0"
154+
}
155+
}
156+
}
157+
```
158+
159+
*NOTE: Analogously to the previous method, the input and output from this method are encrypted, which you can encrypt and
160+
decrypt with the key derived through Diffie-Hellman. Again, the command and output included here are for reference
161+
purposes, but you will not be able to reproduce verbatim. Instead, you have to run `newTaskEncryptionKey` and use that
162+
for encryption and decryption.*
163+

0 commit comments

Comments
 (0)