Skip to content

Commit f500172

Browse files
Jimmy Phanlostlevels
Jimmy Phan
authored and
lostlevels
committed
Add app attestation and assertion api documentation.
This adds attestation and assertion documentation. Attestation is the verifying an app is a valid instance of an iOS app and assertion is requesting a secret of some kind after attestation is verified, in this case X.509 certificates that can be used for client authentication. Add response to successful assertion.
1 parent b55fdb3 commit f500172

File tree

10 files changed

+230
-0
lines changed

10 files changed

+230
-0
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22
dist
33
build
44
.idea/
5+
.DS_Store

‎reference/auth.v1.yaml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,10 @@ tags:
3939
description: >-
4040
List and manage users.
4141
42+
- name: Attestation
43+
description: >-
44+
Attest and assert an app is a valid instance of an iOS app.
45+
4246
paths:
4347
'/auth/login':
4448
post:
@@ -719,6 +723,98 @@ paths:
719723
security:
720724
- serverToken: []
721725

726+
'/v1/attestations/challenges':
727+
post:
728+
operationId: CreateAttestationChallenge
729+
summary: Create an attestation challenge.
730+
description: >-
731+
Starts the attestation flow by requesting an attestation challenge that the client will later use in an Apple API call and to verify an attestation.
732+
requestBody:
733+
content:
734+
'application/json':
735+
schema:
736+
$ref: './auth/models/newappchallenge.v1.yaml'
737+
responses:
738+
'201':
739+
$ref: '#/components/responses/AppChallenge'
740+
'400':
741+
$ref: './common/responses/badrequest.v1.yaml'
742+
'401':
743+
$ref: './common/responses/unauthorized.v1.yaml'
744+
'403':
745+
$ref: './common/responses/forbidden.v1.yaml'
746+
tags:
747+
- Attestation
748+
749+
'/v1/attestations/verifications':
750+
post:
751+
operationId: VerifyAttestation
752+
summary: Verify an attestation.
753+
description: >-
754+
This confirms the app is a valid instance of an iOS app. It must use the previously generated challenge.
755+
requestBody:
756+
content:
757+
'application/json':
758+
schema:
759+
$ref: './auth/models/attestationverify.v1.yaml'
760+
responses:
761+
'204':
762+
description: The attestation was verified successfully.
763+
'400':
764+
$ref: './common/responses/badrequest.v1.yaml'
765+
'401':
766+
$ref: './common/responses/unauthorized.v1.yaml'
767+
'403':
768+
$ref: './common/responses/forbidden.v1.yaml'
769+
tags:
770+
- Attestation
771+
772+
'/v1/assertions/challenges':
773+
post:
774+
operationId: CreateAssertionChallenge
775+
summary: Create an assertion challenge.
776+
description: >-
777+
Requests an assertion challenge be generated. This can only happen after attestation has been verified.
778+
requestBody:
779+
content:
780+
'application/json':
781+
schema:
782+
$ref: './auth/models/newappchallenge.v1.yaml'
783+
responses:
784+
'201':
785+
$ref: '#/components/responses/AppChallenge'
786+
'400':
787+
$ref: './common/responses/badrequest.v1.yaml'
788+
'401':
789+
$ref: './common/responses/unauthorized.v1.yaml'
790+
'403':
791+
$ref: './common/responses/forbidden.v1.yaml'
792+
tags:
793+
- Attestation
794+
795+
'/v1/assertions/verifications':
796+
post:
797+
operationId: VerifyAssertion
798+
summary: Verify an assertion.
799+
description: >-
800+
This verifies an assertion and returns X.509 certficates.
801+
requestBody:
802+
content:
803+
'application/json':
804+
schema:
805+
$ref: './auth/models/assertionverify.v1.yaml'
806+
responses:
807+
'200':
808+
$ref: '#/components/responses/Assertion'
809+
'400':
810+
$ref: './common/responses/badrequest.v1.yaml'
811+
'401':
812+
$ref: './common/responses/unauthorized.v1.yaml'
813+
'403':
814+
$ref: './common/responses/forbidden.v1.yaml'
815+
tags:
816+
- Attestation
817+
722818
components:
723819
securitySchemes:
724820
basicAuth:
@@ -998,3 +1094,21 @@ components:
9981094
required:
9991095
- code
10001096
- reason
1097+
AppChallenge:
1098+
description: 'Challenge generated by server and which client should use in later operations.'
1099+
headers:
1100+
'X-Tidepool-Session-Token':
1101+
$ref: './common/headers/tidepoolsessiontoken.v1.yaml'
1102+
content:
1103+
'application/json':
1104+
schema:
1105+
$ref: './auth/models/appchallenge.v1.yaml'
1106+
Assertion:
1107+
description: 'Certificates returned upon successful assertion.'
1108+
headers:
1109+
'X-Tidepool-Session-Token':
1110+
$ref: './common/headers/tidepoolsessiontoken.v1.yaml'
1111+
content:
1112+
'application/json':
1113+
schema:
1114+
$ref: './auth/models/assertionsecret.v1.yaml'

‎reference/auth/models/appchallenge.v1.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
title: Challenge
2+
description: Challenge generated by server.
3+
type: object
4+
properties:
5+
challenge:
6+
type: string
7+
minLength: 1

‎reference/auth/models/assertionsecret.v1.yaml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
title: AssertionSecret
2+
description: Data sent back upon successful app assertion. This will include X.509 certificates.
3+
type: object
4+
properties:
5+
certificates:
6+
description: X.509 certificates to be used for client authentication.
7+
type: array
8+
items:
9+
type: object
10+
properties:
11+
content:
12+
type: string
13+
description: base64 encoded X.509 certificate in DER format.
14+
ttlInDays:
15+
type: integer
16+
type:
17+
type: string
18+
oneOf:
19+
- CONSTRAINED
20+
- WILDCARD

‎reference/auth/models/assertionverify.v1.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
title: Assertion Verify
2+
description: Request body for verifying an assertion.
3+
type: object
4+
properties:
5+
assertion:
6+
$ref: '../../common/models/base64.v1.yaml'
7+
description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple.
8+
clientData:
9+
type: object
10+
properties:
11+
challenge:
12+
type: string
13+
minLength: 1
14+
partner:
15+
description: Code name of partner to retrieve certificate from.
16+
type: string
17+
minLength: 1
18+
enum:
19+
- Coastal
20+
partnerData:
21+
description: Actual data to send to partner API.
22+
$ref: './coastaldata.v1.yaml'
23+
description: Actual data requested by client. Must include the previously requested challenge.
24+
keyId:
25+
$ref: './keyid.v1.yaml'
26+
description: Base64 encoded key Id received from Apple App Attest API.
27+
required:
28+
- attestation
29+
- clientData
30+
- keyId

‎reference/auth/models/attestationverify.v1.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
title: Attestation Verify
2+
description: Request body for verifying an attestation.
3+
type: object
4+
properties:
5+
attestation:
6+
$ref: '../../common/models/base64.v1.yaml'
7+
description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple.
8+
challenge:
9+
type: string
10+
minLength: 1
11+
description: Challenge string returned from the Tidepool platform API.
12+
keyId:
13+
$ref: './keyid.v1.yaml'
14+
description: Base64 encoded key Id received from Apple App Attest API.
15+
required:
16+
- attestation
17+
- challenge
18+
- keyId

‎reference/auth/models/coastaldata.v1.yaml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
title: CoastalData
2+
description: Data to send to Coastal's API.
3+
type: object
4+
properties:
5+
rcTypeId:
6+
type: string
7+
rcInstanceId:
8+
type: string
9+
rcHWVersions:
10+
type: array
11+
items:
12+
type: string
13+
rcSWVersions:
14+
type: array
15+
items:
16+
type: string
17+
phdTypeId:
18+
type: string
19+
phdInstanceId:
20+
type: string
21+
csr:
22+
type: string
23+
rcbMac:
24+
type: string

‎reference/auth/models/keyid.v1.yaml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
title: Key Id
2+
description: Base64 encoded key identifier received from apple. The Key Id is some shortened data, usually a hash, used to identify the longer actual key.
3+
$ref: '../../common/models/base64.v1.yaml'

‎reference/auth/models/newappchallenge.v1.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
title: New App Challenge
2+
description: Information needed when generating an attestation or assertion challenge.
3+
type: object
4+
properties:
5+
keyId:
6+
$ref: '../../common/models/base64.v1.yaml'
7+
description: Base64 encoded key Id received from Apple App Attest API.
8+
required:
9+
- keyId

‎reference/common/models/base64.v1.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
title: Base64
2+
type: string
3+
description: Base64 encoded data.
4+
pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'

0 commit comments

Comments
 (0)