From 1d4f2e8d625a28b81109fde870794e5c35ceb6b6 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Tue, 5 Nov 2024 20:08:03 -0800 Subject: [PATCH 1/4] initial Go commit. Signed-off-by: hayleycd --- content/en/language_clients/go/_index.html | 11 +++++ content/en/language_clients/go/overview.md | 49 +++++++++++++++++++ .../language_client_overview.md | 2 +- 3 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 content/en/language_clients/go/_index.html create mode 100644 content/en/language_clients/go/overview.md diff --git a/content/en/language_clients/go/_index.html b/content/en/language_clients/go/_index.html new file mode 100644 index 00000000..f4ec0010 --- /dev/null +++ b/content/en/language_clients/go/_index.html @@ -0,0 +1,11 @@ +--- +type: docs +title: "Go" +description: "Go Language Client" +lead: "Go Language Client" +date: 2024-10-06T08:49:15+00:00 +lastmod: 2024-10-06T08:49:15+00:00 +draft: false +images: [] +weight: 60 +--- \ No newline at end of file diff --git a/content/en/language_clients/go/overview.md b/content/en/language_clients/go/overview.md new file mode 100644 index 00000000..fec3211f --- /dev/null +++ b/content/en/language_clients/go/overview.md @@ -0,0 +1,49 @@ +--- +type: docs +category: Go +title: Go Client Overview +weight: 5 +--- + +[`sigstore-go`](https://pkg.go.dev/github.com/sigstore/sigstore-go) is the Go language client for Sigstore. + +[Cosign](../../cosign/signing/overview.md) is a command line utility that is used to sign software artifacts and verify signatures using Sigstore and is also written in Go. `sigstore-go` is a lighter weight tool and boasts the following benefits: + +- Friendly API for integrating Go code with Sigstore +- Smaller dependency tree +- Focuses on newly specified data structures in [sigstore/protobuf-specs](https://github.com/sigstore/protobuf-specs) +- Perfect for simple signing and verififcation tasks + +`sigstore-go` is currently in beta. + +## Features + +- Signing and verification of [Sigstore bundles](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) +- Verification of raw Sigstore signatures +- Signing and verifying with a Timestamp Authority (TSA) +- Online and offline signing and verifying 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 + +## Installation + +### Main CLI installation + +`sigstore-go` requires Go 1.21 or greater. The package is tested with Go 1.23. + +To compile/install the CLI, clone [`sigstore-go`](https://github.com/sigstore/sigstore-go) and run. + +```console +make install +``` +Alternatively, you can use `go run cmd/sigstore-go/main.go` to access the CLI. + +### + +## Example + +### Signing example + +### Verifying example diff --git a/content/en/language_clients/language_client_overview.md b/content/en/language_clients/language_client_overview.md index a974704f..688ee24f 100644 --- a/content/en/language_clients/language_client_overview.md +++ b/content/en/language_clients/language_client_overview.md @@ -14,6 +14,6 @@ Sigstore has clients for the following language ecosystems: - [Ruby](https://github.com/sigstore/sigstore-ruby#sigstore) - [JavaScript](https://github.com/sigstore/sigstore-js#sigstore-js---) - [Java](https://github.com/sigstore/sigstore-java#sigstore-java) -- [Go](https://github.com/sigstore/sigstore-go#sigstore-go) +- [Go](../go/overview) Language client documentation is hosted in the individual project repositories. Project summaries are currently being added to the main Sigstore documentation. From c8ad2681ccb9ced8d2fd85ee152d57b920080a21 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Tue, 5 Nov 2024 21:04:07 -0800 Subject: [PATCH 2/4] Initial Go entry Signed-off-by: hayleycd --- content/en/language_clients/go/overview.md | 34 ++++++++++++++++++---- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/content/en/language_clients/go/overview.md b/content/en/language_clients/go/overview.md index fec3211f..3bea0bae 100644 --- a/content/en/language_clients/go/overview.md +++ b/content/en/language_clients/go/overview.md @@ -38,12 +38,36 @@ To compile/install the CLI, clone [`sigstore-go`](https://github.com/sigstore/si ```console make install ``` -Alternatively, you can use `go run cmd/sigstore-go/main.go` to access the CLI. - -### +Alternatively, you can use `go run cmd/sigstore-go/main.go` to access the CLI, as show in the [example](#cli-example). ## Example -### Signing example +### CLI example + +The following is an example of using the sigstore-go CLI to verify a signature. + +```console +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": ... + }, + ... +} +``` +### Additional examples + +Additional examples are available in the [project documentation](https://github.com/sigstore/sigstore-go#sigstore-go). -### Verifying example +- [Signing example](https://github.com/sigstore/sigstore-go/blob/main/docs/signing.md#examples) +- [Verifying example](https://github.com/sigstore/sigstore-go/blob/main/docs/verification.md#verification-using-sigstore-go) +- [OCI image verifying example](https://github.com/sigstore/sigstore-go/blob/main/docs/oci-image-verification.md#example-of-oci-image-verification-using-sigstore-go) From 40a526677b281d9be5bad1d3a7043bd365d5c128 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Thu, 7 Nov 2024 18:19:31 -0800 Subject: [PATCH 3/4] Clarified cosign vs sigstore-go. Signed-off-by: hayleycd --- content/en/language_clients/go/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/language_clients/go/overview.md b/content/en/language_clients/go/overview.md index 3bea0bae..c2abd694 100644 --- a/content/en/language_clients/go/overview.md +++ b/content/en/language_clients/go/overview.md @@ -5,9 +5,9 @@ title: Go Client Overview weight: 5 --- -[`sigstore-go`](https://pkg.go.dev/github.com/sigstore/sigstore-go) is the Go language client for Sigstore. +[`sigstore-go`](https://pkg.go.dev/github.com/sigstore/sigstore-go) is the Go language client library for Sigstore. -[Cosign](../../cosign/signing/overview.md) is a command line utility that is used to sign software artifacts and verify signatures using Sigstore and is also written in Go. `sigstore-go` is a lighter weight tool and boasts the following benefits: +`sigstore-go` is intended as a minimal dependency library for signing and verifying. It's not intended to replace [cosign](../../cosign/signing/overview.md), which provides a CLI with many features for interacting with Sigstore. Over time, `cosign` will use `sigstore-go` for verification. - Friendly API for integrating Go code with Sigstore - Smaller dependency tree From 314119b346adf8c2acdf7b1ed59bd9bd4b5cec68 Mon Sep 17 00:00:00 2001 From: hayleycd Date: Thu, 7 Nov 2024 18:27:20 -0800 Subject: [PATCH 4/4] Addressing linter comments. Signed-off-by: hayleycd --- content/en/language_clients/go/overview.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/content/en/language_clients/go/overview.md b/content/en/language_clients/go/overview.md index c2abd694..b5912cdd 100644 --- a/content/en/language_clients/go/overview.md +++ b/content/en/language_clients/go/overview.md @@ -14,7 +14,7 @@ weight: 5 - Focuses on newly specified data structures in [sigstore/protobuf-specs](https://github.com/sigstore/protobuf-specs) - Perfect for simple signing and verififcation tasks -`sigstore-go` is currently in beta. +`sigstore-go` is currently in beta. ## Features @@ -31,20 +31,21 @@ weight: 5 ### Main CLI installation -`sigstore-go` requires Go 1.21 or greater. The package is tested with Go 1.23. +`sigstore-go` requires Go 1.21 or greater. The package is tested with Go 1.23. -To compile/install the CLI, clone [`sigstore-go`](https://github.com/sigstore/sigstore-go) and run. +To compile/install the CLI, clone [`sigstore-go`](https://github.com/sigstore/sigstore-go) and run. ```console make install ``` -Alternatively, you can use `go run cmd/sigstore-go/main.go` to access the CLI, as show in the [example](#cli-example). + +Alternatively, you can use `go run cmd/sigstore-go/main.go` to access the CLI, as show in the [example](#cli-example). ## Example ### CLI example -The following is an example of using the sigstore-go CLI to verify a signature. +The following is an example of using the sigstore-go CLI to verify a signature. ```console go run cmd/sigstore-go/main.go \ @@ -64,9 +65,10 @@ Verification successful! ... } ``` + ### Additional examples -Additional examples are available in the [project documentation](https://github.com/sigstore/sigstore-go#sigstore-go). +Additional examples are available in the [project documentation](https://github.com/sigstore/sigstore-go#sigstore-go). - [Signing example](https://github.com/sigstore/sigstore-go/blob/main/docs/signing.md#examples) - [Verifying example](https://github.com/sigstore/sigstore-go/blob/main/docs/verification.md#verification-using-sigstore-go)