SBC (B2BUA)¶
A Session Border Controller sits between two networks as a back-to-back user agent:
two fully independent dialogs, topology hiding, media anchoring, and control over
exactly which headers cross the trust boundary. In SIPhon the B2BUA is first-class —
no entity IDs, no bridge calls, just @b2bua.* handlers and a call object.
The call lifecycle¶
from siphon import b2bua, gateway, log
@b2bua.on_invite
def on_invite(call):
call.media.anchor(engine="rtpengine") # hide media topology
call.remove_headers_matching("^X-") # strip internal headers
gw = gateway.select("carriers") # pick a trunk
call.dial(gw.uri, timeout=30) # dial the B-leg
@b2bua.on_provisional
def on_provisional(call, reply):
log.info(f"[{call.id}] {reply.status_code} from the callee")
@b2bua.on_early_media
def on_early_media(call, reply):
log.info(f"[{call.id}] early media {reply.status_code}")
@b2bua.on_answer
def on_answer(call, reply):
log.info(f"[{call.id}] answered")
@b2bua.on_failure
def on_failure(call, code, reason):
call.reject(code, reason) # propagate to the A-leg
@b2bua.on_bye
def on_bye(call, initiator):
call.media.release()
log.info(f"[{call.id}] ended by {initiator.side}")
@b2bua.on_cancel
def on_cancel(call): # caller abandoned before answer
log.info(f"[{call.id}] cancelled")
Each B-leg gets its own Call-ID and From-tag by default, so the two dialogs are fully
decoupled — topology hiding out of the box. Other call methods: call.fork(targets)
(ring several B-legs), call.reject(code, reason), call.terminate(),
call.set_header / remove_header, and B-leg URI rewrites — userpart
(call.set_ruri_user / set_from_user / set_to_user) and host
(call.set_from_host / set_to_host).
Keeping a tenant domain in the From¶
Topology hiding rewrites the B-leg From host to SIPhon's advertised address and the To host to the dial target. That's the right default, but a multitenant downstream that selects the tenant from the From domain needs the original domain to survive — a domainless From lands the call in its unauthenticated/default routing context. Pin it:
@b2bua.on_invite
def on_invite(call):
call.set_from_host("tenant.example.com") # keep the tenant domain in From
call.dial(str(call.ruri), next_hop="sip:pbx.example.com:5060")
set_from_host opts that leg out of the From host-rewrite; set_to_host pins the To
host the same way (a declarative replacement for hand-building
set_header("To", "<sip:user@host>")). Only the host changes — scheme, user, port,
params, and tags are preserved — and both apply to call.dial() and call.fork().
A target that is not a SIP URI has no host to give the To. call.dial("tel:+15550100",
next_hop=...) sends tel:+15550100 as the Request-URI (RFC 3966) and leaves the To as
the caller wrote it, its host included, which is what a B2BUA that routes a request on
unchanged wants. Where the caller-facing host must not cross, pin one with
set_to_host.
Header policies — control what crosses the boundary¶
The whole point of an SBC is deciding which headers leak between two networks. SIPhon handles this with named, versioned header policies instead of hand-rolled strip/copy logic on every call.
call.dial(
"sip:5112@ims.example.com",
header_policy="ims-trust-domain-boundary@2026",
copy=["X-Operator-Tag"], # also let this one through
strip=["History-Info"], # also drop this one
translate=[("Diversion", "rfc7044")], # rewrite Diversion → History-Info
)
Built-in presets¶
Pin the version (@2026) so a SIPhon upgrade can't silently change which headers
cross the boundary.
| Preset | Use at | Behaviour |
|---|---|---|
transparent-b2bua@2026 |
general SBC (default) | today's strip set; behaviour-equivalent to pre-policy SIPhon |
ims-intra-trust-domain@2026 |
S-CSCF ↔ AS | passes P-* headers + end-to-end preconditions |
ims-trust-domain-boundary@2026 |
P-CSCF / IBCF / BGCF edge | strict trust-boundary hygiene |
sip-trunk-edge@2026 |
plain SIP trunk | strips P-* / X-* |
Set a default for all calls in siphon.yaml and override per call as needed:
Need a posture none of them quite match? Define your own — see Custom policies below.
Custom policies¶
When your posture is "that preset, except for these headers", define your own in
siphon.yaml rather than repeating copy=[…] on every dial() call site. Custom
policies live in the same namespace as the built-ins, so scripts and
default_header_policy select them the same way.
header_policies:
"trunk-edge-plus@1":
extends: "sip-trunk-edge@2026"
request:
copy: ["X-Account-Ref"] # crosses despite the base's X-* strip
strip: ["Alert-Info"]
rewrite:
P-Asserted-Identity: host-to-advertised
translate:
Diversion: diversion-to-history-info
response:
strip: ["Server"]
b2bua:
default_header_policy: "trunk-edge-plus@1"
The base supplies each direction's default and its rules; the rules you write are
matched first, so they win. A direction you leave out is inherited verbatim, and an
extends: with no rules at all is just a stable local alias for a built-in.
Drop extends: to declare a policy in full, in which case each direction needs its
own default: (copy or strip):
header_policies:
"locked-down@1":
request:
default: strip
copy: ["Allow", "Supported", "Content-Type"]
response:
default: copy
strip: ["P-*", "Server", "User-Agent"]
Header names are exact and case-insensitive; a trailing * is a prefix match
("X-*"), not a glob. Within one direction an exact name beats a prefix and a longer
prefix beats a shorter one, so strip: ["X-*"] alongside copy: ["X-Account-Ref"]
does what it looks like. rewrite: ops are host-to-advertised,
replace-with-server-header and replace-with-user-agent-header; translate: ops
are diversion-to-history-info (alias rfc7044).
The map key is the name scripts pin and must carry an @version — same rule as the
built-ins — and it may not take a built-in's name. Policies are resolved and
validated at startup, so an unknown op, a rule aimed at a framework-managed header,
or a default_header_policy naming a policy nothing defines stops the node at boot
instead of surfacing mid-call.
Per-call deltas¶
On top of the preset, copy / strip / translate apply per call — for emergency
calls, aggregator quirks, etc. that a policy can't express. translate ops in v1 are
rfc7044 and diversion-to-history-info. Per-call deltas match exact header names
only; prefix patterns are a config-side feature.
Precedence (highest wins)¶
- Script
call.set_header()/call.remove_header()/call.remove_headers_matching()on the A-leg INVITE. The header goes out on the B-leg as the script left it: no preset or per-call delta strips, rewrites or translates it. copy=/strip=/translate=per-call deltas- The named preset's overrides
- The named preset's default copy/strip set
Outside the list, the framework-managed headers are SIPhon's whatever the script
or the policy says: Via, Call-ID, CSeq, Max-Forwards, Content-Length,
From, To, Contact, Record-Route, Route. Proxy-Authorization and
Proxy-Authenticate are not among them: every preset strips them (RFC 3261 §22.3),
but copy= or a script can carry them.
A few steps run after the policy and still apply on top of a script's value: the
number policy and a carrier's caller ID and CLIR on the identity headers, LCR route
headers, SIPhon's Session-Expires / Min-SE when it runs the session timer, and
replaces merged into Supported.
Responses work the same way. What a script does to a B-leg response in
@b2bua.on_answer, @b2bua.on_provisional or @b2bua.on_early_media with reply.set_header() /
reply.remove_header() / reply.remove_headers_matching() reaches the caller as the
script left it, over the response policy and SIPhon's own Supported / Allow.
SIPhon still sets the caller's Contact, drops the callee's Record-Route, decides a
provisional's reliability itself (RSeq and the 100rel tag in Require, see
below), adds its Supported: timer / Session-Expires when absent while it runs the
session timer, merges replaces into Supported, and rewrites the SDP origin.
One intentional change from pre-policy SIPhon
Every preset strips Proxy-Authenticate on B→A responses. RFC 3261 §22.3 makes
it hop-by-hop, so passing it through would point the A-leg's
Proxy-Authorization at the wrong realm. Opt back in with
copy=["Proxy-Authenticate"] if you really want the old transparent behaviour.
Reliable provisionals toward the caller¶
SIPhon PRACKs the callee's reliable provisionals itself on the B-leg, and it is the caller's UAS on the A-leg, so RFC 3262 on each leg is SIPhon's, under every preset:
- A provisional reaches the caller reliably when the caller sent
Require: 100rel, or sentSupported: 100reland either the callee sent that provisional reliably or it carries SDP (an 18x without SDP stays as the callee sent it). It carriesRequire: 100reland SIPhon's ownRSeq, one more per provisional on the caller's dialog. The callee'sRSeqnever reaches the caller. - It is retransmitted (T1 doubling) until the caller's PRACK, and the next reliable provisional waits for that PRACK.
- SIPhon answers the PRACK:
200when itsRAcknames a provisional SIPhon sent on that dialog (again for a retransmission, and after the final response),481otherwise. A PRACK is never relayed and its body is not bridged; an early offer goes in anUPDATE, which is. - A 2xx waits for the PRACK of a reliable provisional that carried SDP, and follows
that PRACK's
200. Only then is it retransmitted until the caller's ACK, with the 64×T1 no-ACK teardown and the BYE held for the ACK that every 2xx gets. A call that ends while the 2xx waits (a BYE from the callee, a CANCEL from the caller, a timer) gives the caller487 Request Terminated, never a BYE, and the callee a BYE. A final response stops the retransmissions. - The 2xx carries the answer unless the caller's dialog already had it reliably
(RFC 3261 §13.2.1). A callee that answered in a reliable provisional may send its
2xx without SDP. A caller that got that provisional reliably has the answer, and
its 2xx goes without SDP too. A caller that does not use
100relwas only shown a preview of it in an unreliable provisional, so its 2xx carries that same session description, as the media engine left it on the way to the caller and under the sameo=line (RFC 6337 §3.1.1). With a fork it is the answering callee's own. A callee's 2xx that does carry SDP after such a preview goes out under the preview'so=session id: at the same version, byte for byte, when it repeats the previewed description, and at the next version, with aWARN, when it differs, since the caller may ignore a second answer (RFC 3261 §13.2.1). - A caller that leaves a reliable provisional unacknowledged for 32 s (64×T1) is
refused
500. The callee is CANCELled, or BYEd if its 2xx was the one waiting.@b2bua.on_failuredoes not run: routing elsewhere cannot make the caller PRACK. A call already being torn down some other way is left to that teardown.
call.progress() and call.answer() follow the same rules. RSeq and the 100rel
tag are SIPhon's alone: a reply.set_header() of either in @b2bua.on_provisional
or @b2bua.on_early_media does not reach the caller.
Provisional responses¶
@b2bua.on_provisional(call, reply) runs for every provisional response of the
callee that SIPhon relays to the caller, 101 to 199, whether it carries SDP or not.
A phone that rings normally answers 180 without a body, so this is the hook that
tells a script the callee is being alerted, and the place to mark what the caller
sees of it:
@b2bua.on_provisional
def on_provisional(call, reply):
if reply.status_code == 180:
reply.set_header("Privacy", "id")
@b2bua.on_early_media(call, reply) runs only for a provisional with SDP, and is
where the session description goes through the media engine. A response with SDP
runs both, on_provisional first, on the same reply. Neither runs for a
100 Trying, which is hop by hop, nor for a provisional SIPhon does not relay:
one that arrives after the answer, or from a leg that has already ended.
Ringback toward the calling network¶
A callee may answer the INVITE's offer in a reliable 183 "without any intention
of sending early media (this is the case when preconditions are used)", so "by only
looking at the SIP signalling, a UAC cannot be sure whether or not there will be
early media" (RFC 3960 §3.2). Inside an IMS the P-Early-Media header settles it
(RFC 5009): a gateway starts ringing on a 180 unless the most recent
P-Early-Media authorises backward early media (TS 29.163 §7.2.3.2.4). A calling
network that does not read the header, and takes any session description in a
provisional for early media, stops generating ringback and plays its caller silence
until the answer.
At that edge, show the caller a session description only when the callee authorises media toward it, and relay every other provisional without its body:
def early_media_authorised(reply):
early_media = (reply.get_header("P-Early-Media") or "").lower()
return "sendrecv" in early_media or "sendonly" in early_media
@b2bua.on_provisional
def on_provisional(call, reply):
if reply.has_body("application/sdp") and not early_media_authorised(reply):
reply.relay(body=False)
A 180 without SDP is relayed as it is, which is what makes the calling network
ring (RFC 3960 §3.2: "If a 180 (Ringing) has been received but there are no
incoming media packets, generate local ringing"). reply.withhold() relays nothing
for a response instead. The callee's dialog goes on as it would have: SIPhon PRACKs
the reliable provisional, @b2bua.on_early_media still runs with the session
description for the media engine, and an UPDATE on the early dialog is handled as
for any caller that has not had the answer reliably: SIPhon answers a callee's
itself (see "Preconditions before the answer"). The caller gets the answer in
the 2xx, also when the callee's 2xx carries none (RFC 3261 §13.2.1). An authorised
provisional that follows is relayed with its session description. With a fork each
callee's provisional runs the handler and is judged on its own header.
Toward a caller that uses 100rel the provisional without its body is still sent
reliably when the callee's was, which RFC 3262 allows, and a withheld one takes no
RSeq on the caller's dialog.
Supported and Allow on both legs¶
SIPhon is the UAC of the B-leg and the UAS of the A-leg, so the B-leg INVITE's
Supported and Allow, and those of every response it relays back to the caller,
say what SIPhon supports (RFC 3261 §20.37, §20.5). They are not a copy of the other
party's lists, whatever the preset does with the rest of the headers.
A relayed response follows the same rule as the INVITE, mirrored: the callee's
100rel/timer and the end-to-end tags below survive, plus replaces, and Allow
is SIPhon's. transparent-b2bua@2026 strips the callee's Supported on responses
before that, so its responses carry just Supported: replaces.
On the B-leg INVITE:
Allowis SIPhon's method set, the same one its responses advertise.Supportedisreplaces, plustimerwhen SIPhon runs the session timer, plus the caller's100relandtimerif it offered them. On top of that go the tags of extensions the two endpoints negotiate with each other through SIPhon, if the caller offered them and the policy copies what they negotiate with on requests and on responses:
| Tag | Needs the policy to copy |
|---|---|
precondition (RFC 3312) |
Supported and Require, both ways |
histinfo (RFC 7044) |
History-Info, both ways |
resource-priority (RFC 4412) |
Resource-Priority on the request, Accept-Resource-Priority on the response |
Half a negotiation is no negotiation: a callee's Require: precondition that cannot
reach the caller leaves preconditions stuck. A caller offering
Supported: 100rel, timer, precondition, histinfo, resource-priority, outbound, path:
| Preset | B-leg INVITE carries |
|---|---|
transparent-b2bua@2026 |
Supported: 100rel,timer,histinfo,resource-priority,replaces |
ims-intra-trust-domain@2026 |
Supported: 100rel,timer,precondition,histinfo,resource-priority,replaces |
ims-trust-domain-boundary@2026 |
Supported: 100rel,timer,precondition,replaces |
sip-trunk-edge@2026 |
Supported: 100rel,timer,precondition,resource-priority,replaces |
Any other tag the caller lists is dropped. Per-call deltas feed the same test:
copy=["Supported", "Require"] lets precondition cross under the default preset,
strip=["History-Info"] keeps histinfo off anywhere, and
copy=["Resource-Priority", "Accept-Resource-Priority"] opens resource-priority at
the trust boundary. copy=["Supported"] on its own does not relay the caller's list,
since every preset already copies Supported on requests. When a far end really needs
the caller's list, set it from the script, which is precedence 1 and goes out as
written even past a strip=:
replaces, and timer when SIPhon runs the session timer, are still merged into a
Supported the script set. call.remove_header("Allow") sends no Allow at all.
A smaller Allow toward one trunk¶
Some trunk peers pick their transfer method from the Allow they are shown: with
REFER listed they send SIPhon a REFER, without it they transfer the call
themselves. To keep REFER (or anything else) out of what one peer sees, give its
gateway group allow_methods:
gateway:
groups:
- name: "trunk-a"
allow_methods: [INVITE, ACK, CANCEL, BYE, OPTIONS, PRACK, UPDATE]
destinations:
- uri: "sip:198.51.100.7:5060"
That set replaces the full one on everything SIPhon sends that peer or answers it
with: responses relayed to a caller from the group, SIPhon's own 18x/2xx
(answer/ring/progress), its OPTIONS and 405 answers, the health-probe OPTIONS,
and B-leg or originated INVITEs sent to the group. Every other peer keeps the full
set. A peer is in the group by the membership call.from_gateway() uses (resolved
destination addresses plus source_networks); a peer two groups with a set admit
gets the set of the group listed first. An Allow a script sets, or one in a
controller's headers, still wins.
Each entry must be a method SIPhon implements, in upper case, listed once, and
INVITE, ACK, CANCEL and BYE are required; anything else refuses the config.
The set only changes what is advertised: a REFER the peer sends anyway is still
handled.
Preconditions before the answer¶
With precondition crossing, the exchange itself runs on the early dialog
(RFC 3312 §5): the callee answers the INVITE's offer in a reliable 183, the caller
PRACKs it, and whichever side has reserved its resources says so in an UPDATE with
a new offer, before the callee alerts. SIPhon relays that UPDATE to the other
party's early dialog and returns the 2xx with its answer, through the media engine
on an anchored call, and keeps precondition in the relayed UPDATE's Require /
Supported. Nothing in the script takes part.
An UPDATE with an offer crosses only once both early dialogs can carry one: the
answer to the INVITE's offer went in a reliable provisional that was PRACKed on
each, and no other offer is in flight. Until then it is refused as RFC 3311 §5.2
has it, 500 with a Retry-After of 0 to 10 seconds to try again, or 491 when it
crosses an offer of the other party's, and the session stays as it was. A callee
that sends its 183 unreliably has not answered yet (RFC 3262 §5), so a caller's
UPDATE waits for that callee's 2xx.
One UPDATE that cannot cross is answered instead of refused. A caller that does
not use 100rel, or that a script relayed the callee's 183 to without its body,
takes the answer to its INVITE in the 2xx, and until then its dialog can be sent
no offer at all (RFC 3311 §5.1). The callee has its answer and may send an UPDATE
all the same, typically the one that reports its resources reserved. SIPhon is
the UAC of the callee's dialog, so it answers that UPDATE 200 there with what
the caller would say: the caller's own stream as the INVITE offered it, the
formats both sides list, and the precondition status of a party with nothing to
reserve (RFC 3312 §5.2). For a callee's offer of
a=curr:qos local sendrecv
a=curr:qos remote none
a=des:qos mandatory local sendrecv
a=des:qos optional remote sendrecv
the answer carries, every tag inverted for the answerer:
a=curr:qos local sendrecv
a=curr:qos remote sendrecv
a=des:qos optional local sendrecv
a=des:qos mandatory remote sendrecv
The caller's 2xx then carries the callee's session description as that UPDATE
left it (a changed address or port included) without the callee's precondition
attributes, also when the callee's own 2xx has no SDP. On an anchored call the
offer and the answer go through the media engine as a relayed UPDATE's do.
Nothing in the script takes part here either: no handler runs for the UPDATE,
@b2bua.on_answer sees the callee's 2xx as it came, and SIPhon adds the session
description to no provisional.
This holds only where SIPhon can speak for the caller. The UPDATE is still
refused 500 with a Retry-After when the caller's own offer carries
preconditions, which are then the two endpoints' to settle and need a caller
that uses 100rel (RFC 3312 §11), when a stream is keyed, uses ICE or is grouped
(a=crypto, a=fingerprint, a=ice-ufrag, a=mid), or when the offer shares
no format with the caller's.
A caller's Require¶
The same rule decides whether SIPhon can take a call whose INVITE requires an
extension. SIPhon is the caller's UAS, so a Require the call cannot honour is
refused 420 Bad Extension with the tags listed in Unsupported (RFC 3261 §8.2.2.3),
before any B-leg goes out. A tag is honoured when SIPhon implements it (100rel,
timer, replaces, and sec-agree once the caller's IPsec agreement is verified),
or when the policy passes it end to end per the table above and copies Require
to the callee. Require: precondition under
transparent-b2bua@2026 is refused; under ims-intra-trust-domain@2026 it is dialled.
The check runs when call.dial() / fork() / route() is carried out, since that
is when the policy is known. The 420 then goes through @b2bua.on_failure like any
call that could not be connected, so the handler can route again under a relaying
policy:
@b2bua.on_failure
def on_failure(call, code, reason):
if code == 420:
call.dial(str(call.ruri), header_policy="ims-intra-trust-domain@2026")
The paths that answer the caller or dial for it without a script's routing action
refuse the same 420 and end the call without @b2bua.on_failure. When SIPhon answers
the call itself (call.answer(), the control plane's answer,
call.handover(answer=True)), it is the only UAS the caller has, so any tag it does
not implement is refused whatever the policy, before an answer-first handover anchors
media. The control plane's dial and route are checked under the call's policy
when they dial; a refused dial reports DialFailed with code 420. An INVITE with
Replaces is refused on its own transaction before the call it names is touched.
call.progress() is not checked, since a provisional answers nothing.
Add media anchoring¶
call.media.anchor(engine="rtpengine") hides the media path too. For SRTP↔RTP
interworking, WebRTC, transcoding, hold, or announcements, drive RTPEngine directly —
see Media & RTP profiles:
from siphon import b2bua, rtpengine
@b2bua.on_invite
async def on_invite(call):
await rtpengine.offer(call, profile="srtp_to_rtp") # SRTP UE ↔ RTP trunk
call.dial(str(call.ruri))
@b2bua.on_answer
async def on_answer(call, reply):
await rtpengine.answer(reply, profile="srtp_to_rtp", call=call)
@b2bua.on_bye
async def on_bye(call, initiator):
await rtpengine.delete(call)
Hybrid: proxy + SBC in one script¶
INVITEs go to @b2bua.on_invite; REGISTER/OPTIONS/etc. go to @proxy.on_request —
in the same script, same process. So you can B2BUA calls (topology hiding + media)
while lightly proxying registrations:
@proxy.on_request("REGISTER")
async def on_register(request):
if await auth.require_digest(request, realm=DOMAIN):
registrar.save(request)
@b2bua.on_invite
def on_invite(call):
call.media.anchor(engine="rtpengine")
call.dial(gateway.select("carriers").uri)
Authenticate the caller before dialling anything¶
A B2BUA facing untrusted callers should challenge them, not just route them.
Registering any @b2bua.* handler takes INVITE off the proxy path, so a
@proxy.on_request("INVITE") challenge would never run — pass the call to the
digest helpers instead:
from siphon import auth, b2bua, gateway, log
@b2bua.on_invite
async def on_invite(call):
if not await auth.require_proxy_digest(call, realm=DOMAIN):
return # 407 armed; siphon answers the A-leg
log.info(f"authenticated {call.auth_user}")
call.media.anchor(engine="rtpengine")
call.dial(gateway.select("carriers").uri)
An unauthenticated caller gets siphon's own 407 and no B-leg is dialled —
the challenge is armed as the call's deferred reject, so the call actor is
dropped before any trunk sees traffic. That ordering is the point: a toll-fraud
probe never reaches your carrier. The caller re-INVITEs with credentials,
require_proxy_digest returns True, and the hop-by-hop Proxy-Authorization
is stripped before the B-leg INVITE is built (RFC 3261 §22.3).
Pair it with anti-spoofing on the caller ID, as on the proxy path:
from_user = call.from_uri.user if call.from_uri else None
if call.auth_user != from_user:
call.reject(403, "Forbidden")
return
Two different auth directions
Challenging on the call is siphon authenticating its caller.
call.dial(..., auth_passthrough=True) is the opposite: a downstream PBX
or trunk challenges, and siphon relays that challenge to the caller to answer
end-to-end. A third option, call.set_credentials(user, password), has
siphon answer the downstream challenge itself.
Upstream trunk requiring mutual TLS¶
Some upstream SIP trunks require siphon to present a client certificate when
it dials out over TLS — mutual TLS (for example Microsoft Teams Direct Routing).
Without one, the peer aborts the handshake with CertificateUnknown. Attach the
client identity in the top-level tls: block:
tls:
certificate: "/etc/siphon/tls/example.com.crt" # inbound server cert
private_key: "/etc/siphon/tls/example.com.key"
# Presented on OUTBOUND TLS when the upstream trunk requests a client cert:
client_certificate: "/etc/siphon/tls/client.crt"
client_private_key: "/etc/siphon/tls/client.key"
Then dial the trunk over TLS as usual — the B2BUA presents the configured client certificate automatically:
@b2bua.on_invite
def on_invite(call):
call.media.anchor(engine="rtpengine")
call.dial("sip:+15551234567@sbc.example.com;transport=tls")
Both client_certificate and client_private_key must be set together (or
neither); a one-sided setting or an unreadable file fails startup. The outbound
handshake also sends the target hostname (sbc.example.com) as SNI, so a
hostname-vhost trunk front-end can route it.
The client certificate proves siphon to the trunk; it says nothing about the trunk to siphon. To authenticate the trunk too, turn on server verification for it, globally or on the gateway that reaches it:
tls:
# ...client_certificate / client_private_key as above...
verify_server: true # check the certificate of every trunk dialled
# server_ca: "/etc/siphon/tls/trunk-ca.pem" # only for a private CA
The trunk then has to present a certificate for sbc.example.com (the host you
dial, never its resolved address) that chains to a trusted CA, or the call fails
as an unreachable trunk would. See Verifying the server siphon
dials for the matching
rules and per-gateway settings.
Terminate strict peers (Teams) as a B2BUA, not a plain proxy
Microsoft Teams Direct Routing rejects any Contact or Record-Route whose
host is an IP (403 Forbidden) — it must be the SBC FQDN that matches the TLS
certificate. The B2BUA rewrites Contact to siphon's advertised address, so
set advertised_address (or the per-listener advertise) to that FQDN and it
satisfies the requirement. A pure proxy (@proxy.on_request relaying
INVITEs) forwards the upstream UA's Contact verbatim — typically a PBX's
private IP — which Teams refuses; RFC 3261 §16 forbids a proxy from rewriting
another UA's Contact, so this is by design, not a bug. Front Teams-facing
signalling with @b2bua.on_invite. siphon's OPTIONS keepalive and its 200 OK
to Teams' OPTIONS already carry the advertised FQDN in Contact plus an
Allow advertising the supported methods (including REFER/NOTIFY).
Phones and a strict trunk on separate TLS listeners¶
A trunk peer that admits only its configured FQDN in Contact, Via and
Record-Route and the phones registering on the same box need two identities.
Give each its own TLS listener; each message names the listener it leaves on.
listen:
tls:
- "192.0.2.10:5061" # phones
- address: "192.0.2.10:15068"
advertise: "sbc.example.test:5068" # the name the trunk accepts
gateway:
groups:
- name: "trunk"
probe_listener: "192.0.2.10:15068" # probes advertise the trunk name
destinations:
- uri: "sip:trunk.example.test:5061;transport=tls"
@b2bua.on_invite
def on_invite(call):
if call.from_gateway("trunk"):
# Toward a phone: its own connection is reused, so the B-leg names
# the phone listener.
call.dial(call.ruri)
else:
# Toward the trunk: pin the trunk listener, so Via, Contact and From
# name sbc.example.test:5068 whatever the listener order.
call.dial("sip:+15550100@trunk.example.test;transport=tls",
send_socket="tls:192.0.2.10:15068")
Answers to the trunk's own requests (its INVITEs, its OPTIONS) name the trunk
listener because that is where they arrived. Without the send_socket= pin a
new connection to the trunk advertises the transport's identity, the first TLS
listener with an advertise, which works here but breaks as soon as the phone
listener gets an advertise of its own and is listed first. See
Several listeners of one transport.
See also¶
- Real examples:
scripts/b2bua_default.py,examples/b2bua_gateway.py,examples/b2bua_rtpengine.py. - Media & RTP profiles — the RTPEngine profiles in depth.
- Hardening & security — STIR/SHAKEN at the edge, TLS, IPsec.