document --ca-roots and --ca-intermediates flags for 'cosign verify'

content/en/verifying/verify.md

@@ -10,15 +10,15 @@
 The general verification format with the `cosign verify` command is as follows.
 
 ```shell
 $ cosign verify [--key <key path>|<key url>|<kms uri>] <image uri>
 ```
 ## Keyless verification using OpenID Connect
 
 We'll use `user/demo` as our example image in the following commands and keyless signing where appropriate.
 
 For identity-based verification of a container image, use the following command:
 
 ```
 $ cosign verify <image URI> [email protected]
                             --certificate-oidc-issuer=https://accounts.example.com
 
@@ -28,7 +28,7 @@
 
 The following example verifies the signature on file.txt from user [email protected] issued by [email protected]. It uses a provided bundle cosign.bundle that contains the certificate and signature.
 
 ```
 $ cosign verify-blob <file> --bundle cosign.bundle [email protected]
                               --certificate-oidc-issuer=https://accounts.example.com
 ```
@@ -56,7 +56,7 @@
 You can pass more than one image to `cosign verify`.
 
 ```shell
 $ cosign verify user-0/demo-0 user-1/demo-1
 ```
 
 ## Local verifications
@@ -64,29 +64,44 @@
 Verify with an on-disk public key provided by the signer or other organization:
 
 ```shell
 $ cosign verify --key cosign.pub user/demo
 ```
 
 Verify with an on-disk signed image from `cosign save`:
 
 ```shell
 $ cosign verify --key cosign.pub --local-image PATH/to/user/demo
 ```
 
 Verify image with local certificate and local certificate chain:
 
 ```shell
 $ cosign verify --certificate cosign.crt --certificate-chain chain.crt --certificate-oidc-issuer https://issuer.example.com --certificate-identity [email protected] user/demo
 ```
 
 ## 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