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

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