1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261
|
// 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 provides the tooling to use the notation plugin.
//
// includes a CLIManager and a CLIPlugin implementation.
package plugin
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
"github.com/notaryproject/notation-go/internal/slices"
"github.com/notaryproject/notation-go/log"
"github.com/notaryproject/notation-go/plugin/proto"
"github.com/notaryproject/notation-plugin-framework-go/plugin"
)
var executor commander = &execCommander{} // for unit test
// GenericPlugin is the base requirement to be a plugin.
//
// Deprecated: GenericPlugin exists for historical compatibility and should not be used.
// To access GenericPlugin, use the notation-plugin-framework-go's plugin.GenericPlugin type.
type GenericPlugin = plugin.GenericPlugin
// SignPlugin defines the required methods to be a SignPlugin.
//
// Deprecated: SignPlugin exists for historical compatibility and should not be used.
// To access SignPlugin, use the notation-plugin-framework-go's plugin.SignPlugin type.
type SignPlugin = plugin.SignPlugin
// VerifyPlugin defines the required method to be a VerifyPlugin.
//
// Deprecated: VerifyPlugin exists for historical compatibility and should not be used.
// To access VerifyPlugin, use the notation-plugin-framework-go's plugin.VerifyPlugin type.
type VerifyPlugin = plugin.VerifyPlugin
// Plugin defines required methods to be a Plugin.
//
// Deprecated: Plugin exists for historical compatibility and should not be used.
// To access Plugin, use the notation-plugin-framework-go's plugin.Plugin type.
type Plugin = plugin.Plugin
// CLIPlugin implements Plugin interface to CLI plugins.
type CLIPlugin struct {
name string
path string
}
// NewCLIPlugin returns a *CLIPlugin.
func NewCLIPlugin(ctx context.Context, name, path string) (*CLIPlugin, error) {
// validate file existence
fi, err := os.Stat(path)
if err != nil {
// Ignore any file which we cannot Stat
// (e.g. due to permissions or anything else).
return nil, fmt.Errorf("plugin executable file is either not found or inaccessible: %w", err)
}
if !fi.Mode().IsRegular() {
// Ignore non-regular files.
return nil, ErrNotRegularFile
}
// generate plugin
return &CLIPlugin{
name: name,
path: path,
}, nil
}
// GetMetadata returns the metadata information of the plugin.
func (p *CLIPlugin) GetMetadata(ctx context.Context, req *plugin.GetMetadataRequest) (*plugin.GetMetadataResponse, error) {
var metadata plugin.GetMetadataResponse
err := run(ctx, p.name, p.path, req, &metadata)
if err != nil {
return nil, err
}
// validate metadata
if err = validate(&metadata); err != nil {
return nil, &PluginMalformedError{
Msg: fmt.Sprintf("metadata validation failed for plugin %s: %s", p.name, err),
InnerError: err,
}
}
if metadata.Name != p.name {
return nil, fmt.Errorf("plugin executable file name must be %q instead of %q", binName(metadata.Name), filepath.Base(p.path))
}
return &metadata, nil
}
// DescribeKey returns the KeySpec of a key.
//
// if ContractVersion is not set, it will be set by the function.
func (p *CLIPlugin) DescribeKey(ctx context.Context, req *plugin.DescribeKeyRequest) (*plugin.DescribeKeyResponse, error) {
if req.ContractVersion == "" {
req.ContractVersion = plugin.ContractVersion
}
var resp plugin.DescribeKeyResponse
err := run(ctx, p.name, p.path, req, &resp)
return &resp, err
}
// GenerateSignature generates the raw signature based on the request.
//
// if ContractVersion is not set, it will be set by the function.
func (p *CLIPlugin) GenerateSignature(ctx context.Context, req *plugin.GenerateSignatureRequest) (*plugin.GenerateSignatureResponse, error) {
if req.ContractVersion == "" {
req.ContractVersion = plugin.ContractVersion
}
var resp plugin.GenerateSignatureResponse
err := run(ctx, p.name, p.path, req, &resp)
return &resp, err
}
// GenerateEnvelope generates the Envelope with signature based on the request.
//
// if ContractVersion is not set, it will be set by the function.
func (p *CLIPlugin) GenerateEnvelope(ctx context.Context, req *plugin.GenerateEnvelopeRequest) (*plugin.GenerateEnvelopeResponse, error) {
if req.ContractVersion == "" {
req.ContractVersion = plugin.ContractVersion
}
var resp plugin.GenerateEnvelopeResponse
err := run(ctx, p.name, p.path, req, &resp)
return &resp, err
}
// VerifySignature validates the signature based on the request.
//
// if ContractVersion is not set, it will be set by the function.
func (p *CLIPlugin) VerifySignature(ctx context.Context, req *plugin.VerifySignatureRequest) (*plugin.VerifySignatureResponse, error) {
if req.ContractVersion == "" {
req.ContractVersion = plugin.ContractVersion
}
var resp plugin.VerifySignatureResponse
err := run(ctx, p.name, p.path, req, &resp)
return &resp, err
}
func run(ctx context.Context, pluginName string, pluginPath string, req plugin.Request, resp interface{}) error {
logger := log.GetLogger(ctx)
// serialize request
data, err := json.Marshal(req)
if err != nil {
logger.Errorf("Failed to marshal request object: %+v", req)
return fmt.Errorf("failed to marshal request object: %w", err)
}
logger.Debugf("Plugin %s request: %s", req.Command(), string(data))
// execute request
stdout, stderr, err := executor.Output(ctx, pluginPath, req.Command(), data)
if err != nil {
logger.Errorf("plugin %s execution status: %v", req.Command(), err)
if len(stderr) == 0 {
// if stderr is empty, it is possible that the plugin is not
// running properly.
logger.Errorf("failed to execute the %s command for plugin %s: %s", req.Command(), pluginName, err)
return &PluginExecutableFileError{
InnerError: err,
}
} else {
var re proto.RequestError
jsonErr := json.Unmarshal(stderr, &re)
if jsonErr != nil {
logger.Errorf("failed to execute the %s command for plugin %s: %s", req.Command(), pluginName, strings.TrimSuffix(string(stderr), "\n"))
return &PluginMalformedError{
InnerError: jsonErr,
}
}
logger.Errorf("failed to execute the %s command for plugin %s: %s: %w", req.Command(), pluginName, re.Code, re)
return re
}
}
logger.Debugf("Plugin %s response: %s", req.Command(), string(stdout))
// deserialize response
if err = json.Unmarshal(stdout, resp); err != nil {
logger.Errorf("failed to unmarshal plugin %s response: %w", req.Command(), err)
return &PluginMalformedError{
Msg: fmt.Sprintf("failed to unmarshal the response of %s command for plugin %s", req.Command(), pluginName),
InnerError: err,
}
}
return nil
}
// commander is defined for mocking purposes.
type commander interface {
// Output runs the command, passing req to the stdin.
// It only returns an error if the binary can't be executed.
// Returns stdout if err is nil, stderr if err is not nil.
Output(ctx context.Context, path string, command plugin.Command, req []byte) (stdout []byte, stderr []byte, err error)
}
// execCommander implements the commander interface using exec.Command().
type execCommander struct{}
func (c execCommander) Output(ctx context.Context, name string, command plugin.Command, req []byte) ([]byte, []byte, error) {
var stdout, stderr bytes.Buffer
cmd := exec.CommandContext(ctx, name, string(command))
cmd.Stdin = bytes.NewReader(req)
cmd.Stderr = &stderr
cmd.Stdout = &stdout
err := cmd.Run()
if err != nil {
return nil, stderr.Bytes(), err
}
return stdout.Bytes(), nil, nil
}
// validate checks if the metadata is correctly populated.
func validate(metadata *plugin.GetMetadataResponse) error {
if metadata.Name == "" {
return errors.New("empty name")
}
if metadata.Description == "" {
return errors.New("empty description")
}
if metadata.Version == "" {
return errors.New("empty version")
}
if metadata.URL == "" {
return errors.New("empty url")
}
if len(metadata.Capabilities) == 0 {
return errors.New("empty capabilities")
}
if len(metadata.SupportedContractVersions) == 0 {
return errors.New("supported contract versions not specified")
}
if !slices.Contains(metadata.SupportedContractVersions, plugin.ContractVersion) {
return fmt.Errorf(
"contract version %q is not in the list of the plugin supported versions %v",
plugin.ContractVersion, metadata.SupportedContractVersions,
)
}
return nil
}
|