README: update on security considerations & options for increased security
@@ -13,9 +13,10 @@ Contents
3. Recommendations
4. Package Content
5. Compilation
-6. Installation
-7. Disclaimer (ZUC, KASUMI, SNOW3G)
-8. Legal Disclaimer
+6. Security Considerations & Options for Increased Security
+7. Installation
+8. Disclaimer (ZUC, KASUMI, SNOW3G)
+9. Legal Disclaimer
1. Overview
@@ -309,20 +310,57 @@ Note: Building with debugging information is not advised for production use.
For more build options and their explanation run:
> gmake help
-6. Safety options
-=================
-
-There are three build options that can be enabled to increase safety in the code and
-protecting external functions from incorrect input data.
+6. Security Considerations & Options for Increased Security
+===========================================================
+
+Security Considerations
+-----------------------
+The security of a system that uses cryptography depends on the strength of
+the cryptographic algorithms as well as the strength of the keys.
+Cryptographic key strength is dependent on several factors, with some of the
+most important factors including the length of the key, the entropy of the key
+bits, and maintaining the secrecy of the key.
+
+The selection of an appropriate algorithm and mode of operation critically
+affects the security of a system. Appropriate selection criteria is beyond the
+scope of this document and should be determined based upon usage, appropriate
+standards and consultation with a cryptographic expert. This library includes some
+algorithms, which are considered cryptographically weak and are included only
+for legacy and interoperability reasons. See the "Recommendations" section for
+more details.
+
+Secure creation of key material is not a part of this library. This library
+assumes that cryptographic keys have been created using approved methods with
+an appropriate and secure entropy source. Users of this library are
+referred to NIST SP800-133 Revision 1, Recommendation for Cryptographic Key
+Generation, found at https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-133r1.pdf
+
+Even with the use of strong cryptographic algorithms and robustly generated
+keys, software implementations of cryptographic algorithms may be attacked
+at the implementation through cache-timing attacks, buffer-over-reads, and
+other software vulnerabilities. Counter-measures against these types of
+attacks are possible but require additional processing cycles. Whether a
+particular system should provide such counter-measures depends on the threats
+to that system, and cannot be determined by a general library such as this
+one. In order to provide the most flexible implementation, this library allows
+certain counter-measures to be enabled or disabled at compile time. These
+options are listed below as the "Options for Increased Security" and are
+enabled through various build flags.
+
+Options for Increased Security
+------------------------------
+There are three build options that can be enabled to increase safety in the
+code and help protect external functions from incorrect input data.
SAFE_DATA and SAFE_PARAM options are disabled by default, due to
-the performance impact associated to the extra code added.
+the potential performance impact associated to the extra code added.
SAFE_LOOKUP option is enabled by default, and can be disabled
by setting the parameter equal to "n" (e.g. make SAFE_LOOKUP=n).
These options (explained below) can be enabled when building the library,
by setting the parameter equal to "y" (e.g. make SAFE_DATA=y).
-No specific code has been added, and no specific validation or security tests have been performed
-to protect against or check for side-channel attacks.
+No specific code has been added, and no specific validation or security
+tests have been performed to help protect against or check for side-channel
+attacks.
SAFE_DATA
---------
@@ -349,6 +387,10 @@ Algorithms where these constant time functions are used are the following:
- SNOW3G: all architectures
- ZUC: all architectures
+If SAFE_LOOKUP is not enabled in the build (e.g. make SAFE_LOOKUP=n) then the
+algorithms listed above may be susceptible to timing attacks which could expose
+the cryptographic key.
+
7. Installation
===============
