chiark - git - mdw - catacomb/blob - noise.h

   1 /* -*-c-*-
   2  *
   3  * $Id: noise.h,v 1.4 2000/06/17 12:57:47 mdw Exp $
   4  *
   5  * Acquisition of environmental noise (Unix-specific)
   6  *
   7  * (c) 1998 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  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.
  18  *
  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.
  23  *
  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,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: noise.h,v $
  33  * Revision 1.4  2000/06/17 12:57:47  mdw
  34  * New free counter noise generator, for use if /dev/random is
  35  * unavailable.
  36  *
  37  * Revision 1.3  1999/12/22 15:57:55  mdw
  38  * Label system-specific parts more clearly.
  39  *
  40  * Revision 1.2  1999/12/10 23:29:48  mdw
  41  * Change header file guard names.
  42  *
  43  * Revision 1.1  1999/09/03 08:41:12  mdw
  44  * Initial import.
  45  *
  46  */
  47
  48 #ifndef CATACOMB_NOISE_H
  49 #define CATACOMB_NOISE_H
  50
  51 #ifdef __cplusplus
  52   extern "C" {
  53 #endif
  54
  55 /*----- Header files ------------------------------------------------------*/
  56
  57 #include <sys/types.h>
  58
  59 #ifndef CATACOMB_RAND_H
  60 #  include "rand.h"
  61 #endif
  62
  63 /*----- Noise source definition -------------------------------------------*/
  64
  65 extern rand_source noise_source;
  66
  67 /*----- Magic numbers -----------------------------------------------------*/
  68
  69 #define NOISE_NOSETUID ((uid_t)-1)
  70 #define NOISE_NOSETGID ((gid_t)-1)
  71
  72 /*----- Functions provided ------------------------------------------------*/
  73
  74 /* --- @noise_timer@ --- *
  75  *
  76  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
  77  *
  78  * Returns:     Nonzero if some randomness was contributed.
  79  *
  80  * Use:         Contributes the current time to the randomness pool.
  81  *              A guess at the number of useful bits contributed is made,
  82  *              based on first and second order bit differences.  This isn't
  83  *              ever-so reliable, but it's better than nothing.
  84  */
  85
  86 extern int noise_timer(rand_pool */*r*/);
  87
  88 /* --- @noise_devrandom@ --- *
  89  *
  90  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
  91  *
  92  * Returns:     Nonzero if some randomness was contributed.
  93  *
  94  * Use:         Attempts to obtain some randomness from the system entropy
  95  *              pool.  All bits from the device are assumed to be good.
  96  */
  97
  98 extern int noise_devrandom(rand_pool */*r*/);
  99
 100 /* --- @noise_setid@ --- *
 101  *
 102  * Arguments:   @uid_t uid@ = uid to set
 103  *              @gid_t gid@ = gid to set
 104  *
 105  * Returns:     ---
 106  *
 107  * Use:         Sets the user and group ids to be used by @noise_filter@
 108  *              when running child processes.  This is useful to avoid
 109  *              giving shell commands (even carefully written ones) undue
 110  *              privileges.  This interface is Unix-specific.
 111  */
 112
 113 extern void noise_setid(uid_t /*uid*/, gid_t /*gid*/);
 114
 115 /* --- @noise_filter@ --- *
 116  *
 117  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 118  *              @int good@ = number of good bits per 1024 bits
 119  *              @const char *c@ = shell command to run
 120  *
 121  * Returns:     Nonzero if some randomness was contributed.
 122  *
 123  * Use:         Attempts to execute a shell command, and dump it into the
 124  *              randomness pool.  A very rough estimate of the number of
 125  *              good bits is made, based on the size of the command's output.
 126  *              This function calls @waitpid@, so be careful.  Before execing
 127  *              the command, the process uid and gid are set to the values
 128  *              given to @noise_setid@, and an attempt is made to reset the
 129  *              list of supplementary groups.  The environment passed to
 130  *              the command has been severly lobotimized.  If the command
 131  *              fails to complete within a short time period, it is killed.
 132  *              Paranoid use of close-on-exec flags for file descriptors is
 133  *              recommended.
 134  *
 135  *              This interface is Unix-specific.
 136  */
 137
 138 extern int noise_filter(rand_pool */*r*/, int /*good*/, const char */*c*/);
 139
 140 /* --- @noise_freewheel@ --- *
 141  *
 142  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 143  *
 144  * Returns:     Nonzero if some randomness was contributed.
 145  *
 146  * Use:         Runs a free counter for a short while as a desparate attempt
 147  *              to get randomness from somewhere.  This is actually quite
 148  *              effective.
 149  */
 150
 151 int noise_freewheel(rand_pool */*r*/);
 152
 153 /* --- @noise_enquire@ --- *
 154  *
 155  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 156  *
 157  * Returns:     Nonzero if some randomness was contributed.
 158  *
 159  * Use:         Runs some shell commands to enquire about the prevailing
 160  *              environment.  This can gather quite a lot of low-quality
 161  *              entropy.
 162  */
 163
 164 extern int noise_enquire(rand_pool */*r*/);
 165
 166 /* --- @noise_acquire@ --- *
 167  *
 168  * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 169  *
 170  * Returns:     ---
 171  *
 172  * Use:         Acquires some randomness from somewhere.
 173  */
 174
 175 extern void noise_acquire(rand_pool */*r*/);
 176
 177 /*----- That's all, folks -------------------------------------------------*/
 178
 179 #ifdef __cplusplus
 180   }
 181 #endif
 182
 183 #endif