wolfssl: add basic instructions to use FIPS-validated version
https://onedigi.atlassian.net/browse/DEL-8036 Signed-off-by: Javier Viguera <javier.viguera@digi.com>
This commit is contained in:
Javier Viguera
parent
52bececebc
commit
b2bc9539b7
|
|
@ -0,0 +1,139 @@
|
|||
Digi Embedded Yocto FIPS-certified WolfSSL support
|
||||
==================================================
|
||||
|
||||
WolfSSL is a lightweight SSL/TLS library written in C and targeted for
|
||||
embedded and resource-constrained environments.
|
||||
|
||||
WolfSSL is powered by the wolfCrypt library. A version of the wolfCrypt
|
||||
library has been FIPS 140-2 validated, with FIPS 140-3 validation currently
|
||||
in progress.
|
||||
|
||||
For more information, visit:
|
||||
https://www.wolfssl.com/license/fips/
|
||||
|
||||
DEY support
|
||||
-----------
|
||||
Digi Embedded Yocto (DEY) supports building the FIPS validated version of
|
||||
WolfSSL. The source package is usually provided under a commercial license
|
||||
agreement by WolfSSL. DEY provides the recipes and configurations to build
|
||||
the recipe into your final image.
|
||||
|
||||
Instructions
|
||||
------------
|
||||
These instructions assume that DEY is properly installed and a project
|
||||
has already been created. For more info on those tasks, see the online
|
||||
documentation on the Digi Embedded Documentation portal:
|
||||
|
||||
https://www.digi.com/resources/documentation/digidocs/embedded/index.html
|
||||
|
||||
1. Add 'meta-wolfssl' layer to the project.
|
||||
|
||||
# cd <project-dir>
|
||||
# bitbake-layers add-layer <DEY-installdir>/sources/meta-wolfssl
|
||||
|
||||
2. Configure the project for building wolfssl FIPS bundle (1st build).
|
||||
|
||||
DEY added support for building the library from a password-protected
|
||||
7z-compressed package, but any other package format supported by Yocto may
|
||||
be used.
|
||||
|
||||
The build is controlled by variables configured in the project's
|
||||
configuration file (<project-dir>/conf/local.conf).
|
||||
|
||||
* PREFERRED_VERSION_wolfssl: the version of the wolfssl recipe to build
|
||||
* WOLFSSL_FIPS_PKG_PATH: absolute local path to the package
|
||||
* WOLFSSL_FIPS_PKG_PASSWORD: package's unpack password (only for 7z compression)
|
||||
* WOLFSSL_FIPS_CORE_HASH: in-core integrity hash (not available until
|
||||
after a first run)
|
||||
|
||||
An example follows:
|
||||
|
||||
PREFERRED_VERSION_wolfssl = "5.4.0-fips"
|
||||
WOLFSSL_FIPS_PKG_PATH = "/PATH/TO/wolfssl-5.4.0-commercial-fips-linuxv5.7z"
|
||||
WOLFSSL_FIPS_PKG_PASSWORD = "xxxx"
|
||||
#WOLFSSL_FIPS_CORE_HASH = ""
|
||||
|
||||
Note: Leave the variable WOLFSSL_FIPS_CORE_HASH commented. The `wolfcrypttest`
|
||||
application provides the WolfSSL FIPS integrity hash value after the first run.
|
||||
|
||||
3. Add the wolfCrypt test programs to the image.
|
||||
|
||||
In the project's configuration file:
|
||||
|
||||
IMAGE_INSTALL:append = " wolfssl wolfcrypttest wolfcryptbenchmark"
|
||||
|
||||
4. Build and program the images in the device.
|
||||
|
||||
If you need more information on this topic, refer to the DEY online
|
||||
documentation (link above).
|
||||
|
||||
5. Compute the WolfSSL FIPS integrity hash.
|
||||
|
||||
In the device, run the `wolfcrypttest` test application. At this point,
|
||||
it is expected that the application fails because the library has not been
|
||||
built with the integrity hash.
|
||||
|
||||
root:~# wolfcrypttest
|
||||
------------------------------------------------------------------------------
|
||||
wolfSSL version 5.4.0
|
||||
------------------------------------------------------------------------------
|
||||
error test passed!
|
||||
MEMORY test passed!
|
||||
base64 test passed!
|
||||
base16 test passed!
|
||||
asn test passed!
|
||||
in my Fips callback, ok = 0, err = -203
|
||||
message = In Core Integrity check FIPS error
|
||||
hash = 9490AAFD1786A11115256841AA71F9B5313BAA244ACF1A07DD8BB8A893CBC5BC
|
||||
In core integrity hash check failure, copy above hash
|
||||
into verifyCore[] in fips_test.c and rebuild
|
||||
RANDOM test failed!
|
||||
error = -7000
|
||||
Exiting main with return code: -1
|
||||
|
||||
6. Reconfigure the project and build the images again (2nd build).
|
||||
|
||||
Feed the FIPS integrity hash back into the build process with the
|
||||
WOLFSSL_FIPS_CORE_HASH variable.
|
||||
|
||||
For example, the final configuration would be:
|
||||
|
||||
PREFERRED_VERSION_wolfssl = "5.4.0-fips"
|
||||
WOLFSSL_FIPS_PKG_PATH = "/PATH/TO/wolfssl-5.4.0-commercial-fips-linuxv5.7z"
|
||||
WOLFSSL_FIPS_PKG_PASSWORD = "xxxx"
|
||||
WOLFSSL_FIPS_CORE_HASH = "9490AAFD1786A11115256841AA71F9B5313BAA244ACF1A07DD8BB8A893CBC5BC"
|
||||
|
||||
IMAGE_INSTALL:append = " wolfssl wolfcrypttest wolfcryptbenchmark"
|
||||
|
||||
Make sure you get rid of the old build objects and rebuild the images:
|
||||
|
||||
# bitbake -c cleansstate wolfssl wolfcrypttest wolfcryptbenchmark
|
||||
# bitbake -c cleanall <image-recipe>
|
||||
|
||||
7. Build and program the images in the device again.
|
||||
|
||||
Now the test application should complete just fine:
|
||||
|
||||
root:~# wolfcrypttest
|
||||
------------------------------------------------------------------------------
|
||||
wolfSSL version 5.4.0
|
||||
------------------------------------------------------------------------------
|
||||
error test passed!
|
||||
MEMORY test passed!
|
||||
base64 test passed!
|
||||
base16 test passed!
|
||||
asn test passed!
|
||||
RANDOM test passed!
|
||||
MD5 test passed!
|
||||
SHA test passed!
|
||||
SHA-224 test passed!
|
||||
...
|
||||
PKCS7authenveloped test passed!
|
||||
prime test passed!
|
||||
logging test passed!
|
||||
time test passed!
|
||||
mutex test passed!
|
||||
memcb test passed!
|
||||
crypto callback test passed!
|
||||
Test complete
|
||||
Exiting main with return code: 0
|
||||
Loading…
Reference in New Issue