DTLS.DebugFingerprints

DTLS.DebugFingerprints

#Overview

name: DTLS.DebugFingerprints

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DTLS.DebugFingerprints is to enable debugging functionality for DTLS (Datagram Transport Layer Security) certificate fingerprints in Unreal Engine 5. This setting is specifically related to the network security and encryption system, particularly the DTLS protocol implementation.

This setting variable is primarily used in the DTLSHandlerComponent plugin, which is part of the PacketHandlers runtime plugin in Unreal Engine 5. The plugin is responsible for handling DTLS-related functionalities in the engine’s networking subsystem.

The value of this variable is set as a console variable (CVar) with an initial value of 0, meaning it’s disabled by default. It can be changed at runtime through the console or configuration files.

The associated variable CVarDTLSDebugFingerprints directly interacts with DTLS.DebugFingerprints. They share the same value and purpose.

Developers must be aware of several important points when using this variable:

  1. It’s only available in non-shipping builds (#if !UE_BUILD_SHIPPING).
  2. When enabled (set to non-zero), it triggers debug functionality that saves DTLS certificate fingerprints to files.
  3. The debug files are saved in the project’s log directory with a .bin extension.

Best practices for using this variable include:

  1. Only enable it during development and testing phases, not in production builds.
  2. Be cautious about security implications when enabling this debug feature, as it writes sensitive information to disk.
  3. Ensure proper cleanup of debug files after debugging sessions.

Regarding the associated variable CVarDTLSDebugFingerprints:

The purpose of CVarDTLSDebugFingerprints is to provide a programmatic way to access and modify the DTLS.DebugFingerprints setting within the C++ code.

It’s used in the DTLSHandlerComponent plugin, specifically in the DTLSCertStore class.

The value is set through the TAutoConsoleVariable template, which allows it to be modified via console commands or configuration files.

CVarDTLSDebugFingerprints directly controls the behavior of the debug fingerprint functionality. When its value is non-zero, the debug feature is enabled.

Developers should be aware that this variable is checked in performance-sensitive code (CreateCert function), so frequent toggling might have a minor performance impact.

Best practices include using GetValueOnAnyThread() for thread-safe access to the variable’s value, and considering caching the value if used frequently in performance-critical sections.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSCertStore.cpp:9

Scope: file

Source code excerpt:


#if !UE_BUILD_SHIPPING
static TAutoConsoleVariable<int32> CVarDTLSDebugFingerprints(TEXT("DTLS.DebugFingerprints"), 0, TEXT(""));
#endif

TUniquePtr<FDTLSCertStore> FDTLSCertStore::Instance;

FDTLSCertStore& FDTLSCertStore::Get()
{

#Associated Variable and Callsites

This variable is associated with another variable named CVarDTLSDebugFingerprints. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSCertStore.cpp:9

Scope: file

Source code excerpt:


#if !UE_BUILD_SHIPPING
static TAutoConsoleVariable<int32> CVarDTLSDebugFingerprints(TEXT("DTLS.DebugFingerprints"), 0, TEXT(""));
#endif

TUniquePtr<FDTLSCertStore> FDTLSCertStore::Instance;

FDTLSCertStore& FDTLSCertStore::Get()
{

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Private/DTLSCertStore.cpp:44

Scope (from outer to inner):

file
function     TSharedPtr<FDTLSCertificate> FDTLSCertStore::CreateCert

Source code excerpt:


#if !UE_BUILD_SHIPPING
		const bool bDebugFingerprints = (CVarDTLSDebugFingerprints.GetValueOnAnyThread() != 0);

		if (bDebugFingerprints)
		{
			FString DebugFilename = FString::Printf(TEXT("%s%s.bin"), *FPaths::ProjectLogDir(), *FPaths::MakeValidFileName(Identifier));
			FFileHelper::SaveArrayToFile(Cert->GetFingerprint(), *DebugFilename);
		}