Add test coverage analysis documentation

Co-Authored-By: david@wolfssl.com <david@wolfssl.com>
2025-02-17 19:36:47 +00:00 · 2025-02-17 19:36:47 +00:00 · 9709c8fedd
parent 32ffc09590
commit 9709c8fedd
3 changed files with 455 additions and 0 deletions
--- a/docs/test_coverage.txt
+++ b/docs/test_coverage.txt
@ -0,0 +1,205 @@
 # Test Coverage Analysis
 ## Test Files Analyzed:
 1. Unit Tests (tests/unit_tests.c)
 2. Integration Tests (examples/wrap/wrap_test.c)
 3. Example Files (examples/*)
 ## Coverage Types:
 1. Direct test coverage (function called directly)
 2. Indirect test coverage (called by tested functions)
 3. Return code checking verification
 ## Test Coverage Status:
 ### Core TPM2 Functions:
 #### Tested in unit_tests.c:
 - TPM2_GetCapability (with return code check)
 - TPM2_PCR_Read (with return code check)
 - TPM2_PCR_Extend (with return code check)
 - TPM2_GetRandom (with return code check)
 - TPM2_Create (with return code check)
 - TPM2_Load (with return code check)
 - TPM2_StartAuthSession (with return code check)
 #### Tested in wrap_test.c:
 - TPM2_CreatePrimary (with return code check)
 - TPM2_Create (with return code check)
 - TPM2_Load (with return code check)
 - TPM2_RSA_Encrypt (with return code check)
 - TPM2_RSA_Decrypt (with return code check)
 - TPM2_Sign (with return code check)
 - TPM2_VerifySignature (with return code check)
 - TPM2_ECDH_KeyGen (with return code check)
 - TPM2_ECDH_ZGen (with return code check)
 - TPM2_NV_DefineSpace (with return code check)
 - TPM2_NV_Write (with return code check)
 - TPM2_NV_Read (with return code check)
 - TPM2_PCR_Read (with return code check)
 - TPM2_PCR_Extend (with return code check)
 #### Tested in keygen.c:
 - TPM2_CreatePrimary (with return code check)
 - TPM2_Create (with return code check)
 - TPM2_Load (with return code check)
 - wolfTPM2_CreateEK (with return code check)
 - wolfTPM2_CreateSRK (with return code check)
 - wolfTPM2_GetKeyTemplate_RSA (with return code check)
 - wolfTPM2_GetKeyTemplate_ECC (with return code check)
 - wolfTPM2_CreateKey (with return code check)
 - wolfTPM2_LoadKey (with return code check)
 #### Tested in store.c:
 - wolfTPM2_NVCreateAuth (with return code check)
 - wolfTPM2_NVWriteAuth (with return code check)
 - wolfTPM2_NVReadAuth (with return code check)
 - wolfTPM2_NVOpen (with return code check)
 #### Tested in extend.c:
 - TPM2_PCR_Extend (with return code check)
 - TPM2_PCR_Read (with return code check)
 - wolfTPM2_ExtendPCR (with return code check)
 - wolfTPM2_ReadPCR (with return code check)
 #### Tested in attestation examples:
 - TPM2_MakeCredential (with return code check)
 - TPM2_ActivateCredential (with return code check)
 - TPM2_Certify (with return code check)
 - TPM2_PolicyCommandCode (with return code check)
 - TPM2_PolicyOR (with return code check)
 - wolfTPM2_CreateEK (with return code check)
 - wolfTPM2_LoadKey (with return code check)
 - wolfTPM2_CreateAuthSession_EkPolicy (with return code check)
 - wolfTPM2_SetAuthSession (with return code check)
 - wolfTPM2_ReadPublicKey (with return code check)
 #### Tested in TLS examples:
 - wolfTPM2_CreatePrimaryKey (with return code check)
 - wolfTPM2_CreateKey (with return code check)
 - wolfTPM2_LoadKey (with return code check)
 - wolfTPM2_SignHash (with return code check)
 - wolfTPM2_VerifyHash (with return code check)
 - wolfTPM2_ECDHGenKey (with return code check)
 - wolfTPM2_ECDHGenZ (with return code check)
 - wolfTPM2_RsaEncrypt (with return code check)
 - wolfTPM2_RsaDecrypt (with return code check)
 - wolfTPM2_LoadRsaPublicKey (with return code check)
 - wolfTPM2_LoadRsaPrivateKey (with return code check)
 - wolfTPM2_LoadEccPublicKey (with return code check)
 - wolfTPM2_LoadEccPrivateKey (with return code check)
 #### Tested in PKCS7 examples:
 - wolfTPM2_SignHash (with return code check)
 - wolfTPM2_VerifyHash (with return code check)
 - wolfTPM2_LoadKey (with return code check)
 - wolfTPM2_CreateKey (with return code check)
 - wolfTPM2_ExportPublicKeyBuffer (with return code check)
 - wolfTPM2_ImportPrivateKey (with return code check)
 #### Tested in Timestamp examples:
 - TPM2_ReadClock (with return code check)
 - TPM2_GetTime (with return code check)
 - wolfTPM2_GetTime (with return code check)
 - wolfTPM2_CreateAndLoadAIK (with return code check)
 - wolfTPM2_StartSession (with return code check)
 #### Tested in GPIO examples:
 - TPM2_GPIO_Config (with return code check)
 - TPM2_NV_DefineSpace (with return code check)
 - TPM2_NV_Write (with return code check)
 - TPM2_NV_Read (with return code check)
 - wolfTPM2_NVCreateAuth (with return code check)
 - wolfTPM2_NVWriteAuth (with return code check)
 #### Tested in Secure Boot examples:
 - wolfTPM2_NVCreateAuth (with return code check)
 - wolfTPM2_NVWriteAuth (with return code check)
 - wolfTPM2_NVReadAuth (with return code check)
 - wolfTPM2_NVWriteLock (with return code check)
 - wolfTPM2_NVReadPublic (with return code check)
 - wolfTPM2_StartSession (with return code check)
 ## Test Coverage Summary:
 1. Core TPM2 Functions:
   - Most core TPM2 functions have direct test coverage
   - Return code checking is consistently implemented
   - Test coverage spans across unit tests and examples
 2. Wrapper Functions:
   - Comprehensive coverage of key management functions
   - Strong coverage of cryptographic operations
   - Good coverage of session and policy management
 3. Test Coverage Patterns:
   - Consistent error handling and return code checks
   - Parameter validation testing
   - Resource cleanup verification
   - Session management verification
 4. Notable Test Coverage Areas:
   - Key generation and management
   - Cryptographic operations (sign/verify/encrypt/decrypt)
   - NV storage operations
   - PCR operations
   - Session management
   - GPIO configuration
   - Time and timestamp operations
   - Secure boot functionality
   - TLS integration
   - PKCS7 operations
 ### Wrapper Functions:
 #### Tested in unit_tests.c:
 - wolfTPM2_Init (with return code check)
 - wolfTPM2_OpenExisting (with return code check)
 - wolfTPM2_GetCapabilities (with return code check)
 - wolfTPM2_ReadPublicKey (with return code check)
 - wolfTPM2_GetRandom (with return code check)
 - wolfTPM2_UnsetAuth (with return code check)
 - wolfTPM2_SetAuth (with return code check)
 - wolfTPM2_Cleanup (with return code check)
 - wolfTPM2_CreatePrimaryKey (with return code check)
 - wolfTPM2_LoadKey (with return code check)
 #### Tested in wrap_test.c:
 - wolfTPM2_Init (with return code check)
 - wolfTPM2_GetCapabilities (with return code check)
 - wolfTPM2_UnloadHandles_AllTransient (with return code check)
 - wolfTPM2_CreatePrimaryKey (with return code check)
 - wolfTPM2_CreateSRK (with return code check)
 - wolfTPM2_StartSession (with return code check)
 - wolfTPM2_SetAuthSession (with return code check)
 - wolfTPM2_CreateLoadedKey (with return code check)
 - wolfTPM2_CreateAndLoadKey (with return code check)
 - wolfTPM2_SignHashScheme (with return code check)
 - wolfTPM2_VerifyHashScheme (with return code check)
 - wolfTPM2_UnloadHandle (with return code check)
 - wolfTPM2_RsaEncrypt (with return code check)
 - wolfTPM2_RsaDecrypt (with return code check)
 - wolfTPM2_LoadEccPublicKey (with return code check)
 - wolfTPM2_LoadEccPrivateKey (with return code check)
 - wolfTPM2_ECDHGen (with return code check)
 - wolfTPM2_ECDHGenZ (with return code check)
 - wolfTPM2_EccKey_TpmToWolf (with return code check)
 - wolfTPM2_EccKey_WolfToTpm (with return code check)
 - wolfTPM2_ChangeAuthKey (with return code check)
 ### Parameter Encryption Functions:
 #### Tested in unit_tests.c:
 - TPM2_KDFa (indirectly tested through session creation)
 #### Tested in wrap_test.c:
 - TPM2_KDFa (directly tested through parameter encryption)
 ## Test Coverage Patterns:
 1. Function call with NULL argument checks
 2. Function call with invalid argument checks
 3. Function call with valid arguments
 4. Return code verification
 5. Cleanup after test
 ## Notes:
 - Exclude WOLFTPM_LOCAL and static functions
 - Focus on public APIs only
 - Document test coverage patterns
 - Verify return code checking
--- a/docs/test_coverage_report.txt
+++ b/docs/test_coverage_report.txt
@ -0,0 +1,177 @@
 # wolfTPM Test Coverage Report
 ## TPM2 Core APIs Lacking Direct Tests
 ### Policy APIs
 1. TPM2_PolicyPhysicalPresence
   - No direct test coverage
   - Not called by any higher-level functions
   - No example usage found
 2. TPM2_PolicyTemplate
   - No direct test coverage
   - Not used in policy examples
   - No indirect usage found
 3. TPM2_PolicyAuthorizeNV
   - No direct test coverage
   - Not used in NV or policy examples
   - No indirect usage through wrapper functions
 ### Hierarchy Management APIs
 1. TPM2_HierarchyControl
   - No direct test coverage
   - Not used in management examples
   - Critical for TPM hierarchy management
 2. TPM2_SetPrimaryPolicy
   - No direct test coverage
   - Referenced in tpm2_wrap.c but not tested
   - Important for TPM policy management
 3. TPM2_ChangePPS
   - No direct test coverage
   - Platform hierarchy management function
   - No example usage found
 4. TPM2_ChangeEPS
   - No direct test coverage
   - Endorsement hierarchy management
   - No example usage found
 5. TPM2_ClearControl
   - No direct test coverage
   - TPM state management function
   - No example usage found
 ### System Management APIs
 1. TPM2_DictionaryAttackLockReset
   - No direct test coverage
   - Security feature for TPM protection
   - No example usage found
 2. TPM2_DictionaryAttackParameters
   - No direct test coverage
   - Security configuration function
   - No example usage found
 3. TPM2_PP_Commands
   - No direct test coverage
   - Physical presence configuration
   - No example usage found
 4. TPM2_SetAlgorithmSet
   - No direct test coverage
   - TPM algorithm management
   - No example usage found
 ### Firmware Management APIs
 1. TPM2_FieldUpgradeStart
   - No direct test coverage
   - Firmware update initialization
   - No example usage found
 2. TPM2_FieldUpgradeData
   - No direct test coverage
   - Firmware update data transfer
   - No example usage found
 3. TPM2_FirmwareRead
   - No direct test coverage
   - Firmware verification function
   - No example usage found
 ### Context Management APIs
 1. TPM2_ContextSave
   - No direct test coverage
   - Session/object context management
   - No example usage found
 2. TPM2_ContextLoad
   - No direct test coverage
   - Session/object context restoration
   - No example usage found
 ## wolfTPM2 APIs Lacking Direct Tests
 ### Key Management APIs
 1. wolfTPM2_RsaKey_PubPemToTpm
   - No direct test coverage
   - Public key import function
   - No example usage found
 ### Crypto Operation APIs
 1. wolfTPM2_ECDHEGenKey
   - No direct test coverage
   - ECDHE key generation
   - No example usage found
 2. wolfTPM2_ECDHEGenZ
   - No direct test coverage
   - ECDHE shared secret generation
   - No example usage found
 ### System Management APIs
 1. wolfTPM2_SetCommand
   - No direct test coverage
   - Command configuration function
   - No example usage found
 ## Test Coverage Recommendations
 ### High Priority
 1. Policy APIs
   - Add unit tests for TPM2_PolicyPhysicalPresence
   - Add unit tests for TPM2_PolicyTemplate
   - Add unit tests for TPM2_PolicyAuthorizeNV
   - Create policy example demonstrating usage
 2. Hierarchy Management
   - Add unit tests for TPM2_HierarchyControl
   - Add unit tests for TPM2_SetPrimaryPolicy
   - Create management example showing hierarchy control
 3. System Management
   - Add unit tests for dictionary attack functions
   - Add unit tests for algorithm management
   - Create example showing security configuration
 ### Medium Priority
 1. Context Management
   - Add unit tests for TPM2_ContextSave/Load
   - Create example showing context management
   - Add session persistence tests
 2. Crypto Operations
   - Add unit tests for ECDHE functions
   - Extend TLS examples to use ECDHE
   - Add key import tests
 ### Low Priority
 1. Firmware Management
   - Add unit tests for firmware update functions
   - Create firmware update example
   - Add firmware read verification
 ## Test Coverage Guidelines
 1. Each test should verify:
   - Successful operation
   - Error handling
   - Return code checking
   - Resource cleanup
 2. Example files should demonstrate:
   - Real-world usage patterns
   - Error recovery
   - Complete workflows
 3. Test organization:
   - Unit tests for individual functions
   - Integration tests for workflows
   - Examples for usage patterns
 4. Documentation:
   - Test prerequisites
   - Expected results
   - Error conditions
   - Cleanup requirements
--- a/docs/untested_apis.txt
+++ b/docs/untested_apis.txt
@ -0,0 +1,73 @@
 # Public APIs Missing Test Coverage
 ## Key Management APIs
 1. wolfTPM2_RsaKey_PubPemToTpm - No direct test coverage
 ## Crypto Operation APIs
 2. wolfTPM2_ECDHEGenKey - No direct test coverage
 3. wolfTPM2_ECDHEGenZ - No direct test coverage
 ## System Management APIs
 4. wolfTPM2_SetCommand - No direct test coverage
 ## TPM2 Core APIs Missing Test Coverage
 ## Policy APIs
 5. TPM2_PolicyPhysicalPresence - No direct test coverage
 6. TPM2_PolicyTemplate - No direct test coverage
 7. TPM2_PolicyAuthorizeNV - No direct test coverage
 ## Hierarchy Management APIs
 8. TPM2_HierarchyControl - No direct test coverage
 9. TPM2_SetPrimaryPolicy - No direct test coverage
 10. TPM2_ChangePPS - No direct test coverage
 11. TPM2_ChangeEPS - No direct test coverage
 12. TPM2_ClearControl - No direct test coverage
 ## System Management APIs
 13. TPM2_DictionaryAttackLockReset - No direct test coverage
 14. TPM2_DictionaryAttackParameters - No direct test coverage
 15. TPM2_PP_Commands - No direct test coverage
 16. TPM2_SetAlgorithmSet - No direct test coverage
 ## Firmware Management APIs
 17. TPM2_FieldUpgradeStart - No direct test coverage
 18. TPM2_FieldUpgradeData - No direct test coverage
 19. TPM2_FirmwareRead - No direct test coverage
 ## Context Management APIs
 20. TPM2_ContextSave - No direct test coverage
 21. TPM2_ContextLoad - No direct test coverage
 Notes:
 1. APIs marked as missing test coverage have no direct tests verifying their functionality and return code checking
 2. Some APIs may be indirectly tested through other functions but lack explicit test coverage
 3. This list excludes APIs that are tested through example files or unit tests
 4. Focus is on public APIs marked with WOLFTPM_API
 Removed from untested list due to having test coverage:
 - wolfTPM2_ImportEccPrivateKeySeed (tested via wolfTPM2_ImportEccPrivateKey)
 - wolfTPM2_RsaKey_WolfToTpm_ex (tested in tpm2_cryptocb.c)
 - wolfTPM2_DecodeRsaDer (tested in policy_sign.c)
 - wolfTPM2_EccKey_WolfToPubPoint (tested in tpm2_cryptocb.c)
 - wolfTPM2_DecodeEccDer (tested via wolfTPM2_ImportEccPrivateKey)
 - wolfTPM2_SetSessionHandle (tested via session management functions)
 - wolfTPM2_SetAuthHandle (tested in multiple example files)
 - wolfTPM2_NVCreateAuthPolicy (tested in nvram/extend.c)
 - wolfTPM2_NVWriteAuthPolicy (tested via NV policy functions)
 - wolfTPM2_NVReadAuthPolicy (tested via NV policy functions)
 - wolfTPM2_NVOpen (tested in multiple nvram examples)
 - wolfTPM2_Shutdown (tested in wrap/caps.c)
 - wolfTPM2_UnloadHandles (tested via key management functions)
 - wolfTPM2_UnloadHandles_AllTransient (tested via key management functions)
 - All CSR APIs (tested in C# wrapper)
 - TPM2_PolicyAuthValue (tested via wolfTPM2_PolicyAuthValue)
 - TPM2_PolicyPassword (tested via wolfTPM2_PolicyPassword)
 - TPM2_PolicyNvWritten (tested in policy examples)
 - TPM2_HierarchyChangeAuth (tested via hierarchy management functions)
 Notes:
 1. APIs marked as missing test coverage have no direct tests verifying their functionality and return code checking
 2. Some APIs may be indirectly tested through other functions but lack explicit test coverage
 3. This list excludes APIs that are tested through example files or unit tests
 4. Focus is on public APIs marked with WOLFTPM_API