From d0d21dd5dd3937919dcf47c23e1094cc3be0e6c3 Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <nmav@redhat.com>
Date: Mar 28 2017 12:17:07 +0000
Subject: crypto primitives: added text on getrandom


---

diff --git a/en-US/Tasks-Cryptography.xml b/en-US/Tasks-Cryptography.xml
index 8e33007..fc13310 100644
--- a/en-US/Tasks-Cryptography.xml
+++ b/en-US/Tasks-Cryptography.xml
@@ -86,6 +86,9 @@
 	<para><function>os.urandom</function> in Python</para>
       </listitem>
       <listitem>
+	<para>The <function>getrandom</function> system call</para>
+      </listitem>
+      <listitem>
 	<para>Reading from the <filename>/dev/urandom</filename>
 	  character device</para>
       </listitem>
@@ -109,6 +112,21 @@
 	using these functions.
       </para>
     </important>
+    <important>
+      <title>Difficult to use API</title>
+      <para>
+	The <function>getrandom</function> system call has three-state
+	return values, hence requires careful error checking.
+      </para>
+      <para>
+	It was introduced in Linux kernel 3.17, but as of glibc 2.22 no API wrappers are
+	provided. As such one can only use it via the syscall interface
+	as <function>syscall(SYS_getrandom, (void*)dest, (size_t)size, (unsigned int)0)</function>.
+	For portable code targetting older kernel versions one has to check 
+	for the function being	available on run-time, and switch to another
+	facility if the running kernel doesn't support this call.
+      </para>
+    </important>
     <para>
       Other sources of randomness should be considered predictable.
     </para>