8b810a45 |
1 | /* -*-c-*- |
2 | * |
827e6c99 |
3 | * $Id: dsa.h,v 1.7 2000/07/29 09:59:44 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 $ |
827e6c99 |
33 | * Revision 1.7 2000/07/29 09:59:44 mdw |
34 | * Share data structures with Diffie-Hellman stuff. |
35 | * |
b92da8eb |
36 | * Revision 1.6 2000/07/01 11:20:51 mdw |
37 | * New functions for freeing public and private keys. |
38 | * |
80a2ff16 |
39 | * Revision 1.5 2000/06/17 10:53:42 mdw |
40 | * Minor changes for key fetching. Typesetting fixes. |
41 | * |
b04a7659 |
42 | * Revision 1.4 1999/12/22 15:52:44 mdw |
43 | * Reworking for new prime-search system. |
44 | * |
b3f05084 |
45 | * Revision 1.3 1999/12/10 23:29:48 mdw |
46 | * Change header file guard names. |
47 | * |
987bb691 |
48 | * Revision 1.2 1999/11/20 22:23:48 mdw |
49 | * Allow event handler to abort the search process. |
50 | * |
8b810a45 |
51 | * Revision 1.1 1999/11/19 19:28:00 mdw |
52 | * Implementation of the Digital Signature Algorithm. |
53 | * |
54 | */ |
55 | |
b3f05084 |
56 | #ifndef CATACOMB_DSA_H |
57 | #define CATACOMB_DSA_H |
8b810a45 |
58 | |
59 | #ifdef __cplusplus |
60 | extern "C" { |
61 | #endif |
62 | |
63 | /*----- Notes on the Digital Signature Algorithm --------------------------* |
64 | * |
65 | * The Digital Signature Algorithm was designed by the NSA for US Government |
66 | * use. It's defined in FIPS 186-1. Whether it's covered by patents is |
67 | * under dispute, although it looks relatively clear. It produces compact |
68 | * signatures, and is relatively easy to compute. It seems strong, if |
69 | * appropriate parameters are chosen. |
70 | */ |
71 | |
72 | /*----- Header files ------------------------------------------------------*/ |
73 | |
827e6c99 |
74 | #ifndef CATACOMB_DH_H |
75 | # include "dh.h" |
76 | #endif |
77 | |
80a2ff16 |
78 | #ifndef CATACOMB_KEY_H |
79 | # include "key.h" |
80 | #endif |
81 | |
b3f05084 |
82 | #ifndef CATACOMB_MP_H |
8b810a45 |
83 | # include "mp.h" |
84 | #endif |
b04a7659 |
85 | |
86 | #ifndef CATACOMB_PGEN_H |
87 | # include "pgen.h" |
88 | #endif |
8b810a45 |
89 | |
90 | /*----- Data structures ---------------------------------------------------*/ |
91 | |
827e6c99 |
92 | /* --- The parameters and keys are the same as for Diffie-Hellman --- */ |
80a2ff16 |
93 | |
827e6c99 |
94 | typedef dh_param dsa_param; |
95 | typedef dh_pub dsa_pub; |
96 | typedef dh_priv dsa_priv; |
80a2ff16 |
97 | |
8b810a45 |
98 | /* --- DSA signature structure --- * |
99 | * |
100 | * This is the recommended structure for a DSA signature. The actual signing |
101 | * function can cope with arbitrary-sized objects given appropriate |
102 | * parameters, however. |
103 | */ |
104 | |
105 | #define DSA_SIGLEN 20 |
106 | |
107 | typedef struct dsa_sig { |
108 | octet r[DSA_SIGLEN]; /* 160-bit @r@ value */ |
109 | octet s[DSA_SIGLEN]; /* 160-bit @s@ value */ |
110 | } dsa_sig; |
111 | |
80a2ff16 |
112 | /*----- Key fetching ------------------------------------------------------*/ |
113 | |
827e6c99 |
114 | #define dsa_paramfetch dh_paramfetch |
115 | #define dsa_pubfetch dh_pubfetch |
116 | #define dsa_privfetch dh_privfetch |
80a2ff16 |
117 | |
827e6c99 |
118 | #define DSA_PARAMFETCHSZ DH_PARAMFETCHSZ |
119 | #define DSA_PUBFETCHSZ DH_PUBFETCHSZ |
120 | #define DSA_PRIVFETCHSZ DH_PRIVFETCHSZ |
b92da8eb |
121 | |
827e6c99 |
122 | #define dsa_paramfree dh_paramfree |
123 | #define dsa_pubfree dh_pubfree |
124 | #define dsa_privfree dh_privfree |
b92da8eb |
125 | |
b04a7659 |
126 | /*----- DSA stepper -------------------------------------------------------*/ |
127 | |
128 | typedef struct dsa_stepctx { |
129 | |
130 | /* --- To be initialized by the client --- */ |
131 | |
132 | grand *r; /* Random number generator */ |
133 | mp *q; /* Force @p@ to be a multiple */ |
134 | size_t bits; /* Number of bits in the result */ |
135 | unsigned or; /* OR mask for low order bits */ |
136 | } dsa_stepctx; |
137 | |
138 | /* --- @dsa_step@ --- * |
139 | * |
140 | * The stepper chooses random integers, ensures that they are a multiple of |
141 | * @q@ (if specified), sets the low-order bits, and then tests for |
142 | * divisibility by small primes. |
143 | */ |
144 | |
145 | extern int dsa_step(int /*rq*/, pgen_event */*ev*/, void */*p*/); |
146 | |
8b810a45 |
147 | /*----- Functions provided ------------------------------------------------*/ |
148 | |
827e6c99 |
149 | /* --- @dsa_gen@ --- * |
8b810a45 |
150 | * |
151 | * Arguments: @dsa_param *dp@ = where to store parameters |
b04a7659 |
152 | * @unsigned ql@ = length of @q@ in bits |
153 | * @unsigned pl@ = length of @p@ in bits |
154 | * @unsigned steps@ = number of steps to find @q@ |
8b810a45 |
155 | * @const void *k@ = pointer to key material |
156 | * @size_t sz@ = size of key material |
b04a7659 |
157 | * @pgen_proc *event@ = event handler function |
158 | * @void *ectx@ = argument for event handler |
8b810a45 |
159 | * |
b04a7659 |
160 | * Returns: @PGEN_DONE@ if everything worked ok; @PGEN_ABORT@ otherwise. |
8b810a45 |
161 | * |
162 | * Use: Generates the DSA shared parameters from a given seed value. |
b04a7659 |
163 | * This can take quite a long time. |
164 | * |
165 | * The algorithm used is a compatible extension of the method |
166 | * described in the DSA standard, FIPS 186. The standard |
167 | * requires that %$q$% be 160 bits in size (i.e., @ql == 160@) |
168 | * and that the length of %$p$% be %$L = 512 + 64l$% for some |
169 | * %$l$%. Neither limitation applies to this implementation. |
8b810a45 |
170 | */ |
171 | |
827e6c99 |
172 | extern int dsa_gen(dsa_param */*dp*/, unsigned /*ql*/, unsigned /*pl*/, |
173 | unsigned /*steps*/, const void */*k*/, size_t /*sz*/, |
174 | pgen_proc */*event*/, void */*ectx*/); |
8b810a45 |
175 | |
176 | /* --- @dsa_mksig@ --- * |
177 | * |
178 | * Arguments: @const dsa_param *dp@ = pointer to DSA parameters |
b3f05084 |
179 | * @mp *a@ = secret signing key |
180 | * @mp *m@ = message to be signed |
181 | * @mp *k@ = random data |
8b810a45 |
182 | * @mp **rr, **ss@ = where to put output parameters |
183 | * |
184 | * Returns: --- |
185 | * |
186 | * Use: Computes a DSA signature of a message. |
187 | */ |
188 | |
b3f05084 |
189 | extern void dsa_mksig(const dsa_param */*dp*/, mp */*a*/, |
190 | mp */*m*/, mp */*k*/, |
8b810a45 |
191 | mp **/*rr*/, mp **/*ss*/); |
192 | |
193 | /* --- @dsa_sign@ --- * |
194 | * |
195 | * Arguments: @dsa_param *dp@ = pointer to DSA parameters |
196 | * @mp *a@ = pointer to secret signing key |
197 | * @const void *m@ = pointer to message |
198 | * @size_t msz@ = size of the message |
199 | * @const void *k@ = secret random data for securing signature |
200 | * @size_t ksz@ = size of secret data |
201 | * @void *r@ = pointer to output space for @r@ |
202 | * @size_t rsz@ = size of output space for @r@ |
203 | * @void *s@ = pointer to output space for @s@ |
204 | * @size_t ssz@ = size of output space for @s@ |
205 | * |
206 | * Returns: --- |
207 | * |
208 | * Use: Signs a message, storing the results in a big-endian binary |
209 | * form. |
210 | */ |
211 | |
212 | extern void dsa_sign(dsa_param */*dp*/, mp */*a*/, |
213 | const void */*m*/, size_t /*msz*/, |
214 | const void */*k*/, size_t /*ksz*/, |
215 | void */*r*/, size_t /*rsz*/, |
216 | void */*s*/, size_t /*ssz*/); |
217 | |
218 | /* --- @dsa_vrfy@ --- * |
219 | * |
220 | * Arguments: @const dsa_param *dp@ = pointer to DSA parameters |
b3f05084 |
221 | * @mp *y@ = public verification key |
222 | * @mp *m@ = message which was signed |
223 | * @mp *r, *s@ = the signature |
8b810a45 |
224 | * |
225 | * Returns: Zero if the signature is a forgery, nonzero if it's valid. |
226 | * |
227 | * Use: Verifies a DSA digital signature. |
228 | */ |
229 | |
b3f05084 |
230 | extern int dsa_vrfy(const dsa_param */*dp*/, mp */*y*/, |
231 | mp */*m*/, mp */*r*/, mp */*s*/); |
8b810a45 |
232 | |
233 | /* --- @dsa_verify@ --- * |
234 | * |
235 | * Arguments: @const dsa_param *dp@ = pointer to DSA parameters |
b3f05084 |
236 | * @mp *y@ = public verification key |
8b810a45 |
237 | * @const void *m@ = pointer to message block |
238 | * @size_t msz@ = size of message block |
239 | * @const void *r@ = pointer to @r@ signature half |
240 | * @size_t rsz@ = size of @r@ |
241 | * @const void *s@ = pointer to @s@ signature half |
242 | * @size_t ssz@ = size of @s@ |
243 | * |
244 | * Returns: Zero if the signature is a forgery, nonzero if it's valid. |
245 | * |
246 | * Use: Verifies a DSA digital signature. |
247 | */ |
248 | |
b3f05084 |
249 | extern int dsa_verify(const dsa_param */*dp*/, mp */*y*/, |
b92da8eb |
250 | const void */*m*/, size_t /*msz*/, |
251 | const void */*r*/, size_t /*rsz*/, |
252 | const void */*s*/, size_t /*ssz*/); |
8b810a45 |
253 | |
254 | /*----- That's all, folks -------------------------------------------------*/ |
255 | |
256 | #ifdef __cplusplus |
257 | } |
258 | #endif |
259 | |
260 | #endif |