envelopeenc

Documentation

Overview

Envelope encryption - envelope contains secret content encrypted with NaCl secretbox symmetric key ("DEK"), and that key is separately encrypted for each RSA public key recipient ("KEK").

Index

• func NaclSecretBoxEncrypter(kek [32]byte, kekId string) *naclSecretBox
• func RsaOaepSha256Decrypter(privKey *rsa.PrivateKey) *rsaPrivateKey
• func RsaOaepSha256Encrypter(pubKey *rsa.PublicKey) *rsaPublicKey
• type Envelope
  • func Encrypt(plaintext []byte, slotEncrypters []SlotEncrypter, label string) (*Envelope, error)
  • func UnmarshalDONTUSE(buf []byte) (*Envelope, error)
  • func (e *Envelope) Decrypt(decrypters ...SlotDecrypter) ([]byte, error)
  • func (e *Envelope) DecryptWithResolver(resolveKek KekResolver) ([]byte, error)
  • func (e *Envelope) MarshalDONTUSE() ([]byte, error)
• type KekResolver
  • func NewKekResolver(decrypters ...SlotDecrypter) KekResolver
• type KeySlot
• type SlotDecrypter
• type SlotEncrypter
• type SlotKind

Functions

func NaclSecretBoxEncrypter

func NaclSecretBoxEncrypter(kek [32]byte, kekId string) *naclSecretBox

grant access to envelope if user knows a symmetric 256-bit key (identified by KEK ID)

func RsaOaepSha256Decrypter

func RsaOaepSha256Decrypter(privKey *rsa.PrivateKey) *rsaPrivateKey

func RsaOaepSha256Encrypter

func RsaOaepSha256Encrypter(pubKey *rsa.PublicKey) *rsaPublicKey

Types

type Envelope

type Envelope struct {
	KeySlots         []KeySlot `json:"key_slots"`
	Label            string    `json:"label,omitempty"` // non-malleable through RSA_OAEP_SHA256
	EncryptedContent []byte    `json:"content"`         // nonce || secretbox_ciphertext
}

Protects its content with a DEK. the DEK is also contained in the envelope, but encrypted with multiple possible KEKs (public keys) as recipients, therefore the envelope can only be opened by any of the KEK private keys

func Encrypt

func Encrypt(plaintext []byte, slotEncrypters []SlotEncrypter, label string) (*Envelope, error)

func UnmarshalDONTUSE

func UnmarshalDONTUSE(buf []byte) (*Envelope, error)

func (*Envelope) Decrypt

func (e *Envelope) Decrypt(decrypters ...SlotDecrypter) ([]byte, error)

func (*Envelope) DecryptWithResolver

func (e *Envelope) DecryptWithResolver(resolveKek KekResolver) ([]byte, error)

use this when you want to manage resolving the KEK yourself

func (*Envelope) MarshalDONTUSE

func (e *Envelope) MarshalDONTUSE() ([]byte, error)

Marshals an envelope into a compact byte structure TODO: missing label and slot kind (DON'T USE)

type KekResolver

type KekResolver func(kind SlotKind, kekId string) SlotDecrypter

func NewKekResolver

func NewKekResolver(decrypters ...SlotDecrypter) KekResolver

type KeySlot

type KeySlot struct {
	Kind         SlotKind `json:"kind"`          // what kind of a key slot this is
	KekId        string   `json:"kek_id"`        // Kind=1 => SHA256-fingerprint of RSA public key, Kind=2 => name for key
	DekEncrypted []byte   `json:"dek_encrypted"` // Kind=1 => RSA_OAEP_SHA256(kekPub, dek, label), Kind=2 => nonceSeed || naclSecretBoxSeal(dek, deriveNonce(nonceSeed, label), kek)
}

The envelope is locked with several locks. Any of the KEKs can open the envelope

type SlotDecrypter

type SlotDecrypter interface {
	KekId() string
	DecryptSlot(slot *KeySlot, label string) ([]byte, error)
	CanDecrypt(kind SlotKind, kekId string) bool
}

type SlotEncrypter

type SlotEncrypter interface {
	KekId() string
	EncryptSlot(dek []byte, label string) (*KeySlot, error)
}

type SlotKind

type SlotKind uint8

currently supports only one kind, but this is for extensibility

const (
	SlotKindRsaOaepSha256 SlotKind = 1
	SlotKindNaclSecretBox SlotKind = 2
)