<?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-2011 - 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>

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