v2

Documentation

Overview

Package v2 is a package for parsing version 2 secretless.yml files. Most users of this package will only be concerned with the single func NewConfig, which parses yaml file content.

File Format

Here is an example configuration for an http basic auth service that demonstrates all the features of a v2 yaml file:

version: 2
services:
  http_basic_auth:
    connector: basic_auth
    listenOn: tcp://0.0.0.0:8080
    credentials:
      username: someuser
      password:
        from: conjur
        get: testpassword
      config:
        authenticateURLsMatching:
          - ^http.

A few notes:

• listenOn: This may be a tcp port on localhost or a unix socket. tcp ports should start with tcp:// and sockets with unix://. A socket address might look like: unix:///some/absolute/path.

• credentials: The keys of this dictionary are the names of the credentials within secretless. All values must be either a constant string, or a dictionary with the keys "from" and "get". Dictionary keys specify the location of the secret within a Provider, such as a vault or the system environment. "from" identifies the type of secret Provider, and "get" is the id of the secret within that Provider.

• config: The config key provides optional, protocol-specific configuration options. For many protocols, it can be omitted. In the case http, however, we must specify both the type of http authentication (in our example, "basic_auth") as well as which requests should be authenticated (in our example, all of them).

Index

• Variables
• func IsHTTPConnector(connector string) bool
• type Config
  • func NewConfig(v2YAML []byte) (*Config, error)
  • func (c Config) MarshalYAML() (interface{}, error)
  • func (c Config) String() string
• type ConfigEnv
  • func NewConfigEnv(logger log.Logger, availPlugins plugin.AvailablePlugins) ConfigEnv
  • func NewConfigEnvWithOptions(logger log.Logger, availPlugins plugin.AvailablePlugins, ...) ConfigEnv
  • func (c *ConfigEnv) Prepare(cfg Config) error
• type ConfigsByType
  • func NewConfigsByType(uncheckedConfigs []*Service, availPlugins plugin.AvailablePlugins) ConfigsByType
• type Credential
  • func NewCredential(credName string, credYAML interface{}) (*Credential, error)
  • func NewCredentials(credsYAML credentialsYAML) ([]*Credential, error)
• type DeleteFileFunc
• type FileInfoFunc
• type HTTPConfig
  • func NewHTTPConfig(cfgBytes []byte) (*HTTPConfig, error)
• type HTTPServiceConfig
  • func (cfg *HTTPServiceConfig) Name() string
• type NetworkAddress
  • func (a NetworkAddress) Address() string
  • func (a NetworkAddress) Network() string
• type Service
  • func NewService(svcName string, svcYAML *serviceYAML) (*Service, error)
  • func (s Service) HasCredential(credentialName string) bool

Variables

var HTTPAuthenticationStrategies = []interface{}{
	"aws",
	"basic_auth",
	"conjur",
}

HTTPAuthenticationStrategies are the different ways an http service can authenticate.

Functions

func IsHTTPConnector

func IsHTTPConnector(connector string) bool

IsHTTPConnector returns true iff the connector provided uses the http protocol

Types

type Config

type Config struct {
	Debug    bool
	Services []*Service
}

Config represents a full configuration of Secretless, which is just a list of individual Service configurations.

func NewConfig

func NewConfig(v2YAML []byte) (*Config, error)

NewConfig creates a v2.Config from yaml bytes

func (Config) MarshalYAML

func (c Config) MarshalYAML() (interface{}, error)

MarshalYAML serializes Config to the secretless.yml format

func (Config) String

func (c Config) String() string

Serialize Config to YAML

type ConfigEnv

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

ConfigEnv represents the runtime environment that will fulfill the services requested by the Config. It has a single public method, Prepare, that ensures the runtime environment supports the requested services.

func NewConfigEnv

func NewConfigEnv(logger log.Logger, availPlugins plugin.AvailablePlugins) ConfigEnv

NewConfigEnv creates a new instance of ConfigEnv.

func NewConfigEnvWithOptions

func NewConfigEnvWithOptions(
	logger log.Logger,
	availPlugins plugin.AvailablePlugins,
	getFileInfo func(name string) (os.FileInfo, error),
	deleteFile func(name string) error,
) ConfigEnv

NewConfigEnvWithOptions allows injecting all dependencies. Used for unit testing.

func (*ConfigEnv) Prepare

func (c *ConfigEnv) Prepare(cfg Config) error

Prepare ensures the runtime environment is prepared to handle the Config's service requests. It checks both that the requested connectors exist, and that the requested sockets are available, or can be deleted. If any of these checks fail, it will error.

type ConfigsByType

type ConfigsByType struct {
	HTTP     []HTTPServiceConfig
	SSH      []Service
	SSHAgent []Service
	TCP      []Service
}

ConfigsByType holds proxy service configuration in a form that directly corresponds to the ProxyService objects we want to create. One ProxyService will be created for each entry in http, and one for each entry in tcp.

func NewConfigsByType

func NewConfigsByType(
	uncheckedConfigs []*Service,
	availPlugins plugin.AvailablePlugins,
) ConfigsByType

NewConfigsByType converts a slice of v2.Service configs into the configs needed to actually created ProxyServices -- configsByType. In particular, it takes all the http configs and creates proper HTTPServiceConfig objects out of them -- grouping the raw v2.Service configs by their listenOn property. The remaining services are tcp, and already correspond 1-1 to the services we'll run. TODO: Eventually the application code should not be dealing directly with

[]Service at all, but the processing into these more appropriate domain
configs should occur entirely at the border.

type Credential

type Credential struct {
	Name string
	From string
	Get  string
}

Credential is the v2 representation of a named secret stored in a provider. It's the analog of the v1.StoredSecret. TODO: Move to types file along with other non-dependency types.

func NewCredential

func NewCredential(credName string, credYAML interface{}) (*Credential, error)

NewCredential creates a Credential from a credential name and raw yaml that's been unmarshalled into an interface{}.

func NewCredentials

func NewCredentials(credsYAML credentialsYAML) ([]*Credential, error)

NewCredentials converts the raw YAML representation of credentials (credentialsYAML) into it's logical representation ([]*Credential).

type DeleteFileFunc

type DeleteFileFunc func(name string) error

DeleteFileFunc is a function that takes a filename, attempts to delete the file, and returns an error if it can't.

type FileInfoFunc

type FileInfoFunc func(name string) (os.FileInfo, error)

FileInfoFunc is a function that takes a filename and returns information about that file, or an error if it cannot be found or read.

type HTTPConfig

type HTTPConfig struct {
	AuthenticateURLsMatching []*regexp.Regexp
}

HTTPConfig represents service-specific configuration for service connectors built on top of the http protocol

func NewHTTPConfig

func NewHTTPConfig(cfgBytes []byte) (*HTTPConfig, error)

NewHTTPConfig creates an HTTPConfig from yaml bytes

type HTTPServiceConfig

type HTTPServiceConfig struct {
	SharedListenOn    NetworkAddress
	SubserviceConfigs []Service
}

HTTPServiceConfig represents an HTTP proxy service configuration. Multiple http entries within a v2.Service config slice that share a listenOn actually represent a single HTTP proxy service, with sub-handlers for different traffic. This type captures that fact.

func (*HTTPServiceConfig) Name

func (cfg *HTTPServiceConfig) Name() string

Name returns the name of an HTTPServiceConfig

type NetworkAddress

type NetworkAddress string

NetworkAddress is a utility type for handling string manipulation / destructuring for listenOn addresses that include a network. Currently only used outside this package.

func (NetworkAddress) Address

func (a NetworkAddress) Address() string

Address returns the "address" part of a network address, eg, "127.0.0.1".

func (NetworkAddress) Network

func (a NetworkAddress) Network() string

Network returns the "network" part of a network address, eg, "tcp" or "unix".

type Service

type Service struct {
	Debug           bool
	Connector       string
	ConnectorConfig connectorConfig
	Credentials     []*Credential
	ListenOn        NetworkAddress
	Name            string
}

Service represents the configuration of a Secretless proxy service. It includes the service's protocol, the socket or address it listens on, the location of its required credentials, and (optionally) any additional protocol specific configuration.

func NewService

func NewService(svcName string, svcYAML *serviceYAML) (*Service, error)

NewService creates a named v2.Service from yaml bytes

func (Service) HasCredential

func (s Service) HasCredential(credentialName string) bool

HasCredential indicates whether a Service has the specified credential.