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

<!-- ====================================================================== -->
<!-- = secrm.xml                                                          = -->
<!-- = standard security module - reference manual                        = -->
<!-- ====================================================================== -->
<!-- = 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-2019 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="sec" number="i">
  <title>Standard Security Reference</title>

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

  <object nameset="afnix:sec">
    <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>Nameable</name>
    </inherit>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the hasher object with its
	  associated internal states.
	</p>
      </meth>

      <meth>
	<name>hash-p</name>
	<retn>Boolean</retn>
	<args>String</args>
	<p>
	  The <code>hash-p</code> predicate returns true if the string argument
	  is potentially a hash value. It is not possible, with our current
	  technology, to reverse a hash value to one or several
	  representations, nor it is possible to assert that such value exists.
	</p>
      </meth>

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

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

      <meth>
	<name>compute</name>
	<retn>String</retn>
	<args>Literal|Buffer|InputStream</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. When the argument is a 
	  buffer object or an input stream, the characters are consumed from the
	  object.
	</p>
      </meth>

      <meth>
	<name>derive</name>
	<retn>String</retn>
	<args>String</args>
	<p>
	  The <code>derive</code> method computes the hash value from an
	  octet string which is converted before the hash computation. The
	  method returns a string representation of the result hash value.
	</p>
      </meth>

      <meth>
	<name>get-hash-length</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-hash-length</code> method returns the hasher
	  length in bytes.
	</p>
      </meth>

      <meth>
	<name>get-result-length</name>
	<retn>Integer</retn>
	<args>none</args>
	<p>
	  The <code>get-result-length</code> method returns the hasher
	  result length in bytes. The result length is less or equal to
	  the hasher length and is set at construction.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = md2 object                                                      = -->
  <!-- =================================================================== -->

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

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

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

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

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

      <ctor>
	<name>Md2</name>
	<args>Integer</args>
	<p>
	  The <code>Md2</code> constructor creates a MD-2 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

  <!-- =================================================================== -->
  <!-- = md4 object                                                      = -->
  <!-- =================================================================== -->

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

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

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

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

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

      <ctor>
	<name>Md4</name>
	<args>Integer</args>
	<p>
	  The <code>Md4</code> constructor creates a MD-4 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor> 
    </ctors>
  </object>

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

  <object nameset="afnix:sec">
    <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 -->
    <ctors>
      <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>

      <ctor>
	<name>Md5</name>
	<args>Integer</args>
	<p>
	  The <code>Md5</code> constructor creates a MD-5 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

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

  <object nameset="afnix:sec">
    <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 -->
    <ctors>
      <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>

      <ctor>
	<name>Sha1</name>
	<args>Integer</args>
	<p>
	  The <code>Sha1</code> constructor creates a SHA-1 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

  <!-- =================================================================== -->
  <!-- = sha224 object                                                   = -->
  <!-- =================================================================== -->

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

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

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

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

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

      <ctor>
	<name>Sha224</name>
	<args>Integer</args>
	<p>
	  The <code>Sha224</code> constructor creates a SHA-224 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

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

  <object nameset="afnix:sec">
    <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 -->
    <ctors>
      <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>

      <ctor>
	<name>Sha256</name>
	<args>Integer</args>
	<p>
	  The <code>Sha256</code> constructor creates a SHA-256 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

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

  <object nameset="afnix:sec">
    <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 -->
    <ctors>
      <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>

      <ctor>
	<name>Sha384</name>
	<args>Integer</args>
	<p>
	  The <code>Sha384</code> constructor creates a SHA-384 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

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

  <object nameset="afnix:sec">
    <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 -->
    <ctors>
      <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>

      <ctor>
	<name>Sha512</name>
	<args>Integer</args>
	<p>
	  The <code>Sha512</code> constructor creates a SHA-512 hashing
	  object with a result length. The argument is the hasher result
	  length that must be less or equal to the hasher length.
	</p>
      </ctor>
    </ctors>
  </object>

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

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

    <!-- synopsis -->
    <p>
      The <code>Key</code> class is an original class used to store a
      particular key or to generate one. A key is designed to operate
      with a variety of cipher that can be either symmetric or
      asymmetric. In the symmetric case, the key is generally an array
      of bytes. Asymmetric key are generally stored in the form of
      number list that can be computed or loaded by value. By default, a
      random 128 bit symmetric key is created.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <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>String</args>
	<p>
	  The <code>Key</code> constructor creates a symmetric key from an
	  octet string. The octet string argument determines the size of
	  the key. The octet string argument is compatible with the string
	  obtained from the <code>format</code> method.
	</p>
      </ctor>

      <ctor>
	<name>Key</name>
	<args>Item</args>
	<p>
	  The <code>Key</code> constructor creates a key by type. If the
	  key type is <code>KSYM</code>, a symmetric 128 bytes random key is
	  generated. If the key type is <code>KRSA</code>, a 1024 bits RSA
	  random key is generated.
	</p>
      </ctor>

      <ctor>
	<name>Key</name>
	<args>Item Integer|String|Vector</args>
	<p>
	  The <code>Key</code> constructor creates a key by type. The
	  first argument is the key type to generate. The second argument
	  is either the key size, the key octet string or the key byte values.
	  In the first form, an integer argument specifies the key size in bytes
	  or bits depending on the key nature. In the second form, a string is 
	  used as octet string to represent the key. In the third form, a vector
	  of byte values can be used to load the key.
	</p>
      </ctor>
    </ctors>

    <!-- constants -->
    <constants>
      <const>
	<name>KSYM</name>
	<p>
	  The <code>KSYM</code> constant indicates that the key is a 
	  symmetric key.
	</p>
      </const>

      <const>
	<name>KRSA</name>
	<p>
	  The <code>KRSA</code> constant indicates that the key is a 
	  asymmetric RSA key.
	</p>
      </const>

      <const>
	<name>KMAC</name>
	<p>
	  The <code>KMAC</code> constant indicates that the key is a 
	  message authentication (MAC) key.
	</p>
      </const>

      <const>
	<name>RSA-MODULUS</name>
	<p>
	  The <code>RSA-MODULUS</code> constant corresponds to the RSA
	  modulus value.
	</p>
      </const>

      <const>
	<name>RSA-PUBLIC-EXPONENT</name>
	<p>
	  The <code>RSA-PUBLIC-EXPONENT</code> constant corresponds to the RSA
	  public exponent value which is generally 65537.
	</p>
      </const>

      <const>
	<name>RSA-SECRET-EXPONENT</name>
	<p>
	  The <code>RSA-SECRET-EXPONENT</code> constant corresponds to the RSA
	  secret exponent value.
	</p>
      </const>
    </constants>

    <!-- methods -->
    <methods>
      <meth>
	<name>get-byte</name>
	<retn>Byte</retn>
	<args>Integer</args>
	<p>
	  The <code>get-byte</code> method returns a key byte value by index.
	  The index must be in the key range or an exception is
	  raised. This method is primarily used with symmetric key.
	</p>
      </meth>

      <meth>
	<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.
	</p>
      </meth>

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

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

      <meth>
	<name>format</name>
	<retn>String</retn>
	<args>none|Item</args>
	<p>
	  The <code>format</code> method returns a string representation
	  of the key. In the first form, without argument, the key is
	  returned as an octet string if possible. In the second form, the
	  key value is returned as an octet string based on the key
	  element to access.
	</p>
      </meth>

      <meth>
	<name>get-relatif-key</name>
	<retn>Relatif</retn>
	<args>Item</args>
	<p>
	  The <code>get-relatif-key</code> method returns a relatif
	  representation of a key element. This method is well suited for
	  asymmetric key. The key value is returned as a relatif based on
	  the key element to access.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = kdf object                                                      = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Kdf</code> class is an abstract class used to model key
      derivation function. The class provides only a byte buffer which
      can be accessed by index. In the key derivation functions land,
      there are numerous standards, such like PKCS 2.1, IEEE P1363-2000,
      ISO/IEC 18033-2. All of these standards have sometimes conflicting
      definitions.
    </p>

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

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

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the internal state of the kdf
	  object.
	</p>
      </meth>

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

      <meth>
	<name>get-byte</name>
	<retn>Byte</retn>
	<args>Integer</args>
	<p>
	  The <code>get-byte</code> method returns a kdf byte value by index.
	  The index must be in the key range or an exception is raised.
	</p>
      </meth>

      <meth>
	<name>format</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>format</code> method returns a string representation
	  of the derived key.
	</p>
      </meth>

      <meth>
	<name>derive</name>
	<retn>String</retn>
	<args>String</args>
	<p>
	  The <code>derive</code> method returns a string representation
	  of a derived key computed from the octet string argument.
	</p>
      </meth>

      <meth>
	<name>compute</name>
	<retn>String</retn>
	<args>String</args>
	<p>
	  The <code>compute</code> method returns a string representation
	  of a derived key computed from the string argument.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = hkdf object                                                      = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Hkdf</code> class is an abstract class used to model key
      derivation function  based on hash function. The class maintains a
      hasher object that is used to derive the key from an octet string.
    </p>

    <!-- predicate -->
    <pred>hashed-kdf-p</pred>

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

    <!-- methods -->
    <methods>
      <meth>
	<name>get-hasher</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>get-hasher</code> method returns the hasher object
	  associated with the key derivation function object.
	  object.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = kdf1 object                                                     = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Kdf1</code> class is a hashed key derivation function
      class that implements the KDF1 specification as defined by ISO/IEC
      18033-2. The class is strictly equivalent to the mask generation
      function (MGF1) defined in PKCS 2.1. On the other hand, this
      implementation does not conform to the KDF1 specification of IEEE
      1363-2000 which is somehow rather bizarre. The class operates in
      theory with any type of hasher object as long as the octet string
      is not too long.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Kdf1</name>
	<args>Hasher Integer</args>
	<p>
	  The <code>Kdf1</code> constructor creates a KDF1 key derivation
	  function object. The first argument is the hasher object to bind
	  and the second argument is the kdf size.
	</p>
      </ctor>
    </ctors>
  </object>

  <!-- =================================================================== -->
  <!-- = kdf2 object                                                   = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Kdf2</code> class is a hashed key derivation function
      class that implements the KDF2 specification as defined by ISO/IEC
      18033-2. The class is strictly equivalent to the key function
      derivation (KDF1) except that the internal counter runs from 1 to
      k instead of 0 to k-1. The class operates in theory with any type
      of hasher object as long as the octet string is not too long.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Kdf2</name>
	<args>Hasher Integer</args>
	<p>
	  The <code>Kdf2</code> constructor creates a KDF2 key derivation
	  function object. The first argument is the hasher object to bind
	  and the second argument is the kdf size.
	</p>
      </ctor>
    </ctors>
  </object>

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

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

    <!-- synopsis -->
    <p>
      The <code>Cipher</code> class is a base class that is used to
      implement a cipher. A cipher is used to encrypt or decrypt a
      message. There are basically two types of ciphers, namely
      symmetric cipher and asymmetric cipher. For the base class
      operation, only the cipher name and key is needed. A reverse flag
      controls whether or not an encryption operation must be
      reversed. A reset method can also be used to reset the internal
      cipher state. 
    </p>

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

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

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

      <meth>
	<name>stream</name>
	<retn>Integer</retn>
	<args>OutputStream InputStream</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>
      </meth>

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

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

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

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

  <!-- =================================================================== -->
  <!-- = 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 InputStream 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>InputStream</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>

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

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

    <!-- synopsis -->
    <p>
      The <code>PublicCipher</code> class is an abstract class that is
      used to implement an asymmetric cipher. An asymmetric cipher or
      public key cipher is designed to operate with a public key and a
      secret key. Depending on the use model, the public key might be
      used to crypt the data, and the secret key to decrypt. The basic
      assumption around a public cipher is that the secret key cannot be
      derived from the public key.
    </p>

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

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

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

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

  <!-- =================================================================== -->
  <!-- = rsa object                                                      = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Rsa</code> class is a public cipher class that
      implements the RSA algorithm as described by PKCS 2.1, RFC 2437
      and ISO 18033-2. The class implements also some padding mechanism
      described in PKCS 1.5, 2.1 and ISO 18033-2. The RSA algorithm is a
      public cryptographic cipher based on a secret and public keys. The
      class operates in crypting mode by default and uses the public key
      to do the encryption while the secret key is used in reverse
      (decryption) mode. By default, the PKCS 1.5 type 2 padding is
      used. The ISO RSA-REM1 padding with a key derivation function
      (KDF1) is equivalent to PKCS 2.1 padding with the mask generation
      function (MGF1). The ISO RSA-REM1 padding with KDF2 is not
      described in the PKCS 2.1.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Rsa</name>
	<args>none</args>
	<p>
	  The <code>Rsa</code> constructor creates a default RSA public
	  cipher by binding a 1024 bits random key.
	</p>
      </ctor>

      <ctor>
	<name>Rsa</name>
	<args>Key</args>
	<p>
	  The <code>Rsa</code> constructor creates a RSA public cipher by
	  binding the key argument.
	</p>
      </ctor>

      <ctor>
	<name>Rsa</name>
	<args>Key Boolean</args>
	<p>
	  The <code>Rsa</code> constructor creates a RSA public cipher by
	  binding the key argument and the reverse flag. The first
	  argument is the key to bind. The second argument is the reverse
	  flag to set.
	</p>
      </ctor>

      <ctor>
	<name>Rsa</name>
	<args>Key Hasher String</args>
	<p>
	  The <code>Rsa</code> constructor creates a RSA public cipher by
	  binding the key argument and OAEP padding objects. The first
	  argument is the key to bind. The second argument is hasher
	  object to use with the OAEP padding mode. The third argument is
	  an optional label to be used by the KDF object.
	</p>
      </ctor>
    </ctors>

    <!-- constants -->
    <constants>
      <const>
	<name>PAD-PKCS-11</name>
	<p>
	  The <code>PAD-PKCS-11</code> constant indicates that the PKCS
	  1.5 type 1 block should be used to pad the message.
	</p>
      </const>

      <const>
	<name>PAD-PKCS-12</name>
	<p>
	  The <code>PAD-PKCS-12</code> constant indicates that the PKCS
	  1.5 type 3 block should be used to pad the message.
	</p>
      </const>

      <const>
	<name>PAD-OAEP-K1</name>
	<p>
	  The <code>PAD-OAEP-K1</code> constant indicates that the ISO/IEC
	  18033-2 OAEP with KDF1 should be used to pad the message.
	</p>
      </const>

      <const>
	<name>PAD-OAEP-K2</name>
	<p>
	  The <code>PAD-OAEP-K2</code> constant indicates that the ISO/IEC
	  18033-2 OAEP with KDF2 should be used to pad the message.
	</p>
      </const>
    </constants>

    <!-- methods -->
    <methods>
      <meth>
	<name>get-hasher</name>
	<retn>Hasher</retn>
	<args>none</args>
	<p>
	  The <code>get-hasher</code> method returns the hasher object
	  used by the OAEP padding mode.
	</p>
      </meth>

      <meth>
	<name>set-hasher</name>
	<retn>none</retn>
	<args>Hasher</args>
	<p>
	  The <code>set-hasher</code> method sets the hasher object used by
	  the OAEP 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>

      <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-label</name>
	<retn>String</retn>
	<args>none</args>
	<p>
	  The <code>get-padding-label</code> method returns the cipher
	  padding label.
	</p>
      </meth>

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

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

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

      <meth>
	<name>pkcs-primitive</name>
	<retn>Relatif</retn>
	<args>Integer|Relatif</args>
	<p>
	  The <code>pkcs-primitive</code> method compute a relatif value
	  from a relatif argument by either crypting or decrypting the
	  argument.
	  seed.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = signer object                                                   = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Signer</code> class is a base class that is used to
      build a message signature. The signature result is stored in a
      special signature object which is algorithm dependent.
    </p>

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

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

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the signer object with its
	  associated internal states.
	</p>
      </meth>

      <meth>
	<name>compute</name>
	<retn>Signature</retn>
	<args>Literal|Buffer|InputStream</args>
	<p>
	  The <code>compute</code> method computes the signature from a
	  string, a buffer or an input stream. The method returns a signature
	  object. When the argument is a buffer object or an input stream,
	  the characters are consumed from the object.
	</p>
      </meth>

      <meth>
	<name>derive</name>
	<retn>Signature</retn>
	<args>String</args>
	<p>
	  The <code>derive</code> method computes the signature from an
	  octet string which is converted before the signature
	  computation. The method returns a signature object.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = signature object                                                = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Signature</code> class is a container class designed to
      store a message signature. The signature object is produced by a
      signing process, implemented in the form of a digital signature
      algorithm such like RSA or DSA.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Signature</name>
	<args>none</args>
	<p>
	  The <code>Signature</code> constructor creates an empty signature.
	</p>
      </ctor>
    </ctors>

    <!-- constants -->
    <constants>
      <const>
	<name>NIL</name>
	<p>
	  The <code>NIL</code> constant indicates that the signature is a
	  null signature.
	</p>
      </const>

      <const>
	<name>DSA</name>
	<p>
	  The <code>DSA</code> constant indicates that the signature is
	  conforming to DSS.
	</p>
      </const>

      <const>
	<name>DSA-S-COMPONENT</name>
	<p>
	  The <code>DSA-S-COMPONENT</code> constant corresponds to the DSA
	  S component value.
	</p>
      </const>

      <const>
	<name>DSA-R-COMPONENT</name>
	<p>
	  The <code>DSA-R-COMPONENT</code> constant corresponds to the DSA
	  R component value.
	</p>
      </const>
    </constants>

    <!-- methods -->
    <methods>
      <meth>
	<name>reset</name>
	<retn>none</retn>
	<args>none</args>
	<p>
	  The <code>reset</code> method reset the signature object to a null
	  signature.
	</p>
      </meth>
      <meth>
	<name>format</name>
	<retn>String</retn>
	<args>Item</args>
	<p>
	  The <code>format</code> method returns a string representation
	  of the signature component. The signature component is returned
	  as an octet string based on the signature component to access.
	</p>
      </meth>

      <meth>
	<name>get-relatif-component</name>
	<retn>Relatif</retn>
	<args>Item</args>
	<p>
	  The <code>get-relatif-component</code> method returns a relatif
	  representation of a signature component.
	</p>
      </meth>
    </methods>
  </object>

  <!-- =================================================================== -->
  <!-- = dsa object                                                      = -->
  <!-- =================================================================== -->

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

    <!-- synopsis -->
    <p>
      The <code>Dsa</code> class is an original implementation of the
      Digital Signature Standard (DSS) as published in FIPS PUB 186-3.
      This class implements the Digital Signature Algorithm (DSA) with
      an approved key length of 1024, 2048 and 3072 bits with a 160, 224
      and 256 bits hash function which is part of the SHA family.
    </p>

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

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

    <!-- constructors -->
    <ctors>
      <ctor>
	<name>Dsa</name>
	<args>none</args>
	<p>
	  The <code>Dsa</code> constructor creates a signer object with a
	  default DSA key.
	</p>
      </ctor>

      <ctor>
	<name>Dsa</name>
	<args>Key</args>
	<p>
	  The <code>Dsa</code> constructor creates a signer object with a
	  DSA key as its argument.
	</p>
      </ctor>

      <ctor>
	<name>Dsa</name>
	<args>Key Relatif</args>
	<p>
	  The <code>Dsa</code> constructor creates a signer object with a
	  DSA key as its first argument and a fixed <em>k</em> argument as
	  specified by DSS.
	</p>
      </ctor>
    </ctors>
  </object>
</appendix>
