Merge pull request #126 from elms/init_cleanup_document

Reduce Init_ex code and add documention on `ioCb` and `userCtx`

src/tpm2.c

@@ -304,7 +304,7 @@ TPM_RC TPM2_SetHalIoCb(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx)
 {
     TPM_RC rc;
 
-    if (ctx == NULL) {
+    if (ctx == NULL || ioCb == NULL) {
         return BAD_FUNC_ARG;
     }
 
@@ -324,9 +324,9 @@ TPM_RC TPM2_SetHalIoCb(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx)
 TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx,
     int timeoutTries)
 {
-    TPM_RC rc;
+    TPM_RC rc = TPM_RC_SUCCESS;
 
-    if (ctx == NULL || ioCb == NULL) {
+    if (ctx == NULL) {
         return BAD_FUNC_ARG;
     }
 
@@ -336,10 +336,16 @@ TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx,
     TPM2_WolfCrypt_Init();
 #endif
 
+    #if defined(WOLFTPM_LINUX_DEV) || defined(WOLFTPM_SWTPM)
+    if (ioCb != NULL || userCtx != NULL) {
+        return BAD_FUNC_ARG;
+    }
+    #else
     /* Setup HAL IO Callback */
     rc = TPM2_SetHalIoCb(ctx, ioCb, userCtx);
     if (rc != TPM_RC_SUCCESS)
-        return rc;
+      return rc;
+    #endif
 
     /* Set the active TPM global */
     TPM2_SetActiveCtx(ctx);
@@ -358,25 +364,7 @@ TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx,
 
 TPM_RC TPM2_Init_minimal(TPM2_CTX* ctx)
 {
-    TPM_RC rc = TPM_RC_SUCCESS;
+    return TPM2_Init_ex(ctx, NULL, NULL, 0);
-
-    if (ctx == NULL) {
-        return BAD_FUNC_ARG;
-    }
-
-    XMEMSET(ctx, 0, sizeof(TPM2_CTX));
-
-#ifndef WOLFTPM2_NO_WOLFCRYPT
-    TPM2_WolfCrypt_Init();
-#endif
-
-    /* Set the active TPM global */
-    TPM2_SetActiveCtx(ctx);
-
-    /* Use existing locality */
-    ctx->locality = WOLFTPM_LOCALITY_DEFAULT;
-
-    return rc;
 }
 
 TPM_RC TPM2_Init(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx)

src/tpm2_wrap.c

@@ -51,10 +51,9 @@ static int wolfTPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx,
 
 #if defined(WOLFTPM_LINUX_DEV) || defined(WOLFTPM_SWTPM)
     rc = TPM2_Init_minimal(ctx);
-    ctx->userCtx = userCtx;
-
     /* Using standard file I/O for the Linux TPM device */
     (void)ioCb;
+    (void)userCtx;
     (void)timeoutTries;
 #else
     rc = TPM2_Init_ex(ctx, ioCb, userCtx, timeoutTries);
@@ -175,7 +174,7 @@ int wolfTPM2_OpenExisting(WOLFTPM2_DEV* dev, TPM2HalIoCb ioCb, void* userCtx)
     XMEMSET(dev, 0, sizeof(WOLFTPM2_DEV));
 
     /* The 0 startup indicates use existing locality */
-    rc = TPM2_Init_ex(&dev->ctx, ioCb, userCtx, 0);
+    rc = wolfTPM2_Init_ex(&dev->ctx, ioCb, userCtx, 0);
     if (rc != TPM_RC_SUCCESS) {
     #ifdef DEBUG_WOLFTPM
         printf("TPM2_Init failed %d: %s\n", rc, wolfTPM2_GetRCString(rc));

wolftpm/tpm2.h

@@ -2745,6 +2745,12 @@ WOLFTPM_API int TPM2_SetMode(SetMode_In* in);
 
 /* Non-standard API's */
 #define _TPM_Init TPM2_Init
+/* In when using devtpm or swtpm, the ioCb and userCtx are not used
+ * and must be set to NULL. TPM2_Init_minimal() call TPM2_Init_ex()
+ * with them set to NULL.
+ *
+ * In other modes, the ioCb shall be set in order to use TIS.
+ */
 WOLFTPM_API TPM_RC TPM2_Init(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx);
 WOLFTPM_API TPM_RC TPM2_Init_ex(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx,
     int timeoutTries);
@@ -2753,6 +2759,10 @@ WOLFTPM_API TPM_RC TPM2_Cleanup(TPM2_CTX* ctx);
 
 /* Other API's - Not in TPM Specification */
 WOLFTPM_API TPM_RC TPM2_ChipStartup(TPM2_CTX* ctx, int timeoutTries);
+/* 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.
+ */
 WOLFTPM_API TPM_RC TPM2_SetHalIoCb(TPM2_CTX* ctx, TPM2HalIoCb ioCb, void* userCtx);
 WOLFTPM_API TPM_RC TPM2_SetSessionAuth(TPMS_AUTH_COMMAND *cmd);
 

wolftpm/tpm2_wrap.h

@@ -105,9 +105,11 @@ typedef struct WOLFTPM2_CAPS {
 
 
 /* Wrapper API's to simplify TPM use */
+/* For devtpm and swtpm builds, the ioCb and userCtx are not used and should be set to NULL */
 WOLFTPM_API int wolfTPM2_Test(TPM2HalIoCb ioCb, void* userCtx, WOLFTPM2_CAPS* caps);
 WOLFTPM_API int wolfTPM2_Init(WOLFTPM2_DEV* dev, TPM2HalIoCb ioCb, void* userCtx);
 WOLFTPM_API int wolfTPM2_OpenExisting(WOLFTPM2_DEV* dev, TPM2HalIoCb ioCb, void* userCtx);
+
 WOLFTPM_API int wolfTPM2_Cleanup(WOLFTPM2_DEV* dev);
 WOLFTPM_API int wolfTPM2_Cleanup_ex(WOLFTPM2_DEV* dev, int doShutdown);