From faac8c3b0e226dcc0e598321b02f0cb9a920d722 Mon Sep 17 00:00:00 2001
From: Pablo de Lara <pablo.de.lara.guarch@intel.com>
Date: Thu, 23 May 2024 11:12:40 +0100
Subject: [PATCH] FIPS: add documentation on new FIPS mode

Signed-off-by: Pablo de Lara <pablo.de.lara.guarch@intel.com>
---
 Doxyfile  |  1 +
 FIPS.md   | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  1 +
 make.inc  |  2 +-
 4 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 FIPS.md

diff --git a/Doxyfile b/Doxyfile
index f2defb1..d1d431d 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -14,6 +14,7 @@ INPUT                  = isa-l_crypto.h \
 			 README.md \
 			 CONTRIBUTING.md \
 			 SECURITY.md \
+			 FIPS.md \
 			 Release_notes.txt
 
 EXCLUDE                = include/test.h include/memcpy_inline.h include/intrinreg.h include/endian_helper.h
diff --git a/FIPS.md b/FIPS.md
new file mode 100644
index 0000000..f103440
--- /dev/null
+++ b/FIPS.md
@@ -0,0 +1,70 @@
+# FIPS Mode on ISA-L Crypto
+
+## Compilation
+
+FIPS mode is disabled in the library by default.
+In order to enable it, the library needs to be compiled as follows:
+
+- Using autotools:
+
+```
+    ./autogen.sh
+    ./configure --enable-fips-mode
+    make
+```
+
+- Standard makefile:
+
+```
+    make -f Makefile.unx FIPS_MODE=y
+```
+
+- Windows Makefile:
+
+```
+    make /f Makefile.nmake FIPS_MODE=y
+```
+
+## Covered API by this mode
+
+Only the "isal_" prefixed API is in the scope of this mode
+(e.g. `isal_aes_cbc_enc_128()`).
+
+isal_crypto.h or isal_crypto_api.h must be included in the application/framework
+calling this API.
+
+After the first call on this API, crypto self tests will be run.
+If any of the tests fail, no crypto operation will be performed
+and the API will return ISAL_CRYPTO_ERR_SELF_TEST.
+Subsequent calls will return this error too.
+
+The self tests can also be run at the application level by
+calling explicitly `isal_self_tests()`.
+
+The validation of self tests is executed only once, either by invoking
+the `isal_self_tests()` function or by invoking a covered crypto function,
+such as `isal_aes_cbc_enc_128()`. After the tests have been run once,
+they will not be executed again, and subsequent API calls will use the previous test result.
+
+If an algorithm is not NIST approved (e.g. SM3), calling the
+crypto function will return ISAL_CRYPTO_ERR_FIPS_INVALID_ALGO.
+
+## Example of usage
+
+```
+#include <isal_crypto_api.h>
+#include <aes_cbc.h>
+
+...
+
+int ret = isal_aes_cbc_enc_128(pt, iv, expkey_enc, ct, pt_len);
+if (ret != 0)
+        exit(1);
+
+```
+
+## Considerations
+
+- This library does not check for uniqueness on AES-GCM key/IV pair.
+- FIPS mode is supported from ISA-L Crypto version v2.25.
+- FIPS mode has only been tested on Intel x86 architecture.
diff --git a/README.md b/README.md
index 71bff05..29c1cd5 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Also see:
   isa-l crypto.
 * [Contributing](CONTRIBUTING.md).
 * [Security Policy](SECURITY.md).
+* [FIPS Mode](FIPS.md).
 
 Building ISA-L
 --------------
diff --git a/make.inc b/make.inc
index c0c8ab9..0f52f51 100644
--- a/make.inc
+++ b/make.inc
@@ -366,5 +366,5 @@ CS_IGNORE_WORDS ?= iinclude,struc,fo,ue,od,ba,padd,hist,unx,sav,datas
 spellcheck:
 	$(CODESPELL) -d -L $(CS_IGNORE_WORDS) \
 	-S "*.obj,*.o,*.a,*.so,*.lib,*~,*.so,*.so.*,*.d" \
-	./aes ./examples/saturation_test ./include ./md5_mb ./mh_sha1 ./mh_sha1_murmur3_x86_128 ./mh_sha256 ./rolling_hash ./sha1_mb ./sha256_mb ./sha512_mb ./sm3_mb ./tests ./fips ./misc README.md SECURITY.md CONTRIBUTING.md \
+	./aes ./examples/saturation_test ./include ./md5_mb ./mh_sha1 ./mh_sha1_murmur3_x86_128 ./mh_sha256 ./rolling_hash ./sha1_mb ./sha256_mb ./sha512_mb ./sm3_mb ./tests ./fips ./misc README.md SECURITY.md CONTRIBUTING.md FIPS.md \
 	Makefile.unx Makefile.nmake Release_notes.txt LICENSE $(CS_EXTRA_OPTS)