Add verify-tag command for Git tag signature verification (#659)

This commit adds a new 'verify-tag' command to gitsign that allows
users to verify signatures on Git tags. Previously, gitsign only
supported verification of commit signatures through the 'verify'
command.

The verify-tag command follows the same verification process as the
commit verification, but operates on tag objects instead. It supports
all the same identity verification options as the verify command.

Resolves: #658

Signed-off-by: haya14busa <[email protected]>

Author: haya14busa

docs/cli/gitsign.md

@@ -26,5 +26,6 @@ gitsign [flags]
 * [gitsign initialize](gitsign_initialize.md)	 - Initializes Sigstore root to retrieve trusted certificate and key targets for verification.
 * [gitsign show](gitsign_show.md)	 - Show source predicate information
 * [gitsign verify](gitsign_verify.md)	 - Verify a commit
+* [gitsign verify-tag](gitsign_verify-tag.md)	 - Verify a tag
 * [gitsign version](gitsign_version.md)	 - print Gitsign version
 

docs/cli/gitsign_verify-tag.md

@@ -0,0 +1,37 @@
+## gitsign verify-tag
+
+Verify a tag
+
+### Synopsis
+
+Verify a tag.
+
+verify-tag verifies a tag against a set of certificate claims.
+This should generally be used over git verify-tag, since verify-tag will
+check the identity included in the signature's certificate.
+
+```
+gitsign verify-tag <tag> [flags]
+```
+
+### Options
+
+```
+      --certificate-github-workflow-name string         contains the workflow claim from the GitHub OIDC Identity token that contains the name of the executed workflow.
+      --certificate-github-workflow-ref string          contains the ref claim from the GitHub OIDC Identity token that contains the git ref that the workflow run was based upon.
+      --certificate-github-workflow-repository string   contains the repository claim from the GitHub OIDC Identity token that contains the repository that the workflow run was based upon
+      --certificate-github-workflow-sha string          contains the sha claim from the GitHub OIDC Identity token that contains the commit SHA that the workflow run was based upon.
+      --certificate-github-workflow-trigger string      contains the event_name claim from the GitHub OIDC Identity token that contains the name of the event that triggered the workflow run
+      --certificate-identity string                     The identity expected in a valid Fulcio certificate. Valid values include email address, DNS names, IP addresses, and URIs. Either --certificate-identity or --certificate-identity-regexp must be set for keyless flows.
+      --certificate-identity-regexp string              A regular expression alternative to --certificate-identity. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --certificate-identity or --certificate-identity-regexp must be set for keyless flows.
+      --certificate-oidc-issuer string                  The OIDC issuer expected in a valid Fulcio certificate, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --certificate-oidc-issuer or --certificate-oidc-issuer-regexp must be set for keyless flows.
+      --certificate-oidc-issuer-regexp string           A regular expression alternative to --certificate-oidc-issuer. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --certificate-oidc-issuer or --certificate-oidc-issuer-regexp must be set for keyless flows.
+  -h, --help                                            help for verify-tag
+      --insecure-ignore-sct                             when set, verification will not check that a certificate contains an embedded SCT, a proof of inclusion in a certificate transparency log
+      --sct string                                      path to a detached Signed Certificate Timestamp, formatted as a RFC6962 AddChainResponse struct. If a certificate contains an SCT, verification will check both the detached and embedded SCTs.
+```
+
+### SEE ALSO
+
+* [gitsign](gitsign.md)	 - Keyless Git signing with Sigstore!
+

docs/verification.md

@@ -5,7 +5,7 @@
 ### How we sign
 
 In offline Rekor storage mode Gitsign will store a HashedRekord in Rekor
-corresponding to the commit content.
+corresponding to the commit or tag content.
 
 Unfortunately this is a bit complex to query manually. Roughly this is:
 
@@ -19,19 +19,34 @@ signature) attributes.
 
 ### How we verify
 
+For commits:
 1. Recompute and compare commit content checksum from commit.
 2. Get Rekor LogEntry from signature.
 3. Verify Certificate against commit content checksum (ignoring cert NotAfter time).
 4. (if present) Verify signature against TSA cert.
 5. Verify Rekor LogEntry inclusion (offline).
 
-### What's stored in the commit signature
+For tags:
+1. Recompute and compare tag content checksum from tag.
+2. Get Rekor LogEntry from signature.
+3. Verify Certificate against tag content checksum (ignoring cert NotAfter time).
+4. (if present) Verify signature against TSA cert.
+5. Verify Rekor LogEntry inclusion (offline).
 
+### What's stored in the signature
+
+For commits:
 - Commit content checksum (sha256)
 - Commit signing time (untrusted system time)
 - Protobuf encoded [Rekor TransparencyLogEntry](https://github.com/sigstore/protobuf-specs/blob/91485b44360d343dadd98fb7297a500f05e0b5b1/protos/sigstore_rekor.proto#L91)
 - (optional) TSA signature + cert
 
+For tags:
+- Tag content checksum (sha256)
+- Tag signing time (untrusted system time)
+- Protobuf encoded [Rekor TransparencyLogEntry](https://github.com/sigstore/protobuf-specs/blob/91485b44360d343dadd98fb7297a500f05e0b5b1/protos/sigstore_rekor.proto#L91)
+- (optional) TSA signature + cert
+
 Sample encoded TransparencyLogEntry:
 
 ```
@@ -108,13 +123,18 @@ commit signature.
 
 ### What's stored in Rekor
 
-HashedRekord containing:
-
+For commits, a HashedRekord containing:
 - Commit content checksum
 - Fulcio certificate
   - Public Key
   - [Signer Identity info](https://github.com/sigstore/fulcio/blob/main/docs/oidc.md)
 
+For tags, a HashedRekord containing:
+- Tag content checksum
+- Fulcio certificate
+  - Public Key
+  - [Signer Identity info](https://github.com/sigstore/fulcio/blob/main/docs/oidc.md)
+
 ## Online Verification
 
 Note: Gitsign is in the process of migrating clients to offline verification, but this section
@@ -248,17 +268,28 @@ Note that for Git tags, the annotated tag object SHA is what is used (i.e. the
 output of `git rev-parse <tag>`), **not** the SHA of the underlying tagged
 commit.
 
-### What's stored in the commit signature
+### What's stored in the signature
 
+For commits:
 - Commit content checksum (sha256)
 - Commit signing time (untrusted system time)
 - (optional) TSA signature + cert
 
-### What's stored in Rekor
+For tags:
+- Tag content checksum (sha256)
+- Tag signing time (untrusted system time)
+- (optional) TSA signature + cert
 
-HashedRekord containing:
+### What's stored in Rekor
 
+For commits, a HashedRekord containing:
 - Commit SHA checksum
+- Fulcio certificate
+  - Public Key
+  - [Signer Identity info](https://github.com/sigstore/fulcio/blob/main/docs/oidc.md)
+
+For tags, a HashedRekord containing:
+- Tag SHA checksum
 - Fulcio certificate
   - Public Key
   - [Signer Identity info](https://github.com/sigstore/fulcio/blob/main/docs/oidc.md)

internal/commands/root/root.go

@@ -22,6 +22,7 @@ import (
 	"github.com/sigstore/gitsign/internal/commands/initialize"
 	"github.com/sigstore/gitsign/internal/commands/show"
 	"github.com/sigstore/gitsign/internal/commands/verify"
+	verifytag "github.com/sigstore/gitsign/internal/commands/verify-tag"
 	"github.com/sigstore/gitsign/internal/commands/version"
 	"github.com/sigstore/gitsign/internal/config"
 	"github.com/sigstore/gitsign/internal/io"
@@ -92,6 +93,7 @@ func New(cfg *config.Config) *cobra.Command {
 	rootCmd.AddCommand(show.New(cfg))
 	rootCmd.AddCommand(attest.New(cfg))
 	rootCmd.AddCommand(verify.New(cfg))
+	rootCmd.AddCommand(verifytag.New(cfg))
 	rootCmd.AddCommand(initialize.New())
 	o.AddFlags(rootCmd)
 

internal/commands/verify-tag/verify_tag.go

@@ -0,0 +1,144 @@
+// Copyright 2023 The Sigstore Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package verifytag
+
+import (
+	"context"
+	"encoding/pem"
+	"fmt"
+	"io"
+	"os"
+
+	gogit "github.com/go-git/go-git/v5"
+	"github.com/go-git/go-git/v5/plumbing"
+	cosignopts "github.com/sigstore/cosign/v2/cmd/cosign/cli/options"
+	"github.com/sigstore/gitsign/internal/commands/verify"
+	"github.com/sigstore/gitsign/internal/config"
+	"github.com/sigstore/gitsign/internal/gitsign"
+	"github.com/spf13/cobra"
+)
+
+type options struct {
+	Config *config.Config
+	cosignopts.CertVerifyOptions
+}
+
+func (o *options) AddFlags(cmd *cobra.Command) {
+	o.CertVerifyOptions.AddFlags(cmd)
+}
+
+func (o *options) Run(_ io.Writer, args []string) error {
+	ctx := context.Background()
+	repo, err := gogit.PlainOpenWithOptions(".", &gogit.PlainOpenOptions{
+		DetectDotGit: true,
+	})
+	if err != nil {
+		return err
+	}
+
+	if len(args) == 0 {
+		return fmt.Errorf("tag reference is required")
+	}
+	tagRef := args[0]
+
+	// Resolve the tag reference
+	ref, err := repo.Reference(plumbing.ReferenceName(fmt.Sprintf("refs/tags/%s", tagRef)), true)
+	if err != nil {
+		return fmt.Errorf("error resolving tag reference: %w", err)
+	}
+
+	// Get the tag object
+	tagObj, err := repo.TagObject(ref.Hash())
+	if err != nil {
+		return fmt.Errorf("error reading tag object: %w", err)
+	}
+
+	// Extract the signature
+	sig := []byte(tagObj.PGPSignature)
+	p, _ := pem.Decode(sig)
+	if p == nil || p.Type != "SIGNED MESSAGE" {
+		return fmt.Errorf("unsupported signature type")
+	}
+
+	// Get the tag data without the signature
+	tagData := new(plumbing.MemoryObject)
+	if err := tagObj.EncodeWithoutSignature(tagData); err != nil {
+		return err
+	}
+	r, err := tagData.Reader()
+	if err != nil {
+		return err
+	}
+	defer r.Close()
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return err
+	}
+
+	// Verify the signature
+	v, err := gitsign.NewVerifierWithCosignOpts(ctx, o.Config, &o.CertVerifyOptions)
+	if err != nil {
+		return err
+	}
+	summary, err := v.Verify(ctx, data, sig, true)
+	if err != nil {
+		return err
+	}
+
+	// Import the internal package just for the PrintSummary function
+	verify.PrintSummary(os.Stdout, summary)
+
+	return nil
+}
+
+func New(cfg *config.Config) *cobra.Command {
+	o := &options{Config: cfg}
+
+	cmd := &cobra.Command{
+		Use:          "verify-tag <tag>",
+		Args:         cobra.ExactArgs(1),
+		SilenceUsage: true,
+		Short:        "Verify a tag",
+		Long: `Verify a tag.
+
+verify-tag verifies a tag against a set of certificate claims.
+This should generally be used over git verify-tag, since verify-tag will
+check the identity included in the signature's certificate.`,
+		RunE: func(_ *cobra.Command, args []string) error {
+			// Simulate unknown flag errors.
+			if o.Cert != "" {
+				return fmt.Errorf("unknown flag: --certificate")
+			}
+			if o.CertChain != "" {
+				return fmt.Errorf("unknown flag: --certificate-chain")
+			}
+
+			return o.Run(os.Stdout, args)
+		},
+	}
+	o.AddFlags(cmd)
+
+	// Hide flags we don't implement.
+	// --certificate: The cert should always come from the tag.
+	_ = cmd.Flags().MarkHidden("certificate")
+	// --certificate-chain: We only support reading from a TUF root at the moment.
+	// TODO: add support for this.
+	_ = cmd.Flags().MarkHidden("certificate-chain")
+	// --ca-intermediates and --ca-roots
+	_ = cmd.Flags().MarkHidden("ca-intermediates")
+	_ = cmd.Flags().MarkHidden("ca-roots")
+
+	return cmd
+}