diff --git a/docs/Doxyfile b/docs/Doxyfile index e5fa601..3ef2f73 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -811,7 +811,7 @@ WARNINGS = YES # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -819,7 +819,7 @@ WARN_IF_UNDOCUMENTED = NO # markup commands wrongly. # The default value is: YES. -WARN_IF_DOC_ERROR = NO +WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return @@ -828,7 +828,7 @@ WARN_IF_DOC_ERROR = NO # EXTRACT_ALL is set to YES then this flag will automatically be disabled. # The default value is: NO. -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS diff --git a/wolftpm/tpm2.h b/wolftpm/tpm2.h index 8038e68..18bac1c 100644 --- a/wolftpm/tpm2.h +++ b/wolftpm/tpm2.h @@ -2861,7 +2861,7 @@ WOLFTPM_API int TPM2_GPIO_Config(GpioConfig_In* in); \ingroup TPM2_Proprietary \brief Initializes a TPM with HAL IO callback and user supplied context. When using wolfTPM with --enable-devtpm or --enable-swtpm configuration, the ioCb and userCtx are not used. - Note: TPM2_Init_minimal() calls TPM2_Init_ex() with both ioCb and userCtx set to NULL. + \note TPM2_Init_minimal() calls TPM2_Init_ex() with both ioCb and userCtx set to NULL. In other modes, the ioCb shall be set in order to use TIS. Example ioCB for baremetal and RTOS applications are provided in examples/tpm_io.c @@ -2895,7 +2895,7 @@ WOLFTPM_API TPM_RC TPM2_Init(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx); /*! \ingroup TPM2_Proprietary \brief Initializes a TPM with timeoutTries, HAL IO callback and user supplied context. - Note: It is recommended to use TPM2_Init instead of using TPM2_Init_ex directly. + \note It is recommended to use TPM2_Init instead of using TPM2_Init_ex directly. \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: general error (possibly IO) @@ -2918,7 +2918,7 @@ WOLFTPM_API TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx, \ingroup TPM2_Proprietary \brief Initializes a TPM and sets the wolfTPM2 context that will be used. This function is typically used for rich operating systems, like Windows. - Note: It is recommended to use TPM2_Init instead of using TPM2_Init_minimal directly. + \note It is recommended to use TPM2_Init instead of using TPM2_Init_minimal directly. \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: general error (possibly IO) @@ -2939,7 +2939,7 @@ WOLFTPM_API TPM_RC TPM2_Init_minimal(TPM2_CTX* ctx); \return TPM_RC_FAILURE: could not acquire the lock on the wolfTPM2 context \return BAD_FUNC_ARG: the TPM2 device structure is a NULL pointer - \param dev pointer to a TPM2_DEV struct + \param ctx pointer to a TPM2_CTX struct _Example_ \code @@ -2963,7 +2963,7 @@ WOLFTPM_API TPM_RC TPM2_Cleanup(TPM2_CTX* ctx); /*! \ingroup TPM2_Proprietary \brief Makes sure the TPM2 startup has completed and extracts the TPM device information - Note: This function is used in TPM2_Init_ex + \note This function is used in TPM2_Init_ex \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: general error (possibly IO) @@ -2985,7 +2985,7 @@ WOLFTPM_API TPM_RC TPM2_ChipStartup(TPM2_CTX* ctx, int timeoutTries); \ingroup TPM2_Proprietary \brief Sets the user's context and IO callbacks needed for TPM communication \brief Typically, TPM2_Init or wolfTPM2_Init are used to set the HAL IO. - Note: SetHalIoCb will fail if built with devtpm or swtpm as the callback + \note SetHalIoCb will fail if built with devtpm or swtpm as the callback is not used for TPM. For other configuration builds, ioCb must be set to a non-NULL function pointer and userCtx is optional. @@ -3044,7 +3044,7 @@ WOLFTPM_API TPM_RC TPM2_SetSessionAuth(TPM2_AUTH_SESSION *session); \return the number of active TPM Authorizations (between one and three) \return BAD_FUNC_ARG: check the arguments provided for a NULL pointer - \param dev pointer to a TPM2_DEV struct + \param ctx pointer to a TPM2_CTX struct _Example_ \code @@ -3066,8 +3066,6 @@ WOLFTPM_API int TPM2_GetSessionAuthCount(TPM2_CTX* ctx); \ingroup TPM2_Proprietary \brief Sets a new TPM2 context for use - \return does not return a value - \param ctx pointer to a TPM2_CTX struct _Example_ @@ -3088,8 +3086,6 @@ WOLFTPM_API void TPM2_SetActiveCtx(TPM2_CTX* ctx); \return ctx pointer to a TPM2_CTX struct - \param takes no parameters - _Example_ \code TPM2_CTX *tpm2Ctx; @@ -3149,7 +3145,7 @@ WOLFTPM_API int TPM2_GetHashType(TPMI_ALG_HASH hashAlg); /*! \ingroup TPM2_Proprietary \brief Generate a fresh nonce of random numbers - Note: Can use the TPM random number generator if WOLFTPM2_USE_HW_RNG is defined + \note Can use the TPM random number generator if WOLFTPM2_USE_HW_RNG is defined \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: generic failure (TPM IO issue or wolfcrypt configuration) @@ -3174,9 +3170,7 @@ WOLFTPM_API int TPM2_GetNonce(byte* nonceBuf, int nonceSz); /*! \ingroup TPM2_Proprietary \brief Helper function to prepare a correct PCR selection - \brief For example, when preparing to create a TPM2_Quote - - \return has no return value + For example, when preparing to create a TPM2_Quote \param pcr pointer to a structure of type TPML_PCR_SELECTION \param alg value of type TPM_ALG_ID specifying the type of hash algorithm used @@ -3265,7 +3259,7 @@ WOLFTPM_API int TPM2_GetCurveSize(TPM_ECC_CURVE curveID); \return integer value representing a wolfcrypt curve type \return ECC_CURVE_OID_E in case of invalid curve type - \param curveIDnonceBuf pointer to a BYTE buffer + \param curveID pointer to a BYTE buffer _Example_ \code @@ -3290,7 +3284,7 @@ WOLFTPM_API int TPM2_GetTpmCurve(int curveID); \return integer value representing a TPM curve type \return -1 or ECC_CURVE_OID_E in case of invalid curve type - \param curveIDnonceBuf pointer to a BYTE buffer + \param curve_id pointer to a BYTE buffer _Example_ \code @@ -3311,7 +3305,7 @@ WOLFTPM_API int TPM2_GetWolfCurve(int curve_id); /*! \ingroup TPM2_Proprietary \brief Parses TPM2B_ATTEST and populates the data in TPMS_ATTEST structure - Note: This is public API of the helper function TPM2_Packet_ParseAttest + \note This is public API of the helper function TPM2_Packet_ParseAttest \return TPM_RC_SUCCESS: successful \return BAD_FUNC_ARG: check the provided arguments @@ -3362,7 +3356,7 @@ WOLFTPM_API int TPM2_HashNvPublic(TPMS_NV_PUBLIC* nvPublic, byte* buffer, UINT16 /*! \ingroup TPM2_Proprietary \brief Populates TPM2B_PUBLIC structure based on a user provided buffer - Note: Public API of the helper function TPM2_Packet_AppendPublic + \note Public API of the helper function TPM2_Packet_AppendPublic \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: insufficient buffer size @@ -3393,7 +3387,7 @@ WOLFTPM_API int TPM2_AppendPublic(byte* buf, word32 size, int* sizeUsed, TPM2B_P /*! \ingroup TPM2_Proprietary \brief Parses TPM2B_PUBLIC structure and stores in a user provided buffer - Note: Public API of the helper function TPM2_Packet_ParsePublic + \note Public API of the helper function TPM2_Packet_ParsePublic \return TPM_RC_SUCCESS: successful \return TPM_RC_FAILURE: insufficient buffer size @@ -3424,7 +3418,7 @@ WOLFTPM_API int TPM2_ParsePublic(TPM2B_PUBLIC* pub, byte* buf, word32 size, int* /*! \ingroup TPM2_Proprietary \brief Provides the Name of a TPM object - Note: The object is reference by its TPM handle and session index + \note The object is reference by its TPM handle and session index \return TPM_RC_SUCCESS: successful \return BAD_FUNC_ARG: check the provided arguments @@ -3468,13 +3462,11 @@ typedef enum { /*! \ingroup TPM2_Proprietary \brief Provides the vendorID of the active TPM2 context - Note: Depends on correctly read TPM device info during TPM Init + \note Depends on correctly read TPM device info during TPM Init \return integer value of UINT16 type, specifying the vendor ID \return 0 if TPM2 context is invalid or NULL - \param no parameters, uses the active TPM2 context - _Example_ \code TPM2_CTX *tpm2Ctx; @@ -3492,9 +3484,7 @@ WOLFTPM_API UINT16 TPM2_GetVendorID(void); /*! \ingroup TPM2_Proprietary \brief Helper function to print a binary buffer in a formated way - Note: Requires DEBUG_WOLFTPM to be defined - - \return does not return a value + \note Requires DEBUG_WOLFTPM to be defined \param buffer pointer to a buffer of BYTE type \param length integer value of word32 type, containing the size of the buffer @@ -3515,9 +3505,7 @@ WOLFTPM_API void TPM2_PrintBin(const byte* buffer, word32 length); /*! \ingroup TPM2_Proprietary \brief Helper function to print a structure of TPMS_AUTH_COMMAND type in a human readable way - Note: Requires DEBUG_WOLFTPM to be defined - - \return does not return a value + \note Requires DEBUG_WOLFTPM to be defined \param authCmd pointer to a populated structure of TPMS_AUTH_COMMAND type @@ -3536,9 +3524,7 @@ WOLFTPM_API void TPM2_PrintAuth(const TPMS_AUTH_COMMAND* authCmd); /*! \ingroup TPM2_Proprietary \brief Helper function to print a structure of TPM2B_PUBLIC type in a human readable way - Note: Requires DEBUG_WOLFTPM to be defined - - \return does not return a value + \note Requires DEBUG_WOLFTPM to be defined \param pub pointer to a populated structure of TPM2B_PUBLIC type diff --git a/wolftpm/tpm2_wrap.h b/wolftpm/tpm2_wrap.h index cbb78ff..84be8ec 100644 --- a/wolftpm/tpm2_wrap.h +++ b/wolftpm/tpm2_wrap.h @@ -28,13 +28,6 @@ extern "C" { #endif -typedef struct WOLFTPM2_HANDLE { - TPM_HANDLE hndl; - TPM2B_AUTH auth; - TPMT_SYM_DEF symmetric; - TPM2B_NAME name; -} WOLFTPM2_HANDLE; - #define TPM_SES_PWD 0xFF /* Session type for Password that fits in one byte */ typedef struct WOLFTPM2_SESSION { @@ -46,6 +39,13 @@ typedef struct WOLFTPM2_SESSION { TPMI_ALG_HASH authHash; } WOLFTPM2_SESSION; +typedef struct WOLFTPM2_HANDLE { + TPM_HANDLE hndl; + TPM2B_AUTH auth; + TPMT_SYM_DEF symmetric; + TPM2B_NAME name; +} WOLFTPM2_HANDLE; + typedef struct WOLFTPM2_DEV { TPM2_CTX ctx; TPM2_AUTH_SESSION session[MAX_SESSION_NUM]; @@ -141,7 +141,7 @@ typedef struct WOLFTPM2_CAPS { \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) \return BAD_FUNC_ARG: check the provided arguments - \param ioCB function pointer to a IO callback (see examples/tpm_io.h) + \param ioCb function pointer to a IO callback (see examples/tpm_io.h) \param userCtx pointer to a user context (can be NULL) \param caps to a structure of WOLFTPM2_CAPS type for returning the TPM capabilities (can be NULL) @@ -159,7 +159,7 @@ WOLFTPM_API int wolfTPM2_Test(TPM2HalIoCb ioCb, void* userCtx, WOLFTPM2_CAPS* ca \return BAD_FUNC_ARG: check the provided arguments \param dev pointer to an empty structure of WOLFTPM2_DEV type - \param ioCB function pointer to a IO callback (see examples/tpm_io.h) + \param ioCb function pointer to a IO callback (see examples/tpm_io.h) \param userCtx pointer to a user context (can be NULL) _Example_ @@ -189,7 +189,7 @@ WOLFTPM_API int wolfTPM2_Init(WOLFTPM2_DEV* dev, TPM2HalIoCb ioCb, void* userCtx \return BAD_FUNC_ARG: check the provided arguments \param dev pointer to an empty structure of WOLFTPM2_DEV type - \param ioCB function pointer to a IO callback (see examples/tpm_io.h) + \param ioCb function pointer to a IO callback (see examples/tpm_io.h) \param userCtx pointer to a user context (can be NULL) \sa wolfTPM2_Init @@ -469,6 +469,7 @@ WOLFTPM_API int wolfTPM2_SetAuthHandleName(WOLFTPM2_DEV* dev, int index, const W \param session pointer to an empty WOLFTPM2_SESSION struct \param tpmKey pointer to a WOLFTPM2_KEY that will be used as a salt for the session \param bind pointer to a WOLFTPM2_HANDLE that will be used to make the session bounded + \param sesType byte value, the session type (HMAC, Policy or Trial) \param encDecAlg integer value, specifying the algorithm in case of parameter encryption \sa wolfTPM2_SetAuthSession @@ -649,7 +650,7 @@ WOLFTPM_API int wolfTPM2_LoadPrivateKey(WOLFTPM2_DEV* dev, \param dev pointer to a TPM2_DEV struct \param parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys) - \param key pointer to an empty struct of WOLFTPM2_KEY type + \param keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type \param pub pointer to a populated structure of TPM2B_PUBLIC type \param sens pointer to a populated structure of TPM2B_SENSITIVE type @@ -672,7 +673,7 @@ WOLFTPM_API int wolfTPM2_ImportPrivateKey(WOLFTPM2_DEV* dev, \param dev pointer to a TPM2_DEV struct \param key pointer to an empty struct of WOLFTPM2_KEY type \param rsaPub pointer to a byte buffer containing the public key material - \param rsaPubsize integer value of word32 type, specifying the buffer size + \param rsaPubSz integer value of word32 type, specifying the buffer size \param exponent integer value of word32 type, specifying the RSA exponent \sa wolfTPM2_LoadRsaPublicKey_ex @@ -806,7 +807,7 @@ WOLFTPM_API int wolfTPM2_LoadRsaPrivateKey_ex(WOLFTPM2_DEV* dev, \param dev pointer to a TPM2_DEV struct \param key pointer to an empty struct of WOLFTPM2_KEY type - \param curveID integer value, one of the accepted TPM_ECC_CURVE values + \param curveId integer value, one of the accepted TPM_ECC_CURVE values \param eccPubX pointer to a byte buffer containing the public material of point X \param eccPubXSz integer value of word32 type, specifying the point X buffer size \param eccPubY pointer to a byte buffer containing the public material of point Y @@ -833,7 +834,7 @@ WOLFTPM_API int wolfTPM2_LoadEccPublicKey(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, \param dev pointer to a TPM2_DEV struct \param parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy) \param keyBlob pointer to an empty struct of WOLFTPM2_KEYBLOB type - \param curveID integer value, one of the accepted TPM_ECC_CURVE values + \param curveId integer value, one of the accepted TPM_ECC_CURVE values \param eccPubX pointer to a byte buffer containing the public material of point X \param eccPubXSz integer value of word32 type, specifying the point X buffer size \param eccPubY pointer to a byte buffer containing the public material of point Y @@ -862,7 +863,7 @@ WOLFTPM_API int wolfTPM2_ImportEccPrivateKey(WOLFTPM2_DEV* dev, \param dev pointer to a TPM2_DEV struct \param parentKey pointer to a struct of WOLFTPM2_HANDLE type (can be NULL for external keys and the key will be imported under the OWNER hierarchy) \param key pointer to an empty struct of WOLFTPM2_KEY type - \param curveID integer value, one of the accepted TPM_ECC_CURVE values + \param curveId integer value, one of the accepted TPM_ECC_CURVE values \param eccPubX pointer to a byte buffer containing the public material of point X \param eccPubXSz integer value of word32 type, specifying the point X buffer size \param eccPubY pointer to a byte buffer containing the public material of point Y @@ -951,7 +952,7 @@ WOLFTPM_API int wolfTPM2_ComputeName(const TPM2B_PUBLIC* pub, TPM2B_NAME* out); \return TPM_RC_FAILURE: generic failure (check TPM IO and TPM return code) \return BAD_FUNC_ARG: check the provided arguments - \param sense pointer to a correctly populated structure of TPM2B_SENSITIVE type + \param sens pointer to a correctly populated structure of TPM2B_SENSITIVE type \param priv pointer to an empty struct of TPM2B_PRIVATE type \param nameAlg integer value of TPMI_ALG_HASH type, specifying a valid TPM2 hashing algorithm \param name pointer to a TPM2B_NAME structure @@ -1232,7 +1233,7 @@ WOLFTPM_API int wolfTPM2_ECDHGenKey(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* ecdhKey, \param dev pointer to a TPM2_DEV struct \param privKey pointer to a structure of WOLFTPM2_KEY type - \param pubPointer pointer to an empty structure of TPM2B_ECC_POINT type + \param pubPoint pointer to an empty structure of TPM2B_ECC_POINT type \param out pointer to a byte buffer, to store the generated shared secret \param outSz integer value, specifying the size of the shared secret, in bytes @@ -1254,7 +1255,7 @@ WOLFTPM_API int wolfTPM2_ECDHGen(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* privKey, \param dev pointer to a TPM2_DEV struct \param privKey pointer to a structure of WOLFTPM2_KEY type, containing a valid TPM handle - \param pubPointer pointer to a populated structure of TPM2B_ECC_POINT type + \param pubPoint pointer to a populated structure of TPM2B_ECC_POINT type \param out pointer to a byte buffer, to store the computed shared secret \param outSz integer value, specifying the size of the shared secret, in bytes @@ -1347,7 +1348,6 @@ WOLFTPM_API int wolfTPM2_RsaEncrypt(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, \param in pointer to a byte buffer, containing the encrypted data \param inSz integer value, specifying the size of the encrypted data buffer \param msg pointer to a byte buffer, containing the decrypted data - \param msgSz[in,out] integer value, specifying the size of the encrypted data buffer \param[in,out] msgSz pointer to size of the encrypted data buffer, on return set actual size \sa wolfTPM2_RsaEcnrypt @@ -1369,7 +1369,7 @@ WOLFTPM_API int wolfTPM2_RsaDecrypt(WOLFTPM2_DEV* dev, WOLFTPM2_KEY* key, \param pcrIndex integer value, specifying a valid PCR index, between 0 and 23 (TPM locality could have an impact on successful access) \param hashAlg integer value, specifying a TPM_ALG_SHA256 or TPM_ALG_SHA1 registers to be accessed \param digest pointer to a byte buffer, where the PCR values will be stored - \param pDigestLen pointer to an integer variable, where the size of the digest buffer will be stored + \param[in,out] pDigestLen pointer to an integer variable, where the size of the digest buffer will be stored \sa wolfTPM2_ExtendPCR */ @@ -1851,7 +1851,7 @@ WOLFTPM_API int wolfTPM2_SetCommand(WOLFTPM2_DEV* dev, TPM_CC commandCode, \return BAD_FUNC_ARG: check the provided arguments \param dev pointer to a TPM2_DEV struct - \param enableFlag integer value, non-zero values represent "perform Startup after Shutdown" + \param doStartup integer value, non-zero values represent "perform Startup after Shutdown" \sa wolfTPM2_Init */ @@ -1867,7 +1867,7 @@ WOLFTPM_API int wolfTPM2_Shutdown(WOLFTPM2_DEV* dev, int doStartup); \param dev pointer to a TPM2_DEV struct \param handleStart integer value of word32 type, specifying the value of the first TPM handle - \param handleStart integer value of word32 type, specifying the value of the last TPM handle + \param handleCount integer value of word32 type, specifying the number of handles \sa wolfTPM2_Init */ @@ -1980,7 +1980,7 @@ WOLFTPM_API int wolfTPM2_GetKeyTemplate_KeyedHash(TPMT_PUBLIC* publicTemplate, \return BAD_FUNC_ARG: check the provided arguments \param publicTemplate pointer to an empty structure of TPMT_PUBLIC type, to store the new template - \param hashAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, typically TPM_ALG_SHA256 for SHA 256 + \param nameAlg integer value of TPM_ALG_ID type, specifying a TPM supported hashing algorithm, typically TPM_ALG_SHA256 for SHA 256 \sa wolfTPM2_GetKeyTemplate_ECC \sa wolfTPM2_GetKeyTemplate_Symmetric