diff --git a/.github/workflows/conformance.yml b/.github/workflows/conformance.yml index 5077fd01..c7ea238a 100644 --- a/.github/workflows/conformance.yml +++ b/.github/workflows/conformance.yml @@ -40,7 +40,7 @@ jobs: - run: go mod download - - run: go build -o conformance cmd/conformance/main.go + - run: go build -o conformance test/conformance/main.go - uses: sigstore/sigstore-conformance@d658ea74a060aeabae78f8a379167f219dc38c38 # v0.0.16 with: diff --git a/Makefile b/Makefile index 043033be..ccd4373e 100644 --- a/Makefile +++ b/Makefile @@ -13,26 +13,18 @@ # limitations under the License. .PHONY: all -all: build build-examples - -.PHONY: build -build: - go build ./cmd/sigstore-go - go build -o conformance ./cmd/conformance +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: go test ./... -.PHONY: install -install: - go install ./cmd/... - .PHONY: tidy tidy: go mod tidy diff --git a/README.md b/README.md index 09cbdafc..c66eb18e 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,16 @@ A client library for [Sigstore](https://www.sigstore.dev/), written in Go. Features: - Signing and verification of [Sigstore bundles](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) compliant with Sigstore Client Spec -- Verification of raw Sigstore signatures by creating bundles for them (see [conformance tests](cmd/conformance/main.go) for example) +- Verification of raw Sigstore signatures by creating bundles for them (see [conformance tests](test/conformance/main.go) for example) - Signing and verifying with a Timestamp Authority (TSA) - Signing and verifying (offline or online) with Rekor (Artifact Transparency Log) - Structured verification results including certificate metadata - TUF support - Verification support for custom [trusted root](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_trustroot.proto) -- Basic CLI and examples +- Examples for signing and verifying artifacts There is not built-in support for signing with a KMS or other bring-your-own-key; however you can easily add support by implementing your own version of the interface `pkg/sign/keys.go:Keypair`. -For an example of how to use this library, see [the verification documentation](./docs/verification.md), the CLI [cmd/sigstore-go](./cmd/sigstore-go/main.go), or the CLI examples below. Note that the CLI is to demonstrate how to use the library, and not intended as a fully-featured Sigstore CLI like [cosign](https://github.com/sigstore/cosign). - ## Background Sigstore already has a canonical Go client implementation, [cosign](https://github.com/sigstore/cosign), which was developed with a focus on container image signing/verification. It has a rich CLI and a long legacy of features and development. `sigstore-go` is a more minimal and friendly API for integrating Go code with Sigstore, with a focus on the newly specified data structures in [sigstore/protobuf-specs](https://github.com/sigstore/protobuf-specs). `sigstore-go` attempts to minimize the dependency tree for simple signing and verification tasks, omitting KMS support and container image verification, and we intend to refactor parts of `cosign` to depend on `sigstore-go`. @@ -28,9 +26,13 @@ Sigstore already has a canonical Go client implementation, [cosign](https://gith `sigstore-go` is currently beta, and may have minor API changes before the 1.0.0 release. It does however pass the [`sigstore-conformance`](https://github.com/sigstore/sigstore-conformance) signing and verification test suite, and correctness is taken very seriously. -## Documentation +## Documentation and examples + +Documentation is found in the [`docs`](./docs) subdirectory and on [pkg.go.dev](https://pkg.go.dev/github.com/sigstore/sigstore-go). -Documentation is found in the [`docs`](./docs) subdirectory. +See the [examples directory](./examples/README.md) for examples of how to use this library. + +Note that the CLI examples are to demonstrate how to use the library, and not intended as a fully-featured Sigstore CLI like [cosign](https://github.com/sigstore/cosign). ## Requirements @@ -41,43 +43,6 @@ Tested with: Note that we do not provide built versions of this library, but you can see what architectures your version of `go` supports with `go tool dist list`. -## Installation - -You can use the CLI with `go run` as in the below examples, or compile/install the `sigstore-go` CLI: - -```shell -$ make install -``` -## Examples - -```shell -$ go run cmd/sigstore-go/main.go \ - -artifact-digest 76176ffa33808b54602c7c35de5c6e9a4deb96066dba6533f50ac234f4f1f4c6b3527515dc17c06fbe2860030f410eee69ea20079bd3a2c6f3dcf3b329b10751 \ - -artifact-digest-algorithm sha512 \ - -expectedIssuer https://token.actions.githubusercontent.com \ - -expectedSAN https://github.com/sigstore/sigstore-js/.github/workflows/release.yml@refs/heads/main \ - examples/bundle-provenance.json -Verification successful! -{ - "version": 20230823, - "statement": { - "_type": "https://in-toto.io/Statement/v0.1", - "predicateType": "https://slsa.dev/provenance/v0.2", - "subject": ... - }, - ... -} -``` - -You can also specify a TUF root with something like `-tufRootURL tuf-repo-cdn.sigstore.dev`. - -Alternatively, you can install a binary of the CLI like so: - -```shell -$ go install ./cmd/sigstore-go -$ sigstore-go ... -``` - ## Testing Tests are invoked using the standard Go testing framework. A helper exists in the Makefile also. diff --git a/docs/oci-image-verification.md b/docs/oci-image-verification.md index 47a099f1..f3a70368 100644 --- a/docs/oci-image-verification.md +++ b/docs/oci-image-verification.md @@ -136,4 +136,4 @@ and the verification result: } ``` -To explore a more advanced/configurable verification process, see the CLI implementation in [`cmd/sigstore-go/main.go`](../cmd/sigstore-go/main.go). +To explore a more advanced/configurable verification process, see the CLI implementation in [`examples/sigstore-go-verification/main.go`](../examples/sigstore-go-verification/main.go). diff --git a/docs/signing.md b/docs/signing.md index 110dfe6c..5b322975 100644 --- a/docs/signing.md +++ b/docs/signing.md @@ -12,7 +12,6 @@ This document will walk you through using `sigstore-go` to generate a Sigstore b Clone this repository and run the following command: ```shell -$ make build-examples $ go install ./examples/sigstore-go-signing ``` diff --git a/docs/verification.md b/docs/verification.md index 3858db8b..31a7d7cf 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -9,11 +9,10 @@ This document will walk through using `sigstore-go` to verify a Sigstore Bundle. ## Installation -Clone this repository and use `make install` to install the `sigstore-go` CLI: +Clone this repository and use the `go` tool to install the `sigstore-go` CLI: ```shell -$ make install -go install ./cmd/... +go install ./examples/sigstore-go-verification ``` ## Bundle @@ -335,4 +334,4 @@ func main() { } ``` -To explore a more advanced/configurable verification process, see the CLI implementation in [`cmd/sigstore-go/main.go`](../cmd/sigstore-go/main.go). +To explore a more advanced/configurable verification process, see the CLI implementation in [`examples/sigstore-go-verification/main.go`](../examples/sigstore-go-verification/main.go). diff --git a/cmd/sigstore-go/main.go b/examples/sigstore-go-verification/main.go similarity index 100% rename from cmd/sigstore-go/main.go rename to examples/sigstore-go-verification/main.go diff --git a/cmd/conformance/main.go b/test/conformance/main.go similarity index 100% rename from cmd/conformance/main.go rename to test/conformance/main.go