libhavege(3)
NAME
libhavege, havege_create, havege_run, havege_rng, havege_destroy, havege_status, havege_status_dump, havege_version - haveged RNG
SYNOPSIS
#include <haveged/havege.h>
H_PARAMS params = {0};
h_status status;
char status_buf[512];
if (NULL==havege_version(HAVEGE_PREP_VERSION)) exit(1);
H_PTR handle = havege_create(¶ms);
havege_status(handle, &status);
havege_run(handle);
rc = havege_rng(handle, handle->io_buf, handle->i_readSz/sizeof(H_UINT));
havege_status_dump(handle, H_SD_TOPIC_BUILD, status_buf, sizeof(status_buf));
havege_destroy(handle);
DESCRIPTION
The libhavege library provides the haveged random number generator and it's associated tuning and testing facilities in a development sub- package. All haveged conditional build features are preserved and all haveged options not directly related to it's daemon or file system interfaces are available. This means that the same haveged tuning and testing components are present in the library with the equivalent controls provided by the haveged command line.
API METHODS
The libhavege library uses the opaque handle technique to manage it's required resources. Errors are returned in the "error" member of the handle. The havege_destroy() method should be called to dispose of any resources claimed by havege_create(). H_PTR havege_create(H_PARAMS *params); Create an anchor. Most members of the H_PARAMS input to this call correspond closely to haveged command line options (see haveged(8) for details). The caller should check for a non-null return value with a error value of H_NOERR. Any non-null return should be disposed of by a call to havege_destroy() to free any resources. Possible error values: H_NOERR, H_NOTESTSPEC, H_NOBUF, H_NOTESTMEM, H_NOINIT void havege_destroy(H_PTR hptr); Free all allocated anchor resources. If the multi-core option is used, this method should be called from a signal handler to prevent zombie processes. If called by the process that called haveged_create(), hptr will be freed when all child processes (if any) have terminated. If called by a child process, H_EXIT will be set and all children awakened to exit. int havege_rng(H_PTR hptr, H_UINT *buf, H_UINT sz); Read random bytes from an active anchor. The RNG must have been previously readied by a call to havege_run(). The read must take place within the allocated buffer, hptr->io_buf. The range specified is the number of H_UINT to read. If the multi-core option is used, this buffer is memory mapped between collectors. Possible error values: H_NOERR, H_NOTESRUN, H_NOPOST, H_NODONE, H_NORQST, H_NOCOMP, H_EXIT int havege_run(H_PTR hptr); Warm up the RNG and run the start-up tests. The operation succeeded if the error member of the handle is H_NOERR. A failed handle should be disposed of by a call to havege_destroy(). Possible error values: H_NOERR, H_NOCOLLECT, H_NOWALK, H_NOTESTMEM, H_NOTASK, H_NOTESTTOT, H_NOWAIT, H_NOTIMER, and any havege_rng() error. void havege_status(H_PTR hptr, H_STATUS hsts); Fills in the h_status structure with read-only information collected from the package build, run-time tuning, and test components. int havege_status_dump(H_PTR hptr, H_SD_TOPIC topic, char *buf, size_t len); Calls havege_status() and formats standard presentations of havege status in the supplied buffer. The standard formats are: H_SD_TOPIC_BUILD ver: %s; arch: %s; vend: %s; build: (%s); collect: %dK H_SD_TOPIC_TUNE cpu: (%s); data: %dK (%s); inst: %dK (%s); idx: %d/%d; sz: %d/%d H_SD_TOPIC_TEST [tot tests(%s): A:%d/%d B: %d/%d;][continuous tests(%s): A:%d/%d B: %d/%d;][last entropy estimate %g] H_SD_TOPIC_SUM fills: %d, generated: %.4g %c bytes const char *havege_version(const char *version); Return/check library prep version. The prep version is the package version used to build the library. A null argument returns the prep version unconditionally. Using the definition of the prep string in havege.h as input returns the prep version if the header file is compatible with the library, or NULL if it is not. Intended to be called before attempting any initialization.
NOTES
The sizes of the processor level 1 instruction and data caches are used
to tune the HAVEGE algorithm for maximum sensitivity. If these sizes
not specified, haveged will attempt to determine the sizes dynamically
from the Linux sysfs and/or cpuid instruction with a fallback to a
compiled default if no better information is not available.
The haveged RNG includes a run time test facility based upon the test
suite defined in the AIS-31 specification from the The German Federal
Office for Information Security (Bundesamt fr Sicherheit in der
Informationstechnik). The test suite consists of 11 statistical tests
packaged into two test suites ("A" and "B"). The tests can be run at
initialization (a.k.a. a "tot" test), or continuously to monitor all
output. Failure of a suite will abort operation unless the behavior is
explicitly waived in the test setup options.
Procedure A contains 6 test procedures designed to ensure statistically
inconspicuous behavior. The first test, "test0", checks the
disjointedness of 65k six-bit strings. The remainder of the procedure
consists of 257 repetitions of the FIPS140-1 tests, "test1" through
"test4", and an auto-correlation test, "test5". The fixed size of the
Procedure A input makes it ideal for continuous use, but the procedure
is slow and resource intensive. In particular, test5 is several orders
of magnitude slower than any other individual AIS test. As an
alternative for those who cannot tolerate this load, procedure A
variants A<n> are provided that execute all included tests but execute
test5 only every 2^n repetitions. Even with this accommodation,
procedure A is much slower than procedure B.
Procedure B contains 5 tests, "test6a", "test6b', "test7a", "test7b",
and "test8". The first 4 tests verify the expected frequencies for
samples 100,000 one-step, two-step, three-step, and four-step bit
transitions. The last test provides an empirical entropy estimate of
the input. The input required to complete these tests is variable,
resulting in an ever-shifting bit alignment that guards against
buffering artifacts.
Each test procedure requires more than 1MB of data. Test input is
managed by a bit index into the collection buffer. An independent index
manages where integer output is taken from the same buffer. A buffer
fill is triggered when the output index indicates all data has been
extracted from the buffer. Online testing takes place after the buffer
has been refilled but before the output index update allows output to
resume. If any online test fails while processing the buffer, the
buffer will be refilled and reprocessed until any retry is complete and
the buffer contains no failed online tests or the online test procedure
has failed and the RNG is considered broken.
It is recommend to run both AIS test procedures at start-up to ensure
the RNG is properly initialized. If resources are in short supply,
omitting procedure A will save memory and time, with little risk in
circumstances where output is mixed with other sources in /dev/random
or other csprng. Continuous testing is also recommended where the
throughput penalty is acceptable. One recent assessment of testing
throughput costs is shown below.
haveged -n0 -oc | pv > /dev/null 400MiB/s
haveged -n0 -ocb | pv > /dev/null 70MiB/s
haveged -n0 -oca8b | pv > /dev/null 13MiB/s
haveged -n0 -oca8 | pv > /dev/null 8MiB/s
haveged -n0 -oca | pv > /dev/null 100kiB/s
Continuous testing also exposes another possible pitfall. Even an ideal
RNG has a 10e-4 chance of failing either test procedure. The strict
retry policy of AIS-31 is designed to guarantee an ideal RNG will
"almost never" fail a test procedure. A single retry is mandated only
to recover from a previous attempt that experienced a single individual
test failure. The haveged implementation logs all retries and
terminates on test procedure failures unless the procedure has been
flagged as advisory by the "w" argument (see --onlinetest in haveged(8)
). Little evidence of the retry mechanism is seen unless large data
sets are processed. Procedure A is too slow to be practical in these
situations, so procedure B has been the best studied. Retries are
observed at the approximate rate of 0.7-0.8 failures/GB, mostly in the
test7 multi-step transition checks.
The probability that procedureB will fail two times in a row (in which
case the program will be terminated unless w option was specified) is
4e-7 which is expected to happen at an approximate rate of once per
3,000 TB. When producing large amounts of data in order of TBs it's
recommended to use -w option to make sure that program will not
prematurely terminate because of a failed retry and carefully examine
the stderr output for any problems.
FILES
Tuning information may be extracted from the following virtual file
paths if tuning is required and the path exists.
/proc/cpuinfo
/proc/self/status
/sys/devices/system/cpu/online
/sys/devices/system/cpu/cpu%d/cache/index%d/level
DIAGNOSTICS
To enable diagnostic output, supply a msg_out callback when creating
the handle. All possible errors are enumerated in havege.h and
reproduced here for reference.
01 H_NOHANDLE
No memory for handle
02 H_NOBUF
Output buffer allocation failed
03 H_NOINIT
Semaphore init failed
04 H_NOCOLLECT
Collector allocation failed
05 H_NOWALK
Walk buffer allocation failed
06 H_NOTESTSPEC
Invalid test specification
07 H_NOTESTINIT
Test setup failed
08 H_NOTESTMEM
Unable to allocate test memory
09 H_NOTESTTOT
Power on (i.e. 'tot') test failed
10 H_NOTESTRUN
Continuous test failed
11 H_NOCORES
Too many cores specified
12 H_NOTASK
Unable to create child task
13 H_NOWAIT
sem_wait failed
14 H_NOPOST
sem_post failed
15 H_NODONE
sem_post done failed
16 H_NORQST
sem_post request failed
17 H_NOCOMP
wait for completion failed
18 H_EXIT
Exit signal
19 H_NOTIMER
Timer failed
EXAMPLE
The following minimal program writes the contents of 16 collection
buffers of random data to stdout with continuous testing.
#include <stdio.h>
#include <haveged/havege.h>
int main(void)
{
H_PTR havege_state;
H_PARAMS havege_parameters = {0};
int i, rc;
if (NULL==havege_version(HAVEGE_PREP_VERSION)) {
fprintf(stderr, "Incompatible library %s\n", havege_version(NULL));
return 1;
}
havege_parameters.testSpec="ta8bcb";
havege_state = havege_create(&havege_parameters);
rc = havege_state==NULL? H_NOHANDLE : havege_state->error;
if (H_NOERR==rc) {
if (0==havege_run(havege_state)) {
H_UINT *buf = havege_state->io_buf;
int size = havege_state->i_readSz /sizeof(H_UINT);
char info[256];
for(i=0;i<16;i++) {
rc = havege_rng(havege_state, buf, size);
if (rc != size) {
fprintf(stderr, "RNG read failed %d\n", havege_state->error);
break;
}
rc = fwrite(buf, 1, size*sizeof(H_UINT), stdout);
if ( rc < size ) {
fprintf(stderr, "Write failed\n");
break;
}
}
i = havege_status_dump(havege_state, H_SD_TOPIC_TEST, info, sizeof(info));
info[i++] = '\n';
havege_status_dump(havege_state, H_SD_TOPIC_SUM, info+i, sizeof(info)-i);
fprintf(stderr, "%s\n", info);
}
else fprintf(stderr, "Initialize failed %d\n", havege_state->error);
havege_destroy(havege_state);
}
else fprintf(stderr, "Create failed %d\n", rc);
return rc;
}
Defaults are provided for all inputs to havege_create() as documented
in havege.h. In this case for example, (16*4kb=65kb) will be written to
stdout because the default size for i_readsz in 4kb.
SEE ALSO
haveged(8)
REFERENCES
haveged(8) references provides a basic reading list. The following links are suggested as sources for further exploration. The origins of the HAVEGE concept can be found at: http://www.irisa.fr/caps/projects/hipsor/ Tuning concepts inspired by (the complexity) at: http://www.open-mpi.org/projects/hwloc/ Reference documentation for the AIS-31 test suite can be found at: https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Zertifizierung/Interpretationen/AIS_31_Functionality_classes_for_random_number_generators_e.pdf?__blob=publicationFile Implementation and design information available at: http://www.issihosts.com/haveged/
AUTHORS
Gary Wuertz <gary@issiweb.com> and Jirka Hladky <hladky jiri AT gmail DOT com>
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
