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

<!-- ====================================================================== -->
<!-- = appendix-iv.xml                                                    = -->
<!-- = standard security module guide - appendix iv                       = -->
<!-- ====================================================================== -->
<!-- = 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="iv">
  <title>Public ciphers</title>

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