core

Documentation

Index

• Constants
• Variables
• func Copy(dst, src []byte)
• func Decrypt(ciphertext, key []byte, output []byte) (int, error)
• func EnclaveSize(e *Enclave) int
• func Encrypt(plaintext, key []byte) ([]byte, error)
• func Equal(x, y []byte) bool
• func Exit(c int)
• func Hash(b []byte) []byte
• func Move(dst, src []byte)
• func Panic(v interface{})
• func Purge()
• func Scramble(buf []byte) error
• func Wipe(buf []byte)
• type Buffer
  • func NewBuffer(size int) (*Buffer, error)
  • func Open(e *Enclave) (*Buffer, error)
  • func (b *Buffer) Alive() bool
  • func (b *Buffer) Data() []byte
  • func (b *Buffer) Destroy()
  • func (b *Buffer) Freeze()
  • func (b *Buffer) Inner() []byte
  • func (b *Buffer) Melt()
  • func (b *Buffer) Mutable() bool
  • func (b *Buffer) Scramble()
• type Coffer
  • func NewCoffer() *Coffer
  • func (s *Coffer) Destroy() error
  • func (s *Coffer) Destroyed() bool
  • func (s *Coffer) Init() error
  • func (s *Coffer) Rekey() error
  • func (s *Coffer) View() (*Buffer, error)
• type Enclave
  • func NewEnclave(buf []byte) (*Enclave, error)
  • func Seal(b *Buffer) (*Enclave, error)

Constants

const Overhead int = secretbox.Overhead + 24 // auth + nonce

Overhead is the size by which the ciphertext exceeds the plaintext.

Variables

var ErrBufferExpired = errors.New("<memguard::core::ErrBufferExpired> buffer has been purged from memory and can no longer be used")

ErrBufferExpired is returned when attempting to perform an operation on or with a buffer that has been destroyed.

var ErrBufferTooSmall = errors.New("<memguard::core::ErrBufferTooSmall> the given buffer is too small to hold the plaintext")

ErrBufferTooSmall is returned when the decryption function, Open, is given an output buffer that is too small to hold the plaintext. In practice the plaintext will be Overhead bytes smaller than the ciphertext returned by the encryption function, Seal.

var ErrCofferExpired = errors.New("<memguard::core::ErrCofferExpired> attempted usage of destroyed key object")

ErrCofferExpired is returned when a function attempts to perform an operation using a secure key container that has been wiped and destroyed.

var ErrDecryptionFailed = errors.New("<memguard::core::ErrDecryptionFailed> decryption failed: key is wrong or ciphertext is corrupt")

ErrDecryptionFailed is returned when the attempted decryption fails. This can occur if the given key is incorrect or if the ciphertext is invalid.

var ErrInvalidKeyLength = errors.New("<memguard::core::ErrInvalidKeyLength> key must be exactly 32 bytes")

ErrInvalidKeyLength is returned when attempting to encrypt or decrypt with a key that is not exactly 32 bytes in size.

var ErrNullBuffer = errors.New("<memguard::core::ErrNullBuffer> buffer size must be greater than zero")

ErrNullBuffer is returned when attempting to construct a buffer of size less than one.

var ErrNullEnclave = errors.New("<memguard::core::ErrNullEnclave> enclave size must be greater than zero")

ErrNullEnclave is returned when attempting to construct an enclave of size less than one.

Functions

func Copy

func Copy(dst, src []byte)

Copy is identical to Go's builtin copy function except the copying is done in constant time. This is to mitigate against side-channel attacks.

func Decrypt

func Decrypt(ciphertext, key []byte, output []byte) (int, error)

Decrypt decrypts a given ciphertext with a given 32 byte key and writes the result to the start of a given buffer.

The buffer must be large enough to contain the decrypted data. This is in practice Overhead bytes less than the length of the ciphertext returned by the Seal function above. This value is the size of the nonce plus the size of the Poly1305 authenticator.

The size of the decrypted data is returned.

func EnclaveSize

func EnclaveSize(e *Enclave) int

EnclaveSize returns the number of bytes of plaintext data stored inside an Enclave.

func Encrypt

func Encrypt(plaintext, key []byte) ([]byte, error)

Encrypt takes a plaintext message and a 32 byte key and returns an authenticated ciphertext.

func Equal

func Equal(x, y []byte) bool

Equal does a constant-time comparison of two byte slices. This is to mitigate against side-channel attacks.

func Exit

func Exit(c int)

Exit terminates the process with a specified exit code but securely wipes and cleans up sensitive data before doing so.

func Hash

func Hash(b []byte) []byte

Hash implements a cryptographic hash function using Blake2b.

func Move

func Move(dst, src []byte)

Move is identical to Copy except it wipes the source buffer after the copy operation is executed.

func Panic

func Panic(v interface{})

Panic is identical to the builtin panic except it purges the session before calling panic.

func Purge

func Purge()

Purge wipes all sensitive data and keys before reinitialising the session with a fresh encryption key and secure values. Subsequent library operations will use these fresh values and the old data is assumed to be practically unrecoverable.

The creation of new Enclave objects should wait for this function to return since subsequent Enclave objects will use the newly created key.

This function should be called before the program terminates, or else the provided Exit or Panic functions should be used to terminate.

func Scramble

func Scramble(buf []byte) error

Scramble fills a given buffer with cryptographically-secure random bytes.

func Wipe

func Wipe(buf []byte)

Wipe takes a buffer and wipes it with zeroes.

Types

type Buffer

type Buffer struct {
	sync.RWMutex // Local mutex lock // TODO: this does not protect 'data' field
	// contains filtered or unexported fields
}

Buffer is a structure that holds raw sensitive data.

The number of Buffers that can exist at one time is limited by how much memory your system's kernel allows each process to mlock/VirtualLock. Therefore you should call DestroyBuffer on Buffers that you no longer need, ideally defering a Destroy call after creating a new one.

func NewBuffer

func NewBuffer(size int) (*Buffer, error)

NewBuffer is a raw constructor for the Buffer object.

func Open

func Open(e *Enclave) (*Buffer, error)

Open decrypts an Enclave and puts the contents into a Buffer object. The given Enclave is left untouched and may be reused.

The Buffer object should be destroyed after the contents are no longer needed.

func (*Buffer) Alive

func (b *Buffer) Alive() bool

Alive returns true if the buffer has not been destroyed.

func (*Buffer) Data

func (b *Buffer) Data() []byte

Data returns a byte slice representing the memory region containing the data.

func (*Buffer) Destroy

func (b *Buffer) Destroy()

Destroy performs some security checks, securely wipes the contents of, and then releases a Buffer's memory back to the OS. If a security check fails, the process will attempt to wipe all it can before safely panicking.

If the Buffer has already been destroyed, the function does nothing and returns nil.

func (*Buffer) Freeze

func (b *Buffer) Freeze()

Freeze makes the underlying memory of a given buffer immutable. This will do nothing if the Buffer has been destroyed.

func (*Buffer) Inner

func (b *Buffer) Inner() []byte

Inner returns a byte slice representing the entire inner memory pages. This should NOT be used unless you have a specific need.

func (*Buffer) Melt

func (b *Buffer) Melt()

Melt makes the underlying memory of a given buffer mutable. This will do nothing if the Buffer has been destroyed.

func (*Buffer) Mutable

func (b *Buffer) Mutable() bool

Mutable returns true if the buffer is mutable.

func (*Buffer) Scramble

func (b *Buffer) Scramble()

Scramble attempts to overwrite the data with cryptographically-secure random bytes.

type Coffer

type Coffer struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Coffer is a specialized container for securing highly-sensitive, 32 byte values.

func NewCoffer

func NewCoffer() *Coffer

NewCoffer is a raw constructor for the *Coffer object.

func (*Coffer) Destroy

func (s *Coffer) Destroy() error

Destroy wipes and cleans up all memory related to a Coffer object. Once this method has been called, the Coffer can no longer be used and a new one should be created instead.

func (*Coffer) Destroyed

func (s *Coffer) Destroyed() bool

Destroyed returns a boolean value indicating if a Coffer has been destroyed.

func (*Coffer) Init

func (s *Coffer) Init() error

Init is used to reset the value stored inside a Coffer to a new random 32 byte value, overwriting the old.

func (*Coffer) Rekey

func (s *Coffer) Rekey() error

Rekey is used to re-key a Coffer. Ideally this should be done at short, regular intervals.

func (*Coffer) View

func (s *Coffer) View() (*Buffer, error)

View returns a snapshot of the contents of a Coffer inside a Buffer. As usual the Buffer should be destroyed as soon as possible after use by calling the Destroy method.

type Enclave

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

Enclave is a sealed and encrypted container for sensitive data.

func NewEnclave

func NewEnclave(buf []byte) (*Enclave, error)

NewEnclave is a raw constructor for the Enclave object. The given buffer is wiped after the enclave is created.

func Seal

func Seal(b *Buffer) (*Enclave, error)

Seal consumes a given Buffer object and returns its data secured and encrypted inside an Enclave. The given Buffer is destroyed after the Enclave is created.