Merge pull request #34 from veraison/disco-api-plusplus

Disco API - add some missing info

Author: thomas-fossati

.github/workflows/api-checks.yml

@@ -23,3 +23,6 @@ jobs:
 
     - name: Check Endorsement provisioning API
       run: make -C api/endorsement-provisioning check
+
+    - name: Check Discovery API
+      run: make -C api/well-known check

api/well-known/README.md

@@ -1,13 +1,15 @@
 # Discovery APIs
-The APIs described here allow a user of the Veraison to obtain and view meta information about the Veraison deployment. Information about deployment can be queried according to the service e.g. provisioning or verification.
+The APIs described here allow a user of the Veraison to obtain and view meta information about the Veraison deployment. Information about a deployment can be queried according to the service - e.g., provisioning or verification.
 
 The relevant resource is created in response to a client `GET`. The queried information is then outputted as shown in the examples below.
 
 ## Well-known API: Provisioning service
 The information for the provisioning service has the following attributes:
 
 * The allowed provisioning media types;
-* The version of the provisioning service.
+* The version of the provisioning service;
+* The current operational state of the service;
+* The exposed API endpoints and the corresponding URLs (relative to the request's base URL).
 
 ### Querying information about the Provisioning service
 
@@ -29,7 +31,7 @@ Content-format: application/vnd.veraison.discovery+json
     "application/corim-unsigned+cbor; profile=http://enacttrust.com/veraison/1.0.0"
   ],
   "version": "commit-a8056d0",
-  "state": "READY",
+  "service-state": "READY",
   "api-endpoints": {
     "provisioningSubmit": "/endorsement-provisioning/v1/submit"
   }
@@ -42,7 +44,10 @@ The information for the verification service has the following attributes:
 
 * The public key used to verify the Attestation Result;
 * The allowed media types for attestation evidence;
-* The version of the verification service.
+* The version of the verification service;
+* The current operational state of the service;
+* The exposed API endpoints and the corresponding URLs (relative to the request's base URL).
+
 
 ### Querying information about the Verification service
 
@@ -59,6 +64,7 @@ Content-format: application/vnd.veraison.discovery+json
 
 {
   "ear-verification-key": {
+    "alg": "ES256",
     "crv": "P-256",
     "kty": "EC",
     "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8",
@@ -72,9 +78,9 @@ Content-format: application/vnd.veraison.discovery+json
     "application/vnd.enacttrust.tpm-evidence"
   ],
   "version": "commit-a8056d0",
-  "state": "READY",
+  "service-state": "READY",
   "api-endpoints": {
     "newChallengeResponseSession": "/challenge-response/v1/newSession"
   }
 }
-```
+```

api/well-known/schemas/components.yaml

@@ -4,14 +4,13 @@ components:
       required:
         - media-types
         - version
-        - state
+        - service-state
         - api-endpoints
       properties:
-        public-key:
-          type: string
-          format: json
+        ear-verification-key:
+          $ref: '#/components/schemas/PublicKey'
           description:
-            Public key used to verify the Attestation Result
+            Public key and algorithm to be used to verify the Attestation Result
         media-types:
           type: array
           items:
@@ -26,8 +25,9 @@ components:
             Version of the current service running represented using a unique 
             commit hash. This value can change as new commits are made to the service
           example: commit-cb11fa0
-        state:
+        service-state:
           type: string
+          enum: [ DOWN, INITIALIZING, READY, TERMINATING ]
           description:
             State of the VTS service
         api-endpoints:
@@ -38,9 +38,23 @@ components:
     MediaType:
       type: string
       example: 'application/eat-collection; profile=http://arm.com/CCA-SSD/1.0.0'
+      description: an Evidence media type
 
     PublicApiMap:
       type: object
       additionalProperties:
         type: string
+      description: >
+        a dictionary with the API names as keys and their relative URLs as values
 
+    PublicKey:
+      required:
+        - alg
+      properties:
+        alg:
+          type: string
+          description: >
+            Identifier of the algorithm used to sign the Attestation Result
+          example: ES256
+      description: >
+        A public key in JSON Web Key (https://www.rfc-editor.org/rfc/rfc7517) format