Skip to content

Commit fae9ab7

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 0dcc826 commit fae9ab7

File tree

11 files changed

+302
-2484
lines changed

11 files changed

+302
-2484
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
.dccache
22
.idea/
3+
.DS_Store

‎reference/auth.v1.yaml‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ tags:
4444
description: >-
4545
List and manage users.
4646
47+
- name: Attestation
48+
description: >-
49+
Attest and assert an app is a valid instance of an iOS app.
50+
4751
paths:
4852
'/auth/login':
4953
post:
@@ -698,6 +702,98 @@ paths:
698702
security:
699703
- serverToken: []
700704

705+
'/v1/attestations/challenges':
706+
post:
707+
operationId: CreateAttestationChallenge
708+
summary: Create an attestation challenge.
709+
description: >-
710+
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.
711+
requestBody:
712+
content:
713+
'application/json':
714+
schema:
715+
$ref: './auth/models/newappchallenge.v1.yaml'
716+
responses:
717+
'201':
718+
$ref: '#/components/responses/AppChallenge'
719+
'400':
720+
$ref: './common/responses/badrequest.v1.yaml'
721+
'401':
722+
$ref: './common/responses/unauthorized.v1.yaml'
723+
'403':
724+
$ref: './common/responses/forbidden.v1.yaml'
725+
tags:
726+
- Attestation
727+
728+
'/v1/attestations/verifications':
729+
post:
730+
operationId: VerifyAttestation
731+
summary: Verify an attestation.
732+
description: >-
733+
This confirms the app is a valid instance of an iOS app. It must use the previously generated challenge.
734+
requestBody:
735+
content:
736+
'application/json':
737+
schema:
738+
$ref: './auth/models/attestationverify.v1.yaml'
739+
responses:
740+
'204':
741+
description: The attestation was verified successfully.
742+
'400':
743+
$ref: './common/responses/badrequest.v1.yaml'
744+
'401':
745+
$ref: './common/responses/unauthorized.v1.yaml'
746+
'403':
747+
$ref: './common/responses/forbidden.v1.yaml'
748+
tags:
749+
- Attestation
750+
751+
'/v1/assertions/challenges':
752+
post:
753+
operationId: CreateAssertionChallenge
754+
summary: Create an assertion challenge.
755+
description: >-
756+
Requests an assertion challenge be generated. This can only happen after attestation has been verified.
757+
requestBody:
758+
content:
759+
'application/json':
760+
schema:
761+
$ref: './auth/models/newappchallenge.v1.yaml'
762+
responses:
763+
'201':
764+
$ref: '#/components/responses/AppChallenge'
765+
'400':
766+
$ref: './common/responses/badrequest.v1.yaml'
767+
'401':
768+
$ref: './common/responses/unauthorized.v1.yaml'
769+
'403':
770+
$ref: './common/responses/forbidden.v1.yaml'
771+
tags:
772+
- Attestation
773+
774+
'/v1/assertions/verifications':
775+
post:
776+
operationId: VerifyAssertion
777+
summary: Verify an assertion.
778+
description: >-
779+
This verifies an assertion and returns X.509 certficates.
780+
requestBody:
781+
content:
782+
'application/json':
783+
schema:
784+
$ref: './auth/models/assertionverify.v1.yaml'
785+
responses:
786+
'200':
787+
$ref: '#/components/responses/Assertion'
788+
'400':
789+
$ref: './common/responses/badrequest.v1.yaml'
790+
'401':
791+
$ref: './common/responses/unauthorized.v1.yaml'
792+
'403':
793+
$ref: './common/responses/forbidden.v1.yaml'
794+
tags:
795+
- Attestation
796+
701797
components:
702798
securitySchemes:
703799
basicAuth:
@@ -977,3 +1073,21 @@ components:
9771073
required:
9781074
- code
9791075
- reason
1076+
AppChallenge:
1077+
description: 'Challenge generated by server and which client should use in later operations.'
1078+
headers:
1079+
'X-Tidepool-Session-Token':
1080+
$ref: './common/headers/tidepoolsessiontoken.v1.yaml'
1081+
content:
1082+
'application/json':
1083+
schema:
1084+
$ref: './auth/models/appchallenge.v1.yaml'
1085+
Assertion:
1086+
description: 'Certificates returned upon successful assertion.'
1087+
headers:
1088+
'X-Tidepool-Session-Token':
1089+
$ref: './common/headers/tidepoolsessiontoken.v1.yaml'
1090+
content:
1091+
'application/json':
1092+
schema:
1093+
$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)