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

   1 /* -*-c-*-
   2  *
   3  * $Id: dsa.h,v 1.8 2001/02/03 16:08:24 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.8  2001/02/03 16:08:24  mdw
  34  * Add consistency checking for public keys.
  35  *
  36  * Revision 1.7  2000/07/29 09:59:44  mdw
  37  * Share data structures with Diffie-Hellman stuff.
  38  *
  39  * Revision 1.6  2000/07/01 11:20:51  mdw
  40  * New functions for freeing public and private keys.
  41  *
  42  * Revision 1.5  2000/06/17 10:53:42  mdw
  43  * Minor changes for key fetching.  Typesetting fixes.
  44  *
  45  * Revision 1.4  1999/12/22 15:52:44  mdw
  46  * Reworking for new prime-search system.
  47  *
  48  * Revision 1.3  1999/12/10 23:29:48  mdw
  49  * Change header file guard names.
  50  *
  51  * Revision 1.2  1999/11/20 22:23:48  mdw
  52  * Allow event handler to abort the search process.
  53  *
  54  * Revision 1.1  1999/11/19 19:28:00  mdw
  55  * Implementation of the Digital Signature Algorithm.
  56  *
  57  */
  58
  59 #ifndef CATACOMB_DSA_H
  60 #define CATACOMB_DSA_H
  61
  62 #ifdef __cplusplus
  63   extern "C" {
  64 #endif
  65
  66 /*----- Notes on the Digital Signature Algorithm --------------------------*
  67  *
  68  * The Digital Signature Algorithm was designed by the NSA for US Government
  69  * use.  It's defined in FIPS 186-1.  Whether it's covered by patents is
  70  * under dispute, although it looks relatively clear.  It produces compact
  71  * signatures, and is relatively easy to compute.  It seems strong, if
  72  * appropriate parameters are chosen.
  73  */
  74
  75 /*----- Header files ------------------------------------------------------*/
  76
  77 #ifndef CATACOMB_DH_H
  78 #  include "dh.h"
  79 #endif
  80
  81 #ifndef CATACOMB_KEY_H
  82 #  include "key.h"
  83 #endif
  84
  85 #ifndef CATACOMB_KEYCHECK_H
  86 #  include "keycheck.h"
  87 #endif
  88
  89 #ifndef CATACOMB_MP_H
  90 #  include "mp.h"
  91 #endif
  92
  93 #ifndef CATACOMB_PGEN_H
  94 #  include "pgen.h"
  95 #endif
  96
  97 /*----- Data structures ---------------------------------------------------*/
  98
  99 /* --- The parameters and keys are the same as for Diffie-Hellman --- */
 100
 101 typedef dh_param dsa_param;
 102 typedef dh_pub dsa_pub;
 103 typedef dh_priv dsa_priv;
 104
 105 /* --- DSA key seed structure --- */
 106
 107 typedef struct dsa_seed {
 108   void *p;                              /* Pointer to seed material */
 109   size_t sz;                            /* Size of seed material */
 110   unsigned count;                       /* Iterations to find @p@ */
 111 } dsa_seed;
 112
 113 /* --- DSA signature structure --- *
 114  *
 115  * This is the recommended structure for a DSA signature.  The actual signing
 116  * function can cope with arbitrary-sized objects given appropriate
 117  * parameters, however.
 118  */
 119
 120 #define DSA_SIGLEN 20
 121
 122 typedef struct dsa_sig {
 123   octet r[DSA_SIGLEN];                  /* 160-bit @r@ value */
 124   octet s[DSA_SIGLEN];                  /* 160-bit @s@ value */
 125 } dsa_sig;
 126
 127 /*----- Key fetching ------------------------------------------------------*/
 128
 129 #define dsa_paramfetch dh_paramfetch
 130 #define dsa_pubfetch dh_pubfetch
 131 #define dsa_privfetch dh_privfetch
 132
 133 #define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ
 134 #define DSA_PUBFETCHSZ DH_PUBFETCHSZ
 135 #define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ
 136
 137 #define dsa_paramfree dh_paramfree
 138 #define dsa_pubfree dh_pubfree
 139 #define dsa_privfree dh_privfree
 140
 141 /*----- DSA stepper -------------------------------------------------------*/
 142
 143 typedef struct dsa_stepctx {
 144
 145   /* --- To be initialized by the client --- */
 146
 147   grand *r;                             /* Random number generator */
 148   mp *q;                                /* Force @p@ to be a multiple */
 149   size_t bits;                          /* Number of bits in the result */
 150   unsigned or;                          /* OR mask for low order bits */
 151   unsigned count;                       /* Counts the number of steps made */
 152   void *seedbuf;                        /* Pointer to seed buffer */
 153 } dsa_stepctx;
 154
 155 /* --- @dsa_step@ --- *
 156  *
 157  * The stepper chooses random integers, ensures that they are a multiple of
 158  * @q@ (if specified), sets the low-order bits, and then tests for
 159  * divisibility by small primes.
 160  */
 161
 162 extern int dsa_step(int /*rq*/, pgen_event */*ev*/, void */*p*/);
 163
 164 /*----- Functions provided ------------------------------------------------*/
 165
 166 /* --- @dsa_gen@ --- *
 167  *
 168  * Arguments:   @dsa_param *dp@ = where to store parameters
 169  *              @unsigned ql@ = length of @q@ in bits
 170  *              @unsigned pl@ = length of @p@ in bits
 171  *              @unsigned steps@ = number of steps to find @q@
 172  *              @const void *k@ = pointer to key material
 173  *              @size_t sz@ = size of key material
 174  *              @dsa_seed *sd@ = optional pointer for output seed information
 175  *              @pgen_proc *event@ = event handler function
 176  *              @void *ectx@ = argument for event handler
 177  *
 178  * Returns:     @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
 179  *
 180  * Use:         Generates the DSA shared parameters from a given seed value.
 181  *              This can take quite a long time.
 182  *
 183  *              The algorithm used is a compatible extension of the method
 184  *              described in the DSA standard, FIPS 186.  The standard
 185  *              requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
 186  *              and that the length of %$p$% be %$L = 512 + 64l$% for some
 187  *              %$l$%.  Neither limitation applies to this implementation.
 188  */
 189
 190 extern int dsa_gen(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
 191                    unsigned /*steps*/, const void */*k*/, size_t /*sz*/,
 192                    dsa_seed */*sd*/, pgen_proc */*event*/, void */*ectx*/);
 193
 194 /* --- @dsa_checkparam@ --- *
 195  *
 196  * Arguments:   @keycheck *kc@ = keycheck state
 197  *              @const dsa_param *dp@ = pointer to the parameter set
 198  *              @const dsa_seed *ds@ = pointer to seed information
 199  *
 200  * Returns:     Zero if all OK, or return status from function.
 201  *
 202  * Use:         Checks a set of DSA parameters for consistency and security.
 203  */
 204
 205 extern int dsa_checkparam(keycheck */*kc*/, const dsa_param */*dp*/,
 206                           const dsa_seed */*ds*/);
 207
 208 /* --- @dsa_mksig@ --- *
 209  *
 210  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 211  *              @mp *a@ = secret signing key
 212  *              @mp *m@ = message to be signed
 213  *              @mp *k@ = random data
 214  *              @mp **rr, **ss@ = where to put output parameters
 215  *
 216  * Returns:     ---
 217  *
 218  * Use:         Computes a DSA signature of a message.
 219  */
 220
 221 extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/,
 222                       mp */*m*/, mp */*k*/,
 223                       mp **/*rr*/, mp **/*ss*/);
 224
 225 /* --- @dsa_sign@ --- *
 226  *
 227  * Arguments:   @dsa_param *dp@ = pointer to DSA parameters
 228  *              @mp *a@ = pointer to secret signing key
 229  *              @const void *m@ = pointer to message
 230  *              @size_t msz@ = size of the message
 231  *              @const void *k@ = secret random data for securing signature
 232  *              @size_t ksz@ = size of secret data
 233  *              @void *r@ = pointer to output space for @r@
 234  *              @size_t rsz@ = size of output space for @r@
 235  *              @void *s@ = pointer to output space for @s@
 236  *              @size_t ssz@ = size of output space for @s@
 237  *
 238  * Returns:     ---
 239  *
 240  * Use:         Signs a message, storing the results in a big-endian binary
 241  *              form.
 242  */
 243
 244 extern void dsa_sign(dsa_param */*dp*/, mp */*a*/,
 245                      const void */*m*/, size_t /*msz*/,
 246                      const void */*k*/, size_t /*ksz*/,
 247                      void */*r*/, size_t /*rsz*/,
 248                      void */*s*/, size_t /*ssz*/);
 249
 250 /* --- @dsa_vrfy@ --- *
 251  *
 252  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 253  *              @mp *y@ = public verification key
 254  *              @mp *m@ = message which was signed
 255  *              @mp *r, *s@ = the signature
 256  *
 257  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 258  *
 259  * Use:         Verifies a DSA digital signature.
 260  */
 261
 262 extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/,
 263                     mp */*m*/, mp */*r*/, mp */*s*/);
 264
 265 /* --- @dsa_verify@ --- *
 266  *
 267  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 268  *              @mp *y@ = public verification key
 269  *              @const void *m@ = pointer to message block
 270  *              @size_t msz@ = size of message block
 271  *              @const void *r@ = pointer to @r@ signature half
 272  *              @size_t rsz@ = size of @r@
 273  *              @const void *s@ = pointer to @s@ signature half
 274  *              @size_t ssz@ = size of @s@
 275  *
 276  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 277  *
 278  * Use:         Verifies a DSA digital signature.
 279  */
 280
 281 extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/,
 282                       const void */*m*/, size_t /*msz*/,
 283                       const void */*r*/, size_t /*rsz*/,
 284                       const void */*s*/, size_t /*ssz*/);
 285
 286 /*----- That's all, folks -------------------------------------------------*/
 287
 288 #ifdef __cplusplus
 289   }
 290 #endif
 291
 292 #endif