3 * $Id: rsa.h,v 1.3 2000/07/01 11:24:37 mdw Exp $
5 * The RSA public-key cryptosystem
7 * (c) 1999 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Catacomb.
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.
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.
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,
30 /*----- Revision history --------------------------------------------------*
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.
38 * Revision 1.2 2000/06/17 12:07:36 mdw
39 * Add key fetching interface. Add new rsa_decrypt interface.
41 * Revision 1.1 1999/12/22 15:50:45 mdw
42 * Initial RSA support.
46 #ifndef CATACOMB_RSA_H
47 #define CATACOMB_RSA_H
53 /*----- Header files ------------------------------------------------------*/
55 #ifndef CATACOMB_GRAND_H
59 #ifndef CATACOMB_KEY_H
67 #ifndef CATACOMB_PGEN_H
71 /*----- Data structures ---------------------------------------------------*/
73 /* --- RSA private and public keys --- */
75 typedef struct rsa_pub
{
80 typedef struct rsa_priv
{
81 mp
*n
, *p
, *q
, *q_inv
;
85 /* --- RSA private and public key contexts --- *
87 * These are used to store information about `active' keys which will speed
88 * up the various operations.
91 typedef struct rsa_privctx
{
97 typedef struct rsa_pubctx
{
102 /* --- Encoding and decoding function schemas --- *
104 * See `oaep.h' and `pkcs1.h' for appropriate encoding functions.
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*/
);
112 /*----- Key fetching ------------------------------------------------------*/
114 extern const key_fetchdef rsa_pubfetch
[];
115 #define RSA_PUBFETCHSZ 4
117 extern const key_fetchdef rsa_privfetch
[];
118 #define RSA_PRIVFETCHSZ 12
120 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
122 * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
126 * Use: Frees an RSA key block.
129 extern void rsa_pubfree(rsa_pub */
*rp*/
);
130 extern void rsa_privfree(rsa_priv */
*rp*/
);
132 /*----- RSA private key operations ----------------------------------------*/
134 /* --- @rsa_privcreate@ --- *
136 * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key context
137 * @rsa_priv *rp@ = pointer to RSA private key
138 * @grand *r@ = pointer to random number source for blinding
142 * Use: Initializes an RSA private-key context. Keeping a context
143 * for several decryption or signing operations provides a minor
144 * performance benefit.
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.
151 extern void rsa_privcreate(rsa_privctx */
*rd*/
, rsa_priv */
*rp*/
,
154 /* --- @rsa_privdestroy@ --- *
156 * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context
160 * Use: Destroys an RSA decryption context.
163 extern void rsa_privdestroy(rsa_privctx */
*rd*/
);
165 /* --- @rsa_privop@ --- *
167 * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context
168 * @mp *d@ = destination
169 * @mp *c@ = input message
171 * Returns: The transformed output message.
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
176 * decryption and unblinds it afterwards to thwart timing
180 extern mp
*rsa_privop(rsa_privctx */
*rd*/
, mp */
*d*/
, mp */
*c*/
);
182 /* --- @rsa_qprivop@ --- *
184 * Arguments: @rsa_priv *rp@ = pointer to RSA parameters
185 * @mp *d@ = destination
186 * @mp *c@ = input message
187 * @grand *r@ = pointer to random number source for blinding
189 * Returns: Correctly transformed output message
191 * Use: Performs an RSA private key operation, very carefully.
194 extern mp
*rsa_qprivop(rsa_priv */
*rp*/
, mp */
*d*/
, mp */
*c*/
, grand */
*r*/
);
196 /* --- @rsa_sign@ --- *
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
205 * Returns: The length of the output string if successful, negative on
208 * Use: Computes an RSA digital signature.
211 extern int rsa_sign(rsa_privctx */
*rp*/
, const void */
*m*/
, size_t /*sz*/,
212 dstr */
*d*/
, rsa_encodeproc
/*e*/, void */
*earg*/
);
214 /* --- @rsa_decrypt@ --- *
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
223 * Returns: The length of the output string if successful, negative on
226 * Use: Does RSA signature verification.
229 extern int rsa_decrypt(rsa_privctx */
*rp*/
, const void */
*m*/
, size_t /*sz*/,
230 dstr */
*d*/
, rsa_decodeproc
/*e*/, void */
*earg*/
);
232 /*----- RSA public key operations -----------------------------------------*/
234 /* --- @rsa_pubcreate@ --- *
236 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
237 * @rsa_pub *rp@ = pointer to RSA public key
241 * Use: Initializes an RSA public-key context.
244 extern void rsa_pubcreate(rsa_pubctx */
*rd*/
, rsa_pub */
*rp*/
);
246 /* --- @rsa_pubdestroy@ --- *
248 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
252 * Use: Destroys an RSA public-key context.
255 extern void rsa_pubdestroy(rsa_pubctx */
*rd*/
);
257 /* --- @rsa_pubop@ --- *
259 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
260 * @mp *d@ = destination
261 * @mp *p@ = input message
263 * Returns: The transformed output message.
265 * Use: Performs an RSA public key operation.
268 extern mp
*rsa_pubop(rsa_pubctx */
*rd*/
, mp */
*d*/
, mp */
*p*/
);
270 /* --- @rsa_qpubop@ --- *
272 * Arguments: @rsa_pub *rp@ = pointer to RSA parameters
273 * @mp *d@ = destination
274 * @mp *p@ = input message
276 * Returns: Correctly transformed output message.
278 * Use: Performs an RSA public key operation.
281 extern mp
*rsa_qpubop(rsa_pub */
*rp*/
, mp */
*d*/
, mp */
*c*/
);
283 /* --- @rsa_encrypt@ --- *
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
292 * Returns: The length of the output string if successful, negative on
295 * Use: Does RSA encryption.
298 extern int rsa_encrypt(rsa_pubctx */
*rp*/
, const void */
*m*/
, size_t /*sz*/,
299 dstr */
*d*/
, rsa_encodeproc
/*e*/, void */
*earg*/
);
301 /* --- @rsa_verify@ --- *
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
310 * Returns: The length of the output string if successful, negative on
313 * Use: Does RSA signature verification.
316 extern int rsa_verify(rsa_pubctx */
*rp*/
, const void */
*m*/
, size_t /*sz*/,
317 dstr */
*d*/
, rsa_decodeproc
/*e*/, void */
*earg*/
);
319 /*----- Miscellaneous operations ------------------------------------------*/
321 /* --- @rsa_gen@ --- *
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
330 * Returns: Zero if all went well, nonzero otherwise.
332 * Use: Constructs a pair of strong RSA primes and other useful RSA
333 * parameters. A small encryption exponent is chosen if
337 extern int rsa_gen(rsa_priv */
*rp*/
, unsigned /*nbits*/,
338 grand */
*r*/
, unsigned /*n*/,
339 pgen_proc */
*event*/
, void */
*ectx*/
);
341 /* --- @rsa_recover@ --- *
343 * Arguments: @rsa_priv *rp@ = pointer to parameter block
345 * Returns: Zero if all went well, nonzero if the parameters make no
348 * Use: Derives the full set of RSA parameters given a minimal set.
351 extern int rsa_recover(rsa_priv */
*rp*/
);
353 /*----- That's all, folks -------------------------------------------------*/