How should I configure TLS options for each use case?

Starting from ObjectDeliverer v1.9.0, you can use TCP/IP TLS server/client protocols.

This page explains which TLS options to use for each typical use case, and why.

Available options

Client-side (UProtocolTcpIpClientTls)

  • WithCertificateVerification()
    • Enables certificate chain verification.
  • WithTrustedCaCertificate(path)
    • Use this when you need to trust a private/custom CA that is not in the OS trust store.
  • WithAllowSelfSignedCertificates(true)
    • Allows self-signed certificates.
  • WithPinnedPublicKey(...) / WithPinnedPublicKeyFromFile(...)
    • Public key pinning for the server certificate.
  • WithPeerVerificationDisabled()
    • Disables certificate verification. Not recommended except for temporary testing.
  • WithClientCertificate(certPath, keyPath)
    • Sends a client certificate for mTLS.

Server-side (UProtocolTcpIpServerTls)

  • WithClientAuthMode(None / Optional / Required)
    • Controls whether client certificates are requested/required.
  • WithClientCaBundle(path)
    • Sets the CA bundle used to validate client certificates (for mTLS).

1. Production environment (public server certificate)

This is the standard setup for most production systems.

Background:

  • In production, you need more than encryption. You also need to verify that the server is the real one.

  • Using CA-signed certificates keeps operations predictable across multiple environments.

  • Client:

    • WithCertificateVerification()

  • Server:

    • CreateProtocolTcpIpServerTls(port, certPath, keyPath, minimumProtocol)

Key points:

  • Match the hostname/IP passed to InitializeTls() with SAN/CN values in the certificate.
  • If you use a private CA, add WithTrustedCaCertificate(...) on the client.

What this prevents:

  • Connecting to impersonated servers
  • Eavesdropping/tampering on the network path

2. Internal network / private CA

This is common when certificates are issued by an in-house CA.

Background:

  • In enterprise, factory, or lab environments, private CAs are frequently used.

  • Without explicitly trusting that CA on clients, valid internal servers will still be rejected.

  • Client:

    • WithCertificateVerification()
    • WithTrustedCaCertificate(caCertPath)

Key points:

  • Define a clear certificate distribution and rotation process for both test and production.

What this prevents:

  • Accidental trust of servers signed by unknown CAs
  • “Encrypted but not actually authenticated” setups

3. Development environment (self-signed certificate)

Useful for local and short-cycle development.

Background:

  • During development, teams often want TLS quickly without setting up a full CA workflow.

  • Self-signed certificates can work safely, but only if you also pin the expected server key.

  • Client:

    • WithCertificateVerification()
    • WithAllowSelfSignedCertificates(true)
    • WithPinnedPublicKey(...) or WithPinnedPublicKeyFromFile(...)

Key points:

  • Allowing self-signed certificates alone is not enough. Public key pinning is required.
  • The implementation tests also validate success/failure behavior with this combination.

What this prevents:

  • Connecting to a fake server in development environments
  • Overly permissive “accept any self-signed cert” mistakes

4. Temporary connectivity check only (not for production)

Use this only when you need quick connection diagnostics.

Background:

  • Sometimes you need to confirm only route/port connectivity before certificate setup is ready.

  • This is useful for short-term troubleshooting, but it removes server identity checks.

  • Client:

    • WithPeerVerificationDisabled()

Key points:

  • Do not use this in production because it is vulnerable to man-in-the-middle attacks.
  • After diagnostics, switch back to verified settings using WithCertificateVerification().

5. Mutual TLS (mTLS) for client authentication

Use this when the server must verify who the client is.

Background:

  • Standard TLS mainly authenticates the server to the client.

  • mTLS adds client authentication on the server side, enabling mutual authentication.

  • This means:

    • For the server: unknown clients cannot connect.
    • For the client: fake/impersonated servers can be rejected.

  • Server:

    • WithClientAuthMode(Required) or WithClientAuthMode(Optional)
    • WithClientCaBundle(caCertPath)

  • Client:

    • WithCertificateVerification()
    • WithTrustedCaCertificate(serverCaPath)
    • WithClientCertificate(clientCertPath, clientKeyPath)

When to use each mode:

  • Required: Client certificate is mandatory. Missing/invalid certificates are rejected.
  • Optional: Validate certificate if provided, but still allow clients without one.

What this prevents:

  • Unauthorized clients connecting to the server
  • Attacks that rely on impersonating only one side of the connection

Common configuration mistakes

  • Connecting with InitializeTls("localhost", ...) while the certificate only includes 127.0.0.1
    • Hostname/IP verification will fail.
  • Using WithAllowSelfSignedCertificates(true) without pinning
    • Connection will fail due to missing pinning.
  • Enabling WithClientAuthMode(Required) without WithClientCaBundle(...)
    • Client certificates cannot be validated correctly.

Minimal example

auto ServerProtocol = UProtocolFactory::CreateProtocolTcpIpServerTls(
    8443, ServerCertPath, ServerKeyPath, EObjectDelivererTlsProtocol::TLSv1_2);

auto ClientProtocol = UProtocolFactory::CreateProtocolTcpIpClientTls(
    TEXT("localhost"), 8443, false, false, EObjectDelivererTlsProtocol::TLSv1_2);

ClientProtocol->WithCertificateVerification();
ClientProtocol->WithAllowSelfSignedCertificates(true);
ClientProtocol->WithPinnedPublicKey(PublicKeyHash);

Reference: Create OpenSSL-based keys/certificates with ObjectDelivererEditor

From ObjectDeliverer v1.9.0 onward, you can generate a self-signed certificate from ObjectDelivererEditor via Tools -> Generate TLS Certificate.
This feature uses the OpenSSL library internally and outputs the key/certificate files required for TLS.

Steps:

  1. Open Tools -> Generate TLS Certificate in Unreal Editor.
  2. Choose an output directory (avoid Content/; use a dedicated secure folder).
  3. Confirm the warning dialog and run generation.
  4. The following files are created in the selected directory:
    • server.crt (server certificate)
    • server.key (server private key)
    • server.pubkey.txt (public key hash, directly usable with WithPinnedPublicKeyFromFile(...))

How to use:

  • On the TLS server, set server.crt / server.key in CreateProtocolTcpIpServerTls(..., certPath, keyPath, ...).
  • On the self-signed TLS client, use both WithAllowSelfSignedCertificates(true) and WithPinnedPublicKeyFromFile(".../server.pubkey.txt").

Notes:

  • This editor menu is for development/testing self-signed certificates (default: 365 days, CN=localhost).
  • For production or mTLS client-certificate operations, use certificates issued by a public CA or private CA.

If you want to generate certificates manually with OpenSSL commands, see this FAQ.

Back to FAQ