update: changed Sign to use OCI image manifest as default (notaryproj…

…ect#573)

cmd/notation/registry.go

@@ -204,7 +204,7 @@ func pingReferrersAPI(ctx context.Context, remoteRepo *remote.Repository) error
 		// A 404 returned by Referrers API indicates that Referrers API is
 		// not supported.
 		logger.Infof("failed to ping Referrers API with error: %v", err)
-		errMsg := "Target registry does not support the Referrers API. Try the flag `--signature-manifest image` to store signatures using OCI image manifest for backwards compatibility"
+		errMsg := "Target registry does not support the Referrers API. Try removing the flag `--signature-manifest artifact` to store signatures using OCI image manifest"
 		return notationerrors.ErrorReferrersAPINotSupported{Msg: errMsg}
 	}
 	return nil

cmd/notation/sign.go

@@ -46,7 +46,7 @@ func signCommand(opts *signOpts) *cobra.Command {
 
 Prerequisite: a signing key needs to be configured using the command "notation key".
 
-Example - Sign an OCI artifact using the default signing key, with the default JWS envelope:
+Example - Sign an OCI artifact using the default signing key, with the default JWS envelope, and use OCI image manifest to store the signature:
   notation sign <registry>/<repository>@<digest>
 
 Example - Sign an OCI artifact using the default signing key, with the COSE envelope:
@@ -61,8 +61,8 @@ Example - Sign an OCI artifact identified by a tag (Notation will resolve tag to
 Example - Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours
   notation sign --expiry 24h <registry>/<repository>@<digest>
 
-Example - Sign an OCI artifact and use OCI image manifest to store the signature, with the default JWS envelope:
-  notation sign --signature-manifest image <registry>/<repository>@<digest>
+Example - Sign an OCI artifact and use OCI artifact manifest to store the signature:
+  notation sign --signature-manifest artifact <registry>/<repository>@<digest>
 `,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
@@ -84,7 +84,7 @@ Example - Sign an OCI artifact and use OCI image manifest to store the signature
 	opts.SecureFlagOpts.ApplyFlags(command.Flags())
 	cmd.SetPflagExpiry(command.Flags(), &opts.expiry)
 	cmd.SetPflagPluginConfig(command.Flags(), &opts.pluginConfig)
-	command.Flags().StringVar(&opts.signatureManifest, "signature-manifest", signatureManifestArtifact, "manifest type for signature. options: \"artifact\", \"image\"")
+	command.Flags().StringVar(&opts.signatureManifest, "signature-manifest", signatureManifestImage, "manifest type for signature. options: \"image\", \"artifact\"")
 	cmd.SetPflagUserMetadata(command.Flags(), &opts.userMetadata, cmd.PflagUserMetadataSignUsage)
 	return command
 }
@@ -112,8 +112,8 @@ func runSign(command *cobra.Command, cmdOpts *signOpts) error {
 	_, err = notation.Sign(ctx, signer, sigRepo, opts)
 	if err != nil {
 		var errorPushSignatureFailed notation.ErrorPushSignatureFailed
-		if errors.As(err, &errorPushSignatureFailed) {
-			return fmt.Errorf("%v. Target registry does not seem to support OCI artifact manifest. Try the flag `--signature-manifest image` to store signatures using OCI image manifest for backwards compatibility", err)
+		if errors.As(err, &errorPushSignatureFailed) && !ociImageManifest {
+			return fmt.Errorf("%v. Possible reason: target registry does not support OCI artifact manifest. Try removing the flag `--signature-manifest artifact` to store signatures using OCI image manifest", err)
 		}
 		return err
 	}

cmd/notation/sign_test.go

@@ -23,7 +23,7 @@ func TestSignCommand_BasicArgs(t *testing.T) {
 			Key:             "key",
 			SignatureFormat: envelope.JWS,
 		},
-		signatureManifest: "artifact",
+		signatureManifest: "image",
 	}
 	if err := command.ParseFlags([]string{
 		expected.reference,
@@ -87,7 +87,7 @@ func TestSignCommand_CorrectConfig(t *testing.T) {
 		},
 		expiry:            365 * 24 * time.Hour,
 		pluginConfig:      []string{"key0=val0", "key1=val1"},
-		signatureManifest: "artifact",
+		signatureManifest: "image",
 	}
 	if err := command.ParseFlags([]string{
 		expected.reference,

specs/commandline/sign.md

@@ -36,25 +36,23 @@ Flags:
        --plain-http                 registry access via plain HTTP
        --plugin-config stringArray  {key}={value} pairs that are passed as it is to a plugin, refer plugin's documentation to set appropriate values
        --signature-format string    signature envelope format, options: "jws", "cose" (default "jws")
-       --signature-manifest string  manifest type for signature, options: "image", "artifact" (default "artifact")
+       --signature-manifest string  manifest type for signature, options: "image", "artifact" (default "image")
   -u,  --username string            username for registry operations (default to $NOTATION_USERNAME if not specified)
   -m,  --user-metadata stringArray  {key}={value} pairs that are added to the signature payload
   -v,  --verbose                    verbose mode
 ```
 
 ## Use OCI image manifest to store signatures
 
-By default, Notation uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in registries. For registries that don't support `OCI artifact` or [Referrers API][oci-referers-api] is not enabled, users SHOULD use flag `--signature-manifest image` to force Notation to store the signatures using [OCI image manifest][oci-image-spec].
+By default, Notation uses [OCI image manifest][oci-image-spec] to store signatures in registries. Users can use [OCI artifact manifest][oci-artifact-manifest] by enabling the `--signature-manifest artifact` flag. When using OCI artifact manifest to store the signature, the registry is REQUIRED to support both `OCI artifact` and [Referrers API][oci-referers-api].
 
 Note that there is no deterministic way to determine whether a registry supports `OCI artifact` or not. The following response status contained in error messages MAY indicate that the registry doesn't support `OCI artifact`.
 
 - Response status `400 BAD Request` with error code `MANIFEST_INVALID` or `UNSUPPORTED`
 
 ### Set config property for OCI image manifest
 
-OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. Notation creates a default config descriptor for the user if flag `--signature-manifest image` is used.
-
-Notation uses empty JSON object `{}` as the default configuration content, and thus the default `config` property is fixed, as following:
+OCI image manifest requires additional property `config` of type `descriptor`, which is not required by OCI artifact manifest. When signing with OCI image manifest, Notation uses empty JSON object `{}` as the default configuration content, and thus the `config` property is fixed, as following:
 
 ```json
 "config": {
@@ -154,10 +152,10 @@ Warning: Always sign the artifact using digest(`@sha256:...`) rather than a tag(
 Successfully signed localhost:5000/net-monitor@sha256:b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
 ```
 
-### Sign an artifact and store the signature using OCI image manifest
+### Sign an artifact and store the signature using OCI artifact manifest
 
 ```shell
-notation sign --signature-manifest image <registry>/<repository>@<digest>
+notation sign --signature-manifest artifact <registry>/<repository>@<digest>
 ```
 
 [oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md

test/e2e/run.sh

@@ -40,7 +40,7 @@ if [ ! -f "$NOTATION_E2E_OLD_BINARY_PATH" ]; then
     echo "Try to use old notation binary at $NOTATION_E2E_OLD_BINARY_PATH"
 
     if [ ! -f $NOTATION_E2E_OLD_BINARY_PATH ]; then
-        TAG=1.0.0-rc.1 # without 'v'
+        TAG=1.0.0-rc.2 # without 'v'
         echo "Didn't find old notation binary locally. Try to download notation v$TAG."
 
         TAR_NAME=notation_${TAG}_linux_amd64.tar.gz

test/e2e/suite/command/verify.go

@@ -15,7 +15,7 @@ var _ = Describe("notation verify", func() {
 			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).
 				MatchKeyWords(SignSuccessfully)
 
-			notation.Exec("verify", artifact.ReferenceWithDigest()).
+			notation.Exec("verify", artifact.ReferenceWithDigest(), "-v").
 				MatchKeyWords(VerifySuccessfully)
 		})
 	})
@@ -25,7 +25,7 @@ var _ = Describe("notation verify", func() {
 			OldNotation().Exec("sign", artifact.ReferenceWithDigest()).
 				MatchKeyWords(SignSuccessfully)
 
-			notation.Exec("verify", artifact.ReferenceWithTag()).
+			notation.Exec("verify", artifact.ReferenceWithTag(), "-v").
 				MatchKeyWords(VerifySuccessfully)
 		})
 	})