DTLS.PreSharedKeys

DTLS.PreSharedKeys

#Overview

name: DTLS.PreSharedKeys

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DTLS.PreSharedKeys is to control the use of pre-shared keys in the DTLS (Datagram Transport Layer Security) handler component of Unreal Engine. This setting is primarily related to network security and encryption in the engine’s networking system.

This setting variable is used in the DTLS Handler Component, which is part of the PacketHandlers plugin in Unreal Engine. It specifically affects the behavior of the DTLSHandlerComponent module.

The value of this variable is set using a console variable (CVar) named CVarPreSharedKeys. It is initialized with a default value of 1, meaning pre-shared keys are enabled by default.

The associated variable CVarPreSharedKeys interacts directly with DTLS.PreSharedKeys. They share the same value and purpose. CVarPreSharedKeys is used in the C++ code to check the current setting and determine whether to use pre-shared keys or self-signed certificates.

Developers must be aware that:

  1. When this variable is non-zero, the system uses pre-shared keys for encryption.
  2. When it’s set to zero, self-signed certificates will be generated instead.
  3. This setting affects the cipher list used in SSL context initialization.
  4. It impacts how encryption data is set in the DTLSHandlerComponent.

Best practices when using this variable include:

  1. Consider the security implications of using pre-shared keys vs. self-signed certificates for your specific use case.
  2. Ensure that when changing this setting, you also update any related encryption data or certificate generation processes.
  3. Test thoroughly with both settings (0 and non-zero) to ensure your networking code handles both scenarios correctly.
  4. Document clearly in your project which setting is used and why, as it significantly affects the security model of your network communications.

Regarding the associated variable CVarPreSharedKeys:

The purpose of CVarPreSharedKeys is to provide a runtime-configurable way to access the DTLS.PreSharedKeys setting. It’s an instance of TAutoConsoleVariable, which allows the value to be changed during runtime via console commands.

CVarPreSharedKeys is used in the DTLS Handler Component to determine the encryption method at various points, such as during initialization of the SSL context and when setting encryption data.

The value of CVarPreSharedKeys is typically accessed using the GetValueOnAnyThread() method, which allows it to be safely read from any thread.

Developers should be aware that changes to CVarPreSharedKeys will immediately affect the behavior of the DTLS handler, potentially impacting ongoing network communications.

Best practices for CVarPreSharedKeys include:

  1. Use GetValueOnAnyThread() when accessing the value to ensure thread-safe operations.
  2. Consider the performance implications of frequently checking this value, especially in performance-critical code paths.
  3. If changing this value at runtime, ensure that all related systems are properly updated or reinitialized to reflect the new setting.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

#undef UI

TAutoConsoleVariable<int32> CVarPreSharedKeys(TEXT("DTLS.PreSharedKeys"), 1, TEXT("If non-zero, use pre-shared keys, otherwise self-signed certificates will be generated."));

#endif // WITH_SSL

DEFINE_LOG_CATEGORY(LogDTLSHandler);

IMPLEMENT_MODULE(FDTLSHandlerComponentModule, DTLSHandlerComponent)

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
function     bool FDTLSContext::Initialize

Source code excerpt:

	FSslModule::Get().GetCertificateManager().AddCertificatesToSslContext(SSLContext);

	const bool bPreSharedKeys = (CVarPreSharedKeys.GetValueOnAnyThread() != 0);

	const char* CipherList = bPreSharedKeys ? DTLSContext::CipherListPSK : DTLSContext::CipherListCert;

	int32 Result = SSL_CTX_set_cipher_list(SSLContext, CipherList);
	if (Result == 0) 
	{

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

Scope: file

Source code excerpt:

#undef UI

TAutoConsoleVariable<int32> CVarPreSharedKeys(TEXT("DTLS.PreSharedKeys"), 1, TEXT("If non-zero, use pre-shared keys, otherwise self-signed certificates will be generated."));

#endif // WITH_SSL

DEFINE_LOG_CATEGORY(LogDTLSHandler);

IMPLEMENT_MODULE(FDTLSHandlerComponentModule, DTLSHandlerComponent)

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

Scope (from outer to inner):

file
function     void FDTLSHandlerComponent::SetEncryptionData

Source code excerpt:

void FDTLSHandlerComponent::SetEncryptionData(const FEncryptionData& EncryptionData)
{
	const bool bPreSharedKeys = (CVarPreSharedKeys.GetValueOnAnyThread() != 0);

	if (bPreSharedKeys)
	{
		PreSharedKey = MakeUnique<FDTLSPreSharedKey>();
		PreSharedKey->SetPreSharedKey(EncryptionData.Key);
		PreSharedKey->SetIdentity(EncryptionData.Identifier);

#Loc: <Workspace>/Engine/Plugins/Runtime/PacketHandlers/DTLSHandlerComponent/Source/Public/DTLSHandlerComponent.h:11

Scope: file

Source code excerpt:

#if WITH_SSL

extern TAutoConsoleVariable<int32> CVarPreSharedKeys;

/*
* DTLS encryption component.
*/
class DTLSHANDLERCOMPONENT_API FDTLSHandlerComponent : public FEncryptionComponent
{