pal

README

PAL

PAL is a tool for provisioning secrets to docker containers in production.

Architecture

PAL uses a client/server architecture consisting of two components: a pal client which runs as the entrypoint to a container, and pald, which is a daemon that runs outside of the container, accepts requests from pal instances over a unix domain socket, and makes access control decisions.

PAL provisions secrets by distributing ciphertexts. A container must have access to ciphertexts of the secrets that it wishes to access. The pal client sends these to pald, which decrypts them.

Backends

Currently, PAL supports two backends: PGP and Red October.

PGP

The PGP backend uses a static PGP key to decrypt ciphertexts. The pald daemon must have access to this key in order to perform decryption. The palpgpenc tool (see cmd/palpgpenc) can be used to encrypt secrets for a particular PGP key.

Red October

The Red October backend uses Red October to decrypt ciphertexts. Since decryption requests come from pald, pald must have its own user account in Red October, or otherwise must have access to the credentials to a shared user account. Secrets owners then delegation decryption access to the pald account so that pald can request decryption on behalf of pal.

Configuration

pal requires a PAL_SECRETS_YAML environment variable in your container. PAL_SECRETS_YAML is broken into blocks named by environments. The name of your desired environment must be provided to pal via the -env flag or via the APP_ENV environment variable. The environments are further divided into env and file blocks, each of which is a YAML dictionary. The env block maps environment variable names to their contents, while the file block maps file paths to their contents. pal writes files as the current container's user, but the file permissions must be set by the chosen command if necessary.

Both blocks admit contents in one of these schemes, denoted by adding a prefix to the contents:

• ro: Red October encrypted data. The value placed under the key will be returned after Red October decryption.
• ro+base64: Red October encrypted, base64-encoded data. The value placed under this key will be returned after Red October decryption followed by base64 decoding. This is useful for binary data, as Red October only handles secrets encoded as strings.
• pgp: PGP encrypted data. The value placed under the key will be returned after pald decrypt it using one of its configured keyrings
• pgp+base64: PGP encrypted, base64-encoded data.
• No prefix: Data with no prefix are just returned as read from the file. This is useful for defining a development environment with well-known secrets.

An example of PAL_SECRETS_YAML is as follow:

PAL_SECRETS_YAML: |
  dev:
    env:
      SECRET: "This is not secret"
    file:
      /usr/local/secret.txt: "Neither is this"
  production:
    env:
      SECRET: |
        ro:eyJWZXJzaW9uIjotMSwiRGF0YSI6ImV5SldaWEp6YVc5dUlqb3hMQ0pXWVhWc2RFbGtJam8
        TnpNMU5EY3pPREVzSWt0bGVWTmxkQ0k2VzNzaVRtRnRaU0k2V3lKQmJHbGpaU0lzSWtKdllpSm
        RMQ0pMWlhraU9pSXdkMjVvVWtaVmVGTkVRUzlWUmpkWk4wVmxNMngzUFQwaWZWMHNJa3RsZVZO
        bGRGSlRRU0k2ZXlKQmJHbGpaU0k2ZXlKTFpYa2lPaUoyWkhSSVRuWnpiRGxQZVRSYWNWZDFVRE
        p0TlZoWlRYYzBPRTlRWjFwSlRIbHljR05rS3pjdk9EVnNObGR6Tm0wd2VYTnBkamxRVnpGMEsx
        VTFaR2hXZFVwU1ZETnRTR0poYTFBNGNVOUthamhCTjFSM2EycFZVRU4xYWtoelQwMVdSVFZRVm
        1ndk9WVXlSMXBEZVdseVRIVk1aSG92VTBSclVsUmpZVXRGTDBoM1RIZEplbGxyVTBaS1QzQlJa
        ME01WjFGbmVEZzJPR1JMZVdnM00wWTRjbXM0TjB0eWFDOW1UM3BDVkRWRVJXeDJabTFXTWtkRF
        UwbFJhVFJFUml0MFVqZGlVM2htVmtKa1R6VXphVFJLYVdWcWRUaE1OWHBuTW5oTFIxbGpjblp6
        YTNoRlExZHRRbXNyYlc1T2NtOU5aRFpCUXpNeVJrZ3ZTR2xHWVVkRlkzbGlSVmR0U2xkMFUyZF
        pXR3MwYmt4bE5YSkJaMUo0ZUZST04xVXdha3hPTURSSlNsWk1WV3RxWmxOWU1ESlhTMnBqZFVG
        MFVuZEZhVGt3TW10WVZsUkpXVVJ3WVRaV2RuTlBiRWxCWTNvelIwcEtTbWM5UFNKOUxDSkNiMk
        lpT25zaVMyVjVJam9pUm1WUllYSkxVV3RyUzJrM09GbFBNekpCTnk5MldsSnRkWFowYWtsTmJr
        OW1ablpvUVVGeVJqbDJUMWd2UjI1WE1GbDJNRGwxT0VSRVJWQnNjVUp5TlhkSlR6QnlNM0Z3ZW
        1SeU5DOVhhamxqYkN0aGNHMTFZVEZhUW5oRlZpOUNTVk00VFVGWFZEUjBWalpDWm1wUWEwZFdM
        MmxsZFVORmNrbEtTa1pzVmxwTE0zYzJRWFZQTkc5aVkwNUpjVlZ0YjNWclJVVkxVek01TVdKNW
        NERlFOVTB6YkVack9USTRjbWhwWTBZd1FucEJSVWhYZFhkS1kzbE9OM0p5VlhkVU5EUXJlVzFp
        YlVsdU9UY3lkRGxYSzI5dFlVTm9VVmhuZFUwdll6SkNZMnByVERCNGJIZHViVEJTY205cmVEVl
        NjSFpSS3paMU1TdEJhbmd5WjNoMmRGaFNha296YkRGV01GUmlUeXMyVWxJclRVOTVRa1Z0Unk5
        R1VEVllOMGx3VkZsWlZVUk9RMnczYzJKemVqWkhZa3hLTTNoaUsyTjZjV1JGTUhkNlZubEtXbF
        I2V0c1UFEwOHplWFJwY1hobVlVSnRjVkIzUFQwaWZYMHNJa2xXSWpvaVZsUXpaMm9yV1hoTlRH
        YzBiVzk1UTJkd05uUTVkejA5SWl3aVJHRjBZU0k2SW5aMWJWVkJSa1pvWlRSUFFuQjBNak5yTj
        JkaVFsRTlQU0lzSWxOcFoyNWhkSFZ5WlNJNkluSnlSM2RtU3lzclRXVnhSREZtVUM5aU1GQlVi
        M1JQY0ZrNVVUMGlmUT09IiwiU2lnbmF0dXJlIjoiS0FrS21PK0J1UzU5ai8vbWZjSDN1a3BVeD
        JjPSJ9
    file:
      /usr/local/secret.txt: |
        ro:eyJWZXJzaW9uIjotMSwiRGF0YSI6ImV5SldaWEp6YVc5dUlqb3hMQ0pXWVhWc2RFbGtJam9
        4TlRZek56WTFPREF3TENKTVlXSmxiSE1pT2xzaWNHRnNMV1Y0WVcxd2JHVWlYU3dpUzJWNVUyV
        jBJanBiZXlKT1lXMWxJanBiSW1wcmNtOXNiQ0lzSW1KbGJtSjFjbXRsY25RaVhTd2lTMlY1SWp
        vaVpIbGtLMm95U1VGdFZYa3JOeXR4TDI1RVkzaExRVDA5SW4xZExDSkxaWGxUWlhSU1UwRWlPb
        nNpWW1WdVluVnlhMlZ5ZENJNmV5SkxaWGtpT2lKbFp6RnZUME5xWWxoM1VHWkJOVnBCV21Gd2N
        sQTJka1pRUmxweGN6QmFRa0pzWVUxdk4ydHZiV1p2Y200M1pqZ3lkQ3MyZDNJNVNEVkdhbVExT
        ms5SlExWm5jVGRZVVVNeGRXSkViMkkyY1ZseE5rbEdaSHBsU0hWV0wzZEhla3BOVjNWdlZGUlB
        aVEJvTHpoWE1WTkZWRWh0VUZBMFdqaHZiR0pGSzFsTE9YaFZUMDFuYkdaWmFXOVRhRGR5WTBaS
        FlsWXZSa1ZCYVROcU0yMW1ZV0ZsVVRjd09IY3JZMmRyVFUxU2VIUmtTRFExU1VRNFJEVkpNR3c
        wUkdNNU5FWmhZalJXUkVoNlQzbzROeTlQTjNwRFRuRTRWemhEUkhCWE9XTmpURk5tTnpCS1dqZ
        EthRkJpWWl0U1VWaG5aWG80V0hBMU5VNUtXa3RpVW01R09FUTJRbGxYVUc5Sk5uTkdTVGhwVTB
        0T2FUTXdNbGRrTVU1a1IwUkllR3BLTVRKUWRtUjRTbTkyTUcxMlpXd3ZORk5ZVm5oYVEweHBNS
        GxYUTNGaWJpdHBSMUZXWTJwVVRrbHBRMDVVVFcxT2NFUmpiVFppWjNjOVBTSjlMQ0pxYTNKdmJ
        Hd2lPbnNpUzJWNUlqb2lVVkZTT1hjNFFubHlhbWMzUmpaNFZFczRZMXBuVVZvd2RVZE1TVmt3V
        EhsTmRpOVRhRXBIU1V0V2JXRXpRelZNTkVrNFFuTXlSMGw0Tld0TFoxZExjbmhTUnpWQlprMVV
        XVVp2V1RNMVprbGhRM2RaTmtreksxSklSelJ4TVdkMVptWkRObmRrWlRVd1V6SnNTaTg0Wm1Wa
        1prSlVibTlCVDFjekt6aE1VMmN2TWtnd2FtOTRkVkJrU201dVdUVk9XV0pSYWxKME4yaG9PVmh
        4VDIxSmVtMVFOak5zWlVocE9FNHZTMUpOUlhGc1lqQTlJbjE5TENKSlZpSTZJbXAzTm5CQ1prZ
        EthbnByTm1KVVVGWXZOMFE1UmtFOVBTSXNJa1JoZEdFaU9pSnBWa3BwY21kQ1QxUnlNR3BhYzF
        GWFdEUXliR3hCUFQwaUxDSlRhV2R1WVhSMWNtVWlPaUpqTm1GQlIwbGFRbXNyV2toVFpuUmFVb
        EpDZDFGUlkwWkJNMFU5SW4wPSIsIlNpZ25hdHVyZSI6IkJaWnFXcjZ1TGYzcjZocFVCbmxtU2l
        KcUtSbz0ifQ==

Building and testing

• make: build the binaries, placing them in bin
• make test: run unit tests
• make integration-test: run the integration test stack including redoctober, pal and pald. See README.md in the test directory for more details.

Demo

For a demonstration of integrating PAL with the Red October backend, see the demo directory.

Documentation

Index

• type Client
  • func NewClientV1(r io.Reader, socketAddr, appEnv string) Client
  • func NewClientV2(r io.Reader, socketAddr, appEnv string) Client
• type ConfigEntry
• type Server
  • func NewServer(config *ServerConfigEntry) (s *Server, err error)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) ServeRPC(l net.Listener) error
• type ServerConfigEntry
  • func LoadServerConfigEntry(r io.Reader, environment string) (*ServerConfigEntry, error)

Types

type Client

type Client interface {
	// Decrypt sends decryption requests to pald for every secret specified in the
	// configuration for this Client. Upon success, the decrypted plaintexts are
	// stored for use in a future call to Exec.
	Decrypt() error
	// Exec executes the given command with the given environment. It additonally
	// injects any secrets decrypted with a previous call to Decrypt.
	Exec(arg, env []string) error
}

Client represents a PAL client capable of issuing deryption requests and executing a subprocess with a provided set of environment variables. It provides the core functionality for the 'pal' command line tool, and is implemented by the ClientV1 and ClientV2 types.

func NewClientV1

func NewClientV1(r io.Reader, socketAddr, appEnv string) Client

NewClientV1 constructs a new Client that implements version 1 of the PAL protocol. r is a PAL YAML configuration, socketAddr is the file path to the pald socket, and appEnv is the environment from the config to use.

If there is an error reading or parsing r, NewClientV1 will abort the process.

func NewClientV2

func NewClientV2(r io.Reader, socketAddr, appEnv string) Client

NewClientV2 constructs a new Client that implements version 2 of the PAL protocol. r is a PAL YAML configuration, socketAddr is the file path to the pald socket, and appEnv is the environment from the config to use.

If there is an error reading or parsing r, NewClientV2 will abort the process.

type ConfigEntry

type ConfigEntry struct {
	Envs       map[string]string `yaml:"env,omitempty"`
	Files      map[string]string `yaml:"file,omitempty"`
	EntryPoint string            `yaml:"entrypoint,omitempty"`
	Command    string            `yaml:"command,omitempty"`
}

ConfigEntry represents a parsed PAL client YAML configuration entry. Note that this is not the schema for a PAL client YAML configuration file. Instead, a PAL client YAML configuration file is itself a map where the keys are environment names, and each value is a single entry (represented by this type). In other words, the full parsed config file is represented by map[string]*ConfigEntry

The following is an example configuration file:

dev:
  entrypoint: env
  env:
    TESTVAR: ro:4VUfu2xX0KGcvRmP76e4VkdESQziR1S4kh7/TRoNOVJ

type Server

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

Server represents a PAL server capable of servicing deryption requests. It provides the core functionality for the 'pald' daemon.

func NewServer

func NewServer(config *ServerConfigEntry) (s *Server, err error)

NewServer constructs a new Server that supports versions 1 and 2 of the PAL protocol.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the legacy version 1 of the PAL protocol. It is only capable of handling Red October decryption requests.

func (*Server) ServeRPC

func (s *Server) ServeRPC(l net.Listener) error

ServeRPC serves version 2 of the PAL protocol.

type ServerConfigEntry

type ServerConfigEntry struct {
	ROServer string `yaml:"roserver,omitempty"`
	CABundle string `yaml:"ca,omitempty"`
	User     string `yaml:"ro_user,omitempty"`
	Password string `yaml:"ro_password,omitempty"`

	PGPKeyRingPath string `yaml:"pgp_keyring_path,omitempty"`
	PGPCipher      string `yaml:"pgp_cypher,omitempty"`
	PGPPassphrase  string `yaml:"pgp_passphrase,omitempty"`
	PGPHash        string `yaml:"pgp_hash,omitempty"`

	LabelsEnabled     bool   `yaml:"labels_enabled,omitempty"`
	LabelsRetriever   string `yaml:"labels_retriever,omitempty"`
	NotaryTrustServer string `yaml:"notary_trust_server,omitempty"`
	NotaryTrustDir    string `yaml:"notary_trust_dir,omitempty"`
}

ServerConfigEntry represents a parsed PAL server YAML configuration entry. Note that this is not the schema for a PAL server YAML configuration file. Instead, a PAL server YAML configuration file is itself a map where the keys are environment names, and each value is a single entry (represented by this type). In other words, the full parsed config file is represented by map[string]*ServerConfigEntry

The following is an example configuration file:

dev:
  entrypoint: env
  env:
    TESTVAR: ro:4VUfu2xX0KGcvRmP76e4VkdESQziR1S4kh7/TRoNOVJ

func LoadServerConfigEntry

func LoadServerConfigEntry(r io.Reader, environment string) (*ServerConfigEntry, error)

LoadServerConfigEntry reads and parses r as a PAL server YAML configuration file, and returns the entry corresponding to the given environment name.