diff --git a/.gitignore b/.gitignore index 6cd4ef26..8cea200a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ build .idea/ /node_modules/ /tools/ +.DS_Store diff --git a/reference/auth.v1.yaml b/reference/auth.v1.yaml index 977fd30f..6ab3da22 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: @@ -722,6 +726,106 @@ 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' + security: + - sessionToken: [] + 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' + security: + - sessionToken: [] + 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' + security: + - sessionToken: [] + 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' + security: + - sessionToken: [] + tags: + - Attestation + components: securitySchemes: basicAuth: @@ -1001,3 +1105,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..286cf16b --- /dev/null +++ b/reference/auth/models/assertionsecret.v1.yaml @@ -0,0 +1,8 @@ +title: Assertion Secret +description: Data sent back upon successful app assertion. +type: object +properties: + data: + oneOf: + - $ref: './coastalresponse.v1.yaml' + - $ref: './palmtreeresponse.v1.yaml' \ 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..d27f23a1 --- /dev/null +++ b/reference/auth/models/assertionverify.v1.yaml @@ -0,0 +1,34 @@ +title: Assertion Verify +description: Request body for verifying an assertion. +type: object +properties: + assertion: + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' + 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: + description: The previously returned assertion challenge. + type: string + minLength: 1 + partner: + description: Code name of partner to retrieve certificate from. + type: string + minLength: 1 + enum: + - Coastal + - PalmTree + partnerData: + oneOf: + - $ref: './coastalrequest.v1.yaml' + - $ref: './palmtreerequest.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..6a785352 --- /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: + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' + 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: The previously returned attestation challenge. + keyId: + $ref: './keyid.v1.yaml' +required: + - attestation + - challenge + - keyId diff --git a/reference/auth/models/coastalrequest.v1.yaml b/reference/auth/models/coastalrequest.v1.yaml new file mode 100644 index 00000000..06c1424c --- /dev/null +++ b/reference/auth/models/coastalrequest.v1.yaml @@ -0,0 +1,22 @@ +title: Coastal Request Data +description: Data to send to Coastal's API. +type: object +properties: + rcInstanceId: + type: string + minLength: 1 + rcHWVersion: + type: string + rcSWVersion: + type: string + phdTypeId: + type: string + minLength: 1 + phdInstanceId: + type: string + minLength: 1 + csr: + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' + description: Base64 encoded string of the PEM formatted certificate signing request to Coastal. + minLength: 1 \ No newline at end of file diff --git a/reference/auth/models/coastalresponse.v1.yaml b/reference/auth/models/coastalresponse.v1.yaml new file mode 100644 index 00000000..478cf285 --- /dev/null +++ b/reference/auth/models/coastalresponse.v1.yaml @@ -0,0 +1,21 @@ +title: Coastal Response +description: Data retrieved from Coastal's API. +type: object +properties: + certificates: + description: X.509 certificates to be used for client authentication. + type: array + items: + type: object + properties: + content: + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' + description: base64 encoded X.509 certificate in DER format. + ttlInDays: + type: integer + type: + type: string + enum: + - CONSTRAINED + - WILDCARD \ No newline at end of file diff --git a/reference/auth/models/keyid.v1.yaml b/reference/auth/models/keyid.v1.yaml new file mode 100644 index 00000000..248a7f91 --- /dev/null +++ b/reference/auth/models/keyid.v1.yaml @@ -0,0 +1,4 @@ +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. +type: string +pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' diff --git a/reference/auth/models/newappchallenge.v1.yaml b/reference/auth/models/newappchallenge.v1.yaml new file mode 100644 index 00000000..b8001001 --- /dev/null +++ b/reference/auth/models/newappchallenge.v1.yaml @@ -0,0 +1,10 @@ +title: New App Challenge +description: Information needed when generating an attestation or assertion challenge. +type: object +properties: + keyId: + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' + description: Base64 encoded key Id received from Apple App Attest API. +required: + - keyId diff --git a/reference/auth/models/palmtreerequest.v1.yaml b/reference/auth/models/palmtreerequest.v1.yaml new file mode 100644 index 00000000..923e841f --- /dev/null +++ b/reference/auth/models/palmtreerequest.v1.yaml @@ -0,0 +1,8 @@ +title: Palm Tree Request Data +description: Data to send to Palm Tree's API. +type: object +properties: + csr: + description: Base64 encoded string of the DER formatted certificate signing request to PalmTree. + type: string + pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$' \ No newline at end of file diff --git a/reference/auth/models/palmtreeresponse.v1.yaml b/reference/auth/models/palmtreeresponse.v1.yaml new file mode 100644 index 00000000..f1ff92ac --- /dev/null +++ b/reference/auth/models/palmtreeresponse.v1.yaml @@ -0,0 +1,24 @@ +title: Palm Tree Response +description: Data retrieved from Palm Tree's API. +type: object +properties: + type: + type: string + enrollment: + type: object + properties: + body: + type: string + description: PEM encoded certificate. + id: + type: string + issuerName: + type: string + serialNumber: + type: string + subjectName: + type: string + status: + type: string + validityPeriod: + type: string \ No newline at end of file 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}=)?$'