Encryption in transit

Intra-cluster encryption in transit is implemented via a deployed service mesh, specifically Istio. At installation time, Domino can deploy Istio for Domino use only, or Domino can be configured to leverage an existing deployed Istio on the Kubernetes cluster (potentially shared with other applications). See Installation Configuration Reference for details.




Custom certificate authority certificates

Attention

This is only applicable for a Domino deployed Istio

Out of the box, Istio provides scalable identity and X.509 certificate management for use with mTLS encryption, including periodic certificate and key rotation. Because all encrypted communication is internal, these certificates are not exposed or required for communication to any external services, such as web browsers and clients.

We do understand that certain enterprise policies mandate the use of corporate public key infrastructure (PKI) and necessitate the use of certificate authority (CA) certificates.

Setting up custom CA certificates

Note

All certificates must be X.509 PEM format and keys must be passwordless.

Filename Description
root-cert.pem Root CA certificate for PKI.
ca-cert.pem Intermediate CA certificate from root CA. This is the Istio CA certificate.
ca-key.pem Private key for Istio CA certificate.
cert-chain.pem Full chain from ca-cert.pem to root-cert.pem (including both certificates).

Assuming N intermediate certificates denoted as int-ca-<i>.pem, with i = {1,...,N}.

# Concatenate all certificates
cat ca-cert.pem int-ca-1.pem ... int-ca-N.pem root-cert.pem > cert-chain.pem
# Create new secret with CA cert files
kubectl -n istio-system create secret generic cacerts \
    --from-file=./ca-cert.pem \
    --from-file=./ca-key.pem \
    --from-file=./root-cert.pem \
    --from-file=./cert-chain.pem

New Domino installation

A standard installation following the install process with the fleetcommand-agent (Domino installer) will automatically pick up the created Secret and Istio will use the custom CA certificates.

Existing Domino installation

Restarting all the pods of the existing Domino installation

Updating existing custom CA certificates

This section describes how to update the custom CA certificate used by Istio for intra-cluster encryption in transit. There are two scenarios:

  1. No changes to the private key and common name

This assumes only ca-cert.pem is updated.

  1. Updated to the private key, common name, or upstream certificates

Any of the certificate files have changed, including any upstream intermediate certificates.

In both cases, you need to create a new full chain certificate file (cert-chain.pem)

Tip

We recommend backing up existing certificates and keys before updating new ones.

No changes to private key and common name

The procedure to update the custom CA certificates is to create a Secret with a new files and restart the Istio daemon (istiod).

# Delete existing secret with CA cert files
kubectl -n istio-system delete secret cacerts

# Create new secret with CA cert files
kubectl -n istio-system create secret generic cacerts \
    --from-file=./ca-cert.pem \
    --from-file=./ca-key.pem \
    --from-file=./root-cert.pem \
    --from-file=./cert-chain.pem

# Restarting all istiod pods
kubectl -n istio-system delete po -l app=istiod

Updated private key, common name, or upstream certificates

If changes have been made or are needed to the private key, common name (CN) or upstream certificates, a full restart is required in addition to creating a new Secret with the new files an restarting the Istio daemon in the previous section.

# Delete existing secret with CA cert files
kubectl -n istio-system delete secret cacerts

# Create new secret with CA cert files
kubectl -n istio-system create secret generic cacerts \
    --from-file=./ca-cert.pem \
    --from-file=./ca-key.pem \
    --from-file=./root-cert.pem \
    --from-file=./cert-chain.pem

# Full restart for all Istio pods
for NS in istio-system domino-platform domino-compute; \
do \
    kubectl -n $NS get po --no-headers -o custom-columns=name:metadata.name | xargs kubectl -n $NS delete po; \
done