Categorygithub.com/alvarolm/memguard
modulepackage
0.15.0
Repository: https://github.com/alvarolm/memguard.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
11
Dependents
0
Files
814 SLOC

# README

MemGuard

Easy and secure handling of sensitive memory, in pure Go.

This is a thread-safe package, designed to allow you to easily handle sensitive values in memory. It supports all major operating systems and is written in pure Go.

Features

  • Interference from the garbage-collector is blocked by using system-calls to manually allocate memory.
  • It is very difficult for another process to find or access sensitive memory as the data is sandwiched between guard-pages. This feature also acts as an immediate access alarm in case of buffer overflows.
  • Buffer overflows are further protected against using a random canary value. If this value changes, the process will panic.
  • We try our best to prevent the system from writing anything sensitive to the disk. The data is locked to prevent swapping, system core dumps can be disabled, and the kernel is advised (where possible) to never include the secure memory in dumps.
  • True kernel-level immutability is implemented. That means that if anything attempts to modify an immutable container, the kernel will throw an access violation and the process will terminate.
  • All sensitive data is wiped before the associated memory is released back to the operating system.
  • 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 Go's own garbage-collector to automatically destroy containers that have run out of scope.

Some of these features were inspired by libsodium, so credits to them.

Full documentation and a complete overview of the API can be found here.

Installation

Although we do recommend using a release, the simplest way to install the library is to go get it:

$ go get github.com/awnumar/memguard

If you would prefer a signed release that you can verify and manually compile yourself, download and extract the latest release. Then go ahead and run:

$ go install -v ./

The latest release is guaranteed to be cryptographically signed with my most recent PGP key, which can be found on keybase. To import it directly into GPG, run:

$ curl https://keybase.io/awn/pgp_keys.asc | gpg --import

We strongly encourage you to vendor your dependencies for a clean and reliable build. Go's dep makes this task relatively frictionless.

# Packages

No description provided by the author

# Functions

CatchInterrupt starts a goroutine that monitors for interrupt signals.
Concatenate takes two LockedBuffers and concatenates them.
DestroyAll calls Destroy on all LockedBuffers that have not already been destroyed.
DisableUnixCoreDumps disables core-dumps.
Duplicate takes a LockedBuffer and creates a new one with the same contents and mutability state as the original.
Equal compares the contents of two LockedBuffers in constant time.
NewImmutable creates a new, immutable LockedBuffer of a specified size.
NewImmutableFromBytes is identical to NewImmutable but for the fact that the created LockedBuffer is of the same length and has the same contents as a given slice.
NewImmutableRandom is identical to NewImmutable but for the fact that the created LockedBuffer is filled with cryptographically-secure pseudo-random bytes instead of zeroes.
NewMutable creates a new, mutable LockedBuffer of a specified length.
NewMutableFromBytes is identical to NewMutable but for the fact that the created LockedBuffer is of the same length and has the same contents as a given slice.
NewMutableRandom is identical to NewMutable but for the fact that the created LockedBuffer is filled with cryptographically-secure pseudo-random bytes instead of zeroes.
SafeExit exits the program with a specified exit-code, but calls DestroyAll first.
Split takes a LockedBuffer, splits it at a specified offset, and then returns the two newly created LockedBuffers.
Trim shortens a LockedBuffer according to the given specifications.
WipeBytes zeroes out a given byte slice.

# Variables

ErrDestroyed is returned when a function is called on a destroyed LockedBuffer.
ErrImmutable is returned when a function that needs to modify a LockedBuffer is given a LockedBuffer that is immutable.
ErrInvalidConversion is returned when attempting to get a slice of a LockedBuffer that is of an inappropriate size for that slice type.
ErrInvalidLength is returned when a LockedBuffer of smaller than one byte is requested.

# Structs

LockedBuffer is a structure that holds secure values.