From f17cb55486e81d19075ec6fa30285ed94d345bd8 Mon Sep 17 00:00:00 2001 From: Dmitry Savintsev Date: Tue, 18 Feb 2025 17:19:49 +0100 Subject: [PATCH 1/2] expand examples documentation Signed-off-by: Dmitry Savintsev --- Makefile | 2 +- examples/sigstore-go-verification/README.md | 44 ++++++++++++++++++++- 2 files changed, 44 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index ccd4373..58a5412 100644 --- a/Makefile +++ b/Makefile @@ -17,9 +17,9 @@ all: build-examples .PHONY: build-examples build-examples: + go build -C ./examples/oci-image-verification -o oci-image-verification . go build -C ./examples/sigstore-go-signing -o sigstore-go-signing . go build -C ./examples/sigstore-go-verification -o sigstore-go-verification . - go build -C ./examples/oci-image-verification -o oci-image-verification . .PHONY: test test: diff --git a/examples/sigstore-go-verification/README.md b/examples/sigstore-go-verification/README.md index a74455d..8d34682 100644 --- a/examples/sigstore-go-verification/README.md +++ b/examples/sigstore-go-verification/README.md @@ -1,9 +1,51 @@ +# Building examples + +To build example programs, run `make build-examples` in the repo root. +The built executables will be in the `examples/` subdirectory: +```shell +$ make build-examples && ls -tr examples | tail -3 +go build -C ./examples/oci-image-verification -o oci-image-verification . +go build -C ./examples/sigstore-go-signing -o sigstore-go-signing . +go build -C ./examples/sigstore-go-verification -o sigstore-go-verification . + +$ find examples -type f -perm -u+x | sort +examples/oci-image-verification/oci-image-verification +examples/sigstore-go-signing/sigstore-go-signing +examples/sigstore-go-verification/sigstore-go-verification +``` + +# oci-image-verification + +This is a CLI fo verifying signatures on the OCI images. View the help text with `-h` or `--help` for all the options. +(The usage example below is not intended to represent the best practices - add all the restrictions and verification parameters +such as `-expectedIssuer` and `-expectedSAN` applicable to your environment.) +```shell +./oci-image-verification \ + -requireTlog=false -ignore-sct -expectedIssuerRegex='.*' -expectedSANRegex='.*' \ + -trustedrootJSONpath=$HOME/dev/files/trustedroot.json -ociImage docker.company.com:4443/repo/image/name +``` + +# sigstore-go-signing +This is a test CLI for signing sigstore bundles. +```shell +$ ./sigstore-go-signing -h +Usage of ./sigstore-go-signing: + -id-token string + OIDC token to send to Fulcio + -in-toto + Content to sign is in-toto document + -rekor + Including transparency log entry from Rekor + -tsa + Include signed timestamp from timestamp authority +``` + # sigstore-go-verification This is a CLI for verifying Sigstore bundles. View the help text with `-h` or `--help` for all the options. ```shell -$ go run . \ +$ ./sigstore-go-verification \ -artifact-digest 76176ffa33808b54602c7c35de5c6e9a4deb96066dba6533f50ac234f4f1f4c6b3527515dc17c06fbe2860030f410eee69ea20079bd3a2c6f3dcf3b329b10751 \ -artifact-digest-algorithm sha512 \ -expectedIssuer https://token.actions.githubusercontent.com \ From 53ba2c03e8bde05c6b15f1b6dc0c668bd6dc7a02 Mon Sep 17 00:00:00 2001 From: Dmitry Savintsev Date: Thu, 20 Feb 2025 09:27:47 +0100 Subject: [PATCH 2/2] address PR feedback Signed-off-by: Dmitry Savintsev --- examples/sigstore-go-verification/README.md | 44 +++++++++++++++++---- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/examples/sigstore-go-verification/README.md b/examples/sigstore-go-verification/README.md index 8d34682..ced2c86 100644 --- a/examples/sigstore-go-verification/README.md +++ b/examples/sigstore-go-verification/README.md @@ -3,7 +3,7 @@ To build example programs, run `make build-examples` in the repo root. The built executables will be in the `examples/` subdirectory: ```shell -$ make build-examples && ls -tr examples | tail -3 +$ make build-examples go build -C ./examples/oci-image-verification -o oci-image-verification . go build -C ./examples/sigstore-go-signing -o sigstore-go-signing . go build -C ./examples/sigstore-go-verification -o sigstore-go-verification . @@ -16,13 +16,42 @@ examples/sigstore-go-verification/sigstore-go-verification # oci-image-verification -This is a CLI fo verifying signatures on the OCI images. View the help text with `-h` or `--help` for all the options. -(The usage example below is not intended to represent the best practices - add all the restrictions and verification parameters -such as `-expectedIssuer` and `-expectedSAN` applicable to your environment.) +This is a CLI for verifying signatures on the OCI images. View the help text with `-h` or `--help` for all the options. ```shell -./oci-image-verification \ - -requireTlog=false -ignore-sct -expectedIssuerRegex='.*' -expectedSANRegex='.*' \ - -trustedrootJSONpath=$HOME/dev/files/trustedroot.json -ociImage docker.company.com:4443/repo/image/name +$ ./oci-image-verification -h +Usage of ./oci-image-verification: + -artifact string + Path to artifact to verify + -artifact-digest string + Hex-encoded digest of artifact to verify + -artifact-digest-algorithm string + Digest algorithm (default "sha256") + -expectedIssuer string + The expected OIDC issuer for the signing certificate + -expectedIssuerRegex string + The expected OIDC issuer for the signing certificate + -expectedSAN string + The expected identity in the signing certificate's SAN extension + -expectedSANRegex string + The expected identity in the signing certificate's SAN extension + -ignore-sct + Ignore SCT verification - do not check that a certificate contains an embedded SCT, a proof of inclusion in a certificate transparency log + -minBundleVersion string + Minimum acceptable bundle version (e.g. '0.1') + -ociImage string + OCI image to verify + -publicKey string + Path to trusted public key + -requireTimestamp + Require either an RFC3161 signed timestamp or log entry integrated timestamp (default true) + -requireTlog + Require Artifact Transparency log entry (Rekor) (default true) + -trustedrootJSONpath string + Path to trustedroot JSON file (default "examples/trusted-root-public-good.json") + -tufDirectory string + Directory to store TUF metadata (default "tufdata") + -tufRootURL string + URL of TUF root containing trusted root JSON file ``` # sigstore-go-signing @@ -64,4 +93,3 @@ Verification successful! ``` You can also specify a TUF root with something like `-tufRootURL tuf-repo-cdn.sigstore.dev`. -