Skip to content

Latest commit

 

History

History
 
 

kbs

README.md

Key Broker Service

The Confidential Containers Key Broker Service (KBS) facilitates remote attestation-based identity authentication and authorization, secret resource storage and access control. The KBS is an implementation of a Relying Party. The KBS itself does not validate attestation evidence. Instead, it supports different external components to verify TEE evidence in the form of plug-ins, including

Quick Start

We provide a quick start guide to deploy KBS locally and conduct configuration and testing on Ubuntu 22.04.

Typical Deployments

The KBS can be deployed in several different environments, including as part of a docker compose cluster, part of a Kubernetes cluster or without any containerization. Additionally, the KBS can interact with other attestation components in different ways. This section focuses on the different ways the KBS can interact with other components.

Background Check Mode

Background check mode is the most common way to configure the KBS and AS. The term Background Check is from the RATS architecture. In background check mode, the KBS releases secrets to a confidential guest after the attestation agent has validated the hardware evidence.

flowchart LR
    AA -- attests guest --> KBS
    CDH -- requests resource ----> KBS
    subgraph Guest
        AA <.-> CDH
    end
    subgraph Trustee
        AS -- validates evidence--> KBS
    end
Loading

In background check mode, the KBS is the relying party and the AS is the verifier.

Usages and examples for background check mode can be found here.

Passport Mode

Passport mode decouples the provisioning of resources from the validation of evidence. In background check mode these tasks are already handled by separate components, but in passport mode they are decoupled even more. The term Passport is from the RATS architecture.

In passport mode, there are two KBSes, one that uses a KBS to verify the evidence and a second to provision resources.

flowchart LR
    CDH -- requests resource ----> KBS2
    AA -- attests guest --> KBS1
    subgraph Guest
        CDH <.-> AA
    end
    subgraph Trustee 1
        AS -- validates evidence--> KBS1
    end
    subgraph Trustee 2
        KBS2
    end
Loading

In the RATS passport model the client typically connects directly to the verifier to get an attestation token (a passport). In CoCo we do not support direct conections to the AS, so KBS1 serves as an intermediary. Together KBS1 and the AS represent the verifier. KBS2 is the relying party.

Passport mode is good for use cases when resource provisioning and attestation are handled by separate entities.

Usages and examples for background check mode can be found here.

Advanced Topics

Build KBS Manually

If you do not want to use the community version of KBS (built-in-as, grpc-coco-as), you can choose to build it from the source code.

Docker image

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

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

Binary

The Makefile supports a number of other configuration parameters.

For example,

make background-check-kbs [HTTPS_CRYPTO=?] [POLICY_ENGINE=?] [AS_TYPES=?] [COCO_AS_INTEGRATION_TYPE=?] [ALIYUN=?]

The parameters

  • HTTPS_CRYPTO: either rustls or openssl can be specified. If not provided, rustls is default.
  • POLICY_ENGINE: The KBS has a policy engine to facilitate access control. This should not be confused with the policy engine in the AS, which determines whether or not TEE evidence is valid. POLICY_ENGINE determines which type of policy engine the KBS will use. Today only opa is supported. The KBS can also be built without a policy engine if it is not required.
  • AS_TYPES: The KBS supports multiple backend attestation services. AS_TYPES selects which verifier to use. The options are coco-as and intel-trust-authority-as.
  • COCO_AS_INTEGRATION_TYPE: The KBS can connect to the CoCo AS in multiple ways. COCO_AS_INTEGRATION_TYPE can be set either to grpc or builtin. With grpc the KBS will make a remote connection to the AS. If you are manually building and configuring the components, you'll need to set them up so that this connection can be established. Similar to passport mode, the remote AS can be useful if secret provisioning and attestation verification are not in the same scope. With builtin the KBA uses the AS as a crate. This is recommended if you want to avoid the complexity of a remote connection.
  • ALIYUN: The kbs support aliyun KMS as secret storage backend. true to enable building this feature. By default it is false.

HTTPS Support

The KBS can use HTTPS. This requires a crypto backend. HTTPS_CRYPTO determines which backend will be used. The options are rustls and openssl. The default is rustls.

If you want a self-signed cert for test cases, please refer to the document.

Storage Backend

The KBS can use different backend storage. LocalFs will always be builtin. ALIYUN determines whether aliyun kms support will be built. The options are true or false (by defult). Please refer to the document for more details.

References

Attestation Protocol

The KBS implements and supports a simple, vendor and hardware-agnostic implementation protocol to perform attestation.

API

KBS implements an HTTP-based, OpenAPI 3.1 compliant API. This API is formally described in its OpenAPI formatted specification.

Resource Repository

The resource repository where KBS store resource data.

Config

A custom, JSON-formatted configuration file can be provided to configure KBS.

Related Tools

KBS Client

We provide a KBS client rust SDK and binary cmdline tool.