entropy

README

github.com/jlowellwofford/entropy/pkg/entropy

Overview

This package provides an API that wraps all of the IOCTL calls on the /dev/(u)random devices. These IOCTLs require important functionality beyond just reading/writing /dev/(u)random. Of particular imporance, they allow for adding to and clearing the entropy count on the system.

The entropy count is intended to provide an estimate of how much information (in the Shannon sense) is stored in the entropy pool. The /dev/random device will only provide at maximum the number of bits in the entropy count.

Note: all entropy count values are in bits, not bytes.

The kernel makes no attempt to estimate the entropy of data. It's up to the user of the API to provide those estimates. That is why, e.g. the AddEntropy function, which adds bytes to the pool, requires the user to also provide the entropy count.

Intended use

This package and the associated command was originaly created to provide an easy interface for artificially injecting entropy into the kernel to accelerate entropy gathering when booting large numbers of VMs for test clusters. This pkg provides a generic interface that could be used to, e.g. create a goland version of programs like rng-trools or haveged.

See also

Command documentation README

Kernel source devices/char/random.c

Man page random(4)

Authors

• J. Lowell Wofford <lowell@lanl.gov

Documentation

Index

• Constants
• func AddEntropy(cnt int, buf []byte) error
• func AddToEntCnt(add int) error
• func ClearPool() error
• func GetEntCnt() (int, error)
• func ReseedCrng() error
• func ZapEntCnt() error

Constants

const (
	RNDGETENTCNT   = 0x80045200
	RNDADDTOENTCNT = 0x40045201
	RNDGETPOOL     = 0x80085202
	RNDADDENTROPY  = 0x40085203
	RNDZAPENTCNT   = 0x5204
	RNDCLEARPOOL   = 0x5206
	RNDRESEEDCRNG  = 0x5207
)

Functions

func AddEntropy

func AddEntropy(cnt int, buf []byte) error

AddEntropy will add the contents of `buf` to the entropy pool. The kernel takes these bytes and "mixes" tthem * using a CRC-like algorithm. Additionally, cnt is added to the entropy count (see `AddToEntCnt()`). * * This is like writing data to `/dev/(u)random`, then calling RNDADDTOENTCOUNT. * * AddEntropy is a wrapper around the RNDADDENTROPY IOCTL on `/dev/(u)random`.

func AddToEntCnt

func AddToEntCnt(add int) error

AddToEntCnt adds the specified integer to the entropy count. * * Note: this does not directly add to the value, but adds by an algorithm that asymptotically * approaches the pool size. See `devices/char/random.c` in the kernel source code for details. * * AddToEntCnt is a wrapper around the RNDADDTOENTCNT IOCTL on `/dev/(u)random`.

func ClearPool

func ClearPool() error

* ClearPool clears the entropy pool counters (i.e. the entropy count). Historically, this also cleared all of the * bytes in the entropy pool, but on modern kernels this is just an alias for ZapEntCnt. * * ClearPool is a wrapper around the RNDCLEARPOOL IOCTL on `/dev/(u)random`.

func GetEntCnt

func GetEntCnt() (int, error)

GetEntCnt returns the current count for the system. * * This is the same as reading the contents of `/proc/sys/kernel/random/entropy_avail`, but is accomplished through the RNDGETENTCNT IOCTL. * * GetEntCnt is a wrapper around the RNDGETENTCNT IOCTL on `/dev/(u)random`.

func ReseedCrng

func ReseedCrng() error

* ReseedCrng will re-seed the CRNG used to generate `/dev/urandom`. * * ReseedCrng is a wrapper around the RNDRESEEDCRNG IOCTL on `/dev/(u)random`

func ZapEntCnt

func ZapEntCnt() error

* ZapEntCnt clears the entropy pool counters (i.e the entropy count). This might be useful if, for instance, you * suspect your entropy pool is tainted or your entropy count has been artificially inflated. * * ZapEntCnt is a wrapper around the RNDZAPENTCNT IOCTL on `/dev/(u)random`.