<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = appendix-ii.xml                                                    = -->
<!-- = standard text processing module guide - appendix ii                = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2006 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="txt" number="ii">
  <title>Text hashing and ciphering reference</title>

  <p>
  This appendix is a reference of the <afnix/> text hashing and
  ciphering subsystem of the standard text processing module.
  module.
  </p>

  <table>
    <title>Standard text processing module</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-txt</td><td>module</td></tr>
      <tr><td>afnix:txt</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = hasher object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Hasher</name>

    <!-- synopsis -->
    <p>
    The <code>Hasher</code> class is a base class that is used to
    build a message hash. The hash result is stored in an array of
    bytes and can be retrieved byte by byte or as a formatted
    printable string. This class does not have a constructor.
    </p>

    <!-- predicate -->
    <pred>hasher-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method return the hash algorithm name.
      </p>
    </method>

    <method>
      <name>get-hash</name>
      <retn>Character</retn>
      <args>Integer</args>
      <p>
      The <code>get-hash</code> method returns the hash byte value by
      index. The argument is the byte index which must be in the range
      of the hash algorithm result value.
      </p>
    </method>

    <method>
      <name>format</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>format</code> method return a string representation of
      the hash value.
      </p>
    </method>

    <method>
      <name>compute</name>
      <retn>String</retn>
      <args>Literal|Buffer|Input</args>
      <p>
      The <code>compute</code> method computes the hash value from a
      string, a buffer or an input stream. The method returns a string
      representation of the result hash value.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = md5 object                                                      = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Md5</name>

    <!-- synopsis -->
    <p>
    The <code>Md5</code> class is a hashing class that implements the
    MD-5 algorithm.
    </p>

    <!-- predicate -->
    <pred>md5-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Hasher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Md5</name>
      <args>none</args>
      <p>
      The <code>Md5</code> constructor creates a default hashing
      object that implements the MD-5 algorithm.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = sha1 object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Sha1</name>

    <!-- synopsis -->
    <p>
    The <code>Sha1</code> class is a hashing class that implements the
    SHA-1 algorithm.
    </p>

    <!-- predicate -->
    <pred>sha1-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Hasher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Sha1</name>
      <args>none</args>
      <p>
      The <code>Sha1</code> constructor creates a default hashing
      object that implements the SHA-1 algorithm.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = sha256 object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Sha256</name>

    <!-- synopsis -->
    <p>
    The <code>Sha256</code> class is a hashing class that implements the
    SHA-256 algorithm.
    </p>

    <!-- predicate -->
    <pred>sha256-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Hasher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Sha256</name>
      <args>none</args>
      <p>
      The <code>Sha256</code> constructor creates a default hashing
      object that implements the SHA-256 algorithm.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = sha384 object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Sha384</name>

    <!-- synopsis -->
    <p>
    The <code>Sha384</code> class is a hashing class that implements the
    SHA-384 algorithm.
    </p>

    <!-- predicate -->
    <pred>sha384-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Hasher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Sha384</name>
      <args>none</args>
      <p>
      The <code>Sha384</code> constructor creates a default hashing
      object that implements the SHA-384 algorithm.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = sha512 object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Sha512</name>

    <!-- synopsis -->
    <p>
    The <code>Sha512</code> class is a hashing class that implements the
    SHA-512 algorithm.
    </p>

    <!-- predicate -->
    <pred>sha512-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Hasher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Sha512</name>
      <args>none</args>
      <p>
      The <code>Sha512</code> constructor creates a default hashing
      object that implements the SHA-512 algorithm.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = key object                                                      = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Key</name>

    <!-- synopsis -->
    <p>
    The <code>Key</code> class is a cipher key class that generates
    random key or message key. The key generation algorithm is based
    on the SHA-256 algorithm and accept different size. The default
    key size is 128 bits.
    </p>

    <!-- predicate -->
    <pred>key-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Key</name>
      <args>none</args>
      <p>
      The <code>Key</code> constructor creates a default cipher key.
      The key is generated with random bytes and is 128 bits long.
      </p>
    </ctor>

    <ctor>
      <name>Key</name>
      <args>K128|K192|K256</args>
      <p>
      The <code>Key</code> constructor creates a random cipher key by
      type. The argument is the key type which specify the key
      size.
      </p>
    </ctor>

    <ctor>
      <name>Key</name>
      <args>String</args>
      <p>
      The <code>Key</code> constructor creates a message cipher key
      those size is 128 bits long. The first argument is the message
      to be used for the key generation.
      </p>
    </ctor>

    <ctor>
      <name>Key</name>
      <args>K128|K192|K256 String</args>
      <p>
      The <code>Key</code> constructor creates a message cipher key
      by type. The first argument is the key type which specifies the
      key size. The second argument is the message to be used for the
      key generation.
      </p>
    </ctor>

    <!-- constants -->
    <constant>
      <name>K128</name>
      <p>
      The <code>K128</code> constant indicates that the key is a 128
      bits key.
      </p>
    </constant>

    <constant>
      <name>K192</name>
      <p>
      The <code>K192</code> constant indicates that the key is a 192
      bits key.
      </p>
    </constant>

    <constant>
      <name>K256</name>
      <p>
      The <code>K256</code> constant indicates that the key is a 256
      bits key.
      </p>
    </constant>

    <!-- methods -->
    <method>
      <name>get</name>
      <retn>Character</retn>
      <args>Integer</args>
      <p>
      The <code>get</code> method returns a key character by index.
      The index must be in the key range or an exception is raised.
      </p>
    </method>

    <method>
      <name>format</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>format</code> method returns a string representation
      of the key. Each byte is represented with its equivalent string
      representation.
      </p>
    </method>

    <method>
      <name>get-type</name>
      <retn>Item</retn>
      <args>none</args>
      <p>
      The <code>get-type</code> method returns the key type in the
      form of an item object. The item object is associated with the
      key object and the key size constant. The item can be used in
      key constructor.
      </p>
    </method>

    <method>
      <name>get-size</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-size</code> method returns the key size in bytes.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = cipher object                                                   = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Cipher</name>

    <!-- synopsis -->
    <p>
    The <code>Cipher</code> class is a base class that is used to
    implement a symmetric block cipher. A reverse flag controls the
    cipher operation. When false, the cipher operates in encrypt
    mode. When true, the cipher operates in decrypt mode, that is the
    reverse mode. This class cannot be instantiated by itself.
    </p>

    <!-- predicate -->
    <pred>cipher-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- methods -->
    <method>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the cipher internal state.
      </p>
    </method>

    <method>
      <name>stream</name>
      <retn>Integer</retn>
      <args>Output Input</args>
      <p>
      The <code>stream</code> method process an input stream and write
      into an output stream. The method returns the number of
      character processed. The first argument is the output stream
      used to write the coded characters. The second argument is the
      input stream used to read the characters.
      </p>
    </method>

    <method>
      <name>set-key</name>
      <retn>none</retn>
      <args>Key</args>
      <p>
      The <code>set-key</code> method sets the cipher key. The first
      argument is the key to set.
      </p>
    </method>

    <method>
      <name>get-key</name>
      <retn>Key</retn>
      <args>none</args>
      <p>
      The <code>get-key</code> method returns the cipher key.
      </p>
    </method>

    <method>
      <name>get-name</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-name</code> method returns the cipher standard name.
      </p>
    </method>

    <method>
      <name>get-size</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-size</code> method returns the cipher block size.
      </p>
    </method>

    <method>
      <name>set-reverse</name>
      <retn>none</retn>
      <args>Boolean</args>
      <p>
      The <code>set-reverse</code> method sets the cipher reverse
      flag. The first argument is the flag to set. If the flag is true,
      the cipher operates in reverse mode. If the flag is false, the
      cipher operates in direct mode.
      </p>
    </method>

    <method>
      <name>get-reverse</name>
      <retn>Boolean</retn>
      <args>none</args>
      <p>
      The <code>get-reverse</code> method returns the cipher reverse
      flag. If the flag is true, the cipher operates in reverse
      mode. If the flag is false, the cipher operates in direct mode.
      </p>
    </method>
  </object>

  <!-- =================================================================== -->
  <!-- = aes object                                                      = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>Aes</name>

    <!-- synopsis -->
    <p>
    The <code>Aes</code> class is a cipher class that implements the
    <em>advanced encryption standard</em> or AES block cipher. The AES
    cipher is a symmetric block cipher.
    </p>

    <!-- predicate -->
    <pred>aes-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Cipher</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>Aes</name>
      <args>Key</args>
      <p>
      The <code>Aes</code> constructor creates a direct cipher with a key.
      The first argument is the key used by the cipher.
      </p>
    </ctor>

    <ctor>
      <name>Aes</name>
      <args>Key Boolean</args>
      <p>
      The <code>Aes</code> constructor creates a cipher with a key and
      a reverse flag. The first argument is the key used by the
      cipher. The second argument is the reverse flag.
      </p>
    </ctor>
  </object>

  <!-- =================================================================== -->
  <!-- = input cipher object                                             = -->
  <!-- =================================================================== -->

  <object nameset="afnix:txt">
    <name>InputCipher</name>

    <!-- synopsis -->
    <p>
    The <code>InputCipher</code> class is an stream interface that can
    stream out an input stream from a cipher. In other word, an input
    stream is read and block are encoded as long as the input stream 
    read characters. If the cipher is nil, the input cipher simply
    read the input stream and is therefore transparent. The class acts
    like an input stream, read the character from the bounded input
    stream and encode or decode them from the bounded cipher. The
    <code>InputCipher</code> defines two modes of operations. In
    <em>electronic codebook mode</em> or ECB, the character are
    encoded in a block basis. In <em>cipher block chaining</em> mode,
    the block are encoded by doing an XOR operation with the previous
    block. In all cases, a block padding is added, following the
    recommendation of RFC 2630 and NIST 800-38A.
    </p>

    <!-- predicate -->
    <pred>input-cipher-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Input</name>
    </inherit>

    <!-- constructors -->
    <ctor>
      <name>InputCipher</name>
      <args>Cipher</args>
      <p>
      The <code>InputCipher</code> constructor creates an input cipher
      with a cipher object. The first argument is the cipher to used
      for processing.
      </p>
    </ctor>

    <ctor>
      <name>InputCipher</name>
      <args>Cipher Input</args>
      <p>
      The <code>InputCipher</code> constructor creates an input cipher
      with a cipher object and an input stream. The first argument is
      the cipher to used for processing. The second argument is the
      input stream object used for the character reading.
      </p>
    </ctor>

    <ctor>
      <name>InputCipher</name>
      <args>Cipher Input ECB|CBC</args>
      <p>
      The <code>InputCipher</code> constructor creates an input cipher
      with a cipher object, an input stream and a mode. The first
      argument is the cipher to used for processing. The second
      argument is the input stream object used for the character
      reading.  The third argument is the input cipher mode which can
      be either ECB or CBC.
      </p>
    </ctor>

    <!-- constants -->
    <constant>
      <name>ECB</name>
      <p>
      The <code>ECB</code> constant indicates that the input cipher is
      to operate in <em>electronic codebook</em> mode. This mode is
      the default mode.
      </p>
    </constant>

    <constant>
      <name>CBC</name>
      <p>
      The <code>CBC</code> constant indicates that the input cipher is
      to operate in <em>cipher chaining block</em> mode.
      </p>
    </constant>

    <!-- methods -->
    <method>
      <name>set-is</name>
      <retn>none</retn>
      <args>Input</args>
      <p>
      The <code>set-is</code> method sets the input cipher input stream.
      This method can be used to chain multiple input streams in a
      unique coding session.
      </p>
    </method>

    <method>
      <name>dup</name>
      <retn>InputCipher</retn>
      <args>Input</args>
      <p>
      The <code>dup</code> method duplicate the input cipher by
      binding the same input stream parameter and attaching the input
      stream argument. This method is particularly useful with
      <code>InputMapped</code> stream.
      </p>
    </method>
  </object>
</appendix>
