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

   1 /* -*-c-*-
   2  *
   3  * Diffie-Hellman and related public-key systems
   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_DH_H
  29 #define CATACOMB_DH_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Header files ------------------------------------------------------*/
  36
  37 #ifndef CATACOMB_GROUP_H
  38 #  include "group.h"
  39 #endif
  40
  41 #ifndef CATACOMB_GRAND_H
  42 #  include "grand.h"
  43 #endif
  44
  45 #ifndef CATACOMB_KEY_H
  46 #  include "key.h"
  47 #endif
  48
  49 #ifndef CATACOMB_KEYCHECK_H
  50 #  include "keycheck.h"
  51 #endif
  52
  53 #ifndef CATACOMB_PGEN_H
  54 #  include "pgen.h"
  55 #endif
  56
  57 #ifndef CATACOMB_QDPARSE_H
  58 #  include "qdparse.h"
  59 #endif
  60
  61 /*----- Data structures ---------------------------------------------------*/
  62
  63 typedef gprime_param dh_param;          /* Group parameters */
  64
  65 typedef struct dh_pub {
  66   dh_param dp;                          /* Shared parameters */
  67   mp *y;                                /* Public key */
  68 } dh_pub;
  69
  70 typedef struct dh_priv {
  71   dh_param dp;                          /* Shared parameters */
  72   mp *x;                                /* Private key */
  73   mp *y;                                /* %$y \equiv g^x \pmod{p}$% */
  74 } dh_priv;
  75
  76 /*----- Key fetching ------------------------------------------------------*/
  77
  78 extern const key_fetchdef dh_paramfetch[];
  79 #define DH_PARAMFETCHSZ 5
  80
  81 extern const key_fetchdef dh_pubfetch[];
  82 #define DH_PUBFETCHSZ 6
  83
  84 extern const key_fetchdef dh_privfetch[];
  85 #define DH_PRIVFETCHSZ 9
  86
  87 /* --- @dh_paramfree@, @dh_pubfree@, @dh_privfree@ --- *
  88  *
  89  * Arguments:   @dh_param *dp@, @dh_pub *dp@, @dh_priv *dp@ = pointer to
  90  *                      key block to free
  91  *
  92  * Returns:     ---
  93  *
  94  * Use:         Frees a Diffie-Hellman key block.
  95  */
  96
  97 extern void dh_paramfree(dh_param */*dp*/);
  98 extern void dh_pubfree(dh_pub */*dp*/);
  99 extern void dh_privfree(dh_priv */*dp*/);
 100
 101 /*----- Functions provided ------------------------------------------------*/
 102
 103 /* --- @dh_gen@ --- *
 104  *
 105  * Arguments:   @dh_param *dp@ = pointer to output parameter block
 106  *              @unsigned ql@ = length of %$q$% in bits, or zero
 107  *              @unsigned pl@ = length of %$p$% in bits
 108  *              @unsigned steps@ = number of steps to go
 109  *              @grand *r@ = random number source
 110  *              @pgen_proc *event@ = event handler function
 111  *              @void *ectx@ = argument for the event handler
 112  *
 113  * Returns:     @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
 114  *
 115  * Use:         Generates Diffie-Hellman parameters.
 116  *
 117  *              The parameters are a prime %$q$%, relatively small, and a
 118  *              large prime %$p = kq + 1$% for some %$k$%, together with a
 119  *              generator %$g$% of the cyclic subgroup of order %$q$%.  These
 120  *              are actually the same as the DSA parameter set, but the
 121  *              generation algorithm is different.  Also, if @ql@ is zero,
 122  *              this algorithm forces %$k = 2$%, and chooses %$g = 4$%.  Make
 123  *              sure you have something interesting to do if you choose this
 124  *              option.
 125  */
 126
 127 extern int dh_gen(dh_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
 128                   unsigned /*steps*/, grand */*r*/, pgen_proc */*event*/,
 129                   void */*ectx*/);
 130
 131 /* --- @dh_limlee@ --- *
 132  *
 133  * Arguments:   @dh_param *dp@ = pointer to output parameter block
 134  *              @unsigned ql@ = length of smallest factor of %$(p - 1)/2$%
 135  *              @unsigned pl@ = length of %$p$% in bits
 136  *              @unsigned flags@ = other generation flags
 137  *              @unsigned steps@ = number of steps to go
 138  *              @grand *r@ = random number source
 139  *              @pgen_proc *oev@ = outer event handler function
 140  *              @void *oec@ = argument for the outer event handler
 141  *              @pgen_proc *iev@ = inner event handler function
 142  *              @void *iec@ = argument for the inner event handler
 143  *              @size_t *nf@, @mp ***f@ = output array for factors
 144  *
 145  * Returns:     @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
 146  *
 147  * Use:         Generates Diffie-Hellman parameters based on a Lim-Lee prime.
 148  *
 149  *              The modulus is a large prime %$p = 2 \prod q_i + 1$%, @pl@
 150  *              bits long, where the %$q_i$% are smaller primes each at least
 151  *              @ql@ bits long.  It is safe to set @nf@ and @f@ to zero if
 152  *              you're not interested in the factor values.
 153  *
 154  *              The returned %$g$% generates a subgroup of order %$q_0$% (the
 155  *              first factor, returned as @f[0]@), if the flag @DH_SUBGROUP@
 156  *              is set on entry; otherwise %$g$% will have order
 157  *              %$(p - 1)/2$%.
 158  */
 159
 160 #define DH_SUBGROUP 1u
 161
 162 extern int dh_limlee(dh_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
 163                      unsigned /*flags*/, unsigned /*steps*/, grand */*r*/,
 164                      pgen_proc */*oev*/, void */*oec*/, pgen_proc */*iev*/,
 165                      void */*iec*/, size_t */*nf*/, mp ***/*f*/);
 166
 167 /* --- @dh_kcdsagen@ --- *
 168  *
 169  * Arguments:   @dh_param *dp@ = pointer to output parameter block
 170  *              @unsigned ql@ = size of small factor of %$(p - 1)/2$%
 171  *              @unsigned pl@ = size of %$p$% in bits
 172  *              @unsigned flags@ = other generation flags (none defined)
 173  *              @unsigned steps@ = number of steps to go
 174  *              @grand *r@ = random number source
 175  *              @pgen_proc *ev@ = event handler function
 176  *              @void *ec@ = context for the event handler
 177  *
 178  * Returns:     @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it failed.
 179  *
 180  * Use:         Generates a KCDSA prime group.  That is, it chooses a prime
 181  *              %$p$%, such that $%p = 2 q v + 1$%, for primes %$q$% and
 182  *              %$v$%.  The actual group of interest is the subgroup of order
 183  *              %$q$%.
 184  */
 185
 186 extern int dh_kcdsagen(dh_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
 187                        unsigned /*flags*/, unsigned /*steps*/, grand */*r*/,
 188                        pgen_proc */*ev*/, void */*ec*/);
 189
 190 /* --- @dh_checkparam@ --- *
 191  *
 192  * Arguments:   @keycheck *kc@ = keycheck state
 193  *              @const dh_param *dp@ = pointer to the parameter set
 194  *              @mp **v@ = optional vector of factors
 195  *              @size_t n@ = size of vector
 196  *
 197  * Returns:     Zero if all OK, or return status from function.
 198  *
 199  * Use:         Checks a set of Diffie-Hellman parameters for consistency and
 200  *              security.
 201  */
 202
 203 extern int dh_checkparam(keycheck */*kc*/, const dh_param */*dp*/,
 204                          mp **/*v*/, size_t /*n*/);
 205
 206 /* ---- @dh_infofromdata@ --- *
 207  *
 208  * Arguments:   @dh_param *dp@ = parameters to fill in
 209  *              @pdata *pd@ = packed data structure
 210  *
 211  * Returns:     ---
 212  *
 213  * Use:         Fills in a parameters structure from a packed data block.
 214  */
 215
 216 struct pdata;
 217 extern void dh_infofromdata(dh_param */*dp*/, struct pdata */*pd*/);
 218
 219 /* --- @dh_parse@, @dhbin_parse@ --- *
 220  *
 221  * Arguments:   @qd_parse *qd@ = parser context
 222  *              @dh_param *dp@ = parameters to fill in
 223  *
 224  * Returns:     Zero if OK, nonzero on error.
 225  *
 226  * Use:         Parses a prime/binary group string.  This is either one of
 227  *              the standard group strings, or a %$p$%, %$q$%, %$g$% triple
 228  *              separated by commas.
 229  */
 230
 231 extern int dh_parse(qd_parse */*qd*/, dh_param */*dp*/);
 232 extern int dhbin_parse(qd_parse */*qd*/, gbin_param */*gb*/);
 233
 234 /*----- That's all, folks -------------------------------------------------*/
 235
 236 #ifdef __cplusplus
 237   }
 238 #endif
 239
 240 #endif