Plugging in external CA key and certificate

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

Set up Istio by following the instructions in the quick start with global mutual TLS enabled:
```
$ kubectl apply -f install/kubernetes/istio-demo-auth.yaml
```
OR Using Helm with global.mtls.enabled to true.

From Istio 0.7, you can use authentication policy to configure mutual TLS for all/selected services in a namespace (repeated for all namespaces to get global setting). See authentication policy task

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, which reads the certificates and key from the secret-mount files:
```
$ kubectl apply -f @install/kubernetes/istio-citadel-plugin-certs.yaml@
```
Note: if you are using different certificate/key file or secret names, you need to change corresponding volume mounts and arguments in istio-citadel-plugin-certs.yaml.
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:

$ tail -n 22 /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:

$ kubectl delete secret cacerts -n istio-system

To remove the Istio components:

$ kubectl delete -f @install/kubernetes/istio-auth.yaml@

What's next

Read more about Citadel (codename is istio_ca) arguments.
Read how the sample certificates and keys are generated.