Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document: Optimized the path of resources. #21

Merged
merged 1 commit into from
Dec 14, 2022
Merged

Document: Optimized the path of resources. #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 32 additions & 8 deletions docs/kbs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure what this is for. Could you give an example here?

Copy link
Member Author

@jialez0 jialez0 Dec 14, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

For example, if the user has two TEE Pod instances, the repository field can be used to manage the resources that need to be provided to the two TEE Pod instances:

/kbs/v0/resource/tee-instance-abcde123/key/<key-id>
/kbs/v0/resource/tee-instance-edcba321/key/<key-id>

Copy link
Member Author

@jialez0 jialez0 Dec 14, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And, if KBS needs to support multiple tenants in the future, repository can also be the name of the tenant, for example:

/kbs/v0/resource/Alice/key/<key-id>

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:
Expand All @@ -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.
Expand All @@ -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: >-
Expand All @@ -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:
Expand Down
41 changes: 27 additions & 14 deletions docs/kbs_attestation_protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ format:
``` json
{
"kty": "$key_type",
"alg": "$key_algorithm"
"alg": "$key_algorithm",
"k": "public_key"
}
```
Expand Down Expand Up @@ -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.

jialez0 marked this conversation as resolved.
Show resolved Hide resolved
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

Expand Down Expand Up @@ -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
Expand Down