git.distorted.org.uk Git - u/mdw/catacomb/blob - dsarand.h

   1 /* -*-c-*-
   2  *
   3  * $Id: dsarand.h,v 1.3 2001/02/03 16:08:56 mdw Exp $
   4  *
   5  * Random number generator for DSA
   6  *
   7  * (c) 1999 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: dsarand.h,v $
  33  * Revision 1.3  2001/02/03 16:08:56  mdw
  34  * Give generic random objects separate namespaces for their supported misc
  35  * ops.  Add operations for reading the current seed value.
  36  *
  37  * Revision 1.2  2000/06/17 10:54:14  mdw
  38  * Typesetting fixes.
  39  *
  40  * Revision 1.1  1999/12/22 15:53:12  mdw
  41  * Random number generator for finding DSA parameters.
  42  *
  43  */
  44
  45 #ifndef CATACOMB_DSARAND_H
  46 #define CATACOMB_DSARAND_H
  47
  48 #ifdef __cplusplus
  49   extern "C" {
  50 #endif
  51
  52 /*----- Header files ------------------------------------------------------*/
  53
  54 #include <mLib/bits.h>
  55
  56 #ifndef CATACOMB_GRAND_H
  57 #  include "grand.h"
  58 #endif
  59
  60 #ifndef CATACOMB_SHA_H
  61 #  include "sha.h"
  62 #endif
  63
  64 /*----- Data structures ---------------------------------------------------*/
  65
  66 typedef struct dsarand {
  67   octet *p;                             /* Pointer to seed (modified) */
  68   size_t sz;                            /* Size of the seed buffer */
  69   unsigned passes;                      /* Number of passes to make */
  70 } dsarand;
  71
  72 /*----- Functions provided ------------------------------------------------*/
  73
  74 /* --- @dsarand_init@ --- *
  75  *
  76  * Arguments:   @dsarand *d@ = pointer to context
  77  *              @const void *p@ = pointer to seed buffer
  78  *              @size_t sz@ = size of the buffer
  79  *
  80  * Returns:     ---
  81  *
  82  * Use:         Initializes a DSA random number generator.
  83  */
  84
  85 extern void dsarand_init(dsarand */*d*/, const void */*p*/, size_t /*sz*/);
  86
  87 /* --- @dsarand_reseed@ --- *
  88  *
  89  * Arguments:   @dsarand *d@ = pointer to context
  90  *              @const void *p@ = pointer to seed buffer
  91  *              @size_t sz@ = size of the buffer
  92  *
  93  * Returns:     ---
  94  *
  95  * Use:         Initializes a DSA random number generator.
  96  */
  97
  98 extern void dsarand_reseed(dsarand */*d*/, const void */*p*/, size_t /*sz*/);
  99
 100 /* --- @dsarand_destroy@ --- *
 101  *
 102  * Arguments:   @dsarand *d@ = pointer to context
 103  *
 104  * Returns:     ---
 105  *
 106  * Use:         Disposes of a DSA random number generation context.
 107  */
 108
 109 extern void dsarand_destroy(dsarand */*d*/);
 110
 111 /* --- @dsarand_fill@ --- *
 112  *
 113  * Arguments:   @dsarand *d@ = pointer to context
 114  *              @void *p@ = pointer to output buffer
 115  *              @size_t sz@ = size of output buffer
 116  *
 117  * Returns:     ---
 118  *
 119  * Use:         Fills an output buffer with pseudorandom data.
 120  *
 121  *              Let %$p$% be the numerical value of the input buffer, and let
 122  *              %$b$% be the number of bytes required.  Let
 123  *              %$z = \lceil b / 20 \rceil$% be the number of SHA outputs
 124  *              required.  Then the output of pass %$n$% is
 125  *
 126  *                %$P_n = \sum_{0 \le i < z} 2^{160i} SHA(p + nz + i)$%
 127  *                                                      %${} \bmod 2^{8b}$%
 128  *
 129  *              and the actual result in the output buffer is the XOR of all
 130  *              of the output passes.
 131  *
 132  *              The DSA procedure for choosing @q@ involves two passes with
 133  *              %$z = 1$%; the procedure for choosing @p@ involves one pass
 134  *              with larger %$z$%.  This generalization of the DSA generation
 135  *              procedure is my own invention but it seems relatively sound.
 136  */
 137
 138 extern void dsarand_fill(dsarand */*d*/, void */*p*/, size_t /*sz*/);
 139
 140 /*----- Generic pseudorandom-number generator interface -------------------*/
 141
 142 /* --- Miscellaneous operations --- */
 143
 144 enum {
 145   DSARAND_PASSES = GRAND_SPECIFIC('D'), /* @unsigned n@ */
 146   DSARAND_SEEDSZ,                       /* No args */
 147   DSARAND_GETSEED                       /* @void *buf@ */
 148 };
 149
 150 /* --- @dsarand_create@ --- *
 151  *
 152  * Arguments:   @const void *p@ = pointer to seed buffer
 153  *              @size_t sz@ = size of seed buffer
 154  *
 155  * Returns:     Pointer to a generic generator.
 156  *
 157  * Use:         Constructs a generic generator interface to a DSA generator.
 158  */
 159
 160 extern grand *dsarand_create(const void */*p*/, size_t /*sz*/);
 161
 162 /*----- That's all, folks -------------------------------------------------*/
 163
 164 #ifdef __cplusplus
 165   }
 166 #endif
 167
 168 #endif