docs: spec updates for arbitrary blob signing

.github/workflows/add-to-project.yml

@@ -24,7 +24,7 @@ jobs:
     name: Add issue to project
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/add-to-project@31b3f3ccdc584546fc445612dec3f38ff5edb41c # v0.5.0
+      - uses: actions/add-to-project@0609a2702eefb44781da00f8e04901d6e5cd2b92 # v0.6.0
         with:
           project-url: https://github.com/orgs/notaryproject/projects/10
           github-token: ${{ secrets.ADD_TO_PROJECT_PAT }}

.github/workflows/build.yml

@@ -31,14 +31,14 @@ jobs:
       fail-fast: true
     steps:
       - name: Set up Go ${{ matrix.go-version }}
-        uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
         with:
           go-version: ${{ matrix.go-version }}
           check-latest: true
       - name: Check out code
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Cache Go modules
-        uses: actions/cache@704facf57e6136b1bc63b828d79edcd491f0ee84 # v3.3.2
+        uses: actions/cache@ab5e6d0c87105b4c9c2047343972218f562e4319 # v4.0.1
         id: go-mod-cache
         with:
           path: ~/go/pkg/mod
@@ -59,4 +59,4 @@ jobs:
             make e2e-covdata
           fi
       - name: Upload coverage to codecov.io
-        uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d # v3.1.4
+        uses: codecov/codecov-action@54bcd8715eee62d40e33596ef5e8f0f48dbbccab # v4.1.0

.github/workflows/codeql.yml

@@ -15,9 +15,13 @@ name: "CodeQL"
 
 on:
   push:
-    branches: main
+    branches: 
+      - main
+      - release-*
   pull_request:
-    branches: main
+    branches: 
+      - main
+      - release-*
   schedule:
     - cron: '38 21 * * 1'
 
@@ -40,13 +44,13 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - name: Set up Go ${{ matrix.go-version }} environment
-        uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
         with:
           go-version: ${{ matrix.go-version }}
           check-latest: true
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@2cb752a87e96af96708ab57187ab6372ee1973ab # v2.22.0
+        uses: github/codeql-action/init@47b3d888fe66b639e431abf22ebca059152f1eea # v3.24.5
         with:
           languages: go
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@2cb752a87e96af96708ab57187ab6372ee1973ab # v2.22.0
+        uses: github/codeql-action/analyze@47b3d888fe66b639e431abf22ebca059152f1eea # v3.24.5

.github/workflows/license-checker.yml

@@ -15,9 +15,13 @@ name: License Checker
 
 on:
   push:
-    branches: main
+    branches: 
+      - main
+      - release-*
   pull_request:
-    branches: main
+    branches: 
+      - main
+      - release-*
 
 permissions:
   contents: read

.github/workflows/release-github.yml

@@ -33,7 +33,7 @@ jobs:
       fail-fast: true
     steps:
       - name: Set up Go ${{ matrix.go-version }}
-        uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4.1.0
+        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
         with:
           go-version: ${{ matrix.go-version }}
           check-latest: true

.github/workflows/scorecard.yml

@@ -18,7 +18,9 @@ on:
     # Weekly on Saturdays.
     - cron: '30 1 * * 6'
   push:
-    branches: [ main ]
+    branches: 
+      - main
+      - release-*
     paths:
     - '!docs/**'
     - '!specs/**'
@@ -44,21 +46,21 @@ jobs:
           persist-credentials: false
 
       - name: "Run analysis"
-        uses: ossf/scorecard-action@483ef80eb98fb506c348f7d62e28055e49fe2398 # tag=v2.3.0
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # tag=v2.3.1
         with:
           results_file: results.sarif
           results_format: sarif
           repo_token: ${{ secrets.SCORECARD_READ_TOKEN }}
           publish_results: true
 
       - name: "Upload artifact"
-        uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # tag=v3.1.3
+        uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # tag=v4.3.1
         with:
           name: SARIF file
           path: results.sarif
           retention-days: 5
 
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@2cb752a87e96af96708ab57187ab6372ee1973ab # v2.22.0
+        uses: github/codeql-action/upload-sarif@47b3d888fe66b639e431abf22ebca059152f1eea # v3.24.5
         with:
           sarif_file: results.sarif

CODEOWNERS

@@ -1,3 +1,3 @@
 # Repo-Level Owners (in alphabetical order)
 # Note: This is only for the notaryproject/notation repo
-* @gokarnm @JeyJeyGao @justincormack @niazfk @priteshbandi @rgnote @shizhMSFT @stevelasker @Two-Hearts
+* @gokarnm @JeyJeyGao @justincormack @niazfk @priteshbandi @rgnote @shizhMSFT @stevelasker @toddysm @Two-Hearts

MAINTAINERS

@@ -2,13 +2,14 @@
 # Pattern: [First Name] [Last Name] <[Email Address]> ([GitHub Handle])
 Justin Cormack <[email protected]> (@justincormack)
 Niaz Khan <[email protected]> (@niazfk)
+Pritesh Bandi <[email protected]> (@priteshbandi)
+Shiwei Zhang <[email protected]> (@shizhMSFT)
 Steve Lasker <[email protected]> (@stevelasker)
+Toddy Mladenov <[email protected]> (@toddysm)
 
 # Repo-Level Maintainers (in alphabetical order)
 # Note: This is for the notaryproject/notation repo
 Junjie Gao <[email protected]> (@JeyJeyGao)
 Milind Gokarn <[email protected]> (@gokarnm)
 Patrick Zheng <[email protected]> (@Two-Hearts)
-Pritesh Bandi <[email protected]> (@priteshbandi)
 Rakesh Gariganti <[email protected]> (@rgnote)
-Shiwei Zhang <[email protected]> (@shizhMSFT)

README.md

@@ -24,10 +24,10 @@ You can find the Notary Project [README](https://github.com/notaryproject/.githu
 
 ## Quick Start
 
-- [Quick start: Sign and validate a container image](https://notaryproject.dev/docs/quickstart-guides/quickstart/)
+- [Quick start: Sign and validate a container image](https://notaryproject.dev/docs/quickstart-guides/quickstart-sign-image-artifact/)
 - [Try out Notation in this Killercoda interactive sandbox environment](https://killercoda.com/notaryproject/scenario/notation)
 - Build, sign, and verify container images using Notation with [Azure Key Vault](https://docs.microsoft.com/azure/container-registry/container-registry-tutorial-sign-build-push?wt.mc_id=azurelearn_inproduct_oss_notaryproject) or [AWS Signer](https://docs.aws.amazon.com/signer/latest/developerguide/container-workflow.html)
- 
+
 ## Community
 
 Notary Project is a [CNCF Incubating project](https://www.cncf.io/projects/notary/). We :heart: your contribution.

cmd/notation/inspect.go

@@ -94,7 +94,7 @@ Example - [Experimental] Inspect signatures on an OCI artifact identified by a d
 		Long:  longMessage,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
-				return errors.New("missing reference")
+				return errors.New("missing reference to the artifact: use `notation inspect --help` to see what parameters are required")
 			}
 			opts.reference = args[0]
 			return nil

cmd/notation/internal/plugin/plugin.go

@@ -0,0 +1,86 @@
+// Copyright The Notary Project 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 plugin
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"github.com/notaryproject/notation/internal/httputil"
+)
+
+// MaxPluginSourceBytes specifies the limit on how many bytes are allowed in the
+// server's response to the download from URL request.
+//
+// The plugin source size must be strictly less than this value.
+var MaxPluginSourceBytes int64 = 256 * 1024 * 1024 // 256 MiB
+
+// PluginSourceType is an enum for plugin source
+type PluginSourceType int
+
+const (
+	// PluginSourceTypeFile means plugin source is file
+	PluginSourceTypeFile PluginSourceType = 1 + iota
+
+	// PluginSourceTypeURL means plugin source is URL
+	PluginSourceTypeURL
+)
+
+const (
+	// MediaTypeZip means plugin file is zip
+	MediaTypeZip = "application/zip"
+
+	// MediaTypeGzip means plugin file is gzip
+	MediaTypeGzip = "application/x-gzip"
+)
+
+// DownloadPluginFromURLTimeout is the timeout when downloading plugin from a
+// URL
+const DownloadPluginFromURLTimeout = 10 * time.Minute
+
+// DownloadPluginFromURL downloads plugin source from url to a tmp file on file
+// system
+func DownloadPluginFromURL(ctx context.Context, pluginURL string, tmpFile io.Writer) error {
+	// Get the data
+	client := httputil.NewAuthClient(ctx, &http.Client{Timeout: DownloadPluginFromURLTimeout})
+	req, err := http.NewRequest(http.MethodGet, pluginURL, nil)
+	if err != nil {
+		return err
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	// Check server response
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("%s %q: https response bad status: %s", resp.Request.Method, resp.Request.URL, resp.Status)
+	}
+	// Write the body to file
+	lr := &io.LimitedReader{
+		R: resp.Body,
+		N: MaxPluginSourceBytes,
+	}
+	_, err = io.Copy(tmpFile, lr)
+	if err != nil {
+		return err
+	}
+	if lr.N == 0 {
+		return fmt.Errorf("%s %q: https response reached the %d MiB size limit", resp.Request.Method, resp.Request.URL, MaxPluginSourceBytes/1024/1024)
+	}
+	return nil
+}

cmd/notation/list.go

@@ -43,14 +43,32 @@ func listCommand(opts *listOpts) *cobra.Command {
 			inputType: inputTypeRegistry, // remote registry by default
 		}
 	}
+	longMessage := `List all the signatures associated with signed artifact
+
+Example - List signatures of an OCI artifact:
+  notation list <registry>/<repository>@<digest>
+
+Example - List signatures of an OCI artifact identified by a tag (Notation will resolve tag to digest)
+  notation list <registry>/<repository>:<tag>
+`
+	experimentalExamples := `
+Example - [Experimental] List signatures of an OCI artifact using the Referrers API. If it's not supported (returns 404), fallback to the Referrers tag schema
+  notation list --allow-referrers-api <registry>/<repository>@<digest>
+
+Example - [Experimental] List signatures of an OCI artifact referenced in an OCI layout
+  notation list --oci-layout "<oci_layout_path>@<digest>"
+
+Example - [Experimental] List signatures of an OCI artifact identified by a tag and referenced in an OCI layout
+  notation list --oci-layout "<oci_layout_path>:<tag>"
+`
 	command := &cobra.Command{
 		Use:     "list [flags] <reference>",
 		Aliases: []string{"ls"},
 		Short:   "List signatures of the signed artifact",
-		Long:    "List all the signatures associated with signed artifact",
+		Long:    longMessage,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
-				return errors.New("no reference specified")
+				return errors.New("missing reference to the artifact: use `notation list --help` to see what parameters are required")
 			}
 			opts.reference = args[0]
 			return nil
@@ -74,6 +92,7 @@ func listCommand(opts *listOpts) *cobra.Command {
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] list signatures stored in OCI image layout")
 	experimental.HideFlags(command, "", []string{"allow-referrers-api", "oci-layout"})
 	command.Flags().IntVar(&opts.maxSignatures, "max-signatures", 100, "maximum number of signatures to evaluate or examine")
+	experimental.HideFlags(command, experimentalExamples, []string{"allow-referrers-api", "oci-layout"})
 	return command
 }
 

cmd/notation/login.go

@@ -25,9 +25,9 @@ import (
 	"github.com/notaryproject/notation-go/log"
 	"github.com/notaryproject/notation/internal/auth"
 	"github.com/notaryproject/notation/internal/cmd"
-	credentials "github.com/oras-project/oras-credentials-go"
 	"github.com/spf13/cobra"
 	"golang.org/x/term"
+	"oras.land/oras-go/v2/registry/remote/credentials"
 )
 
 const urlDocHowToAuthenticate = "https://notaryproject.dev/docs/how-to/registry-authentication/"

cmd/notation/logout.go

@@ -20,8 +20,8 @@ import (
 
 	"github.com/notaryproject/notation/internal/auth"
 	"github.com/notaryproject/notation/internal/cmd"
-	credentials "github.com/oras-project/oras-credentials-go"
 	"github.com/spf13/cobra"
+	"oras.land/oras-go/v2/registry/remote/credentials"
 )
 
 type logoutOpts struct {

cmd/notation/main.go

@@ -16,7 +16,9 @@ package main
 import (
 	"os"
 
+	"github.com/notaryproject/notation-go/dir"
 	"github.com/notaryproject/notation/cmd/notation/cert"
+	"github.com/notaryproject/notation/cmd/notation/plugin"
 	"github.com/notaryproject/notation/cmd/notation/policy"
 	"github.com/spf13/cobra"
 )
@@ -31,6 +33,16 @@ func main() {
 			// to avoid leaking credentials
 			os.Unsetenv(defaultUsernameEnv)
 			os.Unsetenv(defaultPasswordEnv)
+
+			// update Notation config directory
+			if notationConfig := os.Getenv("NOTATION_CONFIG"); notationConfig != "" {
+				dir.UserConfigDir = notationConfig
+			}
+
+			// update Notation Libexec directory (for plugins)
+			if notationLibexec := os.Getenv("NOTATION_LIBEXEC"); notationLibexec != "" {
+				dir.UserLibexecDir = notationLibexec
+			}
 		},
 	}
 	cmd.AddCommand(
@@ -40,7 +52,7 @@ func main() {
 		cert.Cmd(),
 		policy.Cmd(),
 		keyCommand(),
-		pluginCommand(),
+		plugin.Cmd(),
 		loginCommand(nil),
 		logoutCommand(nil),
 		versionCommand(),

cmd/notation/manifest.go

@@ -48,7 +48,10 @@ func resolveReference(ctx context.Context, inputType inputType, reference string
 	case inputTypeRegistry:
 		ref, err := registry.ParseReference(reference)
 		if err != nil {
-			return ocispec.Descriptor{}, "", fmt.Errorf("failed to resolve user input reference: %w", err)
+			return ocispec.Descriptor{}, "", fmt.Errorf("%q: %w. Expecting <registry>/<repository>:<tag> or <registry>/<repository>@<digest>", reference, err)
+		}
+		if ref.Reference == "" {
+			return ocispec.Descriptor{}, "", fmt.Errorf("%q: invalid reference: no tag or digest. Expecting <registry>/<repo>:<tag> or <registry>/<repo>@<digest>", reference)
 		}
 		tagOrDigestRef = ref.Reference
 		resolvedRef = ref.Registry + "/" + ref.Repository
@@ -113,16 +116,16 @@ func parseOCILayoutReference(raw string) (string, string, error) {
 		// find `tag`
 		idx := strings.LastIndex(raw, ":")
 		if idx == -1 || (idx == 1 && len(raw) > 2 && unicode.IsLetter(rune(raw[0])) && raw[2] == '\\') {
-			return "", "", notationerrors.ErrorOCILayoutMissingReference{}
+			return "", "", notationerrors.ErrorOCILayoutMissingReference{Msg: fmt.Sprintf("%q: invalid reference: missing tag or digest. Expecting <file_path>:<tag> or <file_path>@<digest>", raw)}
 		} else {
 			path, ref = raw[:idx], raw[idx+1:]
 		}
 	}
 	if path == "" {
-		return "", "", fmt.Errorf("found empty file path in %q", raw)
+		return "", "", fmt.Errorf("%q: invalid reference: missing oci-layout file path. Expecting <file_path>:<tag> or <file_path>@<digest>", raw)
 	}
 	if ref == "" {
-		return "", "", fmt.Errorf("found empty reference in %q", raw)
+		return "", "", notationerrors.ErrorOCILayoutMissingReference{Msg: fmt.Sprintf("%q: invalid reference: missing tag or digest. Expecting <file_path>:<tag> or <file_path>@<digest>", raw)}
 	}
 	return path, ref, nil
 }