Skip to content

README.md

Latest commit

 

History

History
104 lines (79 loc) · 7.23 KB

README.md

File metadata and controls

104 lines (79 loc) · 7.23 KB

wolfHSM unit tests

Overview

The wolfHSM unit tests are designed to run on separate cores, or separate processes to model a real HSM client-server.

Tests can be run on either a POSIX host (ie a development laptop), or on the embedded target.

The unit tests are split into 3 groups:

  • Client, for tests that run on the client core/process
  • Server, for tests that run on the server core/process
  • Misc, for tests that can run on either core/process

The groups are organized in wh_test_list.c.

Running the tests from a dev machine

To run the unit tests on a POSIX system (Linux/Mac):

cd test-refactor
make check

The top-level make forwards to the POSIX port; cd test-refactor/posix && make check still works if you want to invoke the port directly.

Results are printed via WOLFHSM_CFG_PRINTF from the wolfHSM build. test-suite.log contains the detailed output.

Running the tests from an embedded target

To run the tests on a target device, create an application running on the client or server that runs the tests from main(). See sections on adding ports and tests.

Adding a port

The unit tests run within the port's main application. As a prerequiste, setup a new port application as described in the porting guide.

For the unit test port, see wh_test_posix_main.c and the two wh_test_posix_*.c sources as a reference implementation.

Client

  1. Implement main() which creates a client context and initializes it with a config such that it can establish communication to a listening server
  2. Implement whTestPort_ResetClient which resets the context between tests. Can be empty.
  3. Call whTestGroup_Client(&clientCtx)
  4. Optionally call whTestGroup_Misc()

For running the more substantial client tests only, no server modifications are required.

Server

  1. Implement main() which declares a server context and initializes it with a config such that it can access basic platform functionality (NVM, etc.)
  2. Implement whTestPort_ResetServer which resets the context between tests. Can be empty.
  3. Call whTestGroup_Server(&serverCtx) prior to entering the main request handling loop.
  4. Optionally call whTestGroup_Misc()

Adding a multi-port test

  1. Create a new function which returns int (0 for success) with a context argument (whClientContext* for client tests, whServerContext* for server tests, or none for misc tests).
  2. In wh_test_list.c, add a line with WH_TEST_DECL(<function>)
  3. In wh_test_list.c, add the function to the appropriate whTestCase array.

Note: if the test is specific to a platform, do not add it to the common list as shown above. Port-specific tests live within the port (not this directory), and are called from the port-specific code.

Adding a port-specific test

For tests that exist within a specific port, call whTestGroup_RunOne() to utilize the error checking and log formatting from the test framework.

Migration from test/

The legacy unit suite in wolfHSM/test/ is being incrementally translated to wolfHSM/test-refactor/ while preserving the original during the transition. Code coverage Github workflows will be used for confirmation.

Key differences

  • Tests are registered and called based on a list in wh_test_list.c rather than manual inline code, making it simpler to add tests.
  • Tests accept a client or server context which is initialized outside the test itself, reducing copypasta within the test code, and improving portability.
  • Tests are divided into groups, which clarifies the origin and environment of the test.
  • Tests are always run against a running server process or core, no sequencing code for single-thread simulation.

Test mapping

Translated tests:

Legacy (wolfHSM/test/) New location Group Notes
wh_test_dma.c::whTest_Dma misc/wh_test_dma.c::whTest_Dma Misc
wh_test_cert.c::whTest_CertRamSim server/wh_test_cert.c::whTest_CertVerify Server remove ramsim coupling and migrate to server group
wh_test_crypto.c::whTest_Crypto client-server/wh_test_aes.c::whTest_CryptoAes, client-server/wh_test_sha.c::{whTest_CryptoSha224/256/384/512, ...LargeInput, ...Async, ...DmaAsync} (16 functions), client-server/wh_test_ecc.c::{whTest_CryptoEcc, whTest_CryptoEccCacheDuplicate, whTest_CryptoEccCrossVerify, whTest_CryptoEccAsync}, client-server/wh_test_curve25519.c::whTest_CryptoCurve25519, client-server/wh_test_ed25519.c::{whTest_CryptoEd25519Inline, whTest_CryptoEd25519ServerKey, whTest_CryptoEd25519Dma}, client-server/wh_test_mldsa.c::{whTestCrypto_MlDsaClient, whTestCrypto_MlDsaDmaClient, whTestCrypto_MlDsaVerifyOnlyDma}, client-server/wh_test_cmac.c::whTest_CryptoCmac, client-server/wh_test_keypolicy.c::{whTest_CryptoKeyUsagePolicies, whTest_CryptoKeyRevocationAesCbc}, client-server/wh_test_rng.c::{whTest_CryptoRng, whTest_CryptoRngAsync, whTest_CryptoRngDmaAsync}, client-server/wh_test_rsa.c::whTest_CryptoRsa Client Full coverage
wh_test_clientserver.c (echo and server-info paths) client-server/wh_test_echo.c::whTest_Echo, client-server/wh_test_server_info.c::whTest_ServerInfo Client pthread test ported, sequential test dropped
wh_test_wolfcrypt_test.c::whTest_WolfCryptTest client-server/wh_test_wolfcrypt.c::whTest_WolfCryptTest Client
wh_test_flash_ramsim.c::whTest_Flash_RamSim posix/wh_test_flash_ramsim.c::{whTest_FlashWriteLock, whTest_FlashEraseProgramVerify, whTest_FlashUnitOps} POSIX port-specific (whTestGroup_RunOne) remove ramsim coupling and migrate to server group
wh_test_nvm_flash.c::whTest_NvmFlash posix/wh_test_nvm_flash.c::whTest_NvmAddOverwriteDestroy POSIX port-specific (whTestGroup_RunOne) remove ramsim coupling and migrate to server group
wh_test_posix_threadsafe_stress.c::whTest_ThreadSafeStress called directly from posix/wh_test_posix_main.c POSIX port-specific (direct call)

Not yet migrated (still live in wolfHSM/test/):

Legacy (wolfHSM/test/) Notes
wh_test_comm.c::whTest_Comm
wh_test_clientserver.c::whTest_ClientServer Pthread variant: remaining client-side coverage (NVM ops, etc.) still needs to be split out as new tests. The sequential test is dropped
wh_test_crypto_affinity.c::whTest_CryptoAffinity
wh_test_keywrap.c::whTest_KeyWrapClientConfig
wh_test_multiclient.c::whTest_MultiClient
wh_test_lock.c::whTest_LockConfig, whTest_LockPosix whTest_LockConfig to be reworked to fit the Misc group, likely with a context param.
wh_test_log.c::whTest_Log, whTest_LogBackend_RunAll whTest_LogBackend_RunAll to be reworked to fit the Misc group, likely with a context param.
wh_test_she.c::whTest_She
wh_test_timeout.c::whTest_TimeoutPosix
wh_test_auth.c::whTest_AuthMEM, whTest_AuthTCP
wh_test_server_img_mgr.c::whTest_ServerImgMgr
wh_test_nvmflags.c::whTest_NvmFlags
wh_test_flash_fault_inject.c
wh_test_check_struct_padding.c

Other improvements

  • Add callback from wh_Server_HandleRequestMessage to allow sleep and avoid a busy loop
  • Implement whTestPort_ResetServer/Client and re-enable persistent-NVM-artifact tests (WOLFHSM_CFG_TEST_ALLOW_PERSISTENT_NVM_ARTIFACTS is intentionally not defined in config/wolfhsm_cfg.h)