1*faac8c3bSPablo de Lara# FIPS Mode on ISA-L Crypto 2*faac8c3bSPablo de Lara 3*faac8c3bSPablo de Lara## Compilation 4*faac8c3bSPablo de Lara 5*faac8c3bSPablo de LaraFIPS mode is disabled in the library by default. 6*faac8c3bSPablo de LaraIn order to enable it, the library needs to be compiled as follows: 7*faac8c3bSPablo de Lara 8*faac8c3bSPablo de Lara- Using autotools: 9*faac8c3bSPablo de Lara 10*faac8c3bSPablo de Lara``` 11*faac8c3bSPablo de Lara ./autogen.sh 12*faac8c3bSPablo de Lara ./configure --enable-fips-mode 13*faac8c3bSPablo de Lara make 14*faac8c3bSPablo de Lara``` 15*faac8c3bSPablo de Lara 16*faac8c3bSPablo de Lara- Standard makefile: 17*faac8c3bSPablo de Lara 18*faac8c3bSPablo de Lara``` 19*faac8c3bSPablo de Lara make -f Makefile.unx FIPS_MODE=y 20*faac8c3bSPablo de Lara``` 21*faac8c3bSPablo de Lara 22*faac8c3bSPablo de Lara- Windows Makefile: 23*faac8c3bSPablo de Lara 24*faac8c3bSPablo de Lara``` 25*faac8c3bSPablo de Lara make /f Makefile.nmake FIPS_MODE=y 26*faac8c3bSPablo de Lara``` 27*faac8c3bSPablo de Lara 28*faac8c3bSPablo de Lara## Covered API by this mode 29*faac8c3bSPablo de Lara 30*faac8c3bSPablo de LaraOnly the "isal_" prefixed API is in the scope of this mode 31*faac8c3bSPablo de Lara(e.g. `isal_aes_cbc_enc_128()`). 32*faac8c3bSPablo de Lara 33*faac8c3bSPablo de Laraisal_crypto.h or isal_crypto_api.h must be included in the application/framework 34*faac8c3bSPablo de Laracalling this API. 35*faac8c3bSPablo de Lara 36*faac8c3bSPablo de LaraAfter the first call on this API, crypto self tests will be run. 37*faac8c3bSPablo de LaraIf any of the tests fail, no crypto operation will be performed 38*faac8c3bSPablo de Laraand the API will return ISAL_CRYPTO_ERR_SELF_TEST. 39*faac8c3bSPablo de LaraSubsequent calls will return this error too. 40*faac8c3bSPablo de Lara 41*faac8c3bSPablo de LaraThe self tests can also be run at the application level by 42*faac8c3bSPablo de Laracalling explicitly `isal_self_tests()`. 43*faac8c3bSPablo de Lara 44*faac8c3bSPablo de LaraThe validation of self tests is executed only once, either by invoking 45*faac8c3bSPablo de Larathe `isal_self_tests()` function or by invoking a covered crypto function, 46*faac8c3bSPablo de Larasuch as `isal_aes_cbc_enc_128()`. After the tests have been run once, 47*faac8c3bSPablo de Larathey will not be executed again, and subsequent API calls will use the previous test result. 48*faac8c3bSPablo de Lara 49*faac8c3bSPablo de LaraIf an algorithm is not NIST approved (e.g. SM3), calling the 50*faac8c3bSPablo de Laracrypto function will return ISAL_CRYPTO_ERR_FIPS_INVALID_ALGO. 51*faac8c3bSPablo de Lara 52*faac8c3bSPablo de Lara## Example of usage 53*faac8c3bSPablo de Lara 54*faac8c3bSPablo de Lara``` 55*faac8c3bSPablo de Lara#include <isal_crypto_api.h> 56*faac8c3bSPablo de Lara#include <aes_cbc.h> 57*faac8c3bSPablo de Lara 58*faac8c3bSPablo de Lara... 59*faac8c3bSPablo de Lara 60*faac8c3bSPablo de Laraint ret = isal_aes_cbc_enc_128(pt, iv, expkey_enc, ct, pt_len); 61*faac8c3bSPablo de Laraif (ret != 0) 62*faac8c3bSPablo de Lara exit(1); 63*faac8c3bSPablo de Lara 64*faac8c3bSPablo de Lara``` 65*faac8c3bSPablo de Lara 66*faac8c3bSPablo de Lara## Considerations 67*faac8c3bSPablo de Lara 68*faac8c3bSPablo de Lara- This library does not check for uniqueness on AES-GCM key/IV pair. 69*faac8c3bSPablo de Lara- FIPS mode is supported from ISA-L Crypto version v2.25. 70*faac8c3bSPablo de Lara- FIPS mode has only been tested on Intel x86 architecture. 71