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

   1 /* -*-c-*-
   2  *
   3  * $Id: rsa.h,v 1.3 2000/07/01 11:24:37 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: rsa.h,v $
  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.
  37  *
  38  * Revision 1.2  2000/06/17 12:07:36  mdw
  39  * Add key fetching interface.  Add new rsa_decrypt interface.
  40  *
  41  * Revision 1.1  1999/12/22 15:50:45  mdw
  42  * Initial RSA support.
  43  *
  44  */
  45
  46 #ifndef CATACOMB_RSA_H
  47 #define CATACOMB_RSA_H
  48
  49 #ifdef __cplusplus
  50   extern "C" {
  51 #endif
  52
  53 /*----- Header files ------------------------------------------------------*/
  54
  55 #ifndef CATACOMB_GRAND_H
  56 #  include "grand.h"
  57 #endif
  58
  59 #ifndef CATACOMB_KEY_H
  60 #  include "key.h"
  61 #endif
  62
  63 #ifndef CATACOMB_MP_H
  64 #  include "mp.h"
  65 #endif
  66
  67 #ifndef CATACOMB_PGEN_H
  68 #  include "pgen.h"
  69 #endif
  70
  71 /*----- Data structures ---------------------------------------------------*/
  72
  73 /* --- RSA private and public keys --- */
  74
  75 typedef struct rsa_pub {
  76   mp *n;
  77   mp *e;
  78 } rsa_pub;
  79
  80 typedef struct rsa_priv {
  81   mp *n, *p, *q, *q_inv;
  82   mp *e, *d, *dp, *dq;
  83 } rsa_priv;
  84
  85 /* --- RSA private and public key contexts --- *
  86  *
  87  * These are used to store information about `active' keys which will speed
  88  * up the various operations.
  89  */
  90
  91 typedef struct rsa_privctx {
  92   rsa_priv *rp;
  93   grand *r;
  94   mpmont nm, pm, qm;
  95 } rsa_privctx;
  96
  97 typedef struct rsa_pubctx {
  98   mpmont mm;
  99   rsa_pub *rp;
 100 } rsa_pubctx;
 101
 102 /* --- Encoding and decoding function schemas --- *
 103  *
 104  * See `oaep.h' and `pkcs1.h' for appropriate encoding functions.
 105  */
 106
 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*/);
 111
 112 /*----- Key fetching ------------------------------------------------------*/
 113
 114 extern const key_fetchdef rsa_pubfetch[];
 115 #define RSA_PUBFETCHSZ 4
 116
 117 extern const key_fetchdef rsa_privfetch[];
 118 #define RSA_PRIVFETCHSZ 12
 119
 120 /* --- @rsa_pubfree@, @rsa_privfree@ --- *
 121  *
 122  * Arguments:   @rsa_pub *rp@, @rsa_priv *rp@ = pointer to key block
 123  *
 124  * Returns:     ---
 125  *
 126  * Use:         Frees an RSA key block.
 127  */
 128
 129 extern void rsa_pubfree(rsa_pub */*rp*/);
 130 extern void rsa_privfree(rsa_priv */*rp*/);
 131
 132 /*----- RSA private key operations ----------------------------------------*/
 133
 134 /* --- @rsa_privcreate@ --- *
 135  *
 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
 139  *
 140  * Returns:     ---
 141  *
 142  * Use:         Initializes an RSA private-key context.  Keeping a context
 143  *              for several decryption or signing operations provides a minor
 144  *              performance benefit.
 145  *
 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.
 149  */
 150
 151 extern void rsa_privcreate(rsa_privctx */*rd*/, rsa_priv */*rp*/,
 152                            grand */*r*/);
 153
 154 /* --- @rsa_privdestroy@ --- *
 155  *
 156  * Arguments:   @rsa_privctx *rd@ = pointer to an RSA decryption context
 157  *
 158  * Returns:     ---
 159  *
 160  * Use:         Destroys an RSA decryption context.
 161  */
 162
 163 extern void rsa_privdestroy(rsa_privctx */*rd*/);
 164
 165 /* --- @rsa_privop@ --- *
 166  *
 167  * Arguments:   @rsa_privctx *rd@ = pointer to RSA private key context
 168  *              @mp *d@ = destination
 169  *              @mp *c@ = input message
 170  *
 171  * Returns:     The transformed output message.
 172  *
 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
 177  *              attacks.
 178  */
 179
 180 extern mp *rsa_privop(rsa_privctx */*rd*/, mp */*d*/, mp */*c*/);
 181
 182 /* --- @rsa_qprivop@ --- *
 183  *
 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
 188  *
 189  * Returns:     Correctly transformed output message
 190  *
 191  * Use:         Performs an RSA private key operation, very carefully.
 192  */
 193
 194 extern mp *rsa_qprivop(rsa_priv */*rp*/, mp */*d*/, mp */*c*/, grand */*r*/);
 195
 196 /* --- @rsa_sign@ --- *
 197  *
 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
 204  *
 205  * Returns:     The length of the output string if successful, negative on
 206  *              failure.
 207  *
 208  * Use:         Computes an RSA digital signature.
 209  */
 210
 211 extern int rsa_sign(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/,
 212                     dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/);
 213
 214 /* --- @rsa_decrypt@ --- *
 215  *
 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
 222  *
 223  * Returns:     The length of the output string if successful, negative on
 224  *              failure.
 225  *
 226  * Use:         Does RSA signature verification.
 227  */
 228
 229 extern int rsa_decrypt(rsa_privctx */*rp*/, const void */*m*/, size_t /*sz*/,
 230                        dstr */*d*/, rsa_decodeproc /*e*/, void */*earg*/);
 231
 232 /*----- RSA public key operations -----------------------------------------*/
 233
 234 /* --- @rsa_pubcreate@ --- *
 235  *
 236  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 237  *              @rsa_pub *rp@ = pointer to RSA public key
 238  *
 239  * Returns:     ---
 240  *
 241  * Use:         Initializes an RSA public-key context.
 242  */
 243
 244 extern void rsa_pubcreate(rsa_pubctx */*rd*/, rsa_pub */*rp*/);
 245
 246 /* --- @rsa_pubdestroy@ --- *
 247  *
 248  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 249  *
 250  * Returns:     ---
 251  *
 252  * Use:         Destroys an RSA public-key context.
 253  */
 254
 255 extern void rsa_pubdestroy(rsa_pubctx */*rd*/);
 256
 257 /* --- @rsa_pubop@ --- *
 258  *
 259  * Arguments:   @rsa_pubctx *rd@ = pointer to an RSA public key context
 260  *              @mp *d@ = destination
 261  *              @mp *p@ = input message
 262  *
 263  * Returns:     The transformed output message.
 264  *
 265  * Use:         Performs an RSA public key operation.
 266  */
 267
 268 extern mp *rsa_pubop(rsa_pubctx */*rd*/, mp */*d*/, mp */*p*/);
 269
 270 /* --- @rsa_qpubop@ --- *
 271  *
 272  * Arguments:   @rsa_pub *rp@ = pointer to RSA parameters
 273  *              @mp *d@ = destination
 274  *              @mp *p@ = input message
 275  *
 276  * Returns:     Correctly transformed output message.
 277  *
 278  * Use:         Performs an RSA public key operation.
 279  */
 280
 281 extern mp *rsa_qpubop(rsa_pub */*rp*/, mp */*d*/, mp */*c*/);
 282
 283 /* --- @rsa_encrypt@ --- *
 284  *
 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
 291  *
 292  * Returns:     The length of the output string if successful, negative on
 293  *              failure.
 294  *
 295  * Use:         Does RSA encryption.
 296  */
 297
 298 extern int rsa_encrypt(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/,
 299                        dstr */*d*/, rsa_encodeproc /*e*/, void */*earg*/);
 300
 301 /* --- @rsa_verify@ --- *
 302  *
 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
 309  *
 310  * Returns:     The length of the output string if successful, negative on
 311  *              failure.
 312  *
 313  * Use:         Does RSA signature verification.
 314  */
 315
 316 extern int rsa_verify(rsa_pubctx */*rp*/, const void */*m*/, size_t /*sz*/,
 317                       dstr */*d*/, rsa_decodeproc /*e*/, void */*earg*/);
 318
 319 /*----- Miscellaneous operations ------------------------------------------*/
 320
 321 /* --- @rsa_gen@ --- *
 322  *
 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
 329  *
 330  * Returns:     Zero if all went well, nonzero otherwise.
 331  *
 332  * Use:         Constructs a pair of strong RSA primes and other useful RSA
 333  *              parameters.  A small encryption exponent is chosen if
 334  *              possible.
 335  */
 336
 337 extern int rsa_gen(rsa_priv */*rp*/, unsigned /*nbits*/,
 338                    grand */*r*/, unsigned /*n*/,
 339                    pgen_proc */*event*/, void */*ectx*/);
 340
 341 /* --- @rsa_recover@ --- *
 342  *
 343  * Arguments:   @rsa_priv *rp@ = pointer to parameter block
 344  *
 345  * Returns:     Zero if all went well, nonzero if the parameters make no
 346  *              sense.
 347  *
 348  * Use:         Derives the full set of RSA parameters given a minimal set.
 349  */
 350
 351 extern int rsa_recover(rsa_priv */*rp*/);
 352
 353 /*----- That's all, folks -------------------------------------------------*/
 354
 355 #ifdef __cplusplus
 356   }
 357 #endif
 358
 359 #endif