From b831888318227737b680fe0553e697a284ace85c Mon Sep 17 00:00:00 2001
From: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com>
Date: Wed, 24 May 2023 08:46:05 -0400
Subject: [PATCH] [Docs] Add instructions to verify Docker install images
 (#15058)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add instructions to verify Docker install images

* remove line breaks

* Update docs/static/docker.asciidoc

Co-authored-by: Maxime Gréau <maxime.greau@elastic.co>

---------

Co-authored-by: Maxime Gréau <maxime.greau@elastic.co>
---
 docs/static/docker.asciidoc | 39 +++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/static/docker.asciidoc b/docs/static/docker.asciidoc
index 6e33a9f665e..0c636d008b1 100644
--- a/docs/static/docker.asciidoc
+++ b/docs/static/docker.asciidoc
@@ -39,6 +39,45 @@ https://www.docker.elastic.co[www.docker.elastic.co].
 
 endif::[]
 
+==== Verifying the image
+
+Although it's optional, we highly recommend verifying the signatures included with your downloaded Docker images to ensure that the images are valid.
+
+Elastic images are signed with https://docs.sigstore.dev/cosign/overview/[Cosign] which is part of the https://www.sigstore.dev/[Sigstore] project. Cosign supports container signing, verification, and storage in an OCI registry. Install the appropriate https://docs.sigstore.dev/cosign/installation/[Cosign application]
+for your operating system.
+
+Run the following commands to verify the container image signature for {ls} v{version}:
+
+ifeval::["{release-state}"=="unreleased"]
+
+Version {logstash_version} of Logstash has not yet been
+released, so no Docker image is currently available for this version.
+
+endif::[]
+
+ifeval::["{release-state}"!="unreleased"]
+
+["source","sh",subs="attributes"]
+--------------------------------------------
+wget https://artifacts.elastic.co/cosign.pub <1>
+cosign verify --key cosign.pub {docker-image} <2>
+--------------------------------------------
+<1> Download the Elastic public key to verify container signature
+<2> Verify the container against the Elastic public key
+
+The command prints the check results and the signature payload in JSON format, for example:
+
+["source","sh",subs="attributes"]
+--------------------------------------------
+Verification for {docker-image} --
+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
+--------------------------------------------
+
+endif::[]
+
 [[docker-config]]
 === Configuring Logstash for Docker