From 5a655632005ca867f63da021435fef3b5789cdfa Mon Sep 17 00:00:00 2001 From: Mohammed Al Sahaf Date: Sun, 30 Jul 2023 23:06:09 +0300 Subject: [PATCH 1/2] signature-verification: accommodate changes in cosign cli behavior and add tldr Closes TL;DR needed for Signature Verification page #312 --- src/docs/markdown/install.md | 2 +- src/docs/markdown/signature-verification.md | 41 +++++++++++++++++++-- src/includes/docs/nav.html | 2 +- 3 files changed, 39 insertions(+), 6 deletions(-) diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index 7098d4d..a8db1fa 100644 --- a/src/docs/markdown/install.md +++ b/src/docs/markdown/install.md @@ -38,7 +38,7 @@ Our [official packages](https://github.com/caddyserver/dist) come only with the 1. Obtain a Caddy binary: - [from releases on GitHub](https://github.com/caddyserver/caddy/releases) (expand "Assets") - - Refer to [Verifying Asset Signatures](/docs/signature-verification) for how to verify the asset signature + - Refer to [Asset Signature Verification](/docs/signature-verification) for how to verify the asset signature - [from our download page](/download) - [by building from source](/docs/build) (either with `go` or `xcaddy`) 2. [Install Caddy as a system service.](/docs/running#manual-installation) This is strongly recommended, especially for production servers. diff --git a/src/docs/markdown/signature-verification.md b/src/docs/markdown/signature-verification.md index 5ff552e..f075be7 100644 --- a/src/docs/markdown/signature-verification.md +++ b/src/docs/markdown/signature-verification.md @@ -1,13 +1,39 @@ --- -title: Verifying Asset Signatures +title: Asset Signature Verification --- -# Signature Verification +# Asset Signature Verification Artifact signing allows you to validate the artifact you have is the same one created by the project's workflow and was not modified by an unauthorized party (e.g. man-in-the-middle). The validation provides common ground, assurance, and knowledge that all parties are refering to the same artifact, collection of bytes, whether it is an executable, SBOM, or text file. As of Caddy v2.6.0, CI/CD release artifacts are signed using project [Sigstore](https://www.sigstore.dev/) technology, which issues certificates containing details about the subject to whom the certificate is issued. You can start by inspecting the certificate used to sign your artifact of choice. The certificates are base64-encoded, so you first have to base64-decode it to receive the PEM file. In this example, we'll work with the `caddy_2.6.0_checksums.txt` artifact and assume a Linux-like environment. + + Start by downloading the the 3 files pertaining to your artifact of choice (i.e. `` which is the actual artifact whose companion signature and certs are to be verified, `.sig` which is the signature of the artifact, and `.pem` is the certificate descending from the root cert by Fulcio by Sigstore). Then base64 decode the downloaded `.pem` file to the armored version: 
base64 -d < caddy_2.6.0_checksums.txt.pem > cert.pem
@@ -103,8 +129,15 @@ Notice the stated intended usage of the certificate, which is `Code Signing`. Th Now that we have the certificate, we can use `cosign` cli to validate the signature. We run the following command (notice it uses the undecoded cert): -
COSIGN_EXPERIMENTAL=1 cosign verify-blob --certificate ./caddy_2.6.0_checksums.txt.pem --signature ./caddy_2.6.0_checksums.txt.sig ./caddy_2.6.0_checksums.txt
-tlog entry verified with uuid: 04deb84e5a73ba75ea69092c6d700eaeb869c29cae3e0cf98dbfef871361ed09 index: 3618623
+
cosign verify-blob \
+--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+--certificate-github-workflow-name "Release" \
+--certificate-github-workflow-ref refs/tags/v2.6.0 \
+--certificate-identity-regexp caddyserver/caddy \
+--certificate ./caddy_2.6.0_checksums.txt.pem \
+--signature ./caddy_2.6.0_checksums.txt.sig \
+--verbose \
+./caddy_2.6.0_checksums.txt
 Verified OK
 

 
diff --git a/src/includes/docs/nav.html b/src/includes/docs/nav.html
index 18c5344..025bdf6 100644
--- a/src/includes/docs/nav.html
+++ b/src/includes/docs/nav.html
@@ -47,7 +47,7 @@
 		
  • Monitoring Caddy
    • 
 		
  • Caddy Architecture
    • 
 		
  • Keep Caddy Running
    • 
-		
  • Verifying Asset Signatures
    • 
+		
  • Asset Signature Verification
    • 
 
 		
  • Developers
    • 
 		
  • 

From b76ac71ce5b5c6ebd3c8208066d08ddb86eb8923 Mon Sep 17 00:00:00 2001
From: Mohammed Al Sahaf 
Date: Tue, 1 Aug 2023 08:38:10 +0200
Subject: [PATCH 2/2] Update src/docs/markdown/signature-verification.md

Co-authored-by: Matt Holt 
---
 src/docs/markdown/signature-verification.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/docs/markdown/signature-verification.md b/src/docs/markdown/signature-verification.md
index f075be7..a210e0b 100644
--- a/src/docs/markdown/signature-verification.md
+++ b/src/docs/markdown/signature-verification.md
@@ -10,7 +10,7 @@ As of Caddy v2.6.0, CI/CD release artifacts are signed using project [Sigstore](