From 920faab30b3a151ed5ea6ebedc4fae4f3e0928dd Mon Sep 17 00:00:00 2001 From: "J. Lowell Wofford" Date: Fri, 4 Dec 2020 15:20:52 -0700 Subject: [PATCH] restructure for easier package importing --- README.md | 42 +++++----------- pkg/entropy/binary_be.go => binary_be.go | 0 pkg/entropy/binary_le.go => binary_le.go | 0 cmd/entropy/README.md | 49 +++++++++++++++++++ cmd/entropy/entropy.go | 2 +- .../constants_linux.go => constants_linux.go | 0 pkg/entropy/entropy.go => entropy.go | 0 .../entropy_linux.go => entropy_linux.go | 0 pkg/entropy/README.md | 25 ---------- {pkg/entropy/util => util}/gen_constants.c | 0 10 files changed, 63 insertions(+), 55 deletions(-) rename pkg/entropy/binary_be.go => binary_be.go (100%) rename pkg/entropy/binary_le.go => binary_le.go (100%) create mode 100644 cmd/entropy/README.md rename pkg/entropy/constants_linux.go => constants_linux.go (100%) rename pkg/entropy/entropy.go => entropy.go (100%) rename pkg/entropy/entropy_linux.go => entropy_linux.go (100%) delete mode 100644 pkg/entropy/README.md rename {pkg/entropy/util => util}/gen_constants.c (100%) diff --git a/README.md b/README.md index 4e407c5..4990572 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,27 @@ -# About +# github.com/jlowellwofford/entropy/pkg/entropy -Entropy is a simple go pkg and cmdline interface for manipulating entropy in the linux kernel. +# Overview -It achieves this by using the the IOCTL interface to /dev/(u)random. +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. -# Some basic theory +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. -The linux kernel simulates randomness by keeping a pool of data, estimating its information entropy, and generating data out of it using SHA hashes. +Note: all entropy count values are in bits, not bytes. -When information is added to the pool it gets "mixed" into the pool with a CRC-like algorithm; it doesn't actually add the raw data. +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. -Optionally, when information is added, the entropy count of the pool can be incrememnted. This isn't a literal add, but rather an asymptotic algorithm that approaches the pool size. +# Intended use -Information can be added to the pool by writing to `/dev/random` or `/dev/urandom`, but this will not increment the entropy count. This package/command provide an interface to the IOCTLs that provide extended userspace functionality for manipulating randomness. Of particular note, the `AddToEntCnt()` function adds bits to the entropy count and the `AddEntropy()` function adds bytes to the pool while also incrementing entropy bits. +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](https://github.com/nhorman/rng-tools) or [haveged](http://www.issihosts.com/haveged/). +# See also -# Command -The `entropy` command has the following usage information: +Command documentation [README](cmd/entropy/README.md) -``` -Usage: entropy [...] +Kernel source `devices/char/random.c` -Commands: - - get(entropy) - get the current system entropy. - addto(entcnt) - (superuser) Add bits to the current entropy count. - Note: this does not literally increase entropy count by . The kernel adds using an asymptotic algorithm. - See for details. - add(entropy) [] - (superuser) Add the contents of to entropy, incrementing entropy by the byte-length of the file. - The optional specifies the percentage of total data to count as Shannon entropy (default: 1, which is highly unlikely). - zap(entcnt) - (superuser) Clear the kernel entropy count. - clear(pool) - (superuser) Clear the entropy pool and counters (on modern linux, this just does zapentcnt). - reseed(crng) - (superuser) Reseed the CRNG. -``` - -# Package - -The `entropy` package provides a basic wrapper for all IOCTL functions provided by the kernel. +Man page `random(4)` # Authors -- J. Lowell Wofford \ No newline at end of file +- J. Lowell Wofford [...] + +Commands: + + get(entropy) - get the current system entropy. + addto(entcnt) - (superuser) Add bits to the current entropy count. + Note: this does not literally increase entropy count by . The kernel adds using an asymptotic algorithm. + See for details. + add(entropy) [] - (superuser) Add the contents of to entropy, incrementing entropy by the byte-length of the file. + The optional specifies the percentage of total data to count as Shannon entropy (default: 1, which is highly unlikely). + zap(entcnt) - (superuser) Clear the kernel entropy count. + clear(pool) - (superuser) Clear the entropy pool and counters (on modern linux, this just does zapentcnt). + reseed(crng) - (superuser) Reseed the CRNG. +``` + +# Package + +The `entropy` package provides a basic wrapper for all IOCTL functions provided by the kernel. See [README](../../README.md). + +# See also + +Kernel source `devices/char/random.c` + +Man page `random(4)` + +# Authors + +- J. Lowell Wofford \ No newline at end of file diff --git a/cmd/entropy/entropy.go b/cmd/entropy/entropy.go index f99bd75..05a8f75 100644 --- a/cmd/entropy/entropy.go +++ b/cmd/entropy/entropy.go @@ -15,7 +15,7 @@ import ( "os" "strconv" - "github.com/jlowellwofford/entropy/pkg/entropy" + "github.com/jlowellwofford/entropy" ) func usage() { diff --git a/pkg/entropy/constants_linux.go b/constants_linux.go similarity index 100% rename from pkg/entropy/constants_linux.go rename to constants_linux.go diff --git a/pkg/entropy/entropy.go b/entropy.go similarity index 100% rename from pkg/entropy/entropy.go rename to entropy.go diff --git a/pkg/entropy/entropy_linux.go b/entropy_linux.go similarity index 100% rename from pkg/entropy/entropy_linux.go rename to entropy_linux.go diff --git a/pkg/entropy/README.md b/pkg/entropy/README.md deleted file mode 100644 index c43a810..0000000 --- a/pkg/entropy/README.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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](https://github.com/nhorman/rng-tools) or [haveged](http://www.issihosts.com/haveged/). - -# See also - -Kernel source `devices/char/random.c` - -Man page `random(4)` - -# Authors - -- J. Lowell Wofford