143 lines
5.5 KiB
XML
143 lines
5.5 KiB
XML
<?xml version='1.0' encoding='utf-8' ?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
]>
|
|
<chapter id="chap-Defensive_Coding-Tasks-Cryptography">
|
|
<title>Cryptography</title>
|
|
|
|
<section>
|
|
<title>Primitives</title>
|
|
<para>
|
|
Choosing from the following cryptographic primitives is
|
|
recommended:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>RSA with 2048 bit keys and OAEP or PSS
|
|
padding</para></listitem>
|
|
<listitem><para>AES-128 in CBC mode</para></listitem>
|
|
<listitem><para>AES-128 in GCM mode</para></listitem>
|
|
<listitem><para>AES-256 in CBC mode</para></listitem>
|
|
<listitem><para>AES-256 in GCM mode</para></listitem>
|
|
<listitem><para>SHA-256</para></listitem>
|
|
<listitem><para>HMAC-SHA-256</para></listitem>
|
|
<listitem><para>HMAC-SHA-1</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>3DES (triple DES, with two or three 56 bit keys),
|
|
but strongly discouraged</para></listitem>
|
|
<listitem><para>RC4 (but very, very strongly discouraged)</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
|
|
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"/>).
|
|
</para>
|
|
<para>
|
|
In particlar, when using AES in CBC mode, it is necessary to
|
|
add integrity checking by other means, preferably using
|
|
HMAC-SHA-256 and <emphasis>after</emphasis> encryption (that
|
|
is, on the encrypted cipher text). For AES in GCM mode,
|
|
correct construction of nonces is absolutely essential.
|
|
</para>
|
|
</important>
|
|
<!-- TODO: More algorithms are available in the NIST documents
|
|
linked from: http://wiki.brq.redhat.com/SecurityTechnologies/FIPS -->
|
|
</section>
|
|
|
|
<section>
|
|
<title id="sect-Defensive_Coding-Tasks-Cryptography-Randomness">Randomness</title>
|
|
<para>
|
|
The following facilities can be used to generate unpredictable
|
|
and non-repeating values. When these functions are used without
|
|
special safeguards, each individual random value should be at
|
|
least 12 bytes long.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><function>PK11_GenerateRandom</function> in the NSS library
|
|
(usable for high data rates)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><function>RAND_bytes</function> in the OpenSSL library
|
|
(usable for high data rates)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><function>gnutls_rnd</function> in GNUTLS, with
|
|
<literal>GNUTLS_RND_RANDOM</literal> as the first argument
|
|
(usable for high data rates)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><type>java.security.SecureRandom</type> in Java
|
|
(usable for high data rates)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><function>os.urandom</function> in Python</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <function>getrandom</function> system call since glibc 2.25</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <function>getentropy</function> call since glibc 2.25</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Reading from the <filename>/dev/urandom</filename>
|
|
character device</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
All these functions should be non-blocking, and they should not
|
|
wait until physical randomness becomes available. (Some
|
|
cryptography providers for Java can cause
|
|
<type>java.security.SecureRandom</type> to block, however.)
|
|
Those functions which do not obtain all bits directly from
|
|
<filename>/dev/urandom</filename> are suitable for high data
|
|
rates because they do not deplete the system-wide entropy pool.
|
|
</para>
|
|
<important>
|
|
<title>Difficult to use API</title>
|
|
<para>
|
|
Both <function>RAND_bytes</function> and
|
|
<function>PK11_GenerateRandom</function> have three-state
|
|
return values (with conflicting meanings). Careful error
|
|
checking is required. Please review the documentation when
|
|
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 before glibc 2.25 no API wrappers were
|
|
provided. As such one could 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 multiple 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>
|
|
<para>
|
|
Generating randomness for cryptographic keys in long-term use
|
|
may need different steps and is best left to cryptographic
|
|
libraries.
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|