132 lines
3.2 KiB
Text
132 lines
3.2 KiB
Text
|
|
:experimental:
|
|
|
|
[[chap-Defensive_Coding-Tasks-Cryptography]]
|
|
=== Cryptography
|
|
|
|
==== Primitives
|
|
|
|
Choosing from the following cryptographic primitives is
|
|
recommended:
|
|
|
|
* RSA with 2048-bit keys and OAEP or PSS
|
|
padding
|
|
|
|
* AES-128 in CBC mode
|
|
|
|
* AES-128 in GCM mode
|
|
|
|
* AES-256 in CBC mode
|
|
|
|
* AES-256 in GCM mode
|
|
|
|
* SHA-256
|
|
|
|
* HMAC-SHA-256
|
|
|
|
* HMAC-SHA-1
|
|
|
|
Other cryptographic algorithms can be used if they are required
|
|
for interoperability with existing software:
|
|
|
|
* RSA with key sizes larger than 1024
|
|
and legacy padding
|
|
|
|
* AES-192
|
|
|
|
* 3DES (triple DES, with two or three 56-bit keys),
|
|
but strongly discouraged
|
|
|
|
* RC4 (but very, very strongly discouraged)
|
|
|
|
* SHA-1
|
|
|
|
* HMAC-MD5
|
|
|
|
.Important
|
|
[IMPORTANT]
|
|
====
|
|
|
|
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 (<<chap-Defensive_Coding-TLS>>).
|
|
|
|
In particular, when using AES in CBC mode, it is necessary to
|
|
add integrity checking by other means, preferably using
|
|
HMAC-SHA-256 and *after* encryption (that
|
|
is, on the encrypted cipher text). For AES in GCM mode,
|
|
correct construction of nonces is absolutely essential.
|
|
|
|
====
|
|
|
|
==== Randomness
|
|
|
|
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.
|
|
|
|
* `PK11_GenerateRandom` in the NSS library
|
|
(usable for high data rates)
|
|
|
|
* `RAND_bytes` in the OpenSSL library
|
|
(usable for high data rates)
|
|
|
|
* `gnutls_rnd` in GNUTLS, with
|
|
`GNUTLS_RND_RANDOM` as the first argument
|
|
(usable for high data rates)
|
|
|
|
* `java.security.SecureRandom` in Java
|
|
(usable for high data rates)
|
|
|
|
* `os.urandom` in Python
|
|
|
|
* The `getrandom` system call since glibc 2.25
|
|
|
|
* The `getentropy` call since glibc 2.25
|
|
|
|
* Reading from the `/dev/urandom`
|
|
character device
|
|
|
|
All these functions should be non-blocking, and they should not
|
|
wait until physical randomness becomes available. (Some
|
|
cryptography providers for Java can cause
|
|
`java.security.SecureRandom` to block, however.)
|
|
Those functions which do not obtain all bits directly from
|
|
`/dev/urandom` are suitable for high data
|
|
rates because they do not deplete the system-wide entropy pool.
|
|
|
|
.Difficult to use API
|
|
[IMPORTANT]
|
|
====
|
|
|
|
Both `RAND_bytes` and
|
|
`PK11_GenerateRandom` have three-state
|
|
return values (with conflicting meanings). Careful error
|
|
checking is required. Please review the documentation when
|
|
using these functions.
|
|
|
|
====
|
|
|
|
.Difficult to use API
|
|
[IMPORTANT]
|
|
====
|
|
|
|
The `getrandom` system call has three-state
|
|
return values, hence requires careful error checking.
|
|
|
|
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 `syscall(SYS_getrandom, (void*)dest, (size_t)size, (unsigned int)0)`.
|
|
For portable code targetting multiple kernel versions one has to check
|
|
for the function beingavailable on run-time, and switch to another
|
|
facility if the running kernel does not support this call.
|
|
|
|
====
|
|
|
|
Other sources of randomness should be considered predictable.
|
|
|
|
Generating randomness for cryptographic keys in long-term use
|
|
may need different steps and is best left to cryptographic
|
|
libraries.
|