diff --git a/docs/test_coverage.txt b/docs/test_coverage.txt new file mode 100644 index 00000000..2908700d --- /dev/null +++ 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 diff --git a/docs/test_coverage_report.txt b/docs/test_coverage_report.txt new file mode 100644 index 00000000..b8dbe7a9 --- /dev/null +++ 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 diff --git a/docs/untested_apis.txt b/docs/untested_apis.txt new file mode 100644 index 00000000..34bd8a55 --- /dev/null +++ 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 diff --git a/wolftpm/tpm2_wrap.h b/wolftpm/tpm2_wrap.h index 8fc26d74..50d85fc4 100644 --- a/wolftpm/tpm2_wrap.h +++ b/wolftpm/tpm2_wrap.h @@ -1085,6 +1085,34 @@ WOLFTPM_API int wolfTPM2_ImportEccPrivateKey(WOLFTPM2_DEV* dev, \sa wolfTPM2_LoadEccPrivateKey_ex \sa wolfTPM2_LoadPrivateKey */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import an ECC private key into the TPM with a custom seed + \note Allows importing ECC keys with a user-provided seed for key derivation + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param parentKey pointer to a WOLFTPM2_KEY struct containing parent key + \param keyBlob pointer to an empty WOLFTPM2_KEYBLOB structure to store imported key + \param curveId integer value specifying the ECC curve ID (TPM_ECC_CURVE) + \param eccPubX pointer to ECC public key X coordinate + \param eccPubXSz size of X coordinate in bytes + \param eccPubY pointer to ECC public key Y coordinate + \param eccPubYSz size of Y coordinate in bytes + \param eccPriv pointer to ECC private key data + \param eccPrivSz size of private key data in bytes + \param attributes TPM object attributes to apply to imported key + \param seed pointer to custom seed data for key derivation + \param seedSz size of seed data in bytes + + \sa wolfTPM2_ImportEccPrivateKey + \sa wolfTPM2_LoadEccPrivateKey +*/ WOLFTPM_API int wolfTPM2_ImportEccPrivateKeySeed(WOLFTPM2_DEV* dev, const WOLFTPM2_KEY* parentKey, WOLFTPM2_KEYBLOB* keyBlob, int curveId, const byte* eccPubX, word32 eccPubXSz, @@ -1399,6 +1427,24 @@ WOLFTPM_API int wolfTPM2_RsaKey_TpmToPemPub(WOLFTPM2_DEV* dev, \sa wolfTPM2_RsaKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import a wolfcrypt RSA key into the TPM + \note Allows using externally generated keys by wolfcrypt with TPM 2.0 + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param wolfKey pointer to a wolfcrypt RsaKey structure containing the key to import + \param tpmKey pointer to an empty WOLFTPM2_KEY structure to store the imported TPM key + + \sa wolfTPM2_RsaKey_TpmToWolf + \sa wolfTPM2_RsaKey_WolfToTpm_ex +*/ WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm(WOLFTPM2_DEV* dev, RsaKey* wolfKey, WOLFTPM2_KEY* tpmKey); @@ -1419,6 +1465,25 @@ WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm(WOLFTPM2_DEV* dev, RsaKey* wolfKey, \sa wolfTPM2_RsaKey_WolfToTpm \sa wolfTPM2_RsaKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import a wolfcrypt RSA key into the TPM under a specific parent key + \note Allows using wolfcrypt generated keys with wolfTPM under a specific storage key + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param parentKey pointer to a WOLFTPM2_KEY struct pointing to a Primary Key or TPM Hierarchy + \param wolfKey pointer to a wolfcrypt RsaKey structure containing the key to import + \param tpmKey pointer to an empty WOLFTPM2_KEY structure to store the imported TPM key + + \sa wolfTPM2_RsaKey_WolfToTpm + \sa wolfTPM2_RsaKey_TpmToWolf +*/ WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm_ex(WOLFTPM2_DEV* dev, const WOLFTPM2_KEY* parentKey, RsaKey* wolfKey, WOLFTPM2_KEY* tpmKey); @@ -1438,6 +1503,25 @@ WOLFTPM_API int wolfTPM2_RsaKey_WolfToTpm_ex(WOLFTPM2_DEV* dev, \sa wolfTPM2_RsaKey_TpmToPem \sa wolfTPM2_RsaKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import a PEM format RSA public key into the TPM + \note Converts and loads a PEM formatted RSA public key for use with TPM operations + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param tpmKey pointer to an empty WOLFTPM2_KEY structure to store the imported TPM key + \param pem pointer to PEM formatted public key data + \param pemSz size of PEM data in bytes + + \sa wolfTPM2_RsaKey_TpmToPemPub + \sa wolfTPM2_RsaKey_WolfToTpm +*/ WOLFTPM_API int wolfTPM2_RsaKey_PubPemToTpm(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* tpmKey, const byte* pem, word32 pemSz); @@ -1458,6 +1542,26 @@ WOLFTPM_API int wolfTPM2_RsaKey_PubPemToTpm(WOLFTPM2_DEV* dev, \sa wolfTPM2_ImportPrivateKeyBuffer \sa wolfTPM2_DecodeEccDer */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import DER RSA private or public key into TPM public and sensitive structures + \note This does not make any calls to TPM hardware, only converts key format + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param der pointer to DER encoded key data + \param derSz size of DER data in bytes + \param pub pointer to TPM2B_PUBLIC structure to store public key components + \param sens pointer to TPM2B_SENSITIVE structure to store private key components + \param attributes TPM object attributes to apply (or 0 to use defaults) + + \sa wolfTPM2_ImportPublicKeyBuffer + \sa wolfTPM2_ImportPrivateKeyBuffer +*/ WOLFTPM_API int wolfTPM2_DecodeRsaDer(const byte* der, word32 derSz, TPM2B_PUBLIC* pub, TPM2B_SENSITIVE* sens, TPMA_OBJECT attributes); #endif /* !NO_RSA */ @@ -1478,6 +1582,24 @@ WOLFTPM_API int wolfTPM2_DecodeRsaDer(const byte* der, word32 derSz, \sa wolfTPM2_EccKey_WolfToTpm \sa wolfTPM2_EccKey_WolfToTpm_ex */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Extract an ECC TPM key and convert it to a wolfcrypt key + \note Allows using TPM generated keys with wolfcrypt functions + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param tpmKey pointer to a WOLFTPM2_KEY struct containing TPM key + \param wolfKey pointer to an empty ecc_key structure to store converted key + + \sa wolfTPM2_EccKey_WolfToTpm + \sa wolfTPM2_EccKey_WolfToTpm_ex +*/ WOLFTPM_API int wolfTPM2_EccKey_TpmToWolf(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* tpmKey, ecc_key* wolfKey); @@ -1496,6 +1618,24 @@ WOLFTPM_API int wolfTPM2_EccKey_TpmToWolf(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* tpmKe \sa wolfTPM2_EccKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import a wolfcrypt ECC key into the TPM + \note Allows using externally generated keys by wolfcrypt with TPM 2.0 + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param wolfKey pointer to a wolfcrypt ecc_key structure containing key to import + \param tpmKey pointer to an empty WOLFTPM2_KEY structure to store imported key + + \sa wolfTPM2_EccKey_TpmToWolf + \sa wolfTPM2_EccKey_WolfToTpm_ex +*/ WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm(WOLFTPM2_DEV* dev, ecc_key* wolfKey, WOLFTPM2_KEY* tpmKey); @@ -1516,6 +1656,25 @@ WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm(WOLFTPM2_DEV* dev, ecc_key* wolfKey, \sa wolfTPM2_EccKey_WolfToTPM \sa wolfTPM2_EccKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import ECC wolfcrypt key into the TPM under a specific parent key + \note Allows using wolfcrypt generated keys with wolfTPM under a specific storage key + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param parentKey pointer to a WOLFTPM2_KEY struct pointing to a Primary Key or TPM Hierarchy + \param wolfKey pointer to a wolfcrypt ecc_key structure containing key to import + \param tpmKey pointer to an empty WOLFTPM2_KEY structure to store imported key + + \sa wolfTPM2_EccKey_WolfToTpm + \sa wolfTPM2_EccKey_TpmToWolf +*/ WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm_ex(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* parentKey, ecc_key* wolfKey, WOLFTPM2_KEY* tpmKey); @@ -1534,6 +1693,23 @@ WOLFTPM_API int wolfTPM2_EccKey_WolfToTpm_ex(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* pa \sa wolfTPM2_EccKey_TpmToWolf */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Extract the public point from a wolfcrypt ECC key for use with TPM + \note Converts wolfcrypt ECC public key format to TPM format + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param wolfKey pointer to a wolfcrypt ecc_key structure containing the key + \param pubPoint pointer to a TPM2B_ECC_POINT structure to store the public point + + \sa wolfTPM2_EccKey_TpmToWolf +*/ WOLFTPM_API int wolfTPM2_EccKey_WolfToPubPoint(WOLFTPM2_DEV* dev, ecc_key* wolfKey, TPM2B_ECC_POINT* pubPoint); @@ -1554,6 +1730,26 @@ WOLFTPM_API int wolfTPM2_EccKey_WolfToPubPoint(WOLFTPM2_DEV* dev, ecc_key* wolfK \sa wolfTPM2_ImportPrivateKeyBuffer \sa wolfTPM2_DecodeRsaDer */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Import DER ECC private or public key into TPM public and sensitive structures + \note This does not make any calls to TPM hardware, only converts key format + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param der pointer to DER encoded key data + \param derSz size of DER data in bytes + \param pub pointer to TPM2B_PUBLIC structure to store public key components + \param sens pointer to TPM2B_SENSITIVE structure to store private key components + \param attributes TPM object attributes to apply (or 0 to use defaults) + + \sa wolfTPM2_ImportPublicKeyBuffer + \sa wolfTPM2_ImportPrivateKeyBuffer +*/ WOLFTPM_API int wolfTPM2_DecodeEccDer(const byte* der, word32 derSz, TPM2B_PUBLIC* pub, TPM2B_SENSITIVE* sens, TPMA_OBJECT attributes); #endif /* HAVE_ECC */ @@ -1747,6 +1943,26 @@ WOLFTPM_API int wolfTPM2_ECDHGenKey(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* ecdhKey, \sa wolfTPM2_ECDHEGenKey \sa wolfTPM2_ECDHEGenZ */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate an ECDH shared secret using a TPM key and external public point + \note Performs ECDH key agreement between TPM private key and external public point + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param privKey pointer to a WOLFTPM2_KEY struct containing TPM private key + \param pubPoint pointer to TPM2B_ECC_POINT containing external public point + \param out pointer to buffer to store generated shared secret + \param outSz pointer to int containing buffer size, updated with actual size + + \sa wolfTPM2_ECDHGenZ + \sa wolfTPM2_ECDHEGenKey +*/ WOLFTPM_API int wolfTPM2_ECDHGen(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* privKey, TPM2B_ECC_POINT* pubPoint, byte* out, int* outSz); @@ -1769,6 +1985,26 @@ WOLFTPM_API int wolfTPM2_ECDHGen(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* privKey, \sa wolfTPM2_ECDHEGenKey \sa wolfTPM2_ECDHEGenZ */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate ECDH shared secret Z value using TPM key and external public point + \note Similar to wolfTPM2_ECDHGen but returns only the Z coordinate + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param privKey pointer to a WOLFTPM2_KEY struct containing TPM private key + \param pubPoint pointer to TPM2B_ECC_POINT containing external public point + \param out pointer to buffer to store generated Z value + \param outSz pointer to int containing buffer size, updated with actual size + + \sa wolfTPM2_ECDHGen + \sa wolfTPM2_ECDHEGenZ +*/ WOLFTPM_API int wolfTPM2_ECDHGenZ(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* privKey, const TPM2B_ECC_POINT* pubPoint, byte* out, int* outSz); @@ -2468,6 +2704,25 @@ WOLFTPM_API int wolfTPM2_HmacStart(WOLFTPM2_DEV* dev, WOLFTPM2_HMAC* hmac, \sa wolfTPM2_HmacStart \sa wolfTPM2_HMACFinish */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Update an HMAC operation with data + \note Adds data to an active HMAC sequence + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param hmac pointer to an active WOLFTPM2_HMAC structure + \param data pointer to data to add to HMAC + \param dataSz size of data in bytes + + \sa wolfTPM2_HmacStart + \sa wolfTPM2_HmacFinish +*/ WOLFTPM_API int wolfTPM2_HmacUpdate(WOLFTPM2_DEV* dev, WOLFTPM2_HMAC* hmac, const byte* data, word32 dataSz); @@ -2509,6 +2764,26 @@ WOLFTPM_API int wolfTPM2_HmacFinish(WOLFTPM2_DEV* dev, WOLFTPM2_HMAC* hmac, \sa wolfTPM2_EncryptDecrypt \sa TPM2_EncryptDecrypt2 */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Load a symmetric key into the TPM + \note Creates and loads a symmetric key for encryption/decryption operations + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param key pointer to an empty WOLFTPM2_KEY structure to store loaded key + \param alg algorithm type (TPM_ALG_AES, etc) + \param keyBuf pointer to key material + \param keySz size of key material in bytes + + \sa wolfTPM2_EncryptDecryptBlock + \sa wolfTPM2_EncryptDecrypt +*/ WOLFTPM_API int wolfTPM2_LoadSymmetricKey(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, int alg, const byte* keyBuf, word32 keySz); @@ -3016,6 +3291,27 @@ WOLFTPM_API int wolfTPM2_GetTime(WOLFTPM2_KEY* aikKey, GetTime_Out* getTimeOut); \sa wolfTPM2_CSR_MakeAndSign \sa wolfTPM2_CSR_MakeAndSign_ex */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Add a custom extension to a Certificate Signing Request (CSR) + \note Allows adding custom X.509 extensions to CSR before signing + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct (not used) + \param csr pointer to a WOLFTPM2_CSR structure + \param critical If 0, the extension will not be marked critical, otherwise it will be marked critical + \param oid Dot separated oid as a string (e.g., "1.2.840.10045.3.1.7") + \param der pointer to DER encoded extension data + \param derSz size of DER data in bytes + + \sa wolfTPM2_CSR_SetKeyUsage + \sa wolfTPM2_CSR_SetSubject +*/ WOLFTPM_API int wolfTPM2_CSR_SetCustomExt(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, int critical, const char *oid, const byte *der, word32 derSz); @@ -3042,6 +3338,24 @@ WOLFTPM_API int wolfTPM2_CSR_SetCustomExt(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, \sa wolfTPM2_CSR_MakeAndSign \sa wolfTPM2_CSR_MakeAndSign_ex */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set the Key Usage extension in a Certificate Signing Request (CSR) + \note Configures how the key can be used (e.g., digitalSignature, keyEncipherment) + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param csr pointer to a WOLFTPM2_CSR structure + \param keyUsage string containing comma-separated key usage values + + \sa wolfTPM2_CSR_SetCustomExt + \sa wolfTPM2_CSR_SetSubject +*/ WOLFTPM_API int wolfTPM2_CSR_SetKeyUsage(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, const char* keyUsage); @@ -3063,6 +3377,24 @@ WOLFTPM_API int wolfTPM2_CSR_SetKeyUsage(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, \sa wolfTPM2_CSR_MakeAndSign \sa wolfTPM2_CSR_MakeAndSign_ex */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set the Subject Name in a Certificate Signing Request (CSR) + \note Sets the Distinguished Name (DN) in the CSR (e.g., CN=example.com) + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param csr pointer to a WOLFTPM2_CSR structure + \param subject string containing the subject DN in /CN=example.com format + + \sa wolfTPM2_CSR_SetKeyUsage + \sa wolfTPM2_CSR_SetCustomExt +*/ WOLFTPM_API int wolfTPM2_CSR_SetSubject(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, const char* subject); @@ -3093,6 +3425,30 @@ WOLFTPM_API int wolfTPM2_CSR_SetSubject(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, \sa wolfTPM2_CSR_SetCustomExt \sa wolfTPM2_CSR_MakeAndSign */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate and sign a Certificate Signing Request (CSR) with extended options + \note Creates a CSR using configured parameters and signs it with specified key + + \return Success: Positive integer (size of the output) + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param csr pointer to a WOLFTPM2_CSR structure + \param key pointer to a WOLFTPM2_KEY structure containing signing key + \param outFormat output format (CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM) + \param out pointer to buffer for CSR output + \param outSz size of output buffer + \param sigType signature algorithm to use (0 for default SHA2-256) + \param selfSignCert If 1, generate self-signed cert; if 0, generate CSR + \param devId device ID for crypto callback (-2 for auto-register) + + \sa wolfTPM2_CSR_MakeAndSign + \sa wolfTPM2_CSR_Generate_ex +*/ WOLFTPM_API int wolfTPM2_CSR_MakeAndSign_ex(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, WOLFTPM2_KEY* key, int outFormat, byte* out, int outSz, int sigType, int selfSignCert, int devId); @@ -3150,9 +3506,34 @@ WOLFTPM_API int wolfTPM2_CSR_MakeAndSign(WOLFTPM2_DEV* dev, WOLFTPM2_CSR* csr, \sa wolfTPM2_SetCryptoDevCb \sa wolfTPM2_CSR_Generate */ -WOLFTPM_API int wolfTPM2_CSR_Generate_ex(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, - const char* subject, const char* keyUsage, int outFormat, - byte* out, int outSz, int sigType, int selfSignCert, int devId); + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate a Certificate Signing Request (CSR) or self-signed certificate with extended options + \note Single shot API for outputting a CSR or self-signed cert based on TPM key + + \return Success: Positive integer (size of the output) + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param key pointer to a loaded WOLFTPM2_KEY structure + \param subject distinguished name string using /CN= syntax + \param keyUsage string list of comma separated key usage attributes + \param outFormat output format (CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM) + \param out pointer to buffer for CSR/cert output + \param outSz size of output buffer + \param sigType signature algorithm (0 for default SHA2-256) + \param selfSignCert If 1, generate self-signed cert; if 0, generate CSR + \param devId device ID for crypto callback (-2 for auto-register) + + \sa wolfTPM2_CSR_Generate + \sa wolfTPM2_CSR_MakeAndSign_ex +*/ +WOLFTPM_API int wolfTPM2_CSR_Generate_ex(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, + const char* subject, const char* keyUsage, int outFormat, + byte* out, int outSz, int sigType, int selfSignCert, int devId); /*! \ingroup wolfTPM2_Wrappers @@ -3177,6 +3558,28 @@ WOLFTPM_API int wolfTPM2_CSR_Generate_ex(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, \sa wolfTPM2_SetCryptoDevCb \sa wolfTPM2_CSR_Generate_ex */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate a Certificate Signing Request (CSR) or self-signed certificate + \note Simplified version of wolfTPM2_CSR_Generate_ex with default options + + \return Success: Positive integer (size of the output) + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param key pointer to a loaded WOLFTPM2_KEY structure + \param subject distinguished name string using /CN= syntax + \param keyUsage string list of comma separated key usage attributes + \param outFormat output format (CTC_FILETYPE_ASN1 or CTC_FILETYPE_PEM) + \param out pointer to buffer for CSR/cert output + \param outSz size of output buffer + + \sa wolfTPM2_CSR_Generate_ex + \sa wolfTPM2_CSR_MakeAndSign +*/ WOLFTPM_API int wolfTPM2_CSR_Generate(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, const char* subject, const char* keyUsage, int outFormat, byte* out, int outSz); @@ -3200,6 +3603,22 @@ WOLFTPM_API int wolfTPM2_CSR_Generate(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, \sa TPM2_HierarchyChangeAuth */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set the platform hierarchy authentication value to random + \note Used to prevent applications from using platform hierarchy (TCG PC Client spec section 10) + + \return Success: Positive integer (size of the output) + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param session pointer to a WOLFTPM2_SESSION struct for protecting new platform auth + + \sa TPM2_HierarchyChangeAuth +*/ WOLFTPM_API int wolfTPM2_ChangePlatformAuth(WOLFTPM2_DEV* dev, WOLFTPM2_SESSION* session); @@ -3259,6 +3678,24 @@ typedef struct TpmCryptoDevCtx { \sa wolfTPM2_SetCryptoDevCb \sa wolfTPM2_ClearCryptoDevCb */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Reference crypto callback for TPM crypto offload + \note Callback function registered with wolfTPM2_SetCryptoDevCb or wc_CryptoDev_RegisterDevice + + \return TPM_RC_SUCCESS: successful + \return CRYPTOCB_UNAVAILABLE: Do not use TPM hardware, fall-back to software crypto + \return WC_HW_E: generic hardware failure + + \param devId device ID used when registering callback (any signed integer except INVALID_DEVID) + \param info pointer to wc_CryptoInfo structure with crypto type and parameters + \param ctx user context supplied when callback was registered + + \sa wolfTPM2_SetCryptoDevCb + \sa wolfTPM2_ClearCryptoDevCb +*/ WOLFTPM_API int wolfTPM2_CryptoDevCb(int devId, wc_CryptoInfo* info, void* ctx); /*! @@ -3277,6 +3714,25 @@ WOLFTPM_API int wolfTPM2_CryptoDevCb(int devId, wc_CryptoInfo* info, void* ctx); \sa wolfTPM2_CryptoDevCb \sa wolfTPM2_ClearCryptoDevCb */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Register a crypto callback function and return assigned devId + \note Used to set up TPM crypto offload for wolfCrypt operations + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param cb callback function (wolfTPM2_CryptoDevCb or custom implementation) + \param tpmCtx pointer to TpmCryptoDevCtx for wolfTPM2_CryptoDevCb or custom context + \param pDevId pointer to store automatically assigned device ID + + \sa wolfTPM2_CryptoDevCb + \sa wolfTPM2_ClearCryptoDevCb +*/ WOLFTPM_API int wolfTPM2_SetCryptoDevCb(WOLFTPM2_DEV* dev, CryptoDevCallbackFunc cb, TpmCryptoDevCtx* tpmCtx, int* pDevId); @@ -3353,6 +3809,18 @@ WOLFTPM_API int wolfTPM_PK_SetCbCtx(WOLFSSL* ssl, void* userCtx); \sa wolfTPM2_Free */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a WOLFTPM2_DEV + \note Dynamically allocates memory for TPM device structure + + \return pointer to new device struct + \return NULL: on any error + + \sa wolfTPM2_Free +*/ WOLFTPM_API WOLFTPM2_DEV* wolfTPM2_New(void); /*! @@ -3365,6 +3833,20 @@ WOLFTPM_API WOLFTPM2_DEV* wolfTPM2_New(void); \sa wolfTPM2_New */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Cleanup and Free a WOLFTPM2_DEV that was allocated by wolfTPM2_New + \note Frees memory and cleans up TPM device resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct to be freed + + \sa wolfTPM2_New +*/ WOLFTPM_API int wolfTPM2_Free(WOLFTPM2_DEV *dev); /*! @@ -3376,6 +3858,18 @@ WOLFTPM_API int wolfTPM2_Free(WOLFTPM2_DEV *dev); \sa wolfTPM2_FreeKeyBlob */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a WOLFTPM2_KEYBLOB + \note Dynamically allocates memory for TPM key blob structure + + \return pointer to newly initialized WOLFTPM2_KEYBLOB + \return NULL on any error + + \sa wolfTPM2_FreeKeyBlob +*/ WOLFTPM_API WOLFTPM2_KEYBLOB* wolfTPM2_NewKeyBlob(void); /*! @@ -3388,6 +3882,20 @@ WOLFTPM_API WOLFTPM2_KEYBLOB* wolfTPM2_NewKeyBlob(void); \sa wolfTPM2_NewKeyBlob */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Free a WOLFTPM2_KEYBLOB that was allocated with wolfTPM2_NewKeyBlob + \note Frees memory and cleans up TPM key blob resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param blob pointer to a WOLFTPM2_KEYBLOB to be freed + + \sa wolfTPM2_NewKeyBlob +*/ WOLFTPM_API int wolfTPM2_FreeKeyBlob(WOLFTPM2_KEYBLOB* blob); /*! @@ -3399,6 +3907,18 @@ WOLFTPM_API int wolfTPM2_FreeKeyBlob(WOLFTPM2_KEYBLOB* blob); \sa wolfTPM2_FreePublicTemplate */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a TPMT_PUBLIC template + \note Dynamically allocates memory for TPM public key template + + \return pointer to newly initialized TPMT_PUBLIC template + \return NULL on any error + + \sa wolfTPM2_FreePublicTemplate +*/ WOLFTPM_API TPMT_PUBLIC* wolfTPM2_NewPublicTemplate(void); /*! @@ -3411,6 +3931,20 @@ WOLFTPM_API TPMT_PUBLIC* wolfTPM2_NewPublicTemplate(void); \sa wolfTPM2_NewPublicTemplate */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Free a TPMT_PUBLIC template that was allocated with wolfTPM2_NewPublicTemplate + \note Frees memory and cleans up TPM public template resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param PublicTemplate pointer to a TPMT_PUBLIC template to be freed + + \sa wolfTPM2_NewPublicTemplate +*/ WOLFTPM_API int wolfTPM2_FreePublicTemplate(TPMT_PUBLIC* PublicTemplate); @@ -3423,6 +3957,18 @@ WOLFTPM_API int wolfTPM2_FreePublicTemplate(TPMT_PUBLIC* PublicTemplate); \sa wolfTPM2_FreeKey */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a WOLFTPM2_KEY + \note Dynamically allocates memory for TPM key structure + + \return pointer to newly initialized WOLFTPM2_KEY + \return NULL on any error + + \sa wolfTPM2_FreeKey +*/ WOLFTPM_API WOLFTPM2_KEY* wolfTPM2_NewKey(void); /*! @@ -3435,6 +3981,20 @@ WOLFTPM_API WOLFTPM2_KEY* wolfTPM2_NewKey(void); \sa wolfTPM2_NewKey */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Free a WOLFTPM2_KEY that was allocated with wolfTPM2_NewKey + \note Frees memory and cleans up TPM key resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param key pointer to a WOLFTPM2_KEY to be freed + + \sa wolfTPM2_NewKey +*/ WOLFTPM_API int wolfTPM2_FreeKey(WOLFTPM2_KEY* key); @@ -3447,6 +4007,18 @@ WOLFTPM_API int wolfTPM2_FreeKey(WOLFTPM2_KEY* key); \sa wolfTPM2_FreeSession */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a WOLFTPM2_SESSION + \note Dynamically allocates memory for TPM session structure + + \return pointer to newly initialized WOLFTPM2_SESSION + \return NULL on any error + + \sa wolfTPM2_FreeSession +*/ WOLFTPM_API WOLFTPM2_SESSION* wolfTPM2_NewSession(void); /*! @@ -3459,6 +4031,20 @@ WOLFTPM_API WOLFTPM2_SESSION* wolfTPM2_NewSession(void); \sa wolfTPM2_NewSession */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Free a WOLFTPM2_SESSION that was allocated with wolfTPM2_NewSession + \note Frees memory and cleans up TPM session resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param session pointer to a WOLFTPM2_SESSION to be freed + + \sa wolfTPM2_NewSession +*/ WOLFTPM_API int wolfTPM2_FreeSession(WOLFTPM2_SESSION* session); #ifdef WOLFTPM2_CERT_GEN @@ -3471,6 +4057,18 @@ WOLFTPM_API int wolfTPM2_FreeSession(WOLFTPM2_SESSION* session); \sa wolfTPM2_FreeCSR */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Allocate and initialize a WOLFTPM2_CSR + \note Dynamically allocates memory for TPM CSR structure + + \return pointer to newly initialized WOLFTPM2_CSR + \return NULL on any error + + \sa wolfTPM2_FreeCSR +*/ WOLFTPM_API WOLFTPM2_CSR* wolfTPM2_NewCSR(void); /*! \ingroup wolfTPM2_Wrappers @@ -3482,6 +4080,20 @@ WOLFTPM_API WOLFTPM2_CSR* wolfTPM2_NewCSR(void); \sa wolfTPM2_NewCSR */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Free a WOLFTPM2_CSR that was allocated with wolfTPM2_NewCSR + \note Frees memory and cleans up TPM CSR resources + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param csr pointer to a WOLFTPM2_CSR to be freed + + \sa wolfTPM2_NewCSR +*/ WOLFTPM_API int wolfTPM2_FreeCSR(WOLFTPM2_CSR* csr); #endif #endif /* !WOLFTPM2_NO_HEAP */ @@ -3625,6 +4237,23 @@ WOLFTPM_API int wolfTPM2_SetKeyBlobFromBuffer(WOLFTPM2_KEYBLOB* key, \sa wolfTPM2_PolicyPCR \sa wolfTPM2_PolicyAuthorize */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Restart the policy digest for a policy session + \note Resets the policy digest to its initial value + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param sessionHandle handle of the policy session to restart + + \sa wolfTPM2_GetPolicyDigest + \sa wolfTPM2_PolicyPCR +*/ WOLFTPM_API int wolfTPM2_PolicyRestart(WOLFTPM2_DEV* dev, TPM_HANDLE sessionHandle); /*! @@ -3646,6 +4275,26 @@ WOLFTPM_API int wolfTPM2_PolicyRestart(WOLFTPM2_DEV* dev, TPM_HANDLE sessionHand \sa wolfTPM2_PolicyAuthorize \sa wolfTPM2_PolicyRestart */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Get the current policy digest of a policy session + \note Retrieves the current value of the policy session's digest + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + \return BUFFER_E: policyDigest buffer is too small + + \param dev pointer to a TPM2_DEV struct + \param sessionHandle handle of the policy session + \param policyDigest buffer to store the policy digest + \param policyDigestSz pointer to size of buffer, updated with actual size + + \sa wolfTPM2_PolicyRestart + \sa wolfTPM2_PolicyPCR +*/ WOLFTPM_API int wolfTPM2_GetPolicyDigest(WOLFTPM2_DEV* dev, TPM_HANDLE sessionHandle, byte* policyDigest, word32* policyDigestSz); @@ -3790,6 +4439,28 @@ WOLFTPM_API int wolfTPM2_PolicyPCRMake(TPM_ALG_ID pcrAlg, \sa wolfTPM2_PolicyPCRMake */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Create a policy hash using command code and input data + \note Computes policyDigestnew = hash(policyDigestOld || [cc] || [Input]) + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + \return BUFFER_E: digest buffer is too small + + \param hashAlg hash algorithm to use for policy + \param digest input/output buffer for policy digest + \param digestSz pointer to size of digest buffer + \param cc command code to include in policy + \param input optional input data to include in policy + \param inputSz size of input data + + \sa wolfTPM2_PolicyPCRMake + \sa wolfTPM2_PolicyRefMake +*/ WOLFTPM_API int wolfTPM2_PolicyHash(TPM_ALG_ID hashAlg, byte* digest, word32* digestSz, TPM_CC cc, const byte* input, word32 inputSz); @@ -3813,6 +4484,28 @@ WOLFTPM_API int wolfTPM2_PolicyHash(TPM_ALG_ID hashAlg, \sa wolfTPM2_PolicyPCRMake \sa wolfTPM2_PolicyHash */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Generate a policy authorization digest based on a public key + \note Creates policy digest for authorizing based on signed policy + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + \return BUFFER_E: digest buffer is too small + + \param pcrAlg hash algorithm to use for policy + \param pub pointer to TPM2B_PUBLIC structure containing authorizing key + \param digest input/output buffer for policy digest + \param digestSz pointer to size of digest buffer + \param policyRef optional policy reference data + \param policyRefSz size of policy reference data + + \sa wolfTPM2_PolicyAuthorize + \sa wolfTPM2_PolicyPCRMake +*/ WOLFTPM_API int wolfTPM2_PolicyAuthorizeMake(TPM_ALG_ID pcrAlg, const TPM2B_PUBLIC* pub, byte* digest, word32* digestSz, const byte* policyRef, word32 policyRefSz); @@ -3834,6 +4527,25 @@ WOLFTPM_API int wolfTPM2_PolicyAuthorizeMake(TPM_ALG_ID pcrAlg, \sa wolfTPM2_PolicyAuthValue \sa wolfTPM2_PolicyCommandCode */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set a password policy for a policy session + \note Sets a clear text password requirement for the policy session + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param tpmSession pointer to active policy session + \param auth pointer to password data + \param authSz size of password data in bytes + + \sa wolfTPM2_PolicyAuthValue + \sa wolfTPM2_PolicyCommandCode +*/ WOLFTPM_API int wolfTPM2_PolicyPassword(WOLFTPM2_DEV* dev, WOLFTPM2_SESSION* tpmSession, const byte* auth, int authSz); @@ -3853,6 +4565,25 @@ WOLFTPM_API int wolfTPM2_PolicyPassword(WOLFTPM2_DEV* dev, \sa wolfTPM2_PolicyPassword \sa wolfTPM2_PolicyCommandCode */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set an auth value policy for a policy session + \note Sets an HMAC key requirement for the policy session + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param tpmSession pointer to active policy session + \param auth pointer to auth value data + \param authSz size of auth value data in bytes + + \sa wolfTPM2_PolicyPassword + \sa wolfTPM2_PolicyCommandCode +*/ WOLFTPM_API int wolfTPM2_PolicyAuthValue(WOLFTPM2_DEV* dev, WOLFTPM2_SESSION* tpmSession, const byte* auth, int authSz); @@ -3871,6 +4602,24 @@ WOLFTPM_API int wolfTPM2_PolicyAuthValue(WOLFTPM2_DEV* dev, \sa wolfTPM2_PolicyPassword \sa wolfTPM2_PolicyAuthValue */ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Set a command code policy for a policy session + \note Restricts policy session to specific TPM command + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param tpmSession pointer to active policy session + \param cc TPM command code to allow + + \sa wolfTPM2_PolicyPassword + \sa wolfTPM2_PolicyAuthValue +*/ WOLFTPM_API int wolfTPM2_PolicyCommandCode(WOLFTPM2_DEV* dev, WOLFTPM2_SESSION* tpmSession, TPM_CC cc); @@ -3897,6 +4646,22 @@ WOLFTPM_API int wolfTPM2_PolicyCommandCode(WOLFTPM2_DEV* dev, #define TPM2_IDEVID_CERT_HANDLE 0x1C90200 #endif +/*! + \ingroup wolfTPM2_Wrappers + \brief Set authentication for pre-provisioned identity keys + \note Used with IAK and IDevID keys on ST33KTPM devices + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param handle pointer to WOLFTPM2_HANDLE for the identity key + \param masterPassword pointer to master password data + \param masterPasswordSz size of master password in bytes + + \sa wolfTPM2_CreateAndLoadAIK +*/ WOLFTPM_API int wolfTPM2_SetIdentityAuth(WOLFTPM2_DEV* dev, WOLFTPM2_HANDLE* handle, uint8_t* masterPassword, uint16_t masterPasswordSz); @@ -3904,9 +4669,44 @@ WOLFTPM_API int wolfTPM2_SetIdentityAuth(WOLFTPM2_DEV* dev, WOLFTPM2_HANDLE* han /* Internal API's */ +/*! + \ingroup wolfTPM2_Wrappers + \brief Internal helper to create RSA key template + \note Used internally by key creation functions + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param publicTemplate pointer to TPMT_PUBLIC template to populate + \param nameAlg hash algorithm for key name + \param objectAttributes TPM object attributes + \param keyBits RSA key size in bits + \param exponent RSA public exponent + \param sigScheme signature scheme algorithm + \param sigHash hash algorithm for signatures + + \sa GetKeyTemplateECC +*/ WOLFTPM_LOCAL int GetKeyTemplateRSA(TPMT_PUBLIC* publicTemplate, TPM_ALG_ID nameAlg, TPMA_OBJECT objectAttributes, int keyBits, long exponent, TPM_ALG_ID sigScheme, TPM_ALG_ID sigHash); +/*! + \ingroup wolfTPM2_Wrappers + \brief Internal helper to create ECC key template + \note Used internally by key creation functions + + \return TPM_RC_SUCCESS: successful + \return BAD_FUNC_ARG: check the provided arguments + + \param publicTemplate pointer to TPMT_PUBLIC template to populate + \param nameAlg hash algorithm for key name + \param objectAttributes TPM object attributes + \param curve ECC curve identifier + \param sigScheme signature scheme algorithm + \param sigHash hash algorithm for signatures + + \sa GetKeyTemplateRSA +*/ WOLFTPM_LOCAL int GetKeyTemplateECC(TPMT_PUBLIC* publicTemplate, TPM_ALG_ID nameAlg, TPMA_OBJECT objectAttributes, TPM_ECC_CURVE curve, TPM_ALG_ID sigScheme, TPM_ALG_ID sigHash); @@ -3916,17 +4716,167 @@ WOLFTPM_LOCAL int GetKeyTemplateECC(TPMT_PUBLIC* publicTemplate, typedef int (*wolfTPM2FwDataCb)( uint8_t* data, uint32_t data_req_sz, uint32_t offset, void* cb_ctx); +/*! + \ingroup wolfTPM2_Wrappers + \brief Calculate hash of firmware manifest for upgrade + \note Supports SHA2-384 or SHA2-512 for manifest hash + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param hashAlg hash algorithm to use (TPM_ALG_SHA384 or TPM_ALG_SHA512) + \param manifest_hash buffer to store computed manifest hash + \param manifest_hash_sz size of manifest hash buffer + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeRecover +*/ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Calculate hash of firmware manifest for upgrade + \note Supports SHA2-384 or SHA2-512 for manifest hash + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param hashAlg hash algorithm to use (TPM_ALG_SHA384 or TPM_ALG_SHA512) + \param manifest_hash buffer to store computed manifest hash + \param manifest_hash_sz size of manifest hash buffer + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeRecover +*/ WOLFTPM_API int wolfTPM2_FirmwareUpgradeHash(WOLFTPM2_DEV* dev, TPM_ALG_ID hashAlg, /* Can use SHA2-384 or SHA2-512 for manifest hash */ uint8_t* manifest_hash, uint32_t manifest_hash_sz, uint8_t* manifest, uint32_t manifest_sz, wolfTPM2FwDataCb cb, void* cb_ctx); +/*! + \ingroup wolfTPM2_Wrappers + \brief Perform TPM firmware upgrade + \note Upgrades TPM firmware using provided manifest and data callback + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgradeHash + \sa wolfTPM2_FirmwareUpgradeRecover +*/ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Perform TPM firmware upgrade + \note Upgrades TPM firmware using provided manifest and data callback + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgradeHash + \sa wolfTPM2_FirmwareUpgradeRecover +*/ WOLFTPM_API int wolfTPM2_FirmwareUpgrade(WOLFTPM2_DEV* dev, uint8_t* manifest, uint32_t manifest_sz, wolfTPM2FwDataCb cb, void* cb_ctx); +/*! + \ingroup wolfTPM2_Wrappers + \brief Recover from failed TPM firmware upgrade + \note Attempts to recover TPM after interrupted/failed upgrade + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeHash +*/ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Recover from failed TPM firmware upgrade + \note Attempts to recover TPM after interrupted/failed upgrade + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + \param manifest pointer to firmware manifest data + \param manifest_sz size of firmware manifest + \param cb callback function for firmware data access + \param cb_ctx context pointer passed to callback + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeHash +*/ WOLFTPM_API int wolfTPM2_FirmwareUpgradeRecover(WOLFTPM2_DEV* dev, uint8_t* manifest, uint32_t manifest_sz, wolfTPM2FwDataCb cb, void* cb_ctx); +/*! + \ingroup wolfTPM2_Wrappers + \brief Cancel ongoing TPM firmware upgrade + \note Aborts current firmware upgrade process + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeRecover +*/ + + +/*! + \ingroup wolfTPM2_Wrappers + \brief Cancel ongoing TPM firmware upgrade + \note Aborts current firmware upgrade process + + \return TPM_RC_SUCCESS: successful + \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) + \return BAD_FUNC_ARG: check the provided arguments + + \param dev pointer to a TPM2_DEV struct + + \sa wolfTPM2_FirmwareUpgrade + \sa wolfTPM2_FirmwareUpgradeRecover +*/ WOLFTPM_API int wolfTPM2_FirmwareUpgradeCancel(WOLFTPM2_DEV* dev); #endif /* WOLFTPM_FIRMWARE_UPGRADE */