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

   1 /* -*-c-*-
   2  *
   3  * $Id: rsa.h,v 1.4 2004/04/08 01:36:15 mdw Exp $
   4  *
   5  * The RSA public-key cryptosystem
   6  *
   7  * (c) 1999 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Catacomb.
  13  *
  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.
  18  *
  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.
  23  *
  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,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 #ifndef CATACOMB_RSA_H
  31 #define CATACOMB_RSA_H
  32
  33 #ifdef __cplusplus
  34   extern "C" {
  35 #endif
  36
  37 /*----- Header files ------------------------------------------------------*/
  38
  39 #ifndef CATACOMB_GRAND_H
  40 #  include "grand.h"
  41 #endif
  42
  43 #ifndef CATACOMB_GCIPHER_H
  44 #  include "gcipher.h"
  45 #endif
  46
  47 #ifndef CATACOMB_GHASH_H
  48 #  include "ghash.h"
  49 #endif
  50
  51 #ifndef CATACOMB_KEY_H
  52 #  include "key.h"
  53 #endif
  54
  55 #ifndef CATACOMB_MP_H
  56 #  include "mp.h"
  57 #endif
  58
  59 #ifndef CATACOMB_PGEN_H
  60 #  include "pgen.h"
  61 #endif
  62
  63 /*----- Data structures ---------------------------------------------------*/
  64
  65 /* --- RSA private and public keys --- */
  66
  67 typedef struct rsa_pub {
  68   mp *n;
  69   mp *e;
  70 } rsa_pub;
  71
  72 typedef struct rsa_priv {
  73   mp *n, *p, *q, *q_inv;
  74   mp *e, *d, *dp, *dq;
  75 } rsa_priv;
  76
  77 /* --- RSA private and public key contexts --- *
  78  *
  79  * These are used to store information about `active' keys which will speed
  80  * up the various operations.
  81  */
  82
  83 typedef struct rsa_privctx {
  84   rsa_priv *rp;
  85   grand *r;
  86   mpmont nm, pm, qm;
  87 } rsa_privctx;
  88
  89 typedef struct rsa_pubctx {
  90   mpmont mm;
  91   rsa_pub *rp;
  92 } rsa_pubctx;
  93
  94 /* --- Encoding and decoding function schemas --- *
  95  *
  96  * See `oaep.h' and `pkcs1.h' for appropriate encoding functions.
  97  */
  98
  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*/);
 102
 103 typedef int rsa_decunpad(mp */*m*/, octet */*b*/, size_t /*sz*/,
 104                          unsigned long /*nbits*/, void */*p*/);
 105
 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*/);
 109
 110 /*----- Key fetching ------------------------------------------------------*/
 111
 112 extern const key_fetchdef rsa_pubfetch[];
 113 #define RSA_PUBFETCHSZ 4
 114
 115 extern const key_fetchdef rsa_privfetch[];
 116 #define RSA_PRIVFETCHSZ 12
 117
 118 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
 119  *
 120  * Arguments:   @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
 121  *
 122  * Returns:     ---
 123  *
 124  * Use:         Frees an RSA key block.
 125  */
 126
 127 extern void rsa_pubfree(rsa_pub */*rp*/);
 128 extern void rsa_privfree(rsa_priv */*rp*/);
 129
 130 /*----- RSA private key operations ----------------------------------------*/
 131
 132 /* --- @rsa_privcreate@ --- *
 133  *
 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
 137  *
 138  * Returns:     ---
 139  *
 140  * Use:         Initializes an RSA private-key context.  Keeping a context
 141  *              for several decryption or signing operations provides a minor
 142  *              performance benefit.
 143  *
 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.
 147  */
 148
 149 extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/,
 150                            grand */*r*/);
 151
 152 /* --- @rsa_privdestroy@ --- *
 153  *
 154  * Arguments:   @rsa_privctx *rd@ = pointer to an RSA decryption context
 155  *
 156  * Returns:     ---
 157  *
 158  * Use:         Destroys an RSA decryption context.
 159  */
 160
 161 extern void rsa_privdestroy(rsa_privctx */*rd*/);
 162
 163 /* --- @rsa_privop@ --- *
 164  *
 165  * Arguments:   @rsa_privctx *rd@ = pointer to RSA private key context
 166  *              @mp *d@ = destination
 167  *              @mp *c@ = input message
 168  *
 169  * Returns:     The transformed output message.
 170  *
 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
 175  *              attacks.
 176  */
 177
 178 extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/);
 179
 180 /* --- @rsa_qprivop@ --- *
 181  *
 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
 186  *
 187  * Returns:     Correctly transformed output message
 188  *
 189  * Use:         Performs an RSA private key operation, very carefully.
 190  */
 191
 192 extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/);
 193
 194 /* --- @rsa_sign@ --- *
 195  *
 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
 202  *
 203  * Returns:     The signature, as a multiprecision integer, or null on
 204  *              failure.
 205  *
 206  * Use:         Computes an RSA digital signature.
 207  */
 208
 209 extern mp *rsa_sign(rsa_privctx */*rp*/, mp */*d*/,
 210                     const void */*m*/, size_t /*msz*/,
 211                     rsa_pad */*e*/, void */*earg*/);
 212
 213 /* --- @rsa_decrypt@ --- *
 214  *
 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
 220  *
 221  * Returns:     The length of the output string if successful, negative on
 222  *              failure.
 223  *
 224  * Use:         Does RSA decryption.
 225  */
 226
 227 extern int rsa_decrypt(rsa_privctx */*rp*/, mp */*m*/,
 228                        dstr */*d*/, rsa_decunpad */*e*/, void */*earg*/);
 229
 230 /*----- RSA public key operations -----------------------------------------*/
 231
 232 /* --- @rsa_pubcreate@ --- *
 233  *
 234  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 235  *              @rsa_pub *rp@ = pointer to RSA public key
 236  *
 237  * Returns:     ---
 238  *
 239  * Use:         Initializes an RSA public-key context.
 240  */
 241
 242 extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/);
 243
 244 /* --- @rsa_pubdestroy@ --- *
 245  *
 246  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 247  *
 248  * Returns:     ---
 249  *
 250  * Use:         Destroys an RSA public-key context.
 251  */
 252
 253 extern void rsa_pubdestroy(rsa_pubctx */*rd*/);
 254
 255 /* --- @rsa_pubop@ --- *
 256  *
 257  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 258  *              @mp *d@ = destination
 259  *              @mp *p@ = input message
 260  *
 261  * Returns:     The transformed output message.
 262  *
 263  * Use:         Performs an RSA public key operation.
 264  */
 265
 266 extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/);
 267
 268 /* --- @rsa_qpubop@ --- *
 269  *
 270  * Arguments:   @rsa_pub *rp@ = pointer to RSA parameters
 271  *              @mp *d@ = destination
 272  *              @mp *p@ = input message
 273  *
 274  * Returns:     Correctly transformed output message.
 275  *
 276  * Use:         Performs an RSA public key operation.
 277  */
 278
 279 extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/);
 280
 281 /* --- @rsa_encrypt@ --- *
 282  *
 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
 289  *
 290  * Returns:     The encrypted message, as a multiprecision integer, or null
 291  *              on failure.
 292  *
 293  * Use:         Does RSA encryption.
 294  */
 295
 296 extern mp *rsa_encrypt(rsa_pubctx */*rp*/, mp */*d*/,
 297                        const void */*m*/, size_t /*msz*/,
 298                        rsa_pad */*e*/, void */*earg*/);
 299
 300 /* --- @rsa_verify@ --- *
 301  *
 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
 309  *
 310  * Returns:     The length of the output string if successful (0 if no output
 311  *              was wanted); negative on failure.
 312  *
 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
 317  *              zero for success.
 318  */
 319
 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*/);
 323
 324 /*----- Miscellaneous operations ------------------------------------------*/
 325
 326 /* --- @rsa_gen@ --- *
 327  *
 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
 334  *
 335  * Returns:     Zero if all went well, nonzero otherwise.
 336  *
 337  * Use:         Constructs a pair of strong RSA primes and other useful RSA
 338  *              parameters.  A small encryption exponent is chosen if
 339  *              possible.
 340  */
 341
 342 extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/,
 343                    grand */*r*/, unsigned /*n*/,
 344                    pgen_proc */*event*/, void */*ectx*/);
 345
 346 /* --- @rsa_recover@ --- *
 347  *
 348  * Arguments:   @rsa_priv *rp@ = pointer to parameter block
 349  *
 350  * Returns:     Zero if all went well, nonzero if the parameters make no
 351  *              sense.
 352  *
 353  * Use:         Derives the full set of RSA parameters given a minimal set.
 354  */
 355
 356 extern int rsa_recover(rsa_priv */*rp*/);
 357
 358 /*----- Padding schemes ---------------------------------------------------*/
 359
 360 /* --- PKCS1 padding --- */
 361
 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 */
 366 } pkcs1;
 367
 368 extern rsa_pad pkcs1_cryptencode;
 369 extern rsa_decunpad pkcs1_cryptdecode;
 370 extern rsa_pad pkcs1_sigencode;
 371 extern rsa_vrfunpad pkcs1_sigdecode;
 372
 373 /* --- OAEP --- */
 374
 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 */
 381 } oaep;
 382
 383 extern rsa_pad oaep_encode;
 384 extern rsa_decunpad oaep_decode;
 385
 386 /* --- PSS --- */
 387
 388 typedef struct pss {
 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 */
 393 } pss;
 394
 395 extern rsa_pad pss_encode;
 396 extern rsa_vrfunpad pss_decode;
 397
 398 /*----- That's all, folks -------------------------------------------------*/
 399
 400 #ifdef __cplusplus
 401   }
 402 #endif
 403
 404 #endif