mirror of
https://github.com/taigrr/arduinolibs
synced 2025-01-18 04:33:12 -08:00
528 lines
39 KiB
HTML
528 lines
39 KiB
HTML
<!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>ArduinoLibs: RNGClass 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">ArduinoLibs
|
|
</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 Page</span></a></li>
|
|
<li><a href="pages.html"><span>Related Pages</span></a></li>
|
|
<li><a href="modules.html"><span>Modules</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 List</span></a></li>
|
|
<li><a href="classes.html"><span>Class Index</span></a></li>
|
|
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
|
|
<li><a href="functions.html"><span>Class 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"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </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> |
|
|
<a href="#pub-static-attribs">Static Public Attributes</a> |
|
|
<a href="classRNGClass-members.html">List of all members</a> </div>
|
|
<div class="headertitle">
|
|
<div class="title">RNGClass Class Reference</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
|
|
<p>Pseudo random number generator suitable for cryptography.
|
|
<a href="classRNGClass.html#details">More...</a></p>
|
|
|
|
<p><code>#include <<a class="el" href="RNG_8h_source.html">RNG.h</a>></code></p>
|
|
<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:acbcf327242f51ae2d9209aeaa45e30e9"><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#acbcf327242f51ae2d9209aeaa45e30e9">RNGClass</a> ()</td></tr>
|
|
<tr class="memdesc:acbcf327242f51ae2d9209aeaa45e30e9"><td class="mdescLeft"> </td><td class="mdescRight">Constructs a new random number generator instance. <a href="#acbcf327242f51ae2d9209aeaa45e30e9">More...</a><br/></td></tr>
|
|
<tr class="separator:acbcf327242f51ae2d9209aeaa45e30e9"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:aef3ee2fb14a39caf650dc90a0226dd31"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="aef3ee2fb14a39caf650dc90a0226dd31"></a>
|
|
 </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#aef3ee2fb14a39caf650dc90a0226dd31">~RNGClass</a> ()</td></tr>
|
|
<tr class="memdesc:aef3ee2fb14a39caf650dc90a0226dd31"><td class="mdescLeft"> </td><td class="mdescRight">Destroys this random number generator instance. <br/></td></tr>
|
|
<tr class="separator:aef3ee2fb14a39caf650dc90a0226dd31"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a7f1aab3c324f8e8a424d683425e0fcf8"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8">begin</a> (const char *tag, int eepromAddress)</td></tr>
|
|
<tr class="memdesc:a7f1aab3c324f8e8a424d683425e0fcf8"><td class="mdescLeft"> </td><td class="mdescRight">Initializes the random number generator. <a href="#a7f1aab3c324f8e8a424d683425e0fcf8">More...</a><br/></td></tr>
|
|
<tr class="separator:a7f1aab3c324f8e8a424d683425e0fcf8"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:aacf23b192b0e4cc8726d9abe05f5a9db"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#aacf23b192b0e4cc8726d9abe05f5a9db">addNoiseSource</a> (<a class="el" href="classNoiseSource.html">NoiseSource</a> &source)</td></tr>
|
|
<tr class="memdesc:aacf23b192b0e4cc8726d9abe05f5a9db"><td class="mdescLeft"> </td><td class="mdescRight">Adds a noise source to the random number generator. <a href="#aacf23b192b0e4cc8726d9abe05f5a9db">More...</a><br/></td></tr>
|
|
<tr class="separator:aacf23b192b0e4cc8726d9abe05f5a9db"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a5848e87a5f2f0302c88b0377f0e3366d"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a5848e87a5f2f0302c88b0377f0e3366d">setAutoSaveTime</a> (uint16_t minutes)</td></tr>
|
|
<tr class="memdesc:a5848e87a5f2f0302c88b0377f0e3366d"><td class="mdescLeft"> </td><td class="mdescRight">Sets the amount of time between automatic seed saves. <a href="#a5848e87a5f2f0302c88b0377f0e3366d">More...</a><br/></td></tr>
|
|
<tr class="separator:a5848e87a5f2f0302c88b0377f0e3366d"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a418a833cf18198fd7e5d6dbd78c99c29"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29">rand</a> (uint8_t *data, size_t len)</td></tr>
|
|
<tr class="memdesc:a418a833cf18198fd7e5d6dbd78c99c29"><td class="mdescLeft"> </td><td class="mdescRight">Generates random bytes into a caller-supplied buffer. <a href="#a418a833cf18198fd7e5d6dbd78c99c29">More...</a><br/></td></tr>
|
|
<tr class="separator:a418a833cf18198fd7e5d6dbd78c99c29"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a49e3231ba65a5e4b045bc90976e0a659"><td class="memItemLeft" align="right" valign="top">bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a49e3231ba65a5e4b045bc90976e0a659">available</a> (size_t len) const </td></tr>
|
|
<tr class="memdesc:a49e3231ba65a5e4b045bc90976e0a659"><td class="mdescLeft"> </td><td class="mdescRight">Determine if there is sufficient entropy available for a specific request size. <a href="#a49e3231ba65a5e4b045bc90976e0a659">More...</a><br/></td></tr>
|
|
<tr class="separator:a49e3231ba65a5e4b045bc90976e0a659"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ad99535ea23ae2fec55bdebb8c24def02"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02">stir</a> (const uint8_t *data, size_t len, unsigned int credit=0)</td></tr>
|
|
<tr class="memdesc:ad99535ea23ae2fec55bdebb8c24def02"><td class="mdescLeft"> </td><td class="mdescRight">Stirs additional entropy data into the random pool. <a href="#ad99535ea23ae2fec55bdebb8c24def02">More...</a><br/></td></tr>
|
|
<tr class="separator:ad99535ea23ae2fec55bdebb8c24def02"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a139584fb249148e2058d1d645d090db7"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7">save</a> ()</td></tr>
|
|
<tr class="memdesc:a139584fb249148e2058d1d645d090db7"><td class="mdescLeft"> </td><td class="mdescRight">Saves the random seed to EEPROM. <a href="#a139584fb249148e2058d1d645d090db7">More...</a><br/></td></tr>
|
|
<tr class="separator:a139584fb249148e2058d1d645d090db7"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a8cb91e39f0c4591de5bf98b1e2880b13"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13">loop</a> ()</td></tr>
|
|
<tr class="memdesc:a8cb91e39f0c4591de5bf98b1e2880b13"><td class="mdescLeft"> </td><td class="mdescRight">Run periodic housekeeping tasks on the random number generator. <a href="#a8cb91e39f0c4591de5bf98b1e2880b13">More...</a><br/></td></tr>
|
|
<tr class="separator:a8cb91e39f0c4591de5bf98b1e2880b13"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:a9901367d86f2303a59bbc12fe91cad00"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#a9901367d86f2303a59bbc12fe91cad00">destroy</a> ()</td></tr>
|
|
<tr class="memdesc:a9901367d86f2303a59bbc12fe91cad00"><td class="mdescLeft"> </td><td class="mdescRight">Destroys the data in the random number pool and the saved seed in EEPROM. <a href="#a9901367d86f2303a59bbc12fe91cad00">More...</a><br/></td></tr>
|
|
<tr class="separator:a9901367d86f2303a59bbc12fe91cad00"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-static-attribs"></a>
|
|
Static Public Attributes</h2></td></tr>
|
|
<tr class="memitem:ae3a013bfc73795fd26ee36e70d89f4c2"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ae3a013bfc73795fd26ee36e70d89f4c2"></a>
|
|
static const int </td><td class="memItemRight" valign="bottom"><a class="el" href="classRNGClass.html#ae3a013bfc73795fd26ee36e70d89f4c2">SEED_SIZE</a> = 49</td></tr>
|
|
<tr class="memdesc:ae3a013bfc73795fd26ee36e70d89f4c2"><td class="mdescLeft"> </td><td class="mdescRight">Size of a saved random number seed in EEPROM space. <br/></td></tr>
|
|
<tr class="separator:ae3a013bfc73795fd26ee36e70d89f4c2"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<div class="textblock"><p>Pseudo random number generator suitable for cryptography. </p>
|
|
<p>Random number generators must be seeded properly before they can be used or an adversary may be able to predict the random output. Seed data may be:</p>
|
|
<ul>
|
|
<li>Device-specific, for example serial numbers or MAC addresses. </li>
|
|
<li>Application-specific, unique to the application. The tag that is passed to <a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> is an example of an application-specific value. </li>
|
|
<li>Noise-based, generated by a hardware random number generator that provides unpredictable values from a noise source.</li>
|
|
</ul>
|
|
<p>The following example demonstrates how to initialise the random number generator:</p>
|
|
<div class="fragment"><div class="line"><span class="preprocessor">#include <SPI.h></span></div>
|
|
<div class="line"><span class="preprocessor">#include <Ethernet.h></span></div>
|
|
<div class="line"><span class="preprocessor">#include <Crypto.h></span></div>
|
|
<div class="line"><span class="preprocessor">#include <RNG.h></span></div>
|
|
<div class="line"><span class="preprocessor">#include <TransistorNoiseSource.h></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="classTransistorNoiseSource.html">TransistorNoiseSource</a> noise(A1);</div>
|
|
<div class="line"></div>
|
|
<div class="line"><span class="comment">// MAC address for Ethernet communication.</span></div>
|
|
<div class="line">byte mac_address[] = {0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED};</div>
|
|
<div class="line"></div>
|
|
<div class="line"><span class="keywordtype">void</span> setup() {</div>
|
|
<div class="line"> <span class="comment">// Initialize the Ethernet shield.</span></div>
|
|
<div class="line"> Ethernet.begin(mac_address);</div>
|
|
<div class="line"></div>
|
|
<div class="line"> <span class="comment">// Initialize the random number generator with the application tag</span></div>
|
|
<div class="line"> <span class="comment">// "MyApp 1.0" and load the previous seed from EEPROM address 950.</span></div>
|
|
<div class="line"> RNG.<a class="code" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8">begin</a>(<span class="stringliteral">"MyApp 1.0"</span>, 950);</div>
|
|
<div class="line"></div>
|
|
<div class="line"> <span class="comment">// Stir in the Ethernet MAC address.</span></div>
|
|
<div class="line"> RNG.<a class="code" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02">stir</a>(mac_address, <span class="keyword">sizeof</span>(mac_address));</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><!-- fragment --><p>The application should regularly call <a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a> to stir in new data from the registered noise sources and to periodically save the seed:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> <a class="code" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13">loop</a>() {</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>The <a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a> function will automatically save the random number seed on a regular basis. By default the seed is saved every hour but this can be changed using <a class="el" href="classRNGClass.html#a5848e87a5f2f0302c88b0377f0e3366d" title="Sets the amount of time between automatic seed saves. ">setAutoSaveTime()</a>.</p>
|
|
<p>Keep in mind that saving too often may cause the EEPROM to wear out quicker. It is wise to limit saving to once an hour or once a day depending upon how long you intend to field the device before replacing it. For example, an EEPROM rated for 100k erase/write cycles will last about 69 days saving once a minute or 11 years saving once an hour.</p>
|
|
<p>The application can still elect to call <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> at any time if wants. For example, if the application can detect power loss or shutdown conditions programmatically, then it may make sense to force a <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> of the seed upon shutdown.</p>
|
|
<p>The Arduino Due does not have EEPROM so RNG saves the seed into the last page of system flash memory instead. The RNG class will also mix in data from the CPU's built-in True Random Number Generator (TRNG). Assuming that the CPU's TRNG is trustworthy, this should be sufficient to properly seed the random number generator. It is recommended to also mix in data from other noise sources just in case the CPU's TRNG is not trustworthy.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classNoiseSource.html" title="Abstract base class for random noise sources. ">NoiseSource</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8h_source.html#l00031">31</a> of file <a class="el" href="RNG_8h_source.html">RNG.h</a>.</p>
|
|
</div><h2 class="groupheader">Constructor & Destructor Documentation</h2>
|
|
<a class="anchor" id="acbcf327242f51ae2d9209aeaa45e30e9"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">RNGClass::RNGClass </td>
|
|
<td>(</td>
|
|
<td class="paramname"></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Constructs a new random number generator instance. </p>
|
|
<p>This constructor must be followed by a call to <a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> to properly initialize the random number generator.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00230">230</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<h2 class="groupheader">Member Function Documentation</h2>
|
|
<a class="anchor" id="aacf23b192b0e4cc8726d9abe05f5a9db"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::addNoiseSource </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="classNoiseSource.html">NoiseSource</a> & </td>
|
|
<td class="paramname"><em>source</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Adds a noise source to the random number generator. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">source</td><td>The noise source to add, which will be polled regularly by <a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a> to accumulate noise-based entropy from the source.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<p>RNG supports a maximum of four noise sources. If the application needs more than that then the application must poll the noise sources itself by calling <a class="el" href="classNoiseSource.html#a7ce647815524fe84f562aca5256e12f3" title="Stirs entropy from this noise source into the global random number pool. ">NoiseSource::stir()</a> directly.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a>, <a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00459">459</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a49e3231ba65a5e4b045bc90976e0a659"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">bool RNGClass::available </td>
|
|
<td>(</td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>len</em></td><td>)</td>
|
|
<td> const</td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Determine if there is sufficient entropy available for a specific request size. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">len</td><td>The number of bytes of random data that will be requested via a call to <a class="el" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29" title="Generates random bytes into a caller-supplied buffer. ">rand()</a>. </td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>Returns true if there is at least <em>len</em> * 8 bits of entropy in the random number pool, or false if not.</dd></dl>
|
|
<p>This function can be used by the application to wait for sufficient entropy to become available from the system's noise sources before generating important values. For example:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">bool</span> haveKey = <span class="keyword">false</span>;</div>
|
|
<div class="line">byte key[32];</div>
|
|
<div class="line"></div>
|
|
<div class="line"><span class="keywordtype">void</span> <a class="code" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13">loop</a>() {</div>
|
|
<div class="line"> ...</div>
|
|
<div class="line"></div>
|
|
<div class="line"> <span class="keywordflow">if</span> (!haveKey && RNG.<a class="code" href="classRNGClass.html#a49e3231ba65a5e4b045bc90976e0a659">available</a>(<span class="keyword">sizeof</span>(key))) {</div>
|
|
<div class="line"> RNG.<a class="code" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29">rand</a>(key, <span class="keyword">sizeof</span>(key));</div>
|
|
<div class="line"> haveKey = <span class="keyword">true</span>;</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"></div>
|
|
<div class="line"> ...</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>If <em>len</em> is larger than the maximum number of entropy credits supported by the random number pool (384 bits, 48 bytes), then the maximum will be used instead. For example, asking if 512 bits (64 bytes) are available will return true if in reality only 384 bits are available. If this is a problem for the application's security requirements, then large requests for random data should be broken up into smaller chunks with the application waiting for the entropy pool to refill between chunks.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29" title="Generates random bytes into a caller-supplied buffer. ">rand()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00585">585</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a7f1aab3c324f8e8a424d683425e0fcf8"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::begin </td>
|
|
<td>(</td>
|
|
<td class="paramtype">const char * </td>
|
|
<td class="paramname"><em>tag</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">int </td>
|
|
<td class="paramname"><em>eepromAddress</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Initializes the random number generator. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">tag</td><td>A string that is stirred into the random pool at startup; usually this should be a value that is unique to the application and version such as "MyApp 1.0" so that different applications do not generate the same sequence of values upon first boot. </td></tr>
|
|
<tr><td class="paramname">eepromAddress</td><td>The EEPROM address to load the previously saved seed from and to save new seeds when <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> is called. There must be at least SEED_SIZE (49) bytes of EEPROM space available at the address.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<p>This function should be followed by calls to <a class="el" href="classRNGClass.html#aacf23b192b0e4cc8726d9abe05f5a9db" title="Adds a noise source to the random number generator. ">addNoiseSource()</a> to register the application's noise sources.</p>
|
|
<p>The <em>eepromAddress</em> is ignored on the Arduino Due. The seed is instead stored in the last page of system flash memory.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#aacf23b192b0e4cc8726d9abe05f5a9db" title="Adds a noise source to the random number generator. ">addNoiseSource()</a>, <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a>, <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00359">359</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a9901367d86f2303a59bbc12fe91cad00"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::destroy </td>
|
|
<td>(</td>
|
|
<td class="paramname"></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Destroys the data in the random number pool and the saved seed in EEPROM. </p>
|
|
<p>This function attempts to throw away any data that could theoretically be used to predict previous and future outputs of the random number generator if the device is captured, sold, or otherwise compromised.</p>
|
|
<p>After this function is called, <a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> must be called again to re-initialize the random number generator.</p>
|
|
<dl class="section note"><dt>Note</dt><dd>The <a class="el" href="classRNGClass.html#a418a833cf18198fd7e5d6dbd78c99c29" title="Generates random bytes into a caller-supplied buffer. ">rand()</a> and <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> functions take some care to manage the random number pool in a way that makes prediction of past outputs from a captured state very difficult. Future outputs may be predictable if noise or other high-entropy data is not mixed in with <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a> on a regular basis.</dd></dl>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a7f1aab3c324f8e8a424d683425e0fcf8" title="Initializes the random number generator. ">begin()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00806">806</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a8cb91e39f0c4591de5bf98b1e2880b13"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::loop </td>
|
|
<td>(</td>
|
|
<td class="paramname"></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Run periodic housekeeping tasks on the random number generator. </p>
|
|
<p>This function must be called on a regular basis from the application's main "loop()" function. </p>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00715">715</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a418a833cf18198fd7e5d6dbd78c99c29"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::rand </td>
|
|
<td>(</td>
|
|
<td class="paramtype">uint8_t * </td>
|
|
<td class="paramname"><em>data</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>len</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Generates random bytes into a caller-supplied buffer. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">data</td><td>Points to the buffer to fill with random bytes. </td></tr>
|
|
<tr><td class="paramname">len</td><td>Number of bytes to generate.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<p>Calling this function will decrease the amount of entropy in the random number pool by <em>len</em> * 8 bits. If there isn't enough entropy, then this function will still return <em>len</em> bytes of random data generated from what entropy it does have.</p>
|
|
<p>If the application requires a specific amount of entropy before generating important values, the <a class="el" href="classRNGClass.html#a49e3231ba65a5e4b045bc90976e0a659" title="Determine if there is sufficient entropy available for a specific request size. ">available()</a> function can be polled to determine when sufficient entropy is available.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a49e3231ba65a5e4b045bc90976e0a659" title="Determine if there is sufficient entropy available for a specific request size. ">available()</a>, <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00508">508</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a139584fb249148e2058d1d645d090db7"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::save </td>
|
|
<td>(</td>
|
|
<td class="paramname"></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Saves the random seed to EEPROM. </p>
|
|
<p>During system startup, noise sources typically won't have accumulated much entropy. But startup is usually the time when the system most needs to generate random data for session keys, IV's, and the like.</p>
|
|
<p>The purpose of this function is to pass some of the accumulated entropy from one session to the next after a loss of power. Thus, once the system has been running for a while it will get progressively better at generating random values and the accumulated entropy will not be completely lost.</p>
|
|
<p>Normally it isn't necessary to call <a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a> directly. The <a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a> function will automatically save the seed on a periodic basis (default of 1 hour).</p>
|
|
<p>The seed that is saved is generated in such a way that it cannot be used to predict random values that were generated previously or subsequently in the current session. So a compromise of the EEPROM contents of a captured device should not result in compromise of random values that have already been generated. However, if power is lost and the system restarted, then there will be a short period of time where the random state will be predictable from the seed. For this reason it is very important to <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a> in new noise data at startup.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a>, <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00687">687</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="a5848e87a5f2f0302c88b0377f0e3366d"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::setAutoSaveTime </td>
|
|
<td>(</td>
|
|
<td class="paramtype">uint16_t </td>
|
|
<td class="paramname"><em>minutes</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Sets the amount of time between automatic seed saves. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">minutes</td><td>The number of minutes between automatic seed saves.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<p>The default time between automatic seed saves is 1 hour.</p>
|
|
<p>This function is intended to help with EEPROM wear by slowing down how often seed data is saved as noise is stirred into the random pool. The exact period to use depends upon how long you intend to field the device before replacing it. For example, an EEPROM rated for 100k erase/write cycles will last about 69 days saving once a minute or 11 years saving once an hour.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a139584fb249148e2058d1d645d090db7" title="Saves the random seed to EEPROM. ">save()</a>, <a class="el" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02" title="Stirs additional entropy data into the random pool. ">stir()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00484">484</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="ad99535ea23ae2fec55bdebb8c24def02"></a>
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">void RNGClass::stir </td>
|
|
<td>(</td>
|
|
<td class="paramtype">const uint8_t * </td>
|
|
<td class="paramname"><em>data</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">size_t </td>
|
|
<td class="paramname"><em>len</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">unsigned int </td>
|
|
<td class="paramname"><em>credit</em> = <code>0</code> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
|
|
<p>Stirs additional entropy data into the random pool. </p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramname">data</td><td>Points to the additional data to be stirred in. </td></tr>
|
|
<tr><td class="paramname">len</td><td>Number of bytes to be stirred in. </td></tr>
|
|
<tr><td class="paramname">credit</td><td>The number of bits of entropy to credit for the data that is stirred in. Note that this is bits, not bytes.</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<p>The maximum credit allowed is <em>len</em> * 8 bits, indicating that every bit in the input <em>data</em> is good and random. Practical noise sources are rarely that good, so <em>credit</em> will usually be smaller. For example, to credit 2 bits of entropy per byte, the function would be called as follows:</p>
|
|
<div class="fragment"><div class="line">RNG.<a class="code" href="classRNGClass.html#ad99535ea23ae2fec55bdebb8c24def02">stir</a>(noise_data, noise_bytes, noise_bytes * 2);</div>
|
|
</div><!-- fragment --><p>If <em>credit</em> is zero, then the <em>data</em> will be stirred in but no entropy credit is given. This is useful for static values like serial numbers and MAC addresses that are different between devices but highly predictable.</p>
|
|
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classRNGClass.html#a8cb91e39f0c4591de5bf98b1e2880b13" title="Run periodic housekeeping tasks on the random number generator. ">loop()</a> </dd></dl>
|
|
|
|
<p>Definition at line <a class="el" href="RNG_8cpp_source.html#l00618">618</a> of file <a class="el" href="RNG_8cpp_source.html">RNG.cpp</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<hr/>The documentation for this class was generated from the following files:<ul>
|
|
<li><a class="el" href="RNG_8h_source.html">RNG.h</a></li>
|
|
<li><a class="el" href="RNG_8cpp_source.html">RNG.cpp</a></li>
|
|
</ul>
|
|
</div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated on Sun Feb 14 2016 08:32:00 for ArduinoLibs by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.6
|
|
</small></address>
|
|
</body>
|
|
</html>
|