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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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.
Types ¶
This section is empty.
Source Files
Directories