trusted-attestation-controller

README

trusted-attestation-controller

• Overview
• Getting started
  • Prerequisites
  • Installing with source code
  • Provision TCS issuer root certificate and private key
• Attestation Plugins
• Limitations

Overview

The Trusted Attestation Controller is a Kubernetes controller for reconciling the QuoteAttestation requests initiated by the Trusted Certificate Service (TCS). It mediates between the TCS and the key server(s) which supports attestation services. The key servers could plugin to the controller by implementing the API provided by the controller.

Getting started

This section covers how to getting started with the Trusted Attestation Controller. That includes how to build and deploy the controller to a Kubernetes cluster.

Prerequisites

Prerequisites for building and running Trusted Attestation Controller:

• Kubernetes cluster with running Trusted Certificate Service
• Key Management Reference Application (KMRA) AppHSM Server
• git, or similar tool, to obtain the source code
• Docker, or similar tool, to build container images
• Container registry (local or remote)

Installing with source code

This section covers how to obtain the source code, build and install it.

1. Getting the source code

git clone https://github.com/intel/trusted-attestation-controller.git

1. Build and push the container image

Choose a container registry to push the generated image using REGISTRY make variable. The registry should be reachable from the Kubernetes cluster.

$ cd trusted-attestation-controller
$ export REGISTRY="localhost:5000" # docker registry to push the container image
$ make docker-build docker-push

1. Deploy QuoteAttestation CRD

# set the KUBECONFIG based on your configuration
export KUBECONFIG="$HOME/.kube/config"
kubectl apply -f https://raw.githubusercontent.com/intel/trusted-certificate-issuer/main/deployment/crds/quoteattestations.tcs.intel.com.yaml

1. Setup a key server

Download the KMRA v2.0 source code and refer to its instructions for setting up the key server on a host that is securely accessible from your Kubernetes cluster.

1. Configure the key server url and credentials

export SERVER_URL=<<https://server-address:port>>
sed -ie "s;^KEY_SERVER=\(.*\);$SERVER_URL;g" ./config/manager/.kmra-server.conf
sed -e "s;^\(ca.crt=\).*;\1$(base64 -w 0 /ca/certificate/file);g" \
     -e "s;^\(client.crt=\).*;\1$(base64 -w 0 /client/certificate/file);g" \
     -e "s;^\(client.key=\).*;\1$(base64 -w 0 /client/privatekey/file);g" ./config/manager/.ca.secrets

1. Deploy the controller

make deploy

Provision TCS issuer root certificate and private key

Once the deployment is up and running, it is ready to accept QuoteAttestation custom resources.

Create a TCSIssuer with spec.selfSign set to false. This results in a QuoteAttestation object gets created by the TCS with its SGX enclave quote and a public key.

kubectl create ns sandbox
cat <<EOF |kubectl create -f -
apiVersion: tcs.intel.com/v1alpha1
kind: TCSIssuer
metadata:
    name: my-ca
    namespace: sandbox
spec:
    secretName: my-ca-cert
    selfSign: false
EOF

kubectl get quoteattestation,tcsissuer -n sandbox
NAME                                                           AGE
quoteattestation.tcs.intel.com/my-ca.tcsissuer.tcs.intel.com   0s

NAME                            AGE   READY   REASON      MESSAGE
tcsissuer.tcs.intel.com/my-ca   10s   False   Reconcile   Signer is not ready

And, the Trusted Attestation Controller reconciles this request and forwards the attestation request to the configured key server plugin, in this case the KMRA. The server validates the provided SGX quote. Only if the validation success, the controller requests the server to fetch the encrypted CA private key and certificate and it updates the QuoteAttestation object status with the results. Then the TCS enclave decrypts the key, and TCS deletes the QuoteAttestation object silently.

kubectl get quoteattestation,tcsissuer -n sandbox
NAME                            AGE   READY   REASON      MESSAGE
tcsissuer.tcs.intel.com/my-ca   1m    True    Reconcile   Success

Attestation Plugins

To integrate the external key management servers with TCS, the attestation controller provides a GRPC based plugin API. Refer to developer documentation for writing attestation plugins.

Limitations

• This version of the software is pre-production release and is meant for evaluation and trial purposes only.