From 6a9a9a72d5b20e2f336a59dbe85b086d7d20fafd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niels=20M=C3=B6ller?= <nisse@lysator.liu.se>
Date: Thu, 4 Feb 1999 15:43:12 +0100
Subject: [PATCH] crypto.wmml
Rev: tutorial/crypto.wmml:1.1
---
tutorial/crypto.wmml | 226 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 226 insertions(+)
create mode 100644 tutorial/crypto.wmml
diff --git a/tutorial/crypto.wmml b/tutorial/crypto.wmml
new file mode 100644
index 0000000000..a9b7cc63d3
--- /dev/null
+++ b/tutorial/crypto.wmml
@@ -0,0 +1,226 @@
+<--! -*-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)->set_iv(iv)->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>
--
GitLab