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

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