plugin

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 31, 2024 License: Apache-2.0 Imports: 5 Imported by: 12

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

View Source 
const (
	ErrorMsgMalformedInput     string = "Input is not a valid JSON"
	ErrorMsgMalformedOutputFmt string = "Failed to generate response. Error: %s"
)
View Source 
const BinaryPrefix = "notation-"

BinaryPrefix is the prefix required on all plugin binary names.

View Source 
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 NewError 

func NewError(code ErrorCode, msg string) *Error

func NewGenericError 

func NewGenericError(msg string) *Error

func NewGenericErrorf 

func NewGenericErrorf(format string, msg ...any) *Error

func NewJSONParsingError 

func NewJSONParsingError(msg string) *Error

func NewUnsupportedContractVersionError 

func NewUnsupportedContractVersionError(version string) *Error

func NewUnsupportedError 

func NewUnsupportedError(msg string) *Error

func NewValidationError 

func NewValidationError(msg string) *Error

func NewValidationErrorf 

func NewValidationErrorf(format string, msg ...any) *Error

func (*Error) Error 

func (e *Error) Error() string

Error returns the formatted error message.

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 

type GetMetadataRequest struct {
	PluginConfig map[string]string `json:"pluginConfig,omitempty"`
}

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.

https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection

type KeySpec 

type KeySpec string

KeySpec is type of the signing algorithm, including algorithm and size. 

const (
	KeySpecRSA2048 KeySpec = "RSA-2048"
	KeySpecRSA3072 KeySpec = "RSA-3072"
	KeySpecRSA4096 KeySpec = "RSA-4096"
	KeySpecEC256   KeySpec = "EC-256"
	KeySpecEC384   KeySpec = "EC-384"
	KeySpecEC521   KeySpec = "EC-521"
)

KeySpec supported by notation.

https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection

type Plugin 

type Plugin interface {
	SignPlugin
	VerifyPlugin
}

Plugin defines required methods to be a Plugin.

type Request 

type Request interface {
	Command() Command
	Validate() error
}

Request defines a plugin request, which is always associated to a command.

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.

https://github.com/notaryproject/notaryproject/blob/main/specs/signature-specification.md#algorithm-selection

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.