Add a arc4random_uniform() that returns a uniformly distributed number

in the range 0 <= x < upper_bound

Please use this new API instead of "arc4random() % upper_bound", as it
avoids the "modulo bias" that favours small results when upper_bound is
not a power of two.

feedback deraadt@ mcbride@; ok deraadt@

2 files changed, 12 insertions, 4 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3a78a60932e..da1dfd6426c 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.137 2007/11/28 23:24:07 art Exp $
+#	$OpenBSD: Makefile,v 1.138 2008/03/02 21:29:06 djm Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -254,7 +254,8 @@ MLINKS+=random.9 add_true_randomness.9 \
 	random.9 add_audio_randomness.9 \
 	random.9 get_random_bytes.9 \
 	random.9 arc4random.9 \
-	random.9 arc4random_bytes.9
+	random.9 arc4random_bytes.9 \
+	random.9 arc4random_uniform.9
 MLINKS+=rasops.9 rasops_init.9 rasops.9 rasops_reconfig.9
 MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
 	rssadapt.9 ieee80211_rssadapt_input.9 \
diff --git a/share/man/man9/random.9 b/share/man/man9/random.9
index b17faf8d00e..ac4246dceba 100644
--- a/share/man/man9/random.9
+++ b/share/man/man9/random.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: random.9,v 1.22 2007/05/31 19:20:01 jmc Exp $
+.\"	$OpenBSD: random.9,v 1.23 2008/03/02 21:29:07 djm Exp $
 .\"
 .\" Copyright (c) 1996,2000 Michael Shalayeff
 .\" All rights reserved.
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 31 2007 $
+.Dd $Mdocdate: March 2 2008 $
 .Dt RND 9
 .Os
 .Sh NAME
@@ -51,6 +51,8 @@
 .Fn arc4random "void"
 .Ft void
 .Fn arc4random_bytes "void *buf" "size_t nbytes"
+.Ft u_int32_t
+.Fn arc4random_uniform "u_int32_t upper_bound"
 .Sh DESCRIPTION
 The
 .Fn add_mouse_randomness ,
@@ -87,6 +89,11 @@ and
 will give random 32 bit numbers hashed with
 the ARC4 algorithm, which appears to be faster and less abusive
 to the entropy pool.
+.Pp
+.Fn arc4random_uniform
+will return a uniformly distributed random number less than
+.Fa upper_bound ,
+avoiding "modulo bias" when the upper bound is not a divisor of 2**32.
 .Sh SEE ALSO
 .Xr arc4random 3 ,
 .Xr pchb 4 ,