Previous section To contents Next section

14.14.5 Public key algorithms

The only public key algorithm currently in the toolkit is RSA. As the algorithm uses arithmetic on huge numbers, you must also have the GMP library and the corresponding Pike module installed in order to use RSA.

CLASS
Crypto.rsa

METHOD
Crypto.rsa.set_public_key

SYNTAX
object rsa->set_public_key(object(Gmp.mpz) modulo, object(Gmp.mpz) e)

DESCRIPTION
Sets the modulo and the public exponent. For convenience, returns the object itself.

METHOD
Crypto.rsa.set_private_key

SYNTAX
object rsa->set_public_key(object(Gmp.mpz) d)

DESCRIPTION
Sets the private exponent. For convenience, returns the object itself.

METHOD
Crypto.rsa.generate_key

SYNTAX
object rsa->generate_key(int bits, function|void random)

DESCRIPTION
Generates a new rsa key pair, with a modulo of the given bitsize. random should be a function that takes one integer argument n and returns a string of n random octets. The default function is Crypto.randomness.really_random()->read. For convenience, this method returns the object itself.

METHOD
Crypto.rsa.query_blocksize

SYNTAX
int rsa->query_block_size()

DESCRIPTION
Returns the length of the largest string that can be encrypted in one RSA-operation using the current key.

METHOD
Crypto.rsa.encrypt

SYNTAX
string rsa->encrypt(string message, function|void random)

DESCRIPTION
Encrypts message using PKCS#1-style RSA encryption. The function random is used to generate random message padding. Padding does not require a strong random number generator. The default random function is derived from Pike's builting pseudorandom generator predef::random.

METHOD
Crypto.rsa.decrypt

SYNTAX
string rsa->decrypt(string gibberish)

DESCRIPTION
Decrypts a PKCS#1-style RSA-encrypted message. This operation requires knowledge of the private key. Decryption may fail if the input is not a properly encrypted message for this key. In this case, the method returns zero. The PKCS#1 padding method used is vulnerable to a chosen-ciphertext attack discovered by Daniel Bleichenbacher.
There are several methods for signature creation and verification. I don't quite like the interface, so it may very well change in some future version of the Toolkit.

METHOD
Crypto.rsa.sign

SYNTAX
object(Gmp.mpz) rsa->sign(string message, program hash)

DESCRIPTION
Creates a PKCS#1-style signature. This operation requires knowledge of the private key. hash should be a hash algorithm with an ->identifier method which returns a DER-encoded ASN.1 Object Identifier for the hash algorithm. Currently, this is supported only by Crypto.md5. The function returns the signature as a bignum; applications can use 
Standards.ASN1.Types.asn1_bit_string(rsa->sign(...))->get_der()
to convert it a DER-encoded ASN.1 bitstring.

METHOD
Crypto.rsa.verify

SYNTAX
int verify(string message, program hash, object(Gmp.mpz) signature)

DESCRIPTION
Verifies a PKCS#1-style RSA signature. Returns 1 if the signature is valid, 0 if not.

METHOD
Crypto.rsa.sha_sign

SYNTAX
string rsa->sha_sign(string message)

DESCRIPTION
Creates an RSA signature using a simpler but non-standard convention.

METHOD
Crypto.rsa.sha_verify

SYNTAX
int sha_verify(string message, string signature)

DESCRIPTION
Verifies signatures created by sha_sign. Returns 1 if the signature is valid, 0 if not.
Previous section To contents Next section