pluginutil

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Apr 11, 2024 License: MPL-2.0 Imports: 35 Imported by: 16

Documentation

Index

Constants

View Source
const (
	// PluginAutoMTLSEnv is used to ensure AutoMTLS is used. This will override
	// setting a TLSProviderFunc for a plugin.
	PluginAutoMTLSEnv = "VAULT_PLUGIN_AUTOMTLS_ENABLED"

	// PluginMlockEnabled is the ENV name used to pass the configuration for
	// enabling mlock
	PluginMlockEnabled = "VAULT_PLUGIN_MLOCK_ENABLED"

	// PluginVaultVersionEnv is the ENV name used to pass the version of the
	// vault server to the plugin
	PluginVaultVersionEnv = "VAULT_VERSION"

	// PluginMetadataModeEnv is an ENV name used to disable TLS communication
	// to bootstrap mounting plugins.
	PluginMetadataModeEnv = "VAULT_PLUGIN_METADATA_MODE"

	// PluginUnwrapTokenEnv is the ENV name used to pass unwrap tokens to the
	// plugin.
	PluginUnwrapTokenEnv = "VAULT_UNWRAP_TOKEN"

	// PluginCACertPEMEnv is an ENV name used for holding a CA PEM-encoded
	// string. Used for testing.
	PluginCACertPEMEnv = "VAULT_TESTING_PLUGIN_CA_PEM"

	// PluginMultiplexingOptOut is an ENV name used to define a comma separated list of plugin names
	// opted-out of the multiplexing feature; for emergencies if multiplexing ever causes issues
	PluginMultiplexingOptOut = "VAULT_PLUGIN_MULTIPLEXING_OPT_OUT"

	// PluginUseLegacyEnvLayering opts out of new environment variable precedence.
	// If set to true, Vault process environment variables take precedence over any
	// colliding plugin-specific environment variables. Otherwise, plugin-specific
	// environment variables take precedence over Vault process environment variables.
	PluginUseLegacyEnvLayering = "VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING"
)
View Source
const MultiplexingCtxKey string = "multiplex_id"
View Source
const (
	PluginMultiplexing_MultiplexingSupport_FullMethodName = "/pluginutil.multiplexing.PluginMultiplexing/MultiplexingSupport"
)

Variables

View Source
var ErrNoMultiplexingIDFound = errors.New("no multiplexing ID found")
View Source
var ErrPinnedVersionNotFound = errors.New("pinned version not found")

ErrPluginNotFound is returned when a plugin does not have a pinned version.

View Source
var File_sdk_helper_pluginutil_multiplexing_proto protoreflect.FileDescriptor
View Source
var PluginMultiplexing_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "pluginutil.multiplexing.PluginMultiplexing",
	HandlerType: (*PluginMultiplexingServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "MultiplexingSupport",
			Handler:    _PluginMultiplexing_MultiplexingSupport_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "sdk/helper/pluginutil/multiplexing.proto",
}

PluginMultiplexing_ServiceDesc is the grpc.ServiceDesc for PluginMultiplexing service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func CtxCancelIfCanceled

func CtxCancelIfCanceled(f context.CancelFunc, ctxCanceler context.Context) chan struct{}

CtxCancelIfCanceled takes a context cancel func and a context. If the context is shutdown the cancelfunc is called. This is useful for merging two cancel functions.

func GRPCSupport

func GRPCSupport() bool

GRPCSupport defaults to returning true, unless VAULT_VERSION is missing or it fails to meet the version constraint.

func GetMultiplexIDFromContext added in v0.6.0

func GetMultiplexIDFromContext(ctx context.Context) (string, error)

func InMetadataMode

func InMetadataMode() bool

InMetadataMode returns true if the plugin calling this function is running in metadata mode.

func MultiplexingSupported added in v0.4.0

func MultiplexingSupported(ctx context.Context, cc grpc.ClientConnInterface, name string) (bool, error)

func OptionallyEnableMlock

func OptionallyEnableMlock() error

OptionallyEnableMlock determines if mlock should be called, and if so enables mlock.

func RegisterPluginMultiplexingServer added in v0.4.0

func RegisterPluginMultiplexingServer(s grpc.ServiceRegistrar, srv PluginMultiplexingServer)

Types

type IdentityToken added in v0.11.0

type IdentityToken string

func (IdentityToken) String added in v0.11.0

func (t IdentityToken) String() string

String returns a redacted token string. Use the Token() method to obtain the non-redacted token contents.

func (IdentityToken) Token added in v0.11.0

func (t IdentityToken) Token() string

Token returns the non-redacted token contents.

type IdentityTokenRequest added in v0.11.0

type IdentityTokenRequest struct {
	// Audience identifies the recipient of the token. The requested
	// value will be in the "aud" claim. Required.
	Audience string
	// TTL is the requested duration that the token will be valid for.
	// Optional with a default of 1hr.
	TTL time.Duration
}

type IdentityTokenResponse added in v0.11.0

type IdentityTokenResponse struct {
	// Token is the plugin identity token.
	Token IdentityToken
	// TTL is the duration that the token is valid for after truncation is applied.
	// The TTL may be truncated depending on the lifecycle of its signing key.
	TTL time.Duration
}

type LookRunnerUtil

type LookRunnerUtil interface {
	Looker
	RunnerUtil
}

LookRunnerUtil defines the functions for both Looker and Wrapper

type Looker

type Looker interface {
	LookupPlugin(ctx context.Context, pluginName string, pluginType consts.PluginType) (*PluginRunner, error)
	LookupPluginVersion(ctx context.Context, pluginName string, pluginType consts.PluginType, version string) (*PluginRunner, error)
}

Looker defines the plugin Lookup function that looks into the plugin catalog for available plugins and returns a PluginRunner

type MultiplexingSupportRequest added in v0.4.0

type MultiplexingSupportRequest struct {
	// contains filtered or unexported fields
}

func (*MultiplexingSupportRequest) Descriptor deprecated added in v0.4.0

func (*MultiplexingSupportRequest) Descriptor() ([]byte, []int)

Deprecated: Use MultiplexingSupportRequest.ProtoReflect.Descriptor instead.

func (*MultiplexingSupportRequest) ProtoMessage added in v0.4.0

func (*MultiplexingSupportRequest) ProtoMessage()

func (*MultiplexingSupportRequest) ProtoReflect added in v0.4.0

func (*MultiplexingSupportRequest) Reset added in v0.4.0

func (x *MultiplexingSupportRequest) Reset()

func (*MultiplexingSupportRequest) String added in v0.4.0

func (x *MultiplexingSupportRequest) String() string

type MultiplexingSupportResponse added in v0.4.0

type MultiplexingSupportResponse struct {
	Supported bool `protobuf:"varint,1,opt,name=supported,proto3" json:"supported,omitempty"`
	// contains filtered or unexported fields
}

func (*MultiplexingSupportResponse) Descriptor deprecated added in v0.4.0

func (*MultiplexingSupportResponse) Descriptor() ([]byte, []int)

Deprecated: Use MultiplexingSupportResponse.ProtoReflect.Descriptor instead.

func (*MultiplexingSupportResponse) GetSupported added in v0.4.0

func (x *MultiplexingSupportResponse) GetSupported() bool

func (*MultiplexingSupportResponse) ProtoMessage added in v0.4.0

func (*MultiplexingSupportResponse) ProtoMessage()

func (*MultiplexingSupportResponse) ProtoReflect added in v0.4.0

func (*MultiplexingSupportResponse) Reset added in v0.4.0

func (x *MultiplexingSupportResponse) Reset()

func (*MultiplexingSupportResponse) String added in v0.4.0

func (x *MultiplexingSupportResponse) String() string

type PinnedVersion added in v0.11.0

type PinnedVersion struct {
	Name    string            `json:"name"`
	Type    consts.PluginType `json:"type"`
	Version string            `json:"version"`
}

type PluginClient added in v0.4.0

type PluginClient interface {
	Conn() grpc.ClientConnInterface
	Reload() error
	plugin.ClientProtocol
}

type PluginClientConfig added in v0.4.0

type PluginClientConfig struct {
	Name            string
	PluginType      consts.PluginType
	Version         string
	PluginSets      map[int]plugin.PluginSet
	HandshakeConfig plugin.HandshakeConfig
	Logger          log.Logger
	IsMetadataMode  bool
	AutoMTLS        bool
	MLock           bool
	Wrapper         RunnerUtil
}

type PluginMultiplexingClient added in v0.4.0

type PluginMultiplexingClient interface {
	MultiplexingSupport(ctx context.Context, in *MultiplexingSupportRequest, opts ...grpc.CallOption) (*MultiplexingSupportResponse, error)
}

PluginMultiplexingClient is the client API for PluginMultiplexing service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewPluginMultiplexingClient added in v0.4.0

func NewPluginMultiplexingClient(cc grpc.ClientConnInterface) PluginMultiplexingClient

type PluginMultiplexingServer added in v0.4.0

type PluginMultiplexingServer interface {
	MultiplexingSupport(context.Context, *MultiplexingSupportRequest) (*MultiplexingSupportResponse, error)
	// contains filtered or unexported methods
}

PluginMultiplexingServer is the server API for PluginMultiplexing service. All implementations must embed UnimplementedPluginMultiplexingServer for forward compatibility

type PluginMultiplexingServerImpl added in v0.4.0

type PluginMultiplexingServerImpl struct {
	UnimplementedPluginMultiplexingServer

	Supported bool
}

func (PluginMultiplexingServerImpl) MultiplexingSupport added in v0.4.0

type PluginRunner

type PluginRunner struct {
	Name           string                      `json:"name" structs:"name"`
	Type           consts.PluginType           `json:"type" structs:"type"`
	Version        string                      `json:"version" structs:"version"`
	OCIImage       string                      `json:"oci_image" structs:"oci_image"`
	Runtime        string                      `json:"runtime" structs:"runtime"`
	Command        string                      `json:"command" structs:"command"`
	Args           []string                    `json:"args" structs:"args"`
	Env            []string                    `json:"env" structs:"env"`
	Sha256         []byte                      `json:"sha256" structs:"sha256"`
	Builtin        bool                        `json:"builtin" structs:"builtin"`
	BuiltinFactory func() (interface{}, error) `json:"-" structs:"-"`
	RuntimeConfig  *prutil.PluginRuntimeConfig `json:"-" structs:"-"`
	Tmpdir         string                      `json:"-" structs:"-"`
}

PluginRunner defines the metadata needed to run a plugin securely with go-plugin.

func (*PluginRunner) BinaryReference added in v0.10.0

func (p *PluginRunner) BinaryReference() string

BinaryReference returns either the OCI image reference if it's a container plugin or the path to the binary if it's a plain process plugin.

func (*PluginRunner) Run

func (r *PluginRunner) Run(ctx context.Context, wrapper RunnerUtil, pluginSets map[int]plugin.PluginSet, hs plugin.HandshakeConfig, env []string, logger log.Logger) (*plugin.Client, error)

Run takes a wrapper RunnerUtil instance along with the go-plugin parameters and returns a configured plugin.Client with TLS Configured and a wrapping token set on PluginUnwrapTokenEnv for plugin process consumption.

func (*PluginRunner) RunConfig added in v0.2.0

func (r *PluginRunner) RunConfig(ctx context.Context, opts ...RunOpt) (*plugin.Client, error)

func (*PluginRunner) RunMetadataMode

func (r *PluginRunner) RunMetadataMode(ctx context.Context, wrapper RunnerUtil, pluginSets map[int]plugin.PluginSet, hs plugin.HandshakeConfig, env []string, logger log.Logger) (*plugin.Client, error)

RunMetadataMode returns a configured plugin.Client that will dispense a plugin in metadata mode. The PluginMetadataModeEnv is passed in as part of the Cmd to plugin.Client, and consumed by the plugin process on api.VaultPluginTLSProvider.

type RunOpt added in v0.2.0

type RunOpt func(*runConfig)

func AutoMTLS added in v0.2.0

func AutoMTLS(autoMTLS bool) RunOpt

func Env added in v0.2.0

func Env(env ...string) RunOpt

func HandshakeConfig added in v0.2.0

func HandshakeConfig(hs plugin.HandshakeConfig) RunOpt

func Logger added in v0.2.0

func Logger(logger log.Logger) RunOpt

func MLock added in v0.4.0

func MLock(mlock bool) RunOpt

func MetadataMode added in v0.2.0

func MetadataMode(isMetadataMode bool) RunOpt

func PluginSets added in v0.2.0

func PluginSets(pluginSets map[int]plugin.PluginSet) RunOpt

func Runner added in v0.2.0

func Runner(wrapper RunnerUtil) RunOpt

type RunnerUtil

type RunnerUtil interface {
	NewPluginClient(ctx context.Context, config PluginClientConfig) (PluginClient, error)
	ResponseWrapData(ctx context.Context, data map[string]interface{}, ttl time.Duration, jwt bool) (*wrapping.ResponseWrapInfo, error)
	MlockEnabled() bool
	VaultVersion(ctx context.Context) (string, error)
	ClusterID(ctx context.Context) (string, error)
}

RunnerUtil interface defines the functions needed by the runner to wrap the metadata needed to run a plugin process. This includes looking up Mlock configuration and wrapping data in a response wrapped token. logical.SystemView implementations satisfy this interface.

type SetPluginInput added in v0.10.0

type SetPluginInput struct {
	Name     string
	Type     consts.PluginType
	Version  string
	Command  string
	OCIImage string
	Runtime  string
	Args     []string
	Env      []string
	Sha256   []byte
}

SetPluginInput is only used as input for the plugin catalog's set methods. We don't use the very similar PluginRunner struct to avoid confusion about what's settable, which does not include the builtin fields.

type UnimplementedPluginMultiplexingServer added in v0.4.0

type UnimplementedPluginMultiplexingServer struct {
}

UnimplementedPluginMultiplexingServer must be embedded to have forward compatible implementations.

func (UnimplementedPluginMultiplexingServer) MultiplexingSupport added in v0.4.0

type UnsafePluginMultiplexingServer added in v0.4.0

type UnsafePluginMultiplexingServer interface {
	// contains filtered or unexported methods
}

UnsafePluginMultiplexingServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to PluginMultiplexingServer will result in compilation errors.

type VersionedPlugin added in v0.6.0

type VersionedPlugin struct {
	Type              string `json:"type"` // string instead of consts.PluginType so that we get the string form in API responses.
	Name              string `json:"name"`
	Version           string `json:"version"`
	OCIImage          string `json:"oci_image,omitempty"`
	Runtime           string `json:"runtime,omitempty"`
	SHA256            string `json:"sha256,omitempty"`
	Builtin           bool   `json:"builtin"`
	DeprecationStatus string `json:"deprecation_status,omitempty"`

	// Pre-parsed semver struct of the Version field
	SemanticVersion *version.Version `json:"-"`
}

VersionedPlugin holds any versioning information stored about a plugin in the plugin catalog.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL