SagerNet / SagerNet/sing-box

Feature Request: Decouple REALITY handshake TLS from fallback forwarding

Open
#4,482 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
38.1k
Forks
4.6k
Avg merge
19d 15h
Merged PRs (30d)
1

Description

Feature Request: Decouple REALITY handshake TLS from fallback forwarding

Problem Description

In the current REALITY implementation, the handshake configuration serves two coupled purposes:

  1. TLS handshake template: sing-box connects to the handshake server, completes a real TLS handshake, and uses the obtained certificate, session ticket, and key exchange parameters to masquerade the connection to REALITY clients.
  2. Fallback forwarding: Unauthenticated connections (those without a valid UUID) are transparently forwarded to the handshake server.

This coupling has led to real-world incidents. One user recently reported (source) that his DMIT VPS was suspended for "stealing OpenAI and Cloudflare's resources." His VLESS-REALITY configuration had handshake.server pointing to cdn.microsoftxxxx.net (a Microsoft CDN domain) and listened on 0.0.0.0. Unauthenticated connections were being forwarded to the CDN, making DMIT's network monitoring detect that his server was being used as an anonymous relay to access third-party services — even though he never intended this.

This is not an isolated case. Any sing-box instance with REALITY enabled and a public-facing inbound port effectively becomes an open relay: anyone who can reach the port can use the server as a gateway to access the handshake server's origin. Hosting providers (DMIT, Oracle Cloud, and others adopting behavioral detection) may flag or suspend such instances.

Proposed Solution

Decouple the two responsibilities by introducing a separate fallback field (or a simple reject_on_auth_fail boolean), allowing users to control how unauthenticated connections are handled independently from the certificate source.

Option A — Minimal change: reject_fallback boolean

"reality": {
    "enabled": true,
    "handshake": {
        "server": "example.com",
        "server_port": 443
    },
    "reject_fallback": true   // new: drop unauthenticated connections instead of forwarding
}

Option B — Full decoupling: separate cert_source and fallback

"reality": {
    "enabled": true,
    "cert_source": {
        "server": "example.com",
        "server_port": 443    // only used for TLS handshake to obtain certificate parameters
    },
    "fallback": null           // null = reject; or point to a local/trusted server
}
Use Case
  • Users want to use a public HTTPS service as the TLS masquerade target (e.g., a CDN domain or their own domain hosted elsewhere)
  • Users do NOT want unauthenticated connections to be forwarded anywhere outside the local machine
  • The goal: preserve REALITY's traffic obfuscation while eliminating the open-relay risk
Limitations of Current Workarounds
Workaround Problem
Point handshake to a local HTTPS service with a self-signed cert Poor masquerade; client traffic is easily identifiable as non-standard
Point handshake to another server you own Fallback traffic still exits the VPS; the provider can still detect outbound forwarding behavior
Use iptables to restrict inbound source IPs Not practical for mobile clients or multi-IP environments
Additional Context

This is not an edge case. As more VPS providers adopt behavioral detection for proxy/abuse monitoring, REALITY users are increasingly caught between the protocol's need for a realistic handshake target and the security risk of running an open forwarder. A reject_fallback option would resolve this tension with minimal implementation effort.

Thank you for considering this.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue identifies the REALITY handshake and fallback behavior but names no implementation files, tests, or entry points. Start by locating the existing REALITY configuration and connection-handling code, then resolve whether the change should use a rejection flag or fully separate certificate and fallback settings; done means unauthenticated connections no longer become unintended external relays.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
networking, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.