diff --git a/_docs/tasks/security/plugin-ca-cert.md b/_docs/tasks/security/plugin-ca-cert.md new file mode 100644 index 0000000000..4716081087 --- /dev/null +++ b/_docs/tasks/security/plugin-ca-cert.md @@ -0,0 +1,147 @@ +--- +title: Plugging in CA certificate and key +overview: This task shows how operators can plug existing certificate and key into Istio CA. + +order: 40 + +layout: docs +type: markdown +--- +{% include home.html %} + +This task shows how operators can plug existing certificate and key into Istio CA. + +By default, the Istio CA generates self-signed CA certificate and key and uses them to sign the workload certificates. +The Istio CA can also use the operator-specified certificate and key to sign workload certificates. +This task demonstrates an example to plug certificate and key into the Istio CA. + +## Before you begin + +* Set up Istio on auth-enabled Kubernetes by following the instructions in the + [quick start]({{home}}/docs/setup/kubernetes/quick-start.html). + Note that authentication should be enabled at step 4 in the + [installation steps]({{home}}/docs/setup/kubernetes/quick-start.html#installation-steps). + +## Plugging in the existing certificate and key + +Suppose we want to have Istio CA use the existing certificate `ca-cert.pem` and key `ca-key.pem`. +Furthermore, the certificate `ca-cert.pem` is signed by the root certificate `root-cert.pem`, +and we would like to use `root-cert.pem` as the root certificate for Istio workloads. + +In this example, because the Istio CA certificate (`ca-cert.pem`) is not set as the workloads' root certificate (`root-cert.pem`), +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 this example, it only contains the Istio CA 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`, you can have an empty `cert-chain.pem` file. + +Download the example files: +```bash +wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/ca-cert.pem +wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/ca-key.pem +wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/root-cert.pem +wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/samples/plugin_ca_certs/cert-chain.pem +``` + +The following steps enable plugging in the certificate and key into the Istio CA: +1. Create a secret `cacert` including all the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`: + ```bash + kubectl create secret generic cacerts -n istio-system --from-file=/tmp/ca-cert.pem --from-file=/tmp/ca-key.pem \ + --from-file=/tmp/root-cert.pem --from-file=/tmp/cert-chain.pem + ``` + +1. Redeploy the Istio CA, which reads the certificates and key from the secret-mount files: + ```bash + kubectl apply -f install/kubernetes/istio-ca-plugin-certs.yaml + ``` + +1. To make sure the workloads obtain the new certificates promptly, + delete the secrets generated by Istio CA (named as istio.\*). + In this example, `istio.default`. The Istio CA will issue new certificates for the workloads. + ```bash + kubectl delete secret istio.default + ``` +Note that if you are using different certificate/key file or secret names, +you need to change corresponding arguments in `istio-ca-plugin-certs.yaml`. + +## 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]({{home}}/docs/guides/bookinfo.html). + +1. Retrieve the mounted certificates. + + Get the pods: + ```bash + kubectl get pods + ``` + + which produces: + ```bash + NAME READY STATUS RESTARTS AGE + details-v1-1520924117-48z17 2/2 Running 0 6m + productpage-v1-560495357-jk1lz 2/2 Running 0 6m + ratings-v1-734492171-rnr5l 2/2 Running 0 6m + reviews-v1-874083890-f0qf0 2/2 Running 0 6m + reviews-v2-1343845940-b34q5 2/2 Running 0 6m + reviews-v3-1813607990-8ch52 2/2 Running 0 6m + ``` + + In the following, we take the pod `ratings-v1-734492171-rnr5l` as an example, and verify the mounted certificates. + Run the following commands to retrieve the certificates mounted on the proxy: + + ```bash + kubectl exec -it ratings-v1-734492171-rnr5l -c istio-proxy -- /bin/cat /etc/certs/root-cert.pem > /tmp/pod-root-cert.pem + ``` + The file `/tmp/pod-root-cert.pem` should contain the root certificate specified by the operator. + + ```bash + kubectl exec -it ratings-v1-734492171-rnr5l -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem + ``` + The file `/tmp/pod-cert-chain.pem` should contain the workload certificate and the CA certificate. + +1. Verify the root certificate is the same as the one specified by operator: + ```bash + openssl x509 -in /tmp/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 + ``` + +1. Verify that the CA certificate is the same as the one specified by operator: + ```bash + tail /tmp/pod-cert-chain.pem -n 22 > /tmp/pod-cert-chain-ca.pem + openssl x509 -in /tmp/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 that the output to be empty. + +1. Verify the certificate chain from the root certificate to the workload certificate: + ```bash + head /tmp/pod-cert-chain.pem -n 18 > /tmp/pod-cert-chain-workload.pem + openssl verify -CAfile <(cat /tmp/ca-cert.pem /tmp/root-cert.pem) /tmp/pod-cert-chain-workload.pem + ``` + Expect the following output: + ```bash + /tmp/pod-cert-chain-workload.pem: OK + ``` + +## Cleanup + +* To remove the secret `cacerts`: + + ```bash + kubectl delete secret cacerts -n istio-system + ``` + +* To remove the Istio components: + ```bash + kubectl delete -f install/kubernetes/istio-auth.yaml + ``` + +## Further reading + +* Read the [Istio CA arguments](https://github.com/istio/istio/blob/master/security/cmd/istio_ca/main.go). +* Read [how the sample certificates and keys are generated](https://github.com/istio/istio/blob/master/security/samples/plugin_ca_certs).