3 * The RSA public-key cryptosystem
5 * (c) 1999 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
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.
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.
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,
28 #ifndef CATACOMB_RSA_H
29 #define CATACOMB_RSA_H
35 /*----- Header files ------------------------------------------------------*/
37 #ifndef CATACOMB_GRAND_H
41 #ifndef CATACOMB_GCIPHER_H
45 #ifndef CATACOMB_GHASH_H
49 #ifndef CATACOMB_KEY_H
57 #ifndef CATACOMB_PGEN_H
61 /*----- Data structures ---------------------------------------------------*/
63 /* --- RSA private and public keys --- */
65 typedef struct rsa_pub {
70 typedef struct rsa_priv {
71 mp *n, *p, *q, *q_inv;
75 /* --- RSA private and public key contexts --- *
77 * These are used to store information about `active' keys which will speed
78 * up the various operations.
81 typedef struct rsa_privctx {
87 typedef struct rsa_pubctx {
92 /* --- Encoding and decoding function schemas --- *
94 * See `oaep.h' and `pkcs1.h' for appropriate encoding functions.
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*/);
101 typedef int rsa_decunpad(mp */*m*/, octet */*b*/, size_t /*sz*/,
102 unsigned long /*nbits*/, void */*p*/);
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*/);
108 /*----- Key fetching ------------------------------------------------------*/
110 extern const key_fetchdef rsa_pubfetch[];
111 #define RSA_PUBFETCHSZ 4
113 extern const key_fetchdef rsa_privfetch[];
114 #define RSA_PRIVFETCHSZ 12
116 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
118 * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
122 * Use: Frees an RSA key block.
125 extern void rsa_pubfree(rsa_pub */*rp*/);
126 extern void rsa_privfree(rsa_priv */*rp*/);
128 /*----- RSA private key operations ----------------------------------------*/
130 /* --- @rsa_privcreate@ --- *
132 * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key context
133 * @rsa_priv *rp@ = pointer to RSA private key
134 * @grand *r@ = pointer to random number source for blinding
138 * Use: Initializes an RSA private-key context. Keeping a context
139 * for several decryption or signing operations provides a minor
140 * performance benefit.
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.
147 extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/,
150 /* --- @rsa_privdestroy@ --- *
152 * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context
156 * Use: Destroys an RSA decryption context.
159 extern void rsa_privdestroy(rsa_privctx */*rd*/);
161 /* --- @rsa_privop@ --- *
163 * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context
164 * @mp *d@ = destination
165 * @mp *c@ = input message
167 * Returns: The transformed output message.
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
172 * decryption and unblinds it afterwards to thwart timing
176 extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/);
178 /* --- @rsa_qprivop@ --- *
180 * Arguments: @rsa_priv *rp@ = pointer to RSA parameters
181 * @mp *d@ = destination
182 * @mp *c@ = input message
183 * @grand *r@ = pointer to random number source for blinding
185 * Returns: Correctly transformed output message
187 * Use: Performs an RSA private key operation, very carefully.
190 extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/);
192 /* --- @rsa_sign@ --- *
194 * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context
195 * @mp *d@ = where to put the result
196 * @const void *m@ = pointer to input message
197 * @size_t msz@ = size of input message
198 * @rsa_pad *e@ = encoding procedure
199 * @void *earg@ = argument pointer for encoding procedure
201 * Returns: The signature, as a multiprecision integer, or null on
204 * Use: Computes an RSA digital signature.
207 extern mp *rsa_sign(rsa_privctx */*rp*/, mp */*d*/,
208 const void */*m*/, size_t /*msz*/,
209 rsa_pad */*e*/, void */*earg*/);
211 /* --- @rsa_decrypt@ --- *
213 * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context
214 * @mp *m@ = encrypted message, as a multiprecision integer
215 * @dstr *d@ = pointer to output string
216 * @rsa_decunpad *e@ = decoding procedure
217 * @void *earg@ = argument pointer for decoding procedure
219 * Returns: The length of the output string if successful, negative on
222 * Use: Does RSA decryption.
225 extern int rsa_decrypt(rsa_privctx */*rp*/, mp */*m*/,
226 dstr */*d*/, rsa_decunpad */*e*/, void */*earg*/);
228 /*----- RSA public key operations -----------------------------------------*/
230 /* --- @rsa_pubcreate@ --- *
232 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
233 * @rsa_pub *rp@ = pointer to RSA public key
237 * Use: Initializes an RSA public-key context.
240 extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/);
242 /* --- @rsa_pubdestroy@ --- *
244 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
248 * Use: Destroys an RSA public-key context.
251 extern void rsa_pubdestroy(rsa_pubctx */*rd*/);
253 /* --- @rsa_pubop@ --- *
255 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
256 * @mp *d@ = destination
257 * @mp *p@ = input message
259 * Returns: The transformed output message.
261 * Use: Performs an RSA public key operation.
264 extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/);
266 /* --- @rsa_qpubop@ --- *
268 * Arguments: @rsa_pub *rp@ = pointer to RSA parameters
269 * @mp *d@ = destination
270 * @mp *p@ = input message
272 * Returns: Correctly transformed output message.
274 * Use: Performs an RSA public key operation.
277 extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/);
279 /* --- @rsa_encrypt@ --- *
281 * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key context
282 * @mp *d@ = proposed destination integer
283 * @const void *m@ = pointer to input message
284 * @size_t msz@ = size of input message
285 * @rsa_pad *e@ = encoding procedure
286 * @void *earg@ = argument pointer for encoding procedure
288 * Returns: The encrypted message, as a multiprecision integer, or null
291 * Use: Does RSA encryption.
294 extern mp *rsa_encrypt(rsa_pubctx */*rp*/, mp */*d*/,
295 const void */*m*/, size_t /*msz*/,
296 rsa_pad */*e*/, void */*earg*/);
298 /* --- @rsa_verify@ --- *
300 * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt
301 * @mp *s@ = the signature, as a multiprecision integer
302 * @const void *m@ = pointer to message to verify, or null
303 * @size_t sz@ = size of input message
304 * @dstr *d@ = pointer to output string, or null
305 * @rsa_vfrunpad *e@ = decoding procedure
306 * @void *earg@ = argument pointer for decoding procedure
308 * Returns: The length of the output string if successful (0 if no output
309 * was wanted); negative on failure.
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
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*/);
322 /*----- Miscellaneous operations ------------------------------------------*/
324 /* --- @rsa_gen@ --- *
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
333 * Returns: Zero if all went well, nonzero otherwise.
335 * Use: Constructs a pair of strong RSA primes and other useful RSA
336 * parameters. A small encryption exponent is chosen if
340 extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/,
341 grand */*r*/, unsigned /*n*/,
342 pgen_proc */*event*/, void */*ectx*/);
344 /* --- @rsa_recover@ --- *
346 * Arguments: @rsa_priv *rp@ = pointer to parameter block
348 * Returns: Zero if all went well, nonzero if the parameters make no
351 * Use: Derives the full set of RSA parameters given a minimal set.
353 * On failure, the parameter block might be partially filled in,
354 * but the @rsa_privfree@ function will be able to free it
358 extern int rsa_recover(rsa_priv */*rp*/);
360 /*----- Padding schemes ---------------------------------------------------*/
362 /* --- PKCS1 padding --- */
364 typedef struct pkcs1 {
365 grand *r; /* Random number source */
366 const void *ep; /* Encoding parameters block */
367 size_t epsz; /* Size of the parameter block */
370 extern rsa_pad pkcs1_cryptencode;
371 extern rsa_decunpad pkcs1_cryptdecode;
372 extern rsa_pad pkcs1_sigencode;
373 extern rsa_vrfunpad pkcs1_sigdecode;
377 typedef struct oaep {
378 const gccipher *cc; /* Cipher class for masking */
379 const gchash *ch; /* Hash class for parameter block */
380 grand *r; /* Random number source */
381 const void *ep; /* Encoding parameters block */
382 size_t epsz; /* Size of the parameter block */
385 extern rsa_pad oaep_encode;
386 extern rsa_decunpad oaep_decode;
391 const gccipher *cc; /* Cipher class for masking */
392 const gchash *ch; /* Hash class for choosing a seed */
393 grand *r; /* Random number source */
394 size_t ssz; /* Requested salt size */
397 extern rsa_pad pss_encode;
398 extern rsa_vrfunpad pss_decode;
400 /*----- That's all, folks -------------------------------------------------*/