crypto

Documentation

Index

• Constants
• func CipherName(cipher string, keyLen KeyLen, mode Mode) string
• func EncodeData(data Data) ([]byte, error)
• func GobEncodeData(data Data) ([]byte, error)
• func HashSHA256(data []byte) ([]byte, error)
• func MakeNonce() ([]byte, error)
• func MakeRand(length uint) ([]byte, error)
• func MakeSalt() ([]byte, error)
• func NewCipherKey(l KeyLen, secret, salt []byte) ([]byte, error)
• func NewPBKDF2CipherKey(l KeyLen, iterations int, secret, salt []byte) ([]byte, error)
• func NewScryptCipherKey(l KeyLen, iterations int, secret, salt []byte) ([]byte, error)
• type Data
  • func DecodeData(b []byte) (Data, error)
  • func GobDecodeData(b []byte) (Data, error)
  • func NewData(h Header, data []byte) Data
  • func (e Data) Valid() error
• type Encryptor
• type Header
  • func NewHeader(cipher string, keyLen KeyLen, mode Mode, salt []byte, iv []byte, nonce []byte) (Header, error)
  • func (h *Header) Name() string
  • func (h Header) Valid() error
• type KeyLen
  • func (k KeyLen) String() string
• type ManagedSecret
  • func NewManagedSecret(id, secret string) *ManagedSecret
  • func (s ManagedSecret) ID() string
• type Mode
  • func (m Mode) String() string
• type Secret
• type SecureSecret
  • func NewSecureSecret(id string, openSecret func(Secret) []byte) *SecureSecret
  • func (s SecureSecret) ID() string
  • func (s SecureSecret) Open() []byte
• type TextSecret
  • func (s TextSecret) ID() string
  • func (s TextSecret) Open() []byte

Constants

const (
	Key128 KeyLen = 16 // 128 bit
	Key192        = 24 // 128 bit
	Key256        = 32 // 128 bit
)

key lengths

const (
	// SaltLength is the default salt length.
	SaltLength = 32

	// NonceLength is the default nonce length.
	NonceLength = 12
)

const MinSaltLength = 8

MinSaltLength is the minimum length of the salt buffer.

Functions

func CipherName

func CipherName(cipher string, keyLen KeyLen, mode Mode) string

CipherName is a convenience function that returns the name, key length, and mode of a cipher in the following format "[cipher][key length]-[mode]" e.g. "aes192-ctr".

func EncodeData

func EncodeData(data Data) ([]byte, error)

EncodeData encodes Data to a byte representation. This provides a small abstraction in case we want to swap out the gob encoder for something else.

func GobEncodeData

func GobEncodeData(data Data) ([]byte, error)

GobEncodeData serializes Data to a gob binary representation.

func HashSHA256

func HashSHA256(data []byte) ([]byte, error)

HashSHA256 returns a sha256 hash of data.

func MakeNonce

func MakeNonce() ([]byte, error)

MakeNonce returns random nonce of size length.

func MakeRand

func MakeRand(length uint) ([]byte, error)

MakeRand returns a buffer of size length filled with random bytes.

func MakeSalt

func MakeSalt() ([]byte, error)

MakeSalt returns random salt of size length.

func NewCipherKey

func NewCipherKey(l KeyLen, secret, salt []byte) ([]byte, error)

NewCipherKey generate a new cipher key of the appropriate key length. Note: Currently this is hard-coded to 4096 key iterations. The thinking here is that the strength of secret was determined externally and therefore it less important to iterate (again) a large number of times. 1<<15 (or 32768) key iterations, seems to be the current consensus for passwords in general (2020).

func NewPBKDF2CipherKey

func NewPBKDF2CipherKey(l KeyLen, iterations int, secret, salt []byte) ([]byte, error)

NewPBKDF2CipherKey generate a new cipher key using pbkdf2.

func NewScryptCipherKey

func NewScryptCipherKey(l KeyLen, iterations int, secret, salt []byte) ([]byte, error)

NewScryptCipherKey generate a new cipher key using scrypt.

Types

type Data

type Data struct {
	Header
	Bytes []byte
}

Data is a serializable wrapper for encrypted bytes with additional metadata in the Header.

func DecodeData

func DecodeData(b []byte) (Data, error)

DecodeData decodes a byte representation to Data. This provides a small abstraction in case we want to swap out the gob decoder for something else.

func GobDecodeData

func GobDecodeData(b []byte) (Data, error)

GobDecodeData deserializes a gob binary representation to Data.

func NewData

func NewData(h Header, data []byte) Data

NewData returns an Data initialized with a Header and encrypted data.

func (Data) Valid

func (e Data) Valid() error

Valid returns an error if the Data is not valid.

type Encryptor

type Encryptor interface {
	// ID returns the id of the secret used to encrypt the data.
	ID() string

	// Name returns the name of encryption cipher, keyLen length
	// and mode used to encrypt the data ("aes192-ctr").
	Name() string

	// Encrypt returns data encrypted with the secret.
	Encrypt(plaintext []byte) (ciphertext []byte, err error)

	// Decrypt returns data decrypted with the secret.
	Decrypt(ciphertext []byte) (plaintext []byte, err error)
}

Encryptor is the interface use to supply cipher implementations to the datastore.

type Header

type Header struct {
	Cipher string // e.g. "aes"
	KeyLen KeyLen // e.g. 128
	Mode   Mode   // e.g. "gcm"
	Salt   []byte
	IV     []byte
	Nonce  []byte
}

A Header describes an encryption block. It contains the cipher name, key length, mode used as well as the cipher key salt, iv or nonce.

func NewHeader

func NewHeader(cipher string, keyLen KeyLen, mode Mode, salt []byte, iv []byte, nonce []byte) (Header, error)

NewHeader create a new Header checking the length of the salt buffer against MinSaltLength. If the length of the salt buffer is less than MinSaltLength it returns an error.

func (*Header) Name

func (h *Header) Name() string

Name returns the name of the cipher in following format "[cipher][key length]-[mode]" e.g. "aes192-ctr".

func (Header) Valid

func (h Header) Valid() error

Valid returns an error if the Header is not valid.

type KeyLen

type KeyLen int

KeyLen is used to select 128, 192, or 256 bit keys.

func (KeyLen) String

func (k KeyLen) String() string

type ManagedSecret

type ManagedSecret struct {
	TextSecret
	// contains filtered or unexported fields
}

A ManagedSecret provides a simple plaintext secret alongside a unique id.

func NewManagedSecret

func NewManagedSecret(id, secret string) *ManagedSecret

NewManagedSecret creates a new ManagedSecret with a secret with its corresponding id.

func (ManagedSecret) ID

func (s ManagedSecret) ID() string

ID return the id of the secret for tracking, or rollover etc.

type Mode

type Mode string

Mode are the supported modes for a cipher.

func (Mode) String

func (m Mode) String() string

type Secret

type Secret interface {
	// ID return the id of the secret for tracking, or rollover etc.
	ID() string
	// Open returns a byte representation of the secret for encryption and decryption.
	Open() []byte
}

Secret is the interface that wraps a cipher keyLen and its id.

type SecureSecret

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

SecureSecret provides a unique id for a secret alongside an openSecret callback which returns a byte representation of the secret for encryption and decryption on Open. When SecureSecret calls openSecret it will pass a copy of itself as a Secret. This allows for remote loading of the secret based on its id, or using a secure in-memory storage solution for the secret like memguarded (https://github.com/n0rad/memguarded).

func NewSecureSecret

func NewSecureSecret(id string, openSecret func(Secret) []byte) *SecureSecret

NewSecureSecret creates a new SecureSecret with an id and an callback function which returns a byte representation of the secret for encryption and decryption.

func (SecureSecret) ID

func (s SecureSecret) ID() string

ID return the id of the secret for tracking, or rollover etc.

func (SecureSecret) Open

func (s SecureSecret) Open() []byte

Open returns a byte representation of the secret for encryption and decryption.

type TextSecret

type TextSecret string

A TextSecret provides a simple plaintext secret.

func (TextSecret) ID

func (s TextSecret) ID() string

ID return the id of the secret for tracking, or rollover etc.

func (TextSecret) Open

func (s TextSecret) Open() []byte

Open returns a byte representation of the secret for encryption and decryption.