core

package
Version: v0.22.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 20, 2020 License: Apache-2.0 Imports: 12 Imported by: 7

Documentation

Index

Constants

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

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

Variables

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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 added in v0.20.0

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
	// 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 added in v0.18.0

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 added in v0.20.1

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 added in v0.18.0

func (b *Buffer) Mutable() bool

Mutable returns true if the buffer is mutable.

func (*Buffer) Scramble added in v0.22.2

func (b *Buffer) Scramble()

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

type Coffer

type Coffer struct {
	sync.RWMutex
	// 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()

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

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL