From f500172f87c1a94438188639f113e8de6961b7a8 Mon Sep 17 00:00:00 2001 From: Jimmy Phan Date: Thu, 26 Jan 2023 13:10:08 -0800 Subject: [PATCH] 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. --- .gitignore | 1 + reference/auth.v1.yaml | 114 ++++++++++++++++++ reference/auth/models/appchallenge.v1.yaml | 7 ++ reference/auth/models/assertionsecret.v1.yaml | 20 +++ reference/auth/models/assertionverify.v1.yaml | 30 +++++ .../auth/models/attestationverify.v1.yaml | 18 +++ reference/auth/models/coastaldata.v1.yaml | 24 ++++ reference/auth/models/keyid.v1.yaml | 3 + reference/auth/models/newappchallenge.v1.yaml | 9 ++ reference/common/models/base64.v1.yaml | 4 + 10 files changed, 230 insertions(+) create mode 100644 reference/auth/models/appchallenge.v1.yaml create mode 100644 reference/auth/models/assertionsecret.v1.yaml create mode 100644 reference/auth/models/assertionverify.v1.yaml create mode 100644 reference/auth/models/attestationverify.v1.yaml create mode 100644 reference/auth/models/coastaldata.v1.yaml create mode 100644 reference/auth/models/keyid.v1.yaml create mode 100644 reference/auth/models/newappchallenge.v1.yaml create mode 100644 reference/common/models/base64.v1.yaml diff --git a/.gitignore b/.gitignore index 3360b535..7679d679 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ dist build .idea/ +.DS_Store diff --git a/reference/auth.v1.yaml b/reference/auth.v1.yaml index 3171324e..e08b65e2 100644 --- a/reference/auth.v1.yaml +++ b/reference/auth.v1.yaml @@ -39,6 +39,10 @@ tags: description: >- List and manage users. + - name: Attestation + description: >- + Attest and assert an app is a valid instance of an iOS app. + paths: '/auth/login': post: @@ -719,6 +723,98 @@ paths: security: - serverToken: [] + '/v1/attestations/challenges': + post: + operationId: CreateAttestationChallenge + summary: Create an attestation challenge. + description: >- + 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. + requestBody: + content: + 'application/json': + schema: + $ref: './auth/models/newappchallenge.v1.yaml' + responses: + '201': + $ref: '#/components/responses/AppChallenge' + '400': + $ref: './common/responses/badrequest.v1.yaml' + '401': + $ref: './common/responses/unauthorized.v1.yaml' + '403': + $ref: './common/responses/forbidden.v1.yaml' + tags: + - Attestation + + '/v1/attestations/verifications': + post: + operationId: VerifyAttestation + summary: Verify an attestation. + description: >- + This confirms the app is a valid instance of an iOS app. It must use the previously generated challenge. + requestBody: + content: + 'application/json': + schema: + $ref: './auth/models/attestationverify.v1.yaml' + responses: + '204': + description: The attestation was verified successfully. + '400': + $ref: './common/responses/badrequest.v1.yaml' + '401': + $ref: './common/responses/unauthorized.v1.yaml' + '403': + $ref: './common/responses/forbidden.v1.yaml' + tags: + - Attestation + + '/v1/assertions/challenges': + post: + operationId: CreateAssertionChallenge + summary: Create an assertion challenge. + description: >- + Requests an assertion challenge be generated. This can only happen after attestation has been verified. + requestBody: + content: + 'application/json': + schema: + $ref: './auth/models/newappchallenge.v1.yaml' + responses: + '201': + $ref: '#/components/responses/AppChallenge' + '400': + $ref: './common/responses/badrequest.v1.yaml' + '401': + $ref: './common/responses/unauthorized.v1.yaml' + '403': + $ref: './common/responses/forbidden.v1.yaml' + tags: + - Attestation + + '/v1/assertions/verifications': + post: + operationId: VerifyAssertion + summary: Verify an assertion. + description: >- + This verifies an assertion and returns X.509 certficates. + requestBody: + content: + 'application/json': + schema: + $ref: './auth/models/assertionverify.v1.yaml' + responses: + '200': + $ref: '#/components/responses/Assertion' + '400': + $ref: './common/responses/badrequest.v1.yaml' + '401': + $ref: './common/responses/unauthorized.v1.yaml' + '403': + $ref: './common/responses/forbidden.v1.yaml' + tags: + - Attestation + components: securitySchemes: basicAuth: @@ -998,3 +1094,21 @@ components: required: - code - reason + AppChallenge: + description: 'Challenge generated by server and which client should use in later operations.' + headers: + 'X-Tidepool-Session-Token': + $ref: './common/headers/tidepoolsessiontoken.v1.yaml' + content: + 'application/json': + schema: + $ref: './auth/models/appchallenge.v1.yaml' + Assertion: + description: 'Certificates returned upon successful assertion.' + headers: + 'X-Tidepool-Session-Token': + $ref: './common/headers/tidepoolsessiontoken.v1.yaml' + content: + 'application/json': + schema: + $ref: './auth/models/assertionsecret.v1.yaml' \ No newline at end of file diff --git a/reference/auth/models/appchallenge.v1.yaml b/reference/auth/models/appchallenge.v1.yaml new file mode 100644 index 00000000..0e3c306d --- /dev/null +++ b/reference/auth/models/appchallenge.v1.yaml @@ -0,0 +1,7 @@ +title: Challenge +description: Challenge generated by server. +type: object +properties: + challenge: + type: string + minLength: 1 diff --git a/reference/auth/models/assertionsecret.v1.yaml b/reference/auth/models/assertionsecret.v1.yaml new file mode 100644 index 00000000..0a919906 --- /dev/null +++ b/reference/auth/models/assertionsecret.v1.yaml @@ -0,0 +1,20 @@ +title: AssertionSecret +description: Data sent back upon successful app assertion. This will include X.509 certificates. +type: object +properties: + certificates: + description: X.509 certificates to be used for client authentication. + type: array + items: + type: object + properties: + content: + type: string + description: base64 encoded X.509 certificate in DER format. + ttlInDays: + type: integer + type: + type: string + oneOf: + - CONSTRAINED + - WILDCARD \ No newline at end of file diff --git a/reference/auth/models/assertionverify.v1.yaml b/reference/auth/models/assertionverify.v1.yaml new file mode 100644 index 00000000..2a7c6f9f --- /dev/null +++ b/reference/auth/models/assertionverify.v1.yaml @@ -0,0 +1,30 @@ +title: Assertion Verify +description: Request body for verifying an assertion. +type: object +properties: + assertion: + $ref: '../../common/models/base64.v1.yaml' + description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple. + clientData: + type: object + properties: + challenge: + type: string + minLength: 1 + partner: + description: Code name of partner to retrieve certificate from. + type: string + minLength: 1 + enum: + - Coastal + partnerData: + description: Actual data to send to partner API. + $ref: './coastaldata.v1.yaml' + description: Actual data requested by client. Must include the previously requested challenge. + keyId: + $ref: './keyid.v1.yaml' + description: Base64 encoded key Id received from Apple App Attest API. +required: + - attestation + - clientData + - keyId diff --git a/reference/auth/models/attestationverify.v1.yaml b/reference/auth/models/attestationverify.v1.yaml new file mode 100644 index 00000000..e4df04e3 --- /dev/null +++ b/reference/auth/models/attestationverify.v1.yaml @@ -0,0 +1,18 @@ +title: Attestation Verify +description: Request body for verifying an attestation. +type: object +properties: + attestation: + $ref: '../../common/models/base64.v1.yaml' + description: Base64 encoded data received from Apple App Attest API. User must base64 encode the binary data received from Apple. + challenge: + type: string + minLength: 1 + description: Challenge string returned from the Tidepool platform API. + keyId: + $ref: './keyid.v1.yaml' + description: Base64 encoded key Id received from Apple App Attest API. +required: + - attestation + - challenge + - keyId diff --git a/reference/auth/models/coastaldata.v1.yaml b/reference/auth/models/coastaldata.v1.yaml new file mode 100644 index 00000000..187c06cb --- /dev/null +++ b/reference/auth/models/coastaldata.v1.yaml @@ -0,0 +1,24 @@ +title: CoastalData +description: Data to send to Coastal's API. +type: object +properties: + rcTypeId: + type: string + rcInstanceId: + type: string + rcHWVersions: + type: array + items: + type: string + rcSWVersions: + type: array + items: + type: string + phdTypeId: + type: string + phdInstanceId: + type: string + csr: + type: string + rcbMac: + type: string diff --git a/reference/auth/models/keyid.v1.yaml b/reference/auth/models/keyid.v1.yaml new file mode 100644 index 00000000..59fbd1f2 --- /dev/null +++ b/reference/auth/models/keyid.v1.yaml @@ -0,0 +1,3 @@ +title: Key Id +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. +$ref: '../../common/models/base64.v1.yaml' diff --git a/reference/auth/models/newappchallenge.v1.yaml b/reference/auth/models/newappchallenge.v1.yaml new file mode 100644 index 00000000..2f0c2014 --- /dev/null +++ b/reference/auth/models/newappchallenge.v1.yaml @@ -0,0 +1,9 @@ +title: New App Challenge +description: Information needed when generating an attestation or assertion challenge. +type: object +properties: + keyId: + $ref: '../../common/models/base64.v1.yaml' + description: Base64 encoded key Id received from Apple App Attest API. +required: + - keyId diff --git a/reference/common/models/base64.v1.yaml b/reference/common/models/base64.v1.yaml new file mode 100644 index 00000000..8d841293 --- /dev/null +++ b/reference/common/models/base64.v1.yaml @@ -0,0 +1,4 @@ +title: Base64 +type: string +description: Base64 encoded data. +pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'