Add more in depth comments in header file for she.h

Author: night1rider

.wolfssl_known_macro_extras

@@ -888,9 +888,9 @@ WOLFSSL_SE050_NO_TRNG
 WOLFSSL_SECURE_RENEGOTIATION_ON_BY_DEFAULT
 WOLFSSL_SERVER_EXAMPLE
 WOLFSSL_SETTINGS_FILE
+WOLFSSL_SH224
 WOLFSSL_SHE
 WOLFSSL_SHE_EXTENDED
-WOLFSSL_SH224
 WOLFSSL_SHA256_ALT_CH_MAJ
 WOLFSSL_SHA512_HASHTYPE
 WOLFSSL_SHUTDOWNONCE

tests/api/test_she.c

@@ -428,7 +428,7 @@ int test_wc_SHE_SetM2M4Header(void)
 
 #if defined(WOLF_CRYPTO_CB) && defined(WOLFSSL_SHE) && !defined(NO_AES)
 
-/* SHE callback — re-calls with software devId */
+/* SHE callback -- re-calls with software devId */
 static int test_she_crypto_cb(int devIdArg, wc_CryptoInfo* info, void* ctx)
 {
     wc_SHE* she;
@@ -513,7 +513,7 @@ static int test_she_crypto_cb(int devIdArg, wc_CryptoInfo* info, void* ctx)
                       info->she.op.generateM4M5.m5Sz);
             break;
         case WC_SHE_EXPORT_KEY:
-            /* Simulate hardware export — fill with test pattern */
+            /* Simulate hardware export -- fill with test pattern */
             if (info->she.op.exportKey.m1 != NULL) {
                 XMEMSET(info->she.op.exportKey.m1, 0x11, WC_SHE_M1_SZ);
             }
@@ -572,7 +572,7 @@ int test_wc_SHE_CryptoCb(void)
     ExpectIntEQ(XMEMCMP(m4, sheTestExpM4, WC_SHE_M4_SZ), 0);
     ExpectIntEQ(XMEMCMP(m5, sheTestExpM5, WC_SHE_M5_SZ), 0);
 
-    /* ExportKey via callback — simulated hardware */
+    /* ExportKey via callback -- simulated hardware */
 #if !defined(NO_WC_SHE_EXPORTKEY)
     {
         byte em1[WC_SHE_M1_SZ];

wolfcrypt/src/she.c

@@ -123,7 +123,7 @@ int wc_SHE_Init(wc_SHE* she, void* heap, int devId)
     ForceZero(she, sizeof(wc_SHE));
     she->heap  = heap;
     she->devId = devId;
-    /* kdfEncOverride/kdfMacOverride are zero from XMEMSET — defaults used */
+    /* kdfEncOverride/kdfMacOverride are zero from XMEMSET -- defaults used */
 
     return 0;
 }
@@ -222,7 +222,7 @@ void wc_SHE_Free(wc_SHE* she)
 }
 
 /* -------------------------------------------------------------------------- */
-/* GetUID — callback required                                                 */
+/* GetUID -- callback required                                                 */
 /*                                                                            */
 /* Dispatches to callback to fetch UID from hardware.                        */
 /* Buffer size validation is the callback's responsibility.                  */
@@ -241,7 +241,7 @@ int wc_SHE_GetUID(wc_SHE* she, byte* uid, word32 uidSz,
 #endif /* WOLF_CRYPTO_CB && !NO_WC_SHE_GETUID */
 
 /* -------------------------------------------------------------------------- */
-/* GetCounter — callback required                                             */
+/* GetCounter -- callback required                                             */
 /*                                                                            */
 /* Dispatches to callback to read current counter from hardware.             */
 /* Returns CRYPTOCB_UNAVAILABLE if no callback.                              */
@@ -425,13 +425,13 @@ int wc_SHE_GenerateM1M2M3(wc_SHE* she,
     WC_DECLARE_VAR(aes, Aes, 1, 0);
     WC_DECLARE_VAR(cmac, Cmac, 1, 0);
 
-    /* Validate SHE context first — required for both callback and software */
+    /* Validate SHE context first -- required for both callback and software */
     if (she == NULL) {
         return BAD_FUNC_ARG;
     }
 
 #ifdef WOLF_CRYPTO_CB
-    /* Try callback first — callback handles its own parameter validation.
+    /* Try callback first -- callback handles its own parameter validation.
      * This allows callers to pass NULL authKey/newKey when a secure element
      * holds the keys and the callback talks to it directly. */
     if (she->devId != INVALID_DEVID) {
@@ -448,7 +448,7 @@ int wc_SHE_GenerateM1M2M3(wc_SHE* she,
     }
 #endif
 
-    /* Software path — validate all parameters */
+    /* Software path -- validate all parameters */
     if (uid == NULL || uidSz != WC_SHE_UID_SZ ||
         authKey == NULL || authKeySz != WC_SHE_KEY_SZ ||
         newKey == NULL || newKeySz != WC_SHE_KEY_SZ ||
@@ -482,7 +482,7 @@ int wc_SHE_GenerateM1M2M3(wc_SHE* she,
         return MEMORY_E;
     }
 
-    /* Init AES once — used by both MP16 and CBC */
+    /* Init AES once -- used by both MP16 and CBC */
     ret = wc_AesInit(aes, she->heap, she->devId);
     if (ret != 0) {
         WC_FREE_VAR(aes, she->heap);
@@ -584,7 +584,7 @@ int wc_SHE_GenerateM4M5(wc_SHE* she,
     }
 
 #ifdef WOLF_CRYPTO_CB
-    /* Try callback first — useful for uploading M1/M2/M3 to an HSM which
+    /* Try callback first -- useful for uploading M1/M2/M3 to an HSM which
      * loads the key and returns the correct M4/M5 proof values.  The callback
      * handles its own parameter validation. */
     if (she->devId != INVALID_DEVID) {
@@ -599,7 +599,7 @@ int wc_SHE_GenerateM4M5(wc_SHE* she,
     }
 #endif
 
-    /* Software path — validate all parameters */
+    /* Software path -- validate all parameters */
     if (uid == NULL || uidSz != WC_SHE_UID_SZ ||
         newKey == NULL || newKeySz != WC_SHE_KEY_SZ ||
         m4 == NULL || m4Sz < WC_SHE_M4_SZ ||
@@ -631,7 +631,7 @@ int wc_SHE_GenerateM4M5(wc_SHE* she,
         return MEMORY_E;
     }
 
-    /* Init AES once — used by both MP16 and ECB */
+    /* Init AES once -- used by both MP16 and ECB */
     ret = wc_AesInit(aes, she->heap, she->devId);
     if (ret != 0) {
         WC_FREE_VAR(aes, she->heap);
@@ -700,7 +700,7 @@ int wc_SHE_GenerateM4M5(wc_SHE* she,
 /* -------------------------------------------------------------------------- */
 #if defined(WOLF_CRYPTO_CB) && !defined(NO_WC_SHE_EXPORTKEY)
 /* -------------------------------------------------------------------------- */
-/* Export Key — callback required                                             */
+/* Export Key -- callback required                                             */
 /*                                                                            */
 /* Asks hardware to export a key slot as M1-M5 in SHE loadable format.       */
 /* -------------------------------------------------------------------------- */

wolfcrypt/test/test.c

@@ -55733,14 +55733,15 @@ WOLFSSL_TEST_SUBROUTINE wc_test_ret_t she_test(void)
         goto exit_SHE_Test;
     }
 
+#if defined(WOLF_CRYPTO_CB) || !defined(NO_WC_SHE_IMPORT_M123)
     /* ---- Import M1/M2/M3 and generate M4/M5 (only NewKey needed) ---- */
     wc_SHE_Free(she);
     ret = wc_SHE_Init(she, HEAP_HINT, devId);
     if (ret != 0) {
         goto exit_SHE_Test;
     }
 
-    /* Import M1/M2/M3, then generate M4/M5 via one-shot */
+    /* Import M1/M2/M3, then generate M4/M5 */
     ret = wc_SHE_ImportM1M2M3(she,
                                 expM1, WC_SHE_M1_SZ,
                                 expM2, WC_SHE_M2_SZ,
@@ -55767,6 +55768,7 @@ WOLFSSL_TEST_SUBROUTINE wc_test_ret_t she_test(void)
         ret = WC_TEST_RET_ENC_NC;
         goto exit_SHE_Test;
     }
+#endif /* WOLF_CRYPTO_CB || !NO_WC_SHE_IMPORT_M123 */
 
     /* ---- One-shot M1/M2/M3 ---- */
     wc_SHE_Free(she);
@@ -55858,7 +55860,7 @@ WOLFSSL_TEST_SUBROUTINE wc_test_ret_t she_test(void)
         goto exit_SHE_Test;
     }
 
-    /* Generate M4/M5 on second context — completely independent */
+    /* Generate M4/M5 on second context -- completely independent */
     ret = wc_SHE_GenerateM4M5(she2,
               sheUid, sizeof(sheUid),
               WC_SHE_MASTER_ECU_KEY_ID, 4,
@@ -65989,7 +65991,7 @@ static int myCryptoDevCb(int devIdArg, wc_CryptoInfo* info, void* ctx)
                           info->she.op.generateM4M5.m5Sz);
                 break;
             case WC_SHE_EXPORT_KEY:
-                /* Simulate hardware export — fill with test pattern */
+                /* Simulate hardware export -- fill with test pattern */
                 if (info->she.op.exportKey.m1 != NULL) {
                     XMEMSET(info->she.op.exportKey.m1, 0x11,
                             WC_SHE_M1_SZ);