Add test coverage analysis documentation

Co-Authored-By: david@wolfssl.com <david@wolfssl.com>

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

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

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