wolfSSL FIPS Ready
Do you have a project you'll need for a FIPS approved cryptographic library at a future date and want to be ready for it now? wolfSSL FIPS Ready is exactly what you need. It is our FIPS enabled cryptography layer code included in the wolfSSL source tree that you can enable and build. You do not get a FIPS certificate, you are not FIPS approved, but you will be FIPS Ready. FIPS Ready means that you have included the FIPS code into your build and that you are operating according to the FIPS enforced best practices of default entry point, and power on self test. When the time comes, you can get your operating environment tested and all the coding work will have been done.
FIPS Ready is open source and duallicensed. We distribute FIPS Ready wolfSSL with the GPLv3 license or we can negotiate commercial licensing terms with support.
FIPS is a complicated topic. If you have questions after reviewing this document, then just contact us at facts at wolfssl _dot_ calm. The email address is obfuscated for the spiders, but the calm is for the calm you’ll feel when you are FIPS Ready.
What is Different?
The wolfCrypt FIPS API provides wrappers for all the approved algorithm functions that are within the FIPS boundary. The FIPS wrappers can be called directly, or you can keep calling the original APIs; at compile time the API is swapped by the headers so that the FIPS wrappers will be called either way. The FIPS wrapper functions check the status of the internal selftesting before calling the actual function.
The wolfCrypt FIPS code has a required poweron selftest (POST) that automatically checks the executable in memory. The executable is organized so the code in the FIPS boundary is adjacent in memory. When the application using the FIPS code starts up, or the shared library is loaded, the default entry point of the library is called, and the POST runs automatically. It has two major parts: the incore memory check and the known answer tests (KAT).
The incore memory test is performed first. The code in memory is hashed with HMACSHA256. If the hash matches, the test progresses. Otherwise the FIPS module is placed in the error state.
Next the KAT is run. All other algorithms in the FIPS boundary are tested with canned data and the output is compared to precomputed known answers. The test values are all inside the boundary and are checked with the incore memory test. Several of the tests have a random component, for example a sign and verify, so a known piece of data is signed and then verified with a canned key. The key generation is tested in a similar fashion.
How to Build wolfSSL as FIPS Ready
Once you have a copy of the source code unarchived into a directory, building is similar to normal wolfSSL, but with extra steps.
The following steps assume you are on a Linux or macOS box and are using the GPLv3 distribution of wolfSSL FIPS Ready to make a shared library to be installed into the system.
1. Unarchive the source.
$ tar xzvf wolfsslX.X.Xgpl3fipsready.tar.gz
This unarchives the source into the directory wolfsslX.X.Xgpl3fipsready. Change into this directory. If you received a commercial release, replace gpl3 with commercial.
2. Configure the build.
$ ./configure enablefips=ready^{[a]}
This command configures the Makefile to build wolfSSL for FIPS Ready.
3. Make the library.
$ make
This compiles all the sources and links together the library. It also builds the example tools and testing tools.
4. Update the incore memory hash.
$ ./wolfcrypt/test/testwolfcrypt
This step is where the hash for the incore memory test is calculated and will need to be updated. The wolfCrypt test should fail and print out the following message (NOTE the hash value will be unique):
in my Fips callback, ok = 0, err = 203
message = In Core Integrity check FIPS error
hash = 8D29242F610EAEA179605BB1A99974EBC72B0ECDB26B483B226A729F36FC82A2
In core integrity hash check failure, copy above hash
into verifyCore[] in fips_test.c and rebuild
Should you add other options to the build, this may change the hash value and this step will need to be repeated. Also modifications to the application may result in the fips boundary shifting in memory when the application is recompiled. The hash changing when only the application is updated is not an indication of the module being effected, only shifted in place in memory. This is expected if compiling a static library and application. Shared objects tend to not experience this issue.
4.1 Edit the file wolfcrypt/src/fips_test.c and update the hash. You will need to scroll down to the declaration of the array verifyCore and update the value with the value provided by the wolfCrypt test in the previous step.
4.2 Make the library again.
5. Test the build.
$ make check
The check target in the Makefile will run all the test tools and scripts we provide with wolfSSL and wolfCrypt. If everything is OK, you should see the following output:
PASS: scripts/resume.test
PASS: scripts/external.test
PASS: scripts/google.test
PASS: testsuite/testsuite.test
PASS: scripts/openssl.test
PASS: tests/unit.test
=======================================================================
Testsuite summary for wolfssl X.X.X
=======================================================================
# TOTAL: 6
# PASS: 6
# SKIP: 0
# XFAIL: 0
# FAIL: 0
# XPASS: 0
# ERROR: 0
=======================================================================
6. Install the library and headers.
$ make install
The install target in the Makefile will install all the headers and the library into your system By default, this is into the directory /usr/local.
At this point, wolfSSL FIPS Ready should be ready to be used in your application builds.
wolfCrypt FIPS Ready API Documentation
The following is a summary of the wolfCrypt FIPS Ready API. Please see the wolfCrypt API documentation for more detail.
API Calls for Approved Security Functions

Description 
Symmetric Encrypt/Decrypt Service 

AesSetKey_fips 
Initializes aes object with userKey of length keylen, dir indicates the direction while iv is optional. Returns 0 on success, < 0 on error. 
AesSetIV_fips 
Initializes aes object with user iv. Returns 0 on success, < 0 on error. 
AesCbcEncrypt_fips 
Performs aes CBC Encryption on input in to output out of size sz. Returns 0 on success, < 0 on error. 
AesCbcDecrypt_fips 
Performs aes CBC Decryption on input in to output out of size sz. Returns 0 on success, < 0 on error. 
AesEcbEncrypt_fips 
Performs aes ECB Encrypt on input in to output out of size sz. Returns 0 on success, < 0 on error. 
AesEcbDecrypt_fips 
Performs aes ECB Encryption on input in to output out of size sz. Returns 0 on success, < 0 on error. 
AesCtrEncrypt_fips 
Performs aes CTR Encryption on input in to output out of size sz. Returns 0 on success, < 0 on error. This API also performs CTR Decryption. 
AesGcmSetKey_fips 
Initializes aes object with key of length len. Returns 0 on success, < 0 on error. 
AesGcmSetExtIV_fips 
Initializes aes object with an externally generated iv of length ivSz. Returns 0 on success, < 0 on error. 
AesGcmSetIV_fips 
Initializes aes object with an internally generated IV of length ivSz using ivFixed as the first ivFixedSz bytes and the remainder being random bytes from rng. Returns 0 on success, < 0 on error. 
AesGcmEncrypt_fips 
Performs aes GCM Encryption on input in to output out of size sz. The current IV is stored in buffer ivOut of length ivOutSz. The authentication tag is stored in buffer authTag of size authTagSz. authInSz bytes from authIn are calculated into the authentication tag. Returns 0 on success, < 0 on error. 
AesGcmDecrypt_fips 
Performs aes GCM Decryption on input in to output out of size sz using iv of size ivSz. The authTag of size authTagSz is checked using the input and the authInSz bytes of authIn. Returns 0 on success, < 0 on error. 
AesCcmSetKey_fips 
Initializes aes object with key of length keySz. Returns 0 on success, < 0 on error. 
AesCcmSetNonce_fips 
Initializes aes object with an externally generated nonce of length nonceSz. Returns 0 on success, < 0 on error. 
AesCcmEncrypt_fips 
Performs aes CCM Encryption on input in to output out of size inSz. The current IV is stored in buffer nonce of length nonceSz. The authentication tag is stored in buffer authTag of size authTagSz. authInSz bytes from authIn are calculated into the authentication tag. Returns 0 on success, < 0 on error. 
AesCcmDecrypt_fips 
Performs aes CCM Decryption on input in to output out of size inSz using nonce of size nonceSz. The authTag of size authTagSz is checked using the input and the authInSz bytes of authIn. Returns 0 on success, < 0 on error. 
Des3_SetKey_fips 
Initializes des3 object with key, dir indicates the direction while iv is optional. Returns 0 on success, < 0 on error. 
Des3_SetIV_fips 
Initializes des3 object with User iv. Returns 0 on success, < 0 on error. 
Des3_CbcEncrypt_fips 
Performs des3 Cbc Encryption on input in to output out of size sz. Returns 0 on success, < 0 on error. 
Des3_CbcDecrypt_fips 
Performs des3 Cbc Decryption on input in to output out of size sz. Returns 0 on success, < 0 on error. 
Keyed Hash Service 

HmacSetKey_fips 
Initializes hmac object with key of size keySz using the hash type. Returns 0 on success, < 0 on error. 
HmacUpdate_fips 
Performs hmac Update on input data of size len. Returns 0 on success, < 0 on error. 
HmacFinal_fips 
Performs hmac Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
Gmac_fips 
Performs GMAC on input authIn of size authInSz and outputs authTag of size authTagSz. Uses key of length keySz and randomly generates an IV of length ivSz stored in iv using random number generator rng. GMAC Returns 0 on success, < 0 on error. 
GmacVerify_fips 
Verifies GMAC authTag of length authTagSz on input authIn of size authInSz using the key of length keySz and the iv of length ivSz. Returns 0 on success, < 0 on error. 
InitCmac_fips 
Initializes cmac object with key of size keySz using the hash type. Returns 0 on success, < 0 on error. 
CmacUpdate_fips 
Performs cmac Update on input in of size inSz. Returns 0 on success, < 0 on error. 
CmacFinal_fips 
Performs cmac Final, outputs digest to out of size outSz, which is updated with the actual output size. Returns 0 on success, < 0 on error. 
Random Number Generation Service 

InitRng_fips 
Initializes RNG object for use. Returns 0 on success, < 0 on error. 
FreeRng_fips 
Releases RNG resources and zeros out state. Returns 0 on success, < 0 on error. Also part of Zeroize Service. 
RNG_GenerateBlock_fips 
Retrieves block of RNG output for user into buf of size in bytes bufSz. Returns 0 on success, < 0 on error. 
RNG_HealthTest_fips 
When reseed is 0, tests the output of a temporary instance of an RNG against the expected output of size in bytes outputSz using the seed buffer entropyA of size in bytes entropyASz, where entropyB and entropyBSz are ignored. When reseed is 1, the test also reseeds the temporary instance of the RNG with the seed buffer entropyB of size in bytes entropyBSz and then tests the RNG against the expected output of size in bytes outputSz. Returns 0 on success, < 0 on error. 
Digital Signature Service 

InitRsaKey_fips 
Initializes RSA key object for use with optional heap hint p. Returns 0 on success, < 0 on error. 
FreeRsaKey_fips 
Releases RSA key resources. Returns 0 on success, < 0 on error. 
RsaSSL_Sign_fips 
Performs RSA key Signing operation on input in of size inLen, outputting to out of size outLen using rng. Returns 0 on success, < 0 on error. 
RsaSSL_VerifyInline_fips 
Performs RSA key Verification without allocating temporary memory on input in of size inLen, writes to output out. Returns 0 on success, < 0 on error. 
RsaSSL_Verify_fips 
Performs RSA key Verification on input in of size inLen, writes to output out of size outLen. Returns 0 on success, < 0 on error. 
RsaPSS_Sign_fips 
Performs RSA key Signing operation with PSS padding on input in of size inLen, outputting to out of size outLen using rng. It uses the hash algorithm hash with the mask generation function mgf. Returns 0 on success, < 0 on error. 
RsaPSS_SignEx_fips 
Performs RSA key Signing operation with PSS padding on input in of size inLen, outputting to out of size outLen using rng. It uses the hash algorithm hash with the mask generation function mgf and a salt length of saltLen. Returns 0 on success, < 0 on error. 
RsaPSS_VerifyInline_fips 
Performs RSA key Verification without allocating temporary memory on input in of size inLen, writes to output out. It uses the hash algorithm hash with the mask generation function mgf. Returns 0 on success, < 0 on error. 
RsaPSS_VerifyInlineEx_fips 
Performs RSA key Verification on input in of size inLen, writes to output out of size outLen. It uses the hash algorithm hash with the mask generation function mgf and a salt length of saltLen. Returns 0 on success, < 0 on error. 
RsaPSS_Verify_fips 
Performs RSA key Verification on input in of size inLen, writes to output out of size outLen. It uses the hash algorithm hash with the mask generation function mgf. Returns 0 on success, < 0 on error. 
RsaPSS_VerifyEx_fips 
Performs RSA key Verification on input in of size inLen, writes to output out of size outLen. It uses the hash algorithm hash with the mask generation function mgf and a salt length of saltLen. Returns 0 on success, < 0 on error. 
RsaPSS_CheckPadding_fips 
Checks the padding after RSA key verification on input in of size inSz with signature sig of size sigSz using hash hashType. Returns 0 on success, < 0 on error. 
RsaPSS_CheckPaddingEx_fips 
Checks the padding after RSA key verification on input in of size inSz with signature sig of size sigSz using hash hashType and a salt length of saltLen. Returns 0 on success, < 0 on error. 
RsaEncryptSize_fips 
Retrieves RSA key Output Size. Returns key output size > 0 on success, < 0 on error. 
wc_RsaPrivateKeyDecode 
Decodes an Rsa Private key from a buffer input starting at index inOutIdx of size inSz. Returns 0 on success, < 0 on error. 
wc_RsaPublicKeyDecode 
Decodes an Rsa Public key from a buffer input starting at index inOutIdx of size inSz. Returns 0 on success, < 0 on error. 
ecc_init_fips 
Initializes ECC key object for use. Returns 0 on success, < 0 on error. 
ecc_free_fips 
Releases ECC key object resources. Returns 0 on success, < 0 on error. 
ecc_import_x963_fips 
Imports the ECC public key in ANSI X9.63 format from in of size inLen. Returns 0 on success, < 0 on error. 
ecc_sign_hash_fips 
Performs ECC key Signing operation on in of length inlen and output to out of length outlen using rng. Returns 0 on success, < 0 on error. 
ecc_verify_hash_fips 
Performs ECC key Verification of sig of size siglen, with hash of length hashlen. The signature verification result is returned in res. Returns 0 on success, < 0 on error. 
Message Digest Service 

InitSha_fips 
Initializes sha object for use. Returns 0 on success, < 0 on error. 
ShaUpdate_fips 
Performs sha Update on input data of size len. Returns 0 on success, < 0 on error. 
ShaFinal_fips 
Performs sha Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha224_fips 
Initializes sha224 object for use. Returns 0 on success, < 0 on error. 
Sha224Update_fips 
Performs sha224 Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha224Final_fips 
Performs sha224 Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha256_fips 
Initializes sha256 object for use. Returns 0 on success, < 0 on error. 
Sha256Update_fips 
Performs sha256 Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha256Final_fips 
Performs sha256 Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha384_fips 
Initializes sha384 object for use. Returns 0 on success, < 0 on error. 
Sha384Update_fips 
Performs sha384 Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha384Final_fips 
Performs sha384 Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha512_fips 
Initializes sha512 object for use. Returns 0 on success, < 0 on error. 
Sha512Update_fips 
Performs sha512 Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha512Final_fips 
Performs sha512 Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha3_224_fips 
Initializes sha3 (224bit) object for use. Returns 0 on success, < 0 on error. 
Sha3_224_Update_fips 
Performs sha3 (224bit) Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha3_224_Final_fips 
Performs sha3 (224bit) Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha3_256_fips 
Initializes sha3 (256bit) object for use. Returns 0 on success, < 0 on error. 
Sha3_256_Update_fips 
Performs sha3 (256bit) Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha3_256_Final_fips 
Performs sha3 (256bit) Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha3_384_fips 
Initializes sha3 (384bit) object for use. Returns 0 on success, < 0 on error. 
Sha3_384_Update_fips 
Performs sha3 (384bit) Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha3_384_Final_fips 
Performs sha3 (384bit) Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
InitSha3_512_fips 
Initializes sha3 (512bit) object for use. Returns 0 on success, < 0 on error. 
Sha3_512_Update_fips 
Performs sha3 (512bit) Update on input data of size len. Returns 0 on success, < 0 on error. 
Sha3_512_Final_fips 
Performs sha3 (512bit) Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
Key Generation Service 

MakeRsaKey_fips 
Generates an RSA key with modulus length size and exponent e using the random number generator rng. 
CheckProbablePrime_fips 
For a potential modulus of length nlen, check the candidate numbers pRaw of size pRawSz and qRaw of size qRawSz to see if they are probably prime. They should both have a GCD with the exponent eRaw of size eRawSz of 1. The prime candidates are checked with MillerRabin. The result is written to isPrime. Returns 0 on success, < 0 on error. 
RsaExportKey_fips 
Exports the RSA key as its components e of eSz, n of nSz, d of dSz, p of pSz, q of qSz. The sizes should be the sizes of the buffers, and are updated to the actual length of number. Returns 0 on success, < 0 on error. 
ecc_make_key_fips 
Performs the ECC Key Generation operation on key of size keysize using rng. Returns 0 on success, < 0 on error. 
ecc_export_x963_fips 
Exports the ECC public key in ANSI X9.63 format to out of size outLen. Returns 0 on success, < 0 on error. 
HKDF_fips 
Performs HMAC based Key Derivation Function using a hash of type and inKey of size inKeySz, with a salt of length saltSz and info of infoSz. The key is written to out of size outSz. Returns 0 on success, < 0 on error. 
Key Agreement Service 

ecc_shared_secret_fips 
Performs ECDHE Key Agreement operation with privKey and the peer’s pubKey and storing the result in sharedSecret of length sharedSz. Returns 0 on success, < 0 on error. 
DhAgree_fips 
Creates the agreement agree of size agreeSz using DH key private priv of size privSz and peer’s public key otherPub of size pubSz. Returns 0 on success, < 0 on error. 
DSA Key Service 

InitDhKey_fips 
Initializes DH key object for use. No return code. 
FreeDhKey_fips 
Releases DH key resources. No return code. 
DhSetKeyEx_fips 
Sets the group parameters for the DH key from the unsigned binary inputs p of size pSz, q of size qSz, and g of size gSz. Returns 0 on success, < 0 on error. 
DhGenerateKeyPair_fips 
Generates the public part pub of size pubSz, private part priv of size privSz using rng for DH key. Returns 0 on success, < 0 on error. 
Key Transport Service 

RsaPublicEncrypt_fips 
Performs RSA key Public Encryption on input in of size inLen, writes to output out of size outLen using rng. Returns 0 on success, < 0 on error. 
RsaPublicEncryptEx_fips 
Performs RSA key Public Encryption on input in of size inLen, writes to output out of size outLen using rng. It uses padding of type. If using PSS padding, it uses hash and mgf, with label of size labelSz. Returns 0 on success, < 0 on error. 
RsaPrivateDecryptInline_fips 
Performs RSA key Private Decryption without allocating temporary memory on input in of size inLen, writes to output out. Returns 0 on success, < 0 on error. 
RsaPrivateDecryptInlineEx_fips 
Performs RSA key Private Decryption without allocating temporary memory on input in of size inLen, writes to output out. It uses padding of type. If using PSS padding, it uses hash and mgf, with label of size labelSz. Returns 0 on success, < 0 on error. 
RsaPrivateDecrypt_fips 
Performs Rsa key Private Decryption on input in of size inLen, writes to output out of size outLen. Returns 0 on success, < 0 on error. 
RsaPrivateDecryptEx_fips 
Performs Rsa key Private Decryption on input in of size inLen, writes to output out of size outLen. It uses padding of type. If using PSS padding, it uses hash and mgf, with label of size labelSz. Returns 0 on success, < 0 on error. 
Show status Service 

wolfCrypt_GetStatus_fips 
Returns the current status of the module. A return code of 0 means the module is in a state without errors. Any other return code is the specific error state of the module. 
wolfCrypt_GetVersion_fips 
Returns a pointer to the nullterminated char string of the wolfCrypt library version. 
wolfCrypt_GetCoreHash_fips 
Returns a pointer to the nullterminated char string of the core hash in hex. 
API Calls for Allowed Security Functions
API 
Description 
Message digest MD5 Service 

wc_InitMd5 
Initializes md5 object for use. Returns 0 on success, < 0 on error. 
wc_Md5Update 
Performs md5 Update on input data of size len. Returns 0 on success, < 0 on error. 
wc_Md5Final 
Performs md5 Final, outputs digest to hash. Returns 0 on success, < 0 on error. 
Copyright © 2020 wolfSSL Inc. All rights reserved.
[a]DNO_STRICT_ECDSA_LEN should be considered for addition to the fips=ready CFLAGS at some point, the strict len check causes a lot of issues with the vector tests, not sure how it will work out with normal SSL/TLS and crypto operations though.