Trireme-csr

Trireme-CSR is an identity and root of trust service running as a controller on Kubernetes. It is used by Trireme-Kubernetes to bootstrap the root of trust, but could be used in other project as a standalone component.

It is composed of two distinct components:

• A client library: runtimes can import the trireme-csr client library and generate a KeyPair and associated Certificate Signing Request. A Custom Ressource Definition is used in order to store the CSR on the Kubernetes API.
• A Trireme-CSR controller: as a controller on that Custom Ressource Definition is then responsible for validating and issuing the corresponding certificate.

The initial client receives the generated certificate as part of the Custom Ressource Definition status.

This scheme allows each node to receive a valid certificate generated by a central trusted Certificate Authority.

Generating or providing a Valid CA

The Trireme-CSR requires a valid Certificate Authority in order to provide the root of trust. This Certificate Authority can be an existing one in your organisation or it could be generated specifically for Trireme-CSR

The Certificate Authority is provided to the controler through a standard Kubernetes secret. It is expected to be found in a secret trireme-cacert by default.

This script can be used as an example on howto generate an example Certificate Authority and push it as a secret to Kubernetes:

wget https://raw.githubusercontent.com/aporeto-inc/trireme-kubernetes/master/deployment/gen_pki_ca.sh
./gen_pki_ca.sh

Deploying the Trireme-CSR controller

The controller is deployed as a standard Kubernetes pod. It expects the CACert and CAKey to be mounted (By default it will be mounted from the existing secret). It also requires the Certificate Custom Ressource definition to be already created.

All of this can be done by deploying the following files:

• Config Map used for all the configuration. Ideally it should be reviewed before being deployed:

kubectl create -f https://raw.githubusercontent.com/aporeto-inc/trireme-kubernetes/master/deployment/trireme/trireme-cm.yaml

• Certificate Custom Ressource Definition:

kubectl create -f https://raw.githubusercontent.com/aporeto-inc/trireme-kubernetes/master/deployment/trireme/cert-crd.yaml

• ServiceAccount and roles used for access to the Certificates:

kubectl create -f https://raw.githubusercontent.com/aporeto-inc/trireme-kubernetes/master/deployment/trireme/certgen-serviceaccount.yaml

• Trireme-CSR Controller as a ReplicaSet:

kubectl create -f https://raw.githubusercontent.com/aporeto-inc/trireme-kubernetes/master/deployment/trireme/certgen-rs.yaml

Requesting an identity//certificate

In order for a client to request an identity to the controller source of truth, a new object needs to be created as Certificate with a Certificate Signing Request enclosed in the object Spec. See details about the object specification in the CRD section .

This process can be done manually or automated by using the Trireme-CSR client library. The client library first generates a Keypair and stores it in-memory. A corresponding certificate is then generated and a Certificate object is created on Kubernetes API. The library then blocks and waits for the Controller to fulfill the request and generate and send the certificate back.

An example implementation using the Trireme-CSR client library can be found in the example directory

Certificate Custom Resource Definition

A new object type is defined on Kubernetes API (using a Custom Ressource Definition) that contains the Certificate Signing Request as part of the request and the validated and signed certificate as part of the response (status).

This new object is defined as following:

apiVersion: certmanager.k8s.io/v1alpha1
kind: Certificate
metadata:
  name: node1
spec:
  request: [CSR PEM]
status:
  ca: [CA PEM]
  certificate: [CERT PEM] 
  token: [Smart Token]
  state: created

The spec is filled in by the client at object creation time with the CSR. The Controller creates and updates the status part of the definition with the CA, Certificate, SmartToken (More on this later), and state of the certificate (created, rejected, processing)

The definition of the certificates object can be found here

Using Kubernetes API as a gatekeeper

In order to provide an identity Root of Trust, Trireme-CSR is leveraging Kubernetes API access control (Also known as ABAC//RBAC). The key concept is that only the cluster-admin should be able to create the root of trust (The CA).

ABAC//RBAC is used in order to define two additional cluster roles that define granular permissions related to the certificates:

• trireme-cert-generator: This is the permissions associated to the Trireme-CSR controller. It defines the right to create and update the Certificate object.
• trireme-enforcer-role: As an example, those are the permissions generated for Trireme-Kubernetes. It includes the ability to create and get//list the Certificate object.

In order to keep the whole scheme secure, all the pods on the cluster should run with the minimal required privileges. The role to create certificate should only be used if the pod is required to create a certificate.

Prerequisite

• Kubernetes 1.7 (Custom Ressource Definitions are required)