Improved documentation for sniffer statistics (ZD 12731).

src/sniffer.c

@@ -2189,6 +2189,9 @@ static int SetupKeys(const byte* input, int* sslBytes, SnifferSession* session,
             ret = wc_RsaPrivateKeyDecode(keyBuf->buffer, &idx, &key, keyBuf->length);
             if (ret != 0) {
             #ifndef HAVE_ECC
+                #ifdef WOLFSSL_SNIFFER_STATS
+                INC_STAT(SnifferStats.sslKeyFails);
+                #endif
                 SetError(RSA_DECODE_STR, error, session, FATAL_ERROR_STATE);
             #else
                 /* If we can do ECC, this isn't fatal. Not loading an ECC
@@ -2342,6 +2345,11 @@ static int SetupKeys(const byte* input, int* sslBytes, SnifferSession* session,
 
             wc_FreeDhKey(&dhKey);
         
+
+        #ifdef WOLFSSL_SNIFFER_STATS
+            if (ret != 0)
+                INC_STAT(SnifferStats.sslKeyFails);
+        #endif
             /* left-padded with zeros up to the size of the prime */
             if (params->p_len > session->sslServer->arrays->preMasterSz) {
                 word32 diff = params->p_len - session->sslServer->arrays->preMasterSz;

sslSniffer/README.md

@@ -404,25 +404,23 @@ See the header file `sniffer.h` for the structure `SSLStats` for the list of sta
 ```c
 typedef struct SSLStats
 {
-    unsigned long int sslStandardConns;
+    unsigned long int sslStandardConns;      /* server_hello count not including resumed sessions */
-    unsigned long int sslClientAuthConns;
+    unsigned long int sslClientAuthConns;    /* client's who have presented certificates (mutual authentication) */
-    unsigned long int sslResumedConns;
+    unsigned long int sslResumedConns;       /* resumed connections */
-    unsigned long int sslEphemeralMisses;
+    unsigned long int sslEphemeralMisses;    /* TLS v1.2 and older PFS / ephemeral connections missed (not able to decrypt) */
-    unsigned long int sslResumeMisses;
+    unsigned long int sslResumeMisses;       /* Resumption sessions not found */
-    unsigned long int sslCiphersUnsupported;
+    unsigned long int sslCiphersUnsupported; /* No cipher suite match found when compared to supported */
-    unsigned long int sslKeysUnmatched;
+    unsigned long int sslKeysUnmatched;      /* Key callback failures (not found). Applies to WOLFSSL_SNIFFER_WATCH only */
-    unsigned long int sslKeyFails;
+    unsigned long int sslKeyFails;           /* Failures loading or using keys */
-    unsigned long int sslDecodeFails;
+    unsigned long int sslDecodeFails;        /* Dropped packets (not application_data or match protocol version) */
-    unsigned long int sslAlerts;
+    unsigned long int sslAlerts;             /* Number of decoded alert messages */
-    unsigned long int sslDecryptedBytes;
+    unsigned long int sslDecryptedBytes;     /* Number of decrypted bytes */
-    unsigned long int sslEncryptedBytes;
+    unsigned long int sslEncryptedBytes;     /* Number of encrypted bytes */
-    unsigned long int sslEncryptedPackets;
+    unsigned long int sslEncryptedPackets;   /* Number of encrypted packets */
-    unsigned long int sslDecryptedPackets;
+    unsigned long int sslDecryptedPackets;   /* Number of decrypted packets */
-    unsigned long int sslKeyMatches;
+    unsigned long int sslKeyMatches;         /* Key callback successes (failures tracked in sslKeysUnmatched). Applies to WOLFSSL_SNIFFER_WATCH only. */
-    unsigned long int sslEncryptedConns;
+    unsigned long int sslEncryptedConns;     /* Number of created sniffer sessions */
-
+    unsigned long int sslResumptionInserts;  /* Number of sessions reused with resumption */
-    unsigned long int sslResumptionValid;
-    unsigned long int sslResumptionInserts;
 } SSLStats;
 ```
 

wolfssl/sniffer.h

@@ -167,46 +167,45 @@ SSL_SNIFFER_API int ssl_SetConnectionCtx(void* ctx);
 
 typedef struct SSLStats
 {
-    unsigned long int sslStandardConns;
+    unsigned long int sslStandardConns;      /* server_hello count not including resumed sessions */
-    unsigned long int sslClientAuthConns;
+    unsigned long int sslClientAuthConns;    /* client's who have presented certificates (mutual authentication) */
-    unsigned long int sslResumedConns;
+    unsigned long int sslResumedConns;       /* resumed connections */
-    unsigned long int sslEphemeralMisses;
+    unsigned long int sslEphemeralMisses;    /* TLS v1.2 and older PFS / ephemeral connections missed (not able to decrypt) */
-    unsigned long int sslResumeMisses;
+    unsigned long int sslResumeMisses;       /* Resumption sessions not found */
-    unsigned long int sslCiphersUnsupported;
+    unsigned long int sslCiphersUnsupported; /* No cipher suite match found when compared to supported */
-    unsigned long int sslKeysUnmatched;
+    unsigned long int sslKeysUnmatched;      /* Key callback failures (not found). Applies to WOLFSSL_SNIFFER_WATCH only */
-    unsigned long int sslKeyFails;
+    unsigned long int sslKeyFails;           /* Failures loading or using keys */
-    unsigned long int sslDecodeFails;
+    unsigned long int sslDecodeFails;        /* Dropped packets (not application_data or match protocol version) */
-    unsigned long int sslAlerts;
+    unsigned long int sslAlerts;             /* Number of decoded alert messages */
-    unsigned long int sslDecryptedBytes;
+    unsigned long int sslDecryptedBytes;     /* Number of decrypted bytes */
-    unsigned long int sslEncryptedBytes;
+    unsigned long int sslEncryptedBytes;     /* Number of encrypted bytes */
-    unsigned long int sslEncryptedPackets;
+    unsigned long int sslEncryptedPackets;   /* Number of encrypted packets */
-    unsigned long int sslDecryptedPackets;
+    unsigned long int sslDecryptedPackets;   /* Number of decrypted packets */
-    unsigned long int sslKeyMatches;
+    unsigned long int sslKeyMatches;         /* Key callback successes (failures tracked in sslKeysUnmatched). Applies to WOLFSSL_SNIFFER_WATCH only. */
-    unsigned long int sslEncryptedConns;
+    unsigned long int sslEncryptedConns;     /* Number of created sniffer sessions */
-    unsigned long int sslResumptionInserts;
+    unsigned long int sslResumptionInserts;  /* Number of sessions reused with resumption */
 } SSLStats;
 
-
 WOLFSSL_API
 SSL_SNIFFER_API int ssl_ResetStatistics(void);
 
-
 WOLFSSL_API
 SSL_SNIFFER_API int ssl_ReadStatistics(SSLStats* stats);
 
-
 WOLFSSL_API
 SSL_SNIFFER_API int ssl_ReadResetStatistics(SSLStats* stats);
 
+
+#if defined(WOLFSSL_STATIC_EPHEMERAL) && defined(WOLFSSL_TLS13)
+/* macro indicating support for key callback */
+#undef  WOLFSSL_SNIFFER_KEY_CALLBACK
+#define WOLFSSL_SNIFFER_KEY_CALLBACK
+
 typedef int (*SSLKeyCb)(void* vSniffer, int namedGroup,
     const unsigned char* srvPub, unsigned int srvPubSz,
     const unsigned char* cliPub, unsigned int cliPubSz,
     DerBuffer* privKey, void* cbCtx, char* error);
 
-#if defined(WOLFSSL_STATIC_EPHEMERAL) && defined(WOLFSSL_TLS13)
-/* macro indicating support for key callback */
-#undef  WOLFSSL_SNIFFER_KEY_CALLBACK
-#define WOLFSSL_SNIFFER_KEY_CALLBACK
 WOLFSSL_API 
 SSL_SNIFFER_API int ssl_SetKeyCallback(SSLKeyCb cb, void* cbCtx);
 #endif