dbplugin

Documentation

Index

• Variables
• func Serve(db Database)
• func ServeConfig(db Database) *plugin.ServeConfig
• type ChangeExpiration
• type ChangePassword
• type Database
  • func NewPluginClient(ctx context.Context, sys pluginutil.RunnerUtil, ...) (Database, error)
  • func PluginFactory(ctx context.Context, pluginName string, sys pluginutil.LookRunnerUtil, ...) (Database, error)
• type DatabaseErrorSanitizerMiddleware
  • func NewDatabaseErrorSanitizerMiddleware(next Database, secrets secretsFn) DatabaseErrorSanitizerMiddleware
  • func (mw DatabaseErrorSanitizerMiddleware) Close() (err error)
  • func (mw DatabaseErrorSanitizerMiddleware) DeleteUser(ctx context.Context, req DeleteUserRequest) (DeleteUserResponse, error)
  • func (mw DatabaseErrorSanitizerMiddleware) Initialize(ctx context.Context, req InitializeRequest) (resp InitializeResponse, err error)
  • func (mw DatabaseErrorSanitizerMiddleware) NewUser(ctx context.Context, req NewUserRequest) (resp NewUserResponse, err error)
  • func (mw DatabaseErrorSanitizerMiddleware) Type() (string, error)
  • func (mw DatabaseErrorSanitizerMiddleware) UpdateUser(ctx context.Context, req UpdateUserRequest) (UpdateUserResponse, error)
• type DatabasePluginClient
  • func (dc *DatabasePluginClient) Close() error
• type DeleteUserRequest
• type DeleteUserResponse
• type GRPCDatabasePlugin
  • func (GRPCDatabasePlugin) GRPCClient(doneCtx context.Context, _ *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)
  • func (d GRPCDatabasePlugin) GRPCServer(_ *plugin.GRPCBroker, s *grpc.Server) error
• type InitializeRequest
• type InitializeResponse
• type NewUserRequest
• type NewUserResponse
• type Statements
• type UpdateUserRequest
• type UpdateUserResponse
• type UsernameMetadata

Variables

var (
	ErrPluginShutdown = errors.New("plugin shutdown")
)

Functions

func Serve

func Serve(db Database)

Serve is called from within a plugin and wraps the provided Database implementation in a databasePluginRPCServer object and starts a RPC server.

func ServeConfig

func ServeConfig(db Database) *plugin.ServeConfig

Types

type ChangeExpiration

type ChangeExpiration struct {
	// NewExpiration of the user
	NewExpiration time.Time

	// Statements is an ordered list of commands to run within the database
	// when changing the user's expiration.
	Statements Statements
}

ChangeExpiration of a given user

type ChangePassword

type ChangePassword struct {
	// NewPassword for the user
	NewPassword string

	// Statements is an ordered list of commands to run within the database
	// when changing the user's password.
	Statements Statements
}

ChangePassword of a given user

type Database

type Database interface {
	// Initialize the database plugin. This is the equivalent of a constructor for the
	// database object itself.
	Initialize(ctx context.Context, req InitializeRequest) (InitializeResponse, error)

	// NewUser creates a new user within the database. This user is temporary in that it
	// will exist until the TTL expires.
	NewUser(ctx context.Context, req NewUserRequest) (NewUserResponse, error)

	// UpdateUser updates an existing user within the database.
	UpdateUser(ctx context.Context, req UpdateUserRequest) (UpdateUserResponse, error)

	// DeleteUser from the database. This should not error if the user didn't
	// exist prior to this call.
	DeleteUser(ctx context.Context, req DeleteUserRequest) (DeleteUserResponse, error)

	// Type returns the Name for the particular database backend implementation.
	// This type name is usually set as a constant within the database backend
	// implementation, e.g. "mysql" for the MySQL database backend. This is used
	// for things like metrics and logging. No behavior is switched on this.
	Type() (string, error)

	// Close attempts to close the underlying database connection that was
	// established by the backend.
	Close() error
}

Database to manipulate users within an external system (typically a database).

func NewPluginClient

func NewPluginClient(ctx context.Context, sys pluginutil.RunnerUtil, pluginRunner *pluginutil.PluginRunner, logger log.Logger, isMetadataMode bool) (Database, error)

NewPluginClient returns a databaseRPCClient with a connection to a running plugin. The client is wrapped in a DatabasePluginClient object to ensure the plugin is killed on call of Close().

func PluginFactory

func PluginFactory(ctx context.Context, pluginName string, sys pluginutil.LookRunnerUtil, logger log.Logger) (Database, error)

PluginFactory is used to build plugin database types. It wraps the database object in a logging and metrics middleware.

type DatabaseErrorSanitizerMiddleware

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

DatabaseErrorSanitizerMiddleware wraps an implementation of Databases and sanitizes returned error messages

func NewDatabaseErrorSanitizerMiddleware

func NewDatabaseErrorSanitizerMiddleware(next Database, secrets secretsFn) DatabaseErrorSanitizerMiddleware

func (DatabaseErrorSanitizerMiddleware) Close

func (mw DatabaseErrorSanitizerMiddleware) Close() (err error)

func (DatabaseErrorSanitizerMiddleware) DeleteUser

func (mw DatabaseErrorSanitizerMiddleware) DeleteUser(ctx context.Context, req DeleteUserRequest) (DeleteUserResponse, error)

func (DatabaseErrorSanitizerMiddleware) Initialize

func (mw DatabaseErrorSanitizerMiddleware) Initialize(ctx context.Context, req InitializeRequest) (resp InitializeResponse, err error)

func (DatabaseErrorSanitizerMiddleware) NewUser

func (mw DatabaseErrorSanitizerMiddleware) NewUser(ctx context.Context, req NewUserRequest) (resp NewUserResponse, err error)

func (DatabaseErrorSanitizerMiddleware) Type

func (mw DatabaseErrorSanitizerMiddleware) Type() (string, error)

func (DatabaseErrorSanitizerMiddleware) UpdateUser

func (mw DatabaseErrorSanitizerMiddleware) UpdateUser(ctx context.Context, req UpdateUserRequest) (UpdateUserResponse, error)

type DatabasePluginClient

type DatabasePluginClient struct {
	sync.Mutex

	Database
	// contains filtered or unexported fields
}

DatabasePluginClient embeds a databasePluginRPCClient and wraps it's Close method to also call Kill() on the plugin.Client.

func (*DatabasePluginClient) Close

func (dc *DatabasePluginClient) Close() error

This wraps the Close call and ensures we both close the database connection and kill the plugin.

type DeleteUserRequest

type DeleteUserRequest struct {
	// Username to delete from the database
	Username string

	// Statements is an ordered list of commands to run within the database
	// when deleting a user.
	Statements Statements
}

type DeleteUserResponse

type DeleteUserResponse struct{}

type GRPCDatabasePlugin

type GRPCDatabasePlugin struct {
	Impl Database

	// Embeding this will disable the netRPC protocol
	plugin.NetRPCUnsupportedPlugin
}

func (GRPCDatabasePlugin) GRPCClient

func (GRPCDatabasePlugin) GRPCClient(doneCtx context.Context, _ *plugin.GRPCBroker, c *grpc.ClientConn) (interface{}, error)

func (GRPCDatabasePlugin) GRPCServer

func (d GRPCDatabasePlugin) GRPCServer(_ *plugin.GRPCBroker, s *grpc.Server) error

type InitializeRequest

type InitializeRequest struct {
	// Config to initialize the database with. This can include things like connection details,
	// a "root" username & password, etc. This will not include all configuration items specified
	// when configuring the database. Some values will be stripped out by the database engine
	// prior to being passed to the plugin.
	Config map[string]interface{}

	// VerifyConnection during initialization. If true, a connection should be made to the
	// database to verify the connection can be made. If false, no connection should be made
	// on initialization.
	VerifyConnection bool
}

InitializeRequest contains all information needed to initialize a database plugin.

type InitializeResponse

type InitializeResponse struct {
	// Config that should be saved in Vault. This may differ from the config in the request,
	// but should contain everything required to Initialize the database.
	// REQUIRED in order to save the configuration into Vault after initialization
	Config map[string]interface{}
}

InitializeResponse returns any information Vault needs to know after initializing a database plugin.

type NewUserRequest

type NewUserRequest struct {
	// UsernameConfig is metadata that can be used to generate a username
	// within the database plugin
	UsernameConfig UsernameMetadata

	// Statements is an ordered list of commands to run within the database when
	// creating a new user. This frequently includes permissions to give the
	// user or similar actions.
	Statements Statements

	// RollbackStatements is an ordered list of commands to run within the database
	// if the new user creation process fails.
	RollbackStatements Statements

	// Password credentials to use when creating the user
	Password string

	// Expiration of the user. Not all database plugins will support this.
	Expiration time.Time
}

NewUserRequest request a new user is created

type NewUserResponse

type NewUserResponse struct {
	// Username of the user created within the database.
	// REQUIRED so Vault knows the name of the user that was created
	Username string
}

NewUserResponse returns any information Vault needs to know after creating a new user.

type Statements

type Statements struct {
	// Commands is an ordered list of commands to execute in the database.
	// These commands may include templated fields such as {{username}} and {{password}}
	Commands []string
}

Statements wraps a collection of statements to run in a database when an operation is performed (create, update, etc.). This is a struct rather than a string slice so we can easily add more information to this in the future.

type UpdateUserRequest

type UpdateUserRequest struct {
	// Username to make changes to.
	Username string

	// Password indicates the new password to change to.
	// If nil, no change is requested.
	Password *ChangePassword

	// Expiration indicates the new expiration date to change to.
	// If nil, no change is requested.
	Expiration *ChangeExpiration
}

type UpdateUserResponse

type UpdateUserResponse struct{}

type UsernameMetadata

type UsernameMetadata struct {
	DisplayName string
	RoleName    string
}

UsernameMetadata is metadata the database plugin can use to generate a username