eyaml

Documentation

Overview

Package eyaml is a pure-Go (no cgo) implementation of the encryption scheme used by Puppet's hiera-eyaml: the ENC[PKCS7,<base64>] token format that carries an encrypted value inside otherwise-plaintext YAML.

The engine is built exclusively on the Go standard library's crypto packages (crypto/rsa, crypto/x509, crypto/aes, crypto/cipher, crypto/rand, encoding/pem and encoding/asn1). The PKCS#7 / CMS EnvelopedData structure (RFC 5652) is assembled by hand on those primitives so the package needs no third-party crypto and no cgo.

Scheme

The default and only shipped Encryptor is PKCS7, which mirrors hiera-eyaml's pkcs7 encryptor:

• a random 256-bit AES content key encrypts the plaintext with AES-256-CBC (PKCS#7 block padding);
• the content key is wrapped for the recipient with RSA (PKCS#1 v1.5) under the recipient's X.509 certificate;
• the whole thing is serialised as a CMS EnvelopedData ContentInfo and base64-wrapped into an ENC[PKCS7,...] token.

CreateKeys generates the RSA keypair plus self-signed certificate that hiera-eyaml's "eyaml createkeys" would produce.

Extending

Encryptor is a pluggable seam: additional schemes (for example the hiera-eyaml "gpg" encryptor) can be added by implementing the interface. The gpg scheme is intentionally deferred and not implemented here, because it would pull in OpenPGP machinery beyond the standard-library crypto surface.

Index

• func Decrypt(enc Encryptor, token string) ([]byte, error)
• func Encrypt(enc Encryptor, plaintext []byte) (string, error)
• func FormatToken(scheme string, ciphertext []byte) string
• func IsToken(s string) bool
• func LoadCertificate(pemBytes []byte) (*x509.Certificate, error)
• func LoadPrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)
• func ParseToken(s string) (scheme string, ciphertext []byte, err error)
• type Encryptor
• type KeyOptions
• type KeyPair
  • func CreateKeys(opts *KeyOptions) (*KeyPair, error)
• type PKCS7
  • func NewPKCS7(certPEM, keyPEM []byte) (*PKCS7, error)
  • func (p *PKCS7) Decrypt(ciphertext []byte) ([]byte, error)
  • func (p *PKCS7) Encrypt(plaintext []byte) ([]byte, error)
  • func (p *PKCS7) Name() string

Functions

func Decrypt

func Decrypt(enc Encryptor, token string) ([]byte, error)

Decrypt is the high-level helper: it parses an ENC[...] token, checks the scheme matches enc, and returns the recovered plaintext.

func Encrypt

func Encrypt(enc Encryptor, plaintext []byte) (string, error)

Encrypt is the high-level helper: it seals plaintext with enc and returns a ready-to-store ENC[...] token.

func FormatToken

func FormatToken(scheme string, ciphertext []byte) string

FormatToken renders scheme and raw ciphertext as an ENC[...] token.

func IsToken

func IsToken(s string) bool

IsToken reports whether s contains an ENC[...] token.

func LoadCertificate

func LoadCertificate(pemBytes []byte) (*x509.Certificate, error)

LoadCertificate parses a PEM-encoded X.509 certificate.

func LoadPrivateKey

func LoadPrivateKey(pemBytes []byte) (*rsa.PrivateKey, error)

LoadPrivateKey parses a PEM-encoded RSA private key (PKCS#1 or PKCS#8).

func ParseToken

func ParseToken(s string) (scheme string, ciphertext []byte, err error)

ParseToken extracts the scheme name and decoded (base64-removed) ciphertext from the first ENC[...] token in s. Whitespace inside the payload, such as the line wrapping hiera-eyaml emits, is ignored.

Types

type Encryptor

type Encryptor interface {
	// Name is the scheme label that appears inside the token, e.g. "PKCS7".
	Name() string
	// Encrypt turns plaintext into raw scheme ciphertext (before base64).
	Encrypt(plaintext []byte) ([]byte, error)
	// Decrypt reverses Encrypt on raw scheme ciphertext.
	Decrypt(ciphertext []byte) ([]byte, error)
}

Encryptor is a pluggable eyaml cipher scheme. The default implementation is PKCS7; other hiera-eyaml schemes (for example gpg) can be added by implementing this interface.

type KeyOptions

type KeyOptions struct {
	// Bits is the RSA modulus size; zero means 2048.
	Bits int
	// Rand overrides the randomness source (defaults to crypto/rand.Reader).
	Rand io.Reader
	// NotBefore/NotAfter bound certificate validity; zero values default to
	// now and now+100 years.
	NotBefore time.Time
	NotAfter  time.Time
	// Serial sets the certificate serial number; nil means a random 128-bit
	// value.
	Serial *big.Int
}

KeyOptions tunes CreateKeys. The zero value yields hiera-eyaml's defaults: a 2048-bit key, a 100-year validity window starting now, and a random 128-bit serial, drawn from crypto/rand.

type KeyPair

type KeyPair struct {
	PrivateKeyPEM []byte
	PublicKeyPEM  []byte
}

KeyPair holds the PEM-encoded material produced by CreateKeys: an RSA private key and the matching self-signed X.509 certificate that hiera-eyaml calls the "public key".

func CreateKeys

func CreateKeys(opts *KeyOptions) (*KeyPair, error)

CreateKeys generates an RSA keypair and a self-signed certificate, mirroring hiera-eyaml's "eyaml createkeys". opts may be nil to accept all defaults.

type PKCS7

type PKCS7 struct {
	// Cert is the recipient certificate used when encrypting.
	Cert *x509.Certificate
	// Key is the RSA private key used when decrypting.
	Key *rsa.PrivateKey
	// Rand overrides the randomness source (defaults to crypto/rand.Reader).
	Rand io.Reader
	// contains filtered or unexported fields
}

PKCS7 is the hiera-eyaml "pkcs7" encryptor: AES-256-CBC content encryption with an RSA-wrapped content key, serialised as CMS EnvelopedData. Cert is required to Encrypt; Key is required to Decrypt.

func NewPKCS7

func NewPKCS7(certPEM, keyPEM []byte) (*PKCS7, error)

NewPKCS7 builds a PKCS7 encryptor from PEM material. Either argument may be empty: pass only certPEM for an encrypt-only value, only keyPEM for a decrypt-only value, or both for round trips.

func (*PKCS7) Decrypt

func (p *PKCS7) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt opens ciphertext with the configured private key.

func (*PKCS7) Encrypt

func (p *PKCS7) Encrypt(plaintext []byte) ([]byte, error)

Encrypt seals plaintext for the configured certificate.

func (*PKCS7) Name

func (p *PKCS7) Name() string

Name reports the scheme label, "PKCS7".