Opt-In Software Blog

Software, dvelopment, and practical insights

ProxyMapService: TLS Record Split and Per-Port / Per-Host SSL Settings

Read in: English | Русский

Three versions of ProxyMapService have been released since the previous post: 1.0.0, 1.0.1 and 1.0.2. The headline feature of the latest one is TLS record splitting: the proxy can now split the first outgoing TLS record (the ClientHello) into several separate TLS records. Besides that, these releases bring per-port and per-host SSL settings, the ability to start the service with no configuration, and a few changes worth knowing about before you upgrade.

TLS Record Split (1.0.2)

Why you might need it

The ClientHello is the first message of a TLS handshake, and it carries the target hostname (SNI) in plaintext. Some DPI systems classify HTTPS traffic by inspecting that first record as a single unit: if they find a particular SNI in it, the connection gets blocked or handled specially.

Fragmentation at the TLS protocol level breaks such a check. The resulting records keep the same content type and version as the original one and together reassemble into the identical payload, so any RFC-conforming TLS server accepts them unchanged. DPI, however, no longer sees one reassembled ClientHello but several distinct packets, because each record is written separately.

How to enable

The TlsRecordSplit option can be set at two levels: for a whole port, in the Listen section of a ProxyMappings entry, or only for particular hosts, in HostRules.

For a whole port:

"ProxyMappings": [
    {
        "Listen": {
            "Port": 5001,
            "TlsRecordSplit": "1,0+sm"
        }
    }
]

For particular hosts — for example, to fragment the ClientHello only when connecting to YouTube:

"HostRules": {
    "Items": [
        {
            "Pattern": "youtube\\.com$",
            "TlsRecordSplit": "1,0+sm"
        },
        {
            "Pattern": "googlevideo\\.com$",
            "TlsRecordSplit": "1,0+sm"
        },
        {
            "Pattern": "\\.ytimg\\.com$",
            "TlsRecordSplit": "1,0+sm"
        }
    ]
}

A HostRule value takes precedence over the one from Listen; if the rule does not set the option, the Listen value is inherited. This way you can leave the rest of the traffic alone and split records only for the hosts that need it.

The value format is the same at both levels: a comma-separated list of split positions, each in the syntax offset[:repeats:skip][+flag1[flag2]].

  • offset — split position relative to the start of the ClientHello (the TLS record payload, without the 5-byte record header); a negative offset without flags counts from the end of the ClientHello;
  • repeats:skip — optional; repeat the split repeats times with a skip byte step (e.g. 1:3:5 splits at positions 1, 6 and 11);
  • flags:
    • +s — offset from the start of the SNI hostname;
    • +e — offset from the end of the ClientHello (with +s — from the end of the SNI hostname);
    • +m — offset from the middle of the ClientHello (with +s — from the middle of the SNI hostname);
    • +n — zero offset (the position stays absolute).

A few examples:

Value Where the record is split
1 after the first byte of the ClientHello
3+s 3 bytes after the start of the SNI hostname
0+sm in the middle of the SNI hostname
-5 5 bytes before the end of the ClientHello

Positions can be combined: "1,0+sm" from the examples above splits the record in two places at once — after the first byte and in the middle of the hostname.

Works in both modes

The split is applied to the outgoing (upstream) TLS connection and works in two modes:

  • with SSL decryption enabled (DecryptSSL: true) — the proxy generates the ClientHello itself (including a Chrome-like or Firefox-like TLS fingerprint), and the split is applied underneath the TLS implementation;
  • in passthrough mode (no decryption) — the client’s own ClientHello travels through the tunnel and is re-chunked on the fly.

Behavior details

  • Only the first TLS record (the ClientHello) is split; all subsequent records pass through unchanged.
  • If the specification resolves to nothing to split — for example, all positions reference the SNI hostname but the record has none, or a position falls on the record boundary — the record is sent as-is.
  • When the split is active, the proxy logs it at debug level (enable TlsHandshakeLog to see it).

Per-Port and Per-Host SSL Settings (1.0.0)

The global SslClientOptions (outgoing TLS connections) and SslServerOptions (incoming TLS connections when decryption is enabled) can now be refined at two levels:

  • Listen.SslClientOptions / Listen.SslServerOptions — apply to all traffic of a listening port (range) from ProxyMappings;
  • HostRule.SslClientOptions / HostRule.SslServerOptions — apply only to connections matching the host rule.

Precedence: global settings → Listen → HostRule. Only the properties explicitly set in an override replace the inherited values; everything else is inherited from the level above. A HostRule override is applied only when the rule matches and the rule’s action is not Deny.

For example, let’s restrict the protocol versions for one port and give one host a dedicated certificate and a Chrome-like fingerprint:

"ProxyMappings": [
    {
        "Listen": {
            "Port": 5001,
            "DecryptSSL": true,
            "SslServerOptions": {
                "EnabledSslProtocols": "Tls12,Tls13"
            }
        }
    }
],
"HostRules": {
    "Items": [
        {
            "HostName": "example.com",
            "SslClientOptions": {
                "TlsClientType": "BoringSsl"
            },
            "SslServerOptions": {
                "ServerCertificate": {
                    "Path": "certs/example.com.pfx",
                    "Password": "secret"
                }
            }
        }
    ]
}

The properties that can be overridden:

  • in SslClientOptions: EnabledSslProtocols, CheckCertificateRevocation, ApplicationProtocols, TrustedCAs, TlsClientType;
  • in SslServerOptions: EnabledSslProtocols, ClientCertificateRequired, CheckCertificateRevocation, ApplicationProtocols, ServerCertificate, CACertificate.

TlsClientType replaces UseBoringSsl

The post about the Chrome-like TLS fingerprint used the UseBoringSsl option. It has been replaced by TlsClientType in SslClientOptions, with these values:

  • Native — the default, the standard .NET SslStream;
  • BoringSsl — Chrome-like TLS fingerprint (BoringSslStream);
  • Nss — Firefox-like TLS fingerprint (NssStream).

So the former "UseBoringSsl": true is now written as "TlsClientType": "BoringSsl". And thanks to the overrides above, the client type can be chosen per port or per host.

Store-based certificates

ServerCertificate and CACertificate accept the full SslCertificateConfig shape. A dedicated certificate for a host can be loaded either from a file (Path + Password, ~ is expanded) or from a local certificate store (StoreLocation + StoreName + Subject).

What breaks when upgrading

The CertificatePath and CertificatePassword properties of HostRule have been removed in favor of SslServerOptions.ServerCertificate. Old configurations will not produce an error — the old properties are silently ignored — so migrate them manually:

// before:
{
    "HostName": "example.com",
    "CertificatePath": "certs/example.com.pfx",
    "CertificatePassword": "secret"
}
// after:
{
    "HostName": "example.com",
    "SslServerOptions": {
        "ServerCertificate": {
            "Path": "certs/example.com.pfx",
            "Password": "secret"
        }
    }
}

Starting Without a Configuration (1.0.1)

Previously, a missing or empty ProxyMappings section threw NoMappingsException and the service refused to start. Now it logs a No proxy mappings warning and keeps running, using the built-in DefaultProxyMappings section from appsettings.json — a plain Bypass listener on port 5001 with SSL decryption.

This makes it possible to start the service “empty”, open the dashboard, edit the configuration and restart the service right from the web UI.

Note that the fallback is applied only when the effective configuration is the base appsettings.json, i.e. no additional appsettings.*.json layers were loaded. If an environment-specific settings file is present (such as appsettings.Production.json), it is expected to define ProxyMappings itself.

Session API: the Domain Is Now Required (1.0.1)

SessionAPIConfig.Domain must now be non-empty for the Session API to be reachable. Previously, an empty domain made every request without a hostname match count as a Session API request. The default value in appsettings.json has changed from "" to proxymapper. Requests addressed to any other hostname are no longer captured by the Session API handler, so if you use it, check this value in your configuration.

Search