diff --git a/.gitignore b/.gitignore index 7c4f0f6cd5f0d2e3e45eea2fde9d2e1aa55affb4..24e1c5d1970968679002f804ad7eb4132331094c 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ job_api_fuzz_test* *_lnk.def TAGS acvp_app +test/wycheproof/wycheproof +!wycheproof.c diff --git a/Makefile b/Makefile index e4a298d5ba2bd255922215ccbbd168d5ef60be2b..9da44c69c48686061ad500f17fb14406ff6c1efb 100644 --- a/Makefile +++ b/Makefile @@ -30,16 +30,21 @@ all: $(MAKE) -C lib $(MAKE) -C test +ifeq ($(ARCH),x86_64) + $(MAKE) -C test/wycheproof +endif $(MAKE) -C perf clean: $(MAKE) -C lib clean $(MAKE) -C test clean + $(MAKE) -C test/wycheproof clean $(MAKE) -C perf clean style: $(MAKE) -C lib style $(MAKE) -C test style + $(MAKE) -C test/wycheproof style $(MAKE) -C perf style install: @@ -54,9 +59,6 @@ help: doxy: $(MAKE) -C lib doxy -README: README.md - pandoc -f markdown -t plain $< -o $@ - .PHONY: TAGS TAGS: find ./ -name "*.[ch]" -print | etags - @@ -72,14 +74,14 @@ TAGS: # -I FILE -- File containing words to be ignored # CODESPELL ?= codespell -CS_IGNORE_WORDS ?= iinclude,struc,fo,ue,od,ba +CS_IGNORE_WORDS ?= iinclude,struc,fo,ue,od,ba,padd .PHONY: spellcheck spellcheck: $(CODESPELL) -d -L $(CS_IGNORE_WORDS) \ -S "*.obj,*.o,*.a,*.so,*.lib,*~,*.so,*.so.*,*.d,ipsec_perf" \ -S "ipsec_MB_testapp,ipsec_xvalid_test" \ - ./lib ./perf ./test README README.md SECURITY.md CONTRIBUTING \ + ./lib ./perf ./test README.md SECURITY.md CONTRIBUTING \ Makefile win_x64.mak ReleaseNotes.txt LICENSE $(CS_EXTRA_OPTS) # cppcheck analysis check diff --git a/README.md b/README.md index 900fe6f0e9d1b20ef938bd9e762a5dabbb3772da..b187d42cec3c4d5909c6ae29e2308351f954b23b 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,9 @@ Table 1. List of supported cipher algorithms and their implementations. | AES128-CTR | N | Y by8 | Y by8 | N | N | Y by16 | N | | AES192-CTR | N | Y by8 | Y by8 | N | N | Y by16 | N | | AES256-CTR | N | Y by8 | Y by8 | N | N | Y by16 | N | -| AES128-ECB | N | Y by4 | Y by4 | N | N | N | N | -| AES192-ECB | N | Y by4 | Y by4 | N | N | N | N | -| AES256-ECB | N | Y by4 | Y by4 | N | N | N | N | +| AES128-ECB | N | Y(1) | Y by8 | Y(10) | N | Y by16 | N | +| AES192-ECB | N | Y(1) | Y by8 | Y(10) | N | Y by16 | N | +| AES256-ECB | N | Y(1) | Y by8 | Y(10) | N | Y by16 | N | | NULL | Y | N | N | N | N | N | N | | AES128-DOCSIS | N | Y(2) | Y(4) | N | Y(7) | Y(8) | N | | AES256-DOCSIS | N | Y(2) | Y(4) | N | Y(7) | Y(8) | N | @@ -79,7 +79,7 @@ Table 1. List of supported cipher algorithms and their implementations. | KASUMI-F8 | Y | N | N | N | N | N | N | | ZUC-EEA3 | N | Y x4 | Y x4 | Y x8 | Y x16 | Y x16 | Y x4 | | ZUC-EEA3-256 | N | Y x4 | Y x4 | Y x8 | Y x16 | Y x16 | Y x4 | -| SNOW3G-UEA2 | N | Y | Y | Y | Y x16 | Y x16 | Y | +| SNOW3G-UEA2 | N | Y x4 | Y | Y | Y x16 | Y x16 | Y | | AES128-CBCS(9) | N | Y(1) | Y(3) | N | N | Y(6) | N | | Chacha20 | N | Y | Y | Y | Y | N | N | | Chacha20 AEAD | N | Y | Y | Y | Y | N | N | @@ -97,6 +97,8 @@ Notes: (7) - same as AES128-CBC for AVX, combines cipher and CRC32 (8) - decryption is by16 and encryption is x16 (9) - currently 1:9 crypt:skip pattern supported +(10) - by default, decryption and encryption are AVX by8. + On CPUs supporting VAES, decryption and encryption are AVX2-VAES by16. Legend: ` byY` - single buffer Y blocks at a time @@ -122,6 +124,11 @@ Table 2. List of supported integrity algorithms and their implementations. | HMAC-SHA2-256_128 | N | Y(2)x4 | Y x4 | Y x8 | Y x16 | N | N | | HMAC-SHA2-384_192 | N | Y x2 | Y x2 | Y x4 | Y x8 | N | N | | HMAC-SHA2-512_256 | N | Y x2 | Y x2 | Y x4 | Y x8 | N | N | +| SHA1 | N | Y(2)x4 | Y x4 | Y x8 | Y x16 | N | N | +| SHA2-224 | N | Y(2)x4 | Y x4 | Y x8 | Y x16 | N | N | +| SHA2-256 | N | Y(2)x4 | Y x4 | Y x8 | Y x16 | N | N | +| SHA2-384 | N | Y x2 | Y x2 | Y x4 | Y x8 | N | N | +| SHA2-512 | N | Y x2 | Y x2 | Y x4 | Y x8 | N | N | | AES128-GMAC | N | Y by8 | Y by8 | Y by8 | Y by8 | Y by48 | N | | AES192-GMAC | N | Y by8 | Y by8 | Y by8 | Y by8 | Y by48 | N | | AES256-GMAC | N | Y by8 | Y by8 | Y by8 | Y by8 | Y by48 | N | @@ -159,8 +166,8 @@ Notes: - CRC8: WIMAX OFDMA HCS - CRC7: FP header - CRC6: IUUP header -(7) - used only with PON-AES128-CTR cipher -(8) - x16 for init keystream generation, then by32 +(7) - used only with PON-AES128-CTR cipher +(8) - x4/x16 for init keystream generation, then by4/by32 Legend: ` byY`- single buffer Y blocks at a time @@ -246,17 +253,19 @@ Legacy or to be avoided algorithms listed in the table below are implemented in the library in order to support legacy applications. Please use corresponding alternative algorithms instead. ``` -+-------------------------------------------------------------+ -| # | Algorithm | Recommendation | Alternative | -|---+--------------------+----------------+-------------------| -| 1 | DES encryption | Avoid | AES encryption | -|---+--------------------+----------------+-------------------| -| 2 | 3DES encryption | Avoid | AES encryption | -|---+--------------------+----------------+-------------------| -| 3 | HMAC-MD5 integrity | Legacy | HMAC-SHA1 | -|---+--------------------+----------------+-------------------| -| 4 | AES-ECB encryption | Avoid | AES-CBC, AES-CNTR | -+-------------------------------------------------------------+ ++--------------------------------------------------------------+ +| # | Algorithm | Recommendation | Alternative | +|---+---------------------+----------------+-------------------| +| 1 | DES encryption | Avoid | AES encryption | +|---+---------------------+----------------+-------------------| +| 2 | 3DES encryption | Avoid | AES encryption | +|---+---------------------+----------------+-------------------| +| 3 | HMAC-MD5 integrity | Legacy | HMAC-SHA256 | +|---+---------------------+----------------+-------------------| +| 4 | AES-ECB encryption | Avoid | AES-CBC, AES-CNTR | +|---+---------------------+----------------+-------------------| +| 3 | HMAC-SHA1 integrity | Avoid | HMAC-SHA256 | ++--------------------------------------------------------------+ ``` Multi-Buffer Crypto for IPsec Library depends on C library and it is recommended to use its latest version. @@ -282,8 +291,15 @@ security updates. **Note:** There is just one branch used in the project. All development is done on the main branch. +5\. Documentation +=============== + +Full documentation can be found at: https://intel.github.io/intel-ipsec-mb + +To generate documentation locally, run: +`> make doxy` -5\. Compilation +6\. Compilation =============== Linux (64-bit only) @@ -308,8 +324,8 @@ or Build with debugging information: `> make DEBUG=y` -Build with AESNI emulation support (disabled by default): - > make AESNI_EMU=y +Build with AESNI emulation support (disabled by default): +`> make AESNI_EMU=y` **Note:** Building with debugging information is not advised for production use. @@ -343,7 +359,8 @@ Build without safety features: - SAFE_DATA clears sensitive information stored temporarily on stack, registers or internal data structures - SAFE_PARAM adds extra checks on input parameters - SAFE_LOOKUP uses constant-time lookups (enabled by default) -- SAFE_OPTIONS additional option to disable all safe options. disable to turn off SAFE_DATA, SAFE_PARAM, SAFE_LOOKUP (enabled by default) +- SAFE_OPTIONS additional option to disable all safe options. Enabled by default. + Disable to turn off: SAFE_DATA, SAFE_PARAM and SAFE_LOOKUP. `> nmake /f win_x64.mak SAFE_DATA=n SAFE_PARAM=n` `> nmake /f win_x64.mak SAFE_OPTIONS=n` @@ -351,8 +368,8 @@ Build without safety features: Build with debugging information: `> nmake /f win_x64.mak DEBUG=y` -Build with AESNI emulation support (disabled by default): - > nmake /f win_x64.mak AESNI_EMU=y +Build with AESNI emulation support (disabled by default): +`> nmake /f win_x64.mak AESNI_EMU=y` **Note:** Building with debugging information is not advised for production use. @@ -413,7 +430,7 @@ Build with debugging information: For more build options and their explanation run: `> gmake help` -6\. Security Considerations & Options for Increased Security +7\. Security Considerations & Options for Increased Security ============================================================ ### Security Considerations @@ -483,9 +500,10 @@ algorithms listed above may be susceptible to timing attacks which could expose the cryptographic key. ### SAFE_OPTIONS -SAFE_OPTIONS is a parameter that can be used to disable -all other safe options(SAFE_DATA, SAFE_PARAM, SAFE_LOOKUP). By just -setting this parameter (e.g. SAFE_OPTIONS=n). +SAFE_OPTIONS is a parameter that can be used to disable/enable +all supported safe options (i.e. SAFE_DATA, SAFE_PARAM, SAFE_LOOKUP). +It is set to `y` by default and all safe options are enabled. +`SAFE_OPTIONS=n` disables all safe options. ### Security API **Force clearing/zeroing of memory** @@ -502,7 +520,7 @@ The library GCM and GMAC implementation provides flexibility as to tag size sele As explained in [NIST Special Publication 800-38D](https://csrc.nist.gov/publications/detail/sp/800-38d/final) section 5.2.1.2 and Appendix C, using tag sizes shorter than 96 bits can be insecure. Please refer to the aforementioned sections to understand the details, trade offs and mitigations of using shorter tag sizes. -7\. Installation +8\. Installation ================ Linux (64-bit only) @@ -559,7 +577,7 @@ If there is no need to run ldconfig at install stage please use NOLDCONFIG=y opt If library was compiled as an archive (not a default option) then install it using SHARED=n option: `> sudo gmake install SHARED=n` -8\. Backwards compatibility +9\. Backwards compatibility =========================== In version 0.54, some symbols have been renamed to avoid too generic names (such as cipher modes or @@ -575,7 +593,7 @@ For applications which face symbol conflicts due to these old generic names, they should be compiled with the flag -DNO_COMPAT_IMB_API_053, which will not export the old symbols. -9\. Disclaimer (ZUC, KASUMI, SNOW3G) +10\. Disclaimer (ZUC, KASUMI, SNOW3G) ==================================== Please note that cryptographic material, such as ciphering algorithms, may be diff --git a/docs/index.html b/docs/index.html index 61b40c7a6007131278cef39b63b85e7564334b57..867ea8d08482b147735604bf5a0708c133bdbbf5 100644 --- a/docs/index.html +++ b/docs/index.html @@ -14,6 +14,6 @@