Plugging in External CA Key and Certificate

4 minute read

This task shows how operators can configure Citadel with existing root certificate, signing certificate and key.

By default, Citadel generates self-signed root certificate and key, and uses them to sign the workload certificates. Citadel can also use the operator-specified certificate and key to sign workload certificates, with operator-specified root certificate. This task demonstrates an example to plug certificates and key into Citadel.

Before you begin

Follow the Istio installation guide to install Istio with mutual TLS enabled.

Plugging in the existing certificate and key

Suppose we want to have Citadel use the existing signing (CA) certificate ca-cert.pem and key ca-key.pem. Furthermore, the certificate ca-cert.pem is signed by the root certificate root-cert.pem. We would like to use root-cert.pem as the root certificate for Istio workloads.

In the following example, Citadel’s signing (CA) certificate (ca-cert.pem) is different from root certificate (root-cert.pem), so the workload cannot validate the workload certificates directly from the root certificate. The workload needs a cert-chain.pem file to specify the chain of trust, which should include the certificates of all the intermediate CAs between the workloads and the root CA. In our example, it contains Citadel’s signing certificate, so cert-chain.pem is the same as ca-cert.pem. Note that if your ca-cert.pem is the same as root-cert.pem, the cert-chain.pem file should be empty.

These files are ready to use in the samples/certs/ directory.

The following steps enable plugging in the certificates and key into Citadel:

Create a secret cacert including all the input files ca-cert.pem, ca-key.pem, root-cert.pem and cert-chain.pem:

$ kubectl create secret generic cacerts -n istio-system --from-file=samples/certs/ca-cert.pem \
    --from-file=samples/certs/ca-key.pem --from-file=samples/certs/root-cert.pem \
    --from-file=samples/certs/cert-chain.pem

Redeploy Citadel with global.mtls.enabled set to true and security.selfSigned to false. Citadel will read certificates and key from the secret-mount files.
```
$ istioctl manifest apply --set values.global.mtls.enabled=true --set values.security.selfSigned=false
```
To make sure the workloads obtain the new certificates promptly, delete the secrets generated by Citadel (named as istio.\*). In this example, istio.default. Citadel will issue new certificates for the workloads.
```
$ kubectl delete secret istio.default
```

Verifying the new certificates

In this section, we verify that the new workload certificates and root certificates are propagated. This requires you have openssl installed on your machine.

Deploy the Bookinfo application following the instructions.
Retrieve the mounted certificates. In the following, we take the ratings pod as an example, and verify the certificates mounted on the pod.
Set the pod name to RATINGSPOD:
```
$ RATINGSPOD=`kubectl get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`
```
Run the following commands to retrieve the certificates mounted on the proxy:
```
$ kubectl exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem
```
The file /tmp/pod-root-cert.pem contains the root certificate propagated to the pod.
```
$ kubectl exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem
```
The file /tmp/pod-cert-chain.pem contains the workload certificate and the CA certificate propagated to the pod.

Verify the root certificate is the same as the one specified by operator:

$ openssl x509 -in @samples/certs/root-cert.pem@ -text -noout > /tmp/root-cert.crt.txt
$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt
$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt

Expect the output to be empty.

Verify the CA certificate is the same as the one specified by operator:

$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem
$ openssl x509 -in @samples/certs/ca-cert.pem@ -text -noout > /tmp/ca-cert.crt.txt
$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt

Expect the output to be empty.

Verify the certificate chain from the root certificate to the workload certificate:

$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem
$ openssl verify -CAfile <(cat @samples/certs/ca-cert.pem@ @samples/certs/root-cert.pem@) /tmp/pod-cert-chain-workload.pem
/tmp/pod-cert-chain-workload.pem: OK

Cleanup

To remove the secret cacerts and redeploy Citadel with self-signed root certificate:

$ kubectl delete secret cacerts -n istio-system
$ istioctl manifest apply --set values.global.mtls.enabled=true

To remove the Istio components: follow the uninstall instructions to remove.