Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / pyopenssl / b51bda3df396de582f9a275eb04e1ce54df9705f / . / doc / html / openssl-rand.html
blob: 46e7189a05f24a4170cb3022dac6386071de91e1 [file] [log] [blame]
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<title>3.2 rand -- An interface to the OpenSSL pseudo random number generator </title>
5<META NAME="description" CONTENT="3.2 rand -- An interface to the OpenSSL pseudo random number generator ">
6<META NAME="keywords" CONTENT="pyOpenSSL">
7<META NAME="resource-type" CONTENT="document">
8<META NAME="distribution" CONTENT="global">
9<link rel="STYLESHEET" href="pyOpenSSL.css">
10<LINK REL="next" href="openssl-ssl.html">
11<LINK REL="previous" href="openssl-crypto.html">
12<LINK REL="up" href="openssl.html">
13<LINK REL="next" href="openssl-ssl.html">
14</head>
15<body>
16<DIV CLASS="navigation">
17<table align="center" width="100%" cellpadding="0" cellspacing="2">
18<tr>
Jean-Paul Calderoneec155e52010-10-07 22:34:15 -0400[diff] [blame]19<td><A href="revoked.html"><img src="previous.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]20 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]21 alt="Previous Page" width="32"></A></td>
22<td><A href="openssl.html"><img src="up.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]23 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]24 alt="Up One Level" width="32"></A></td>
25<td><A href="openssl-ssl.html"><img src="next.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]26 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]27 alt="Next Page" width="32"></A></td>
28<td align="center" width="100%">Python OpenSSL Manual</td>
29<td><A href="contents.html"><img src="contents.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]30 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]31 alt="Contents" width="32"></A></td>
32<td><img src="blank.gif"
33 border="0" height="32"
34 alt="" width="32"></td>
35<td><img src="blank.gif"
36 border="0" height="32"
37 alt="" width="32"></td>
38</tr></table>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]39<b class="navlabel">Previous:</b> <a class="sectref" href="revoked.html">3.1.12 Revoked objects</A>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]40<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
41<b class="navlabel">Next:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
42<br><hr>
43</DIV>
44<!--End of Navigation Panel-->
45
46<H2><A NAME="SECTION000420000000000000000">&nbsp;</A>
47<BR>
483.2 <tt class="module">rand</tt> -- An interface to the OpenSSL pseudo random number generator
49</H2>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]50
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]51<P>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]52
53
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]54<P>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]55This module handles the OpenSSL pseudo random number generator (PRNG) and
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]56declares the following:
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]57
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]58<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]59<dl><dt><b><a name='l2h-117'><tt class='function'>add</tt></a></b>(<var>string, entropy</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]60<dd>
61Mix bytes from <var>string</var> into the PRNG state. The <var>entropy</var> argument is
62(the lower bound of) an estimate of how much randomness is contained in
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]63<var>string</var>, measured in bytes. For more information, see e.g. <a class="rfc" name="rfcref-2324"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]64href="http://www.ietf.org/rfc/rfc1750.txt">RFC 1750</a>.
65</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]66
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]67<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]68<dl><dt><b><a name='l2h-118'><tt class='function'>bytes</tt></a></b>(<var>num_bytes</var>)
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]69<dd>
70Get some random bytes from the PRNG as a string.
71
72<P>
73This is a wrapper for the C function <tt class="function">RAND_bytes</tt>.
74</dl>
75
76<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]77<dl><dt><b><a name='l2h-119'><tt class='function'>cleanup</tt></a></b>()
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]78<dd>
79Erase the memory used by the PRNG.
80
81<P>
82This is a wrapper for the C function <tt class="function">RAND_cleanup</tt>.
83</dl>
84
85<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]86<dl><dt><b><a name='l2h-120'><tt class='function'>egd</tt></a></b>(<var>path</var><big>[</big><var>, bytes</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]87<dd>
Jean-Paul Calderonef1b839d2008-09-01 12:06:06 -0400[diff] [blame]88Query the Entropy Gathering Daemon<A NAME="tex2html2"
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]89 HREF="#foot1227"><SUP>2</SUP></A> on socket <var>path</var> for <var>bytes</var>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]90bytes of random data and and uses <tt class="function">add</tt> to seed the PRNG. The default
91value of <var>bytes</var> is 255.
92</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]93
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]94<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]95<dl><dt><b><a name='l2h-121'><tt class='function'>load_file</tt></a></b>(<var>path</var><big>[</big><var>, bytes</var><big>]</big>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]96<dd>
97Read <var>bytes</var> bytes (or all of it, if <var>bytes</var> is negative) of data from
98the file <var>path</var> to seed the PRNG. The default value of <var>bytes</var> is -1.
99</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]100
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]101<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]102<dl><dt><b><a name='l2h-122'><tt class='function'>screen</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]103<dd>
104Add the current contents of the screen to the PRNG state.
105Availability: Windows.
106</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]107
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]108<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]109<dl><dt><b><a name='l2h-123'><tt class='function'>seed</tt></a></b>(<var>string</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]110<dd>
111This is equivalent to calling <tt class="function">add</tt> with <var>entropy</var> as the length
112of the string.
113</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]114
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]115<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]116<dl><dt><b><a name='l2h-124'><tt class='function'>status</tt></a></b>()
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]117<dd>
118Returns true if the PRNG has been seeded with enough data, and false otherwise.
119</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]120
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]121<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]122<dl><dt><b><a name='l2h-125'><tt class='function'>write_file</tt></a></b>(<var>path</var>)
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]123<dd>
124Write a number of random bytes (currently 1024) to the file <var>path</var>. This
125file can then be used with <tt class="function">load_file</tt> to seed the PRNG again.
126</dl>
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500[diff] [blame]127
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]128<P>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]129<dl><dt><b>exception <a name='l2h-126'><tt class='exception'>Error</tt></a></b>
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]130<dd>
131If the current RAND method supports any errors, this is raised when needed.
132The default method does not raise this when the entropy pool is depleted.
133
134<P>
135Whenever this exception is raised directly, it has a list of error messages
136from the OpenSSL error queue, where each item is a tuple <code>(<var>lib</var>,
137<var>function</var>, <var>reason</var>)</code>. Here <var>lib</var>, <var>function</var> and <var>reason</var>
138are all strings, describing where and what the problem is. See <span class='manpage'><i>err</i>(3)</span>
139for more information.
140</dl>
141
142<P>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]143<BR><HR><H4>Footnotes</H4>
144<DL>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]145<DT><A NAME="foot1227">... Daemon</A><A
Jean-Paul Calderonef1b839d2008-09-01 12:06:06 -0400[diff] [blame]146 href="openssl-rand.html#tex2html2"><SUP>2</SUP></A></DT>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]147<DD>See
148<a class="url" href="http://www.lothar.com/tech/crypto/">http://www.lothar.com/tech/crypto/</a>
149
150</DD>
151</DL>
152<DIV CLASS="navigation">
153<p><hr>
154<table align="center" width="100%" cellpadding="0" cellspacing="2">
155<tr>
Jean-Paul Calderoneec155e52010-10-07 22:34:15 -0400[diff] [blame]156<td><A href="revoked.html"><img src="previous.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]157 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]158 alt="Previous Page" width="32"></A></td>
159<td><A href="openssl.html"><img src="up.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]160 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]161 alt="Up One Level" width="32"></A></td>
162<td><A href="openssl-ssl.html"><img src="next.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]163 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]164 alt="Next Page" width="32"></A></td>
165<td align="center" width="100%">Python OpenSSL Manual</td>
166<td><A href="contents.html"><img src="contents.gif"
Jean-Paul Calderone215d51b2009-11-13 09:19:21 -0500[diff] [blame]167 border="0" height="32"
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]168 alt="Contents" width="32"></A></td>
169<td><img src="blank.gif"
170 border="0" height="32"
171 alt="" width="32"></td>
172<td><img src="blank.gif"
173 border="0" height="32"
174 alt="" width="32"></td>
175</tr></table>
Jean-Paul Calderone78caacc2011-04-07 15:41:56 -0400[diff] [blame]176<b class="navlabel">Previous:</b> <a class="sectref" href="revoked.html">3.1.12 Revoked objects</A>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]177<b class="navlabel">Up:</b> <a class="sectref" href="openssl.html">3 OpenSSL </A>
178<b class="navlabel">Next:</b> <a class="sectref" href="openssl-ssl.html">3.3 SSL </A>
179<hr>
Jean-Paul Calderone26ebc9e2011-04-11 19:57:10 -0400[diff] [blame]180<span class="release-info">Release 0.12.</span>
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500[diff] [blame]181</DIV>
182<!--End of Navigation Panel-->
183
184</BODY>
185</HTML>