Documentation ¶
Overview ¶
Package plugin provides the tooling to use the notation plugin.
includes a CLIManager and a CLIPlugin implementation.
Package plugin defines the protocol layer for communication between notation and notation external plugin.
Index ¶
- Constants
- type Capability
- type Command
- type CriticalAttributes
- type DescribeKeyRequest
- type DescribeKeyResponse
- type Error
- func NewError(code ErrorCode, msg string) *Error
- func NewGenericError(msg string) *Error
- func NewGenericErrorf(format string, msg ...any) *Error
- func NewJSONParsingError(msg string) *Error
- func NewUnsupportedContractVersionError(version string) *Error
- func NewUnsupportedError(msg string) *Error
- func NewValidationError(msg string) *Error
- func NewValidationErrorf(format string, msg ...any) *Error
- type ErrorCode
- type GenerateEnvelopeRequest
- type GenerateEnvelopeResponse
- type GenerateSignatureRequest
- type GenerateSignatureResponse
- type GenericPlugin
- type GetMetadataRequest
- type GetMetadataResponse
- type HashAlgorithm
- type KeySpec
- type Plugin
- type Request
- type SignPlugin
- type Signature
- type SignatureAlgorithm
- type TrustPolicy
- type VerificationResult
- type VerifyPlugin
- type VerifySignatureRequest
- type VerifySignatureResponse
Constants ¶
const ( ErrorMsgMalformedInput string = "Input is not a valid JSON" ErrorMsgMalformedOutputFmt string = "Failed to generate response. Error: %s" )
const BinaryPrefix = "notation-"
BinaryPrefix is the prefix required on all plugin binary names.
const ContractVersion = "1.0"
ContractVersion is the <major>.<minor> version of the plugin contract.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capability ¶
type Capability string
Capability is a feature available in the plugin contract.
const ( // CapabilitySignatureGenerator is the name of the capability // for a plugin to support generating raw signatures. CapabilitySignatureGenerator Capability = "SIGNATURE_GENERATOR.RAW" // CapabilityEnvelopeGenerator is the name of the capability // for a plugin to support generating envelope signatures. CapabilityEnvelopeGenerator Capability = "SIGNATURE_GENERATOR.ENVELOPE" // CapabilityTrustedIdentityVerifier is the name of the // capability for a plugin to support verifying trusted identities. CapabilityTrustedIdentityVerifier Capability = "SIGNATURE_VERIFIER.TRUSTED_IDENTITY" // CapabilityRevocationCheckVerifier is the name of the // capability for a plugin to support verifying revocation checks. CapabilityRevocationCheckVerifier Capability = "SIGNATURE_VERIFIER.REVOCATION_CHECK" )
type Command ¶
type Command string
Command is a CLI command available in the plugin contract.
const ( // CommandGetMetadata is the name of the plugin command // which must be supported by every plugin and returns the // plugin metadata. CommandGetMetadata Command = "get-plugin-metadata" // CommandDescribeKey is the name of the plugin command // which must be supported by every plugin that has the // SIGNATURE_GENERATOR.RAW capability. CommandDescribeKey Command = "describe-key" // CommandGenerateSignature is the name of the plugin command // which must be supported by every plugin that has the // SIGNATURE_GENERATOR.RAW capability. CommandGenerateSignature Command = "generate-signature" // CommandGenerateEnvelope is the name of the plugin command // which must be supported by every plugin that has the // SIGNATURE_GENERATOR.ENVELOPE capability. CommandGenerateEnvelope Command = "generate-envelope" // CommandVerifySignature is the name of the plugin command // which must be supported by every plugin that has // any SIGNATURE_VERIFIER.* capability CommandVerifySignature Command = "verify-signature" Version Command = "version" )
type CriticalAttributes ¶
type CriticalAttributes struct { ContentType string `json:"contentType"` SigningScheme string `json:"signingScheme"` Expiry *time.Time `json:"expiry,omitempty"` AuthenticSigningTime *time.Time `json:"authenticSigningTime,omitempty"` ExtendedAttributes map[string]interface{} `json:"extendedAttributes,omitempty"` }
CriticalAttributes contains all critical attributes and their values in the signature envelope
type DescribeKeyRequest ¶
type DescribeKeyRequest struct { ContractVersion string `json:"contractVersion"` KeyID string `json:"keyId"` PluginConfig map[string]string `json:"pluginConfig,omitempty"` }
DescribeKeyRequest contains the parameters passed in a describe-key request.
func (DescribeKeyRequest) Command ¶
func (DescribeKeyRequest) Command() Command
func (DescribeKeyRequest) Validate ¶
func (r DescribeKeyRequest) Validate() error
Validate validates DescribeKeyRequest struct
type DescribeKeyResponse ¶
type DescribeKeyResponse struct { // The same key id as passed in the request. KeyID string `json:"keyId"` // One of following supported key types: // https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection KeySpec KeySpec `json:"keySpec"` }
DescribeKeyResponse is the response of a describe-key request.
type Error ¶
type Error struct { ErrCode ErrorCode `json:"errorCode"` Message string `json:"errorMessage,omitempty"` Metadata map[string]string `json:"errorMetadata,omitempty"` }
Error is used to return a well-formed error response as per NotaryProject specification.
func NewGenericError ¶
func NewGenericErrorf ¶
func NewJSONParsingError ¶
func NewUnsupportedError ¶
func NewValidationError ¶
func NewValidationErrorf ¶
type ErrorCode ¶
type ErrorCode string
const ( ErrorCodeValidation ErrorCode = "VALIDATION_ERROR" ErrorCodeUnsupportedContractVersion ErrorCode = "UNSUPPORTED_CONTRACT_VERSION" ErrorCodeAccessDenied ErrorCode = "ACCESS_DENIED" ErrorCodeTimeout ErrorCode = "TIMEOUT" ErrorCodeThrottled ErrorCode = "THROTTLED" ErrorCodeGeneric ErrorCode = "ERROR" )
type GenerateEnvelopeRequest ¶
type GenerateEnvelopeRequest struct { ContractVersion string `json:"contractVersion"` KeyID string `json:"keyId"` PayloadType string `json:"payloadType"` SignatureEnvelopeType string `json:"signatureEnvelopeType"` Payload []byte `json:"payload"` ExpiryDurationInSeconds uint64 `json:"expiryDurationInSeconds,omitempty"` PluginConfig map[string]string `json:"pluginConfig,omitempty"` }
GenerateEnvelopeRequest contains the parameters passed in a generate-envelope request.
func (GenerateEnvelopeRequest) Command ¶
func (GenerateEnvelopeRequest) Command() Command
func (GenerateEnvelopeRequest) Validate ¶
func (r GenerateEnvelopeRequest) Validate() error
Validate validates GenerateEnvelopeRequest struct
type GenerateEnvelopeResponse ¶
type GenerateEnvelopeResponse struct { SignatureEnvelope []byte `json:"signatureEnvelope"` SignatureEnvelopeType string `json:"signatureEnvelopeType"` Annotations map[string]string `json:"annotations,omitempty"` }
GenerateEnvelopeResponse is the response of a generate-envelope request.
type GenerateSignatureRequest ¶
type GenerateSignatureRequest struct { ContractVersion string `json:"contractVersion"` KeyID string `json:"keyId"` KeySpec KeySpec `json:"keySpec"` Hash HashAlgorithm `json:"hashAlgorithm"` Payload []byte `json:"payload"` PluginConfig map[string]string `json:"pluginConfig,omitempty"` }
GenerateSignatureRequest contains the parameters passed in a generate-signature request.
func (GenerateSignatureRequest) Command ¶
func (GenerateSignatureRequest) Command() Command
func (GenerateSignatureRequest) Validate ¶
func (r GenerateSignatureRequest) Validate() error
Validate validates GenerateSignatureRequest struct
type GenerateSignatureResponse ¶
type GenerateSignatureResponse struct { KeyID string `json:"keyId"` Signature []byte `json:"signature"` SigningAlgorithm SignatureAlgorithm `json:"signingAlgorithm"` // Ordered list of certificates starting with leaf certificate // and ending with root certificate. CertificateChain [][]byte `json:"certificateChain"` }
GenerateSignatureResponse is the response of a generate-signature request.
type GenericPlugin ¶
type GenericPlugin interface { // GetMetadata returns the metadata information of the plugin. GetMetadata(ctx context.Context, req *GetMetadataRequest) (*GetMetadataResponse, error) }
GenericPlugin is the base requirement to be a plugin.
type GetMetadataRequest ¶
GetMetadataRequest contains the parameters passed in a get-plugin-metadata request.
func (GetMetadataRequest) Command ¶
func (GetMetadataRequest) Command() Command
func (GetMetadataRequest) Validate ¶
func (GetMetadataRequest) Validate() error
Validate validates GetMetadataRequest struct
type GetMetadataResponse ¶
type GetMetadataResponse struct { Name string `json:"name"` Description string `json:"description"` Version string `json:"version"` URL string `json:"url"` SupportedContractVersions []string `json:"supportedContractVersions,omitempty"` Capabilities []Capability `json:"capabilities"` }
GetMetadataResponse provided by the plugin.
func (*GetMetadataResponse) HasCapability ¶
func (resp *GetMetadataResponse) HasCapability(capability Capability) bool
HasCapability return true if the metadata states that the capability is supported. Returns true if capability is empty.
type HashAlgorithm ¶
type HashAlgorithm string
HashAlgorithm supported by notation.
const ( HashAlgorithmSHA256 HashAlgorithm = "SHA-256" HashAlgorithmSHA384 HashAlgorithm = "SHA-384" HashAlgorithmSHA512 HashAlgorithm = "SHA-512" )
one of the following supported hash algorithm names.
type KeySpec ¶
type KeySpec string
KeySpec is type of the signing algorithm, including algorithm and size.
type Plugin ¶
type Plugin interface { SignPlugin VerifyPlugin }
Plugin defines required methods to be a Plugin.
type SignPlugin ¶
type SignPlugin interface { GenericPlugin // DescribeKey returns the KeySpec of a key. DescribeKey(ctx context.Context, req *DescribeKeyRequest) (*DescribeKeyResponse, error) // GenerateSignature generates the raw signature based on the request. GenerateSignature(ctx context.Context, req *GenerateSignatureRequest) (*GenerateSignatureResponse, error) // GenerateEnvelope generates the Envelope with signature based on the // request. GenerateEnvelope(ctx context.Context, req *GenerateEnvelopeRequest) (*GenerateEnvelopeResponse, error) }
SignPlugin defines the required methods to be a SignPlugin.
type Signature ¶
type Signature struct { CriticalAttributes CriticalAttributes `json:"criticalAttributes"` UnprocessedAttributes []string `json:"unprocessedAttributes"` CertificateChain [][]byte `json:"certificateChain"` }
Signature represents a signature pulled from the envelope
type SignatureAlgorithm ¶
type SignatureAlgorithm string
SignatureAlgorithm supported by notation
const ( SignatureAlgorithmECDSA_SHA256 SignatureAlgorithm = "ECDSA-SHA-256" SignatureAlgorithmECDSA_SHA384 SignatureAlgorithm = "ECDSA-SHA-384" SignatureAlgorithmECDSA_SHA512 SignatureAlgorithm = "ECDSA-SHA-512" SignatureAlgorithmRSASSA_PSS_SHA256 SignatureAlgorithm = "RSASSA-PSS-SHA-256" SignatureAlgorithmRSASSA_PSS_SHA384 SignatureAlgorithm = "RSASSA-PSS-SHA-384" SignatureAlgorithmRSASSA_PSS_SHA512 SignatureAlgorithm = "RSASSA-PSS-SHA-512" )
one of the following supported signing algorithm names.
type TrustPolicy ¶
type TrustPolicy struct { TrustedIdentities []string `json:"trustedIdentities"` SignatureVerification []Capability `json:"signatureVerification"` }
TrustPolicy represents trusted identities that sign the artifacts
type VerificationResult ¶
type VerificationResult struct { Success bool `json:"success"` Reason string `json:"reason,omitempty"` }
VerificationResult is the result of a verification performed by the plugin
type VerifyPlugin ¶
type VerifyPlugin interface { GenericPlugin // VerifySignature validates the signature based on the request. VerifySignature(ctx context.Context, req *VerifySignatureRequest) (*VerifySignatureResponse, error) }
VerifyPlugin defines the required method to be a VerifyPlugin.
type VerifySignatureRequest ¶
type VerifySignatureRequest struct { ContractVersion string `json:"contractVersion"` Signature Signature `json:"signature"` TrustPolicy TrustPolicy `json:"trustPolicy"` PluginConfig map[string]string `json:"pluginConfig,omitempty"` }
VerifySignatureRequest contains the parameters passed in a verify-signature request.
func (VerifySignatureRequest) Command ¶
func (VerifySignatureRequest) Command() Command
func (VerifySignatureRequest) Validate ¶
func (r VerifySignatureRequest) Validate() error
Validate validates VerifySignatureRequest struct
type VerifySignatureResponse ¶
type VerifySignatureResponse struct { VerificationResults map[Capability]*VerificationResult `json:"verificationResults"` ProcessedAttributes []interface{} `json:"processedAttributes"` }
VerifySignatureResponse is the response of a verify-signature request.