progs/perftest.c: Use from Glibc syscall numbers.

[catacomb] / rand / grand.h

/* -*-c-*-
 *
 * Generic interface to random number generators
 *
 * (c) 1999 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.
 */

#ifndef CATACOMB_GRAND_H
#define CATACOMB_GRAND_H

#ifdef __cplusplus
  extern "C" {
#endif

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

#include <assert.h>
#include <stddef.h>

#include <mLib/bits.h>

/*----- Generic random number generator interface -------------------------*/

typedef struct grand {
  const struct grand_ops *ops;
} grand;

typedef struct grand_ops {

  /* --- Various important properties --- */

  const char *name;                     /* Generator's name */
  unsigned f;                           /* Various flags */
  uint32 max;                           /* Maximum raw output, if nonzero;
                                         * must be either zero or at least
                                         * 256
                                         */

  /* --- Maintenance methods --- */

  int (*misc)(grand */*r*/, unsigned /*op*/, ...); /* Miscellaneous ops */
  void (*destroy)(grand */*r*/);        /* Destroy generator context */

  /* --- Output methods --- *
   *
   * Of these, only @raw@ need be implemented directly by the generator: the
   * others can point to provided @grand_default...@ functions, which will
   * synthesize the necessary behaviour.  Of course, this comes at an
   * efficiency penalty.
   */

  uint32 (*raw)(grand */*r*/);          /* Uniform over %$[0, max)$% */
  octet (*byte)(grand */*r*/);          /* Uniform over %$[0, 256)$% */
  uint32 (*word)(grand */*r*/);         /* Uniform over %$[0, 2^{32})$% */
  uint32 (*range)(grand */*r*/, uint32 /*l*/); /* Uniform over %$[0, l)$% */
  void (*fill)(grand */*r*/, void */*p*/, size_t /*sz*/); /* Fill buffer */
} grand_ops;

#define GR_DESTROY(r)           (r)->ops->destroy((r))
#define GR_RAW(r)               (r)->ops->raw((r))
#define GR_WORD(r)              (r)->ops->word((r))
#define GR_RANGE(r, l)          (r)->ops->range((r), (l))
#define GR_FILL(r, p, sz)       (r)->ops->fill((r), (p), (sz))

/* --- Flag types --- */

#define GRAND_CRYPTO 1u                 /* Cryptographically strong */

/* --- Operation types --- */

enum {

  /* --- Required operations --- */

  GRAND_CHECK,                          /* @unsigned op2@ */

  /* --- Standard seeding operations --- */

  GRAND_SEEDINT,                        /* @int i@ */
  GRAND_SEEDUINT32,                     /* @uint32 i@ */
  GRAND_SEEDBLOCK,                      /* @const void *p, size_t sz@ */
  GRAND_SEEDMP,                         /* @mp *m@ */
  GRAND_SEEDRAND                        /* @grand *g@ */

  /* --- Generator-specific operations --- */

#define GRAND_SPECIFIC(ch) ((unsigned)(ch) << 8)
};

#define GRAND_BADOP assert(((void)"bad grand_misc op", 0))

/*----- Default operations ------------------------------------------------*/

/* --- @grand_defaultbyte@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, 256)$%.
 *
 * Use:         Default @byte@ output method.  This calls the @range@ method
 *              to return a uniform random value between 0 and 255.
 */

extern octet grand_defaultbyte(grand */*r*/);

/* --- @grand_defaultword@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, 2^{32})$%.
 *
 * Use:         Default @word@ output method.  This calls the @fill@ method
 *              to fill a 4-octet buffer with uniform random bytes, and then
 *              converts them to an integer.
 */

extern uint32 grand_defaultword(grand */*r*/);

/* --- @grand_defaultrange@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *              @uint32 l@ = limit for acceptable results
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, l)$%.
 *
 * Use:         Default @range@ output method.  This falls back to either
 *              @word@ (if the generator's @max@ is zero, or if @max < l@) or
 *              @raw@ (otherwise).  This might recurse via @fill@ and @byte@,
 *              but this is safe because of the constraint on the @raw@
 *              method.
 */

extern uint32 grand_defaultrange(grand */*r*/, uint32 /*l*/);

/* --- @grand_defaultfill@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *              @void *p@ = pointer to a buffer
 *              @size_t sz@ = size of the buffer
 *
 * Returns:     ---
 *
 * Use:         Fills a buffer with uniformly distributed pseudorandom bytes.
 *              This calls the @byte@ method repeatedly to fill in the output
 *              buffer.
 */

extern void grand_defaultfill(grand */*r*/, void */*p*/, size_t /*sz*/);

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

/* --- @grand_byte@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, 256)$%.
 */

extern octet grand_byte(grand */*r*/);

/* --- @grand_word@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, 2^{32})$%.
 */

extern uint32 grand_word(grand */*r*/);

/* --- @grand_range@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *              @uint32 l@ = limit for acceptable results
 *
 * Returns:     A uniformly-distributed pseudorandom integer in the interval
 *              %$[0, l)$%.
 */

extern uint32 grand_range(grand */*r*/, uint32 /*l*/);

/* --- @grand_fill@ --- *
 *
 * Arguments:   @grand *r@ = pointet to generic generator
 *              @void *p@ = pointer to a buffer
 *              @size_t sz@ = size of the buffer
 *
 * Returns:     ---
 *
 * Use:         Fills a buffer with uniformly distributed pseudorandom bytes
 *              (see @grand_byte@).
 */

extern void grand_fill(grand */*r*/, void */*p*/, size_t /*sz*/);

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

#ifdef __cplusplus
  }
#endif

#endif