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