# README
MemGuard
Software enclave for storage of sensitive information in memory.
This package attempts to reduce the likelihood of sensitive data being exposed when in memory. It aims to support all major operating systems and is written in pure Go.
Features
- Sensitive data is encrypted and authenticated in memory with XSalsa20Poly1305. The scheme used also defends against cold-boot attacks.
- Memory allocation bypasses the language runtime by using system calls to query the kernel for resources directly. This avoids interference from the garbage-collector.
- Buffers that store plaintext data are fortified with guard pages and canary values to detect spurious accesses and overflows.
- Effort is taken to prevent sensitive data from touching the disk. This includes locking memory to prevent swapping and handling core dumps.
- Kernel-level immutability is implemented so that attempted modification of protected regions results in an access violation.
- Multiple endpoints provide session purging and safe termination capabilities as well as signal handling to prevent remnant data being left behind.
- Side-channel attacks are mitigated against by making sure that the copying and comparison of data is done in constant-time.
- Accidental memory leaks are mitigated against by harnessing the garbage-collector to automatically destroy containers that have become unreachable.
Some features were inspired by libsodium, so credits to them.
Full documentation and a complete overview of the API can be found here. Interesting and useful code samples can be found within the examples subpackage.
Installation
$ go get github.com/awnumar/memguard
API is experimental and may have unstable changes. You should pin a version. [modules]
Contributing
- Submitting program samples to
./examples. - Reporting bugs, vulnerabilities, and any difficulties in using the API.
- Writing useful security and crypto libraries that utilise memguard.
- Implementing kernel-specific/cpu-specific protections.
- Submitting performance improvements.
Issues are for reporting bugs and for discussion on proposals. Pull requests should be made against master.
# Functions
CatchInterrupt is a wrapper around CatchSignal that makes it easy to safely handle receiving interrupt signals.
CatchSignal assigns a given function to be run in the event of a signal being received by the process.
NewBuffer creates a mutable data container of the specified size.
NewBufferFromBytes constructs an immutable buffer from a byte slice.
NewBufferFromEntireReader reads from an io.Reader into an immutable buffer.
NewBufferFromReader reads some number of bytes from an io.Reader into an immutable LockedBuffer.
NewBufferFromReaderUntil constructs an immutable buffer containing data sourced from an io.Reader object.
NewBufferRandom constructs an immutable buffer filled with cryptographically-secure random bytes.
NewEnclave seals up some data into an encrypted enclave object.
NewEnclaveRandom generates and seals arbitrary amounts of cryptographically-secure random bytes into an encrypted enclave object.
NewStream initialises a new empty Stream object.
Purge resets the session key to a fresh value and destroys all existing LockedBuffers.
SafeExit destroys everything sensitive before exiting with a specified status code.
SafePanic wipes all it can before calling panic(v).
ScrambleBytes overwrites an arbitrary buffer with cryptographically-secure random bytes.
WipeBytes overwrites an arbitrary buffer with zeroes.
# Variables
StreamChunkSize is the maximum amount of data that is locked into memory at a time.
# Structs
Enclave is a sealed and encrypted container for sensitive data.
LockedBuffer is a structure that holds raw sensitive data.
Stream is an in-memory encrypted container implementing the reader and writer interfaces.