chiark - git - mdw - catacomb/blob - pub/rsa.h

   1 /* -*-c-*-
   2  *
   3  * The RSA public-key cryptosystem
   4  *
   5  * (c) 1999 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   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.
  16  *
  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.
  21  *
  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
  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
  41 #ifndef CATACOMB_GCIPHER_H
  42 #  include "gcipher.h"
  43 #endif
  44
  45 #ifndef CATACOMB_GHASH_H
  46 #  include "ghash.h"
  47 #endif
  48
  49 #ifndef CATACOMB_KEY_H
  50 #  include "key.h"
  51 #endif
  52
  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
  63 /* --- RSA private and public keys --- */
  64
  65 typedef struct rsa_pub {
  66   mp *n;
  67   mp *e;
  68 } rsa_pub;
  69
  70 typedef struct rsa_priv {
  71   mp *n, *p, *q, *q_inv;
  72   mp *e, *d, *dp, *dq;
  73 } rsa_priv;
  74
  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;
  83   grand *r;
  84   mpmont nm, pm, qm;
  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
  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*/);
 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
 115
 116 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
 117  *
 118  * Arguments:   @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
 119  *
 120  * Returns:     ---
 121  *
 122  * Use:         Frees an RSA key block.
 123  */
 124
 125 extern void rsa_pubfree(rsa_pub */*rp*/);
 126 extern void rsa_privfree(rsa_priv */*rp*/);
 127
 128 /*----- RSA private key operations ----------------------------------------*/
 129
 130 /* --- @rsa_privcreate@ --- *
 131  *
 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
 135  *
 136  * Returns:     ---
 137  *
 138  * Use:         Initializes an RSA private-key context.  Keeping a context
 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
 147 extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/,
 148                            grand */*r*/);
 149
 150 /* --- @rsa_privdestroy@ --- *
 151  *
 152  * Arguments:   @rsa_privctx *rd@ = pointer to an RSA decryption context
 153  *
 154  * Returns:     ---
 155  *
 156  * Use:         Destroys an RSA decryption context.
 157  */
 158
 159 extern void rsa_privdestroy(rsa_privctx */*rd*/);
 160
 161 /* --- @rsa_privop@ --- *
 162  *
 163  * Arguments:   @rsa_privctx *rd@ = pointer to RSA private key context
 164  *              @mp *d@ = destination
 165  *              @mp *c@ = input message
 166  *
 167  * Returns:     The transformed output message.
 168  *
 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
 173  *              attacks.
 174  */
 175
 176 extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/);
 177
 178 /* --- @rsa_qprivop@ --- *
 179  *
 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
 184  *
 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
 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
 200  *
 201  * Returns:     The signature, as a multiprecision integer, or null on
 202  *              failure.
 203  *
 204  * Use:         Computes an RSA digital signature.
 205  */
 206
 207 extern mp *rsa_sign(rsa_privctx */*rp*/, mp */*d*/,
 208                     const void */*m*/, size_t /*msz*/,
 209                     rsa_pad */*e*/, void */*earg*/);
 210
 211 /* --- @rsa_decrypt@ --- *
 212  *
 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
 218  *
 219  * Returns:     The length of the output string if successful, negative on
 220  *              failure.
 221  *
 222  * Use:         Does RSA decryption.
 223  */
 224
 225 extern int rsa_decrypt(rsa_privctx */*rp*/, mp */*m*/,
 226                        dstr */*d*/, rsa_decunpad */*e*/, void */*earg*/);
 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
 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
 287  *
 288  * Returns:     The encrypted message, as a multiprecision integer, or null
 289  *              on failure.
 290  *
 291  * Use:         Does RSA encryption.
 292  */
 293
 294 extern mp *rsa_encrypt(rsa_pubctx */*rp*/, mp */*d*/,
 295                        const void */*m*/, size_t /*msz*/,
 296                        rsa_pad */*e*/, void */*earg*/);
 297
 298 /* --- @rsa_verify@ --- *
 299  *
 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
 307  *
 308  * Returns:     The length of the output string if successful (0 if no output
 309  *              was wanted); negative on failure.
 310  *
 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.
 316  */
 317
 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*/);
 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  *              @mp *e@ = public exponent
 329  *              @grand *r@ = random number source
 330  *              @unsigned n@ = number of attempts to make
 331  *              @pgen_proc *event@ = event handler function
 332  *              @void *ectx@ = argument for the event handler
 333  *
 334  * Returns:     Zero if all went well, nonzero otherwise.
 335  *
 336  * Use:         Constructs a pair of strong RSA primes and other useful RSA
 337  *              parameters.  A small encryption exponent is chosen if
 338  *              possible.
 339  */
 340
 341 extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/,
 342                    grand */*r*/, unsigned /*n*/,
 343                    pgen_proc */*event*/, void */*ectx*/);
 344
 345 extern int rsa_gen_e(rsa_priv */*rp*/, unsigned /*nbits*/, mp */*e*/,
 346                      grand */*r*/, unsigned /*nsteps*/,
 347                      pgen_proc */*event*/, void */*ectx*/);
 348
 349 /* --- @rsa_recover@ --- *
 350  *
 351  * Arguments:   @rsa_priv *rp@ = pointer to parameter block
 352  *
 353  * Returns:     Zero if all went well, nonzero if the parameters make no
 354  *              sense.
 355  *
 356  * Use:         Derives the full set of RSA parameters given a minimal set.
 357  *
 358  *              On failure, the parameter block might be partially filled in,
 359  *              but the @rsa_privfree@ function will be able to free it
 360  *              successfully.
 361  */
 362
 363 extern int rsa_recover(rsa_priv */*rp*/);
 364
 365 /*----- Padding schemes ---------------------------------------------------*/
 366
 367 /* --- PKCS1 padding --- */
 368
 369 typedef struct pkcs1 {
 370   grand *r;                             /* Random number source */
 371   const void *ep;                       /* Encoding parameters block */
 372   size_t epsz;                          /* Size of the parameter block */
 373 } pkcs1;
 374
 375 extern rsa_pad pkcs1_cryptencode;
 376 extern rsa_decunpad pkcs1_cryptdecode;
 377 extern rsa_pad pkcs1_sigencode;
 378 extern rsa_vrfunpad pkcs1_sigdecode;
 379
 380 /* --- OAEP --- */
 381
 382 typedef struct oaep {
 383   const gccipher *cc;                   /* Cipher class for masking */
 384   const gchash *ch;                     /* Hash class for parameter block */
 385   grand *r;                             /* Random number source */
 386   const void *ep;                       /* Encoding parameters block */
 387   size_t epsz;                          /* Size of the parameter block */
 388 } oaep;
 389
 390 extern rsa_pad oaep_encode;
 391 extern rsa_decunpad oaep_decode;
 392
 393 /* --- PSS --- */
 394
 395 typedef struct pss {
 396   const gccipher *cc;                   /* Cipher class for masking */
 397   const gchash *ch;                     /* Hash class for choosing a seed */
 398   grand *r;                             /* Random number source */
 399   size_t ssz;                           /* Requested salt size */
 400 } pss;
 401
 402 extern rsa_pad pss_encode;
 403 extern rsa_vrfunpad pss_decode;
 404
 405 /*----- That's all, folks -------------------------------------------------*/
 406
 407 #ifdef __cplusplus
 408   }
 409 #endif
 410
 411 #endif