-
Notifications
You must be signed in to change notification settings - Fork 26
/
Copy pathKeyServer.yaml
366 lines (348 loc) · 17.6 KB
/
KeyServer.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
swagger: '2.0'
info:
title: Trace Privately KeyServer API
description: |
This is the format of the API that the Trace Privately app expects from its corresponding key server.
version: "0.2"
host: example.com
schemes:
- https
basePath: /api
produces:
- application/json
securityDefinitions:
BearerAuth:
type: apiKey
in: header
name: Authorization
paths:
/auth:
post:
operationId: "keyserver_auth"
summary: Generate an authentication token for subsequent API requests
description: |
Server should create a token that expires periodically (e.g. after X number. of days).
If one of the other API keys doesn't have a valid key, a 401 is returned and the client
should reauthenticate using this endpoint. Client may include the old token as authorization
in this request to invalidate it.
security:
- BearerAuth: []
produces:
- "application/json"
parameters:
- in: body
name: Request data
schema:
type: object
description: The structure is undefined, as its depends on what authentication data the app is using.
responses:
200:
description: A newly-generated token
schema:
type: object
required:
- status
- token
properties:
status:
type: string
example: "OK"
description: OK
token:
type: string
example: "SOME_TOKEN_DATA"
description: This can be in whatever format is necessary for your system
expires_at:
type: string
format: date-time
description: |
This indicates when the token will definitely no longer work, meaning the client
can simply request a new one without needing determine it's invalidated. Server
can choose expiry time, and it can expire the token prematurely if necessary. If expired
prematurely, client will receive a 401 and request a new token.
400:
description: Invalid request data
schema:
type: object
required:
- status
properties:
status:
type: string
example: "ERROR"
description: ERROR
message:
type: string
description: Human-readable string of the error that occurred
401:
description: Unable to authorize user.
/infected:
get:
operationId: "keyserver_infected"
summary: Retrieve a list of active infected keys
description: |
This endpoint returns a list of keys for users that have indicated that have contracted COVID-19.
security:
- BearerAuth: []
produces:
- "application/json"
- "application/x-msgpack"
parameters:
- name: since
description: |
This restricts the date for which keys are returned. In other words, only return keys submitted after this date. The server
may impose its only minimum date if this date isn't specified, such as a maximum of 14 days worth of infected keys. Expects a date time in ISO 8601 format.
in: query
required: false
type: string
format: date-time
- name: offset
description: |
The 0-indexed starting point for the returned results. Results must be returned by their "last updated date ascending" to ensure
consistency between subsequent calls. It is intended that a client retrieving the results by page will retrieve all pages in a short
burst.
in: query
required: false
type: integer
- name: limit
description: |
The maximum number of results to return. See the notes for the offset parameter. This number will typically correspond to the
ENExposureDetectionSession.maximumKeyCount value, so the right number of results can be piped in accordingly.
in: query
required: false
type: integer
responses:
200:
description: A list of infected keys since the specified date.
schema:
type: object
required:
- status
- date
- keys
properties:
status:
type: string
example: "OK"
description: OK
list_type:
type: string
example: "FULL"
description: |
Indicates whether or not the returned keys constitute the full list of keys.
If so, client should clear cache and use this entire list. Otherwise, assume
it's a partial list that can be appended to existing cache. If it's a full list
then it doesn't make sense for `deleted_keys` to be populated.
date:
type: string
format: date-time
description: |
The maximum date keys are returned up to. This date should be used
as the value for the `since` parameter in subsequent requests.
min_retry_date:
type: string
format: date-time
description: |
If specified, the client shouldn't ask for more keys until after
this date. This can be used to rate limit clients, or if the server only
updates its infected key list periodically (e.g. every 24 hours).
keys:
type: array
items:
type: object
required:
- d
- r
description: Contains information about a single key
properties:
d:
type: string
example: "Base 64 Encoded String"
description: |
Base 64 encoded binary data representing a single key. If the `x-msgpack` format is used,
this is the original binary key, not base 64 encoded.
p:
type: integer
example: 123
description: The rolling period number for the key.
r:
type: integer
example: 1234
description: The rolling start number for the key.
l:
type: integer
description: Represents the calculated risk level from 1-100
deleted_keys:
description: |
A list of keys that have subsequently been marked as not infected. Client should remove them from their cache.
These keys should also honor the "since" parameter and return deleted keys based on when their status was changed to deleted.
type: array
items:
type: object
required:
- d
- r
description: Contains information about a single key
properties:
d:
type: string
example: "Base 64 Encoded String"
description: |
Base 64 encoded binary data representing a single key. If the `x-msgpack` format is used,
this is the original binary key, not base 64 encoded.
p:
type: integer
example: 1234
description: The rolling period number for the key.
r:
type: integer
example: 1234
description: The rolling start number for the key.
config:
description: |
This contains the configuration to use in the exposure detection session. It defines the weights to use
in order to determine if a user is exposed.
type: object
properties:
minimum_risk_score:
type: integer
description: |
Exposures with a score below this won't be returned.
minimum: 1
maximum: 8
attenuation:
$ref: '#/definitions/bucketObject'
days_since_last_exposure:
$ref: '#/definitions/bucketObject'
duration:
$ref: '#/definitions/bucketObject'
transmission_risk:
$ref: '#/definitions/bucketObject'
400:
description: Invalid request data
schema:
type: object
required:
- status
properties:
status:
type: string
example: "ERROR"
description: ERROR
message:
type: string
description: Human-readable string of the error that occurred
401:
description: Unable to authorize user. Need to request a token before calling this endpoint again.
/submit:
post:
operationId: "keyserver_submit"
summary: Submit keys that represent a person who has contracted COVID-19.
description: |
This endpoint allows the client to submit keys after its user has indicated they have contracted COVID-19.
security:
- BearerAuth: []
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: body
name: Request data
schema:
type: object
properties:
keys:
type: array
description: List of infected keys
minimum: 1
items:
type: object
required:
- d
- r
description: Contains information about a single key
properties:
d:
type: string
example: "Base 64 Encoded String"
description: Base 64 encoded binary data representing a single key
p:
type: integer
example: 1234
description: The rolling period number for the key.
r:
type: integer
example: 1234
description: The rolling start number for the key.
l:
type: integer
description: Represents the calculated risk level from 1-100
form:
type: array
description: Additional form data gathered from user. Each item
items:
type: object
description: A single form element
properties:
name:
type: string
description: The name of the form element
type:
type: string
description: The type of content
example: image/png
str:
type: string
description: The element data in string format
identifier:
type: string
description: An optional unique identifier from a previous submission so newly-submitted keys can be appended to an existing submission.
responses:
200:
description: A list of infected keys since the specified date.
schema:
type: object
required:
- status
properties:
status:
type: string
example: "OK"
description: OK
identifier:
type: string
example: "SOME_UNIQUE_IDENTIFIER"
description: An identifier specific to this report, so the client can append new keys to the newly-created submission.
400:
description: Invalid request data
schema:
type: object
required:
- status
properties:
status:
type: string
example: "ERROR"
description: ERROR
message:
type: string
description: Human-readable string of the error that occurred
401:
description: Unable to authorize user. Need to request a token before calling this endpoint again.
definitions:
bucketObject:
type: object
properties:
weight:
type: integer
minimum: 0
maximum: 100
scores:
type: array
minItems: 8
maxItems: 8
items:
type: integer
minimum: 1
maximum: 8