Document: Optimized the path of resources.

KBS should not only support the acquisition of keys, but also support the acquisition of multiple confidential resources. This commit revises the path of resource location and describes resources in a more unified format. Signed-off-by: Jiale Zhang <[email protected]>
confidential-containers · Dec 14, 2022 · fa8c1ba · fa8c1ba
1 parent 96c81be
commit fa8c1ba
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 22 deletions.
diff --git a/docs/kbs.yaml b/docs/kbs.yaml
@@ -71,19 +71,37 @@ paths:
               schema:
                 $ref: '#/components/schemas/ErrorInformation'
 
-  /resources/key/<key_id>:
+  /resource/{repository}/{type}/{tag}:
     get:
-      operationId: getKey
-      summary: Get a key from the Key Broker Service.
+      operationId: getResource
+      summary: Get a secret resource from the Key Broker Service.
       parameters:
         - in: cookie
           name: kbs-session-id
           schema:
             type: string
+        - name: repository
+          in: path
+          description: A parent path of resource, can be empty to use the default repository.
+          schema:
+            type: string
+          required: false
+        - name: type
+          in: path
+          description: Resource type name
+          schema:
+            type: string
+          required: true
+        - name: tag
+          in: path
+          description: Resource instance tag
+          schema:
+            type: string
+          required: true
       responses:
         200:
           description: >-
-            The KBS reponse including the key.
+            The KBS reponse including the resource.
             The KBS session ID is returned in a cookie named `kbs-session-id`.
           headers:
             Set-Cookie:
@@ -97,10 +115,10 @@ paths:
         401:
           description: Missing or invalid session ID
         403:
-          description: The KBC is not allowed to get that key
+          description: The KBC is not allowed to get that resource
         404:
-          description: The requested key does not exist
-  /resources/token:
+          description: The requested resource does not exist
+  /resource/token/{tag}:
     get:
       operationId: getToken
       summary: Get an external resource token from the Key Broker Service.
@@ -109,6 +127,12 @@ paths:
           name: kbs-session-id
           schema:
             type: string
+        - name: tag
+          in: path
+          description: Can be left blank to use default.
+          schema:
+            type: string
+          required: false
       responses:
         200:
           description: >-
@@ -128,7 +152,7 @@ paths:
         403:
           description: The KBC is not allowed to get a token.
         404:
-          description: The KBS does not provide token resources.
+          description: The KBS does not provide token resource.
 
 components:
   schemas:

diff --git a/docs/kbs_attestation_protocol.md b/docs/kbs_attestation_protocol.md
@@ -252,7 +252,7 @@ format:
 ``` json
 {
     "kty": "$key_type",
-    "alg": "$key_algorithm"
+    "alg": "$key_algorithm",
     "k": "public_key"
 }
 ```
@@ -383,28 +383,41 @@ A request for protected resource can fail for three reasons:
 3. The requested resource does not exist. The KBS implementation sends an HTTP
    response with a 404 (`Not Found`) status code.
 
-The KBS protocol currently supports two kinds of resources for an attester to
-request: keys and tokens.
+### Secret Resource
 
-### Key Resource
+KBS uses the following path format to locate secret resources:
 
-Keys are generic protected resources that an authenticated attester can get by
-sending a `GET` HTTP request to the `/kbs/v0/resources/key/<key_id>` endpoint.
+```
+/kbs/v0/resource/<repository>/<type>/<tag>
+```
 
-The `<key_id>` resource name is defined by the KBS. There must be a different
-`<key_id>` name for each generic secret or resource that the KBS intends to
-deliver to authenticated attesters.
+Where the URL path parameters are:
+
+- `<repository>`: This is similar to the concept of container image repository (`docker.io/{repository}/{image_name}:{tag}`), 
+which is used to facilitate users to manage different resource groups.
+Its name should be completely set by users.
+This parameter can be empty to use the default repository of KBS.
+- `<type>`: To distinguish different resource types.
+- `<tag>`: To distinguish different resource instances.
 
 The decision to reply successfully to an attester resource request for a
-specific `<key_id>` belongs to the KBS and its underlying attestation service.
+specific resource instance belongs to the KBS and its underlying attestation service.
 The decision is typically based on both the attestation evidence, results and
 provisioned policies for a given attester.
 
 ### Token Resource
 
-Authenticated attesters can also request a token from the KBS, by sending a
-`GET` HTTP request to the `/kbs/v0/resources/token/` endpoint. Attesters can use
-tokens to request additional resources from external (i.e. not the KBS) services.
+Authenticated attesters can also request a token from the KBS.
+Attesters can use tokens to request additional resources from external (i.e. not the KBS) services.
+
+KBS uses the following path format to locate token resource:
+
+```
+/kbs/v0/resource/token/{tag}
+```
+
+Where the URL path parameter `tag` specify some special token requirements,
+it can be left blank and use default token.
 
 #### Token Format
 
@@ -483,7 +496,7 @@ signature.
 
 #### HTTP Response
 
-The token is included in the `/kbs/v0/resources/token/` `GET` HTTP response
+The token is included in the `/kbs/v0/resource/token/` `GET` HTTP response
 body, as JSON content:
 
 ``` json-with-comments