/usr/include/haveged/havege.h is in libhavege-dev 1.7c-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 | /**
** Simple entropy harvester based upon the havege RNG
**
** Copyright 2009-2013 Gary Wuertz gary@issiweb.com
** Copyright 2011-2012 BenEleventh Consulting manolson@beneleventh.com
**
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation, either version 3 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef HAVEGE_H
#define HAVEGE_H
#include <stdint.h>
/**
* Basic types
*/
#define H_UINT uint32_t
#define H_UINT8 uint8_t
/**
* Optional metering call-back. Called with event=0 at start of collection buffer fill.
* Called with event=1 at end of collection buffer fill. The nCollect parameter indicates
* the calling process if multiple collection processes are enabled. Use a value of 0
* to disable metering.
*/
typedef void (*pMeter)(H_UINT nCollect, H_UINT event);
/**
* Optional message display call-back. This printf style method is used for all diagnostic
* output including havege_status(). Use a value of 0 to disable output.
*/
typedef void (*pMsg)(const char *format, ...);
/**
* Injection call-back for RAW diagnostics. Use a value of 0 to disable diagnostic. Ignored
* except for diaqnotic builds.
*/
typedef int (*pRawIn)(volatile H_UINT *pData, H_UINT szData);
/**
* options for H_PARAMS below. Lower byte transferred from verbose settings
* upper byte set by diagnositic run options
*/
#define H_VERBOSE 0x001 /* Show config info */
#define H_DEBUG_OLT 0x002 /* Show detailed test info */
#define H_DEBUG_TIME 0x004 /* Show collection times */
#define H_DEBUG_LOOP 0x008 /* Show loop parameters */
#define H_DEBUG_COMPILE 0x010 /* Show assembly info */
#define H_DEBUG_RAW_OUT 0x100 /* diagnostic output */
#define H_DEBUG_RAW_IN 0x200 /* diagnostic input */
#define H_DEBUG_TEST_IN 0x400 /* input test data */
/**
* Initialization parameters. Use non-zero values to override default values.
* Notes:
*
* 1) Correspondence between provided value and value of H_PTR members are:
* ioSz <==> i_readSz, collectSize <==> i_collectSz, nCores <==> n_cores,
* options <==> havege_opts
* 2) The icacheSize and dcacheSize override cache sizes. Both are specified in KB.
* Either may be specified to override the tuning value. If both are provided,
* tuning code is bypassed. The fallback tuning values can be overridden
* by defining GENERIC_DCACHE and GENERIC_ICACHE (16 will be used if not
* otherwise defined)
* 3) ioSz is specified in bytes. collectSize sizes is specified as number
* of H_UINT.
* 4) null callback values suppress the function.
* 5) sysFs default is '/sys', procFs default is '/proc'.
* 6) testSpec same as haveged option "[t<x>][c<x>] x=[a[n][w]][b[w]]". If
* not specified the default is "ta8b" - i.e. run the tot tests
*/
typedef struct {
H_UINT ioSz; /* size of write buffer */
H_UINT collectSize; /* size of collection buffer */
H_UINT icacheSize; /* Instruction cache size */
H_UINT dcacheSize; /* Data cache size */
H_UINT options; /* Other options */
H_UINT nCores; /* If multi-core */
pMeter metering; /* meterming method */
pMsg msg_out; /* output display method */
pRawIn injection; /* injection method */
char *procFs; /* proc mount point override */
char *sysFs; /* sys mount point override */
char *testSpec; /* test specification */
} H_PARAMS;
/**
* Status codes used in the error member of h_anchor
*/
typedef enum {
H_NOERR, /* 00 No error */
H_NOHANDLE, /* 01 No memory for handle */
H_NOBUF, /* 02 Output buffer allocation failed */
H_NOINIT, /* 03 semaphore init failed */
H_NOCOLLECT, /* 04 H_COLLECT allocation failed */
H_NOWALK, /* 05 Walk buffer allocation failed */
H_NOTESTSPEC, /* 06 invalid test specification */
H_NOTESTINIT, /* 07 test setup failed */
H_NOTESTMEM, /* 08 Unable to allocate test memory */
H_NOTESTTOT, /* 09 tot test failed */
H_NOTESTRUN, /* 10 production test failed */
H_NOCORES, /* 11 too many cores specified */
H_NOTASK, /* 12 Unable to create child task */
H_NOWAIT, /* 13 sem_wait failed */
H_NOPOST, /* 14 sem_post failed */
H_NODONE, /* 15 sem_post done failed */
H_NORQST, /* 16 sem_post request failed */
H_NOCOMP, /* 17 wait for completion failed */
H_EXIT /* 18 Exit signal */
} H_ERR;
/**
* Keep compiler honest
*/
typedef volatile void *H_VOL;
/**
* Anchor for the RNG. Should be read only at devel level and above.
*/
typedef struct h_anchor {
H_UINT *io_buf; /* output buffer */
char *arch; /* "x86","sparc","ppc","ia64",etc */
void *cpu; /* information on the cpu */
void *instCache; /* instruction cache info */
void *dataCache; /* data cache info */
pMsg print_msg; /* output display method */
pMeter metering; /* metering method */
pRawIn inject; /* Injection diagnostic only */
H_VOL collector; /* single thread collector */
H_VOL threads; /* multi thread collectors */
void *testData; /* online test data */
void *tuneData; /* tuning data */
H_UINT error; /* H_ERR enum for status */
H_UINT havege_opts; /* option flags */
H_UINT i_maxidx; /* maximum instruction loop index */
H_UINT i_maxsz; /* maximum code size */
H_UINT i_idx; /* code index used */
H_UINT i_sz; /* code size used */
H_UINT i_collectSz; /* size of collection buffer */
H_UINT i_readSz; /* size of read buffer (bytes) */
H_UINT m_sz; /* size of thread ipc area (bytes) */
H_UINT n_cores; /* number of cores */
H_UINT n_fills; /* number of buffer fills */
} *H_PTR;
/**
* Fail/Success counters for tot and production tests.
*/
typedef enum {
H_OLT_TOT_A_F, /* tot Procedure A failed */
H_OLT_TOT_A_P, /* tot Procedure A passed */
H_OLT_TOT_B_F, /* tot Procedure B failed */
H_OLT_TOT_B_P, /* tot Procedure B passed */
H_OLT_PROD_A_F, /* prod Procedure A failed */
H_OLT_PROD_A_P, /* prod Procedure A passed */
H_OLT_PROD_B_F, /* prod Procedure B failed */
H_OLT_PROD_B_P /* prod Procedure B passed */
} H_OLT_METERS;
/**
* Structure used to query RNG anchor settings for information not exposed by
* H_PTR. List formats are strings with one or more tokens separated by space.
* Sources lists show how tuning parameters are derived. D is a build default,
* P is a run time override, items V* come from linux virtual file system,
* other items trace various cpuid sources. Tuning is skipped if both cache
* sizes have 'P' sources.
*
* Notes:
*
* 1) Build: package version of source
* 2) Build options list: [C][M][T] C=clock_gettime, M=multi-core,
* T=online-test
* 3) Tuning source lists: D=default, P=parameter, C=cpuid present,
* H=hyperthreading, A=AMD cpuid, A5=AMD fn5, A6=AMD fn6, A8=AMD fn8
* L2=Intel has leaf2, L4=Intel has leaf4, B=Intel leaf b,
* 4=intel leaf4, V=virtual file system available
* VS=/sys/devices/system/cpu/cpu%d/cache/index<n>/level,
* VO=/sys/devices/system/cpu/online, VI=/proc/cpuinfo
* VC=/sys/devices/system/cpu
* 4) test spec [A[1..8]][B], see H_PARAMS above.
* 5) zero unless tests are enabled
* 6) Last Coron's entropy estimate from Procedure B, test 8
*/
typedef struct h_status {
const char *version; /* Package version [1] */
const char *buildOptions; /* Options [2] */
const char *vendor; /* cpuid machines only */
const char *cpuSources; /* Tuning sources list [3] */
const char *i_cacheSources; /* Tuning sources list [3] */
const char *d_cacheSources; /* Tuning sources list [3] */
const char *tot_tests; /* tot test spec [4] */
const char *prod_tests; /* prod test spec [4] */
H_UINT i_cache; /* size of L1 instruction cache KB */
H_UINT d_cache; /* size of L1 data cache KB */
H_UINT n_tests[H_OLT_PROD_B_P+1]; /* test statistics [5] */
double last_test8; /* last test8 result [6] */
} *H_STATUS;
/**
* Standard presentation formats for havege_status_dump.
*/
typedef enum {
H_SD_TOPIC_BUILD,
/* ver: %s; arch: %s; vend: %s; opts: (%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 */
} H_SD_TOPIC;
/**
* Public prototypes. Library users note that "havege_*" is reserved for library
* public functions. Note that the multi-core option is experimental and must
* enabled in the build.
*/
/**
* Create an anchor. 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
*/
H_PTR havege_create(H_PARAMS *params);
/**
* This method frees 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.
*/
void havege_destroy(H_PTR hptr);
/**
* Read random bytes from an active anchor. Note that the read must take place
* within the allocated buffer, hptr->io_buf, and the range is specified
* in 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_rng(H_PTR hptr, H_UINT *buf, H_UINT sz);
/**
* This method starts the anchor RNG. The operation suceeded 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,
* any havege_rng error
*/
int havege_run(H_PTR hptr);
/**
* The method fills in the h_status structure with read-only information
* collected from the package build, run-time tuning, and test components.
*/
void havege_status(H_PTR hptr, H_STATUS hsts);
/**
* Standard presentations of havege status. See topic enum above for formats.
*/
int havege_status_dump(H_PTR hptr, H_SD_TOPIC topic, char *buf, size_t len);
#endif
|