document --ca-roots and --ca-intermediates flags for 'cosign verify' (#…

…310)

* document --ca-roots flag for 'cosign verify'

Related to sigstore/cosign#3462.
Document the new 'cosign verify' --ca-roots flag and
its difference to the --certificate-chain flag.
List the supported and currently unsupported use cases
(single/multiple CA(s), intermediate CAs).

Signed-off-by: Dmitry S <[email protected]>

* add docs on --ca-intermediates for 'cosign verify'

Signed-off-by: Dmitry S <[email protected]>

* markdown fixes - add empty lines around shell backticks

Signed-off-by: Dmitry S <[email protected]>

---------

Signed-off-by: Dmitry S <[email protected]>

content/en/verifying/verify.md

@@ -80,13 +80,28 @@ $ cosign verify --certificate cosign.crt --certificate-chain chain.crt --certifi
 ```
 
 ## Verify image with user-provided trusted chain
-Verify image with the provided certificate chain and identity parameters (intended for
-a "bring your own PKI" use case):
+
+Verify image with the provided certificate chain(s) and identity parameters (intended for
+"bring your own PKI" use cases).
+
+* with a single certificate chain file - which may contain one or several intermediate
+certificates followed by the root CA certificate - use the `--certificate-chain` parameter:
 
 ```shell
 $ cosign verify --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
 ```
 
+* with a certificate bundle PEM file containing several CA roots and (optionally)
+intermediate certificates, use the `--ca-roots` parameter together with `--ca-intermediates`:
+
+```shell
+$ cosign verify --ca-roots ca-roots.pem --ca-intermediates ca-intermediates \
+  --certificate-oidc-issuer https://issuer.example.com \
+  --certificate-identity [email protected] user/demo
+```
+
+The `--ca-roots` and `--ca-intermediates` flags are mutually exclusive with `--certificate-chain`.
+
 ## Verify an image on the transparency log
 
 ```shell