From 48c52f9dd0a4a6ddc0d2f294ddd0daa3121e2748 Mon Sep 17 00:00:00 2001 From: Oliver Liu Date: Tue, 31 Oct 2017 00:39:10 -0700 Subject: [PATCH 1/4] Add task on plugging existing key/cert into Istio CA --- _docs/tasks/security/plugin-ca-cert.md | 86 ++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 _docs/tasks/security/plugin-ca-cert.md diff --git a/_docs/tasks/security/plugin-ca-cert.md b/_docs/tasks/security/plugin-ca-cert.md new file mode 100644 index 0000000000000..f854b87cd36a8 --- /dev/null +++ b/_docs/tasks/security/plugin-ca-cert.md @@ -0,0 +1,86 @@ +--- +title: Plugging in CA certificate and key +overview: This task shows how to plug in existing key and certificate into Istio CA. + +order: 40 + +layout: docs +type: markdown +--- +{% include home.html %} + +This task shows how to plug in existing key and certificate into Istio CA. + +By default, the Istio CA generates a self-signed CA certificate and key and uses them to sign the workload certificates. +The Istio CA can also use the existing certificate and key to sign workload certificates. +This task demonstrates an example to and plug in existing cert and key 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 CA certificate + +Suppose we want to have Istio CA use the existing certificate and key `ca-cert.pem`, `ca-key.pem`. +The certificate `ca-cert.pem` is signed by the certificate `root-cert.pem`. +We would like to use `root-cert.pem` as the root certificate for Istio workloads. + +When the Istio CA certificate is not the workloads' root certificate, +the workload cannot validate the workload certificates directly from the root certificate. +In this case, 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. + +The following command downloads the example files: +```bash +wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/ca-cert.pem +wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/ca-key.pem +wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/root-cert.pem +wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/cert-chain.pem +``` + + +In this example, the `cert-chain.pem` file contains the cert of the intermediate CA, that is, `ca-cert.pem`. + +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=ca-cert.pem --from-file=ca-key.pem \ + --from-file=root-cert.pem --from-file=cert-chain.pem + ``` + +1. Redeploy Istio CA that accepts the certs and key and mounts the secret as files: + ```bash + kubectl apply -f install/kubernetes/pluggable-ca.yaml + ``` + Note that the file names are specified as arguments in `pluggable-ca.yaml`. + +1. Refresh the secret `istio.default`, but manually deleting it + (also do the same for other secrets named as istio.*): + ```bash + kubectl delete secret istio.default + ``` + +## 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 + ``` + +* To remove all the secrets generated by Istio: + ```bash + kubectl delete secret --all + ``` + +## Further reading + +* Read the Istio [CA arguments](https://github.com/istio/auth/blob/master/cmd/istio_ca/main.go). +* Read [how the sample certificates and keys are generated](https://github.com/istio/auth/blob/master/samples/plugin_ca_certs). From 2ff2b10bb20285ae991a41f2c25335314885acab Mon Sep 17 00:00:00 2001 From: Oliver Liu Date: Mon, 6 Nov 2017 11:45:57 -0800 Subject: [PATCH 2/4] Small fixes. --- _docs/tasks/security/plugin-ca-cert.md | 55 ++++++++++++-------------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/_docs/tasks/security/plugin-ca-cert.md b/_docs/tasks/security/plugin-ca-cert.md index f854b87cd36a8..78bfb9fbca621 100644 --- a/_docs/tasks/security/plugin-ca-cert.md +++ b/_docs/tasks/security/plugin-ca-cert.md @@ -11,9 +11,9 @@ type: markdown This task shows how to plug in existing key and certificate into Istio CA. -By default, the Istio CA generates a self-signed CA certificate and key and uses them to sign the workload certificates. -The Istio CA can also use the existing certificate and key to sign workload certificates. -This task demonstrates an example to and plug in existing cert and key the 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 operator specified certificate and key to sign workload certificates. +This task demonstrates an example to plug existing certificate and key into the Istio CA. ## Before you begin @@ -25,42 +25,44 @@ This task demonstrates an example to and plug in existing cert and key the Istio ## Plugging in the existing CA certificate Suppose we want to have Istio CA use the existing certificate and key `ca-cert.pem`, `ca-key.pem`. -The certificate `ca-cert.pem` is signed by the certificate `root-cert.pem`. -We would like to use `root-cert.pem` as the root certificate for Istio workloads. +Furthermore, the certificate `ca-cert.pem` is signed by the certificate `root-cert.pem`, +and we would like to use `root-cert.pem` as the root certificate for Istio workloads. -When the Istio CA certificate is not the workloads' root certificate, +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. -In this case, the workload needs a `cert-chain.pem` file to specify the chain of trust, +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 it 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. -The following command downloads the example files: +Downloads the example files: ```bash -wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/ca-cert.pem -wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/ca-key.pem -wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/root-cert.pem -wget https://raw.githubusercontent.com/istio/auth/master/samples/plugin_ca_certs/cert-chain.pem +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 ``` - -In this example, the `cert-chain.pem` file contains the cert of the intermediate CA, that is, `ca-cert.pem`. - -1. Create a secret `cacert` including all the input files - `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`: +The following steps enable plugging in the key and certificate 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=ca-cert.pem --from-file=ca-key.pem \ - --from-file=root-cert.pem --from-file=cert-chain.pem + 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 Istio CA that accepts the certs and key and mounts the secret as files: ```bash - kubectl apply -f install/kubernetes/pluggable-ca.yaml + kubectl apply -f install/kubernetes/istio-ca-plugin-certs.yaml ``` - Note that the file names are specified as arguments in `pluggable-ca.yaml`. -1. Refresh the secret `istio.default`, but manually deleting it - (also do the same for other secrets named as istio.*): +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 certificates for the workloads. ```bash kubectl delete secret istio.default ``` +Note that if you are using different file/secret names, +you need to change corresponding arguments in `istio-ca-plugin-certs.yaml`. ## Cleanup @@ -75,12 +77,7 @@ In this example, the `cert-chain.pem` file contains the cert of the intermediate kubectl delete -f install/kubernetes/istio-auth.yaml ``` -* To remove all the secrets generated by Istio: - ```bash - kubectl delete secret --all - ``` - ## Further reading -* Read the Istio [CA arguments](https://github.com/istio/auth/blob/master/cmd/istio_ca/main.go). -* Read [how the sample certificates and keys are generated](https://github.com/istio/auth/blob/master/samples/plugin_ca_certs). +* 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). From de2fbae7d3a2f4a5f151af06fecec3b7d88f4b91 Mon Sep 17 00:00:00 2001 From: Oliver Liu Date: Mon, 6 Nov 2017 14:18:49 -0800 Subject: [PATCH 3/4] Small fix. --- _docs/tasks/security/plugin-ca-cert.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/_docs/tasks/security/plugin-ca-cert.md b/_docs/tasks/security/plugin-ca-cert.md index 78bfb9fbca621..68743b227949e 100644 --- a/_docs/tasks/security/plugin-ca-cert.md +++ b/_docs/tasks/security/plugin-ca-cert.md @@ -1,6 +1,6 @@ --- title: Plugging in CA certificate and key -overview: This task shows how to plug in existing key and certificate into Istio CA. +overview: This task shows how operators can plug existing certificate and key into Istio CA. order: 40 @@ -9,11 +9,11 @@ type: markdown --- {% include home.html %} -This task shows how to plug in existing key and certificate into Istio CA. +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 operator specified certificate and key to sign workload certificates. -This task demonstrates an example to plug existing certificate and key into the Istio CA. +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 @@ -24,18 +24,18 @@ This task demonstrates an example to plug existing certificate and key into the ## Plugging in the existing CA certificate -Suppose we want to have Istio CA use the existing certificate and key `ca-cert.pem`, `ca-key.pem`. -Furthermore, the certificate `ca-cert.pem` is signed by the certificate `root-cert.pem`, +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 it is the same as `ca-cert.pem`. +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. -Downloads the example files: +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 @@ -43,25 +43,25 @@ wget -P /tmp https://raw.githubusercontent.com/istio/istio/master/security/sampl 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 key and certificate into the Istio CA: +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 Istio CA that accepts the certs and key and mounts the secret as files: +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 certificates for the workloads. + 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 file/secret names, +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`. ## Cleanup From 69225c2455922dad17503209dd2567402d9bf4ae Mon Sep 17 00:00:00 2001 From: Oliver Liu Date: Mon, 6 Nov 2017 16:42:49 -0800 Subject: [PATCH 4/4] Add verification steps. --- _docs/tasks/security/plugin-ca-cert.md | 68 +++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 2 deletions(-) diff --git a/_docs/tasks/security/plugin-ca-cert.md b/_docs/tasks/security/plugin-ca-cert.md index 68743b227949e..47160810878c1 100644 --- a/_docs/tasks/security/plugin-ca-cert.md +++ b/_docs/tasks/security/plugin-ca-cert.md @@ -22,7 +22,7 @@ This task demonstrates an example to plug certificate and key into the Istio CA. 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 CA certificate +## 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`, @@ -56,7 +56,7 @@ The following steps enable plugging in the certificate and key into the Istio CA ``` 1. To make sure the workloads obtain the new certificates promptly, - delete the secrets generated by Istio CA (named as istio.*). + 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 @@ -64,6 +64,70 @@ The following steps enable plugging in the certificate and key into the Istio CA 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`: