From 85a140643989ba6736e87eeba852e1acf61e4ff0 Mon Sep 17 00:00:00 2001
From: Charles Nguyen <charles.nguyen@nomadic-labs.com>
Date: Tue, 17 Sep 2024 16:48:56 +0200
Subject: [PATCH 1/2] docs: update cosign verify documentation

---
 docs/introduction/cosign-verify.rst | 58 +++++++++++++++++++++++++----
 docs/introduction/howtoget.rst      |  2 +-
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/docs/introduction/cosign-verify.rst b/docs/introduction/cosign-verify.rst
index ef13d168c2f8..2f63aab44cbb 100644
--- a/docs/introduction/cosign-verify.rst
+++ b/docs/introduction/cosign-verify.rst
@@ -18,14 +18,14 @@ Obtaining the Public Key
 ------------------------
 To verify a signed Docker image, you need the public key that corresponds to
 the private key used for signing. The pem certificate is available at
-https://storage.googleapis.com/nl-prod-sign-keyring/nl-prod-docker-sign-key.pem
+https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem
 
 Saving the public key:
 
 .. code-block:: bash
 
     # Save the public key to a file (e.g., octez.pub)
-    curl -O https://storage.googleapis.com/nl-prod-sign-keyring/nl-prod-docker-sign-key.pem octez.pub
+    curl -o octez.pub https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem
 
 Verifying the Docker Image
 --------------------------
@@ -39,14 +39,58 @@ To verify the Octez Docker image, follow these steps:
 
 2. **Use Cosign to Verify the Image**:
 
+   Replace the image name with the name of your Docker image and tag with the
+   specific tag ( for example ``tezos/tezos:22.0`` )
+
    .. code-block:: bash
 
-       cosign verify -key octez.pub tezos/tezos-bare:master
+       cosign verify --key octez.pub tezos/tezos-bare:master
 
-   Replace the image name with the name of your Docker image and tag with the
-   specific tag ( for example ``tezos/tezos:22.0`` )
+   Or more directly:
+
+   .. code-block:: bash
+
+       cosign verify --key https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem tezos/tezos-bare:master
 
 3. **Check the Output**:
 
-- If the verification is successful, Cosign will output the signatures and their claims.
-- If the verification fails, an error message will be displayed indicating the failure reason. You can use tools like ``jq`` to parse the json output of Cosign.
+   You can use tools like ``jq`` to parse the json output of Cosign:
+
+   .. code-block:: bash
+
+       cosign verify --key https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem tezos/tezos-bare:master | jq
+
+- If the verification is successful, Cosign will output the signatures and their claims in JSON format:
+
+   .. code-block:: JSON
+
+       The following checks were performed on each of these signatures:
+       - The cosign claims were validated
+       - Existence of the claims in the transparency log was verified offline
+       - The signatures were verified against the specified public key
+       [
+         {
+           "critical": {
+             "identity": {
+                 "docker-reference": "<image>"
+             },
+             "image": {
+               "docker-manifest-digest": "sha256:<digest>"
+             },
+             "type": "cosign container image signature"
+           },
+           "optional": {
+             "Bundle": {
+               "SignedEntryTimestamp": "<timestamp's signature>",
+               "Payload": {
+                 "body": "<payload>",
+                 "integratedTime": <time>,
+                 "logIndex": <logIndex>,
+                 "logID": "<logId>"
+               }
+             }
+           }
+         }
+       ]
+
+- If the verification fails, an error message will be displayed indicating the failure reason.
diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst
index a106ca1e875f..6c2d7294c294 100644
--- a/docs/introduction/howtoget.rst
+++ b/docs/introduction/howtoget.rst
@@ -199,7 +199,7 @@ automatically generated and published on `DockerHub
 <https://hub.docker.com/r/tezos/tezos/>`_. This provides a convenient
 way to run an always up-to-date ``octez-node``.
 
-From version 22.0 all Docker images for tezos are signed using Cosign.
+From version 22.0 all Octez Docker images are signed using Cosign.
 You can verify if the images are correctly signed using the Cosign utility, as explained below:
 
 .. toctree::
-- 
GitLab


From 36c606b78d3b5179c37352c5e934cb7ec2bbc2a3 Mon Sep 17 00:00:00 2001
From: Charles Nguyen <charles.nguyen@nomadic-labs.com>
Date: Fri, 20 Sep 2024 22:30:39 +0200
Subject: [PATCH 2/2] docs: update cosign doc format

---
 docs/introduction/cosign-verify.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/docs/introduction/cosign-verify.rst b/docs/introduction/cosign-verify.rst
index 2f63aab44cbb..48c140126103 100644
--- a/docs/introduction/cosign-verify.rst
+++ b/docs/introduction/cosign-verify.rst
@@ -60,14 +60,17 @@ To verify the Octez Docker image, follow these steps:
 
        cosign verify --key https://keyserver.nomadic-labs.com/cosign/nl-prod-docker-sign-key.pem tezos/tezos-bare:master | jq
 
-- If the verification is successful, Cosign will output the signatures and their claims in JSON format:
+   If the verification is successful, Cosign will output the signatures and their claims in JSON format:
 
-   .. code-block:: JSON
+   .. code-block:: bash
 
        The following checks were performed on each of these signatures:
        - The cosign claims were validated
        - Existence of the claims in the transparency log was verified offline
        - The signatures were verified against the specified public key
+
+   .. code-block:: JSON
+
        [
          {
            "critical": {
@@ -84,8 +87,8 @@ To verify the Octez Docker image, follow these steps:
                "SignedEntryTimestamp": "<timestamp's signature>",
                "Payload": {
                  "body": "<payload>",
-                 "integratedTime": <time>,
-                 "logIndex": <logIndex>,
+                 "integratedTime": "<time>",
+                 "logIndex": "<logIndex>",
                  "logID": "<logId>"
                }
              }
@@ -93,4 +96,4 @@ To verify the Octez Docker image, follow these steps:
          }
        ]
 
-- If the verification fails, an error message will be displayed indicating the failure reason.
+   If the verification fails, an error message will be displayed indicating the failure reason.
-- 
GitLab