Skip to content

Add Doxygen Documentation for Public APIs #400

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
devin-ai-integration wants to merge 3 commits into from
Closed

Add Doxygen Documentation for Public APIs #400

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1aaca3b
Add doxygen documentation for public APIs
devin-ai-integration[bot] Feb 17, 2025
32ffc09
Add newlines between doxygen sections for improved readability
devin-ai-integration[bot] Feb 17, 2025
9709c8f
Add test coverage analysis documentation
devin-ai-integration[bot] Feb 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 205 additions & 0 deletions docs/test_coverage.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
177 changes: 177 additions & 0 deletions docs/test_coverage_report.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading