<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
<!--
  Hamigaki.Checksum Library Document Source

  Copyright Takeshi Mouri 2008.
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt)

  See http://hamigaki.sourceforge.jp/libs/checksum for library home page.
-->
<header name="hamigaki/checksum/sha2.hpp">
  <namespace name="hamigaki">
    <namespace name="checksum">
      <class name="sha2_basic">
        <template>
          <template-nontype-parameter name="Size">
            <type>std::size_t</type>
          </template-nontype-parameter>
        </template>

        <purpose>
          <simpara>RFC 4634で規定されるSHA-2ハッシュアルゴリズムに従い、チェックサムを計算する。</simpara>
        </purpose>

        <description>
          <para><code>sha2_basic&lt;Size&gt;</code>は<code>Size</code>ビットのSHA-2ハッシュ値を計算するクラスである。テンプレート引数<code>Size</code>は224、256、384、512のいずれかでなければならない。</para>
        </description>

        <typedef name="value_type">
          <type>boost::array&lt;boost::uint8_t,Size/8&gt;</type>
        </typedef>

        <constructor/>

        <method-group name="modifiers">
          <method name="reset">
            <type>void</type>
            <effects>SHA-2コンテキストを初期状態に戻す。</effects>
          </method>

          <method name="process_bit">
            <type>void</type>
            <parameter name="bit">
              <paramtype>bool</paramtype>
            </parameter>
            <effects><code>bit</code>で示される1ビットでSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_bits">
            <type>void</type>
            <parameter name="bits">
              <paramtype>unsigned char</paramtype>
            </parameter>
            <parameter name="bit_count">
              <paramtype>std::size_t</paramtype>
            </parameter>
            <effects>符号なし整数<code>bits</code>の下位<code>bit_count</code>ビットを上位ビットから順に使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_byte">
            <type>void</type>
            <parameter name="byte">
              <paramtype>unsigned char</paramtype>
            </parameter>
            <effects>符号なし整数<code>byte</code>を上位ビットから順に使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_block">
            <type>void</type>
            <parameter name="bytes_begin">
              <paramtype>const void*</paramtype>
            </parameter>
            <parameter name="bytes_end">
              <paramtype>const void*</paramtype>
            </parameter>
            <effects><code>[bytes_begin, bytes_end)</code>の範囲を使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_block">
            <type>void</type>
            <parameter name="buffer">
              <paramtype>const void*</paramtype>
            </parameter>
            <parameter name="byte_count">
              <paramtype>std::size_t</paramtype>
            </parameter>
            <effects><code>[buffer, static_cast&lt;const char*&gt;(buffer)+byte_count)</code>の範囲を使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="operator()">
            <type>void</type>
            <parameter name="byte">
              <paramtype>unsigned char</paramtype>
            </parameter>
            <effects><programlisting><![CDATA[process_byte(byte);]]></programlisting></effects>
          </method>
        </method-group>

        <method-group name="queries">
          <method name="checksum" cv="const">
            <type>value_type</type>
            <returns><simpara>SHA-2チェックサム</simpara></returns>
          </method>

          <method name="operator()" cv="const">
            <type>value_type</type>
            <effects><programlisting><![CDATA[return checksum();]]></programlisting></effects>
          </method>
        </method-group>
      </class>

      <class name="sha2_optimal">
        <template>
          <template-nontype-parameter name="Size">
            <type>std::size_t</type>
          </template-nontype-parameter>
        </template>

        <purpose>
          <simpara>RFC 4634で規定されるSHA-2ハッシュアルゴリズムに従い、チェックサムを計算する。</simpara>
        </purpose>

        <description>
          <para><code>sha2_optimal</code>は<classname>sha2_basic</classname>とほぼ同じ機能を提供するが、以下の点が異なる。</para>
          <itemizedlist>
            <listitem><simpara>ビット単位の操作は提供されない。コードはバイト単位の処理に最適化されている。</simpara></listitem>
            <listitem><simpara><code><methodname>checksum</methodname>()</code>がコンテキストを更新する。</simpara></listitem>
          </itemizedlist>
        </description>

        <typedef name="value_type">
          <type>boost::array&lt;boost::uint8_t,Size/8&gt;</type>
        </typedef>

        <constructor/>

        <method-group name="modifiers">
          <method name="reset">
            <type>void</type>
            <effects>SHA-2コンテキストを初期状態に戻す。</effects>
          </method>

          <method name="process_byte">
            <type>void</type>
            <parameter name="byte">
              <paramtype>unsigned char</paramtype>
            </parameter>
            <effects>符号なし整数<code>byte</code>を上位ビットから順に使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_block">
            <type>void</type>
            <parameter name="bytes_begin">
              <paramtype>const void*</paramtype>
            </parameter>
            <parameter name="bytes_end">
              <paramtype>const void*</paramtype>
            </parameter>
            <effects><code>[bytes_begin, bytes_end)</code>の範囲を使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="process_block">
            <type>void</type>
            <parameter name="buffer">
              <paramtype>const void*</paramtype>
            </parameter>
            <parameter name="byte_count">
              <paramtype>std::size_t</paramtype>
            </parameter>
            <effects><code>[buffer, static_cast&lt;const char*&gt;(buffer)+byte_count)</code>の範囲を使用してSHA-2コンテキストを更新する。</effects>
          </method>

          <method name="operator()">
            <type>void</type>
            <parameter name="byte">
              <paramtype>unsigned char</paramtype>
            </parameter>
            <effects><programlisting><![CDATA[process_byte(byte);]]></programlisting></effects>
          </method>
        </method-group>

        <method-group name="queries">
          <method name="checksum">
            <type>value_type</type>
            <returns><simpara>SHA-2チェックサム</simpara></returns>
          </method>

          <method name="operator()">
            <type>value_type</type>
            <effects><programlisting><![CDATA[return checksum();]]></programlisting></effects>
          </method>
        </method-group>
      </class>

      <typedef name="sha224">
         <type><classname>sha2_optimal</classname>&lt;224&gt;</type>
      </typedef>

      <typedef name="sha256">
         <type><classname>sha2_optimal</classname>&lt;256&gt;</type>
      </typedef>

      <typedef name="sha384">
         <type><classname>sha2_optimal</classname>&lt;384&gt;</type>
      </typedef>

      <typedef name="sha512">
         <type><classname>sha2_optimal</classname>&lt;512&gt;</type>
      </typedef>

    </namespace>
  </namespace>
</header>
