diff options
Diffstat (limited to 'src/lib/libc/crypt/arc4random.3')
| -rw-r--r-- | src/lib/libc/crypt/arc4random.3 | 116 |
1 files changed, 0 insertions, 116 deletions
diff --git a/src/lib/libc/crypt/arc4random.3 b/src/lib/libc/crypt/arc4random.3 deleted file mode 100644 index 411860c28f..0000000000 --- a/src/lib/libc/crypt/arc4random.3 +++ /dev/null | |||
| @@ -1,116 +0,0 @@ | |||
| 1 | .\" $OpenBSD: arc4random.3,v 1.37 2019/09/29 16:30:35 jmc Exp $ | ||
| 2 | .\" | ||
| 3 | .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de> | ||
| 4 | .\" All rights reserved. | ||
| 5 | .\" | ||
| 6 | .\" Redistribution and use in source and binary forms, with or without | ||
| 7 | .\" modification, are permitted provided that the following conditions | ||
| 8 | .\" are met: | ||
| 9 | .\" 1. Redistributions of source code must retain the above copyright | ||
| 10 | .\" notice, this list of conditions and the following disclaimer. | ||
| 11 | .\" 2. Redistributions in binary form must reproduce the above copyright | ||
| 12 | .\" notice, this list of conditions and the following disclaimer in the | ||
| 13 | .\" documentation and/or other materials provided with the distribution. | ||
| 14 | .\" 3. All advertising materials mentioning features or use of this software | ||
| 15 | .\" must display the following acknowledgement: | ||
| 16 | .\" This product includes software developed by Niels Provos. | ||
| 17 | .\" 4. The name of the author may not be used to endorse or promote products | ||
| 18 | .\" derived from this software without specific prior written permission. | ||
| 19 | .\" | ||
| 20 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR | ||
| 21 | .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | ||
| 22 | .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | ||
| 23 | .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, | ||
| 24 | .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | ||
| 25 | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
| 26 | .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||
| 27 | .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
| 28 | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||
| 29 | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 30 | .\" | ||
| 31 | .\" Manual page, using -mandoc macros | ||
| 32 | .\" | ||
| 33 | .Dd $Mdocdate: September 29 2019 $ | ||
| 34 | .Dt ARC4RANDOM 3 | ||
| 35 | .Os | ||
| 36 | .Sh NAME | ||
| 37 | .Nm arc4random , | ||
| 38 | .Nm arc4random_buf , | ||
| 39 | .Nm arc4random_uniform | ||
| 40 | .Nd random number generator | ||
| 41 | .Sh SYNOPSIS | ||
| 42 | .In stdlib.h | ||
| 43 | .Ft uint32_t | ||
| 44 | .Fn arc4random "void" | ||
| 45 | .Ft void | ||
| 46 | .Fn arc4random_buf "void *buf" "size_t nbytes" | ||
| 47 | .Ft uint32_t | ||
| 48 | .Fn arc4random_uniform "uint32_t upper_bound" | ||
| 49 | .Sh DESCRIPTION | ||
| 50 | This family of functions provides higher quality data than those | ||
| 51 | described in | ||
| 52 | .Xr rand 3 , | ||
| 53 | .Xr random 3 , | ||
| 54 | and | ||
| 55 | .Xr rand48 3 . | ||
| 56 | .Pp | ||
| 57 | Use of these functions is encouraged for almost all random number | ||
| 58 | consumption because the other interfaces are deficient in either | ||
| 59 | quality, portability, standardization, or availability. | ||
| 60 | These functions can be called in almost all coding environments, | ||
| 61 | including | ||
| 62 | .Xr pthreads 3 | ||
| 63 | and | ||
| 64 | .Xr chroot 2 . | ||
| 65 | .Pp | ||
| 66 | High quality 32-bit pseudo-random numbers are generated very quickly. | ||
| 67 | On each call, a cryptographic pseudo-random number generator is used | ||
| 68 | to generate a new result. | ||
| 69 | One data pool is used for all consumers in a process, so that consumption | ||
| 70 | under program flow can act as additional stirring. | ||
| 71 | The subsystem is re-seeded from the kernel | ||
| 72 | .Xr random 4 | ||
| 73 | subsystem using | ||
| 74 | .Xr getentropy 2 | ||
| 75 | on a regular basis, and also upon | ||
| 76 | .Xr fork 2 . | ||
| 77 | .Pp | ||
| 78 | The | ||
| 79 | .Fn arc4random | ||
| 80 | function returns a single 32-bit value. | ||
| 81 | .Pp | ||
| 82 | .Fn arc4random_buf | ||
| 83 | fills the region | ||
| 84 | .Fa buf | ||
| 85 | of length | ||
| 86 | .Fa nbytes | ||
| 87 | with random data. | ||
| 88 | .Pp | ||
| 89 | .Fn arc4random_uniform | ||
| 90 | will return a single 32-bit value, uniformly distributed but less than | ||
| 91 | .Fa upper_bound . | ||
| 92 | This is recommended over constructions like | ||
| 93 | .Dq Li arc4random() % upper_bound | ||
| 94 | as it avoids "modulo bias" when the upper bound is not a power of two. | ||
| 95 | In the worst case, this function may consume multiple iterations | ||
| 96 | to ensure uniformity; see the source code to understand the problem | ||
| 97 | and solution. | ||
| 98 | .Sh RETURN VALUES | ||
| 99 | These functions are always successful, and no return value is | ||
| 100 | reserved to indicate an error. | ||
| 101 | .Sh SEE ALSO | ||
| 102 | .Xr rand 3 , | ||
| 103 | .Xr rand48 3 , | ||
| 104 | .Xr random 3 | ||
| 105 | .Sh HISTORY | ||
| 106 | These functions first appeared in | ||
| 107 | .Ox 2.1 . | ||
| 108 | .Pp | ||
| 109 | The original version of this random number generator used the | ||
| 110 | RC4 (also known as ARC4) algorithm. | ||
| 111 | In | ||
| 112 | .Ox 5.5 | ||
| 113 | it was replaced with the ChaCha20 cipher, and it may be replaced | ||
| 114 | again in the future as cryptographic techniques advance. | ||
| 115 | A good mnemonic is | ||
| 116 | .Dq A Replacement Call for Random . | ||