From 22df1ebcbae99ac7b0edcb30ac1f257be2bceeef Mon Sep 17 00:00:00 2001 From: Jiale Zhang Date: Tue, 13 Dec 2022 03:48:10 -0500 Subject: [PATCH] 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 --- docs/kbs.yaml | 40 ++++++++++++++++++++++++------- docs/kbs_attestation_protocol.md | 41 +++++++++++++++++++++----------- 2 files changed, 59 insertions(+), 22 deletions(-) diff --git a/docs/kbs.yaml b/docs/kbs.yaml index 77c265091..f29df392f 100644 --- a/docs/kbs.yaml +++ b/docs/kbs.yaml @@ -71,19 +71,37 @@ paths: schema: $ref: '#/components/schemas/ErrorInformation' - /resources/key/: + /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 index 90abd2bca..1b33374bd 100644 --- 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/` endpoint. +``` +/kbs/v0/resource/// +``` -The `` resource name is defined by the KBS. There must be a different -`` name for each generic secret or resource that the KBS intends to -deliver to authenticated attesters. +Where the URL path parameters are: + +- ``: 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. +- ``: To distinguish different resource types. +- ``: To distinguish different resource instances. The decision to reply successfully to an attester resource request for a -specific `` 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