Categorygithub.com/xtls/reality
modulepackage
0.0.0-20240712055506-48f0b2d5ed6d
Repository: https://github.com/xtls/reality.git
Documentation: pkg.go.dev

# README

REALITY

THE NEXT FUTURE

Server side implementation of REALITY protocol, a fork of package tls in latest Go. For client side, please follow https://github.com/XTLS/Xray-core/blob/main/transport/internet/reality/reality.go.

TODO List: TODO

VLESS-XTLS-uTLS-REALITY example for Xray-core

中文 | English

{
    "inbounds": [ // Server Inbound Configuration
        {
            "listen": "0.0.0.0",
            "port": 443,
            "protocol": "vless",
            "settings": {
                "clients": [
                    {
                        "id": "", // Required, execute ./xray uuid to generate, or a string of 1-30 characters
                        "flow": "xtls-rprx-vision" // Optional, if any, client must enable XTLS
                    }
                ],
                "decryption": "none"
            },
            "streamSettings": {
                "network": "tcp",
                "security": "reality",
                "realitySettings": {
                    "show": false, // Optional, if true, output debugging information
                    "dest": "example.com:443", // Required, the format is the same as the dest of VLESS fallbacks
                    "xver": 0, // Optional, the format is the same as xver of VLESS fallbacks
                    "serverNames": [ // Required, the acceptable serverName list, does not support * wildcards for now
                        "example.com",
                        "www.example.com"
                    ],
                    "privateKey": "", // Required, execute ./xray x25519 to generate
                    "minClientVer": "", // Optional, minimum client Xray version, format is x.y.z
                    "maxClientVer": "", // Optional, the highest version of client Xray, the format is x.y.z
                    "maxTimeDiff": 0, // Optional, the maximum time difference allowed, in milliseconds
                    "shortIds": [ // Required, the acceptable shortId list, which can be used to distinguish different clients
                        "", // If there is this item, the client shortId can be empty
                        "0123456789abcdef" // 0 to f, the length is a multiple of 2, the maximum length is 16
                    ]
                }
            }
        }
    ]
}

REALITY is intented to replace the use of TLS, it can eliminate the detectable TLS fingerprint on the server side, while still maintain the forward secrecy, etc. Guard against the certificate chain attack, thus its security exceeds conventional TLS REALITY can point to other people's websites, no need to buy domain names, configure TLS server, more convenient to deploy a proxy service. It achieves full real TLS that is undistingwishable with the specified SNI to the middleman

For general proxy purposes, the minimum standard of the target website: Websites out of China's GFW, support TLSv1.3 and H2, the domain name is not used for redirection (the main domain name may be used to redirect to www) Bonus points: target website IP reside closer to proxy IP (looks more reasonable, and lower latency), handshake messages after Server Hello are encrypted together (such as dl.google.com), OCSP Stapling Configuration bonus items: Block the proxy traffic back to China, TCP/80, UDP/443 are also forwarded to target (REALITY behaves like port forwarding to the observer, the target IP may be better if it is an uncommon choice among REALITY users)

REALITY can also be used with proxy protocols other than XTLS, but this is not recommended due to their obvious and already targeted TLS in TLS characteristics The next main goal of REALITY is "pre-built mode", that is, to collect and build the characteristics of the target website in advance, and the next main goal of XTLS is 0-RTT

{
    "outbounds": [ // Client outbound configuration
        {
            "protocol": "vless",
            "settings": {
                "vnext": [
                    {
                        "address": "", // The domain name or IP of the server
                        "port": 443,
                        "users": [
                            {
                                "id": "", // consistent with the server
                                "flow": "xtls-rprx-vision", // consistent with the server
                                "encryption": "none"
                            }
                        ]
                    }
                ]
            },
            "streamSettings": {
                "network": "tcp",
                "security": "reality",
                "realitySettings": {
                    "show": false, // Optional, if true, output debugging information
                    "fingerprint": "chrome", // Required, use uTLS library to emulate client TLS fingerprint
                    "serverName": "", // One of the server serverNames
                    "publicKey": "", // The public key corresponding to the private key of the server
                    "shortId": "", // One of the server shortIds
                    "spiderX": "" // The initial path and parameters of the crawler, recommended to be different for each client
                }
            }
        }
    ]
}

The REALITY client should receive the "Temporary Trusted Certificate" issued by "Temporary Authentication Key", but the real certificate of the target website will be received in the following three cases:

  1. The REALITY server rejects the Client Hello of the client, and the traffic is redirected to the target website
  2. The Client Hello of the client is redirected to the target website by the middleman
  3. Man-in-the-middle attack, it may be the help of the target website, or it may be a certificate chain attack

The REALITY client can perfectly distinguish temporary trusted certificates, real certificates, and invalid certificates, and decide the next action:

  1. When the temporary trusted certificate is received, the proxy connection is available and everything is business as usual
  2. When the real certificate is received, enter the crawler mode (spiderX)
  3. When an invalid certificate is received, TLS alert will be sent and the connection will be disconnected

# Functions

CipherSuiteName returns the standard name for the passed cipher suite ID (e.g.
CipherSuites returns a list of cipher suites currently implemented by this package, excluding those with security issues, which are returned by [InsecureCipherSuites].
Client returns a new TLS client side connection using conn as the underlying transport.
Dial connects to the given network address using net.Dial and then initiates a TLS handshake, returning the resulting TLS connection.
DialWithDialer connects to the given network address using dialer.Dial and then initiates a TLS handshake, returning the resulting TLS connection.
InsecureCipherSuites returns a list of cipher suites currently implemented by this package and which have security issues.
Listen creates a TLS listener accepting connections on the given network address using net.Listen.
LoadX509KeyPair reads and parses a public/private key pair from a pair of files.
NewListener creates a Listener which accepts connections from an inner Listener and wraps each connection with [Server].
NewLRUClientSessionCache returns a [ClientSessionCache] with the given capacity that uses an LRU strategy.
NewResumptionState returns a state value that can be returned by [ClientSessionCache.Get] to resume a previous session.
ParseSessionState parses a [SessionState] encoded by [SessionState.Bytes].
QUICClient returns a new TLS client side connection using QUICTransport as the underlying transport.
QUICServer returns a new TLS server side connection using QUICTransport as the underlying transport.
Server returns a new TLS server side connection using conn as the underlying transport.
No description provided by the author
VersionName returns the name for the provided TLS version number (e.g.
X509KeyPair parses a public/private key pair from a pair of PEM encoded data.

# Constants

No description provided by the author
No description provided by the author
No description provided by the author
ECDSA algorithms.
No description provided by the author
No description provided by the author
No description provided by the author
EdDSA algorithms.
NoClientCert indicates that no client certificate should be requested during the handshake, and if any certificates are sent they will not be verified.
Legacy signature and hash algorithms for TLS 1.2.
RSASSA-PKCS1-v1_5 algorithms.
No description provided by the author
No description provided by the author
RSASSA-PSS algorithms with public key OID rsaEncryption.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
QUICHandshakeDone indicates that the TLS handshake has completed.
QUICNoEvent indicates that there are no events available.
QUICRejectedEarlyData indicates that the server rejected 0-RTT data even if we offered it.
QUICSetReadSecret and QUICSetWriteSecret provide the read and write secrets for a given encryption level.
No description provided by the author
QUICTransportParameters provides the peer's QUIC transport parameters.
QUICTransportParametersRequired indicates that the caller must provide QUIC transport parameters to send to the peer.
QUICWriteData provides data to send to the peer in CRYPTO frames.
RenegotiateFreelyAsClient allows a remote server to repeatedly request renegotiation.
RenegotiateNever disables renegotiation.
RenegotiateOnceAsClient allows a remote server to request renegotiation once per connection.
RequestClientCert indicates that a client certificate should be requested during the handshake, but does not require that the client send any certificates.
RequireAndVerifyClientCert indicates that a client certificate should be requested during the handshake, and that at least one valid certificate is required to be sent by the client.
RequireAnyClientCert indicates that a client certificate should be requested during the handshake, and that at least one certificate is required to be sent by the client, but that certificate is not required to be valid.
TLS 1.3 cipher suites.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
Legacy names for the corresponding cipher suites with the correct _SHA256 suffix, retained for backward compatibility.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
TLS_FALLBACK_SCSV isn't a standard cipher suite but an indicator that the client is doing version fallback.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
A list of cipher suite IDs that are, or have been, implemented by this package.
TLS 1.0 - 1.2 cipher suites.
VerifyClientCertIfGiven indicates that a client certificate should be requested during the handshake, but does not require that the client sends a certificate.
Deprecated: SSLv3 is cryptographically broken, and is no longer supported by this package.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Structs

A Certificate is a chain of one or more certificates, leaf first.
CertificateRequestInfo contains information from a server's CertificateRequest message, which is used to demand a certificate and proof of control from a client.
CertificateVerificationError is returned when certificate verification fails during the handshake.
CipherSuite is a TLS cipher suite.
ClientHelloInfo contains information from a ClientHello message in order to guide application logic in the GetCertificate and GetConfigForClient callbacks.
ClientSessionState contains the state needed by a client to resume a previous TLS session.
A Config structure is used to configure a TLS client or server.
A Conn represents a secured connection.
ConnectionState records basic TLS details about the connection.
Dialer dials TLS connections given a configuration and a Dialer for the underlying connection.
No description provided by the author
A QUICConfig configures a [QUICConn].
A QUICConn represents a connection which uses a QUIC implementation as the underlying transport as described in RFC 9001.
A QUICEvent is an event occurring on a QUIC connection.
No description provided by the author
RecordHeaderError is returned when a TLS record header is invalid.
A SessionState is a resumable session.

# Interfaces

ClientSessionCache is a cache of ClientSessionState objects that can be used by a client to resume a TLS session with a given server.
No description provided by the author

# Type aliases

An AlertError is a TLS alert.
ClientAuthType declares the policy the server will follow for TLS Client Authentication.
CurveID is the type of a TLS identifier for an elliptic curve.
QUICEncryptionLevel represents a QUIC encryption level used to transmit handshake messages.
A QUICEventKind is a type of operation on a QUIC connection.
RenegotiationSupport enumerates the different levels of support for TLS renegotiation.
SignatureScheme identifies a signature algorithm supported by TLS.