diff options
Diffstat (limited to 'doc/rsa.doc')
| -rw-r--r-- | doc/rsa.doc | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/doc/rsa.doc b/doc/rsa.doc new file mode 100644 index 0000000000..f899a39bb8 --- /dev/null +++ b/doc/rsa.doc @@ -0,0 +1,133 @@ +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++). |