3 * $Id: noise.h,v 1.5 2004/04/02 01:03:49 mdw Exp $
5 * Acquisition of environmental noise (Unix-specific)
7 * (c) 1998 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Catacomb.
14 * Catacomb is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * Catacomb is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with Catacomb; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.5 2004/04/02 01:03:49 mdw
34 * Miscellaneous constification.
36 * Revision 1.4 2000/06/17 12:57:47 mdw
37 * New free counter noise generator, for use if /dev/random is
40 * Revision 1.3 1999/12/22 15:57:55 mdw
41 * Label system-specific parts more clearly.
43 * Revision 1.2 1999/12/10 23:29:48 mdw
44 * Change header file guard names.
46 * Revision 1.1 1999/09/03 08:41:12 mdw
51 #ifndef CATACOMB_NOISE_H
52 #define CATACOMB_NOISE_H
58 /*----- Header files ------------------------------------------------------*/
60 #include <sys/types.h>
62 #ifndef CATACOMB_RAND_H
66 /*----- Noise source definition -------------------------------------------*/
68 extern const rand_source noise_source
;
70 /*----- Magic numbers -----------------------------------------------------*/
72 #define NOISE_NOSETUID ((uid_t)-1)
73 #define NOISE_NOSETGID ((gid_t)-1)
75 /*----- Functions provided ------------------------------------------------*/
77 /* --- @noise_timer@ --- *
79 * Arguments: @rand_pool *r@ = pointer to a randomness pool
81 * Returns: Nonzero if some randomness was contributed.
83 * Use: Contributes the current time to the randomness pool.
84 * A guess at the number of useful bits contributed is made,
85 * based on first and second order bit differences. This isn't
86 * ever-so reliable, but it's better than nothing.
89 extern int noise_timer(rand_pool */
*r*/
);
91 /* --- @noise_devrandom@ --- *
93 * Arguments: @rand_pool *r@ = pointer to a randomness pool
95 * Returns: Nonzero if some randomness was contributed.
97 * Use: Attempts to obtain some randomness from the system entropy
98 * pool. All bits from the device are assumed to be good.
101 extern int noise_devrandom(rand_pool */
*r*/
);
103 /* --- @noise_setid@ --- *
105 * Arguments: @uid_t uid@ = uid to set
106 * @gid_t gid@ = gid to set
110 * Use: Sets the user and group ids to be used by @noise_filter@
111 * when running child processes. This is useful to avoid
112 * giving shell commands (even carefully written ones) undue
113 * privileges. This interface is Unix-specific.
116 extern void noise_setid(uid_t
/*uid*/, gid_t
/*gid*/);
118 /* --- @noise_filter@ --- *
120 * Arguments: @rand_pool *r@ = pointer to a randomness pool
121 * @int good@ = number of good bits per 1024 bits
122 * @const char *c@ = shell command to run
124 * Returns: Nonzero if some randomness was contributed.
126 * Use: Attempts to execute a shell command, and dump it into the
127 * randomness pool. A very rough estimate of the number of
128 * good bits is made, based on the size of the command's output.
129 * This function calls @waitpid@, so be careful. Before execing
130 * the command, the process uid and gid are set to the values
131 * given to @noise_setid@, and an attempt is made to reset the
132 * list of supplementary groups. The environment passed to
133 * the command has been severly lobotimized. If the command
134 * fails to complete within a short time period, it is killed.
135 * Paranoid use of close-on-exec flags for file descriptors is
138 * This interface is Unix-specific.
141 extern int noise_filter(rand_pool */
*r*/
, int /*good*/, const char */
*c*/
);
143 /* --- @noise_freewheel@ --- *
145 * Arguments: @rand_pool *r@ = pointer to a randomness pool
147 * Returns: Nonzero if some randomness was contributed.
149 * Use: Runs a free counter for a short while as a desparate attempt
150 * to get randomness from somewhere. This is actually quite
154 int noise_freewheel(rand_pool */
*r*/
);
156 /* --- @noise_enquire@ --- *
158 * Arguments: @rand_pool *r@ = pointer to a randomness pool
160 * Returns: Nonzero if some randomness was contributed.
162 * Use: Runs some shell commands to enquire about the prevailing
163 * environment. This can gather quite a lot of low-quality
167 extern int noise_enquire(rand_pool */
*r*/
);
169 /* --- @noise_acquire@ --- *
171 * Arguments: @rand_pool *r@ = pointer to a randomness pool
175 * Use: Acquires some randomness from somewhere.
178 extern void noise_acquire(rand_pool */
*r*/
);
180 /*----- That's all, folks -------------------------------------------------*/