doc/rsa.doc

The RSA encryption and utility routines.

The RSA routines are built on top of a big number library (the BN library).
There are support routines in the X509 library for loading and manipulating
the various objects in the RSA library.  When errors are returned, read
about the ERR library for how to access the error codes.

All RSA encryption is done according to the PKCS-1 standard which is
compatible with PEM and RSAref.  This means that any values being encrypted
must be less than the size of the modulus in bytes, minus 10, bytes long.

This library uses RAND_bytes()() for it's random data, make sure to feed
RAND_seed() with lots of interesting and varied data before using these
routines.

The RSA library has one specific data type, the RSA structure.
It is composed of 8 BIGNUM variables (see the BN library for details) and
can hold either a private RSA key or a public RSA key.
Some RSA libraries have different structures for public and private keys, I
don't.  For my libraries, a public key is determined by the fact that the
RSA->d value is NULL.  These routines will operate on any size RSA keys.
While I'm sure 4096 bit keys are very very secure, they take a lot longer
to process that 1024 bit keys :-).

The function in the RSA library are as follows.

RSA *RSA_new();
	This function creates a new RSA object.  The sub-fields of the RSA
	type are also malloced so you should always use this routine to
	create RSA variables.
	
void RSA_free(
RSA *rsa);
	This function 'frees' an RSA structure.  This routine should always
	be used to free the RSA structure since it will also 'free' any
	sub-fields of the RSA type that need freeing.
	
int RSA_size(
RSA *rsa);	
	This function returns the size of the RSA modulus in bytes.  Why do
	I need this you may ask, well the reason is that when you encrypt
	with RSA, the output string will be the size of the RSA modulus.
	So the output for the RSA_encrypt and the input for the RSA_decrypt
	routines need to be RSA_size() bytes long, because this is how many
	bytes are expected.
	
For the following 4 RSA encryption routines, it should be noted that
RSA_private_decrypt() should be used on the output from 
RSA_public_encrypt() and RSA_public_decrypt() should be used on
the output from RSA_private_encrypt().
	
int RSA_public_encrypt(
int from_len;
unsigned char *from	
unsigned char *to	
RSA *rsa);
	This function implements RSA public encryption, the rsa variable
	should be a public key (but can be a private key).  'from_len'
	bytes taken from 'from' and encrypted and put into 'to'.  'to' needs
	to be at least RSA_size(rsa) bytes long.  The number of bytes
	written into 'to' is returned.  -1 is returned on an error.  The
	operation performed is
	to = from^rsa->e mod rsa->n.
	
int RSA_private_encrypt(
int from_len;
unsigned char *from	
unsigned char *to	
RSA *rsa);
	This function implements RSA private encryption, the rsa variable
	should be a private key.  'from_len' bytes taken from
	'from' and encrypted and put into 'to'.  'to' needs
	to be at least RSA_size(rsa) bytes long.  The number of bytes
	written into 'to' is returned.  -1 is returned on an error.  The
	operation performed is
	to = from^rsa->d mod rsa->n.

int RSA_public_decrypt(
int from_len;
unsigned char *from	
unsigned char *to	
RSA *rsa);
	This function implements RSA public decryption, the rsa variable
	should be a public key (but can be a private key).  'from_len'
	bytes are taken from 'from' and decrypted.  The decrypted data is
	put into 'to'.  The number of bytes encrypted is returned.  -1 is
	returned to indicate an error. The operation performed is
	to = from^rsa->e mod rsa->n.

int RSA_private_decrypt(
int from_len;
unsigned char *from	
unsigned char *to	
RSA *rsa);
	This function implements RSA private decryption, the rsa variable
	should be a private key.  'from_len' bytes are taken
	from 'from' and decrypted.  The decrypted data is
	put into 'to'.  The number of bytes encrypted is returned.  -1 is
	returned to indicate an error. The operation performed is
	to = from^rsa->d mod rsa->n.

int RSA_mod_exp(
BIGNUM *n;
BIGNUM *p;
RSA *rsa);
	Normally you will never use this routine.
	This is really an internal function which is called by
	RSA_private_encrypt() and RSA_private_decrypt().  It performs
	n=n^p mod rsa->n except that it uses the 5 extra variables in the
	RSA structure to make this more efficient.
	
RSA *RSA_generate_key(
int bits;
unsigned long e;
void (*callback)();
	This routine is used to generate RSA private keys.  It takes
	quite a period of time to run and should only be used to
	generate initial private keys that should then be stored
	for later use.  The passed callback function 
	will be called periodically so that feedback can be given
	as to how this function is progressing.
	'bits' is the length desired for the modulus, so it would be 1024
	to generate a 1024 bit private key.
	'e' is the value to use for the public exponent 'e'.  Traditionally
	it is set to either 3 or 0x10001.
	The callback function (if not NULL) is called in the following
	situations.
	when we have generated a suspected prime number to test,
	callback(0,num1++).  When it passes a prime number test,
	callback(1,num2++).  When it is rejected as one of
	the 2 primes required due to gcd(prime,e value) != 0,
	callback(2,num3++).  When finally accepted as one of the 2 primes,
	callback(3,num4++).