From bc31a3df75a5e99f32ca711629825a65657639f0 Mon Sep 17 00:00:00 2001 From: "J. Lowell Wofford" Date: Fri, 4 Dec 2020 14:29:10 -0700 Subject: [PATCH] improve documentation; add copyright headers --- README.md | 6 ++++- cmd/entropy/entropy.go | 9 +++++++ pkg/entropy/README.md | 25 +++++++++++++++++ pkg/entropy/binary_amd64.go | 9 +++++++ pkg/entropy/binary_arm64.go | 9 +++++++ pkg/entropy/entropy.go | 46 ++++++++++++++++++++++++++++++++ pkg/entropy/entropy_linux.go | 9 +++++++ pkg/entropy/util/gen_constants.c | 10 +++++-- 8 files changed, 120 insertions(+), 3 deletions(-) create mode 100644 pkg/entropy/README.md diff --git a/README.md b/README.md index 98c9a7c..4e407c5 100644 --- a/README.md +++ b/README.md @@ -36,4 +36,8 @@ Commands: # Package -The `entropy` package provides a basic wrapper for all IOCTL functions provided by the kernel. \ No newline at end of file +The `entropy` package provides a basic wrapper for all IOCTL functions provided by the kernel. + +# Authors + +- J. Lowell Wofford \ No newline at end of file diff --git a/cmd/entropy/entropy.go b/cmd/entropy/entropy.go index 76b238e..f99bd75 100644 --- a/cmd/entropy/entropy.go +++ b/cmd/entropy/entropy.go @@ -1,3 +1,12 @@ +/* entropy.go: this provides a commandline enterface to linux entropy management + * + * Author: J. Lowell Wofford + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ + package main import ( diff --git a/pkg/entropy/README.md b/pkg/entropy/README.md new file mode 100644 index 0000000..c43a810 --- /dev/null +++ b/pkg/entropy/README.md @@ -0,0 +1,25 @@ +# 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 + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ + package entropy import "encoding/binary" diff --git a/pkg/entropy/binary_arm64.go b/pkg/entropy/binary_arm64.go index d5e31f9..7359308 100644 --- a/pkg/entropy/binary_arm64.go +++ b/pkg/entropy/binary_arm64.go @@ -1,3 +1,12 @@ +/* binary_arm64.go: sets the host byte order for arm64 + * + * Author: J. Lowell Wofford + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ + package entropy import "encoding/binary" diff --git a/pkg/entropy/entropy.go b/pkg/entropy/entropy.go index 0aa4165..13768b0 100644 --- a/pkg/entropy/entropy.go +++ b/pkg/entropy/entropy.go @@ -1,25 +1,71 @@ +/* entropy.go: package interface for Linux kernel entropy management + * + * Author: J. Lowell Wofford + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ + package entropy +/* 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 GetEntCnt() (int, error) { return getEntCnt() } +/* 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 AddToEntCnt(add int) error { return addToEntCnt(add) } +/* 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 AddEntropy(cnt int, buf []byte) error { return addEntropy(cnt, buf) } +/* + * 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`. + */ func ZapEntCnt() error { return zapEntCnt() } +/* + * 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 ClearPool() error { return clearPool() } +/* + * ReseedCrng will re-seed the CRNG used to generate `/dev/urandom`. + * + * ReseedCrng is a wrapper around the RNDRESEEDCRNG IOCTL on `/dev/(u)random` + */ func ReseedCrng() error { return reseedCrng() } diff --git a/pkg/entropy/entropy_linux.go b/pkg/entropy/entropy_linux.go index b9e9502..046c9d2 100644 --- a/pkg/entropy/entropy_linux.go +++ b/pkg/entropy/entropy_linux.go @@ -1,3 +1,12 @@ +/* entropy_linux.go + * + * Author: J. Lowell Wofford + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ + package entropy import ( diff --git a/pkg/entropy/util/gen_constants.c b/pkg/entropy/util/gen_constants.c index 64a8c37..c73e1b6 100644 --- a/pkg/entropy/util/gen_constants.c +++ b/pkg/entropy/util/gen_constants.c @@ -1,5 +1,11 @@ -// This simple program writes constants.go -// It uses the Linux headers to generate these contatns. +/* gen_constanc.c: this simple programe writes `constants_linux.go` based on available headers. + * + * Author: J. Lowell Wofford + * + * This software is open source software available under the BSD-3 license. + * Copyright (c) 2020, J. Lowell Wofford. + * See LICENSE file for details. + */ #include #include