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

   1 /* -*-c-*-
   2  *
   3  * Digital Signature Algorithm
   4  *
   5  * (c) 1999 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of Catacomb.
  11  *
  12  * Catacomb is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * Catacomb is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with Catacomb; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef CATACOMB_DSA_H
  29 #define CATACOMB_DSA_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Notes on the Digital Signature Algorithm --------------------------*
  36  *
  37  * The Digital Signature Algorithm was designed by the NSA for US Government
  38  * use.  It's defined in FIPS 186-1.  Whether it's covered by patents is
  39  * under dispute, although it looks relatively clear.  It produces compact
  40  * signatures, and is relatively easy to compute.  It seems strong, if
  41  * appropriate parameters are chosen.
  42  */
  43
  44 /*----- Header files ------------------------------------------------------*/
  45
  46 #include <mLib/macros.h>
  47
  48 #ifndef CATACOMB_DH_H
  49 #  include "dh.h"
  50 #endif
  51
  52 #ifndef CATACOMB_GRAND_H
  53 #  include "grand.h"
  54 #endif
  55
  56 #ifndef CATACOMB_KEY_H
  57 #  include "key.h"
  58 #endif
  59
  60 #ifndef CATACOMB_KEYCHECK_H
  61 #  include "keycheck.h"
  62 #endif
  63
  64 #ifndef CATACOMB_MP_H
  65 #  include "mp.h"
  66 #endif
  67
  68 #ifndef CATACOMB_PGEN_H
  69 #  include "pgen.h"
  70 #endif
  71
  72 /*----- Data structures ---------------------------------------------------*/
  73
  74 /* --- The parameters and keys are the same as for Diffie-Hellman --- */
  75
  76 typedef dh_param dsa_param;
  77 typedef dh_pub dsa_pub;
  78 typedef dh_priv dsa_priv;
  79
  80 /* --- DSA key seed structure --- */
  81
  82 typedef struct dsa_seed {
  83   void *p;                              /* Pointer to seed material */
  84   size_t sz;                            /* Size of seed material */
  85   unsigned count;                       /* Iterations to find @p@ */
  86 } dsa_seed;
  87
  88 /* --- DSA signature structure --- *
  89  *
  90  * This is the recommended structure for a DSA signature.  The actual signing
  91  * function can cope with arbitrary-sized objects given appropriate
  92  * parameters, however.
  93  */
  94
  95 #define DSA_SIGLEN 20
  96
  97 typedef struct dsa_sig {
  98   octet r[DSA_SIGLEN];                  /* 160-bit @r@ value */
  99   octet s[DSA_SIGLEN];                  /* 160-bit @s@ value */
 100 } dsa_sig;
 101
 102 /*----- Key fetching ------------------------------------------------------*/
 103
 104 #define dsa_paramfetch dh_paramfetch
 105 #define dsa_pubfetch dh_pubfetch
 106 #define dsa_privfetch dh_privfetch
 107
 108 #define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ
 109 #define DSA_PUBFETCHSZ DH_PUBFETCHSZ
 110 #define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ
 111
 112 #define dsa_paramfree dh_paramfree
 113 #define dsa_pubfree dh_pubfree
 114 #define dsa_privfree dh_privfree
 115
 116 /*----- DSA stepper -------------------------------------------------------*/
 117
 118 typedef struct dsa_stepctx {
 119
 120   /* --- To be initialized by the client --- */
 121
 122   grand *r;                             /* Random number generator */
 123   mp *q;                                /* Force @p@ to be a multiple */
 124   size_t bits;                          /* Number of bits in the result */
 125   unsigned or;                          /* OR mask for low order bits */
 126   unsigned count;                       /* Counts the number of steps made */
 127   void *seedbuf;                        /* Pointer to seed buffer */
 128 } dsa_stepctx;
 129
 130 /* --- @dsa_step@ --- *
 131  *
 132  * The stepper chooses random integers, ensures that they are a multiple of
 133  * @q@ (if specified), sets the low-order bits, and then tests for
 134  * divisibility by small primes.
 135  */
 136
 137 extern pgen_proc dsa_step;
 138
 139 /*----- Functions provided ------------------------------------------------*/
 140
 141 /* --- @dsa_gen@ --- *
 142  *
 143  * Arguments:   @dsa_param *dp@ = where to store parameters
 144  *              @unsigned ql@ = length of @q@ in bits
 145  *              @unsigned pl@ = length of @p@ in bits
 146  *              @unsigned steps@ = number of steps to find @q@
 147  *              @const void *k@ = pointer to key material
 148  *              @size_t sz@ = size of key material
 149  *              @dsa_seed *sd@ = optional pointer for output seed information
 150  *              @pgen_proc *event@ = event handler function
 151  *              @void *ectx@ = argument for event handler
 152  *
 153  * Returns:     @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
 154  *
 155  * Use:         Generates the DSA shared parameters from a given seed value.
 156  *              This can take quite a long time.
 157  *
 158  *              The algorithm used is a compatible extension of the method
 159  *              described in the DSA standard, FIPS 186.  The standard
 160  *              requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
 161  *              and that the length of %$p$% be %$L = 512 + 64l$% for some
 162  *              %$l$%.  Neither limitation applies to this implementation.
 163  */
 164
 165 extern int dsa_gen(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
 166                    unsigned /*steps*/, const void */*k*/, size_t /*sz*/,
 167                    dsa_seed */*sd*/, pgen_proc */*event*/, void */*ectx*/);
 168
 169 /* --- @dsa_checkparam@ --- *
 170  *
 171  * Arguments:   @keycheck *kc@ = keycheck state
 172  *              @const dsa_param *dp@ = pointer to the parameter set
 173  *              @const dsa_seed *ds@ = pointer to seed information
 174  *
 175  * Returns:     Zero if all OK, or return status from function.
 176  *
 177  * Use:         Checks a set of DSA parameters for consistency and security.
 178  */
 179
 180 extern int dsa_checkparam(keycheck */*kc*/, const dsa_param */*dp*/,
 181                           const dsa_seed */*ds*/);
 182
 183 /* --- @dsa_h2n@ --- *
 184  *
 185  * Arguments:   @mp *d@ = destination integer
 186  *              @mp *r@ = order of the DSA group
 187  *              @const void *h@ = pointer to message hash
 188  *              @size_t hsz@ = size (in bytes) of the hash output
 189  *
 190  * Returns:     Resulting integer.
 191  *
 192  * Use:         Converts a hash to an integer in the demented way necessary
 193  *              for DSA/ECDSA.  This is, of course, completely insane, but
 194  *              there you go.
 195  */
 196
 197 extern mp *dsa_h2n(mp */*d*/, mp */*r*/, const void */*h*/, size_t /*hsz*/);
 198
 199 /* --- @dsa_nonce@ --- *
 200  *
 201  * Arguments:   @mp *d@ = destination integer
 202  *              @mp *q@ = order of the DSA group
 203  *              @mp *x@ = secret key
 204  *              @const octet *m@ = message hash
 205  *              @const gchash *ch@ = hash class
 206  *              @grand *r@ = random bit source, or null
 207  *
 208  * Returns:     A nonce.
 209  *
 210  * Use:         Generates a nonce for use in DSA (or another Fiat--Shamir
 211  *              signature scheme).
 212  */
 213
 214 extern mp *dsa_nonce(mp */*d*/, mp */*q*/, mp */*x*/, const octet */*m*/,
 215                      const gchash */*ch*/, grand */*r*/);
 216
 217 /* --- @dsa_mksig@ --- *
 218  *
 219  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 220  *              @mp *a@ = secret signing key
 221  *              @mp *m@ = message to be signed
 222  *              @mp *k@ = random data
 223  *              @mp **rr, **ss@ = where to put output parameters
 224  *
 225  * Returns:     ---
 226  *
 227  * Use:         Computes a DSA signature of a message.
 228  *
 229  *              This function is deprecated.  It's really rather badly
 230  *              designed, and hard to use securely (and hard to fix).  Please
 231  *              use @gdsa_sign@ instead.
 232  */
 233
 234 extern
 235 #ifndef CATACOMB_DSAIMPL
 236   DEPRECATED("please use `gdsa_sign' instead")
 237 #endif
 238   void dsa_mksig(const dsa_param */*dp*/, mp */*a*/, mp */*m*/, mp */*k*/,
 239                  mp **/*rr*/, mp **/*ss*/);
 240
 241 /* --- @dsa_sign@ --- *
 242  *
 243  * Arguments:   @dsa_param *dp@ = pointer to DSA parameters
 244  *              @mp *a@ = pointer to secret signing key
 245  *              @const void *m@ = pointer to message
 246  *              @size_t msz@ = size of the message
 247  *              @const void *k@ = secret random data for securing signature
 248  *              @size_t ksz@ = size of secret data
 249  *              @void *r@ = pointer to output space for @r@
 250  *              @size_t rsz@ = size of output space for @r@
 251  *              @void *s@ = pointer to output space for @s@
 252  *              @size_t ssz@ = size of output space for @s@
 253  *
 254  * Returns:     ---
 255  *
 256  * Use:         Signs a message, storing the results in a big-endian binary
 257  *              form.
 258  *
 259  *              This function is deprecated.  It's really rather badly
 260  *              designed, and hard to use securely (and hard to fix).  Please
 261  *              use @gdsa_sign@ instead.
 262  */
 263
 264 extern
 265 #ifndef CATACOMB_DSAIMPL
 266   DEPRECATED("please use `gdsa_sign' instead")
 267 #endif
 268   void dsa_sign(dsa_param */*dp*/, mp */*a*/,
 269                 const void */*m*/, size_t /*msz*/,
 270                 const void */*k*/, size_t /*ksz*/,
 271                 void */*r*/, size_t /*rsz*/, void */*s*/, size_t /*ssz*/);
 272
 273 /* --- @dsa_vrfy@ --- *
 274  *
 275  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 276  *              @mp *y@ = public verification key
 277  *              @mp *m@ = message which was signed
 278  *              @mp *r, *s@ = the signature
 279  *
 280  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 281  *
 282  * Use:         Verifies a DSA digital signature.
 283  */
 284
 285 extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/,
 286                     mp */*m*/, mp */*r*/, mp */*s*/);
 287
 288 /* --- @dsa_verify@ --- *
 289  *
 290  * Arguments:   @const dsa_param *dp@ = pointer to DSA parameters
 291  *              @mp *y@ = public verification key
 292  *              @const void *m@ = pointer to message block
 293  *              @size_t msz@ = size of message block
 294  *              @const void *r@ = pointer to @r@ signature half
 295  *              @size_t rsz@ = size of @r@
 296  *              @const void *s@ = pointer to @s@ signature half
 297  *              @size_t ssz@ = size of @s@
 298  *
 299  * Returns:     Zero if the signature is a forgery, nonzero if it's valid.
 300  *
 301  * Use:         Verifies a DSA digital signature.
 302  */
 303
 304 extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/,
 305                       const void */*m*/, size_t /*msz*/,
 306                       const void */*r*/, size_t /*rsz*/,
 307                       const void */*s*/, size_t /*ssz*/);
 308
 309 /*----- That's all, folks -------------------------------------------------*/
 310
 311 #ifdef __cplusplus
 312   }
 313 #endif
 314
 315 #endif