e891b40a755c08ad94ecc1cd073638f8c15c7eaf
[u/mdw/catacomb] / dsa.h
1 /* -*-c-*-
2 *
3 * $Id: dsa.h,v 1.5 2000/06/17 10:53:42 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.5 2000/06/17 10:53:42 mdw
34 * Minor changes for key fetching. Typesetting fixes.
35 *
36 * Revision 1.4 1999/12/22 15:52:44 mdw
37 * Reworking for new prime-search system.
38 *
39 * Revision 1.3 1999/12/10 23:29:48 mdw
40 * Change header file guard names.
41 *
42 * Revision 1.2 1999/11/20 22:23:48 mdw
43 * Allow event handler to abort the search process.
44 *
45 * Revision 1.1 1999/11/19 19:28:00 mdw
46 * Implementation of the Digital Signature Algorithm.
47 *
48 */
49
50 #ifndef CATACOMB_DSA_H
51 #define CATACOMB_DSA_H
52
53 #ifdef __cplusplus
54 extern "C" {
55 #endif
56
57 /*----- Notes on the Digital Signature Algorithm --------------------------*
58 *
59 * The Digital Signature Algorithm was designed by the NSA for US Government
60 * use. It's defined in FIPS 186-1. Whether it's covered by patents is
61 * under dispute, although it looks relatively clear. It produces compact
62 * signatures, and is relatively easy to compute. It seems strong, if
63 * appropriate parameters are chosen.
64 */
65
66 /*----- Header files ------------------------------------------------------*/
67
68 #ifndef CATACOMB_KEY_H
69 # include "key.h"
70 #endif
71
72 #ifndef CATACOMB_MP_H
73 # include "mp.h"
74 #endif
75
76 #ifndef CATACOMB_PGEN_H
77 # include "pgen.h"
78 #endif
79
80 /*----- Data structures ---------------------------------------------------*/
81
82 /* --- DSA parameter structure --- *
83 *
84 * These parameters can, and probably should, be shared among a group of
85 * users.
86 */
87
88 typedef struct dsa_param {
89 mp *p, *q; /* Prime numbers %$p$% and %$q$% */
90 mp *g; /* Generates order-%$q$% subgroup */
91 } dsa_param;
92
93 typedef struct dsa_pub {
94 dsa_param dp; /* Shared parameters */
95 mp *y; /* Public key */
96 } dsa_pub;
97
98 typedef struct dsa_priv {
99 dsa_param dp; /* Shared parameters */
100 mp *x; /* Private key */
101 mp *y; /* %$y \equiv g^x \pmod{p}$% */
102 } dsa_priv;
103
104 /* --- DSA signature structure --- *
105 *
106 * This is the recommended structure for a DSA signature. The actual signing
107 * function can cope with arbitrary-sized objects given appropriate
108 * parameters, however.
109 */
110
111 #define DSA_SIGLEN 20
112
113 typedef struct dsa_sig {
114 octet r[DSA_SIGLEN]; /* 160-bit @r@ value */
115 octet s[DSA_SIGLEN]; /* 160-bit @s@ value */
116 } dsa_sig;
117
118 /*----- Key fetching ------------------------------------------------------*/
119
120 extern const key_fetchdef dsa_paramfetch[];
121 #define DSA_PARAMFETCHSZ 5
122
123 extern const key_fetchdef dsa_pubfetch[];
124 #define DSA_PUBFETCHSZ 6
125
126 extern const key_fetchdef dsa_privfetch[];
127 #define DSA_PRIVFETCHSZ 9
128
129 /*----- DSA stepper -------------------------------------------------------*/
130
131 typedef struct dsa_stepctx {
132
133 /* --- To be initialized by the client --- */
134
135 grand *r; /* Random number generator */
136 mp *q; /* Force @p@ to be a multiple */
137 size_t bits; /* Number of bits in the result */
138 unsigned or; /* OR mask for low order bits */
139 } dsa_stepctx;
140
141 /* --- @dsa_step@ --- *
142 *
143 * The stepper chooses random integers, ensures that they are a multiple of
144 * @q@ (if specified), sets the low-order bits, and then tests for
145 * divisibility by small primes.
146 */
147
148 extern int dsa_step(int /*rq*/, pgen_event */*ev*/, void */*p*/);
149
150 /*----- Functions provided ------------------------------------------------*/
151
152 /* --- @dsa_seed@ --- *
153 *
154 * Arguments: @dsa_param *dp@ = where to store parameters
155 * @unsigned ql@ = length of @q@ in bits
156 * @unsigned pl@ = length of @p@ in bits
157 * @unsigned steps@ = number of steps to find @q@
158 * @const void *k@ = pointer to key material
159 * @size_t sz@ = size of key material
160 * @pgen_proc *event@ = event handler function
161 * @void *ectx@ = argument for event handler
162 *
163 * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise.
164 *
165 * Use: Generates the DSA shared parameters from a given seed value.
166 * This can take quite a long time.
167 *
168 * The algorithm used is a compatible extension of the method
169 * described in the DSA standard, FIPS 186. The standard
170 * requires that %$q$% be 160 bits in size (i.e., @ql == 160@)
171 * and that the length of %$p$% be %$L = 512 + 64l$% for some
172 * %$l$%. Neither limitation applies to this implementation.
173 */
174
175 extern int dsa_seed(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/,
176 unsigned /*steps*/, const void */*k*/, size_t /*sz*/,
177 pgen_proc */*event*/, void */*ectx*/);
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