Merge pull request #41446 from rh-tokeefe/OSSMDOC-406

OSSMDOC-406: Verify instructions in section "Verifying your certifica…

Author: JStickler

modules/ossm-security-cert-manage.adoc

@@ -12,15 +12,16 @@ By default, {SMProductName} generates a self-signed root certificate and key and
 * Install {SMProductName} with mutual TLS enabled to configure certificates.
 * This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority.
 * Deploy the Bookinfo sample application to verify the results with these instructions.
+* OpenSSL is required to verify certificates.
 
 [id="ossm-cert-manage-add-cert-key_{context}"]
 == Adding an existing certificate and key
 
 To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is named `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is named `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file.
 
-Add the certificates to {SMProductShortName} by following these steps. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository] locally and replace `<path>` with the path to your certificates.
+. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository] locally and replace `<path>` with the path to your certificates.
 
-. Create a secret `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
+. Create a secret named `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
 +
 [source,terminal]
 ----
@@ -29,7 +30,7 @@ $ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pe
     --from-file=<path>/cert-chain.pem
 ----
 +
-. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls: true` to `true` and configure your certificateAuthority like the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location.  {SMProductShortName} reads the certificates and key from the secret-mount files.
+. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls true` to `true` and configure the `certificateAuthority` field as shown in the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location.  {SMProductShortName} reads the certificates and key from the secret-mount files.
 +
 [source,yaml]
 ----
@@ -44,97 +45,117 @@ spec:
       istiod:
         type: PrivateKey
         privateKey:
-          rootCADir:  /etc/cacerts
+          rootCADir: /etc/cacerts
 ----
 
-[id="ossm-cert-manage-verify-cert_{context}"]
-== Verifying your certificates
-
-Use the Bookinfo sample application to verify your certificates are mounted correctly. First, retrieve the mounted certificates. Then, verify the certificates mounted on the pod.
-
-. Store the pod name in the variable `RATINGSPOD`.
+. After creating/changing/deleting the `cacert` secret, the control plane `istiod` and `gateway` pods must be restarted so the changes go into effect. Use the following command to restart the pods:
 +
 [source,terminal]
 ----
-$ RATINGSPOD=`oc get pods -l app=ratings -o jsonpath='{.items[0].metadata.name}'`
+$ $ oc -n istio-system delete pods -l 'app in (istiod,istio-ingressgateway, istio-egressgateway)'
 ----
 +
-. Run the following commands to retrieve the certificates mounted on the proxy.
+The Operator will automatically recreate the pods after they have been deleted.
+
+. Restart the bookinfo application pods so that the sidecar proxies pick up the secret changes. Use the following command to restart the pods:
 +
 [source,terminal]
 ----
-$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /var/run/secrets/istio/root-cert.pem > /tmp/pod-root-cert.pem
+$ oc -n bookinfo delete pods --all
 ----
 +
-The file `/tmp/pod-root-cert.pem` contains the root certificate propagated to the pod.
+You should see output similar to the following:
 +
+
 [source,terminal]
 ----
-$ oc exec -it $RATINGSPOD -c istio-proxy -- /bin/cat /etc/certs/cert-chain.pem > /tmp/pod-cert-chain.pem
+pod "details-v1-6cd699df8c-j54nh" deleted
+pod "productpage-v1-5ddcb4b84f-mtmf2" deleted
+pod "ratings-v1-bdbcc68bc-kmng4" deleted
+pod "reviews-v1-754ddd7b6f-lqhsv" deleted
+pod "reviews-v2-675679877f-q67r2" deleted
+pod "reviews-v3-79d7549c7-c2gjs" deleted
 ----
+
+. Verify that the pods were created and are ready with the following command:
 +
-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 the Operator. Replace `<path>` with the path to your certificates.
-+
+
 [source,terminal]
 ----
-$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
+$ oc get pods -n bookinfo
 ----
+
+[id="ossm-cert-manage-verify-cert_{context}"]
+== Verifying your certificates
+
+Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This requires you have `openssl` installed on your machine
+
+. To extract certificates from bookinfo workloads use the following command:
 +
 [source,terminal]
 ----
-$ openssl x509 -in /tmp/pod-root-cert.pem -text -noout > /tmp/pod-root-cert.crt.txt
+$ sleep 60
+$ oc -n bookinfo exec "$(oc -n bookinfo get pod -l app=productpage -o jsonpath={.items..metadata.name})" -c istio-proxy -- openssl s_client -showcerts -connect details:9080 > bookinfo-proxy-cert.txt
+$ sed -n '/-----BEGIN CERTIFICATE-----/{:start /-----END CERTIFICATE-----/!{N;b start};/.*/p}' bookinfo-proxy-cert.txt > certs.pem
+$ awk 'BEGIN {counter=0;} /BEGIN CERT/{counter++} { print > "proxy-cert-" counter ".pem"}' < certs.pem
 ----
 +
+After running the command, you should have three files in your working directory: `proxy-cert-1.pem`, `proxy-cert-2.pem` and `proxy-cert-3.pem`.
+
+. Verify that the root certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
++
 [source,terminal]
 ----
-$ diff /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
+$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
 ----
 +
-Expect the output to be empty.
-+
-. Verify the CA certificate is the same as the one specified by Operator. Replace `<path>` with the path to your certificates.
+Run the following syntax at the terminal window.
 +
 [source,terminal]
 ----
-$ sed '0,/^-----END CERTIFICATE-----/d' /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-ca.pem
+$ openssl x509 -in ./proxy-cert-3.pem -text -noout > /tmp/pod-root-cert.crt.txt
 ----
 +
-[source,terminal]
-----
-$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
-----
+Compare the certificates by running the following syntax at the terminal window.
 +
 [source,terminal]
 ----
-$ openssl x509 -in /tmp/pod-cert-chain-ca.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
+$ diff -s /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
 ----
 +
+You should see the following result:
+`Files /tmp/root-cert.crt.txt and /tmp/pod-root-cert.crt.txt are identical`
+
+
+. Verify that the CA certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
++
 [source,terminal]
 ----
-$ diff /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
+$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
 ----
-+
-Expect the output to be empty.
-+
-. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
+Run the following syntax at the terminal window.
 +
 [source,terminal]
 ----
-$ head -n 21 /tmp/pod-cert-chain.pem > /tmp/pod-cert-chain-workload.pem
+$ openssl x509 -in ./proxy-cert-2.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
 ----
+Compare the certificates by running the following syntax at the terminal window.
 +
 [source,terminal]
 ----
-$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) /tmp/pod-cert-chain-workload.pem
+$ diff -s /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
 ----
+You should see the following result:
+`Files /tmp/ca-cert.crt.txt and /tmp/pod-cert-chain-ca.crt.txt are identical.`
+
+. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
 +
-.Example output
 [source,terminal]
 ----
-/tmp/pod-cert-chain-workload.pem: OK
+$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) ./proxy-cert-1.pem
 ----
+You should see the following result:
+`./proxy-cert-1.pem: OK`
 
 [id="ossm-cert-cleanup_{context}"]
 == Removing the certificates
@@ -155,6 +176,7 @@ $ oc delete secret cacerts -n istio-system
 apiVersion: maistra.io/v2
 kind: ServiceMeshControlPlane
 spec:
-  dataPlane:
-    mtls: true
+  security:
+    dataPlane:
+      mtls: true
 ----