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

<!-- ====================================================================== -->
<!-- = appendix-v.xml                                                     = -->
<!-- = standard security module guide - appendix v                        = -->
<!-- ====================================================================== -->
<!-- = 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="v">
  <title>Digital signature reference</title>

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