3 * $Id: rsa.h,v 1.4 2004/04/08 01:36:15 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 #ifndef CATACOMB_RSA_H
31 #define CATACOMB_RSA_H
37 /*----- Header files ------------------------------------------------------*/
39 #ifndef CATACOMB_GRAND_H
43 #ifndef CATACOMB_GCIPHER_H
47 #ifndef CATACOMB_GHASH_H
51 #ifndef CATACOMB_KEY_H
59 #ifndef CATACOMB_PGEN_H
63 /*----- Data structures ---------------------------------------------------*/
65 /* --- RSA private and public keys --- */
67 typedef struct rsa_pub
{
72 typedef struct rsa_priv
{
73 mp
*n
, *p
, *q
, *q_inv
;
77 /* --- RSA private and public key contexts --- *
79 * These are used to store information about `active' keys which will speed
80 * up the various operations.
83 typedef struct rsa_privctx
{
89 typedef struct rsa_pubctx
{
94 /* --- Encoding and decoding function schemas --- *
96 * See `oaep.h' and `pkcs1.h' for appropriate encoding functions.
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*/
);
103 typedef int rsa_decunpad(mp */
*m*/
, octet */
*b*/
, size_t /*sz*/,
104 unsigned long /*nbits*/, void */
*p*/
);
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*/
);
110 /*----- Key fetching ------------------------------------------------------*/
112 extern const key_fetchdef rsa_pubfetch
[];
113 #define RSA_PUBFETCHSZ 4
115 extern const key_fetchdef rsa_privfetch
[];
116 #define RSA_PRIVFETCHSZ 12
118 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
120 * Arguments: @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
124 * Use: Frees an RSA key block.
127 extern void rsa_pubfree(rsa_pub */
*rp*/
);
128 extern void rsa_privfree(rsa_priv */
*rp*/
);
130 /*----- RSA private key operations ----------------------------------------*/
132 /* --- @rsa_privcreate@ --- *
134 * Arguments: @rsa_privctx *rd@ = pointer to an RSA private key context
135 * @rsa_priv *rp@ = pointer to RSA private key
136 * @grand *r@ = pointer to random number source for blinding
140 * Use: Initializes an RSA private-key context. Keeping a context
141 * for several decryption or signing operations provides a minor
142 * performance benefit.
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.
149 extern void rsa_privcreate(rsa_privctx */
*rd*/
, rsa_priv */
*rp*/
,
152 /* --- @rsa_privdestroy@ --- *
154 * Arguments: @rsa_privctx *rd@ = pointer to an RSA decryption context
158 * Use: Destroys an RSA decryption context.
161 extern void rsa_privdestroy(rsa_privctx */
*rd*/
);
163 /* --- @rsa_privop@ --- *
165 * Arguments: @rsa_privctx *rd@ = pointer to RSA private key context
166 * @mp *d@ = destination
167 * @mp *c@ = input message
169 * Returns: The transformed output message.
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
174 * decryption and unblinds it afterwards to thwart timing
178 extern mp
*rsa_privop(rsa_privctx */
*rd*/
, mp */
*d*/
, mp */
*c*/
);
180 /* --- @rsa_qprivop@ --- *
182 * Arguments: @rsa_priv *rp@ = pointer to RSA parameters
183 * @mp *d@ = destination
184 * @mp *c@ = input message
185 * @grand *r@ = pointer to random number source for blinding
187 * Returns: Correctly transformed output message
189 * Use: Performs an RSA private key operation, very carefully.
192 extern mp
*rsa_qprivop(rsa_priv */
*rp*/
, mp */
*d*/
, mp */
*c*/
, grand */
*r*/
);
194 /* --- @rsa_sign@ --- *
196 * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context
197 * @mp *d@ = where to put the result
198 * @const void *m@ = pointer to input message
199 * @size_t msz@ = size of input message
200 * @rsa_pad *e@ = encoding procedure
201 * @void *earg@ = argument pointer for encoding procedure
203 * Returns: The signature, as a multiprecision integer, or null on
206 * Use: Computes an RSA digital signature.
209 extern mp
*rsa_sign(rsa_privctx */
*rp*/
, mp */
*d*/
,
210 const void */
*m*/
, size_t /*msz*/,
211 rsa_pad */
*e*/
, void */
*earg*/
);
213 /* --- @rsa_decrypt@ --- *
215 * Arguments: @rsa_privctx *rp@ = pointer to an RSA private key context
216 * @mp *m@ = encrypted message, as a multiprecision integer
217 * @dstr *d@ = pointer to output string
218 * @rsa_decunpad *e@ = decoding procedure
219 * @void *earg@ = argument pointer for decoding procedure
221 * Returns: The length of the output string if successful, negative on
224 * Use: Does RSA decryption.
227 extern int rsa_decrypt(rsa_privctx */
*rp*/
, mp */
*m*/
,
228 dstr */
*d*/
, rsa_decunpad */
*e*/
, void */
*earg*/
);
230 /*----- RSA public key operations -----------------------------------------*/
232 /* --- @rsa_pubcreate@ --- *
234 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
235 * @rsa_pub *rp@ = pointer to RSA public key
239 * Use: Initializes an RSA public-key context.
242 extern void rsa_pubcreate(rsa_pubctx */
*rd*/
, rsa_pub */
*rp*/
);
244 /* --- @rsa_pubdestroy@ --- *
246 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
250 * Use: Destroys an RSA public-key context.
253 extern void rsa_pubdestroy(rsa_pubctx */
*rd*/
);
255 /* --- @rsa_pubop@ --- *
257 * Arguments: @rsa_pubctx *rd@ = pointer to an RSA public key context
258 * @mp *d@ = destination
259 * @mp *p@ = input message
261 * Returns: The transformed output message.
263 * Use: Performs an RSA public key operation.
266 extern mp
*rsa_pubop(rsa_pubctx */
*rd*/
, mp */
*d*/
, mp */
*p*/
);
268 /* --- @rsa_qpubop@ --- *
270 * Arguments: @rsa_pub *rp@ = pointer to RSA parameters
271 * @mp *d@ = destination
272 * @mp *p@ = input message
274 * Returns: Correctly transformed output message.
276 * Use: Performs an RSA public key operation.
279 extern mp
*rsa_qpubop(rsa_pub */
*rp*/
, mp */
*d*/
, mp */
*c*/
);
281 /* --- @rsa_encrypt@ --- *
283 * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key context
284 * @mp *d@ = proposed destination integer
285 * @const void *m@ = pointer to input message
286 * @size_t msz@ = size of input message
287 * @rsa_pad *e@ = encoding procedure
288 * @void *earg@ = argument pointer for encoding procedure
290 * Returns: The encrypted message, as a multiprecision integer, or null
293 * Use: Does RSA encryption.
296 extern mp
*rsa_encrypt(rsa_pubctx */
*rp*/
, mp */
*d*/
,
297 const void */
*m*/
, size_t /*msz*/,
298 rsa_pad */
*e*/
, void */
*earg*/
);
300 /* --- @rsa_verify@ --- *
302 * Arguments: @rsa_pubctx *rp@ = pointer to an RSA public key contxt
303 * @mp *s@ = the signature, as a multiprecision integer
304 * @const void *m@ = pointer to message to verify, or null
305 * @size_t sz@ = size of input message
306 * @dstr *d@ = pointer to output string, or null
307 * @rsa_vfrunpad *e@ = decoding procedure
308 * @void *earg@ = argument pointer for decoding procedure
310 * Returns: The length of the output string if successful (0 if no output
311 * was wanted); negative on failure.
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
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*/
);
324 /*----- Miscellaneous operations ------------------------------------------*/
326 /* --- @rsa_gen@ --- *
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
335 * Returns: Zero if all went well, nonzero otherwise.
337 * Use: Constructs a pair of strong RSA primes and other useful RSA
338 * parameters. A small encryption exponent is chosen if
342 extern int rsa_gen(rsa_priv */
*rp*/
, unsigned /*nbits*/,
343 grand */
*r*/
, unsigned /*n*/,
344 pgen_proc */
*event*/
, void */
*ectx*/
);
346 /* --- @rsa_recover@ --- *
348 * Arguments: @rsa_priv *rp@ = pointer to parameter block
350 * Returns: Zero if all went well, nonzero if the parameters make no
353 * Use: Derives the full set of RSA parameters given a minimal set.
356 extern int rsa_recover(rsa_priv */
*rp*/
);
358 /*----- Padding schemes ---------------------------------------------------*/
360 /* --- PKCS1 padding --- */
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 */
368 extern rsa_pad pkcs1_cryptencode
;
369 extern rsa_decunpad pkcs1_cryptdecode
;
370 extern rsa_pad pkcs1_sigencode
;
371 extern rsa_vrfunpad pkcs1_sigdecode
;
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 */
383 extern rsa_pad oaep_encode
;
384 extern rsa_decunpad oaep_decode
;
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 */
395 extern rsa_pad pss_encode
;
396 extern rsa_vrfunpad pss_decode
;
398 /*----- That's all, folks -------------------------------------------------*/