Merge branch 'main' into BlobSigning

go.mod

@@ -9,7 +9,7 @@ require (
 	github.com/opencontainers/go-digest v1.0.0
 	github.com/opencontainers/image-spec v1.1.0
 	github.com/veraison/go-cose v1.1.0
-	golang.org/x/crypto v0.19.0
+	golang.org/x/crypto v0.20.0
 	golang.org/x/mod v0.15.0
 	oras.land/oras-go/v2 v2.4.0
 )

go.sum

@@ -38,8 +38,8 @@ github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5t
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
-golang.org/x/crypto v0.19.0 h1:ENy+Az/9Y1vSrlrvBSyna3PITt4tiZLf7sgCjZBX7Wo=
-golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
+golang.org/x/crypto v0.20.0 h1:jmAMJJZXr5KiCw05dfYK9QnqaqKLYXijU23lsEdcQqg=
+golang.org/x/crypto v0.20.0/go.mod h1:Xwo95rrVNIoSMx9wa1JroENMToLWn3RNVrTBpLHgZPQ=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0 h1:SernR4v+D55NyBH2QiEQrlBAnj1ECL6AGrA5+dPaMY8=

plugin/proto/algorithm.go

@@ -22,13 +22,17 @@ import (
 )
 
 // KeySpec is type of the signing algorithm, including algorithm and size.
+//
 // Deprecated: KeySpec exists for historical compatibility and should not be used.
-// To access KeySpec, use the notation-plugin-framework-go's plugin.KeySpec type.
+// To access KeySpec, use the notation-plugin-framework-go's [plugin.KeySpec] type.
 type KeySpec = plugin.KeySpec
 
 // one of the following supported key spec names.
 //
-// https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
+// Deprecated: KeySpec exists for historical compatibility and should not be used.
+// To access KeySpec, use the notation-plugin-framework-go's [plugin.KeySpec].
+//
+// [keys spec]: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
 const (
 	KeySpecRSA2048 = plugin.KeySpecRSA2048
 	KeySpecRSA3072 = plugin.KeySpecRSA3072
@@ -44,20 +48,20 @@ func EncodeKeySpec(k signature.KeySpec) (plugin.KeySpec, error) {
 	case signature.KeyTypeEC:
 		switch k.Size {
 		case 256:
-			return KeySpecEC256, nil
+			return plugin.KeySpecEC256, nil
 		case 384:
-			return KeySpecEC384, nil
+			return plugin.KeySpecEC384, nil
 		case 521:
-			return KeySpecEC521, nil
+			return plugin.KeySpecEC521, nil
 		}
 	case signature.KeyTypeRSA:
 		switch k.Size {
 		case 2048:
-			return KeySpecRSA2048, nil
+			return plugin.KeySpecRSA2048, nil
 		case 3072:
-			return KeySpecRSA3072, nil
+			return plugin.KeySpecRSA3072, nil
 		case 4096:
-			return KeySpecRSA4096, nil
+			return plugin.KeySpecRSA4096, nil
 		}
 	}
 	return "", fmt.Errorf("invalid KeySpec %q", k)
@@ -66,22 +70,22 @@ func EncodeKeySpec(k signature.KeySpec) (plugin.KeySpec, error) {
 // DecodeKeySpec parses keySpec name to a signature.keySpec type.
 func DecodeKeySpec(k plugin.KeySpec) (keySpec signature.KeySpec, err error) {
 	switch k {
-	case KeySpecRSA2048:
+	case plugin.KeySpecRSA2048:
 		keySpec.Size = 2048
 		keySpec.Type = signature.KeyTypeRSA
-	case KeySpecRSA3072:
+	case plugin.KeySpecRSA3072:
 		keySpec.Size = 3072
 		keySpec.Type = signature.KeyTypeRSA
-	case KeySpecRSA4096:
+	case plugin.KeySpecRSA4096:
 		keySpec.Size = 4096
 		keySpec.Type = signature.KeyTypeRSA
-	case KeySpecEC256:
+	case plugin.KeySpecEC256:
 		keySpec.Size = 256
 		keySpec.Type = signature.KeyTypeEC
-	case KeySpecEC384:
+	case plugin.KeySpecEC384:
 		keySpec.Size = 384
 		keySpec.Type = signature.KeyTypeEC
-	case KeySpecEC521:
+	case plugin.KeySpecEC521:
 		keySpec.Size = 521
 		keySpec.Type = signature.KeyTypeEC
 	default:
@@ -92,13 +96,17 @@ func DecodeKeySpec(k plugin.KeySpec) (keySpec signature.KeySpec, err error) {
 }
 
 // HashAlgorithm is the type of hash algorithm.
+//
 // Deprecated: HashAlgorithm exists for historical compatibility and should not be used.
-// To access HashAlgorithm, use the notation-plugin-framework-go's plugin.HashAlgorithm type.
+// To access HashAlgorithm, use the notation-plugin-framework-go's [plugin.HashAlgorithm] type.
 type HashAlgorithm = plugin.HashAlgorithm
 
 // one of the following supported hash algorithm names.
 //
-// https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
+// Deprecated: HashAlgorithm exists for historical compatibility and should not be used.
+// To access HashAlgorithm, use the notation-plugin-framework-go's [plugin.HashAlgorithm] type.
+//
+// [hash algorithm]: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
 const (
 	HashAlgorithmSHA256 = plugin.HashAlgorithmSHA256
 	HashAlgorithmSHA384 = plugin.HashAlgorithmSHA384
@@ -111,33 +119,37 @@ func HashAlgorithmFromKeySpec(k signature.KeySpec) (plugin.HashAlgorithm, error)
 	case signature.KeyTypeEC:
 		switch k.Size {
 		case 256:
-			return HashAlgorithmSHA256, nil
+			return plugin.HashAlgorithmSHA256, nil
 		case 384:
-			return HashAlgorithmSHA384, nil
+			return plugin.HashAlgorithmSHA384, nil
 		case 521:
-			return HashAlgorithmSHA512, nil
+			return plugin.HashAlgorithmSHA512, nil
 		}
 	case signature.KeyTypeRSA:
 		switch k.Size {
 		case 2048:
-			return HashAlgorithmSHA256, nil
+			return plugin.HashAlgorithmSHA256, nil
 		case 3072:
-			return HashAlgorithmSHA384, nil
+			return plugin.HashAlgorithmSHA384, nil
 		case 4096:
-			return HashAlgorithmSHA512, nil
+			return plugin.HashAlgorithmSHA512, nil
 		}
 	}
 	return "", fmt.Errorf("invalid KeySpec %q", k)
 }
 
 // SignatureAlgorithm is the type of signature algorithm
+//
 // Deprecated: SignatureAlgorithm exists for historical compatibility and should not be used.
-// To access SignatureAlgorithm, use the notation-plugin-framework-go's plugin.SignatureAlgorithm type.
+// To access SignatureAlgorithm, use the notation-plugin-framework-go's [plugin.SignatureAlgorithm] type.
 type SignatureAlgorithm = plugin.SignatureAlgorithm
 
-// one of the following supported signing algorithm names.
+// one of the following supported [signing algorithm] names.
+//
+// Deprecated: SignatureAlgorithm exists for historical compatibility and should not be used.
+// To access SignatureAlgorithm, use the notation-plugin-framework-go's [plugin.SignatureAlgorithm] type.
 //
-// https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
+// [signing algorithm]: https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection
 const (
 	SignatureAlgorithmECDSA_SHA256      = plugin.SignatureAlgorithmECDSA_SHA256
 	SignatureAlgorithmECDSA_SHA384      = plugin.SignatureAlgorithmECDSA_SHA384
@@ -152,35 +164,35 @@ const (
 func EncodeSigningAlgorithm(alg signature.Algorithm) (plugin.SignatureAlgorithm, error) {
 	switch alg {
 	case signature.AlgorithmES256:
-		return SignatureAlgorithmECDSA_SHA256, nil
+		return plugin.SignatureAlgorithmECDSA_SHA256, nil
 	case signature.AlgorithmES384:
-		return SignatureAlgorithmECDSA_SHA384, nil
+		return plugin.SignatureAlgorithmECDSA_SHA384, nil
 	case signature.AlgorithmES512:
-		return SignatureAlgorithmECDSA_SHA512, nil
+		return plugin.SignatureAlgorithmECDSA_SHA512, nil
 	case signature.AlgorithmPS256:
-		return SignatureAlgorithmRSASSA_PSS_SHA256, nil
+		return plugin.SignatureAlgorithmRSASSA_PSS_SHA256, nil
 	case signature.AlgorithmPS384:
-		return SignatureAlgorithmRSASSA_PSS_SHA384, nil
+		return plugin.SignatureAlgorithmRSASSA_PSS_SHA384, nil
 	case signature.AlgorithmPS512:
-		return SignatureAlgorithmRSASSA_PSS_SHA512, nil
+		return plugin.SignatureAlgorithmRSASSA_PSS_SHA512, nil
 	}
 	return "", fmt.Errorf("invalid algorithm %q", alg)
 }
 
 // DecodeSigningAlgorithm parses the signing algorithm name from a given string.
 func DecodeSigningAlgorithm(raw plugin.SignatureAlgorithm) (signature.Algorithm, error) {
 	switch raw {
-	case SignatureAlgorithmECDSA_SHA256:
+	case plugin.SignatureAlgorithmECDSA_SHA256:
 		return signature.AlgorithmES256, nil
-	case SignatureAlgorithmECDSA_SHA384:
+	case plugin.SignatureAlgorithmECDSA_SHA384:
 		return signature.AlgorithmES384, nil
-	case SignatureAlgorithmECDSA_SHA512:
+	case plugin.SignatureAlgorithmECDSA_SHA512:
 		return signature.AlgorithmES512, nil
-	case SignatureAlgorithmRSASSA_PSS_SHA256:
+	case plugin.SignatureAlgorithmRSASSA_PSS_SHA256:
 		return signature.AlgorithmPS256, nil
-	case SignatureAlgorithmRSASSA_PSS_SHA384:
+	case plugin.SignatureAlgorithmRSASSA_PSS_SHA384:
 		return signature.AlgorithmPS384, nil
-	case SignatureAlgorithmRSASSA_PSS_SHA512:
+	case plugin.SignatureAlgorithmRSASSA_PSS_SHA512:
 		return signature.AlgorithmPS512, nil
 	}
 	return 0, errors.New("unknown signing algorithm")

plugin/proto/errors.go

@@ -26,25 +26,41 @@ import (
 type ErrorCode = plugin.ErrorCode
 
 const (
-	// Any of the required request fields was empty,
-	// or a value was malformed/invalid.
+	// ErrorCodeValidation is used when any of the required request fields is empty ormalformed/invalid.
+	//
+	// Deprecated: ErrorCodeValidation exists for historical compatibility and should not be used.
+	// To access ErrorCodeValidation, use the notation-plugin-framework-go's [plugin.ErrorCodeValidation].
 	ErrorCodeValidation = plugin.ErrorCodeValidation
 
-	// The contract version used in the request is unsupported.
+	// ErrorCodeUnsupportedContractVersion is used when when the contract version used in the request is unsupported.
+	//
+	// Deprecated: ErrorCodeUnsupportedContractVersion exists for historical compatibility and should not be used.
+	// To access ErrorCodeUnsupportedContractVersion, use the notation-plugin-framework-go's [plugin.ErrorCodeUnsupportedContractVersion].
 	ErrorCodeUnsupportedContractVersion = plugin.ErrorCodeUnsupportedContractVersion
 
-	// Authentication/authorization error to use given key.
+	// ErrorCodeAccessDenied is used when user doesn't have required permission to access the key.
+	//
+	// Deprecated: ErrorCodeAccessDenied exists for historical compatibility and should not be used.
+	// To access ErrorCodeAccessDenied, use the notation-plugin-framework-go's [plugin.ErrorCodeAccessDenied].
 	ErrorCodeAccessDenied = plugin.ErrorCodeAccessDenied
 
-	// The operation to generate signature timed out
-	// and can be retried by Notation.
+	// ErrorCodeTimeout is used when an operation to generate signature timed out and can be retried by Notation.
+	//
+	// Deprecated: ErrorCodeTimeout exists for historical compatibility and should not be used.
+	// To access ErrorCodeTimeout, use the notation-plugin-framework-go's [plugin.ErrorCodeTimeout].
 	ErrorCodeTimeout = plugin.ErrorCodeTimeout
 
-	// The operation to generate signature was throttles
+	// ErrorCodeThrottled is used when an operation to generate signature was throttles
 	// and can be retried by Notation.
+	//
+	// Deprecated: ErrorCodeThrottled exists for historical compatibility and should not be used.
+	// To access ErrorCodeThrottled, use the notation-plugin-framework-go's [plugin.ErrorCodeThrottled].
 	ErrorCodeThrottled = plugin.ErrorCodeThrottled
 
-	// Any general error that does not fall into any categories.
+	// ErrorCodeGeneric  is used when an general error occurred that does not fall into any categories.
+	//
+	// Deprecated: ErrorCodeGeneric exists for historical compatibility and should not be used.
+	// To access ErrorCodeGeneric, use the notation-plugin-framework-go's [plugin.ErrorCodeGeneric].
 	ErrorCodeGeneric = plugin.ErrorCodeGeneric
 )
 

plugin/proto/metadata.go

@@ -16,11 +16,13 @@ package proto
 import "github.com/notaryproject/notation-plugin-framework-go/plugin"
 
 // GetMetadataRequest contains the parameters passed in a get-plugin-metadata request.
+//
 // Deprecated: GetMetadataRequest exists for historical compatibility and should not be used.
-// To access GetMetadataRequest, use the notation-plugin-framework-go's plugin.GetMetadataRequest type.
+// To access GetMetadataRequest, use the notation-plugin-framework-go's [plugin.GetMetadataRequest] type.
 type GetMetadataRequest = plugin.GetMetadataRequest
 
 // GetMetadataResponse provided by the plugin.
+//
 // Deprecated: GetMetadataResponse exists for historical compatibility and should not be used.
-// To access GetMetadataResponse, use the notation-plugin-framework-go's plugin.GetMetadataResponse type.
+// To access GetMetadataResponse, use the notation-plugin-framework-go's [plugin.GetMetadataResponse] type.
 type GetMetadataResponse = plugin.GetMetadataResponse

plugin/proto/proto.go

@@ -18,69 +18,103 @@ package proto
 import "github.com/notaryproject/notation-plugin-framework-go/plugin"
 
 // Prefix is the prefix required on all plugin binary names.
+//
 // Deprecated: Prefix exists for historical compatibility and should not be used.
-// To access Prefix, use the notation-plugin-framework-go's plugin.BinaryPrefix type.
+// To access Prefix, use the notation-plugin-framework-go's [plugin.BinaryPrefix] type.
 const Prefix = plugin.BinaryPrefix
 
 // ContractVersion is the <major>.<minor> version of the plugin contract.
+//
 // Deprecated: ContractVersion exists for historical compatibility and should not be used.
-// To access ContractVersion, use the notation-plugin-framework-go's plugin.ContractVersion type.
+// To access ContractVersion, use the notation-plugin-framework-go's [plugin.ContractVersion] type.
 const ContractVersion = plugin.ContractVersion
 
 // Command is a CLI command available in the plugin contract.
+//
+// Deprecated: Command exists for historical compatibility and should not be used.
+// To access Command, use the notation-plugin-framework-go's [plugin.Command] type.
 type Command = plugin.Command
 
 // Request defines a plugin request, which is always associated to a command.
+//
 // Deprecated: Request exists for historical compatibility and should not be used.
-// To access Request, use the notation-plugin-framework-go's plugin.Request type.
+// To access Request, use the notation-plugin-framework-go's [plugin.Request] type.
 type Request = plugin.Request
 
 const (
 	// CommandGetMetadata is the name of the plugin command
 	// which must be supported by every plugin and returns the
 	// plugin metadata.
+	//
+	// Deprecated: CommandGetMetadata exists for historical compatibility and should not be used.
+	// To access CommandGetMetadata, use the notation-plugin-framework-go's [plugin.CommandGetMetadata].
 	CommandGetMetadata = plugin.CommandGetMetadata
 
 	// CommandDescribeKey is the name of the plugin command
 	// which must be supported by every plugin that has the
 	// SIGNATURE_GENERATOR.RAW capability.
+	//
+	// Deprecated: CommandDescribeKey exists for historical compatibility and should not be used.
+	// To access CommandDescribeKey, use the notation-plugin-framework-go's [plugin.CommandDescribeKey].
 	CommandDescribeKey = plugin.CommandDescribeKey
 
 	// CommandGenerateSignature is the name of the plugin command
 	// which must be supported by every plugin that has the
 	// SIGNATURE_GENERATOR.RAW capability.
+	//
+	// Deprecated: CommandGenerateSignature exists for historical compatibility and should not be used.
+	// To access CommandGenerateSignature, use the notation-plugin-framework-go's [plugin.CommandGenerateSignature].
 	CommandGenerateSignature = plugin.CommandGenerateSignature
 
 	// CommandGenerateEnvelope is the name of the plugin command
 	// which must be supported by every plugin that has the
 	// SIGNATURE_GENERATOR.ENVELOPE capability.
+	//
+	// Deprecated: CommandGenerateEnvelope exists for historical compatibility and should not be used.
+	// To access CommandGenerateEnvelope, use the notation-plugin-framework-go's [plugin.CommandGenerateEnvelope].
 	CommandGenerateEnvelope = plugin.CommandGenerateEnvelope
 
 	// CommandVerifySignature is the name of the plugin command
 	// which must be supported by every plugin that has
 	// any SIGNATURE_VERIFIER.* capability
+	//
+	// Deprecated: CommandVerifySignature exists for historical compatibility and should not be used.
+	// To access CommandVerifySignature, use the notation-plugin-framework-go's [plugin.CommandVerifySignature].
 	CommandVerifySignature = plugin.CommandVerifySignature
 )
 
 // Capability is a feature available in the plugin contract.
+//
 // Deprecated: Capability exists for historical compatibility and should not be used.
-// To access Capability, use the notation-plugin-framework-go's plugin.Capability type.
+// To access Capability, use the notation-plugin-framework-go's [plugin.Capability] type.
 type Capability = plugin.Capability
 
 const (
 	// CapabilitySignatureGenerator is the name of the capability
 	// for a plugin to support generating raw signatures.
+	//
+	// Deprecated: CapabilitySignatureGenerator exists for historical compatibility and should not be used.
+	// To access CapabilitySignatureGenerator, use the notation-plugin-framework-go's [plugin.CapabilitySignatureGenerator].
 	CapabilitySignatureGenerator = plugin.CapabilitySignatureGenerator
 
 	// CapabilityEnvelopeGenerator is the name of the capability
 	// for a plugin to support generating envelope signatures.
+	//
+	// Deprecated: CapabilityEnvelopeGenerator exists for historical compatibility and should not be used.
+	// To access CapabilityEnvelopeGenerator, use the notation-plugin-framework-go's [plugin.CapabilityEnvelopeGenerator].
 	CapabilityEnvelopeGenerator = plugin.CapabilityEnvelopeGenerator
 
 	// CapabilityTrustedIdentityVerifier is the name of the
 	// capability for a plugin to support verifying trusted identities.
+	//
+	// Deprecated: CapabilityTrustedIdentityVerifier exists for historical compatibility and should not be used.
+	// To access CapabilityTrustedIdentityVerifier, use the notation-plugin-framework-go's [plugin.CapabilityTrustedIdentityVerifier].
 	CapabilityTrustedIdentityVerifier = plugin.CapabilityTrustedIdentityVerifier
 
 	// CapabilityRevocationCheckVerifier is the name of the
 	// capability for a plugin to support verifying revocation checks.
+	//
+	// Deprecated: CapabilityRevocationCheckVerifier exists for historical compatibility and should not be used.
+	// To access CapabilityRevocationCheckVerifier, use the notation-plugin-framework-go's [plugin.CapabilityRevocationCheckVerifier].
 	CapabilityRevocationCheckVerifier = plugin.CapabilityRevocationCheckVerifier
 )