Skip to content

Commit

Permalink
Update documents
Browse files Browse the repository at this point in the history 
1. Update README.md to explain the two deploy mode (background-check and passport)
2. Update `kbs_attestation_protocol.md` and `kbs.yaml` to adapt the new APIs and structures
3. Add a Quick Start guide

Signed-off-by: Jiale Zhang <zhangjiale@linux.alibaba.com>
  • Loading branch information
@jialez0
jialez0 committed Aug 3, 2023
1 parent 101abdb commit 93b676d
Show file tree
Hide file tree
Showing 7 changed files with 380 additions and 172 deletions.
12 changes: 8 additions & 4 deletions Cargo.lock
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

195 changes: 77 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,159 +1,118 @@
# Key Broker Service

The Confidential Containers Key Broker Service (KBS) is a remote attestation
entry point, also known as a [Relying Party](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html)
in [RATS](https://datatracker.ietf.org/doc/draft-ietf-rats-architecture/)
entry point, it is the reference implementation of [Relying Party](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html)
and [Verifier](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html) in [RATS](https://datatracker.ietf.org/doc/draft-ietf-rats-architecture/)
role terminology.

KBS integrates the [Attestation-Service](https://github.com/confidential-containers/attestation-service) to verify TEE evidence.
This project relys on the [Attestation-Service (AS)](https://github.com/confidential-containers/attestation-service) to verify TEE evidence.

KBS can also be deployed as [RATS Verifier](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html).
In this case, KBS will be responsible for distributing the Attestation Token (Following the RATS Passport model).
AS supports many different TEE platforms with a common and unified software architecture.
The following are the currently supported TEE platform types:

## Protocol
- AMD SEV-SNP
- Azure SNP vTPM
- Intel SGX
- Intel TDX

The KBS implements and supports a simple, vendor and hardware-agnostic
[implementation protocol](https://github.com/confidential-containers/kbs/blob/main/docs/kbs_attestation_protocol.md).

## API

KBS implements an HTTP-based, [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) compliant API.
This API is formally described in its [OpenAPI formatted specification](./docs/kbs.yaml).

## Attestation
KBS has two deploy model, which are consistent with [RATS](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html)
- Background Check Model: KBS integrate AS to verify TEE evidence, then distribute resource data.
- Passport Model: ABS (Attestation Broker Service) integrate AS to verify TEE evidence and distribute token,
KBS verify the token then distribute resource data.

By default, KBS relies on the [Confidential Containers Attestation-Service (AS)](https://github.com/confidential-containers/attestation-service)
to verify the TEE Evidence.
## Background Check Mode

KBS can either integrate the CoCo AS as a dependent crate, or as a separated `gRPC`
service. This integration interface is defined by the KBS `coco-as-builtin` feature.
The name of [Background Check](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html#section-5.2) is from RATS architecture.

### Integrated CoCo Attestation Service
In this mode, The Client in TEE conveys Evidence to KBS,
which treats it as opaque and simply forwards it on to integrated Attestation Service.
AS compares the Evidence against its appraisal policy, and returns an Attestation Token (include parsed evidence claims) to KBS.
The KBS then compares the Attestation Token against its own appraisal policy and return the requested resource data to client.

By default, KBS will integrate the CoCo Attestation Service as a crate.
This can be build with:

``` shell
cargo build
```

or with the default Makefile target:

``` shell
make
Build and install KBS with native integrated AS in background check mode:
```shell
make background-check-kbs
make install-kbs
```

The integrated Attestation Service configuration file can be provided at
runtime through the [KBS config file](./docs/config.md), by using the `--config`
command line option.

### `gRPC` CoCo Attestation Service

In some cases, it is preferable to deploy the Attestation Service as a separate
(local or remote) service. KBS supports that model by using the AS `gRPC`
interface, with the `coco-as-grpc` Cargo feature.

This can be built with:

``` shell
cargo build --no-default-features --features coco-as-grpc
The optional compile parameters that can be added are as follows:
```shell
make background-check-kbs [HTTPS_CRYPTO=?] [POLICY_ENGINE=?] [AS_TYPES=?] [COCO_AS_INTEGRATE_TYPE=?]
```

or with the corresponding Makefile target:
where:
- `HTTPS_CRYPTO`:
Can be `rustls` or `openssl`. Specify the library KBS uses to support HTTPS.
Default value is `rustls`
- `POLICY_ENGINE`: Can be `opa`.
Specify the resource policy engine type of KBS.
If not set this parameter, KBS will not integrate resource policy engine.
- `AS_TYPES`: can be `coco-as` or `amber-as`.
Specify the Attestation Service type KBS relies on.
- `COCO_AS_INTEGRATE_TYPE`: can be `grpc` or `builtin`. This parameter only takes effect when `AS_TYPES=coco-as`.
Specify the integration mode of CoCo Attestation Service.

``` shell
make kbs-coco-as-grpc
```

The AS `gRPC` address can be specified in the [KBS config file](./docs/config.md),
and by default KBS will try to reach a locally running AS at `127.0.0.1:50004`.
## Passport Mode

### `Amber` Attestation Service
The name of [Passport](https://www.ietf.org/archive/id/draft-ietf-rats-architecture-22.html#section-5.1) is from RATS architecture.

KBS supports Amber as the Attestation Service with the `amber-as` Cargo feature.
In this mode, Client in TEE conveys Evidence to Attestation Broker Service (ABS),
which rely on integrated AS to verify the Evidence against its appraisal policy.
ABS then gives back the Attestation Token (from AS) which the Client treats as opaque data.
The Client can then present the Attestation Token (include parsed evidence claims) to KBS,
which then compares Token payload against its appraisal policy and return the requested resource data to client.

This can be built with:

``` shell
cargo build --no-default-features --features amber-as,rustls
Build and install ABS:
```shell
make passport-abs [HTTPS_CRYPTO=?] [AS_TYPES=?] [COCO_AS_INTEGRATE_TYPE=?]
make install-abs
```

or with the corresponding Makefile target:
The explanation for compiling optional parameters is the same as above.

``` shell
make kbs-amber-as
Build and install KBS in passport mode:
```shell
make passport-kbs [HTTPS_CRYPTO=?] [POLICY_ENGINE=?]
make install-kbs
```

The Amber configuration can be specified in the [KBS config file](https://github.com/confidential-containers/kbs/blob/main/src/api/src/config.rs).

## Resource Repository

KBS stores confidential resources through a `Repository` abstraction specified
by a Rust trait. The `Repository` interface can be implemented for different
storage backends like e.g. databases or local file systems.
The explanation for compiling optional parameters is the same as above.

The [KBS config file](./docs/config.md)
defines which resource repository backend KBS will use. The default is the local
file system (`LocalFs`).
## Documents

### Local File System Repository
### Quick Start

With the local file system `Repository` default implementation, each resource
file maps to a KBS resource URL. The file path to URL conversion scheme is
defined below:
We provide a [quick start](./quickstart.md) guide to deploy KBS locally and conduct configuration and testing on Ubuntu22.04.

| Resource File Path | Resource URL |
| ------------------- | -------------- |
| `file://<$(KBS_REPOSITORY_DIR)>/<repository_name>/<type>/<tag>` | `https://<kbs_address>/kbs/v0/resource/<repository_name>/<type>/<tag>` |

The KBS root file system resource path is specified in the KBS config file
as well, and the default value is `/opt/confidential-containers/kbs/repository`.
### Attestation Protocol
The KBS implements and supports a simple, vendor and hardware-agnostic
[implementation protocol](https://github.com/confidential-containers/kbs/blob/main/docs/kbs_attestation_protocol.md) to perferm attestation.

## Usage
### API
KBS implements an HTTP-based, [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) compliant API.
This API is formally described in its [OpenAPI formatted specification](./docs/kbs.yaml).

### Build and Run
### Resource Repository
The [resource repository](./docs/resource_repository.md) where KBS store resource data.

Start KBS and specify the `HTTPS` address it should listen to with `--socket`.
When using `HTTPS`, a private key and a certificate must be provided as well:
### Config
A custom, [JSON-formatted configuration file](./docs/config.md) can be provided to configure KBS.

```shell
make kbs
./target/debug/kbs --private-key key.pem --certificate cert.pem --socket https://127.0.0.1:8080
```

KBS can also run in insecure mode, through `HTTP`. This is targeted for
development purposes and should not be used in production.

A custom, [JSON-formatted configuration file](./docs/config.md)
can also be provided:
### Cluster
We provide a `docker compose` script for quickly deploying the KBS in background check with gRPC AS,
the Reference Value Provider and the Key Provider
as local cluster services. Please refer to the [Cluster Guide](./docs/cluster.md)
for a quick start.

```shell
./target/debug/kbs --private-key key.pem --certificate cert.pem --socket https://127.0.0.1:8080 --config /path/to/config.json
```
## Tools

### Build and Deploy with Container
### KBS Client
We provide a [KBS client](./tools/client/) rust SDK and binary cmdline tool.

Build the KBS container image:
### Dockerfile
Build the KBS container (background check mode with native AS) image:

```shell
DOCKER_BUILDKIT=1 docker build -t kbs:coco-as . -f docker/Dockerfile
```

Deploy KBS with the integrated Attestation Service:

```shell
docker run -it --name=kbs --ip=<IP> -p <PORT>:<PORT> kbs:coco-as kbs -s <IP>:<PORT>
```

**Note**: When relying on a local Provisioning Certificate Caching Service (PCCS)
for verifying a TDX or SGX Evidence, the PCCS local port must be passed to
the above described `docker run` command through the `-p` option. Using
`--net host` will work as well for that use case.

### KBS cluster

We provide a `docker compose` script for quickly deploying the KBS, the
Attestation Service, the Reference Value Provider and the Key Provider
as local cluster services. Please refer to the [Cluster Guide](./docs/cluster.md)
for a quick start.

36 changes: 31 additions & 5 deletions docs/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,19 @@ The following KBS properties can be set through the configuration file:

| Property Key | Description | Optional |
|--------------------------|-------------|----------|
| `repository_type` | The resource repository type, e.g. `LocalFs`. | No |
| `repository_description` | <p> The resource repository description. <p> This is a JSON string, and is repository type specific. | Yes |
| `attestation_token_type` | Attestation token broker type, e.g. `Simple`. | No |
| `as_addr` | <p>Attestation service socket address <p>This is only relevant when running the attestation service remotely, i.e. not as a builtin crate. | Yes |
| `as_config_file_path` | <p>Attestation service configuration file path. | Yes |
| `repository_type` | The resource repository type, e.g. `LocalFs`. If deploy the server as ABS (Attestation Broker Service) in passport mode, don't set this field. | No |
| `repository_description` | <p> The resource repository description. <p> This is a JSON string, and is repository type specific. If deploy the server as ABS (Attestation Broker Service), don't set this field. | Yes |
| `attestation_token_type` | Attestation token type, e.g. `CoCo`. If deploy the server as ABS in passport mode, don't set this field. | No |
| `as_addr` | <p>Attestation service socket address <p>This is only relevant when running the attestation service remotely, i.e. not as a builtin crate. If deploy the server as KBS in passport mode, don't set this field. | Yes |
| `as_config_file_path` | <p>Attestation service configuration file path. If deploy the server as KBS in passport mode, don't set this field. | Yes |
| `as_addr` | <p>Attestation service socket address <p>This is only relevant when running the attestation service remotely, i.e. not as a builtin crate. If deploy the server as KBS in passport mode, don't set this field. | Yes |
| `amber` | <p>Amber description. <p>This is only relevant when running with Amber attestation service, and this is a JSON string, the following properties can be set: <p>`base_url` and `api_key` are used to call Amber API. <p>`certs_file` is a JWKS file to verify Amber token. <p>`allow_unmatched_policy` is optional, default is `false`. It determines whether to ignore the `amber_unmatched_policy_ids` field in Amber token. | Yes |
| `policy_path` | <p> The resource policy file path. <p> This is only relevant when enable resource policy engine. This policy is to verify the attestation result claims and decide whether the requester has authority to access specified resource. If deploy the server as ABS (Attestation Broker Service), don't set this field. | Yes |

### Examples

#### KBS in Background Check mode

Running the attestation service remotely:
``` json
{
Expand All @@ -29,6 +34,7 @@ Running the attestation service remotely:
},
"attestation_token_type": "Simple",
"as_addr": "http://127.0.0.1:50004",
"policy_path": "/opt/confidential-containers/kbs/policy.rego"
}
```

Expand All @@ -48,3 +54,23 @@ Running with Amber attestation service:
}
}
```

#### KBS in Passport mode

```json
{
"repository_type": "LocalFs",
"repository_description": {
"dir_path": "/opt/confidential-containers/kbs/repository"
},
"policy_path": "/opt/confidential-containers/kbs/policy.rego"
}
```

#### ABS in Passport mode

Running the attestation service natively:
```json
{
"as_config_file_paths": "/etc/as-config.json",
}
Loading

0 comments on commit 93b676d

Please sign in to comment.