Key Broker Service
The Confidential Containers Key Broker Service (KBS) is a remote attestation entry point, also known as a Relying Party in RATS role terminology.
KBS integrates the Attestation-Service to verify TEE evidence.
KBS can also be deployed as RATS Verifier. In this case, KBS will be responsible for distributing the Attestation Token (Following the RATS Passport model).
Protocol
The KBS implements and supports a simple, vendor and hardware-agnostic implementation protocol.
API
KBS implements an HTTP-based, OpenAPI 3.1 compliant API. This API is formally described in its OpenAPI formatted specification.
Attestation
KBS relies on the Attestation-Service (AS) to verify the TEE Evidence.
KBS can either integrate the AS as a dependent crate, or as a separated gRPC
service. This integration interface is defined by the KBS native-as
feature.
Integrated Attestation Service
By default, KBS will integrate the Attestation Service as a crate. This can be build with:
cargo build
or with the default Makefile target:
make
The integrated Attestation Service configuration file can be provided at
runtime through the KBS config file,
by using the --config
command line option.
gRPC
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 grpc-as
Cargo feature.
This can be built with:
cargo build --no-default-features --features grpc-as
or with the corresponding Makefile target:
make kbs-grpc-as
The AS gRPC
address can be specified in the KBS config file,
and by default KBS will try to reach a locally running AS at 127.0.0.1:50004
.
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 KBS config file defined which resource repository backend KBS will use. The default is the local file system.
Local File System Repository
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:
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
.
Usage
Build and Run
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:
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 can also be provided:
./target/debug/kbs --private-key key.pem --certificate cert.pem --socket https://127.0.0.1:8080 --config /path/to/config.json
Build and Deploy with Container
Build the KBS container image:
DOCKER_BUILDKIT=1 docker build -t kbs:native-as . -f docker/Dockerfile
Deploy KBS with the integrated Attestation Service:
docker run -it --name=kbs --ip=<IP> -p <PORT>:<PORT> kbs:native-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
for a quick start.