3 * $Id: dh.h,v 1.8 2004/04/01 12:50:09 mdw Exp $
5 * Diffie-Hellman and related public-key systems
7 * (c) 1999 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Catacomb.
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.
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.
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,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.8 2004/04/01 12:50:09 mdw
34 * Add cyclic group abstraction, with test code. Separate off exponentation
35 * functions for better static linking. Fix a buttload of bugs on the way.
36 * Generally ensure that negative exponents do inversion correctly. Add
37 * table of standard prime-field subgroups. (Binary field subgroups are
38 * currently unimplemented but easy to add if anyone ever finds a good one.)
40 * Revision 1.7 2001/02/03 16:08:24 mdw
41 * Add consistency checking for public keys.
43 * Revision 1.6 2000/07/29 10:01:16 mdw
44 * Supply commentry for the Diffie-Hellman parameters. Add Lim-Lee
45 * parameter generation.
47 * Revision 1.5 2000/07/01 11:20:51 mdw
48 * New functions for freeing public and private keys.
50 * Revision 1.4 2000/06/17 10:52:47 mdw
51 * Minor changes for key fetching.
53 * Revision 1.3 2000/02/12 18:21:02 mdw
54 * Overhaul of key management (again).
65 /*----- Header files ------------------------------------------------------*/
67 #ifndef CATACOMB_GROUP_H
71 #ifndef CATACOMB_GRAND_H
75 #ifndef CATACOMB_KEY_H
79 #ifndef CATACOMB_KEYCHECK_H
80 # include "keycheck.h"
83 #ifndef CATACOMB_PGEN_H
87 #ifndef CATACOMB_QDPARSE_H
91 /*----- Data structures ---------------------------------------------------*/
93 typedef gprime_param dh_param
; /* Group parameters */
95 typedef struct dh_pub
{
96 dh_param dp
; /* Shared parameters */
97 mp
*y
; /* Public key */
100 typedef struct dh_priv
{
101 dh_param dp
; /* Shared parameters */
102 mp
*x
; /* Private key */
103 mp
*y
; /* %$y \equiv g^x \pmod{p}$% */
106 /*----- Key fetching ------------------------------------------------------*/
108 extern const key_fetchdef dh_paramfetch
[];
109 #define DH_PARAMFETCHSZ 5
111 extern const key_fetchdef dh_pubfetch
[];
112 #define DH_PUBFETCHSZ 6
114 extern const key_fetchdef dh_privfetch
[];
115 #define DH_PRIVFETCHSZ 9
117 /* --- @dh_paramfree@, @dh_pubfree@, @dh_privfree@ --- *
119 * Arguments: @dh_param *dp@, @dh_pub *dp@, @dh_priv *dp@ = pointer to
124 * Use: Frees a Diffie-Hellman key block.
127 extern void dh_paramfree(dh_param */
*dp*/
);
128 extern void dh_pubfree(dh_pub */
*dp*/
);
129 extern void dh_privfree(dh_priv */
*dp*/
);
131 /*----- Functions provided ------------------------------------------------*/
133 /* --- @dh_gen@ --- *
135 * Arguments: @dh_param *dp@ = pointer to output parameter block
136 * @unsigned ql@ = length of %$q$% in bits, or zero
137 * @unsigned pl@ = length of %$p$% in bits
138 * @unsigned steps@ = number of steps to go
139 * @grand *r@ = random number source
140 * @pgen_proc *event@ = event handler function
141 * @void *ectx@ = argument for the event handler
143 * Returns: @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
145 * Use: Generates Diffie-Hellman parameters.
147 * The parameters are a prime %$q$%, relatively small, and a
148 * large prime %$p = kq + 1$% for some %$k$%, together with a
149 * generator %$g$% of the cyclic subgroup of order %$q$%. These
150 * are actually the same as the DSA parameter set, but the
151 * generation algorithm is different. Also, if @ql@ is zero,
152 * this algorithm forces %$k = 2$%, and chooses %$g = 4$%. Make
153 * sure you have something interesting to do if you choose this
157 extern int dh_gen(dh_param */
*dp*/
, unsigned /*ql*/, unsigned /*pl*/,
158 unsigned /*steps*/, grand */
*r*/
, pgen_proc */
*event*/
,
161 /* --- @dh_limlee@ --- *
163 * Arguments: @dh_param *dp@ = pointer to output parameter block
164 * @unsigned ql@ = length of smallest factor of %$(p - 1)/2$%
165 * @unsigned pl@ = length of %$p$% in bits
166 * @unsigned flags@ = other generation flags
167 * @unsigned steps@ = number of steps to go
168 * @grand *r@ = random number source
169 * @pgen_proc *oev@ = outer event handler function
170 * @void *oec@ = argument for the outer event handler
171 * @pgen_proc *iev@ = inner event handler function
172 * @void *iec@ = argument for the inner event handler
173 * @size_t *nf@, @mp ***f@ = output array for factors
175 * Returns: @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
177 * Use: Generates Diffie-Hellman parameters based on a Lim-Lee prime.
179 * The modulus is a large prime %$p = 2 \prod q_i + 1$%, @pl@
180 * bits long, where the %$q_i$% are smaller primes each at least
181 * @ql@ bits long. It is safe to set @nf@ and @f@ to zero if
182 * you're not interested in the factor values.
184 * The returned %$g$% generates a subgroup of order %$q_0$% (the
185 * first factor, returned as @f[0]@), if the flag @DH_SUBGROUP@
186 * is set on entry; otherwise %$g$% will have order
190 #define DH_SUBGROUP 1u
192 extern int dh_limlee(dh_param */
*dp*/
, unsigned /*ql*/, unsigned /*pl*/,
193 unsigned /*flags*/, unsigned /*steps*/, grand */
*r*/
,
194 pgen_proc */
*oev*/
, void */
*oec*/
, pgen_proc */
*iev*/
,
195 void */
*iec*/
, size_t */
*nf*/
, mp
***/
*f*/
);
197 /* --- @dh_checkparam@ --- *
199 * Arguments: @keycheck *kc@ = keycheck state
200 * @const dh_param *dp@ = pointer to the parameter set
201 * @mp **v@ = optional vector of factors
202 * @size_t n@ = size of vector
204 * Returns: Zero if all OK, or return status from function.
206 * Use: Checks a set of Diffie-Hellman parameters for consistency and
210 extern int dh_checkparam(keycheck */
*kc*/
, const dh_param */
*dp*/
,
211 mp
**/
*v*/
, size_t /*n*/);
213 /* --- @dh_parse@ --- *
215 * Arguments: @qd_parse *qd@ = parser context
216 * @dh_param *dp@ = parameters to fill in
218 * Returns: Zero if OK, nonzero on error.
220 * Use: Parses a prime group string. This is either one of the
221 * standard group strings, or a %$p$%, %$q$%, %$g$% triple
222 * separated by commas.
225 extern int dh_parse(qd_parse */
*qd*/
, dh_param */
*dp*/
);
227 /*----- That's all, folks -------------------------------------------------*/