taigrr/arduinolibs
1
0
Fork 0
mirror of https://github.com/taigrr/arduinolibs synced 2025-01-18 04:33:12 -08:00
Code Issues Projects Releases Wiki Activity
arduinolibs/classRingOscillatorNoiseSource.html
Rhys Weatherley 6fadd58f39 Update docs
2018-04-27 12:01:49 +10:00

261 lines
20 KiB
HTML
Raw Permalink Blame History

<!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="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>Arduino Cryptography Library: RingOscillatorNoiseSource Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Arduino Cryptography Library
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main&#160;Page</span></a></li>
<li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Class&#160;List</span></a></li>
<li><a href="classes.html"><span>Class&#160;Index</span></a></li>
<li><a href="hierarchy.html"><span>Class&#160;Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class&#160;Members</span></a></li>
</ul>
</div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Pages</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="classRingOscillatorNoiseSource-members.html">List of all members</a> </div>
<div class="headertitle">
<div class="title">RingOscillatorNoiseSource Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>Processes the signal from a ring oscillator based noise source.
<a href="classRingOscillatorNoiseSource.html#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="RingOscillatorNoiseSource_8h_source.html">RingOscillatorNoiseSource.h</a>&gt;</code></p>
<div class="dynheader">
Inheritance diagram for RingOscillatorNoiseSource:</div>
<div class="dyncontent">
<div class="center">
<img src="classRingOscillatorNoiseSource.png" usemap="#RingOscillatorNoiseSource_map" alt=""/>
<map id="RingOscillatorNoiseSource_map" name="RingOscillatorNoiseSource_map">
<area href="classNoiseSource.html" title="Abstract base class for random noise sources. " alt="NoiseSource" shape="rect" coords="0,0,164,24"/>
</map>
</div></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:ade7f7ed390e23722347b3c207912b3f9"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classRingOscillatorNoiseSource.html#ade7f7ed390e23722347b3c207912b3f9">calibrating</a> () const </td></tr>
<tr class="memdesc:ade7f7ed390e23722347b3c207912b3f9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Determine if the noise source is still calibrating itself. <a href="#ade7f7ed390e23722347b3c207912b3f9">More...</a><br/></td></tr>
<tr class="separator:ade7f7ed390e23722347b3c207912b3f9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ad71698b5c92b41eef2f1322999b3eff9"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classRingOscillatorNoiseSource.html#ad71698b5c92b41eef2f1322999b3eff9">stir</a> ()</td></tr>
<tr class="memdesc:ad71698b5c92b41eef2f1322999b3eff9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Stirs entropy from this noise source into the global random number pool. <a href="#ad71698b5c92b41eef2f1322999b3eff9">More...</a><br/></td></tr>
<tr class="separator:ad71698b5c92b41eef2f1322999b3eff9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="inherit_header pub_methods_classNoiseSource"><td colspan="2" onclick="javascript:toggleInherit('pub_methods_classNoiseSource')"><img src="closed.png" alt="-"/>&#160;Public Member Functions inherited from <a class="el" href="classNoiseSource.html">NoiseSource</a></td></tr>
<tr class="memitem:a601479b7d8cc215f97f2f8a18d3ef4c2 inherit pub_methods_classNoiseSource"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a601479b7d8cc215f97f2f8a18d3ef4c2"></a>
&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classNoiseSource.html#a601479b7d8cc215f97f2f8a18d3ef4c2">NoiseSource</a> ()</td></tr>
<tr class="memdesc:a601479b7d8cc215f97f2f8a18d3ef4c2 inherit pub_methods_classNoiseSource"><td class="mdescLeft">&#160;</td><td class="mdescRight">Constructs a new random noise source. <br/></td></tr>
<tr class="separator:a601479b7d8cc215f97f2f8a18d3ef4c2 inherit pub_methods_classNoiseSource"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a4eca1e894a5d719fb9bf4df34a791cdb inherit pub_methods_classNoiseSource"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a4eca1e894a5d719fb9bf4df34a791cdb"></a>
virtual&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classNoiseSource.html#a4eca1e894a5d719fb9bf4df34a791cdb">~NoiseSource</a> ()</td></tr>
<tr class="memdesc:a4eca1e894a5d719fb9bf4df34a791cdb inherit pub_methods_classNoiseSource"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destroys this random noise source. <br/></td></tr>
<tr class="separator:a4eca1e894a5d719fb9bf4df34a791cdb inherit pub_methods_classNoiseSource"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a48d0efabd71ff6e557a0898be79c49ba inherit pub_methods_classNoiseSource"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classNoiseSource.html#a48d0efabd71ff6e557a0898be79c49ba">added</a> ()</td></tr>
<tr class="memdesc:a48d0efabd71ff6e557a0898be79c49ba inherit pub_methods_classNoiseSource"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called when the noise source is added to RNG with <a class="el" href="classRNGClass.html#aacf23b192b0e4cc8726d9abe05f5a9db">RNG.addNoiseSource()</a>. <a href="#a48d0efabd71ff6e557a0898be79c49ba">More...</a><br/></td></tr>
<tr class="separator:a48d0efabd71ff6e557a0898be79c49ba inherit pub_methods_classNoiseSource"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="inherited"></a>
Additional Inherited Members</h2></td></tr>
<tr class="inherit_header pro_methods_classNoiseSource"><td colspan="2" onclick="javascript:toggleInherit('pro_methods_classNoiseSource')"><img src="closed.png" alt="-"/>&#160;Protected Member Functions inherited from <a class="el" href="classNoiseSource.html">NoiseSource</a></td></tr>
<tr class="memitem:a1af7449a5ae4a8acd34ac218c9eec6c1 inherit pro_methods_classNoiseSource"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classNoiseSource.html#a1af7449a5ae4a8acd34ac218c9eec6c1">output</a> (const uint8_t *data, size_t len, unsigned int credit)</td></tr>
<tr class="memdesc:a1af7449a5ae4a8acd34ac218c9eec6c1 inherit pro_methods_classNoiseSource"><td class="mdescLeft">&#160;</td><td class="mdescRight">Called from subclasses to output noise to the global random number pool. <a href="#a1af7449a5ae4a8acd34ac218c9eec6c1">More...</a><br/></td></tr>
<tr class="separator:a1af7449a5ae4a8acd34ac218c9eec6c1 inherit pro_methods_classNoiseSource"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Processes the signal from a ring oscillator based noise source. </p>
<p>This class processes input from a ring oscillator noise source, such as that described <a class="el" href="crypto_rng_ring.html">here</a>.</p>
<dl class="section note"><dt>Note</dt><dd>The output from a ring oscillator is not generally as good as a "true" noise source. The oscillation can easily settle into regular patterns or sync up with other clock sources on the board. It is even possible to "hack" a ring oscillator by injecting chosen frequencies on the power supply rails to force the oscillation into a predictable waveform (see <a href="http://www.cl.cam.ac.uk/~atm26/papers/markettos-ches2009-inject-trng.pdf">this paper</a> for an example). It is very important that the output of this class be whitened with <a class="el" href="classRNGClass.html">RNG</a> before it is used for cryptography and that the device is isolated from attacker-controlled sources of power. Unless you have a very good reason to use a ring oscillator, <a class="el" href="classTransistorNoiseSource.html" title="Processes the signal from a transistor-based noise source. ">TransistorNoiseSource</a> is usually a better option.</dd></dl>
<p>The noise is read from an input capture pin on the Arduino and stirred into the random number pool on a regular basis. The following pins are used on different Arduino variants:</p>
<table class="doxtable">
<tr>
<td>Variant</td><td>Arduino Pin / AVR Pin</td><td>Timer </td></tr>
<tr>
<td>Arduino Uno</td><td>D8 / PB0</td><td>Timer 1 </td></tr>
<tr>
<td>Arduino Leonardo</td><td>D4 / PD4</td><td>Timer 1 </td></tr>
<tr>
<td>Arduino Mega or Mega 2560</td><td>D49 / PL0</td><td>Timer 4 </td></tr>
</table>
<p>If your board is not pin-compatible with one of the above, then the source for the <a class="el" href="classRingOscillatorNoiseSource.html" title="Processes the signal from a ring oscillator based noise source. ">RingOscillatorNoiseSource</a> class will need to be modified to use a different pin/timer combination. Also, when the timer is in use by this class it cannot be used for other application tasks.</p>
<p>The example below shows how to initialize a ring oscillator based noise source and use it with <a class="el" href="classRNGClass.html">RNG</a>:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;Crypto.h&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;RNG.h&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;RingOscillatorNoiseSource.h&gt;</span></div>
<div class="line"></div>
<div class="line"><span class="comment">// Noise source to seed the random number generator.</span></div>
<div class="line"><a class="code" href="classRingOscillatorNoiseSource.html">RingOscillatorNoiseSource</a> noise;</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">void</span> setup() {</div>
<div class="line"> <span class="comment">// Initialize the random number generator with the application tag</span></div>
<div class="line"> <span class="comment">// &quot;MyApp 1.0&quot; and load the previous seed from EEPROM address 500.</span></div>
<div class="line"> RNG.<a class="code" href="classRNGClass.html#a77eb101a225ce541800ac1361a92b1a6">begin</a>(<span class="stringliteral">&quot;MyApp 1.0&quot;</span>, 500);</div>
<div class="line"></div>
<div class="line"> <span class="comment">// Add the noise source to the list of sources known to RNG.</span></div>
<div class="line"> RNG.<a class="code" href="classRNGClass.html#aacf23b192b0e4cc8726d9abe05f5a9db">addNoiseSource</a>(noise);</div>
<div class="line"></div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">void</span> loop() {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"></div>
<div class="line"> <span class="comment">// Perform regular housekeeping on the random number generator.</span></div>
<div class="line"> RNG.<a class="code" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13">loop</a>();</div>
<div class="line"></div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>For more information, see the documentation for <a class="el" href="classRNGClass.html">RNG</a>.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html">RNG</a>, <a class="el" href="classNoiseSource.html" title="Abstract base class for random noise sources. ">NoiseSource</a>, <a class="el" href="classTransistorNoiseSource.html" title="Processes the signal from a transistor-based noise source. ">TransistorNoiseSource</a> </dd></dl>
<p>Definition at line <a class="el" href="RingOscillatorNoiseSource_8h_source.html#l00029">29</a> of file <a class="el" href="RingOscillatorNoiseSource_8h_source.html">RingOscillatorNoiseSource.h</a>.</p>
</div><h2 class="groupheader">Member Function Documentation</h2>
<a class="anchor" id="ade7f7ed390e23722347b3c207912b3f9"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">bool RingOscillatorNoiseSource::calibrating </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const</td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">virtual</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Determine if the noise source is still calibrating itself. </p>
<dl class="section return"><dt>Returns</dt><dd>Returns true if calibration is in progress; false if the noise source is generating valid random data.</dd></dl>
<p>Noise sources that require calibration start doing so at system startup and then switch over to random data generation once calibration is complete. Since no random data is being generated during calibration, the output from <a class="el" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29">RNG.rand()</a> may be predictable. Use <a class="el" href="classRNGClass.html#a49e3231ba65a5e4b045bc90976e0a659">RNG.available()</a> to determine when sufficient entropy is available to generate good random values.</p>
<p>It is possible that the noise source never exits calibration. This can happen if the input voltage is insufficient to trigger noise or if the noise source is not connected. Noise sources may also periodically recalibrate themselves.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRingOscillatorNoiseSource.html#ad71698b5c92b41eef2f1322999b3eff9" title="Stirs entropy from this noise source into the global random number pool. ">stir()</a> </dd></dl>
<p>Implements <a class="el" href="classNoiseSource.html#ac8ac086f830efb5ffe3e8d506aa61c85">NoiseSource</a>.</p>
<p>Definition at line <a class="el" href="RingOscillatorNoiseSource_8cpp_source.html#l00178">178</a> of file <a class="el" href="RingOscillatorNoiseSource_8cpp_source.html">RingOscillatorNoiseSource.cpp</a>.</p>
</div>
</div>
<a class="anchor" id="ad71698b5c92b41eef2f1322999b3eff9"></a>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">void RingOscillatorNoiseSource::stir </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">virtual</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Stirs entropy from this noise source into the global random number pool. </p>
<p>This function should call <a class="el" href="classNoiseSource.html#a1af7449a5ae4a8acd34ac218c9eec6c1" title="Called from subclasses to output noise to the global random number pool. ">output()</a> to add the entropy from this noise source to the global random number pool.</p>
<p>The noise source should batch up the entropy data, providing between 16 and 48 bytes of data each time. If the noise source does not have sufficient entropy data at the moment, it should return without stiring the current data in.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRingOscillatorNoiseSource.html#ade7f7ed390e23722347b3c207912b3f9" title="Determine if the noise source is still calibrating itself. ">calibrating()</a>, <a class="el" href="classNoiseSource.html#a1af7449a5ae4a8acd34ac218c9eec6c1" title="Called from subclasses to output noise to the global random number pool. ">output()</a> </dd></dl>
<p>Implements <a class="el" href="classNoiseSource.html#a7ce647815524fe84f562aca5256e12f3">NoiseSource</a>.</p>
<p>Definition at line <a class="el" href="RingOscillatorNoiseSource_8cpp_source.html#l00201">201</a> of file <a class="el" href="RingOscillatorNoiseSource_8cpp_source.html">RingOscillatorNoiseSource.cpp</a>.</p>
</div>
</div>
<hr/>The documentation for this class was generated from the following files:<ul>
<li><a class="el" href="RingOscillatorNoiseSource_8h_source.html">RingOscillatorNoiseSource.h</a></li>
<li><a class="el" href="RingOscillatorNoiseSource_8cpp_source.html">RingOscillatorNoiseSource.cpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Apr 27 2018 12:01:32 for Arduino Cryptography Library by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink