8b810a45 |
1 | /* -*-c-*- |
2 | * |
b92da8eb |
3 | * $Id: dsa.h,v 1.6 2000/07/01 11:20:51 mdw Exp $ |
8b810a45 |
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 $ |
b92da8eb |
33 | * Revision 1.6 2000/07/01 11:20:51 mdw |
34 | * New functions for freeing public and private keys. |
35 | * |
80a2ff16 |
36 | * Revision 1.5 2000/06/17 10:53:42 mdw |
37 | * Minor changes for key fetching. Typesetting fixes. |
38 | * |
b04a7659 |
39 | * Revision 1.4 1999/12/22 15:52:44 mdw |
40 | * Reworking for new prime-search system. |
41 | * |
b3f05084 |
42 | * Revision 1.3 1999/12/10 23:29:48 mdw |
43 | * Change header file guard names. |
44 | * |
987bb691 |
45 | * Revision 1.2 1999/11/20 22:23:48 mdw |
46 | * Allow event handler to abort the search process. |
47 | * |
8b810a45 |
48 | * Revision 1.1 1999/11/19 19:28:00 mdw |
49 | * Implementation of the Digital Signature Algorithm. |
50 | * |
51 | */ |
52 | |
b3f05084 |
53 | #ifndef CATACOMB_DSA_H |
54 | #define CATACOMB_DSA_H |
8b810a45 |
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 | |
80a2ff16 |
71 | #ifndef CATACOMB_KEY_H |
72 | # include "key.h" |
73 | #endif |
74 | |
b3f05084 |
75 | #ifndef CATACOMB_MP_H |
8b810a45 |
76 | # include "mp.h" |
77 | #endif |
b04a7659 |
78 | |
79 | #ifndef CATACOMB_PGEN_H |
80 | # include "pgen.h" |
81 | #endif |
8b810a45 |
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 | |
80a2ff16 |
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 | |
8b810a45 |
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 | |
80a2ff16 |
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 | |
b92da8eb |
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 | |
b04a7659 |
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 | |
8b810a45 |
167 | /*----- Functions provided ------------------------------------------------*/ |
168 | |
169 | /* --- @dsa_seed@ --- * |
170 | * |
171 | * Arguments: @dsa_param *dp@ = where to store parameters |
b04a7659 |
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@ |
8b810a45 |
175 | * @const void *k@ = pointer to key material |
176 | * @size_t sz@ = size of key material |
b04a7659 |
177 | * @pgen_proc *event@ = event handler function |
178 | * @void *ectx@ = argument for event handler |
8b810a45 |
179 | * |
b04a7659 |
180 | * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise. |
8b810a45 |
181 | * |
182 | * Use: Generates the DSA shared parameters from a given seed value. |
b04a7659 |
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. |
8b810a45 |
190 | */ |
191 | |
b04a7659 |
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*/); |
8b810a45 |
195 | |
196 | /* --- @dsa_mksig@ --- * |
197 | * |
198 | * Arguments: @const dsa_param *dp@ = pointer to DSA parameters |
b3f05084 |
199 | * @mp *a@ = secret signing key |
200 | * @mp *m@ = message to be signed |
201 | * @mp *k@ = random data |
8b810a45 |
202 | * @mp **rr, **ss@ = where to put output parameters |
203 | * |
204 | * Returns: --- |
205 | * |
206 | * Use: Computes a DSA signature of a message. |
207 | */ |
208 | |
b3f05084 |
209 | extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/, |
210 | mp */*m*/, mp */*k*/, |
8b810a45 |
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 |
b3f05084 |
241 | * @mp *y@ = public verification key |
242 | * @mp *m@ = message which was signed |
243 | * @mp *r, *s@ = the signature |
8b810a45 |
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 | |
b3f05084 |
250 | extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/, |
251 | mp */*m*/, mp */*r*/, mp */*s*/); |
8b810a45 |
252 | |
253 | /* --- @dsa_verify@ --- * |
254 | * |
255 | * Arguments: @const dsa_param *dp@ = pointer to DSA parameters |
b3f05084 |
256 | * @mp *y@ = public verification key |
8b810a45 |
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 | |
b3f05084 |
269 | extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/, |
b92da8eb |
270 | const void */*m*/, size_t /*msz*/, |
271 | const void */*r*/, size_t /*rsz*/, |
272 | const void */*s*/, size_t /*ssz*/); |
8b810a45 |
273 | |
274 | /*----- That's all, folks -------------------------------------------------*/ |
275 | |
276 | #ifdef __cplusplus |
277 | } |
278 | #endif |
279 | |
280 | #endif |