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

   1 /* -*-c-*-
   2  *
   3  * $Id: dsa.h,v 1.3 1999/12/10 23:29:48 mdw Exp $
   4  *
   5  * Digital Signature Algorithm
   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: dsa.h,v $
  33  * Revision 1.3  1999/12/10 23:29:48  mdw
  34  * Change header file guard names.
  35  *
  36  * Revision 1.2  1999/11/20 22:23:48  mdw
  37  * Allow event handler to abort the search process.
  38  *
  39  * Revision 1.1  1999/11/19 19:28:00  mdw
  40  * Implementation of the Digital Signature Algorithm.
  41  *
  42  */
  43
  44 #ifndef CATACOMB_DSA_H
  45 #define CATACOMB_DSA_H
  46
  47 #ifdef __cplusplus
  48   extern "C" {
  49 #endif
  50
  51 /*----- Notes on the Digital Signature Algorithm --------------------------*
  52  *
  53  * The Digital Signature Algorithm was designed by the NSA for US Government
  54  * use.  It's defined in FIPS 186-1.  Whether it's covered by patents is
  55  * under dispute, although it looks relatively clear.  It produces compact
  56  * signatures, and is relatively easy to compute.  It seems strong, if
  57  * appropriate parameters are chosen.
  58  */
  59
  60 /*----- Header files ------------------------------------------------------*/
  61
  62 #ifndef CATACOMB_MP_H
  63 #  include "mp.h"
  64 #endif
  65
  66 /*----- Event codes -------------------------------------------------------*/
  67
  68 enum {
  69   DSAEV_OK,                             /* Everything is fine */
  70
  71   DSAEV_FINDQ,                          /* Search for a @q@ */
  72   DSAEV_FAILQ,                          /* @q@ failed primality test */
  73   DSAEV_PASSQ,                          /* @q@ passeed one iteration */
  74   DSAEV_GOODQ,                          /* Found good prime @q@ */
  75
  76   DSAEV_FINDP,                          /* Search for a @p@ */
  77   DSAEV_TRYP,                           /* Try prospective @p@ */
  78   DSAEV_FAILP,                          /* @p@ failed primality test */
  79   DSAEV_PASSP,                          /* @p@ passed one iteration */
  80   DSAEV_GOODP,                          /* @p@ accepted as being prime */
  81
  82   DSAEV_FINDG,                          /* Search for a @g@ */
  83   DSAEV_TRYH,                           /* Try prospective @h@ */
  84   DSAEV_FAILH,                          /* @h@ failed */
  85   DSAEV_GOODG                           /* @g@ accepted as a generator */
  86 };
  87
  88 /*----- Data structures ---------------------------------------------------*/
  89
  90 /* --- DSA parameter structure --- *
  91  *
  92  * These parameters can, and probably should, be shared among a group of
  93  * users.
  94  */
  95
  96 typedef struct dsa_param {
  97   mp *p, *q;                            /* Prime numbers %$p$% and %$q$% */
  98   mp *g;                                /* Generates order-%$q$% subgroup */
  99 } dsa_param;
 100
 101 /* --- DSA signature structure --- *
 102  *
 103  * This is the recommended structure for a DSA signature.  The actual signing
 104  * function can cope with arbitrary-sized objects given appropriate
 105  * parameters, however.
 106  */
 107
 108 #define DSA_SIGLEN 20
 109
 110 typedef struct dsa_sig {
 111   octet r[DSA_SIGLEN];                  /* 160-bit @r@ value */
 112   octet s[DSA_SIGLEN];                  /* 160-bit @s@ value */
 113 } dsa_sig;
 114
 115 /*----- Functions provided ------------------------------------------------*/
 116
 117 /* --- @dsa_seed@ --- *
 118  *
 119  * Arguments:   @dsa_param *dp@ = where to store parameters
 120  *              @unsigned l@ = bitlength of @p@ in bits
 121  *              @const void *k@ = pointer to key material
 122  *              @int (*proc)(int ev, mp *m, void *p)@ = event procedure
 123  *              @size_t sz@ = size of key material
 124  *
 125  * Returns:     Zero if all went well, nonzero if key material was
 126  *              unsuitable (one of the @DSAEV@ codes).
 127  *
 128  * Use:         Generates the DSA shared parameters from a given seed value.
 129  *              This can take quite a long time.  The size of @p@ in bits is
 130  *              %$l = 512 + 64l'$%.  The DSA standard, FIPS 186, only allows
 131  *              %$0 \le l' \le 8$%.  This implementation has no such limit,
 132  *              although @l@ must be a multiple of 8.
 133  *
 134  *              The event procedure is informed of various happenings during
 135  *              generation.  It is passed an event code describing what
 136  *              happened, and a multiprecision number which pertains to the
 137  *              event code.  It may abort the search at any time by returning
 138  *              a nonzero value, which is returned as the result of the
 139  *              function.
 140  */
 141
 142 extern int dsa_seed(dsa_param */*dp*/, unsigned /*l*/,
 143                     const void */*k*/, size_t /*sz*/,
 144                     int (*proc)(int /*ev*/, mp */*m*/, void */*p*/),
 145                     void */*p*/);
 146
 147 /* --- @dsa_mksig@ --- *
 148  *
 149  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 150  *              @mp *a@ = secret signing key
 151  *              @mp *m@ = message to be signed
 152  *              @mp *k@ = random data
 153  *              @mp **rr, **ss@ = where to put output parameters
 154  *
 155  * Returns:     ---
 156  *
 157  * Use:         Computes a DSA signature of a message.
 158  */
 159
 160 extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/,
 161                       mp */*m*/, mp */*k*/,
 162                       mp **/*rr*/, mp **/*ss*/);
 163
 164 /* --- @dsa_sign@ --- *
 165  *
 166  * Arguments:   @dsa_param *dp@ = pointer to DSA parameters
 167  *              @mp *a@ = pointer to secret signing key
 168  *              @const void *m@ = pointer to message
 169  *              @size_t msz@ = size of the message
 170  *              @const void *k@ = secret random data for securing signature
 171  *              @size_t ksz@ = size of secret data
 172  *              @void *r@ = pointer to output space for @r@
 173  *              @size_t rsz@ = size of output space for @r@
 174  *              @void *s@ = pointer to output space for @s@
 175  *              @size_t ssz@ = size of output space for @s@
 176  *
 177  * Returns:     ---
 178  *
 179  * Use:         Signs a message, storing the results in a big-endian binary
 180  *              form.
 181  */
 182
 183 extern void dsa_sign(dsa_param */*dp*/, mp */*a*/,
 184                      const void */*m*/, size_t /*msz*/,
 185                      const void */*k*/, size_t /*ksz*/,
 186                      void */*r*/, size_t /*rsz*/,
 187                      void */*s*/, size_t /*ssz*/);
 188
 189 /* --- @dsa_vrfy@ --- *
 190  *
 191  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 192  *              @mp *y@ = public verification key
 193  *              @mp *m@ = message which was signed
 194  *              @mp *r, *s@ = the signature
 195  *
 196  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 197  *
 198  * Use:         Verifies a DSA digital signature.
 199  */
 200
 201 extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/,
 202                     mp */*m*/, mp */*r*/, mp */*s*/);
 203
 204 /* --- @dsa_verify@ --- *
 205  *
 206  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 207  *              @mp *y@ = public verification key
 208  *              @const void *m@ = pointer to message block
 209  *              @size_t msz@ = size of message block
 210  *              @const void *r@ = pointer to @r@ signature half
 211  *              @size_t rsz@ = size of @r@
 212  *              @const void *s@ = pointer to @s@ signature half
 213  *              @size_t ssz@ = size of @s@
 214  *
 215  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 216  *
 217  * Use:         Verifies a DSA digital signature.
 218  */
 219
 220 extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/,
 221                const void */*m*/, size_t /*msz*/,
 222                const void */*r*/, size_t /*rsz*/,
 223                const void */*s*/, size_t /*ssz*/);
 224
 225 /*----- That's all, folks -------------------------------------------------*/
 226
 227 #ifdef __cplusplus
 228   }
 229 #endif
 230
 231 #endif