Miscellaneous constification.

[u/mdw/catacomb] / noise.h

/* -*-c-*-
 *
 * $Id: noise.h,v 1.5 2004/04/02 01:03:49 mdw Exp $
 *
 * Acquisition of environmental noise (Unix-specific)
 *
 * (c) 1998 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------* 
 *
 * This file is part of Catacomb.
 *
 * Catacomb is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 * 
 * Catacomb 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 Library General Public License for more details.
 * 
 * You should have received a copy of the GNU Library General Public
 * License along with Catacomb; if not, write to the Free
 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
 * MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: noise.h,v $
 * Revision 1.5  2004/04/02 01:03:49  mdw
 * Miscellaneous constification.
 *
 * Revision 1.4  2000/06/17 12:57:47  mdw
 * New free counter noise generator, for use if /dev/random is
 * unavailable.
 *
 * Revision 1.3  1999/12/22 15:57:55  mdw
 * Label system-specific parts more clearly.
 *
 * Revision 1.2  1999/12/10 23:29:48  mdw
 * Change header file guard names.
 *
 * Revision 1.1  1999/09/03 08:41:12  mdw
 * Initial import.
 *
 */

#ifndef CATACOMB_NOISE_H
#define CATACOMB_NOISE_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <sys/types.h>

#ifndef CATACOMB_RAND_H
#  include "rand.h"
#endif

/*----- Noise source definition -------------------------------------------*/

extern const rand_source noise_source;

/*----- Magic numbers -----------------------------------------------------*/

#define NOISE_NOSETUID ((uid_t)-1)
#define NOISE_NOSETGID ((gid_t)-1)

/*----- Functions provided ------------------------------------------------*/

/* --- @noise_timer@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *
 * Returns:     Nonzero if some randomness was contributed.
 *
 * Use:         Contributes the current time to the randomness pool.
 *              A guess at the number of useful bits contributed is made,
 *              based on first and second order bit differences.  This isn't
 *              ever-so reliable, but it's better than nothing.
 */

extern int noise_timer(rand_pool */*r*/);

/* --- @noise_devrandom@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *
 * Returns:     Nonzero if some randomness was contributed.
 *
 * Use:         Attempts to obtain some randomness from the system entropy
 *              pool.  All bits from the device are assumed to be good.
 */

extern int noise_devrandom(rand_pool */*r*/);

/* --- @noise_setid@ --- *
 *
 * Arguments:   @uid_t uid@ = uid to set
 *              @gid_t gid@ = gid to set
 *
 * Returns:     ---
 *
 * Use:         Sets the user and group ids to be used by @noise_filter@
 *              when running child processes.  This is useful to avoid
 *              giving shell commands (even carefully written ones) undue
 *              privileges.  This interface is Unix-specific.
 */

extern void noise_setid(uid_t /*uid*/, gid_t /*gid*/);

/* --- @noise_filter@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *              @int good@ = number of good bits per 1024 bits
 *              @const char *c@ = shell command to run
 *
 * Returns:     Nonzero if some randomness was contributed.
 *
 * Use:         Attempts to execute a shell command, and dump it into the
 *              randomness pool.  A very rough estimate of the number of
 *              good bits is made, based on the size of the command's output.
 *              This function calls @waitpid@, so be careful.  Before execing
 *              the command, the process uid and gid are set to the values
 *              given to @noise_setid@, and an attempt is made to reset the
 *              list of supplementary groups.  The environment passed to
 *              the command has been severly lobotimized.  If the command
 *              fails to complete within a short time period, it is killed.
 *              Paranoid use of close-on-exec flags for file descriptors is
 *              recommended.
 *
 *              This interface is Unix-specific.
 */

extern int noise_filter(rand_pool */*r*/, int /*good*/, const char */*c*/);

/* --- @noise_freewheel@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *
 * Returns:     Nonzero if some randomness was contributed.
 *
 * Use:         Runs a free counter for a short while as a desparate attempt
 *              to get randomness from somewhere.  This is actually quite
 *              effective.
 */

int noise_freewheel(rand_pool */*r*/);

/* --- @noise_enquire@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *
 * Returns:     Nonzero if some randomness was contributed.
 *
 * Use:         Runs some shell commands to enquire about the prevailing
 *              environment.  This can gather quite a lot of low-quality
 *              entropy.
 */

extern int noise_enquire(rand_pool */*r*/);

/* --- @noise_acquire@ --- *
 *
 * Arguments:   @rand_pool *r@ = pointer to a randomness pool
 *
 * Returns:     ---
 *
 * Use:         Acquires some randomness from somewhere.
 */

extern void noise_acquire(rand_pool */*r*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif