istio.io/content/docs/tasks/security/plugin-ca-cert.md

145 lines
5.8 KiB
Markdown

---
title: Plugging in external CA key and certificate
description: Shows how operators can configure Citadel with existing root certificate, signing certificate and key.
weight: 60
---
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](/docs/setup/kubernetes/quick-start/).
Note that authentication should be enabled at step 5 in the
[installation steps](/docs/setup/kubernetes/quick-start/#installation-steps).
## 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:
1. Create a secret `cacert` including all the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`:
```command
$ 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
```
1. Redeploy Citadel, which reads the certificates and key from the secret-mount files:
```command
$ 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`.
1. 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.
```command
$ 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.
1. Deploy the bookinfo application following the [instructions](/docs/guides/bookinfo/).
1. 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`:
```command
$ 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:
```command
$ 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.
```command
$ 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.
1. Verify the root certificate is the same as the one specified by operator:
```command
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.
1. Verify the CA certificate is the same as the one specified by operator:
```command
$ 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.
1. Verify the certificate chain from the root certificate to the workload certificate:
```command
$ 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
```
Expect the following output:
```command
/tmp/pod-cert-chain-workload.pem: OK
```
## Cleanup
* To remove the secret `cacerts`:
```command
$ kubectl delete secret cacerts -n istio-system
```
* To remove the Istio components:
```command
$ kubectl delete -f install/kubernetes/istio-auth.yaml
```
## What's next
* Read more about [Citadel (codename is istio\_ca) arguments](/docs/reference/commands/istio_ca/).
* Read [how the sample certificates and keys are generated](https://github.com/istio/istio/blob/master/security/samples/plugin_ca_certs).