diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index 5b07032..68c36d4 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..a210e0b 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
    • 
 		
  •