01898d8e |
1 | /* -*-c-*- |
2 | * |
b817bfc6 |
3 | * $Id: rsa.h,v 1.4 2004/04/08 01:36:15 mdw Exp $ |
01898d8e |
4 | * |
5 | * The RSA public-key cryptosystem |
6 | * |
7 | * (c) 1999 Straylight/Edgeware |
8 | */ |
9 | |
45c0fd36 |
10 | /*----- Licensing notice --------------------------------------------------* |
01898d8e |
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. |
45c0fd36 |
18 | * |
01898d8e |
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. |
45c0fd36 |
23 | * |
01898d8e |
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 | |
01898d8e |
30 | #ifndef CATACOMB_RSA_H |
31 | #define CATACOMB_RSA_H |
32 | |
33 | #ifdef __cplusplus |
34 | extern "C" { |
35 | #endif |
36 | |
37 | /*----- Header files ------------------------------------------------------*/ |
38 | |
39 | #ifndef CATACOMB_GRAND_H |
40 | # include "grand.h" |
41 | #endif |
42 | |
b817bfc6 |
43 | #ifndef CATACOMB_GCIPHER_H |
44 | # include "gcipher.h" |
45 | #endif |
46 | |
47 | #ifndef CATACOMB_GHASH_H |
48 | # include "ghash.h" |
49 | #endif |
50 | |
81e9d7ec |
51 | #ifndef CATACOMB_KEY_H |
52 | # include "key.h" |
53 | #endif |
54 | |
01898d8e |
55 | #ifndef CATACOMB_MP_H |
56 | # include "mp.h" |
57 | #endif |
58 | |
59 | #ifndef CATACOMB_PGEN_H |
60 | # include "pgen.h" |
61 | #endif |
62 | |
63 | /*----- Data structures ---------------------------------------------------*/ |
64 | |
7ec885b3 |
65 | /* --- RSA private and public keys --- */ |
66 | |
81e9d7ec |
67 | typedef struct rsa_pub { |
01898d8e |
68 | mp *n; |
81e9d7ec |
69 | mp *e; |
70 | } rsa_pub; |
71 | |
7ec885b3 |
72 | typedef struct rsa_priv { |
81e9d7ec |
73 | mp *n, *p, *q, *q_inv; |
01898d8e |
74 | mp *e, *d, *dp, *dq; |
7ec885b3 |
75 | } rsa_priv; |
81e9d7ec |
76 | |
7ec885b3 |
77 | /* --- RSA private and public key contexts --- * |
78 | * |
79 | * These are used to store information about `active' keys which will speed |
80 | * up the various operations. |
81 | */ |
82 | |
83 | typedef struct rsa_privctx { |
84 | rsa_priv *rp; |
81e9d7ec |
85 | grand *r; |
86 | mpmont nm, pm, qm; |
7ec885b3 |
87 | } rsa_privctx; |
88 | |
89 | typedef struct rsa_pubctx { |
90 | mpmont mm; |
91 | rsa_pub *rp; |
92 | } rsa_pubctx; |
93 | |
94 | /* --- Encoding and decoding function schemas --- * |
95 | * |
96 | * See `oaep.h' and `pkcs1.h' for appropriate encoding functions. |
97 | */ |
98 | |
b817bfc6 |
99 | typedef mp *rsa_pad(mp */*d*/, const void */*m*/, size_t /*msz*/, |
100 | octet */*b*/, size_t /*sz*/, |
101 | unsigned long /*nbits*/, void */*p*/); |
102 | |
103 | typedef int rsa_decunpad(mp */*m*/, octet */*b*/, size_t /*sz*/, |
104 | unsigned long /*nbits*/, void */*p*/); |
105 | |
106 | typedef int rsa_vrfunpad(mp */*s*/, const void */*m*/, size_t /*msz*/, |
107 | octet */*b*/, size_t /*sz*/, |
108 | unsigned long /*nbits*/, void */*p*/); |
81e9d7ec |
109 | |
110 | /*----- Key fetching ------------------------------------------------------*/ |
111 | |
112 | extern const key_fetchdef rsa_pubfetch[]; |
113 | #define RSA_PUBFETCHSZ 4 |
114 | |
115 | extern const key_fetchdef rsa_privfetch[]; |
116 | #define RSA_PRIVFETCHSZ 12 |
01898d8e |
117 | |
7ec885b3 |
118 | /* --- @rsa_pubfree@, @rsa_privfree@ --- * |
01898d8e |
119 | * |
7ec885b3 |
120 | * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block |
01898d8e |
121 | * |
7ec885b3 |
122 | * Returns: --- |
01898d8e |
123 | * |
7ec885b3 |
124 | * Use: Frees an RSA key block. |
01898d8e |
125 | */ |
126 | |
7ec885b3 |
127 | extern void rsa_pubfree(rsa_pub */*rp*/); |
128 | extern void rsa_privfree(rsa_priv */*rp*/); |
129 | |
130 | /*----- RSA private key operations ----------------------------------------*/ |
01898d8e |
131 | |
7ec885b3 |
132 | /* --- @rsa_privcreate@ --- * |
81e9d7ec |
133 | * |
7ec885b3 |
134 | * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key context |
81e9d7ec |
135 | * @rsa_priv *rp@ = pointer to RSA private key |
136 | * @grand *r@ = pointer to random number source for blinding |
137 | * |
138 | * Returns: --- |
139 | * |
7ec885b3 |
140 | * Use: Initializes an RSA private-key context. Keeping a context |
81e9d7ec |
141 | * for several decryption or signing operations provides a minor |
142 | * performance benefit. |
143 | * |
144 | * The random number source may be null if blinding is not |
145 | * desired. This improves decryption speed, at the risk of |
146 | * permitting timing attacks. |
147 | */ |
148 | |
7ec885b3 |
149 | extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/, |
150 | grand */*r*/); |
81e9d7ec |
151 | |
7ec885b3 |
152 | /* --- @rsa_privdestroy@ --- * |
81e9d7ec |
153 | * |
7ec885b3 |
154 | * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context |
81e9d7ec |
155 | * |
156 | * Returns: --- |
157 | * |
158 | * Use: Destroys an RSA decryption context. |
159 | */ |
160 | |
7ec885b3 |
161 | extern void rsa_privdestroy(rsa_privctx */*rd*/); |
81e9d7ec |
162 | |
7ec885b3 |
163 | /* --- @rsa_privop@ --- * |
81e9d7ec |
164 | * |
7ec885b3 |
165 | * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context |
81e9d7ec |
166 | * @mp *d@ = destination |
7ec885b3 |
167 | * @mp *c@ = input message |
81e9d7ec |
168 | * |
7ec885b3 |
169 | * Returns: The transformed output message. |
81e9d7ec |
170 | * |
7ec885b3 |
171 | * Use: Performs an RSA private key operation. This function takes |
172 | * advantage of knowledge of the key factors in order to speed |
173 | * up decryption. It also blinds the ciphertext prior to |
81e9d7ec |
174 | * decryption and unblinds it afterwards to thwart timing |
175 | * attacks. |
176 | */ |
177 | |
7ec885b3 |
178 | extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/); |
81e9d7ec |
179 | |
7ec885b3 |
180 | /* --- @rsa_qprivop@ --- * |
01898d8e |
181 | * |
7ec885b3 |
182 | * Arguments: @rsa_priv *rp@ = pointer to RSA parameters |
01898d8e |
183 | * @mp *d@ = destination |
7ec885b3 |
184 | * @mp *c@ = input message |
01898d8e |
185 | * @grand *r@ = pointer to random number source for blinding |
186 | * |
7ec885b3 |
187 | * Returns: Correctly transformed output message |
188 | * |
189 | * Use: Performs an RSA private key operation, very carefully. |
190 | */ |
191 | |
192 | extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/); |
193 | |
194 | /* --- @rsa_sign@ --- * |
195 | * |
196 | * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context |
b817bfc6 |
197 | * @mp *d@ = where to put the result |
7ec885b3 |
198 | * @const void *m@ = pointer to input message |
b817bfc6 |
199 | * @size_t msz@ = size of input message |
200 | * @rsa_pad *e@ = encoding procedure |
7ec885b3 |
201 | * @void *earg@ = argument pointer for encoding procedure |
202 | * |
b817bfc6 |
203 | * Returns: The signature, as a multiprecision integer, or null on |
7ec885b3 |
204 | * failure. |
01898d8e |
205 | * |
7ec885b3 |
206 | * Use: Computes an RSA digital signature. |
01898d8e |
207 | */ |
208 | |
b817bfc6 |
209 | extern mp *rsa_sign(rsa_privctx */*rp*/, mp */*d*/, |
210 | const void */*m*/, size_t /*msz*/, |
211 | rsa_pad */*e*/, void */*earg*/); |
7ec885b3 |
212 | |
213 | /* --- @rsa_decrypt@ --- * |
214 | * |
215 | * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context |
b817bfc6 |
216 | * @mp *m@ = encrypted message, as a multiprecision integer |
7ec885b3 |
217 | * @dstr *d@ = pointer to output string |
b817bfc6 |
218 | * @rsa_decunpad *e@ = decoding procedure |
7ec885b3 |
219 | * @void *earg@ = argument pointer for decoding procedure |
220 | * |
221 | * Returns: The length of the output string if successful, negative on |
222 | * failure. |
223 | * |
b817bfc6 |
224 | * Use: Does RSA decryption. |
7ec885b3 |
225 | */ |
226 | |
b817bfc6 |
227 | extern int rsa_decrypt(rsa_privctx */*rp*/, mp */*m*/, |
228 | dstr */*d*/, rsa_decunpad */*e*/, void */*earg*/); |
7ec885b3 |
229 | |
230 | /*----- RSA public key operations -----------------------------------------*/ |
231 | |
232 | /* --- @rsa_pubcreate@ --- * |
233 | * |
234 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
235 | * @rsa_pub *rp@ = pointer to RSA public key |
236 | * |
237 | * Returns: --- |
238 | * |
239 | * Use: Initializes an RSA public-key context. |
240 | */ |
241 | |
242 | extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/); |
243 | |
244 | /* --- @rsa_pubdestroy@ --- * |
245 | * |
246 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
247 | * |
248 | * Returns: --- |
249 | * |
250 | * Use: Destroys an RSA public-key context. |
251 | */ |
252 | |
253 | extern void rsa_pubdestroy(rsa_pubctx */*rd*/); |
254 | |
255 | /* --- @rsa_pubop@ --- * |
256 | * |
257 | * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context |
258 | * @mp *d@ = destination |
259 | * @mp *p@ = input message |
260 | * |
261 | * Returns: The transformed output message. |
262 | * |
263 | * Use: Performs an RSA public key operation. |
264 | */ |
265 | |
266 | extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/); |
267 | |
268 | /* --- @rsa_qpubop@ --- * |
269 | * |
270 | * Arguments: @rsa_pub *rp@ = pointer to RSA parameters |
271 | * @mp *d@ = destination |
272 | * @mp *p@ = input message |
273 | * |
274 | * Returns: Correctly transformed output message. |
275 | * |
276 | * Use: Performs an RSA public key operation. |
277 | */ |
278 | |
279 | extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/); |
280 | |
281 | /* --- @rsa_encrypt@ --- * |
282 | * |
283 | * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key context |
b817bfc6 |
284 | * @mp *d@ = proposed destination integer |
7ec885b3 |
285 | * @const void *m@ = pointer to input message |
b817bfc6 |
286 | * @size_t msz@ = size of input message |
287 | * @rsa_pad *e@ = encoding procedure |
7ec885b3 |
288 | * @void *earg@ = argument pointer for encoding procedure |
289 | * |
b817bfc6 |
290 | * Returns: The encrypted message, as a multiprecision integer, or null |
291 | * on failure. |
7ec885b3 |
292 | * |
293 | * Use: Does RSA encryption. |
294 | */ |
295 | |
b817bfc6 |
296 | extern mp *rsa_encrypt(rsa_pubctx */*rp*/, mp */*d*/, |
297 | const void */*m*/, size_t /*msz*/, |
298 | rsa_pad */*e*/, void */*earg*/); |
7ec885b3 |
299 | |
300 | /* --- @rsa_verify@ --- * |
301 | * |
302 | * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt |
b817bfc6 |
303 | * @mp *s@ = the signature, as a multiprecision integer |
304 | * @const void *m@ = pointer to message to verify, or null |
7ec885b3 |
305 | * @size_t sz@ = size of input message |
b817bfc6 |
306 | * @dstr *d@ = pointer to output string, or null |
307 | * @rsa_vfrunpad *e@ = decoding procedure |
7ec885b3 |
308 | * @void *earg@ = argument pointer for decoding procedure |
309 | * |
b817bfc6 |
310 | * Returns: The length of the output string if successful (0 if no output |
311 | * was wanted); negative on failure. |
7ec885b3 |
312 | * |
b817bfc6 |
313 | * Use: Does RSA signature verification. To use a signature scheme |
314 | * with recovery, pass in @m == 0@ and @d != 0@: the recovered |
315 | * message should appear in @d@. To use a signature scheme with |
316 | * appendix, provide @m != 0@ and @d == 0@; the result should be |
317 | * zero for success. |
7ec885b3 |
318 | */ |
319 | |
b817bfc6 |
320 | extern int rsa_verify(rsa_pubctx */*rp*/, mp */*s*/, |
321 | const void */*m*/, size_t /*sz*/, dstr */*d*/, |
322 | rsa_vrfunpad */*e*/, void */*earg*/); |
7ec885b3 |
323 | |
324 | /*----- Miscellaneous operations ------------------------------------------*/ |
325 | |
326 | /* --- @rsa_gen@ --- * |
327 | * |
328 | * Arguments: @rsa_priv *rp@ = pointer to block to be filled in |
329 | * @unsigned nbits@ = required modulus size in bits |
330 | * @grand *r@ = random number source |
331 | * @unsigned n@ = number of attempts to make |
332 | * @pgen_proc *event@ = event handler function |
333 | * @void *ectx@ = argument for the event handler |
334 | * |
335 | * Returns: Zero if all went well, nonzero otherwise. |
336 | * |
337 | * Use: Constructs a pair of strong RSA primes and other useful RSA |
338 | * parameters. A small encryption exponent is chosen if |
339 | * possible. |
340 | */ |
341 | |
342 | extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/, |
343 | grand */*r*/, unsigned /*n*/, |
344 | pgen_proc */*event*/, void */*ectx*/); |
01898d8e |
345 | |
346 | /* --- @rsa_recover@ --- * |
347 | * |
7ec885b3 |
348 | * Arguments: @rsa_priv *rp@ = pointer to parameter block |
01898d8e |
349 | * |
350 | * Returns: Zero if all went well, nonzero if the parameters make no |
351 | * sense. |
352 | * |
353 | * Use: Derives the full set of RSA parameters given a minimal set. |
354 | */ |
355 | |
7ec885b3 |
356 | extern int rsa_recover(rsa_priv */*rp*/); |
01898d8e |
357 | |
b817bfc6 |
358 | /*----- Padding schemes ---------------------------------------------------*/ |
359 | |
360 | /* --- PKCS1 padding --- */ |
361 | |
362 | typedef struct pkcs1 { |
363 | grand *r; /* Random number source */ |
364 | const void *ep; /* Encoding parameters block */ |
365 | size_t epsz; /* Size of the parameter block */ |
366 | } pkcs1; |
367 | |
368 | extern rsa_pad pkcs1_cryptencode; |
369 | extern rsa_decunpad pkcs1_cryptdecode; |
370 | extern rsa_pad pkcs1_sigencode; |
371 | extern rsa_vrfunpad pkcs1_sigdecode; |
372 | |
373 | /* --- OAEP --- */ |
374 | |
375 | typedef struct oaep { |
376 | const gccipher *cc; /* Cipher class for masking */ |
377 | const gchash *ch; /* Hash class for parameter block */ |
378 | grand *r; /* Random number source */ |
379 | const void *ep; /* Encoding parameters block */ |
380 | size_t epsz; /* Size of the parameter block */ |
381 | } oaep; |
382 | |
383 | extern rsa_pad oaep_encode; |
384 | extern rsa_decunpad oaep_decode; |
385 | |
386 | /* --- PSS --- */ |
387 | |
388 | typedef struct pss { |
389 | const gccipher *cc; /* Cipher class for masking */ |
390 | const gchash *ch; /* Hash class for choosing a seed */ |
391 | grand *r; /* Random number source */ |
392 | size_t ssz; /* Requested salt size */ |
393 | } pss; |
394 | |
395 | extern rsa_pad pss_encode; |
396 | extern rsa_vrfunpad pss_decode; |
397 | |
01898d8e |
398 | /*----- That's all, folks -------------------------------------------------*/ |
399 | |
400 | #ifdef __cplusplus |
401 | } |
402 | #endif |
403 | |
404 | #endif |