From cfd91c5469a0d1df7066dd91ae811a751a4801f8 Mon Sep 17 00:00:00 2001
From: Pietro Abate <pietro.abate@nomadic-labs.com>
Date: Mon, 29 Jul 2024 15:03:52 +0200
Subject: [PATCH] docs: add cosign verify documentation

---
 docs/introduction/cosign-verify.rst | 52 +++++++++++++++++++++++++++++
 docs/introduction/howtoget.rst      |  8 +++++
 2 files changed, 60 insertions(+)
 create mode 100644 docs/introduction/cosign-verify.rst

diff --git a/docs/introduction/cosign-verify.rst b/docs/introduction/cosign-verify.rst
new file mode 100644
index 000000000000..ef13d168c2f8
--- /dev/null
+++ b/docs/introduction/cosign-verify.rst
@@ -0,0 +1,52 @@
+Verifying Octez Docker Images with Cosign
+==========================================
+
+`Cosign <https://github.com/sigstore/cosign>`_ is a tool developed by `Sigstore
+<https://sigstore.dev/>`_ to sign and verify container images and other
+artifacts. This document provides instructions on how to verify Docker images of Octez
+signed using Cosign.
+
+Prerequisites
+-------------
+Before you can verify Docker images signed with Cosign, ensure you have
+Docker and Cosign installed on your system.
+
+- `Docker Installation Guide <https://docs.docker.com/get-docker/>`_
+- `Cosign Installation Guide <https://docs.sigstore.dev/cosign/installation/>`_
+
+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
+
+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
+
+Verifying the Docker Image
+--------------------------
+To verify the Octez Docker image, follow these steps:
+
+1. **Pull the Docker Image** (if not already pulled):
+
+   .. code-block:: bash
+
+       docker pull tezos/tezos-bare:master
+
+2. **Use Cosign to Verify the Image**:
+
+   .. code-block:: bash
+
+       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`` )
+
+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.
diff --git a/docs/introduction/howtoget.rst b/docs/introduction/howtoget.rst
index ef4452d42a64..1a79b2227190 100644
--- a/docs/introduction/howtoget.rst
+++ b/docs/introduction/howtoget.rst
@@ -180,6 +180,14 @@ 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.
+You can verify if the images are correctly signed using the Cosign utility, as explained below:
+
+.. toctree::
+   :maxdepth: 2
+
+   cosign-verify
+
 One way to run those Docker images is with `docker-compose <https://docs.docker.com/compose>`_.
 We provide ``docker-compose`` files for all active
 protocols. You can pick one and start with the following command (we'll assume alpha on this guide):
-- 
GitLab