Force subkeys to be sorted in structured keys.

[u/mdw/catacomb] / grand.h

/* -*-c-*-
 *
 * $Id: grand.h,v 1.4 2001/04/19 18:23:53 mdw Exp $
 *
 * 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.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: grand.h,v $
 * Revision 1.4  2001/04/19 18:23:53  mdw
 * Use unsigned integer rather than enum for flags.
 *
 * Revision 1.3  2001/02/03 16:07:33  mdw
 * Give generic random objects separate namespaces for their supported misc
 * ops.
 *
 * Revision 1.2  2000/06/17 11:23:11  mdw
 * Typesetting fix.  Add a flags word to the generic generator.
 *
 * Revision 1.1  1999/12/10 23:16:01  mdw
 * Generic interface.
 *
 */

#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 */

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

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

  /* --- Output methods --- *
   *
   * Only one of these operations need actually be implemented.  All the
   * other operations may be synthesized.  Of course, performance is improved
   * if more are provided.
   */

  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;

/* --- 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))

/*----- 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