share/man/man7d/random.7d

   1 '\" te
   2 .\"  Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH RANDOM 7D "Sep 1, 2008"
   7 .SH NAME
   8 random, urandom \- Strong random number generator device
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 /dev/random
  13 .fi
  14
  15 .LP
  16 .nf
  17 /dev/urandom
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The \fB/dev/random\fR and \fB/dev/urandom\fR files are special files that are a
  24 source for random bytes generated by the kernel random number generator device.
  25 The \fB/dev/random\fR and \fB/dev/urandom\fR files are suitable for
  26 applications requiring high quality random numbers for cryptographic purposes.
  27 .sp
  28 .LP
  29 The generator device produces random numbers from data and devices available to
  30 the kernel and estimates  the amount of randomness (or "entropy") collected
  31 from these sources. The entropy level determines the amount of high quality
  32 random numbers that are produced at a given time.
  33 .sp
  34 .LP
  35 Applications retrieve random bytes by reading \fB/dev/random\fR or
  36 \fB/dev/urandom\fR. The \fB/dev/random\fR interface returns random bytes only
  37 when sufficient amount of entropy has been collected. If there is no entropy to
  38 produce the requested number of bytes, \fB/dev/random\fR blocks until more
  39 entropy can be obtained. Non-blocking I/O mode can be used to disable the
  40 blocking behavior. The \fB/dev/random\fR interface also supports \fBpoll\fR(2).
  41 Note that using \fBpoll\fR(2) will not increase the speed at which random
  42 numbers can be read.
  43 .sp
  44 .LP
  45 Bytes retrieved from \fB/dev/random\fR provide the highest quality random
  46 numbers produced by the generator, and can be used to generate long term keys
  47 and other high value keying material.
  48 .sp
  49 .LP
  50 The  \fB/dev/urandom\fR interface returns bytes regardless of the amount of
  51 entropy available. It does not block on a read request due to lack of entropy.
  52 While bytes produced by the \fB/dev/urandom\fR interface are of lower quality
  53 than bytes produced by \fB/dev/random\fR, they are nonetheless suitable for
  54 less demanding and shorter term cryptographic uses such as short term session
  55 keys, paddings, and challenge strings.
  56 .sp
  57 .LP
  58 Data can be written to \fB/dev/random\fR and \fB/dev/urandom\fR. Data written
  59 to either special file is added to the generator's internal state. Data that is
  60 difficult to predict by other users may contribute randomness to the generator
  61 state and help improve the quality of future generated random numbers.
  62 .sp
  63 .LP
  64 \fB/dev/random\fR collects entropy from providers that are registered with the
  65 kernel-level cryptographic framework and implement random number generation
  66 routines. The \fBcryptoadm\fR(8) utility allows an administrator to configure
  67 which providers will be used with \fB/dev/random\fR.
  68 .SH ERRORS
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBEAGAIN\fR\fR
  73 .ad
  74 .RS 11n
  75 \fBO_NDELAY\fR or \fBO_NONBLOCK\fR was set and no random bytes are available
  76 for reading from \fB/dev/random\fR.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBEINTR\fR\fR
  83 .ad
  84 .RS 11n
  85 A signal was caught while reading and no data was             transferred.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBENOXIO \fR\fR
  92 .ad
  93 .RS 11n
  94 \fBopen\fR(2) request failed on \fB/dev/random\fR because no entropy provider
  95 is available.
  96 .RE
  97
  98 .SH FILES
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB/dev/random\fR\fR
 103 .ad
 104 .RS 16n
 105
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB/dev/urandom\fR\fR
 112 .ad
 113 .RS 16n
 114
 115 .RE
 116
 117 .SH ATTRIBUTES
 118 .sp
 119 .LP
 120 See \fBattributes\fR(5) for descriptions of the following attributes:
 121 .sp
 122
 123 .sp
 124 .TS
 125 box;
 126 c | c
 127 l | l .
 128 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 129 Interface Stability     Evolving
 130 .TE
 131
 132 .SH SEE ALSO
 133 .sp
 134 .LP
 135 \fBcryptoadm\fR(8), \fBopen\fR(2), \fBpoll\fR(2), \fBattributes\fR(5)
 136 .SH NOTES
 137 .sp
 138 .LP
 139 \fB/dev/random\fR can be configured to use only the hardware-based providers
 140 registered with the kernel-level cryptographic framework by disabling the
 141 software-based provider using \fBcryptoadm\fR(8). You can also use
 142 \fBcryptoadm\fR(8) to obtain the name of the software-based provider.
 143 .sp
 144 .LP
 145 Because no entropy is available, disabling all randomness providers causes
 146 \fBread\fR(2) and \fBpoll\fR(2) on \fB/dev/random\fR to block indefinitely and
 147 results in a warning message being logged and displayed on the system console.
 148 However, \fBread\fR(2) and \fBpoll\fR(2) on \fB/dev/urandom\fR continue to work
 149 in this case.
 150 .sp
 151 .LP
 152 An implementation of the \fB/dev/random\fR and \fB/dev/urandom\fR kernel-based
 153 random number generator first appeared in Linux 1.3.30.
 154 .sp
 155 .LP
 156 A \fB/dev/random\fR interface for Solaris first appeared as part of the
 157 CryptoRand implementation.