<!-- -*-html-*- -->

<section title="The Pike Crypto Toolkit" name=crypto>

<section title="Introduction">

The Crypto module provides an object-oriented framwork for encryption
and related functionality. More specifically, its objects han be
classified as follows:

<dl>
  <dt> Block ciphers 
  <dd> encrypt data in chunks of typically 8 bytes, using a secret
      key. 
  <dt> Stream ciphers 
  <dd> operate on the data to be encrypted one byte at a time, for
      exemple by xoring it with a sequence of pseudorandom bytes.
  <dt> Cryptographic hash functions
  <dd> transform a bytesequence of arbitrary length into a short
      string of a fixed length of typically 16 or 20 bytes, in such a
      way that it is practically impossible to find two distinct
      strings with the same hash value. 
  <dt> Public key algorithms 
  <dd> can support both encryption and digital signatures.
  <dt> Abstract building blocks 
  <dd> for combining ciphers (mainly for block ciphers). These objects
      behave like block ciphers, but delegate encryption to one or
      several underlying objects, in some way. 

      For example, block ciphers are often used in a feedback mode.
      The ciphers by themselves know nothing about these different
      "modes of operation", instead this knowledge is abstracted into
      separate objects. If you want IDEA in Cipher Block Chaining
      mode, you combine an IDEA object and a CBC object.

      <p> There are also other objects for cascading ciphers, useful for
      example you can build a triple-DES object by using three DES
      objects in sequence. 
  <dt> Randomness 
  <dd> is essential for many cryptographic application. The toolkit
      includes a few different random number generators, with varying
      degrees of true randomness.
  <dt> Frontend objects 
  <dd> that handle things like padding messages, or make it more
      convenient to use popular combinations of ciphers, feedback
      modes, etc.
</dl>

</section>
<section title="Block ciphers">

The block ciphers included in the current version are DES, IDEA and
CAST128 (note that IDEA is patented, see <a
href="http://www.ascom.ch/systec">Ascom Tech</a> for details).
All block ciphers have a common set of methods.

<method name="crypt_block">
<man_syntax>
string o->crypt_block(string <i>blocks</i>);
</man_syntax>

<man_description>
Encrypts or decrypts an even number of block, using the current key.
If more than one block is given, they are encrypted/decrypted
independently, i.e. in <i>Electronic Code Book</i> (ECB) mode.
</man_description>
</method>

<method name="query_block_size">
<man_syntax>
int o->query_block_size();
</man_syntax>

<man_description>
Returns the block size of the cipher, in octets. A typical block size
is 8 octets. A string passed to crypt_block() must have a length that
is a multiple of the block size.
</man_description>
</method>

<method name="query_key_length">
<man_syntax>
int o->query_key_length();
</man_syntax>

<man_description>
Returns the key size of the cipher, in octets. Note that some block
ciphers, e.g. CAST128, have a variable key size. In this case,
query_key_length returns the recommended key size, although keys of
other lengths are accepted by the set_encrypt_key and set_decrypt_key
methods.

For DES, the real key length is seven octets (56 bits), but the DES
standard mandates the use of parity bits. The query_key_length method
lies about DES, and says that the key_size is eight octets (64 bits).
See also <link to=des_parity>des_parity</link>.
</man_description>
</method>

<method name="set_encrypt_key">
<man_syntax>
object o->set_encrypt_key(string <i>key</i>);
</man_syntax>

<man_description>
Installs a key, and configures the object for doing encryption. For
convenience, this method returns the object itself.
</man_description>
</method>

<method name="set_decrypt_key">
<man_syntax>
object o->set_decrypt_key(string <i>key</i>);
</man_syntax>

<man_description>
Installs a key, and configures the object for doing decryption. For
convenience, this method returns the object itself.
</man_description>
</method>

The classes are <class name="Crypto.des">Crypto.des</class> <class
name="Crypto.idea">Crypto.idea</class> and <class
name="Crypto.cast">Crypto.cast</class>.

To encrypt the block "Pike des" using the DES-key '0123456789abcdef'
(in hex), use
<example language=pike>
Crypto.des()->set_encrypt_key(Crypto.hex_to_string("0123456789abcdef"))
            ->crypt_block("Pike DES")
</example>

although most applications will not use the Crypto.des class directly.
</section>

<section title="Stream Ciphers">

Currently the only stream cipher in the toolkit is the RC4 cipher
(also known as "arcfour"). 

<class name="Crypto.rc4">

<method name="crypt">
<man_syntax>
string Crypto.rc4->crypt(string <i>data</i>);
</man_syntax>

<man_description>
Encrypts or decrypts a string of data.
</man_description>
</method>

<method name="set_encrypt_key">
<man_syntax>
object Crypto.rc4->set_encrypt_key(string <i>key</i>);
</man_syntax>

<man_description>
Installs a key, and configures the object for doing encryption. For
convenience, this method returns the object itself. 
</man_description>
</method>

<method name="set_decrypt_key">
<man_syntax>
object Crypto.rc4->set_decrypt_key(string <i>key</i>);
</man_syntax>

<man_description>
Installs a key, and configures the object for doing decryption. For
convenience, this method returns the object itself.
</man_description>
</method>

Because of the way RC4 works, set_encrypt_key and set_decrypt_key are
actually equivalent.
</class>
</section>

<section title="Hash Functions">

Cryptographic hash functions are essential for many cryptographic
applications, and are also useful in other contexts. The Toolkit
includes the two most common, <i>MD5</i> and <i>SHA1</i>. They have
the same methods.

<method name="update">

<man_syntax>
object o->update(string <i>data</i>);
</man_syntax>

<man_description>
Processes some more data. For convenience, this method returns the
object itself. 
</man_description>
</method>

<method name="digest">
<man_syntax>
string o->digest();
</man_syntax>

<man_description>
Returns the hash value, or <i>message digest</i>, corresponding to all
the data that was previously passed to the update method. Also resets
the hash object, so that it can be used to process a new message.
</man_description>
</method>

<method name="query_digest_size">
<man_syntax>
int o->query_digest_size();
</man_syntax>

<man_description>
Returns the size, in octets, of the digests produced by this hash function.
</man_description>
</method>

To get the md5 hash of a string s, you would use

<example language=pike>
Crypto.md5()->update(s)->digest()
</example>

</section>
<section title="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 name="Crypto.rsa">
<method name=set_public_key>
<man_syntax>
object rsa->set_public_key(object(Gmp.mpz) modulo, object(Gmp.mpz) e)
</man_syntax>
<man_description>
Sets the modulo and the public exponent. For convenience, returns the
object itself.
</man_description>
</method>

<method name=set_private_key>
<man_syntax>
object rsa->set_public_key(object(Gmp.mpz) d)
</man_syntax>
<man_description>
Sets the private exponent. For convenience, returns the object itself.
</man_description>
</method>

<method name=generate_key>
<man_syntax>
object rsa->generate_key(int bits, function|void random)
</man_syntax>

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

<method name=query_blocksize>
<man_syntax>
int rsa->query_block_size()
</man_syntax>

<man_description>
Returns the length of the largest string that can be encrypted in one
RSA-operation using the current key.
</man_description>
</method>

<method name=encrypt>
<man_syntax>
string rsa->encrypt(string message, function|void random)
</man_syntax>

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

<method name=decrypt>
<man_syntax>
string rsa->decrypt(string gibberish)
</man_syntax>

<man_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.
</man_description>
</method>

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 name=sign>
<man_syntax>
object(Gmp.mpz) rsa->sign(string message, program hash)
</man_syntax>
<man_description>

Creates a PKCS#1-style signature. This operation requires knowledge of
the private key. <i>hash</i> 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

<example language=pike>
Standards.ASN1.Types.asn1_bit_string(rsa->sign(...))->get_der()
</example>
to convert it a DER-encoded ASN.1 bitstring.
</man_description>
</method>

<method name=verify>
<man_syntax>
int verify(string message, program hash, object(Gmp.mpz) signature)
</man_syntax>
<man_description>
Verifies a PKCS#1-style RSA signature. Returns 1 if the signature is
valid, 0 if not.
</man_description>
</method>

<method name=sha_sign>
<man_syntax>
string rsa->sha_sign(string message)
</man_syntax>
<man_description>
Creates an RSA signature using a simpler but non-standard convention.
</man_description>
</method>

<method name=sha_verify>
<man_syntax>
int sha_verify(string message, string signature)
</man_syntax>
<man_description>
Verifies signatures created by sha_sign. Returns 1 if the signature is
valid, 0 if not.
</man_description>
</method>

</class>
</section>

<section title="Combining block cryptos">
</section>
</section>