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

<!-- ====================================================================== -->
<!-- = appendix-iii.xml                                                   = -->
<!-- = standard security module guide - appendix iii                      = -->
<!-- ====================================================================== -->
<!-- = 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) 1999-2008 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="sec" number="iii">
  <title>Stream ciphers</title>

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

  <object nameset="afnix:sec">
    <name>BlockCipher</name>

    <!-- synopsis -->
    <p>
    The <code>BlockCipher</code> class is an abstract class that is
    used to implement a symmetric block cipher. By default the cipher
    operates in encryption mode. When the reverse flag is set, the
    decryption mode is activated. For a block cipher, a block size
    controls the cipher operations. The class also defines the
    constants that control the block padding with the associated
    methods.    
    </p>

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

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

    <!-- constants -->
    <constants>
     <const>
      <name>PAD-NONE</name>
      <p>
      The <code>PAD-NONE</code> constant indicates that the block should
      not be padded.
      </p>
     </const>

     <const>
      <name>PAD-BIT-MODE</name>
      <p>
      The <code>PAD-BIT</code> constant indicates that the block
      should be padded in bit mode.
      </p>
     </const>

     <const>
      <name>PAD-ANSI-X923</name>
      <p>
      The <code>PAD-ANSI-X923</code> constant indicates that the block
      should be padded according to ANSI X 923 standard.
      </p>
     </const>

     <const>
      <name>PAD-NIST-800</name>
      <p>
      The <code>PAD-NIST-800</code> constant indicates that the block
      should be padded according to NIST 800-38A recommendations. This
      is the default mode.      
      </p>
     </const>
    </constants>

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

     <meth>
      <name>set-padding-mode</name>
      <retn>none</retn>
      <args>Item</args>
      <p>
      The <code>set-padding-mode</code> method sets the cipher padding
      mode.
      </p>
     </meth>

     <meth>
      <name>get-padding-mode</name>
      <retn>Item</retn>
      <args>none</args>
      <p>
      The <code>get-padding-mode</code> method returns the cipher
      padding mode.
      </p>
     </meth>
    </methods>
  </object>

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

  <object nameset="afnix:sec">
    <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 several 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. Other modes such like <em>cipher feedback mode</em>
    and <em>output feedback mode</em> are also defined.
    </p>

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

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

    <!-- constructors -->
    <ctors>
     <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 Item</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, CBC, CFB or OFB.
      </p>
     </ctor>
    </ctors>

    <!-- constants -->
    <constants>
     <const>
      <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>
     </const>

     <const>
      <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>
     </const>

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

     <const>
      <name>OFB</name>
      <p>
      The <code>OFB</code> constant indicates that the input cipher is
      to operate in <em>output feedback block</em> mode.
      </p>
     </const>
    </constants>

    <!-- methods -->
    <methods>
     <meth>
      <name>reset</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>reset</code> method reset the input cipher object.
      </p>
     </meth>

     <meth>
      <name>get-mode</name>
      <retn>Item</retn>
      <args>none</args>
      <p>
      The <code>get-mode</code> method returns the input cipher
      operating mode.
      </p>
     </meth>

     <meth>
      <name>set-iv</name>
      <retn>none</retn>
      <args>String|Buffer</args>
      <p>
      The <code>set-iv</code> method sets the input cipher initial
      vector. In the first form, the initial vector is set from an
      octet string. In the second form, the initial vector is set from
      a buffer object.
      </p>
     </meth>

     <meth>
      <name>get-iv</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-iv</code> method returns the input cipher initial
      vector as an octet string.
      </p>
     </meth>

     <meth>
      <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>
     </meth>
    </methods>
  </object>

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

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

    <!-- synopsis -->
    <p>
    The <code>Aes</code> class is a block cipher class that implements
    the <em>advanced encryption standard</em> (AES), originally
    known as rijndael. This is an original implementation that
    conforms to the standard FIPS PUB 197. It should be noted that the
    AES standard, unlike rijndael, defines a fixed block size of 16
    bytes (4 words) and 3 keys sizes (128, 192, 256).
    </p>

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

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

    <!-- constructors -->
    <ctors>
     <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>
    </ctors>
  </object>
</appendix>
