Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -798,6 +798,34 @@ For a server, specifying `caFile` implies that:

By default, a destination's hostname is always validated against the certificate that it presents. To accept certificates with any hostname, set `ix::SocketTLSOptions::disable_hostname_validation` to `true`.

### TLS key logging (OpenSSL)

With OpenSSL 1.1.1 or newer, set `keyLogFile` in your TLS options before connecting
or starting a TLS server:

```cpp
ix::SocketTLSOptions options;
options.keyLogFile = "tls.keys";
webSocket.setTLSOptions(options);
```

The file contains TLS session secrets in NSS key-log format, which tools such as
Wireshark can use to decrypt captured traffic. An empty `keyLogFile` disables this
logging. Connections append to the file, including across reconnections; multiple
connections may share a destination. A connection fails if the file cannot be
opened. Other TLS backends reject this option explicitly.

The `ws` TLS commands accept `--keylog-file` and the `SSLKEYLOGFILE` environment
variable. An explicit command-line option takes precedence:

```sh
ws connect wss://example.com/ws --keylog-file tls.keys
SSLKEYLOGFILE=tls.keys ws connect wss://example.com/ws
```

The library API uses `keyLogFile` explicitly; environment-variable handling is
provided by the CLI.

### Network.framework backend on macOS

Build with `USE_NETWORK_FRAMEWORK=ON` to use native TLS for `wss://` and `https://`
Expand Down
8 changes: 8 additions & 0 deletions ixwebsocket/IXSocketFactory.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ namespace ix
{
(void) tlsOptions;
errorMsg.clear();
#if !defined(IXWEBSOCKET_USE_OPEN_SSL) || OPENSSL_VERSION_NUMBER < 0x10101000L || \
defined(LIBRESSL_VERSION_NUMBER)
if (tls && !tlsOptions.keyLogFile.empty())
{
errorMsg = "TLS key logging requires OpenSSL 1.1.1 or newer";
return nullptr;
}
#endif
std::unique_ptr<Socket> socket;

if (!tls)
Expand Down
5 changes: 5 additions & 0 deletions ixwebsocket/IXSocketNetwork.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,11 @@ namespace ix
std::string host,
std::string& error)
{
if (!options.keyLogFile.empty())
{
error = "TLS key logging requires OpenSSL 1.1.1 or newer";
return nullptr;
}
if (!options.isUsingDefaultCiphers())
{
error = "Network.framework backend does not support cipher strings";
Expand Down
61 changes: 61 additions & 0 deletions ixwebsocket/IXSocketOpenSSL.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
#include "IXUniquePtr.h"
#include <cassert>
#include <errno.h>
#include <fstream>
#include <vector>
#ifdef _WIN32
#include <shlwapi.h>
Expand Down Expand Up @@ -230,10 +231,65 @@ namespace ix
int options = SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_CIPHER_SERVER_PREFERENCE;

SSL_CTX_set_options(ctx, options);
if (!configureKeyLogging(ctx, errMsg))
{
SSL_CTX_free(ctx);
return nullptr;
}
}
return ctx;
}

bool SocketOpenSSL::configureKeyLogging(SSL_CTX* context, std::string& errMsg)
{
if (_tlsOptions.keyLogFile.empty())
{
return true;
}
#if OPENSSL_VERSION_NUMBER >= 0x10101000L && !defined(LIBRESSL_VERSION_NUMBER)
std::ofstream file(_tlsOptions.keyLogFile, std::ios::app | std::ios::binary);
if (!file)
{
errMsg = "Cannot open TLS key log file: " + _tlsOptions.keyLogFile;
return false;
}
if (SSL_CTX_set_app_data(context, this) != 1)
{
errMsg = "Cannot configure TLS key logging";
return false;
}
SSL_CTX_set_keylog_callback(context, keyLogCallback);
return true;
#else
(void) context;
errMsg = "TLS key logging requires OpenSSL 1.1.1 or newer";
return false;
#endif
}

void SocketOpenSSL::keyLogCallback(const SSL* ssl, const char* line)
{
auto* socket = static_cast<SocketOpenSSL*>(SSL_CTX_get_app_data(SSL_get_SSL_CTX(ssl)));
if (!socket || !line)
{
return;
}
const int savedError = Socket::getErrno();
try
{
// Different connections can append to the same file; keep each line intact.
static std::mutex mutex;
std::lock_guard<std::mutex> lock(mutex);
std::ofstream file(socket->_tlsOptions.keyLogFile, std::ios::app | std::ios::binary);
file << line << '\n';
}
catch (...)
{
// A debugging log must not throw through OpenSSL's C callback.
}
Socket::setErrno(savedError);
}

bool SocketOpenSSL::openSSLAddCARootsFromString(const std::string roots)
{
// Create certificate store
Expand Down Expand Up @@ -652,6 +708,11 @@ namespace ix
return false;
}

if (!configureKeyLogging(_ssl_context, errMsg))
{
return false;
}

ERR_clear_error();
if (_tlsOptions.hasCertAndKey())
{
Expand Down
2 changes: 2 additions & 0 deletions ixwebsocket/IXSocketOpenSSL.h
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ namespace ix
void openSSLInitialize();
std::string getSSLError(int ret);
SSL_CTX* openSSLCreateContext(std::string& errMsg);
bool configureKeyLogging(SSL_CTX* context, std::string& errMsg);
static void keyLogCallback(const SSL* ssl, const char* line);
bool openSSLAddCARootsFromString(const std::string roots);
bool openSSLClientHandshake(const std::string& hostname,
std::string& errMsg,
Expand Down
1 change: 1 addition & 0 deletions ixwebsocket/IXSocketTLSOptions.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ namespace ix
ss << "TLS Options:" << std::endl;
ss << " certFile = " << certFile << std::endl;
ss << " keyFile = " << keyFile << std::endl;
ss << " keyLogFile = " << keyLogFile << std::endl;
ss << " caFile = " << caFile << std::endl;
ss << " ciphers = " << ciphers << std::endl;
ss << " tls = " << tls << std::endl;
Expand Down
3 changes: 3 additions & 0 deletions ixwebsocket/IXSocketTLSOptions.h
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ namespace ix
// the key used for signing/encryption
std::string keyFile;

// Append TLS session secrets in NSS key-log format (OpenSSL 1.1.1+ only).
std::string keyLogFile;

// the ca certificate (or certificate bundle) file containing
// certificates to be trusted by peers; use 'SYSTEM' to
// leverage the system defaults, use 'NONE' to disable peer verification
Expand Down
5 changes: 5 additions & 0 deletions test/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ foreach(TEST_TARGET_NAME ${TEST_TARGET_NAMES})

endforeach()

if (TARGET IXSocketOpenSSLWriteTest)
target_compile_definitions(IXSocketOpenSSLWriteTest PRIVATE
IX_OPENSSL_TEST_OUTPUT_DIR="${CMAKE_CURRENT_BINARY_DIR}")
endif()

if (USE_WS)
find_package(Python3 QUIET COMPONENTS Interpreter)
if (Python3_Interpreter_FOUND)
Expand Down
10 changes: 10 additions & 0 deletions test/IXSocketNetworkTest.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,16 @@ TEST_CASE("Network.framework TLS", "[network_tls]")
CHECK_FALSE(result.first);
CHECK(result.second.find("cipher") != std::string::npos);
}
SECTION("unsupported key logging fails explicitly")
{
auto options = serverOptions();
options.keyLogFile = "unused-keylog.log";
HttpServer server(0);
server.setTLSOptions(options);
auto result = server.listen();
CHECK_FALSE(result.first);
CHECK(result.second == "TLS key logging requires OpenSSL 1.1.1 or newer");
}
SECTION("bad identity fails at listen")
{
auto options = serverOptions();
Expand Down
Loading
Loading