Reality

[!NOTE] This document is partially generated by AI.

REALITY is a security layer that wraps your proxy traffic in a sophisticated TLS handshake, making it look like you are visiting a legitimate website (e.g., www.microsoft.com).

Network Support

• TCP: Supported (Stream-based).
• UDP: Not supported. Like standard TLS, REALITY is designed for stream-oriented traffic.

Client Configuration (Outbound)

When used as an outbound security layer, the reality block uses these fields:

Configuration Fields

• server_name (string): The mimicked SNI. This should match the domain of the website you are “borrowing” the handshake from.
• public_key (string): The REALITY public key provided by your server.
• short_id (string): A short hexadecimal string used for client identification and to prevent replay attacks.
• mldsa65_verify (string): (Advanced) Post-quantum verify data for enhanced security.
• debug (bool): Enables detailed logging for the REALITY handshake process.

---

Server Configuration (Inbound)

A REALITY server must be configured with a legitimate destination to mimic.

Configuration Fields

• dest (string): The actual destination for the mimicked traffic (e.g., www.google.com:443).
• private_key (string): The server’s REALITY private key.
• short_id (string array): A list of approved short IDs the server will accept from clients.
• mldsa65_signing_key (string): (Advanced) Post-quantum signing key for the Reality server.

Example Configuration

Outbound Example

{
  "reality": {
    "server_name": "www.apple.com",
    "public_key": "vL4P8-YOUR-PUBLIC-KEY-HERE",
    "short_id": "01234567"
  }
}

Inbound Example

{
  "reality": {
    "dest": "www.apple.com:443",
    "private_key": "YOUR-PRIVATE-KEY-HERE",
    "short_id": ["01234567", "abcdef89"]
  }
}

Developer Details

Mechanism

REALITY works by “stealing” the handshake from a legitimate server (dest). If a client provides a valid short_id and the correct public_key, REALITY highjacks the session for proxy traffic. Otherwise, it transparently forwards the handshake to dest, making it indistinguishable from a real connection to that site.

Post-Quantum Security

yuhaiin supports ML-DSA-65 (part of the CRYSTALS-Dilithium standard) to protect against future quantum computing attacks during the Reality handshake.

Implementation

Located in pkg/net/proxy/reality. It requires a tls layer to function correctly.