FreeRTOSv202212.00

# wolfSSL Sniffer The wolfSSL sniffer can be used to passively sniff SSL traffic including https traffic. Of course the server’s private key is required in order to decode the SSL handshake and allow future decryption of SSL messages. Input to the sniffer should be raw packets beginning with the IP header. ## Installation The wolfSSL sniffer requires the wolfSSL library version 1.8.0 or later. Future releases can be obtained from http://www.wolfssl.com To build and install wolfSSL including the wolfSSL sniffer: ```sh ./configure --enable-sniffer make sudo make install ``` ## Build Options The wolfSSL sniffer has several build options to include some extra behavior: SSL Statistics, Session Watching, Store Data Callback, Chain Input, and allowing STARTTLS protocols. The SSL Statistics option provides the logging of some additional statistics regarding the sessions being decoded. The statistics tracking uses a mutex to protect access to the tracking storage. To enable this option, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_STATS` The Session Watching option allows the sniffer to watch any packet provided it without initial setup. It will start to decode all TLS sessions and when the server’s certificate is detected, the certificate is given to a callback function provided by the user which should provide the appropriate private key. To enable this option, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_WATCH` The Store Data Callback option allows the sniffer to take a callback that is called when storing the application data into a custom buffer rather than into the reallocated data pointer the callback is called in a loop until all data is consumed. To enable this option, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_STORE_DATA_CB` The Chain Input option allows the sniffer to receive its input as a struct iovec list rather than a pointer to a raw packet. To enable this option, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DWOLFSSL_SNIFFER_CHAIN_INPUT` The STARTTLS option allows the sniffer to receive and ignore plaintext before receiving the first TLS handshake message. This is useful for protocols like SMTP and POP3 which start out in plaintext and switch to TLS during the connection. To enable this option, use the following configure command line and build as before: `./configure --enable-sniffer CPPFLAGS=-DSTARTTLS_ALLOWED` All options may be enabled with the following configure command line: ```sh ./configure --enable-sniffer \ CPPFLAGS=”-DWOLFSSL_SNIFFER_STATS -DWOLFSSL_SNIFFER_WATCH \ -DWOLFSSL_SNIFFER_STORE_DATA_CB -DWOLFSSL_SNIFFER_CHAIN_INPUT \ -DSTARTTLS_ALLOWED” ``` To add some other cipher support to the sniffer, you can add options like: ```sh --enable-arc4 --enable-nullcipher --enable-des3 ``` By default, wolfSSL restricts RSA key sizes to 1024-bits minimum. To allow the decoding of smaller, less secure RSA keys like 512-bit keys, you will need to add the compiler flag `-DWOLFSSL_MIN_RSA_BITS=512` to CFLAGS or CPPFLAGS, or define it in your user-settings header. ## Synchronous Cryptography Offload Options The sniffer can take advantage of some crypto offload hardware if available. If you have an Intel QuickAssist board or a Cavium OCTEON II or III. Currently, only the algorithms AES-CBC, AES-GCM, and DES3-CBC are offloaded to the hardware. These directions assume you already have the QAT or OCTEON-SDK libraries built. To build for QAT, use the following configure options: ```sh ./configure --enable-sniffer --enable-cryptocb \ --with-intelqa-sync=/path/to/qat ``` To build with OCTEON II support for a standalone host: ```sh ./configure --enable-sniffer --enable-cryptocb \ --with-octeon-sync=/path/to/octeon-sdk ``` To build with OCTEON III support for a Linux host: ```sh ./configure --enable-sniffer --enable-cryptocb \ --with-octeon-sync=/path/to/octeon-sdk \ OCTEON_OBJ=obj-octeon3 OCTEON_HOST=linux ``` ## Command Line Options The wolfSSL sniffer includes a test application `snifftest` in the `sslSniffer/sslSnifferTest/ directory`. The command line application has several options that can be passed in at runtime to change the default behavior of the application. To execute a “live” sniff just run the application without any parameters and then pick an interface to sniff on followed by the port. An example startup may look like this: ```sh $ cd sslSniffer/sslSnifferTest $ ./snifftest 1. en0 (No description available) 2. fw0 (No description available) 3. en1 (No description available) 4. fw1 (No description available) 5. p2p0 (No description available) 6. en3 (No description available) 7. lo0 (No description available) Enter the interface number (1-7): 7 server = 127.0.0.1 server = ::1 server = fe80::1 Enter the port to scan: 11111 ``` The above example sniffs on the localhost interface (lo0) with the default wolfSSL port of 11111 and uses the default wolfSSL server key `../../certs/server-key.pem` for RSA and `../../certs/ecc-key.pem` for ECC. Trace output will be written to a file named `tracefile.txt`. To decode a previously saved pcap file you will need to enter a few parameters. The following table lists the accepted inputs in saved file mode. Synopsis: `snifftest dumpFile pemKey [server] [port] [password]` `snifftest` Options Summary: ``` Option Description Default Value dumpFile A previously saved pcap file NA pemKey The server’s private key in PEM format NA server The server’s IP address (v4 or v6) 127.0.0.1 port The server port to sniff 443 password Private Key Password if required NA ``` To decode a pcap file named test.pcap with a server key file called myKey.pem that was generated on the localhost with a server at port 443 just use: `./snifftest test.pcap myKey.pem` If the server was on 10.0.1.2 and on port 12345 you could instead use: `./snifftest test.pcap myKey.pem 10.0.1.2 12345` If the server was on localhost using IPv6 and on port 12345 you could instead use: `./snifftest test.pcap myKey.pem ::1 12345` ## API Usage The wolfSSL sniffer can be integrated into any application using the existing sniffer API. Use the include `#include <wolfssl/sniffer.h>`. ### ssl_InitSniffer ```c void ssl_InitSniffer(void); ``` Initializes the wolfSSL sniffer for use and should be called once per application. ### ssl_FreeSniffer ```c void ssl_FreeSniffer(void); ``` Frees all resources consumed by the wolfSSL sniffer and should be called when use of the wolfSSL sniffer is no longer required. ### ssl_Trace ```c int ssl_Trace(const char* traceFile, char* error); ``` Enables Tracing when a file is passed in. Disables Tracing if previously on and a NULL value is passed in for the file. Returns Values: * 0 on success * -1 if a problem occurred, the string error will hold a message describing the problem ### ssl_SetPrivateKey ```c int ssl_SetPrivateKey(const char* serverAddress, int port, const char* keyFile, int keyFormat, const char* password, char* error); ``` Creates a sniffer session based on the `serverAddress` and `port` inputs using the ECC or RSA `keyFile` as the server’s key. The `keyFormat` can be either `FILETYPE_PEM` or `FILETYPE_DER`. If the keyFile has password protection then the password parameter can hold the proper value. Return Values: * 0 on success * -1 if a problem occurred, the string error will hold a message describing the problem ### ssl_SetPrivateKeyBuffer ```c int ssl_SetPrivateKeyBuffer(const char* address, int port, const char* keyBuf, int