memguard

README

MemGuard

A library that handles sensitive values in memory.

---

This library is designed to allow you to easily handle sensitive values in memory. The main functionality is to lock and watch portions of memory and wipe them on exit, but there are some supplementary functions too.

Installation

This library can be retrieved with go get.

$ go get github.com/libeclipse/memguard

Documentation

Overview

Package memguard is designed to allow you to easily handle sensitive values in memory.

// Declare a protected slice and copy into it.
encryptionKey := memguard.Make(32)  // Similar to calling make([]byte, 32)
copy(encryptionKey, generateRandomBytes(32))

Please note that it is important to never use append() or to assign values directly. Only ever copy() values into protected slices.

b := memguard.Make(32)

copy(b, []byte("some secure value")) // Correct.

b = []byte("some secure value")            // WRONG
b = append(b, []byte("some secure value")) // WRONG

When you do not know the length of the data in advance, you may have to allocate first and then protect, even though this is not generally the best way of doing things. An example is accepting user input.

password := input() // Some arbitrary input function.
memguard.Protect(password)

Arrays can be protected too.

someArray := [32]byte
memguard.Protect(someArray[:])

When you're about to exit, call Cleanup() first. This will wipe and then unlock all protected data.

memguard.Cleanup()

In order to handle most exit cases, do the following:

// In the main function.
memguard.CatchInterrupt()
defer memguard.Cleanup()

// Anywhere you would terminate.
memguard.SafeExit(0) // 0 is the status code.

Index

• func CatchInterrupt()
• func Cleanup()
• func Make(length int, capacity ...int) (b []byte)
• func Protect(data []byte)
• func SafeExit(c int)
• func Wipe(b []byte)

Functions

func CatchInterrupt

func CatchInterrupt()

CatchInterrupt starts a goroutine that monitors for interrupt signals and calls Cleanup() before exiting.

func Cleanup

func Cleanup()

Cleanup instructs the goroutines to cleanup the memory they've been watching and waits for them to finish.

func Make

func Make(length int, capacity ...int) (b []byte)

Make creates a byte slice of specified length, but protects it before returning. You can also specify an optional capacity, just like with the native make() function. Note that the returned array is only properly protected up until its length, and not its capacity.

func Protect

func Protect(data []byte)

Protect spawns a goroutine that prevents the data from being swapped out to disk, and then waits around for the signal from Cleanup(). When this signal arrives, the goroutine zeroes out the memory that it was protecting, and then unlocks it before returning. Protect can be called multiple times with different pieces of data, but the caller should be aware that the underlying kernel may impose its own limits on the amount of memory that can be locked. For this reason, it is recommended to only call this function on small, highly sensitive structures that contain, for example, encryption keys. In the event of a limit being reached and attaining the lock fails, a warning will be written to stdout and the goroutine will still wipe the memory on exit.

func SafeExit

func SafeExit(c int)

SafeExit cleans up protected memory and then exits safely.

func Wipe

func Wipe(b []byte)

Wipe takes a byte slice and zeroes it out.