random.4: Document write and document the ioctl interface of /dev/random
PATCH 1/1 random.4: Document write and document the ioctl interface of /dev/random
Michael, all,
Below you can find an update to random.4. The update consists out of two parts:
- a minor thing which just documents what happens if a write to /dev/(u)random is performed, which is used in the example script but not explicitely mentioned.
- the other (biggest) part is the documentation of the ioctl() interface which /dev/(u)random exposes. This ioctl() lives in drivers/char/random.c and the primitives can be found in include/linux/random.h
One comment remains, there used to be an RNDGETPOOL ioctl() which
disappeared in v2.6.9. I found two patches on the net:
- http://www.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.8.1/2.6.8.1-mm4/broken-out/dev-random-remove-rndgetpool-ioctl.patch
- https://lkml.org/lkml/2004/3/25/168
But as far as I can tell the first one got applied but the 2nd one seems more correct. The result is that even today one can still find traces of the RNDGETPOOL ioctl() in the header files. Is this there for historical reasons or because it might break userspace, even though using it will just give an EINVAL.
Anyhow, feedback welcome.
my 2 cent
E.
--- man4/random.4 | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-)
man4/random.4 +62 -1
@@ -14,9 +14,13 @@ .\" Add a Usage subsection that recommends most users to use .\" /dev/urandom, and emphasizes parsimonious usage of /dev/random. .\" -.TH RANDOM 4 2010-08-29 "Linux" "Linux Programmer's Manual" +.TH RANDOM 4 2013-02-17 "Linux" "Linux Programmer's Manual" .SH NAME random, urandom \- kernel random number source devices +.SH SYNOPSIS +#include <linux/random.h> +.sp +.BI "int ioctl(" fd ", RND" request ", " param ");" .SH DESCRIPTION The character special files \fI/dev/random\fP and \fI/dev/urandom\fP (present since Linux 1.3.30)
@@ -49,6 +53,12 @@ literature, but it is theoretically possible that such an attack may exist. If this is a concern in your application, use \fI/dev/random\fP instead. +.LP +Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the +entropy pool with the data written, but this will not result in a +higher entropy count. This means that it will impact the contents +read from both files but it will not make reads from +\fI/dev/random\fP faster. .SS Usage If you are unsure about whether you should use .IR /dev/random
@@ -206,6 +216,57 @@ and contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. The former is generated afresh for each read, the latter was generated once. +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to either \fI/dev/random\fP +or \fI/dev/urandom\fP. All requests performed will interact with the input +entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. +The +.B CAP_SYS_ADMIN +capability is required for all requests except +.B RNDGETENTCNT. +.TP +.BR RNDGETENTCNT +Retrieve the entropy count of the input pool, the contents will be the same +as the +.I entropy_avail +file under proc. +The result will be stored in the int pointed to by the argument. +.TP +.BR RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool by the value pointed +to by the argument. +.TP +.BR RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.BR RNDADDENTROPY +Add some additional entropy to the input pool, incrementing the entropy count. +Unlike writing to \fI/dev/random\fP or \fI/dev/urandom\fP which only adds some +data but does not increment the entropy count. The following structure is used: +.IP +.IN +4n +.NF +struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.FI +.IN +.IP +Here +.I entropy_count +is the value added to (or subtracted from) from the entropy count. And +.I buf +is the buffer of size +.I buf_size +which gets added to the entropy pool. +.TP +.BR RNDZAPENTCNT ", " RNDCLEARPOOL +Zero the entropy count of all pools and add some system data (such as +wall clock) to the pools. .SH FILES /dev/random .br
Signature · 6 lines
1.7.10.4 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 1361125279-9359-1-git-send-email-eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Hello Elie,
Quoted 17 lines · Elie De Brauwer
Michael, all,
Below you can find an update to random.4. The update consists out of two parts:
- a minor thing which just documents what happens if a write to /dev/(u)random is performed, which is used in the example script but not explicitely mentioned.
- the other (biggest) part is the documentation of theioctl()interface which /dev/(u)random exposes. Thisioctl()lives indrivers/char/random.cand the primitives can be found ininclude/linux/random.hOne comment remains, there used to be an RNDGETPOOL
ioctl()which
disappeared in v2.6.9. I found two patches on the net:
- http://www.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.8.1/2.6.8.1-mm4/broken-out/dev-random-remove-rndgetpool-ioctl.patch
- https://lkml.org/lkml/2004/3/25/168
Quoted 7 lines
But as far as I can tell the first one got applied but the 2nd one seems more correct. The result is that even today one can still find traces of the RNDGETPOOL
ioctl()in the header files. Is this there for historical reasons or because it might break userspace, even though using it will just give an EINVAL.Anyhow, feedback welcome.
Thanks for this. I've applied.
Cheers,
Michael
Quoted 102 lines
my 2 cent
E.Signed-off-by Elie De Brauwer <[email protected]>--- man4/random.4 | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-)man4/random.4 +62
-2@@ -14,9 +14,13 @@ .\" Add a Usage subsection that recommends most users to use .\" /dev/urandom, and emphasizes parsimonious usage of /dev/random. .\" -.TH RANDOM 4 2010-08-29 "Linux" "Linux Programmer's Manual" +.TH RANDOM 4 2013-02-17 "Linux" "Linux Programmer's Manual" .SH NAME random, urandom \- kernel random number source devices +.SH SYNOPSIS +#include <linux/random.h> +.sp +.BI "int ioctl(" fd ", RND" request ", " param ");" .SH DESCRIPTION The character special files \fI/dev/random\fP and \fI/dev/urandom\fP (present since Linux 1.3.30)@@ -49,6 +53,12 @@ literature, but it is theoretically possible that such an attack may exist. If this is a concern in your application, use \fI/dev/random\fP instead. +.LP +Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the +entropy pool with the data written, but this will not result in a +higher entropy count. This means that it will impact the contents +read from both files but it will not make reads from +\fI/dev/random\fP faster. .SS Usage If you are unsure about whether you should use .IR /dev/random@@ -206,6 +216,57 @@ and contain random strings like 6fd5a44b-35f4-4ad4-a9b9-6b9be13e1fe9. The former is generated afresh for each read, the latter was generated once. +.SS ioctl(2) interface +The following +.BR ioctl (2) +requests are defined on file descriptors connected to either \fI/dev/random\fP +or \fI/dev/urandom\fP. All requests performed will interact with the input +entropy pool impacting both \fI/dev/random\fP and \fI/dev/urandom\fP. +The +.B CAP_SYS_ADMIN +capability is required for all requests except +.B RNDGETENTCNT. +.TP +.BR RNDGETENTCNT +Retrieve the entropy count of the input pool, the contents will be the same +as the +.I entropy_avail +file under proc. +The result will be stored in the int pointed to by the argument. +.TP +.BR RNDADDTOENTCNT +Increment or decrement the entropy count of the input pool by the value pointed +to by the argument. +.TP +.BR RNDGETPOOL +Removed in Linux 2.6.9. +.TP +.BR RNDADDENTROPY +Add some additional entropy to the input pool, incrementing the entropy count. +Unlike writing to \fI/dev/random\fP or \fI/dev/urandom\fP which only adds some +data but does not increment the entropy count. The following structure is used: +.IP +.IN +4n +.NF +struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.FI +.IN +.IP +Here +.I entropy_count +is the value added to (or subtracted from) from the entropy count. And +.I buf +is the buffer of size +.I buf_size +which gets added to the entropy pool. +.TP +.BR RNDZAPENTCNT ", " RNDCLEARPOOL +Zero the entropy count of all pools and add some system data (such as +wall clock) to the pools. .SH FILES /dev/random .br --1.7.10.4
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
On 2013/2/17 Elie De Brauwer wrote:
[...]
man4/random.4 and · line 258
Quoted 11 lines
+.IP
+.IN +4n
+.NFman4/random.4 +8
-0+struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.FI +.IN +.IP
[...]
Hello,
groff complains about undefined IN, NF and FI macros here, they must be lowercased.
IMHO it would be better to use the same formatting sequence found in this page, ie. drop .IP and write
[...] The following structure is used:
.nf
struct rand_pool_info {
int entropy_count;
int buf_size;
__u32 buf[0];
};.fi
Here [...]
Denis
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): CAMqf4EF8dtjaiJ6rDhN62YAMo9jCUuyZqtkhaE11F3fkof_1DQ-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Quoted 25 lines · D. Barbier
On 2013/2/17 Elie De Brauwer wrote:
[...]man4/random.4 and · line 258
Quoted 11 lines
+.IP
+.IN +4n
+.NFman4/random.4 +8
-0+struct rand_pool_info { + int entropy_count; + int buf_size; + __u32 buf[0]; +}; +.FI +.IN +.IP[...]
Hello,
groff complains about undefined IN, NF and FI macros here, they must be lowercased.
IMHO it would be better to use the same formatting sequence found in this page, ie. drop .IP and write[...] The following structure is used:
.nf
Quoted 8 lines
struct rand_pool_info { int entropy_count; int buf_size; __u32 buf[0]; };.fi
Here [...]
Thanks. Fixed as you suggest.
Cheers,
Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html