3 * Diffie-Hellman and related public-key systems
5 * (c) 1999 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
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.
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.
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,
35 /*----- Header files ------------------------------------------------------*/
37 #ifndef CATACOMB_GROUP_H
41 #ifndef CATACOMB_GRAND_H
45 #ifndef CATACOMB_KEY_H
49 #ifndef CATACOMB_KEYCHECK_H
50 # include "keycheck.h"
53 #ifndef CATACOMB_PGEN_H
57 #ifndef CATACOMB_QDPARSE_H
61 /*----- Data structures ---------------------------------------------------*/
63 typedef gprime_param dh_param; /* Group parameters */
65 typedef struct dh_pub {
66 dh_param dp; /* Shared parameters */
67 mp *y; /* Public key */
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}$% */
76 /*----- Key fetching ------------------------------------------------------*/
78 extern const key_fetchdef dh_paramfetch[];
79 #define DH_PARAMFETCHSZ 5
81 extern const key_fetchdef dh_pubfetch[];
82 #define DH_PUBFETCHSZ 6
84 extern const key_fetchdef dh_privfetch[];
85 #define DH_PRIVFETCHSZ 9
87 /* --- @dh_paramfree@, @dh_pubfree@, @dh_privfree@ --- *
89 * Arguments: @dh_param *dp@, @dh_pub *dp@, @dh_priv *dp@ = pointer to
94 * Use: Frees a Diffie-Hellman key block.
97 extern void dh_paramfree(dh_param */*dp*/);
98 extern void dh_pubfree(dh_pub */*dp*/);
99 extern void dh_privfree(dh_priv */*dp*/);
101 /*----- Functions provided ------------------------------------------------*/
103 /* --- @dh_gen@ --- *
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
113 * Returns: @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
115 * Use: Generates Diffie-Hellman parameters.
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
127 extern int dh_gen(dh_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
128 unsigned /*steps*/, grand */*r*/, pgen_proc */*event*/,
131 /* --- @dh_limlee@ --- *
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
145 * Returns: @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it didn't.
147 * Use: Generates Diffie-Hellman parameters based on a Lim-Lee prime.
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.
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
160 #define DH_SUBGROUP 1u
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*/);
167 /* --- @dh_kcdsagen@ --- *
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
178 * Returns: @PGEN_DONE@ if it worked, @PGEN_ABORT@ if it failed.
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
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*/);
190 /* --- @dh_checkparam@ --- *
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
197 * Returns: Zero if all OK, or return status from function.
199 * Use: Checks a set of Diffie-Hellman parameters for consistency and
203 extern int dh_checkparam(keycheck */*kc*/, const dh_param */*dp*/,
204 mp **/*v*/, size_t /*n*/);
206 /* ---- @dh_infofromdata@ --- *
208 * Arguments: @dh_param *dp@ = parameters to fill in
209 * @pdata *pd@ = packed data structure
213 * Use: Fills in a parameters structure from a packed data block.
217 extern void dh_infofromdata(dh_param */*dp*/, struct pdata */*pd*/);
219 /* --- @dh_parse@, @dhbin_parse@ --- *
221 * Arguments: @qd_parse *qd@ = parser context
222 * @dh_param *dp@ = parameters to fill in
224 * Returns: Zero if OK, nonzero on error.
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.
231 extern int dh_parse(qd_parse */*qd*/, dh_param */*dp*/);
232 extern int dhbin_parse(qd_parse */*qd*/, gbin_param */*gb*/);
234 /*----- That's all, folks -------------------------------------------------*/