From 455c70a40da9e734aea9c5d5f04c3ea561f6ac0b Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <nmav@redhat.com>
Date: Aug 26 2016 09:52:08 +0000
Subject: [PATCH 1/2] crypto primitives: updated section and listed recommended libraries


---

diff --git a/en-US/Tasks-Cryptography.xml b/en-US/Tasks-Cryptography.xml
index 1bafc2a..37312cd 100644
--- a/en-US/Tasks-Cryptography.xml
+++ b/en-US/Tasks-Cryptography.xml
@@ -12,35 +12,52 @@
     </para>
     <itemizedlist>
       <listitem><para>RSA with 2048 bit keys and OAEP</para></listitem>
-      <listitem><para>AES-128 in CBC mode</para></listitem>
+      <listitem><para>AES-256 in CBC mode</para></listitem>
       <listitem><para>SHA-256</para></listitem>
+      <listitem><para>SHA3-256</para></listitem>
       <listitem><para>HMAC-SHA-256</para></listitem>
       <listitem><para>HMAC-SHA-1</para></listitem>
     </itemizedlist>
     <para>
+      The following encryption primitives are safe to use when combined
+      with a method that guarrantees unique nonces (e.g., a counter or
+      ECB encryption with a 64-bit cipher).
+    </para>
+    <itemizedlist>
+      <listitem><para>AES-256 in GCM mode</para></listitem>
+      <listitem><para>CHACHA20-POLY1305</para></listitem>
+    </itemizedlist>
+    <para>
       Other cryptographic algorithms can be used if they are required
       for interoperability with existing software:
     </para>
     <itemizedlist>
       <listitem><para>RSA with key sizes larger than 1024
         and legacy padding</para></listitem>
-      <listitem><para>AES-192</para></listitem>
-      <listitem><para>AES-256</para></listitem>
-      <listitem><para>3DES (triple DES, with two or three 56 bit keys)</para></listitem>
-      <listitem><para>RC4 (but very, very strongly discouraged)</para></listitem>
+      <listitem><para>AES under CCM mode</para></listitem>
+      <listitem><para>3DES (triple DES, with three 56 bit keys) for short data transmission</para></listitem>
       <listitem><para>SHA-1</para></listitem>
       <listitem><para>HMAC-MD5</para></listitem>
     </itemizedlist>
     <important>
       <title>Important</title>
       <para>
-	These primitives are difficult to use in a secure way.  Custom
+	Cryptographic primitives are difficult to use in a secure way.  Custom
 	implementation of security protocols should be avoided.  For
 	protecting confidentiality and integrity of network
-	transmissions, TLS should be used (<xref
-	linkend="chap-Defensive_Coding-TLS"/>).
+	transmissions, TLS should be used (<xref linkend="chap-Defensive_Coding-TLS"/>).
       </para>
     </important>
+    <para>
+        For crypto primitives, we recommend to use one of the following cryptographic libraries.
+    </para>
+    <itemizedlist>
+      <listitem><para><ulink url="https://wiki.openssl.org/index.php/Libcrypto_API">OpenSSL's libcrypto</ulink></para></listitem>
+      <listitem><para>GNUTLS' provided primitives (<ulink url="http://www.gnutls.org/manual/gnutls.html#Using-GnuTLS-as-a-cryptographic-library">restricted to TLS-related crypto</ulink>)</para></listitem>
+      <listitem><para><ulink url="https://www.lysator.liu.se/~nisse/nettle/nettle.html">nettle crypto library</ulink></para></listitem>
+      <listitem><para><ulink url="https://gnupg.org/documentation/manuals/gcrypt/">GnuPG's crypto library (libgcrypt)</ulink></para></listitem>
+      <listitem><para>NSS' provided primitives via the PKCS#11 API</para></listitem>
+    </itemizedlist>
 <!-- TODO: More algorithms are available in the NIST documents
      linked from: http://wiki.brq.redhat.com/SecurityTechnologies/FIPS -->
   </section>

From 5a81b08d34117a433caa619f852a97b2c273f4ce Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <nmav@redhat.com>
Date: Aug 26 2016 09:52:11 +0000
Subject: [PATCH 2/2] crypto primitives: added text on getrandom


---

diff --git a/en-US/Tasks-Cryptography.xml b/en-US/Tasks-Cryptography.xml
index 37312cd..e4048e3 100644
--- a/en-US/Tasks-Cryptography.xml
+++ b/en-US/Tasks-Cryptography.xml
@@ -92,6 +92,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>
@@ -115,6 +118,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>