Sophie

Sophie

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

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>BigInt &#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="The Low-Level Interface" href="lowlevel.html" />
    <link rel="prev" title="SSL and TLS" href="ssl.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="bigint">
<h1>BigInt<a class="headerlink" href="#bigint" title="Permalink to this headline">¶</a></h1>
<p><code class="docutils literal notranslate"><span class="pre">BigInt</span></code> is Botan’s implementation of a multiple-precision
integer. Thanks to C++’s operator overloading features, using
<code class="docutils literal notranslate"><span class="pre">BigInt</span></code> is often quite similar to using a native integer type. The
number of functions related to <code class="docutils literal notranslate"><span class="pre">BigInt</span></code> is quite large. You can find
most of them in <code class="docutils literal notranslate"><span class="pre">botan/bigint.h</span></code> and <code class="docutils literal notranslate"><span class="pre">botan/numthry.h</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you can, always use expressions of the form <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">+=</span> <span class="pre">b</span></code> over <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">=</span>
<span class="pre">a</span> <span class="pre">+</span> <span class="pre">b</span></code>. The difference can be <em>very</em> substantial, because the first
form prevents at least one needless memory allocation, and possibly
as many as three. This will be less of an issue once the library
adopts use of C++0x’s rvalue references.</p>
</div>
<div class="section" id="encoding-functions">
<h2>Encoding Functions<a class="headerlink" href="#encoding-functions" title="Permalink to this headline">¶</a></h2>
<p>These transform the normal representation of a <code class="docutils literal notranslate"><span class="pre">BigInt</span></code> into some
other form, such as a decimal string:</p>
<dl class="function">
<dt id="_CPPv3N6BigInt6encodeERK6BigInt8Encoding">
<span id="_CPPv2N6BigInt6encodeERK6BigInt8Encoding"></span><span id="BigInt::encode__BigIntCR.Encoding"></span>SecureVector&lt;byte&gt; <code class="descclassname">BigInt<code class="descclassname">::</code></code><code class="descname">encode</code><span class="sig-paren">(</span><em class="property">const</em> BigInt &amp;<em>n</em>, Encoding <em>enc</em> = Binary<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N6BigInt6encodeERK6BigInt8Encoding" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>This function encodes the BigInt n into a memory
vector. <code class="docutils literal notranslate"><span class="pre">Encoding</span></code> is an enum that has values <code class="docutils literal notranslate"><span class="pre">Binary</span></code>,
<code class="docutils literal notranslate"><span class="pre">Octal</span></code>, <code class="docutils literal notranslate"><span class="pre">Decimal</span></code>, and <code class="docutils literal notranslate"><span class="pre">Hexadecimal</span></code>.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv3N6BigInt6decodeERK12MemoryRegionI4byteE8Encoding">
<span id="_CPPv2N6BigInt6decodeERK12MemoryRegionI4byteE8Encoding"></span><span id="BigInt::decode__MemoryRegion:byte:CR.Encoding"></span>BigInt <code class="descclassname">BigInt<code class="descclassname">::</code></code><code class="descname">decode</code><span class="sig-paren">(</span><em class="property">const</em> MemoryRegion&lt;byte&gt; &amp;<em>vec</em>, Encoding <em>enc</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv3N6BigInt6decodeERK12MemoryRegionI4byteE8Encoding" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Decode the integer from <code class="docutils literal notranslate"><span class="pre">vec</span></code> using the encoding specified.</p>
</dd></dl>

<p>These functions are static member functions, so they would be called
like this:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">BigInt</span> <span class="n">n1</span> <span class="o">=</span> <span class="p">...;</span> <span class="c1">// some number</span>
<span class="n">SecureVector</span><span class="o">&lt;</span><span class="n">byte</span><span class="o">&gt;</span> <span class="n">n1_encoded</span> <span class="o">=</span> <span class="n">BigInt</span><span class="o">::</span><span class="n">encode</span><span class="p">(</span><span class="n">n1</span><span class="p">);</span>
<span class="n">BigInt</span> <span class="n">n2</span> <span class="o">=</span> <span class="n">BigInt</span><span class="o">::</span><span class="n">decode</span><span class="p">(</span><span class="n">n1_encoded</span><span class="p">);</span>
<span class="n">assert</span><span class="p">(</span><span class="n">n1</span> <span class="o">==</span> <span class="n">n2</span><span class="p">);</span>
</pre></div>
</div>
<p>There are also C++-style I/O operators defined for use with
<code class="docutils literal notranslate"><span class="pre">BigInt</span></code>. The input operator understands negative numbers,
hexadecimal numbers (marked with a leading “0x”), and octal numbers
(marked with a leading ‘0’). The ‘-‘ must come before the “0x” or ‘0’
marker. The output operator will never adorn the output; for example,
when printing a hexadecimal number, there will not be a leading “0x”
(though a leading ‘-‘ will be printed if the number is negative). If
you want such things, you’ll have to do them yourself.</p>
<p><code class="docutils literal notranslate"><span class="pre">BigInt</span></code> has constructors that can create a <code class="docutils literal notranslate"><span class="pre">BigInt</span></code> from an
unsigned integer or a string. You can also decode an array (a <code class="docutils literal notranslate"><span class="pre">byte</span></code>
pointer plus a length) into a <code class="docutils literal notranslate"><span class="pre">BigInt</span></code> using a constructor.</p>
</div>
<div class="section" id="number-theory">
<h2>Number Theory<a class="headerlink" href="#number-theory" title="Permalink to this headline">¶</a></h2>
<p>Number theoretic functions available include:</p>
<dl class="function">
<dt id="_CPPv33gcd6BigInt6BigInt">
<span id="_CPPv23gcd6BigInt6BigInt"></span><span id="gcd__BigInt.BigInt"></span>BigInt <code class="descname">gcd</code><span class="sig-paren">(</span>BigInt <em>x</em>, BigInt <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv33gcd6BigInt6BigInt" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns the greatest common divisor of x and y</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv33lcm6BigInt6BigInt">
<span id="_CPPv23lcm6BigInt6BigInt"></span><span id="lcm__BigInt.BigInt"></span>BigInt <code class="descname">lcm</code><span class="sig-paren">(</span>BigInt <em>x</em>, BigInt <em>y</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv33lcm6BigInt6BigInt" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns an integer z which is the smallest integer such that z % x
== 0 and z % y == 0</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv311inverse_mod6BigInt6BigInt">
<span id="_CPPv211inverse_mod6BigInt6BigInt"></span><span id="inverse_mod__BigInt.BigInt"></span>BigInt <code class="descname">inverse_mod</code><span class="sig-paren">(</span>BigInt <em>x</em>, BigInt <em>m</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv311inverse_mod6BigInt6BigInt" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns the modular inverse of x modulo m, that is, an integer
y such that (x*y) % m == 1. If no such y exists, returns zero.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv39power_mod6BigInt6BigInt6BigInt">
<span id="_CPPv29power_mod6BigInt6BigInt6BigInt"></span><span id="power_mod__BigInt.BigInt.BigInt"></span>BigInt <code class="descname">power_mod</code><span class="sig-paren">(</span>BigInt <em>b</em>, BigInt <em>x</em>, BigInt <em>m</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv39power_mod6BigInt6BigInt6BigInt" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns b to the xth power modulo m. If you are doing many
exponentiations with a single fixed modulus, it is faster to use a
<code class="docutils literal notranslate"><span class="pre">Power_Mod</span></code> implementation.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv36ressol6BigInt6BigInt">
<span id="_CPPv26ressol6BigInt6BigInt"></span><span id="ressol__BigInt.BigInt"></span>BigInt <code class="descname">ressol</code><span class="sig-paren">(</span>BigInt <em>x</em>, BigInt <em>p</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv36ressol6BigInt6BigInt" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Returns the square root modulo a prime, that is, returns a number y
such that (y*y) % p == x. Returns -1 if no such integer exists.</p>
</dd></dl>

<dl class="function">
<dt id="_CPPv317quick_check_prime6BigIntR21RandomNumberGenerator">
<span id="_CPPv217quick_check_prime6BigIntR21RandomNumberGenerator"></span><span id="quick_check_prime__BigInt.RandomNumberGeneratorR"></span>bool <code class="descname">quick_check_prime</code><span class="sig-paren">(</span>BigInt <em>n</em>, RandomNumberGenerator &amp;<em>rng</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv317quick_check_prime6BigIntR21RandomNumberGenerator" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv311check_prime6BigIntR21RandomNumberGenerator">
<span id="_CPPv211check_prime6BigIntR21RandomNumberGenerator"></span><span id="check_prime__BigInt.RandomNumberGeneratorR"></span>bool <code class="descname">check_prime</code><span class="sig-paren">(</span>BigInt <em>n</em>, RandomNumberGenerator &amp;<em>rng</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv311check_prime6BigIntR21RandomNumberGenerator" title="Permalink to this definition">¶</a><br /></dt>
<dd></dd></dl>

<dl class="function">
<dt id="_CPPv312verify_prime6BigIntR21RandomNumberGenerator">
<span id="_CPPv212verify_prime6BigIntR21RandomNumberGenerator"></span><span id="verify_prime__BigInt.RandomNumberGeneratorR"></span>bool <code class="descname">verify_prime</code><span class="sig-paren">(</span>BigInt <em>n</em>, RandomNumberGenerator &amp;<em>rng</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv312verify_prime6BigIntR21RandomNumberGenerator" title="Permalink to this definition">¶</a><br /></dt>
<dd><p>Three variations on primality testing. All take an integer to test along with
a random number generator, and return true if the integer seems like it might
be prime; there is a chance that this function will return true even with
a composite number. The probability decreases with the amount of work performed,
so it is much less likely that <code class="docutils literal notranslate"><span class="pre">verify_prime</span></code> will return a false positive
than <code class="docutils literal notranslate"><span class="pre">check_prime</span></code> will.</p>
</dd></dl>

</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 current"><a class="current reference internal" href="#">BigInt</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#encoding-functions">Encoding Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="#number-theory">Number Theory</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="lowlevel.html">The Low-Level Interface</a></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="ssl.html" title="SSL and TLS"
              accesskey="P">previous</a> |
            <a href="lowlevel.html" title="The Low-Level Interface"
              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/bigint.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>