pike.git / tutorial / crypto.wmml

version» Context lines:

pike.git/tutorial/crypto.wmml:1: + <--! -*-html-*- -->    -  + <section title="The Pike Crypto Toolkit"> +  + <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 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 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 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 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> +  + The classes are <class name="Crypto.des"></class> <class + name="Crypto.idea"></class> <class name="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 name="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</>); + </man_syntax> +  + <man_description> + Encrypts or decrypts a string of data. + </man_description> +  + <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 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> +  + Because of the way RC4 works, set_encrypt_key and set_decrypt_key are + actually equivalent. +  + </section> +  + <section name="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 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 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 name="create"> + <man_syntax> + void o->create(void|object) + All block ciphers have a common set of methods +  + <example type=pike> + <caption>Creating an object encrypting using IDEA in CBC-mode</caption> + Crypto(CBC(IDEA)-&gt;set_iv(iv)-&gt;set_encrypt_key(key) + </example> + <p> There is a pike implementation of <link to=ssl type=used_by>SSL (Secure + socket Layer)</link> built on top of the crypto toolkit.</p> + </description> +  + <future> + Compatibility with standards such as RSA Inc's PKCS (Public Key + Cryptography Standards) might be useful. + </future>   Newline at end of file added.