Skip to contentSkip to conversation

random.4: Document write and document the ioctl interface of /dev/random

PATCH In review Elie De Brauwer 3 participants 4 messages Feb 17, 2013 – Mar 15, 2013 2 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

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
index ed35fd9..d9be11e 100644
@@ -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

#2 lore raw

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 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

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.

---
 man4/random.4 |   63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)
man4/random.4 +62 -2
index ed35fd9..d9be11e 100644
@@ -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
#3 lore raw
In reply to a message not in the archive

On 2013/2/17 Elie De Brauwer wrote:
[...]

man4/random.4 and · line 258

Quoted 11 lines

+.IP
+.IN +4n
+.NF

man4/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

#5 lore raw
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
+.NF

man4/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