Sophie

Sophie

distrib > Mageia > cauldron > i586 > by-pkgid > 92a9f9a2ff17105809ab69f8e09db031 > files > 75

botan-doc-1.10.17-7.mga7.noarch.rpm


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>The Low-Level Interface &#8212; Botan</title>
    <link rel="stylesheet" href="_static/agogo.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/language_data.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Secure Memory Containers" href="secmem.html" />
    <link rel="prev" title="BigInt" href="bigint.html" /> 
  </head><body>
    <div class="header-wrapper">
      <div class="header">
        <h1>Botan</h1>
      </div>
    </div>

    <div class="content-wrapper">
      <div class="content">
        <div class="document">
            
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="the-low-level-interface">
<h1>The Low-Level Interface<a class="headerlink" href="#the-low-level-interface" title="Permalink to this headline">¶</a></h1>
<p>Botan has two different interfaces. The one documented in this section
is meant more for implementing higher-level types (see the section on
filters, earlier in this manual) than for use by applications. Using
it safely requires a solid knowledge of encryption techniques and best
practices, so unless you know, for example, what CBC mode and nonces
are, and why PKCS #1 padding is important, you should avoid this
interface in favor of something working at a higher level.</p>
<div class="section" id="basic-algorithm-abilities">
<h2>Basic Algorithm Abilities<a class="headerlink" href="#basic-algorithm-abilities" title="Permalink to this headline">¶</a></h2>
<p>There are a small handful of functions implemented by most of Botan’s
algorithm objects. Among these are:</p>
<dl class="function">
<dt id="_CPPv3N9Algorithm4nameEv">
<span id="_CPPv2N9Algorithm4nameEv"></span><span id="Algorithm::name"></span>std::string <code class="descclassname">Algorithm<code class="descclassname">::</code></code><code class="descname">name</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N9Algorithm4nameEv" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Returns a human-readable string of the name of this
algorithm. Examples of names returned are “AES-128” and
“HMAC(SHA-512)”. You can turn names back into algorithm objects using
the functions in <code class="docutils literal notranslate"><span class="pre">lookup.h</span></code>.</p>
<dl class="function">
<dt id="_CPPv3N9Algorithm5clearEv">
<span id="_CPPv2N9Algorithm5clearEv"></span><span id="Algorithm::clear"></span>void <code class="descclassname">Algorithm<code class="descclassname">::</code></code><code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N9Algorithm5clearEv" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Clear out the algorithm’s internal state. A block cipher object will
“forget” its key, a hash function will “forget” any data put into it,
etc. The object will look and behave as it did when you initially
allocated it.</p>
<dl class="function">
<dt id="_CPPv3N9Algorithm5cloneEv">
<span id="_CPPv2N9Algorithm5cloneEv"></span><span id="Algorithm::clone"></span>T *<code class="descclassname">Algorithm<code class="descclassname">::</code></code><code class="descname">clone</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N9Algorithm5cloneEv" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>This function is central to Botan’s name-based interface. The
<code class="docutils literal notranslate"><span class="pre">clone</span></code> has many different return types, such as <code class="docutils literal notranslate"><span class="pre">BlockCipher</span></code>*
and <code class="docutils literal notranslate"><span class="pre">HashFunction</span></code>*, depending on what kind of object it is called
on. Note that unlike Java’s clone, this returns a new object in a
“pristine” state; that is, operations done on the initial object
before calling <code class="docutils literal notranslate"><span class="pre">clone</span></code> do not affect the initial state of the new
clone.</p>
<p>Cloned objects can (and should) be deallocated with the C++ <code class="docutils literal notranslate"><span class="pre">delete</span></code>
operator.</p>
</div>
<div class="section" id="keys-and-ivs">
<h2>Keys and IVs<a class="headerlink" href="#keys-and-ivs" title="Permalink to this headline">¶</a></h2>
<p>Both symmetric keys and initialization values can be considered byte
(or octet) strings. These are represented by</p>
<dl class="class">
<dt id="_CPPv311OctetString">
<span id="_CPPv211OctetString"></span><span id="OctetString"></span><em class="property">class </em><code class="descname">OctetString</code><a class="headerlink" href="#_CPPv311OctetString" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Also known as <code class="docutils literal notranslate"><span class="pre">SymmetricKey</span></code> and <code class="docutils literal notranslate"><span class="pre">InitializationVector</span></code>, when
you want to express intent.</p>
<dl class="function">
<dt id="_CPPv3N11OctetString11OctetStringER21RandomNumberGenerator6size_t">
<span id="_CPPv2N11OctetString11OctetStringER21RandomNumberGenerator6size_t"></span><span id="OctetString::OctetString__RandomNumberGeneratorR.s"></span><code class="descname">OctetString</code><span class="sig-paren">(</span>RandomNumberGenerator &amp;<em>rng</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N11OctetString11OctetStringER21RandomNumberGenerator6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This constructor creates a new random key <em>length</em> bytes long
using the random number generator.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3N11OctetString11OctetStringENSt6stringE">
<span id="_CPPv2N11OctetString11OctetStringENSt6stringE"></span><span id="OctetString::OctetString__ss"></span><code class="descname">OctetString</code><span class="sig-paren">(</span>std::string <em>str</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N11OctetString11OctetStringENSt6stringE" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>The argument <em>str</em> is assumed to be a hex string; it is
converted to binary and stored. Whitespace is ignored.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3N11OctetString11OctetStringEPK4byte6size_t">
<span id="_CPPv2N11OctetString11OctetStringEPK4byte6size_t"></span><span id="OctetString::OctetString__byteCP.s"></span><code class="descname">OctetString</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>input</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N11OctetString11OctetStringEPK4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This constructor copies its input.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11OctetString9as_stringEv">
<span id="_CPPv2NK11OctetString9as_stringEv"></span><span id="OctetString::as_stringC"></span><code class="descname">as_string</code><span class="sig-paren">(</span><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11OctetString9as_stringEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns the hex representation of the key or IV</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="symmetrically-keyed-algorithms">
<h2>Symmetrically Keyed Algorithms<a class="headerlink" href="#symmetrically-keyed-algorithms" title="Permalink to this headline">¶</a></h2>
<p>Block ciphers, stream ciphers, and MACs are all keyed operations; to
be useful, they have to be set to use a particular key, which is a
randomly chosen string of bits of a specified length.  The length
required by any particular algorithm may vary, depending on both the
algorithm specification and the implementation. You can query any
botan object to find out what key length(s) it supports.</p>
<p>To make this similarity in terms of keying explicit, all algorithms of
those types are derived from the :cpp:class`SymmetricAlgorithm` base.
This type provides functions for setting the key, and querying
restrictions on the size of the key.</p>
<dl class="class">
<dt id="_CPPv318SymmetricAlgorithm">
<span id="_CPPv218SymmetricAlgorithm"></span><span id="SymmetricAlgorithm"></span><em class="property">class </em><code class="descname">SymmetricAlgorithm</code><a class="headerlink" href="#_CPPv318SymmetricAlgorithm" title="Permalink to this definition">¶</a><br /></dt>
<dd><dl class="function">
<dt id="_CPPv3N18SymmetricAlgorithm7set_keyEPK4byte6size_t">
<span id="_CPPv2N18SymmetricAlgorithm7set_keyEPK4byte6size_t"></span><span id="SymmetricAlgorithm::set_key__byteCP.s"></span>void <code class="descname">set_key</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>key</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N18SymmetricAlgorithm7set_keyEPK4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv3N18SymmetricAlgorithm7set_keyERK12SymmetricKey">
<span id="_CPPv2N18SymmetricAlgorithm7set_keyERK12SymmetricKey"></span><span id="SymmetricAlgorithm::set_key__SymmetricKeyCR"></span>void <code class="descname">set_key</code><span class="sig-paren">(</span><em class="property">const</em> SymmetricKey &amp;<em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N18SymmetricAlgorithm7set_keyERK12SymmetricKey" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This sets the key to the value specified. Most algorithms only
accept keys of certain lengths. If you attempt to call
<code class="docutils literal notranslate"><span class="pre">set_key</span></code> with a key length that is not supported, the
exception <code class="docutils literal notranslate"><span class="pre">Invalid_Key_Length</span></code> will be thrown.</p>
<p>In all cases, <code class="docutils literal notranslate"><span class="pre">set_key</span></code> must be called on an object before any
data processing (encryption, decryption, etc) is done by that
object. If this is not done, the results are undefined.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK18SymmetricAlgorithm15valid_keylengthE6size_t">
<span id="_CPPv2NK18SymmetricAlgorithm15valid_keylengthE6size_t"></span><span id="SymmetricAlgorithm::valid_keylength__sC"></span>bool <code class="descname">valid_keylength</code><span class="sig-paren">(</span>size_t <em>length</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK18SymmetricAlgorithm15valid_keylengthE6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This function returns true if and only if <em>length</em> is a valid
keylength for the algorithm.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK18SymmetricAlgorithm17minimum_keylengthEv">
<span id="_CPPv2NK18SymmetricAlgorithm17minimum_keylengthEv"></span><span id="SymmetricAlgorithm::minimum_keylengthC"></span>size_t <code class="descname">minimum_keylength</code><span class="sig-paren">(</span><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK18SymmetricAlgorithm17minimum_keylengthEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Return the smallest key length (in bytes) that is acceptible for the
algorithm.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK18SymmetricAlgorithm17maximum_keylengthEv">
<span id="_CPPv2NK18SymmetricAlgorithm17maximum_keylengthEv"></span><span id="SymmetricAlgorithm::maximum_keylengthC"></span>size_t <code class="descname">maximum_keylength</code><span class="sig-paren">(</span><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK18SymmetricAlgorithm17maximum_keylengthEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Return the largest key length (in bytes) that is acceptible for the
algorithm</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="block-ciphers">
<h2>Block Ciphers<a class="headerlink" href="#block-ciphers" title="Permalink to this headline">¶</a></h2>
<p>All block ciphers classes in botan are subclasses of</p>
<dl class="class">
<dt id="_CPPv311BlockCipher">
<span id="_CPPv211BlockCipher"></span><span id="BlockCipher"></span><em class="property">class </em><code class="descname">BlockCipher</code><a class="headerlink" href="#_CPPv311BlockCipher" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Which subclasses the <a class="reference internal" href="#_CPPv318SymmetricAlgorithm" title="SymmetricAlgorithm"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">SymmetricAlgorithm</span></code></a> interface.</p>
<dl class="function">
<dt id="_CPPv3NK11BlockCipher10block_sizeEv">
<span id="_CPPv2NK11BlockCipher10block_sizeEv"></span><span id="BlockCipher::block_sizeC"></span>size_t <code class="descname">block_size</code><span class="sig-paren">(</span><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher10block_sizeEv" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns the block size of the cipher in bytes</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher9encrypt_nEPK4byteP4byte6size_t">
<span id="_CPPv2NK11BlockCipher9encrypt_nEPK4byteP4byte6size_t"></span><span id="BlockCipher::encrypt_n__byteCP.byteP.sC"></span>void <code class="descname">encrypt_n</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>in</em>, byte *<em>out</em>, size_t <em>n</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher9encrypt_nEPK4byteP4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Encrypt <em>n</em> blocks of data, taking the input from the array <em>in</em>
and placing the ciphertext into <em>out</em>. The two pointers may be
identical, but should not overlap ranges.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher7encryptEPK4byteP4byte">
<span id="_CPPv2NK11BlockCipher7encryptEPK4byteP4byte"></span><span id="BlockCipher::encrypt__byteCP.bytePC"></span>void <code class="descname">encrypt</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>in</em>, byte *<em>out</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher7encryptEPK4byteP4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Encrypt a single block, taking the input from <em>in</em> and placing
it in <em>out</em>. Acts like <a class="reference internal" href="#_CPPv3NK11BlockCipher9encrypt_nEPK4byteP4byte6size_t" title="BlockCipher::encrypt_n"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">encrypt_n</span></code></a>(in, out, 1).</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher7encryptEP4byte">
<span id="_CPPv2NK11BlockCipher7encryptEP4byte"></span><span id="BlockCipher::encrypt__bytePC"></span>void <code class="descname">encrypt</code><span class="sig-paren">(</span>byte *<em>block</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher7encryptEP4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Identical to <a class="reference internal" href="#_CPPv3NK11BlockCipher7encryptEPK4byteP4byte" title="BlockCipher::encrypt"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">encrypt</span></code></a>(block, block)</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher9decrypt_nEPK4byte4byte6size_t">
<span id="_CPPv2NK11BlockCipher9decrypt_nEPK4byte4byte6size_t"></span><span id="BlockCipher::decrypt_n__byteCP.byte.sC"></span>void <code class="descname">decrypt_n</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>in</em>, byte <em>out</em>, size_t <em>n</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher9decrypt_nEPK4byte4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Decrypt <em>n</em> blocks of data, taking the input from <em>in</em> and
placing the plaintext in <em>out</em>. The two pointers may be
identical, but should not overlap ranges.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher7decryptEPK4byteP4byte">
<span id="_CPPv2NK11BlockCipher7decryptEPK4byteP4byte"></span><span id="BlockCipher::decrypt__byteCP.bytePC"></span>void <code class="descname">decrypt</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>in</em>, byte *<em>out</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher7decryptEPK4byteP4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Decrypt a single block, taking the input from <em>in</em> and placing it
in <em>out</em>. Acts like <a class="reference internal" href="#_CPPv3NK11BlockCipher9decrypt_nEPK4byte4byte6size_t" title="BlockCipher::decrypt_n"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">decrypt_n</span></code></a>(in, out, 1).</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3NK11BlockCipher7decryptEP4byte">
<span id="_CPPv2NK11BlockCipher7decryptEP4byte"></span><span id="BlockCipher::decrypt__bytePC"></span>void <code class="descname">decrypt</code><span class="sig-paren">(</span>byte *<em>block</em><span class="sig-paren">)</span> <em class="property">const</em><a class="headerlink" href="#_CPPv3NK11BlockCipher7decryptEP4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Identical to <a class="reference internal" href="#_CPPv3NK11BlockCipher7decryptEPK4byteP4byte" title="BlockCipher::decrypt"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">decrypt</span></code></a>(block, block)</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="stream-ciphers">
<h2>Stream Ciphers<a class="headerlink" href="#stream-ciphers" title="Permalink to this headline">¶</a></h2>
<p>Stream ciphers are somewhat different from block ciphers, in that
encrypting data results in changing the internal state of the
cipher. Also, you may encrypt any length of data in one go (in byte
amounts).</p>
<dl class="function">
<dt id="_CPPv3N12StreamCipher7encryptEPK4byteP4byte6size_t">
<span id="_CPPv2N12StreamCipher7encryptEPK4byteP4byte6size_t"></span><span id="StreamCipher::encrypt__byteCP.byteP.s"></span>void <code class="descclassname">StreamCipher<code class="descclassname">::</code></code><code class="descname">encrypt</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>in</em>, byte *<em>out</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N12StreamCipher7encryptEPK4byteP4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv3N12StreamCipher7encryptEP4byte6size_t">
<span id="_CPPv2N12StreamCipher7encryptEP4byte6size_t"></span><span id="StreamCipher::encrypt__byteP.s"></span>void <code class="descclassname">StreamCipher<code class="descclassname">::</code></code><code class="descname">encrypt</code><span class="sig-paren">(</span>byte *<em>data</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N12StreamCipher7encryptEP4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Stream ciphers implement the <code class="docutils literal notranslate"><span class="pre">SymmetricAlgorithm</span></code> interface.</p>
</div>
<div class="section" id="hash-functions-message-authentication-codes">
<h2>Hash Functions / Message Authentication Codes<a class="headerlink" href="#hash-functions-message-authentication-codes" title="Permalink to this headline">¶</a></h2>
<p>Hash functions take their input without producing any output, only
producing anything when all input has already taken place. MACs are
very similar, but are additionally keyed. Both of these are derived
from the base class <code class="docutils literal notranslate"><span class="pre">BufferedComputation</span></code>, which has the following
functions.</p>
<dl class="function">
<dt id="_CPPv3N19BufferedComputation13output_lengthEv">
<span id="_CPPv2N19BufferedComputation13output_lengthEv"></span><span id="BufferedComputation::output_length"></span>size_t <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">output_length</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation13output_lengthEv" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Return the size of the output of this function.</p>
<dl class="function">
<dt id="_CPPv3N19BufferedComputation6updateEPK4byte6size_t">
<span id="_CPPv2N19BufferedComputation6updateEPK4byte6size_t"></span><span id="BufferedComputation::update__byteCP.s"></span>void <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">update</code><span class="sig-paren">(</span><em class="property">const</em> byte *<em>input</em>, size_t <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation6updateEPK4byte6size_t" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv3N19BufferedComputation6updateE4byte">
<span id="_CPPv2N19BufferedComputation6updateE4byte"></span><span id="BufferedComputation::update__byte"></span>void <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">update</code><span class="sig-paren">(</span>byte <em>input</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation6updateE4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv3N19BufferedComputation6updateERKNSt6stringE">
<span id="_CPPv2N19BufferedComputation6updateERKNSt6stringE"></span><span id="BufferedComputation::update__ssCR"></span>void <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">update</code><span class="sig-paren">(</span><em class="property">const</em> std::string &amp;<em>input</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation6updateERKNSt6stringE" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Updates the hash/mac calculation with <em>input</em>.</p>
<dl class="function">
<dt id="_CPPv3N19BufferedComputation5finalEP4byte">
<span id="_CPPv2N19BufferedComputation5finalEP4byte"></span><span id="BufferedComputation::final__byteP"></span>void <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">final</code><span class="sig-paren">(</span>byte *<em>out</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation5finalEP4byte" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv3N19BufferedComputation5finalEv">
<span id="_CPPv2N19BufferedComputation5finalEv"></span><span id="BufferedComputation::final"></span>SecureVector&lt;byte&gt; <code class="descclassname">BufferedComputation<code class="descclassname">::</code></code><code class="descname">final</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N19BufferedComputation5finalEv" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<p>Complete the hash/MAC calculation and place the result into <code class="docutils literal notranslate"><span class="pre">out</span></code>.
For the argument taking an array, exactly <code class="docutils literal notranslate"><span class="pre">output_length</span></code> bytes will
be written. After you call <code class="docutils literal notranslate"><span class="pre">final</span></code>, the hash function is reset to
its initial state, so it may be reused immediately.</p>
<p>The second method of using final is to call it with no arguments at
all, as shown in the second prototype. It will return the hash/mac
value in a memory buffer.</p>
<p>There is also a pair of functions called <code class="docutils literal notranslate"><span class="pre">process</span></code>. They are a
combination of a single <code class="docutils literal notranslate"><span class="pre">update</span></code>, and <code class="docutils literal notranslate"><span class="pre">final</span></code>. Both versions
return the final value, rather than placing it an array. Calling
<code class="docutils literal notranslate"><span class="pre">process</span></code> with a single byte value isn’t available, mostly because
it would rarely be useful.</p>
<p>A MAC can be viewed (in most cases) as a keyed hash function, so
classes that are derived from <code class="docutils literal notranslate"><span class="pre">MessageAuthenticationCode</span></code> have
<code class="docutils literal notranslate"><span class="pre">update</span></code> and <code class="docutils literal notranslate"><span class="pre">final</span></code> classes just like a <code class="docutils literal notranslate"><span class="pre">HashFunction</span></code> (and
like a <code class="docutils literal notranslate"><span class="pre">HashFunction</span></code>, after <code class="docutils literal notranslate"><span class="pre">final</span></code> is called, it can be used to
make a new MAC right away; the key is kept around).</p>
<p>A MAC has the <code class="docutils literal notranslate"><span class="pre">SymmetricAlgorithm</span></code> interface in addition to the
<code class="docutils literal notranslate"><span class="pre">BufferedComputation</span></code> interface.</p>
<div class="section" id="checksums">
<h3>Checksums<a class="headerlink" href="#checksums" title="Permalink to this headline">¶</a></h3>
<p>Checksums are very similar to hash functions, and in fact share the
same interface. But there are some significant differences, the major
ones being that the output size is very small (usually in the range of
2 to 4 bytes), and is not cryptographically secure. But for their
intended purpose (error checking), they perform very well. Some
examples of checksums included in Botan are the Adler32 and CRC32
checksums.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
        </div>
        <div class="sidebar">
          <h3>Table of Contents</h3>
          <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Welcome</a></li>
<li class="toctree-l1"><a class="reference internal" href="reading.html">Recommended Reading</a></li>
<li class="toctree-l1"><a class="reference internal" href="building.html">Building The Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="firststep.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="filters.html">Information Flow: Pipes and Filters</a></li>
<li class="toctree-l1"><a class="reference internal" href="pubkey.html">Public Key Cryptography</a></li>
<li class="toctree-l1"><a class="reference internal" href="x509.html">Certificate Handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="ssl.html">SSL and TLS</a></li>
<li class="toctree-l1"><a class="reference internal" href="bigint.html">BigInt</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">The Low-Level Interface</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#basic-algorithm-abilities">Basic Algorithm Abilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="#keys-and-ivs">Keys and IVs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#symmetrically-keyed-algorithms">Symmetrically Keyed Algorithms</a></li>
<li class="toctree-l2"><a class="reference internal" href="#block-ciphers">Block Ciphers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#stream-ciphers">Stream Ciphers</a></li>
<li class="toctree-l2"><a class="reference internal" href="#hash-functions-message-authentication-codes">Hash Functions / Message Authentication Codes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="secmem.html">Secure Memory Containers</a></li>
<li class="toctree-l1"><a class="reference internal" href="kdf.html">Key Derivation Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="pbkdf.html">PBKDF Algorithms</a></li>
<li class="toctree-l1"><a class="reference internal" href="passhash.html">Password Hashing</a></li>
<li class="toctree-l1"><a class="reference internal" href="rng.html">Random Number Generators</a></li>
<li class="toctree-l1"><a class="reference internal" href="fpe.html">Format Preserving Encryption</a></li>
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Binding</a></li>
</ul>

          <div role="search">
            <h3 style="margin-top: 1.5em;">Search</h3>
            <form class="search" action="search.html" method="get">
                <input type="text" name="q" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
            </form>
          </div>
        </div>
        <div class="clearer"></div>
      </div>
    </div>

    <div class="footer-wrapper">
      <div class="footer">
        <div class="left">
          <div role="navigation" aria-label="related navigaton">
            <a href="bigint.html" title="BigInt"
              accesskey="P">previous</a> |
            <a href="secmem.html" title="Secure Memory Containers"
              accesskey="N">next</a> |
            <a href="genindex.html" title="General Index"
              accesskey="I">index</a>
          </div>
          <div role="note" aria-label="source link">
              <br/>
              <a href="_sources/lowlevel.txt"
                rel="nofollow">Show Source</a>
          </div>
        </div>

        <div class="right">
          
    <div class="footer" role="contentinfo">
        &#169; Copyright 2000-2011, Jack Lloyd.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.3.
    </div>
        </div>
        <div class="clearer"></div>
      </div>
    </div>

  </body>
</html>