DOCSEARCHbyAlgolia
Submit Docs

REALITY Protocol Documentation

repository·main·Indexed 25 days ago

https://github.com/xtls/reality

A server-side implementation of the REALITY protocol and a fork of the Go crypto/tls package. REALITY provides high-stealth proxying by mimicking real TLS handshakes of legitimate websites to eliminate server-side TLS fingerprinting. The documentation covers VLESS inbound and outbound configurations, target website selection guidelines, and detailed API references for TLS configurations, cipher suites, and Encrypted Client Hello (ECH).

Tokens
10.1K
Snippets
13
Records
68
Agent score
90%

What's inside REALITY

  1. Select a target website for REALITY

    main

    When choosing a target website to mimic with REALITY, follow these guidelines for optimal performance and stealth:

    Minimum Requirements:

    • The website should be hosted outside your local region (e.g., international sites).
    • Must support TLSv1.3 and H2 (HTTP/2).
    • The domain should not automatically redirect (the primary domain might redirect to www, which is acceptable).

    Recommended (High Quality) Targets:

    • Low latency (IP is geographically close to your server).
    • Supports encrypted handshake messages after Server Hello (e.g., dl.google.com).
    • Supports OCSP Stapling.

    Stealth Tips:

    • Use a relatively uncommon target IP to avoid detection.
    • Consider forwarding TCP/80 and UDP/443 to the target to make the server appear as a simple port forwarder.

  2. Configure REALITY Client-side (VLESS Outbound)

    main

    To connect to a REALITY server, configure a vless outbound with security set to reality.

    Key configuration requirements:

    • address: The server's domain or IP.
    • serverName: Must match one of the serverNames configured on the server.
    • password: The public key corresponding to the server's privateKey.
    • shortId: Must match one of the shortIds configured on the server.
    • fingerprint: The uTLS library fingerprint to simulate (e.g., chrome).
    • mldsa65Verify: The public key generated from the server's mldsa65Seed for post-quantum verification.
    • spiderX: An initial path/parameter for the crawler (recommended to be unique per client).
    {
    "outbounds": [
        {
            "protocol": "vless",
            "settings": {
                "vnext": [
                    {
                        "address": "", // Server domain or IP
                        "port": 443,
                        "users": [
                            {
                                "id": "", // Must match server
                                "flow": "xtls-rprx-vision",
                                "encryption": "none"
                            }
                        ]
                    }
                ]
            },
            "streamSettings": {
                "network": "raw",
                "security": "reality",
                "realitySettings": {
                    "show": false,
                    "fingerprint": "chrome",
                    "serverName": "", // Must be in server's serverNames
                    "password": "", // Server's public key
                    "shortId": "", // Must be in server's shortIds
                    "mldsa65Verify": "", // Server's mldsa65Verify public key
                    "spiderX": ""
                }
            }
        }
    ]
}

  3. Configure REALITY Server-side (VLESS Inbound)

    main

    To implement the REALITY protocol on the server side, use a vless inbound configuration with security set to reality.

    Key configuration requirements:

    • target: The destination address (e.g., example.com:443) that the server will mimic.
    • serverNames: A list of valid SNIs the client can use.
    • privateKey: Generated using ./xray x25519.
    • shortIds: A list of valid short IDs (0-f, length multiple of 2, max 16 chars) used to distinguish clients.
    • id: A UUID or a 1-30 byte string.
    • flow: Set to xtls-rprx-vision if using XTLS.

    Note: REALITY can eliminate server-side TLS fingerprinting and provides security superior to conventional TLS by presenting a real TLS handshake to middlemen.

    {
    "inbounds": [
        {
            "listen": "0.0.0.0",
            "port": 443,
            "protocol": "vless",
            "settings": {
                "clients": [
                    {
                        "id": "", // UUID or 1-30 byte string
                        "flow": "xtls-rprx-vision"
                    }
                ],
                "decryption": "none"
            },
            "streamSettings": {
                "network": "raw",
                "security": "reality",
                "realitySettings": {
                    "show": false,
                    "target": "example.com:443",
                    "xver": 0,
                    "serverNames": [
                        "example.com",
                        "www.example.com"
                    ],
                    "privateKey": "", // Generated via ./xray x25519
                    "minClientVer": "",
                    "maxClientVer": "",
                    "maxTimeDiff": 0,
                    "shortIds": [
                        "",
                        "0123456789abcdef"
                    ],
                    "mldsa65Seed": "", // Generated via ./xray mldsa65
                    "limitFallbackUpload": {
                        "afterBytes": 0,
                        "bytesPerSec": 0,
                        "burstBytesPerSec": 0
                    },
                    "limitFallbackDownload": {
                        "afterBytes": 0,
                        "bytesPerSec": 0,
                        "burstBytesPerSec": 0
                    }
                }
            }
        }
    ]
}

  4. Manual REALITY server handshake

    main
    If you are not using the provided reality.Listener (for example, when using Xray-core's RAW transport), you must manually call DetectPostHandshakeRecordsLens(config) in advance. To wrap an existing connection manually, use Server(ctx, conn, config).

  5. Create a REALITY server listener from a network address

    main
    Use Listen to create a new net.Listener that accepts connections on a specific network and address, wrapping them with REALITY server-side logic. The Config must be non-nil and must include at least one certificate or a GetCertificate callback.

  6. Create a REALITY server listener

    main
    Use NewListener to wrap an existing net.Listener with REALITY server-side logic. This allows you to accept incoming connections and automatically upgrade them to REALITY connections using the provided Config. Note that NewListener internally calls DetectPostHandshakeRecordsLens(config), so you do not need to call it manually when using this listener.

  7. Manage the QUIC handshake lifecycle

    main
    After creating a QUICConn, you must call Start(ctx) to begin the handshake protocol. During the handshake, you must provide handshake bytes received from the peer using HandleData(level, data). To monitor the progress and react to protocol requirements, call NextEvent() to retrieve QUICEvent objects.

  8. Configure Encrypted Client Hello (ECH) with EchConfig

    main

    The EchConfig struct represents a single ECH configuration used to encrypt the ClientHello. It contains the following fields:

    • Version: The ECH version.
    • Length: The length of the configuration.
    • ConfigID: A unique identifier for the configuration.
    • KemID: The Key Encapsulation Mechanism ID.
    • PublicKey: The public key for the KEM.
    • SymmetricCipherSuite: A slice of EchCipher defining supported KDF and AEAD IDs.
    • MaxNameLength: Maximum length for the public name.
    • PublicName: The public name (DNS name) associated with this config.
    • Extensions: A slice of echExtension containing additional ECH extensions.
    type EchConfig struct {
	Version uint16
	Length  uint16
	ConfigID             uint8
	KemID                uint16
	PublicKey            []byte
	SymmetricCipherSuite []EchCipher
	MaxNameLength uint8
	PublicName    []byte
	Extensions    []echExtension
}

type EchCipher struct {
	KDFID  uint16
	AEADID uint16
}

type echExtension struct {
	Type uint16
	Data []byte
}

  9. Configure TLS via the Config struct

    main

    The Config struct is used to set up both TLS clients and servers. Key configuration options include:

    • Certificates: A list of certificate chains to present.
    • GetCertificate: A callback to select a certificate based on ClientHelloInfo (useful for SNI).
    • GetConfigForClient: A callback to return a new Config after receiving a ClientHello (useful for virtual hosting).
    • ClientAuth: The ClientAuthType policy.
    • RootCAs: The set of root CAs used by clients to verify servers.
    • ClientCAs: The set of root CAs used by servers to verify clients.
    • MinVersion / MaxVersion: Limits the acceptable TLS versions.
    • CurvePreferences: A list of supported key exchange mechanisms.
    • NextProtos: Supported application-level protocols (ALPN).
    • InsecureSkipVerify: If true, the client accepts any certificate presented by the server.

  10. Configure QUIC session events and resumption

    main

    To enable session resumption features, set EnableSessionEvents: true in your QUICConfig.

    • On the Client: When a QUICStoreSession event is received, use StoreSession(session *SessionState) to save the session in your client cache.
    • On the Server: Use SendSessionTicket(opts QUICSessionTicketOptions) to send a session ticket to the client after the handshake is complete. You can specify if the ticket allows EarlyData (0-RTT).

  11. Configure Encrypted Client Hello (ECH)

    main

    ECH allows clients to encrypt the ClientHello.

    For Clients: Set EncryptedClientHelloConfigList with a serialized ECHConfigList. If set, MinVersion must be VersionTLS13.

    For Servers: Use GetEncryptedClientHelloKeys to return a slice of EncryptedClientHelloKey representing acceptable keys. If this function is provided, the EncryptedClientHelloKeys field is ignored.

  12. Initialize a QUIC connection with QUICClient or QUICServer

    main
    Use QUICClient to create a TLS client-side connection or QUICServer to create a TLS server-side connection using QUIC as the underlying transport. Both require a QUICConfig which must contain a TLSConfig with MinVersion set to at least VersionTLS13.