# Copyright 2026 Tailwind Resource Group # SPDX-License-Identifier: Apache-2.0 # Provided as is, with no warranty. License: https://everythingsfine.io/license/ # # emudhra_gw # # Attach to the egress virtual that passes TLS through untouched. It must be a # STANDARD virtual (tcp profile, no client-ssl or server-ssl profile, no pool, # translate-address and translate-port disabled, source-port preserve). # A "Forwarding (IP)" virtual is fastL4: CLIENT_DATA and SERVER_DATA never run. # Create iRule emudhra_lib before this one. Supported: BIG-IP 17.5 and later. # Requires: iRule emudhra_lib, data group dg_emudhra, HSL pool, and (for the # TLS 1.3 path) the probe virtual running iRule emudhra_probe. # # Paths # TLS 1.2 Passive, on every connection. The server's Certificate message is # parsed in SERVER_DATA before any of it reaches the client, so # enforce mode can reset before the client sees the chain. A cached # CLEAN or WATCH never skips this; a changed chain is seen at once. # TLS 1.3 The chain is encrypted. The gateway asks the probe virtual to make # its own handshake to the same IP:port and SNI. That is evidence of # what the destination serves, not of what this client received. # Cache Per route domain, IP, port and SNI, with passive and probe results # kept apart (see record / verdict_get in emudhra_lib). The cache # limits probes and duplicate logs. In enforce mode a cached BLOCK # from either source is reset at the ClientHello. # # Every library call is wrapped in catch: a runtime TCL error would otherwise # reset the client's connection. Any error, oversize, or timeout fails open. # Inspection failures are recorded as UNKNOWN, never as CLEAN, and never enforced. when RULE_INIT { set static::emu_mode "detect" ;# detect | enforce set static::emu_probe "async" ;# off | async | hold set static::emu_probe_vs "/Common/vs_emudhra_probe" set static::emu_probe_tmo 3000 ;# ms, per sideband step set static::emu_ttl_clean 86400 ;# s, cache life of a CLEAN verdict set static::emu_ttl_hit 604800 ;# s, cache life of a WATCH/BLOCK verdict set static::emu_ttl_unknown 300 ;# s, cache life of an UNKNOWN verdict set static::emu_max_collect 65536 ;# bytes, give up and pass through beyond this set static::emu_pend_max 100 ;# clients attributed per destination while its probe runs set static::emu_hsl_pool "/Common/pool_emudhra_syslog" # Client-speaks-first TLS ports only. STARTTLS ports (25, 587, 143, 110) are not handled. set static::emu_ports [list 443 8443 465 636 853 993 995 5061] } when CLIENT_ACCEPTED { set emu_skip 1 set emu_sni "" set emu_key "" set emu_dst [IP::local_addr] set emu_port [TCP::local_port] set emu_client [IP::client_addr] if {[lsearch -exact $static::emu_ports $emu_port] < 0} { return } set emu_skip 0 set emu_hsl [HSL::open -proto UDP -pool $static::emu_hsl_pool] TCP::collect } when CLIENT_DATA { if {$emu_skip} { TCP::release ; return } set p [TCP::payload] # Not a TLS handshake record: stop watching this flow. if {[catch {call /Common/emudhra_lib::u8 $p 0} b] || $b != 22} { set emu_skip 1 ; TCP::release ; return } # Wait for the whole ClientHello, which may span several records (post-quantum # key shares make it large). Past the collect limit, carry on without SNI. if {[catch {call /Common/emudhra_lib::clienthello_msg $p} ch]} { set ch [list BAD ""] } if {[lindex $ch 0] eq "MORE" && [string length $p] < $static::emu_max_collect} { TCP::collect ; return } set emu_sni "" if {[lindex $ch 0] eq "OK"} { if {[catch {call /Common/emudhra_lib::sni_from_hello [lindex $ch 1]} emu_sni]} { set emu_sni "" } } if {[catch {call /Common/emudhra_lib::dest_key $emu_sni $emu_dst $emu_port} emu_key]} { set emu_skip 1 ; TCP::release ; return } # Known destination: attribute the client, and enforce a cached BLOCK. # Anything else continues, so TLS 1.2 is still inspected passively. if {[catch {call /Common/emudhra_lib::verdict_get $emu_key} vg]} { set vg [list "" "" ""] } foreach {sev pv rv} $vg break if {$sev ne ""} { if {$sev eq [lindex $pv 0]} { set src "passive" } else { set src "probe" } catch {call /Common/emudhra_lib::seen $emu_hsl $emu_client $emu_key $sev "cache-$src" $emu_dst $emu_port $emu_sni} if {$sev eq "BLOCK" && $static::emu_mode eq "enforce"} { if {![catch {call /Common/emudhra_lib::first_in emudhra_blklog "$emu_client|$emu_key" 60} f] && $f} { HSL::send $emu_hsl "<132>emudhra event=block src=cache-$src key=$emu_key client=$emu_client dst=$emu_dst dport=$emu_port sni=$emu_sni" } set emu_skip 1 reject return } } # No probe result for this destination yet: probe it once per 30 s across all # TMMs. TLS 1.3 servers need the probe; TLS 1.2 servers are also seen passively. # The probe virtual writes and logs the verdict and attributes the clients. # async: connect + send only (both return in well under a millisecond on # box); the flow continues while the probe runs. # hold: wait for the verdict. Only the first flow to a new destination # waits; concurrent flows to it pass while the probe is in flight. # Flows that lose the election join the pending list, so they are attributed # when the result arrives. A local sideband failure is recorded here as a # probe UNKNOWN, since the probe virtual never saw the request. if {$rv eq "" && $static::emu_probe ne "off"} { if {![catch {call /Common/emudhra_lib::first_in emudhra_inflight $emu_key 30} f] && $f} { set wait [expr {$static::emu_probe eq "hold"}] if {[catch {call /Common/emudhra_lib::probe $static::emu_probe_vs $emu_dst $emu_port $emu_sni $emu_client $static::emu_probe_tmo $wait} r]} { set r "ERR probe_error" } if {[lindex $r 0] eq "ERR"} { catch {call /Common/emudhra_lib::probe_done $emu_key "UNKNOWN label=- depth=-1 match=- fp=- certs=0 reason=[lindex $r 1]" $emu_hsl $emu_client $emu_dst $emu_port $emu_sni} } if {[lindex $r 0] eq "OK" && [lindex $r 1] eq "BLOCK" && $static::emu_mode eq "enforce"} { if {![catch {call /Common/emudhra_lib::first_in emudhra_blklog "$emu_client|$emu_key" 60} f] && $f} { HSL::send $emu_hsl "<132>emudhra event=block src=probe-hold key=$emu_key client=$emu_client dst=$emu_dst dport=$emu_port sni=$emu_sni" } set emu_skip 1 reject return } } else { catch {call /Common/emudhra_lib::pend_add $emu_key $emu_client} } } TCP::release } when SERVER_CONNECTED { if {$emu_skip} { return } TCP::collect } when SERVER_DATA { if {[catch {call /Common/emudhra_lib::parse_server_flight [TCP::payload]} r]} { set r "ERR" } set v "" switch -glob -- $r { "MORE" { if {[TCP::payload length] < $static::emu_max_collect} { TCP::collect ; return } set v "UNKNOWN label=- depth=-1 match=- fp=- certs=0 reason=oversize" } "CERT *" { set v [string range $r 5 end] } "ERR" { set v "UNKNOWN label=- depth=-1 match=- fp=- certs=0 reason=parse_error" } } # TLS13, NOCERT, NOTTLS: nothing visible to record. Pass the flow through. if {$v ne ""} { catch {call /Common/emudhra_lib::record $emu_key $v "passive" $emu_hsl $emu_dst $emu_port $emu_sni} catch {call /Common/emudhra_lib::seen $emu_hsl $emu_client $emu_key [lindex $v 0] "passive" $emu_dst $emu_port $emu_sni} if {[lindex $v 0] eq "BLOCK" && $static::emu_mode eq "enforce"} { if {![catch {call /Common/emudhra_lib::first_in emudhra_blklog "$emu_client|$emu_key" 60} f] && $f} { HSL::send $emu_hsl "<132>emudhra event=block src=passive key=$emu_key client=$emu_client dst=$emu_dst dport=$emu_port sni=$emu_sni" } reject return } } TCP::release }