This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Key Broker Service

Documentation for Key Broker Service

The Confidential Containers Key Broker Service (KBS) is a remote server which facilitates remote attestation. It is the reference implementation of Relying Party and Verifier in RATS role terminology.

This project relies on the Attestation-Service (AS) to verify TEE evidence.

The following TEE platforms are currently supported:

  • AMD SEV-SNP
  • Azure SNP vTPM
  • Intel SGX
  • Intel TDX

KBS has two deployment modes, which are consistent with RATS

  • Background Check Mode: KBS integrates AS to verify TEE evidence, then distribute resource data.
  • Passport Mode: One KBS integrates AS to verify TEE evidence and distribute tokens, the other KBS verifies the token then distributes resource data.

Background Check Mode

The name of Background Check is from RATS architecture.

In this mode, the Client in TEE conveys Evidence to KBS, which treats it as opaque and simply forwards it to an integrated Attestation Service. AS compares the Evidence against its appraisal policy, and returns an Attestation Token (including 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.

Here, the KBS is corresponding to the Relying Party of RATS and the AS is corresponding to the Verifier of RATS.

Build and install KBS with native integrated AS in background check mode:

make background-check-kbs
make install-kbs

The optional compile parameters that can be added are as follows:

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

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_INTEGRATION_TYPE: can be grpc or builtin. This parameter only takes effect when AS_TYPES=coco-as. Specify the integration mode of CoCo Attestation Service.

Passport Mode

The name of Passport is from RATS architecture.

In this mode, the Client in TEE conveys Evidence to one KBS which is responsible for issuing token, this KBS relies on an integrated AS to verify the Evidence against its appraisal policy. This KBS then gives back the Attestation Token which the Client treats as opaque data. The Client can then present the Attestation Token (including parsed evidence claims) to the other KBS, which is responsible for distributing resources. This KBS then compares the Token’s payload against its appraisal policy and returns the requested resource data to client.

Here, the KBS for issueing token is corresponding to the Verifier of RATS and the KBS for distributing resources is corresponding to the Rely Party of RATS.

Build and install KBS for issueing token:

make passport-issuer-kbs [HTTPS_CRYPTO=?] [AS_TYPES=?] [COCO_AS_INTEGRATION_TYPE=?]
make install-issuer-kbs

The explanation for compiling optional parameters is the same as above.

Build and install KBS for distributing resources:

make passport-resource-kbs [HTTPS_CRYPTO=?] [POLICY_ENGINE=?]
make install-resource-kbs

The explanation for compiling optional parameters is the same as above.

Documents

Quick Start

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

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.

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 for a quick start.

Tools

KBS Client

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

Dockerfile

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

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

1 - KBS backed by AKV

This documentation describes how to mount secrets stored in Azure Key Vault into a KBS deployment

Premise

AKS

We assume an AKS cluster configured with Workload Identity and Key Vault Secrets Provider. The former provides a KBS pod with the privileges to access an Azure Key Vault (AKV) instance. The latter is an implementation of Kubernetes’ Secret Store CSI Driver, mapping secrets from external key vaults into pods. The guides below provide instructions on how to configure a cluster accordingly:

AKV

There should be an AKV instance that has been configured with role based access control (RBAC), containing two secrets named coco_one coco_two for the purpose of the example. Find out how to configure your instance for RBAC in the guide below.

Provide access to Key Vault keys, certificates, and secrets with an Azure role-based access control

Note: You might have to toggle between Access Policy and RBAC modes to create your secrets on the CLI or via the Portal if your user doesn’t have the necessary role assignments.

CoCo

While the steps describe a deployment of KBS, the configuration of a Confidential Containers environment is out of scope for this document. CoCo should be configured with KBS as a Key Broker Client (KBC) and the resulting KBS deployment should be available and configured for confidential pods.

Azure environment

Configure your Resource group, Subscription and AKS cluster name. Adjust accordingly:

export SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
export RESOURCE_GROUP=my-group
export KEYVAULT_NAME=kbs-secrets
export CLUSTER_NAME=coco

Instructions

Create Identity

Create a User managed identity for KBS:

az identity create --name kbs -g "$RESOURCE_GROUP"
export KBS_CLIENT_ID="$(az identity show -g "$RESOURCE_GROUP" --name kbs --query clientId -o tsv)"
export KBS_TENANT_ID=$(az aks show --name "$CLUSTER_NAME" --resource-group "$RESOURCE_GROUP" --query identity.tenantId -o tsv)

Assign a role to access secrets:

export KEYVAULT_SCOPE=$(az keyvault show --name "$KEYVAULT_NAME" --query id -o tsv)
az role assignment create --role "Key Vault Administrator" --assignee "$KBS_CLIENT_ID" --scope "$KEYVAULT_SCOPE"

Namespace

By default KBS is deployed into a coco-tenant Namespace:

export NAMESPACE=coco-tenant
kubectl create namespace $NAMESPACE

KBS identity and Service Account

Workload Identity provides individual pods with IAM privileges to access Azure infrastructure resources. An azure identity is bridged to a Service Account using OIDC and Federated Credentials. Those are scoped to a Namespace, we assume we deploy the Service Account and KBS into the default Namespace, adjust accordingly if necessary.

export AKS_OIDC_ISSUER="$(az aks show --resource-group "$RESOURCE_GROUP" --name "$CLUSTER_NAME" --query "oidcIssuerProfile.issuerUrl" -o tsv)"
az identity federated-credential create \
	--name kbsfederatedidentity \
	--identity-name kbs \
	--resource-group "$RESOURCE_GROUP" \
	--issuer "$AKS_OIDC_ISSUER" \
	--subject "system:serviceaccount:${NAMESPACE}:kbs"

Create a Service Account object and annotate it with the identity’s client id.

cat <<EOF> service-account.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  annotations:
    azure.workload.identity/client-id: ${KBS_CLIENT_ID}
  name: kbs
  namespace: ${NAMESPACE}
EOF
kubectl apply -f service-account.yaml

Secret Provider Class

A Secret Provider Class specifies a set of secrets that should be made available to k8s workloads.

cat <<EOF> secret-provider-class.yaml
apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: ${KEYVAULT_NAME}
  namespace: ${NAMESPACE}
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"
    clientID: ${KBS_CLIENT_ID}
    keyvaultName: ${KEYVAULT_NAME}
    objects: |
      array:
      - |
        objectName: coco_one
        objectType: secret
      - |
        objectName: coco_two
        objectType: secret
    tenantId: ${KBS_TENANT_ID}
EOF
kubectl create -f secret-provider-class.yaml

Deploy KBS

The default KBS deployment needs to be extended with label annotations and CSI volume. The secrets are mounted into the storage hierarchy default/akv.

git clone https://github.com/confidential-containers/kbs.git
cd kbs
git checkout v0.8.2
cd kbs/config/kubernetes
mkdir akv
cat <<EOF> akv/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: coco-tenant

resources:
- ../base

patches:
- path: patch.yaml
  target:
    group: apps
    kind: Deployment
    name: kbs
    version: v1
EOF
cat <<EOF> akv/patch.yaml
- op: add
  path: /spec/template/metadata/labels/azure.workload.identity~1use
  value: "true"
- op: add
  path: /spec/template/spec/serviceAccountName
  value: kbs
- op: add
  path: /spec/template/spec/containers/0/volumeMounts/-
  value:
    name: secrets
    mountPath: /opt/confidential-containers/kbs/repository/default/akv
    readOnly: true
- op: add
  path: /spec/template/spec/volumes/-
  value:
    name: secrets
    csi:
      driver: secrets-store.csi.k8s.io
      readOnly: true
      volumeAttributes:
        secretProviderClass: ${KEYVAULT_NAME}
EOF
kubectl apply -k akv/

Test

The KBS pod should be running, the pod events should give indication of possible errors. From a confidential pod the AKV secrets should be retrievable via Confidential Data Hub:

$ kubectl exec -it deploy/nginx-coco -- curl http://127.0.0.1:8006/cdh/resource/default/akv/coco_one
a secret