3 * Acquisition of environmental noise (Unix-specific)
5 * (c) 1998 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 #ifndef CATACOMB_NOISE_H
29 #define CATACOMB_NOISE_H
35 /*----- Header files ------------------------------------------------------*/
37 #include <sys/types.h>
39 #ifndef CATACOMB_RAND_H
43 /*----- Noise source definition -------------------------------------------*/
45 extern const rand_source noise_source;
47 /*----- Magic numbers -----------------------------------------------------*/
49 #define NOISE_NOSETUID ((uid_t)-1)
50 #define NOISE_NOSETGID ((gid_t)-1)
52 /*----- Functions provided ------------------------------------------------*/
54 /* --- @noise_timer@ --- *
56 * Arguments: @rand_pool *r@ = pointer to a randomness pool
58 * Returns: Nonzero if some randomness was contributed.
60 * Use: Contributes the current time to the randomness pool.
61 * A guess at the number of useful bits contributed is made,
62 * based on first and second order bit differences. This isn't
63 * ever-so reliable, but it's better than nothing.
66 extern int noise_timer(rand_pool */*r*/);
68 /* --- @noise_devrandom@ --- *
70 * Arguments: @rand_pool *r@ = pointer to a randomness pool
72 * Returns: Nonzero if some randomness was contributed.
74 * Use: Attempts to obtain some randomness from the system entropy
75 * pool. All bits from the device are assumed to be good.
78 extern int noise_devrandom(rand_pool */*r*/);
80 /* --- @noise_setid@ --- *
82 * Arguments: @uid_t uid@ = uid to set
83 * @gid_t gid@ = gid to set
87 * Use: Sets the user and group ids to be used by @noise_filter@
88 * when running child processes. This is useful to avoid
89 * giving shell commands (even carefully written ones) undue
90 * privileges. This interface is Unix-specific.
93 extern void noise_setid(uid_t /*uid*/, gid_t /*gid*/);
95 /* --- @noise_filter@ --- *
97 * Arguments: @rand_pool *r@ = pointer to a randomness pool
98 * @int good@ = number of good bits per 1024 bits
99 * @const char *c@ = shell command to run
101 * Returns: Nonzero if some randomness was contributed.
103 * Use: Attempts to execute a shell command, and dump it into the
104 * randomness pool. A very rough estimate of the number of
105 * good bits is made, based on the size of the command's output.
106 * This function calls @waitpid@, so be careful. Before execing
107 * the command, the process uid and gid are set to the values
108 * given to @noise_setid@, and an attempt is made to reset the
109 * list of supplementary groups. The environment passed to
110 * the command has been severly lobotimized. If the command
111 * fails to complete within a short time period, it is killed.
112 * Paranoid use of close-on-exec flags for file descriptors is
115 * This interface is Unix-specific.
118 extern int noise_filter(rand_pool */*r*/, int /*good*/, const char */*c*/);
120 /* --- @noise_freewheel@ --- *
122 * Arguments: @rand_pool *r@ = pointer to a randomness pool
124 * Returns: Nonzero if some randomness was contributed.
126 * Use: Runs a free counter for a short while as a desparate attempt
127 * to get randomness from somewhere. This is actually quite
131 int noise_freewheel(rand_pool */*r*/);
133 /* --- @noise_enquire@ --- *
135 * Arguments: @rand_pool *r@ = pointer to a randomness pool
137 * Returns: Nonzero if some randomness was contributed.
139 * Use: Runs some shell commands to enquire about the prevailing
140 * environment. This can gather quite a lot of low-quality
144 extern int noise_enquire(rand_pool */*r*/);
146 /* --- @noise_acquire@ --- *
148 * Arguments: @rand_pool *r@ = pointer to a randomness pool
152 * Use: Acquires some randomness from somewhere.
155 extern void noise_acquire(rand_pool */*r*/);
157 /*----- That's all, folks -------------------------------------------------*/