memguard: Index | Files

package core

import ""


Package Files

auxiliary.go buffer.go coffer.go crypto.go enclave.go exit.go init.go


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

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


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")

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.

func Copy Uses

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 Uses

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 Uses

func EnclaveSize(e *Enclave) int

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

func Encrypt Uses

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

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

func Equal Uses

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 Uses

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 Uses

func Hash(b []byte) []byte

Hash implements a cryptographic hash function using Blake2b.

func Move Uses

func Move(dst, src []byte)

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

func Panic Uses

func Panic(v interface{})

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

func Purge Uses

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 Uses

func Scramble(buf []byte)

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

func Wipe Uses

func Wipe(buf []byte)

Wipe takes a buffer and wipes it with zeroes.

type Buffer Uses

type Buffer struct {
    sync.RWMutex // Local mutex lock
    // 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 Uses

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

NewBuffer is a raw constructor for the Buffer object.

func Open Uses

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 Uses

func (b *Buffer) Alive() bool

Alive returns true if the buffer has not been destroyed.

func (*Buffer) Data Uses

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

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

func (*Buffer) Destroy Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (b *Buffer) Mutable() bool

Mutable returns true if the buffer is mutable.

type Coffer Uses

type Coffer struct {
    // contains filtered or unexported fields

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

func NewCoffer Uses

func NewCoffer() *Coffer

NewCoffer is a raw constructor for the *Coffer object.

func (*Coffer) Destroy Uses

func (s *Coffer) Destroy()

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 Uses

func (s *Coffer) Destroyed() bool

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

func (*Coffer) Initialise Uses

func (s *Coffer) Initialise() error

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

func (*Coffer) Rekey Uses

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 Uses

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 Uses

type Enclave struct {
    // contains filtered or unexported fields

Enclave is a sealed and encrypted container for sensitive data.

func NewEnclave Uses

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 Uses

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.

Package core imports 12 packages (graph) and is imported by 4 packages. Updated 2019-11-09. Refresh now. Tools for package owners.