sniffer.h (12970B)
1 /* sniffer.h 2 * 3 * Copyright (C) 2006-2025 wolfSSL Inc. 4 * 5 * This file is part of wolfSSL. 6 * 7 * wolfSSL is free software; you can redistribute it and/or modify 8 * it under the terms of the GNU General Public License as published by 9 * the Free Software Foundation; either version 3 of the License, or 10 * (at your option) any later version. 11 * 12 * wolfSSL is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15 * GNU General Public License for more details. 16 * 17 * You should have received a copy of the GNU General Public License 18 * along with this program; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA 20 */ 21 22 23 24 #ifndef WOLFSSL_SNIFFER_H 25 #define WOLFSSL_SNIFFER_H 26 27 #include <wolfssl/wolfcrypt/settings.h> 28 #include <wolfssl/wolfcrypt/asn_public.h> 29 30 #ifdef HAVE_WOLF_EVENT 31 #include <wolfssl/wolfcrypt/wolfevent.h> 32 #endif 33 34 35 #ifdef _WIN32 36 #ifdef SSL_SNIFFER_EXPORTS 37 #define SSL_SNIFFER_API __declspec(dllexport) 38 #else 39 #define SSL_SNIFFER_API __declspec(dllimport) 40 #endif 41 #else 42 #define SSL_SNIFFER_API 43 #endif /* _WIN32 */ 44 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 51 typedef struct IpAddrInfo { 52 int version; 53 union { 54 word32 ip4; 55 byte ip6[16]; 56 }; 57 } IpAddrInfo; 58 59 typedef struct SnifferStreamInfo { 60 IpAddrInfo src; /* server address in network byte order */ 61 IpAddrInfo dst; /* client address in network byte order */ 62 word16 dstPort; /* server port */ 63 word16 srcPort; /* client port */ 64 } SnifferStreamInfo; 65 66 /* @param typeK: (formerly keyType) was shadowing a global declaration in 67 * wolfssl/wolfcrypt/asn.h line 175 68 */ 69 WOLFSSL_API 70 SSL_SNIFFER_API int ssl_SetPrivateKey(const char* address, int port, 71 const char* keyFile, int typeK, 72 const char* password, char* error); 73 74 WOLFSSL_API 75 SSL_SNIFFER_API int ssl_SetPrivateKeyBuffer(const char* address, int port, 76 const char* keyBuf, int keySz, 77 int typeK, const char* password, 78 char* error); 79 80 81 WOLFSSL_API 82 SSL_SNIFFER_API int ssl_SetNamedPrivateKey(const char* name, 83 const char* address, int port, 84 const char* keyFile, int typeK, 85 const char* password, char* error); 86 87 WOLFSSL_API 88 SSL_SNIFFER_API int ssl_SetNamedPrivateKeyBuffer(const char* name, 89 const char* address, int port, 90 const char* keyBuf, int keySz, 91 int typeK, const char* password, 92 char* error); 93 94 WOLFSSL_API 95 SSL_SNIFFER_API int ssl_SetEphemeralKey(const char* address, int port, 96 const char* keyFile, int typeKey, 97 const char* password, char* error); 98 99 WOLFSSL_API 100 SSL_SNIFFER_API int ssl_SetEphemeralKeyBuffer(const char* address, int port, 101 const char* keyBuf, int keySz, int typeKey, 102 const char* password, char* error); 103 104 105 WOLFSSL_API 106 SSL_SNIFFER_API int ssl_SetNamedEphemeralKey(const char* name, 107 const char* address, int port, 108 const char* keyFile, int typeKey, 109 const char* password, char* error); 110 111 WOLFSSL_API 112 SSL_SNIFFER_API int ssl_SetNamedEphemeralKeyBuffer(const char* name, 113 const char* address, int port, 114 const char* keyBuf, int keySz, int typeKey, 115 const char* password, char* error); 116 117 WOLFSSL_API 118 SSL_SNIFFER_API int ssl_DecodePacket(const unsigned char* packet, int length, 119 unsigned char** data, char* error); 120 121 WOLFSSL_API 122 SSL_SNIFFER_API int ssl_FreeDecodeBuffer(unsigned char** data, char* error); 123 124 WOLFSSL_API 125 SSL_SNIFFER_API int ssl_FreeZeroDecodeBuffer(unsigned char** data, int sz, 126 char* error); 127 128 WOLFSSL_API 129 SSL_SNIFFER_API int ssl_Trace(const char* traceFile, char* error); 130 131 WOLFSSL_API 132 SSL_SNIFFER_API int ssl_EnableRecovery(int onOff, int maxMemory, char* error); 133 134 WOLFSSL_API 135 SSL_SNIFFER_API int ssl_GetSessionStats(unsigned int* active, 136 unsigned int* total, 137 unsigned int* peak, 138 unsigned int* maxSessions, 139 unsigned int* missedData, 140 unsigned int* reassemblyMemory, 141 char* error); 142 143 WOLFSSL_API 144 SSL_SNIFFER_API void ssl_InitSniffer(void); 145 WOLFSSL_API 146 SSL_SNIFFER_API void ssl_InitSniffer_ex(int devId); 147 WOLFSSL_API 148 SSL_SNIFFER_API void ssl_InitSniffer_ex2(int threadNum); 149 150 WOLFSSL_API 151 SSL_SNIFFER_API void ssl_FreeSniffer(void); 152 153 WOLFSSL_API 154 SSL_SNIFFER_API void ssl_RemoveStaleSessions(void); 155 156 /* ssl_SetPrivateKey typeKs */ 157 enum { 158 FILETYPE_PEM = 1, 159 FILETYPE_DER = 2, 160 }; 161 162 163 /* 164 * New Sniffer API that provides read-only access to the TLS and cipher 165 * information associated with the SSL session. 166 */ 167 168 typedef struct SSLInfo 169 { 170 unsigned char isValid; 171 /* indicates if the info in this struct is valid: 0 = no, 1 = yes */ 172 unsigned char protocolVersionMajor; /* SSL Version: major */ 173 unsigned char protocolVersionMinor; /* SSL Version: minor */ 174 unsigned char serverCipherSuite0; /* first byte, normally 0 */ 175 unsigned char serverCipherSuite; /* second byte, actual suite */ 176 unsigned char serverCipherSuiteName[256]; 177 /* cipher name, e.g., "TLS_RSA_..." */ 178 unsigned char serverNameIndication[128]; 179 unsigned int keySize; 180 } SSLInfo; 181 182 183 WOLFSSL_API 184 SSL_SNIFFER_API int ssl_DecodePacketWithSessionInfo( 185 const unsigned char* packet, int length, 186 unsigned char** data, SSLInfo* sslInfo, char* error); 187 188 typedef void (*SSLConnCb)(const void* session, SSLInfo* info, void* ctx); 189 190 WOLFSSL_API 191 SSL_SNIFFER_API int ssl_SetConnectionCb(SSLConnCb cb); 192 193 WOLFSSL_API 194 SSL_SNIFFER_API int ssl_SetConnectionCtx(void* ctx); 195 196 197 typedef struct SSLStats 198 { 199 unsigned long int sslStandardConns; /* server_hello count not including resumed sessions */ 200 unsigned long int sslClientAuthConns; /* client's who have presented certificates (mutual authentication) */ 201 unsigned long int sslResumedConns; /* resumed connections */ 202 unsigned long int sslEphemeralMisses; /* TLS v1.2 and older PFS / ephemeral connections missed (not able to decrypt) */ 203 unsigned long int sslResumeMisses; /* Resumption sessions not found */ 204 unsigned long int sslCiphersUnsupported; /* No cipher suite match found when compared to supported */ 205 unsigned long int sslKeysUnmatched; /* Key callback failures (not found). Applies to WOLFSSL_SNIFFER_WATCH only */ 206 unsigned long int sslKeyFails; /* Failures loading or using keys */ 207 unsigned long int sslDecodeFails; /* Dropped packets (not application_data or match protocol version) */ 208 unsigned long int sslAlerts; /* Number of decoded alert messages */ 209 unsigned long int sslDecryptedBytes; /* Number of decrypted bytes */ 210 unsigned long int sslEncryptedBytes; /* Number of encrypted bytes */ 211 unsigned long int sslEncryptedPackets; /* Number of encrypted packets */ 212 unsigned long int sslDecryptedPackets; /* Number of decrypted packets */ 213 unsigned long int sslKeyMatches; /* Key callback successes (failures tracked in sslKeysUnmatched). Applies to WOLFSSL_SNIFFER_WATCH only. */ 214 unsigned long int sslEncryptedConns; /* Number of created sniffer sessions */ 215 unsigned long int sslResumptionInserts; /* Number of sessions reused with resumption */ 216 } SSLStats; 217 218 WOLFSSL_API 219 SSL_SNIFFER_API int ssl_ResetStatistics(void); 220 221 WOLFSSL_API 222 SSL_SNIFFER_API int ssl_ReadStatistics(SSLStats* stats); 223 224 WOLFSSL_API 225 SSL_SNIFFER_API int ssl_ReadResetStatistics(SSLStats* stats); 226 227 228 #if defined(WOLFSSL_STATIC_EPHEMERAL) && defined(WOLFSSL_TLS13) 229 /* macro indicating support for key callback */ 230 #undef WOLFSSL_SNIFFER_KEY_CALLBACK 231 #define WOLFSSL_SNIFFER_KEY_CALLBACK 232 233 typedef int (*SSLKeyCb)(void* vSniffer, int namedGroup, 234 const unsigned char* srvPub, unsigned int srvPubSz, 235 const unsigned char* cliPub, unsigned int cliPubSz, 236 DerBuffer* privKey, void* cbCtx, char* error); 237 238 WOLFSSL_API 239 SSL_SNIFFER_API int ssl_SetKeyCallback(SSLKeyCb cb, void* cbCtx); 240 #endif 241 242 243 #ifdef WOLFSSL_SNIFFER_WATCH 244 typedef int (*SSLWatchCb)(void* vSniffer, 245 const unsigned char* certHash, 246 unsigned int certHashSz, 247 const unsigned char* certChain, 248 unsigned int certChainSz, 249 void* ctx, char* error); 250 251 WOLFSSL_API 252 SSL_SNIFFER_API int ssl_SetWatchKeyCallback(SSLWatchCb cb, char* error); 253 254 WOLFSSL_API 255 SSL_SNIFFER_API int ssl_SetWatchKeyCallback_ex(SSLWatchCb cb, int devId, 256 char* error); 257 258 WOLFSSL_API 259 SSL_SNIFFER_API int ssl_SetWatchKeyCtx(void* ctx, char* error); 260 261 WOLFSSL_API 262 SSL_SNIFFER_API int ssl_SetWatchKey_buffer(void* vSniffer, 263 const unsigned char* key, unsigned int keySz, 264 int keyType, char* error); 265 266 WOLFSSL_API 267 SSL_SNIFFER_API int ssl_SetWatchKey_file(void* vSniffer, 268 const char* keyFile, int keyType, 269 const char* password, char* error); 270 #endif 271 272 #ifdef WOLFSSL_SNIFFER_STORE_DATA_CB 273 typedef int (*SSLStoreDataCb)(const unsigned char* decryptBuf, 274 unsigned int decryptBufSz, unsigned int decryptBufOffset, void* ctx); 275 276 WOLFSSL_API 277 SSL_SNIFFER_API int ssl_SetStoreDataCallback(SSLStoreDataCb cb); 278 #endif 279 280 #ifdef WOLFSSL_SNIFFER_STORE_DATA_CB 281 WOLFSSL_API 282 SSL_SNIFFER_API int ssl_DecodePacketWithSessionInfoStoreData( 283 const unsigned char* packet, int length, void* ctx, 284 SSLInfo* sslInfo, char* error); 285 #endif 286 287 #ifdef WOLFSSL_SNIFFER_CHAIN_INPUT 288 WOLFSSL_API 289 SSL_SNIFFER_API int ssl_DecodePacketWithChain(void* vChain, 290 unsigned int chainSz, unsigned char** data, char* error); 291 #endif 292 293 #if defined(WOLFSSL_SNIFFER_CHAIN_INPUT) && \ 294 defined(WOLFSSL_SNIFFER_STORE_DATA_CB) 295 WOLFSSL_API 296 SSL_SNIFFER_API int ssl_DecodePacketWithChainSessionInfoStoreData( 297 void* vChain, unsigned int chainSz, void* ctx, SSLInfo* sslInfo, 298 char* error); 299 #endif 300 301 WOLFSSL_API 302 SSL_SNIFFER_API int ssl_DecodePacket_GetStream(SnifferStreamInfo* info, 303 const byte* packet, int length, char* error); 304 305 #ifdef WOLFSSL_ASYNC_CRYPT 306 307 WOLFSSL_API 308 SSL_SNIFFER_API int ssl_DecodePacketAsync(void* packet, unsigned int packetSz, 309 int isChain, unsigned char** data, char* error, SSLInfo* sslInfo, 310 void* userCtx); 311 312 WOLFSSL_API 313 SSL_SNIFFER_API int ssl_PollSniffer(WOLF_EVENT** events, int maxEvents, 314 WOLF_EVENT_FLAG flags, int* eventCount); 315 316 #endif /* WOLFSSL_ASYNC_CRYPT */ 317 318 #ifdef WOLFSSL_SNIFFER_KEYLOGFILE 319 320 typedef enum { 321 SNIFFER_SECRET_TLS12_MASTER_SECRET, 322 #if defined(WOLFSSL_TLS13) 323 SNIFFER_SECRET_CLIENT_EARLY_TRAFFIC_SECRET, 324 SNIFFER_SECRET_CLIENT_HANDSHAKE_TRAFFIC_SECRET, 325 SNIFFER_SECRET_SERVER_HANDSHAKE_TRAFFIC_SECRET, 326 SNIFFER_SECRET_CLIENT_TRAFFIC_SECRET, 327 SNIFFER_SECRET_SERVER_TRAFFIC_SECRET, 328 #endif /* WOLFSSL_TLS13 */ 329 SNIFFER_SECRET_NUM_SECRET_TYPES 330 } SnifferSecretType; 331 332 333 WOLFSSL_API 334 SSL_SNIFFER_API int ssl_CreateKeyLogSnifferServer(const char* address, 335 int port, 336 char* error); 337 338 WOLFSSL_API 339 SSL_SNIFFER_API int ssl_LoadSecretsFromKeyLogFile(const char* keylogfile, 340 char* error); 341 342 typedef int (*SSLSnifferSecretCb)(unsigned char* client_random, 343 int type, 344 unsigned char* output_secret); 345 346 #endif /* WOLFSSL_SNIFFER_KEYLOGFILE */ 347 348 WOLFSSL_API 349 SSL_SNIFFER_API int ssl_RemoveSession(const char* clientIp, int clientPort, 350 const char* serverIp, int serverPort, 351 char* error); 352 353 354 #ifdef __cplusplus 355 } /* extern "C" */ 356 #endif 357 358 #endif /* wolfSSL_SNIFFER_H */ 359