01898d8e |
1 | /* -*-c-*- |
2 | * |
7ec885b3 |
3 | * $Id: rsa.h,v 1.3 2000/07/01 11:24:37 mdw Exp $ |
01898d8e |
4 | * |
5 | * The RSA public-key cryptosystem |
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: rsa.h,v $ |
7ec885b3 |
33 | * Revision 1.3 2000/07/01 11:24:37 mdw |
34 | * Remove bad type name `rsa_param'. New functions for freeing public and |
35 | * private keys. Add types and functions for doing pubic key operations, |
36 | * and padded RSA operations. |
37 | * |
81e9d7ec |
38 | * Revision 1.2 2000/06/17 12:07:36 mdw |
39 | * Add key fetching interface. Add new rsa_decrypt interface. |
40 | * |
01898d8e |
41 | * Revision 1.1 1999/12/22 15:50:45 mdw |
42 | * Initial RSA support. |
43 | * |
44 | */ |
45 | |
46 | #ifndef CATACOMB_RSA_H |
47 | #define CATACOMB_RSA_H |
48 | |
49 | #ifdef __cplusplus |
50 | extern "C" { |
51 | #endif |
52 | |
53 | /*----- Header files ------------------------------------------------------*/ |
54 | |
55 | #ifndef CATACOMB_GRAND_H |
56 | # include "grand.h" |
57 | #endif |
58 | |
81e9d7ec |
59 | #ifndef CATACOMB_KEY_H |
60 | # include "key.h" |
61 | #endif |
62 | |
01898d8e |
63 | #ifndef CATACOMB_MP_H |
64 | # include "mp.h" |
65 | #endif |
66 | |
67 | #ifndef CATACOMB_PGEN_H |
68 | # include "pgen.h" |
69 | #endif |
70 | |
71 | /*----- Data structures ---------------------------------------------------*/ |
72 | |
7ec885b3 |
73 | /* --- RSA private and public keys --- */ |
74 | |
81e9d7ec |
75 | typedef struct rsa_pub { |
01898d8e |
76 | mp *n; |
81e9d7ec |
77 | mp *e; |
78 | } rsa_pub; |
79 | |
7ec885b3 |
80 | typedef struct rsa_priv { |
81e9d7ec |
81 | mp *n, *p, *q, *q_inv; |
01898d8e |
82 | mp *e, *d, *dp, *dq; |
7ec885b3 |
83 | } rsa_priv; |
81e9d7ec |
84 | |
7ec885b3 |
85 | /* --- RSA private and public key contexts --- * |
86 | * |
87 | * These are used to store information about `active' keys which will speed |
88 | * up the various operations. |
89 | */ |
90 | |
91 | typedef struct rsa_privctx { |
92 | rsa_priv *rp; |
81e9d7ec |
93 | grand *r; |
94 | mpmont nm, pm, qm; |
7ec885b3 |
95 | } rsa_privctx; |
96 | |
97 | typedef struct rsa_pubctx { |
98 | mpmont mm; |
99 | rsa_pub *rp; |
100 | } rsa_pubctx; |
101 | |
102 | /* --- Encoding and decoding function schemas --- * |
103 | * |
104 | * See `oaep.h' and `pkcs1.h' for appropriate encoding functions. |
105 | */ |
106 | |
107 | typedef int (*rsa_encodeproc)(const void */*m*/, size_t /*msz*/, |
108 | void */*buf*/, size_t /*sz*/, void */*p*/); |
109 | typedef int (*rsa_decodeproc)(const void */*m*/, size_t /*msz*/, |
110 | dstr */*d*/, void */*p*/); |
81e9d7ec |
111 | |
112 | /*----- Key fetching ------------------------------------------------------*/ |
113 | |
114 | extern const key_fetchdef rsa_pubfetch[]; |
115 | #define RSA_PUBFETCHSZ 4 |
116 | |
117 | extern const key_fetchdef rsa_privfetch[]; |
118 | #define RSA_PRIVFETCHSZ 12 |
01898d8e |
119 | |
7ec885b3 |
120 | /* --- @rsa_pubfree@, @rsa_privfree@ --- * |
01898d8e |
121 | * |
7ec885b3 |
122 | * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block |
01898d8e |
123 | * |
7ec885b3 |
124 | * Returns: --- |
01898d8e |
125 | * |
7ec885b3 |
126 | * Use: Frees an RSA key block. |
01898d8e |
127 | */ |
128 | |
7ec885b3 |
129 | extern void rsa_pubfree(rsa_pub */*rp*/); |
130 | extern void rsa_privfree(rsa_priv */*rp*/); |
131 | |
132 | /*----- RSA private key operations ----------------------------------------*/ |
01898d8e |
133 | |
7ec885b3 |
134 | /* --- @rsa_privcreate@ --- * |
81e9d7ec |
135 | * |
7ec885b3 |
136 | * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key context |
81e9d7ec |
137 | * @rsa_priv *rp@ = pointer to RSA private key |
138 | * @grand *r@ = pointer to random number source for blinding |
139 | * |
140 | * Returns: --- |
141 | * |
7ec885b3 |
142 | * Use: Initializes an RSA private-key context. Keeping a context |
81e9d7ec |
143 | * for several decryption or signing operations provides a minor |
144 | * performance benefit. |
145 | * |
146 | * The random number source may be null if blinding is not |
147 | * desired. This improves decryption speed, at the risk of |
148 | * permitting timing attacks. |
149 | */ |
150 | |
7ec885b3 |
151 | extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/, |
152 | grand */*r*/); |
81e9d7ec |
153 | |
7ec885b3 |
154 | /* --- @rsa_privdestroy@ --- * |
81e9d7ec |
155 | * |
7ec885b3 |
156 | * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context |
81e9d7ec |
157 | * |
158 | * Returns: --- |
159 | * |
160 | * Use: Destroys an RSA decryption context. |
161 | */ |
162 | |
7ec885b3 |
163 | extern void rsa_privdestroy(rsa_privctx */*rd*/); |
81e9d7ec |
164 | |
7ec885b3 |
165 | /* --- @rsa_privop@ --- * |
81e9d7ec |
166 | * |
7ec885b3 |
167 | * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context |
81e9d7ec |
168 | * @mp *d@ = destination |
7ec885b3 |
169 | * @mp *c@ = input message |
81e9d7ec |
170 | * |
7ec885b3 |
171 | * Returns: The transformed output message. |
81e9d7ec |
172 | * |
7ec885b3 |
173 | * Use: Performs an RSA private key operation. This function takes |
174 | * advantage of knowledge of the key factors in order to speed |
175 | * up decryption. It also blinds the ciphertext prior to |
81e9d7ec |
176 | * decryption and unblinds it afterwards to thwart timing |
177 | * attacks. |
178 | */ |
179 | |
7ec885b3 |
180 | extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/); |
81e9d7ec |
181 | |
7ec885b3 |
182 | /* --- @rsa_qprivop@ --- * |
01898d8e |
183 | * |
7ec885b3 |
184 | * Arguments: @rsa_priv *rp@ = pointer to RSA parameters |
01898d8e |
185 | * @mp *d@ = destination |
7ec885b3 |
186 | * @mp *c@ = input message |
01898d8e |
187 | * @grand *r@ = pointer to random number source for blinding |
188 | * |
7ec885b3 |
189 | * Returns: Correctly transformed output message |
190 | * |
191 | * Use: Performs an RSA private key operation, very carefully. |
192 | */ |
193 | |
194 | extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/); |
195 | |
196 | /* --- @rsa_sign@ --- * |
197 | * |
198 | * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context |
199 | * @const void *m@ = pointer to input message |
200 | * @size_t sz@ = size of input message |
201 | * @dstr *d@ = pointer to output string |
202 | * @rsa_encodeproc e@ = encoding procedure |
203 | * @void *earg@ = argument pointer for encoding procedure |
204 | * |
205 | * Returns: The length of the output string if successful, negative on |
206 | * failure. |
01898d8e |
207 | * |
7ec885b3 |
208 | * Use: Computes an RSA digital signature. |
01898d8e |
209 | */ |
210 | |
7ec885b3 |
211 | extern int rsa_sign(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/, |
212 | dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/); |
213 | |
214 | /* --- @rsa_decrypt@ --- * |
215 | * |
216 | * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context |
217 | * @const void *m@ = pointer to input message |
218 | * @size_t sz@ = size of input message |
219 | * @dstr *d@ = pointer to output string |
220 | * @rsa_decodeproc e@ = decoding procedure |
221 | * @void *earg@ = argument pointer for decoding procedure |
222 | * |
223 | * Returns: The length of the output string if successful, negative on |
224 | * failure. |
225 | * |
226 | * Use: Does RSA signature verification. |
227 | */ |
228 | |
229 | extern int rsa_decrypt(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/, |
230 | dstr */*d*/, rsa_decodeproc /*e*/, void */*earg*/); |
231 | |
232 | /*----- RSA public key operations -----------------------------------------*/ |
233 | |
234 | /* --- @rsa_pubcreate@ --- * |
235 | * |
236 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
237 | * @rsa_pub *rp@ = pointer to RSA public key |
238 | * |
239 | * Returns: --- |
240 | * |
241 | * Use: Initializes an RSA public-key context. |
242 | */ |
243 | |
244 | extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/); |
245 | |
246 | /* --- @rsa_pubdestroy@ --- * |
247 | * |
248 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
249 | * |
250 | * Returns: --- |
251 | * |
252 | * Use: Destroys an RSA public-key context. |
253 | */ |
254 | |
255 | extern void rsa_pubdestroy(rsa_pubctx */*rd*/); |
256 | |
257 | /* --- @rsa_pubop@ --- * |
258 | * |
259 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
260 | * @mp *d@ = destination |
261 | * @mp *p@ = input message |
262 | * |
263 | * Returns: The transformed output message. |
264 | * |
265 | * Use: Performs an RSA public key operation. |
266 | */ |
267 | |
268 | extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/); |
269 | |
270 | /* --- @rsa_qpubop@ --- * |
271 | * |
272 | * Arguments: @rsa_pub *rp@ = pointer to RSA parameters |
273 | * @mp *d@ = destination |
274 | * @mp *p@ = input message |
275 | * |
276 | * Returns: Correctly transformed output message. |
277 | * |
278 | * Use: Performs an RSA public key operation. |
279 | */ |
280 | |
281 | extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/); |
282 | |
283 | /* --- @rsa_encrypt@ --- * |
284 | * |
285 | * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key context |
286 | * @const void *m@ = pointer to input message |
287 | * @size_t sz@ = size of input message |
288 | * @dstr *d@ = pointer to output string |
289 | * @rsa_encodeproc e@ = encoding procedure |
290 | * @void *earg@ = argument pointer for encoding procedure |
291 | * |
292 | * Returns: The length of the output string if successful, negative on |
293 | * failure. |
294 | * |
295 | * Use: Does RSA encryption. |
296 | */ |
297 | |
298 | extern int rsa_encrypt(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/, |
299 | dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/); |
300 | |
301 | /* --- @rsa_verify@ --- * |
302 | * |
303 | * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt |
304 | * @const void *m@ = pointer to input message |
305 | * @size_t sz@ = size of input message |
306 | * @dstr *d@ = pointer to output string |
307 | * @rsa_decodeproc e@ = decoding procedure |
308 | * @void *earg@ = argument pointer for decoding procedure |
309 | * |
310 | * Returns: The length of the output string if successful, negative on |
311 | * failure. |
312 | * |
313 | * Use: Does RSA signature verification. |
314 | */ |
315 | |
316 | extern int rsa_verify(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/, |
317 | dstr */*d*/, rsa_decodeproc /*e*/, void */*earg*/); |
318 | |
319 | /*----- Miscellaneous operations ------------------------------------------*/ |
320 | |
321 | /* --- @rsa_gen@ --- * |
322 | * |
323 | * Arguments: @rsa_priv *rp@ = pointer to block to be filled in |
324 | * @unsigned nbits@ = required modulus size in bits |
325 | * @grand *r@ = random number source |
326 | * @unsigned n@ = number of attempts to make |
327 | * @pgen_proc *event@ = event handler function |
328 | * @void *ectx@ = argument for the event handler |
329 | * |
330 | * Returns: Zero if all went well, nonzero otherwise. |
331 | * |
332 | * Use: Constructs a pair of strong RSA primes and other useful RSA |
333 | * parameters. A small encryption exponent is chosen if |
334 | * possible. |
335 | */ |
336 | |
337 | extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/, |
338 | grand */*r*/, unsigned /*n*/, |
339 | pgen_proc */*event*/, void */*ectx*/); |
01898d8e |
340 | |
341 | /* --- @rsa_recover@ --- * |
342 | * |
7ec885b3 |
343 | * Arguments: @rsa_priv *rp@ = pointer to parameter block |
01898d8e |
344 | * |
345 | * Returns: Zero if all went well, nonzero if the parameters make no |
346 | * sense. |
347 | * |
348 | * Use: Derives the full set of RSA parameters given a minimal set. |
349 | */ |
350 | |
7ec885b3 |
351 | extern int rsa_recover(rsa_priv */*rp*/); |
01898d8e |
352 | |
353 | /*----- That's all, folks -------------------------------------------------*/ |
354 | |
355 | #ifdef __cplusplus |
356 | } |
357 | #endif |
358 | |
359 | #endif |