From f505644be64cd4844742b361a8ff411d70f4aa88 Mon Sep 17 00:00:00 2001
From: Niclas Eklund <nick@erlang.org>
Date: Fri, 15 Apr 2011 15:49:42 +0200
Subject: Adds NIFs for cryptographically strong random number generation. Also
 adds documentation and unit tests.

Thanks to Geoff Cant.
---
 lib/crypto/doc/src/crypto.xml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'lib/crypto/doc/src')

diff --git a/lib/crypto/doc/src/crypto.xml b/lib/crypto/doc/src/crypto.xml
index c407350c47..087e9ac00c 100644
--- a/lib/crypto/doc/src/crypto.xml
+++ b/lib/crypto/doc/src/crypto.xml
@@ -614,6 +614,19 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
           number generator.</p>
       </desc>
     </func>
+    <func>
+      <name>strong_rand_bytes(N) -> binary()</name>
+      <fsummary>Generate a binary of random bytes</fsummary>
+      <type>
+        <v>N = integer()</v>
+      </type>
+      <desc>
+        <p>Generates N bytes randomly uniform 0..255, and returns the
+        result in a binary. Uses a cryptographically secure prng seeded and
+        periodically mixed with operating system provided entropy. By default
+        this is the <c>RAND_bytes</c> method from OpenSSL.</p>
+      </desc>
+    </func>
     <func>
       <name>rand_uniform(Lo, Hi) -> N</name>
       <fsummary>Generate a random number</fsummary>
@@ -628,6 +641,29 @@ Mpint() = <![CDATA[<<ByteLen:32/integer-big, Bytes:ByteLen/binary>>]]>
           multi-precision integers.</p>
       </desc>
     </func>
+    <func>
+      <name>strong_rand_uniform(N, Top, Bottom) -> Mpint</name>
+      <fsummary>Generate an N bit random number</fsummary>
+      <type>
+        <v>N = non_neg_integer()</v>
+        <v>Top = -1 | 0 | 1</v>
+        <v>Bottom = 0 | 1</v>
+        <v>Mpint = binary()</v>
+      </type>
+      <desc>
+        <p>Generate an N bit random number using OpenSSL's
+        cryptographically strong pseudo random number generator
+        <c>BN_rand</c>.</p>
+        <p>The parameter <c>Top</c> places constraints on the most
+        significant bits of the generated number. If <c>Top</c> is 1, then the
+        two most significant bits will be set to 1, if <c>Top</c> is 0, the
+        most significant bit will be 1, and if <c>Top</c> is -1 then no
+        constraints are applied and thus the generated number may be less than
+        N bits long.</p>
+        <p>If <c>Bottom</c> is 1, then the generated number is
+        constrained to be odd.</p>
+      </desc>
+    </func>
     <func>
       <name>mod_exp(N, P, M) -> Result</name>
       <fsummary>Perform N ^ P mod M</fsummary>
-- 
cgit v1.2.3