doc/rsa.doc

   1 The RSA encryption and utility routines.
   2
   3 The RSA routines are built on top of a big number library (the BN library).
   4 There are support routines in the X509 library for loading and manipulating
   5 the various objects in the RSA library.  When errors are returned, read
   6 about the ERR library for how to access the error codes.
   7
   8 All RSA encryption is done according to the PKCS-1 standard which is
   9 compatible with PEM and RSAref.  This means that any values being encrypted
  10 must be less than the size of the modulus in bytes, minus 10, bytes long.
  11
  12 This library uses RAND_bytes()() for it's random data, make sure to feed
  13 RAND_seed() with lots of interesting and varied data before using these
  14 routines.
  15
  16 The RSA library has one specific data type, the RSA structure.
  17 It is composed of 8 BIGNUM variables (see the BN library for details) and
  18 can hold either a private RSA key or a public RSA key.
  19 Some RSA libraries have different structures for public and private keys, I
  20 don't.  For my libraries, a public key is determined by the fact that the
  21 RSA->d value is NULL.  These routines will operate on any size RSA keys.
  22 While I'm sure 4096 bit keys are very very secure, they take a lot longer
  23 to process that 1024 bit keys :-).
  24
  25 The function in the RSA library are as follows.
  26
  27 RSA *RSA_new();
  28         This function creates a new RSA object.  The sub-fields of the RSA
  29         type are also malloced so you should always use this routine to
  30         create RSA variables.
  31
  32 void RSA_free(
  33 RSA *rsa);
  34         This function 'frees' an RSA structure.  This routine should always
  35         be used to free the RSA structure since it will also 'free' any
  36         sub-fields of the RSA type that need freeing.
  37
  38 int RSA_size(
  39 RSA *rsa);
  40         This function returns the size of the RSA modulus in bytes.  Why do
  41         I need this you may ask, well the reason is that when you encrypt
  42         with RSA, the output string will be the size of the RSA modulus.
  43         So the output for the RSA_encrypt and the input for the RSA_decrypt
  44         routines need to be RSA_size() bytes long, because this is how many
  45         bytes are expected.
  46
  47 For the following 4 RSA encryption routines, it should be noted that
  48 RSA_private_decrypt() should be used on the output from
  49 RSA_public_encrypt() and RSA_public_decrypt() should be used on
  50 the output from RSA_private_encrypt().
  51
  52 int RSA_public_encrypt(
  53 int from_len;
  54 unsigned char *from
  55 unsigned char *to
  56 RSA *rsa);
  57         This function implements RSA public encryption, the rsa variable
  58         should be a public key (but can be a private key).  'from_len'
  59         bytes taken from 'from' and encrypted and put into 'to'.  'to' needs
  60         to be at least RSA_size(rsa) bytes long.  The number of bytes
  61         written into 'to' is returned.  -1 is returned on an error.  The
  62         operation performed is
  63         to = from^rsa->e mod rsa->n.
  64
  65 int RSA_private_encrypt(
  66 int from_len;
  67 unsigned char *from
  68 unsigned char *to
  69 RSA *rsa);
  70         This function implements RSA private encryption, the rsa variable
  71         should be a private key.  'from_len' bytes taken from
  72         'from' and encrypted and put into 'to'.  'to' needs
  73         to be at least RSA_size(rsa) bytes long.  The number of bytes
  74         written into 'to' is returned.  -1 is returned on an error.  The
  75         operation performed is
  76         to = from^rsa->d mod rsa->n.
  77
  78 int RSA_public_decrypt(
  79 int from_len;
  80 unsigned char *from
  81 unsigned char *to
  82 RSA *rsa);
  83         This function implements RSA public decryption, the rsa variable
  84         should be a public key (but can be a private key).  'from_len'
  85         bytes are taken from 'from' and decrypted.  The decrypted data is
  86         put into 'to'.  The number of bytes encrypted is returned.  -1 is
  87         returned to indicate an error. The operation performed is
  88         to = from^rsa->e mod rsa->n.
  89
  90 int RSA_private_decrypt(
  91 int from_len;
  92 unsigned char *from
  93 unsigned char *to
  94 RSA *rsa);
  95         This function implements RSA private decryption, the rsa variable
  96         should be a private key.  'from_len' bytes are taken
  97         from 'from' and decrypted.  The decrypted data is
  98         put into 'to'.  The number of bytes encrypted is returned.  -1 is
  99         returned to indicate an error. The operation performed is
 100         to = from^rsa->d mod rsa->n.
 101
 102 int RSA_mod_exp(
 103 BIGNUM *n;
 104 BIGNUM *p;
 105 RSA *rsa);
 106         Normally you will never use this routine.
 107         This is really an internal function which is called by
 108         RSA_private_encrypt() and RSA_private_decrypt().  It performs
 109         n=n^p mod rsa->n except that it uses the 5 extra variables in the
 110         RSA structure to make this more efficient.
 111
 112 RSA *RSA_generate_key(
 113 int bits;
 114 unsigned long e;
 115 void (*callback)();
 116 char *cb_arg;
 117         This routine is used to generate RSA private keys.  It takes
 118         quite a period of time to run and should only be used to
 119         generate initial private keys that should then be stored
 120         for later use.  The passed callback function
 121         will be called periodically so that feedback can be given
 122         as to how this function is progressing.
 123         'bits' is the length desired for the modulus, so it would be 1024
 124         to generate a 1024 bit private key.
 125         'e' is the value to use for the public exponent 'e'.  Traditionally
 126         it is set to either 3 or 0x10001.
 127         The callback function (if not NULL) is called in the following
 128         situations.
 129         when we have generated a suspected prime number to test,
 130         callback(0,num1++,cb_arg).  When it passes a prime number test,
 131         callback(1,num2++,cb_arg).  When it is rejected as one of
 132         the 2 primes required due to gcd(prime,e value) != 0,
 133         callback(2,num3++,cb_arg).  When finally accepted as one
 134         of the 2 primes, callback(3,num4++,cb_arg).
 135