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

<!-- ====================================================================== -->
<!-- = appendix-i.xml                                                     = -->
<!-- = standard security module guide - appendix i                        = -->
<!-- ====================================================================== -->
<!-- = 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-2009 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="sec" number="i">
  <title>Hashing and key 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>

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