Module Cryptokit.RSA
The RSA
module implements RSA public-key cryptography. Public-key cryptography is asymmetric: two distinct keys are used for encrypting a message, then decrypting it. Moreover, while one of the keys must remain secret, the other can be made public, since it is computationally very hard to reconstruct the private key from the public key. This feature supports both public-key encryption (anyone can encode with the public key, but only the owner of the private key can decrypt) and digital signature (only the owner of the private key can sign, but anyone can check the signature with the public key).
type key
=
{
}
The type of RSA keys. Components
size
,n
ande
define the public part of the key. Componentssize
,n
andd
define the private part of the key. To speed up private key operations through the use of the Chinese remainder theorem (CRT), additional componentsp
,q
,dp
,dq
andqinv
are provided. These are part of the private key.
val wipe_key : key -> unit
Erase all components of a RSA key.
val new_key : ?rng:Random.rng -> ?e:int -> int -> key
Generate a new, random RSA key. The non-optional
int
argument is the desired size for the modulus, in bits (e.g. 2048). The optionalrng
argument specifies a random number generator to use for generating the key; it defaults toCryptokit.Random.secure_rng
. The optionale
argument specifies the public exponent desired. If not specified,e
is chosen randomly. Small values ofe
such ase = 65537
significantly speeds up encryption and signature checking compared with a randome
. Very small values ofe
such ase = 3
can weaken security and are best avoided. The result ofnew_key
is a complete RSA key with all components defined: public, private, and private for use with the CRT.
val encrypt : key -> string -> string
encrypt k msg
encrypts the stringmsg
with the public part of keyk
(componentsn
ande
).msg
must be smaller thankey.n
when both strings are viewed as natural numbers in big-endian notation. In practice,msg
should be of lengthkey.size / 8 - 1
, using padding if necessary. If you need to encrypt longer plaintexts using RSA, encrypt them with a symmetric cipher, using a randomly-generated key, and encrypt only that key with RSA.
val decrypt : key -> string -> string
decrypt k msg
decrypts the ciphertext stringmsg
with the private part of keyk
(componentsn
andd
). The size ofmsg
is limited as described forCryptokit.RSA.encrypt
.
val decrypt_CRT : key -> string -> string
decrypt_CRT k msg
decrypts the ciphertext stringmsg
with the CRT private part of keyk
(componentsn
,p
,q
,dp
,dq
andqinv
). The use of the Chinese remainder theorem (CRT) allows significantly faster decryption thanCryptokit.RSA.decrypt
, at no loss in security. The size ofmsg
is limited as described forCryptokit.RSA.encrypt
.
val sign : key -> string -> string
sign k msg
encrypts the plaintext stringmsg
with the private part of keyk
(componentsn
andd
), thus performing a digital signature onmsg
. The size ofmsg
is limited as described forCryptokit.RSA.encrypt
. If you need to sign longer messages, compute a cryptographic hash of the message and sign only the hash with RSA.
val sign_CRT : key -> string -> string
sign_CRT k msg
encrypts the plaintext stringmsg
with the CRT private part of keyk
(componentsn
,p
,q
,dp
,dq
andqinv
), thus performing a digital signature onmsg
. The use of the Chinese remainder theorem (CRT) allows significantly faster signature thanCryptokit.RSA.sign
, at no loss in security. The size ofmsg
is limited as described forCryptokit.RSA.encrypt
.
val unwrap_signature : key -> string -> string
unwrap_signature k msg
decrypts the ciphertext stringmsg
with the public part of keyk
(componentsn
andd
), thus extracting the plaintext that was signed by the sender. The size ofmsg
is limited as described forCryptokit.RSA.encrypt
.