136 lines
5.3 KiB
Plaintext
136 lines
5.3 KiB
Plaintext
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)();
|
|
char *cb_arg;
|
|
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++,cb_arg). When it passes a prime number test,
|
|
callback(1,num2++,cb_arg). When it is rejected as one of
|
|
the 2 primes required due to gcd(prime,e value) != 0,
|
|
callback(2,num3++,cb_arg). When finally accepted as one
|
|
of the 2 primes, callback(3,num4++,cb_arg).
|
|
|