1xray-core/
2|-- transport/
3| |-- internet/
4| | |-- reality/
5| | | |-- config.go
6| | | |-- config.pb.go
7| | | |-- config.proto
8| | | |-- reality.go

1// Xray-core/transport/internet/reality/reality.go#L106
2func UClient(c net.Conn, config *Config, ctx context.Context, dest net.Destination) (net.Conn, error)

 1// Xray-core/transport/internet/reality/reality.go#L64-L69
 2// Struct fields definition of UConn
 3type UConn struct {
 4	*utls.UConn
 5	ServerName string
 6	AuthKey    []byte
 7	Verified   bool
 8}
 9
10// Xray-core/transport/internet/reality/reality.go#L108-L115
11// uConn is assigned to the UConn instance, utlsConfig is assigned to the utls.Config instance (configuration for utls package)
12uConn := &UConn{}
13utlsConfig := &utls.Config{
14	VerifyPeerCertificate:  uConn.VerifyPeerCertificate,
15	ServerName:             config.ServerName,
16	InsecureSkipVerify:     true,
17	SessionTicketsDisabled: true,
18	KeyLogWriter:           KeyLogWriterFromConfig(config),
19}
20
21// Xray-core/transport/internet/reality/reality.go#L124
22// Initialize utls.UClient and assign it to the first field of uConn
23uConn.UConn = utls.UClient(c, utlsConfig, *fingerprint)

 1// Xray-core/transport/internet/reality/reality.go#L126-L135
 2// Generate the default ClientHello and provide it to uConn
 3// In this step, the client's TLS key pair is also generated
 4uConn.BuildHandshakeState()
 5// Assign the pointer of the generated default ClientHello to hello
 6// (Assigning a pointer to hello means that modifying hello means modifying the original data)
 7hello := uConn.HandshakeState.Hello
 8// Assign a 32-byte empty slice (dynamic array) to SessionId
 9// And fill it to the 40th-71th bytes of ClientHello, occupying the unit position
10hello.SessionId = make([]byte, 32)
11copy(hello.Raw[39:], hello.SessionId)
12// Fill the version number x.y.z of Xray-core into the 1st-3rd bytes of SessionId
13hello.SessionId[0] = core.Version_x
14hello.SessionId[1] = core.Version_y
15hello.SessionId[2] = core.Version_z
16hello.SessionId[3] = 0 // Fill 0 to the 4th byte
17// Fill the current Unix timestamp into the 5th-8th bytes of SessionId
18binary.BigEndian.PutUint32(hello.SessionId[4:], uint32(time.Now().Unix()))
19// Fill shortId from the 9th byte of SessionId
20copy(hello.SessionId[8:], config.ShortId)
21
22// Xray-core/transport/internet/reality/reality.go#L139
23// Convert the REALITY public key to a usable public key object
24publicKey, err := ecdh.X25519().NewPublicKey(config.PublicKey)
25
26// Xray-core/transport/internet/reality/reality.go#L143
27// Use the x25519 private key and REALITY public key in the client TLS key pair generated by BuildHandshakeState() to enter the ECDH algorithm to calculate the shared key.
28// Input the key into HKDF (key derivation function based on HMAC) to calculate preMasterKey.
29uConn.AuthKey, _ = uConn.HandshakeState.State13.EcdheKey.ECDH(publicKey)
30// Xray-core/transport/internet/reality/reality.go#L147-L149
31if _, err := hkdf.New(sha256.New, uConn.AuthKey, hello.Random[:20], []byte("REALITY")).Read(uConn.AuthKey); err != nil {
32			return nil, err
33}
34
35// Xray-core/transport/internet/reality/reality.go#L150-L156
36// Select AEAD algorithm: AES-GCM or Chacha20-Poly1305.
37// AEAD algorithm ensures the security, integrity and anti-replay of ciphertext data,
38// and also provides integrity guarantee for additional data.
39var aead cipher.AEAD
40if aesgcmPreferred(hello.CipherSuites) {
41	block, _ := aes.NewCipher(uConn.AuthKey)
42			aead, _ = cipher.NewGCM(block)
43} else {
44	aead, _ = chacha20poly1305.New(uConn.AuthKey)
45}
46
47// Xray-core/transport/internet/reality/reality.go#L160-L161
48// Encrypt SessionId using AEAD algorithm.
49// Here preMasterKey is used as key and ClientHello is used as additional data.
50// Note: hello.SessionId[:0] refers to reuse of its memory space.
51aead.Seal(hello.SessionId[:0], hello.Random[20:], hello.SessionId[:16], hello.Raw)
52// Copy the final SessionId to bytes 40-72 of ClientHello
53// copy() is used to copy data. Usage: copy(destination, source)
54copy(hello.Raw[39:], hello.SessionId)

1if err := uConn.HandshakeContext(ctx); err != nil {
2	return nil, err
3}

  1// REALITY/blob/main/tls.go#L113
  2// Here is the function definition, where conn is the TCP connection accepted by the server
  3func Server(ctx context.Context, conn net.Conn, config *Config) (*Conn, error)
  4
  5// REALITY/blob/main/tls.go#L119
  6// Open a TCP connection to dest (mask server) in REALITY configuration
  7target, err := config.DialContext(ctx, config.Type, config.Dest)
  8
  9// REALITY/blob/main/tls.go#L139-L156
 10// Initialize the mutex (allows to monopolize a task)
 11mutex := new(sync.Mutex)
 12
 13// Initialize the serverHandshakeStateTLS13 instance
 14// which is defined in handshake_server_tls13.go to store the handshake information
 15hs := serverHandshakeStateTLS13{
 16		c: &Conn{
 17			conn: &MirrorConn{
 18				Mutex:  mutex,
 19				Conn:   conn,
 20				Target: target,
 21			},
 22			config: config,
 23		},
 24		ctx: context.Background(),
 25	}
 26
 27// Indicates whether the client sends irrelevant data before completing the handshake
 28copying := false
 29
 30// Waiting group, so that the main coroutine can wait for the sub-coroutine to finish running
 31// Coroutine: lightweight thread in Go language
 32waitGroup := new(sync.WaitGroup)
 33waitGroup.Add(2) // Add two sub-coroutines
 34
 35// REALITY/blob/main/tls.go#L158-L223
 36// Run the coroutine to distinguish clients
 37go func() {
 38	for {
 39		mutex.Lock() // Lock, monopolize current task
 40		// Read ClientHello, context.Background() generates an empty ctx placeholder
 41		hs.clientHello, err = hs.c.readClientHello(context.Background())
 42		// Determine 1. Whether the client sends data before completing the handshake; 2. Read error;
 43		// 3. The version is less than TLS1.3; 4. The SNI in ClientHello is not in the configuration
 44		// If any condition is met, end the loop (break no longer enters the next loop)
 45		// (Go uses unconditional for to represent an infinite loop)
 46		if copying || err != nil || hs.c.vers != VersionTLS13 || !config.ServerNames[hs.clientHello.serverName] {
 47			break
 48		}
 49		// for loop to get the client x25519 public key
 50		// TLS1.3 ClientHello contains as many public keys and digital certificates as possible
 51		// for different algorithms to avoid
 52		// asking for supported algorithms adds 1 round trip delay in TLS1.2
 53		for i, keyShare := range hs.clientHello.keyShares {
 54			// Determine whether the key type is x25519 and the length is equal to 32 bytes
 55			// This is the length and type of the public key used by the REALITY client
 56			// If any condition is not met, countinue enters the next loop
 57			if keyShare.group != X25519 || len(keyShare.data) != 32 {
 58				continue
 59			}
 60			// Enter the REALITY private key and the client public key into the ECDH algorithm to calculate the shared key.
 61			if hs.c.AuthKey, err = curve25519.X25519(config.PrivateKey, keyShare.data); err != nil {
 62				break
 63			}
 64			// The key is input into HKDF (HMAC-based key derivation function) to calculate preMasterKey.
 65			if _, err = hkdf.New(sha256.New, hs.c.AuthKey, hs.clientHello.random[:20], []byte("REALITY")).Read(hs.c.AuthKey); err != nil {
 66				break
 67			}
 68			// Choose AEAD Algorithm。
 69			var aead cipher.AEAD
 70			if aesgcmPreferred(hs.clientHello.cipherSuites) {
 71				block, _ := aes.NewCipher(hs.c.AuthKey)
 72				aead, _ = cipher.NewGCM(block)
 73			} else {
 74				aead, _ = chacha20poly1305.New(hs.c.AuthKey)
 75			}
 76			if config.Show {
 77				fmt.Printf("REALITY remoteAddr: %v\ths.c.AuthKey[:16]: %v\tAEAD: %T\n", remoteAddr, hs.c.AuthKey[:16], aead) //for debug
 78			}
 79			// Initialize two 32-byte slices
 80			// Used to store ciphertext and plaintext respectively.
 81			ciphertext := make([]byte, 32)
 82			plainText := make([]byte, 32)
 83			copy(ciphertext, hs.clientHello.sessionId)
 84			copy(hs.clientHello.sessionId, plainText)
 85			// Decrypt SessionId using AEAD algorithm.
 86			if _, err = aead.Open(plainText[:0], hs.clientHello.random[20:], ciphertext, hs.clientHello.raw); err != nil {
 87				break
 88			}
 89			// Parse the Xray-core version contained in SessionId,
 90			// Unix timestamp, and ShortId
 91			copy(hs.clientHello.sessionId, ciphertext)
 92			copy(hs.c.ClientVer[:], plainText)
 93			hs.c.ClientTime = time.Unix(int64(binary.BigEndian.Uint32(plainText[4:])), 0)
 94			copy(hs.c.ClientShortId[:], plainText[8:])
 95			if config.Show {
 96				fmt.Printf("REALITY remoteAddr: %v\ths.c.ClientVer: %v\n", remoteAddr, hs.c.ClientVer)
 97				fmt.Printf("REALITY remoteAddr: %v\ths.c.ClientTime: %v\n", remoteAddr, hs.c.ClientTime)
 98				fmt.Printf("REALITY remoteAddr: %v\ths.c.ClientShortId: %v\n", remoteAddr, hs.c.ClientShortId) //for debug
 99			}
100			// Determine whether Xray-core version, time delay, ShortId is allowed
101			if (config.MinClientVer == nil || Value(hs.c.ClientVer[:]...) >= Value(config.MinClientVer...)) &&
102				(config.MaxClientVer == nil || Value(hs.c.ClientVer[:]...) <= Value(config.MaxClientVer...)) &&
103				(config.MaxTimeDiff == 0 || time.Since(hs.c.ClientTime).Abs() <= config.MaxTimeDiff) &&
104				(config.ShortIds[hs.c.ClientShortId]) {
105				hs.c.conn = conn
106			}
107			// Identifies the type of public key used by the client for subsequent use
108			hs.clientHello.keyShares[0].group = CurveID(i)
109			break
110		}
111		if config.Show {
112			fmt.Printf("REALITY remoteAddr: %v\ths.c.conn == conn: %v\n", remoteAddr, hs.c.conn == conn) //for debug
113		}
114		break
115	}
116	// Unlock, cancel monopolization of current task
117	mutex.Unlock()
118	// Determine whether the client sends irrelevant data without completing the handshake
119	if hs.c.conn != conn {
120		if config.Show && hs.clientHello != nil {
121			fmt.Printf("REALITY remoteAddr: %v\tforwarded SNI: %v\n", remoteAddr, hs.clientHello.serverName) //for debug
122		}
123		// Forward the connection to dest in the configuration (i.e. the masquerade server)
124		io.Copy(target, underlying)
125	}
126	// Notify the waiting group that the coroutine has completed running
127	waitGroup.Done()
128}()

  1// REALITY/blob/main/tls.go#L225-L349
  2// Run the coroutine for REALITY server handshake and communication with dest
  3go func() {
  4	// Initialize two slices of size = 8192 long
  5	// s2cSaved is used to store all received data from dest
  6	// buf is the buffer from REALITY server to dest
  7	s2cSaved := make([]byte, 0, size)
  8	buf := make([]byte, size)
  9	handshakeLen := 0
 10f:
 11	for {
 12		// Temporarily give up CPU time slices to optimize program performance
 13		runtime.Gosched()
 14		// Read the received data from dest into buf (buf will be cleared)
 15		n, err := target.Read(buf)
 16		// Determine whether data from dest has been received
 17		if n == 0 {
 18			if err != nil {
 19				conn.Close()
 20				waitGroup.Done()
 21				return
 22			}
 23			continue
 24		}
 25		// Lock, monopolize current task
 26		mutex.Lock()
 27		// Append the data in buf to the existing s2cSaved data
 28		s2cSaved = append(s2cSaved, buf[:n]...)
 29		// Determine whether the client sends irrelevant data without completing the handshake
 30		if hs.c.conn != conn {
 31			// Indicates that the client sends irrelevant data without completing the handshake
 32			copying = true
 33			break
 34		}
 35		// Determine whether the length of s2cSaved is too large
 36		if len(s2cSaved) > size {
 37			break
 38		}
 39		// Traverse type to determine the type of the packet returned by dest
 40		// REALITY/blob/main/tls.go#L91-L99
 41		// types = [7]string{
 42		// "Server Hello",
 43		// "Change Cipher Spec",
 44		// "Encrypted Extensions",
 45		// "Certificate",
 46		// "Certificate Verify",
 47		// "Finished",
 48		// "New Session Ticket",
 49		// }
 50		for i, t := range types {
 51			// Determine whether ServerHello has been sent
 52			// Enter the next loop if it matches
 53			if hs.c.out.handshakeLen[i] != 0 {
 54				continue
 55			}
 56			// Determine whether the type of this loop is
 57			// "New Session Ticket" and the length of s2cSaved is 0
 58			if i == 6 && len(s2cSaved) == 0 {
 59				break
 60			}
 61			// handshakeLen records the length of the handshake packet from dest.
 62			// Here, it is judged that its length is 0 and the length of the handshake packet from dest is greater than 5.
 63			// REALITY/blob/main/common.go#L63
 64			// recordHeaderLen = 5
 65			if handshakeLen == 0 && len(s2cSaved) > recordHeaderLen {
 66				// [1:3] points to the version information of the 2nd-3rd bytes of the TLS handshake packet
 67				// For compatibility reasons, the 2nd-3rd bytes of the ClientHello of TLS1.3, 
 68				// have the same value as TLS1.2, and the version mark of 1.3 exists in the extension
 69				// Here we determine whether the data packet from dest is ServerHello
 70				// or ChangeCipherSpec or ApplicationData,
 71				// These three types of data packets should appear in the handshake
 72				if Value(s2cSaved[1:3]...) != VersionTLS12 ||
 73					(i == 0 && (recordType(s2cSaved[0]) != recordTypeHandshake || s2cSaved[5] != typeServerHello)) ||
 74					(i == 1 && (recordType(s2cSaved[0]) != recordTypeChangeCipherSpec || s2cSaved[5] != 1)) ||
 75					(i > 1 && recordType(s2cSaved[0]) != recordTypeApplicationData) {
 76					break f
 77				}
 78				// [3:5] points to the handshake packet length information of the 4th and 5th bytes of the TLS handshake packet
 79				handshakeLen = recordHeaderLen + Value(s2cSaved[3:5]...)
 80			}
 81			if config.Show {
 82				fmt.Printf("REALITY remoteAddr: %v\tlen(s2cSaved): %v\t%v: %v\n", remoteAddr, len(s2cSaved), t, handshakeLen) //for debug
 83			}
 84			// Determine whether the handshake packet is too long
 85			if handshakeLen > size {
 86				break f
 87			}
 88			// Determine whether the handshake packet type is Change Cipher Spec
 89			if i == 1 && handshakeLen > 0 && handshakeLen != 6 {
 90				break f
 91			}
 92			// Determine whether the handshake packet type is Encrypted Extensions,
 93			// which is the encrypted part attached after the Change Cipher Spec.
 94			if i == 2 && handshakeLen > 512 {
 95				hs.c.out.handshakeLen[i] = handshakeLen
 96				hs.c.out.handshakeBuf = buf[:0]
 97				break
 98			}
 99			// Determine whether the handshake packet type is New Session Ticket
100			if i == 6 && handshakeLen > 0 {
101				hs.c.out.handshakeLen[i] = handshakeLen
102				break
103			}
104			// Determine whether the length of the handshake packet is 0 or greater than the s2cSaved length
105			if handshakeLen == 0 || len(s2cSaved) < handshakeLen {
106				// Unlock, cancel monopolization of current task
107				mutex.Unlock()
108				continue f
109			}
110			// Determine whether the handshake packet type is Server Hello
111			if i == 0 {
112				// Construct a new Server Hello
113				hs.hello = new(serverHelloMsg)
114				// unmarshal is used to parse the ServerHello from dest and fill it into the newly constructed handshake packet
115				// Here we check whether unmarshal reports an error and whether the handshake packet after parsing and filling is legal
116				if !hs.hello.unmarshal(s2cSaved[recordHeaderLen:handshakeLen]) ||
117					hs.hello.vers != VersionTLS12 || hs.hello.supportedVersion != VersionTLS13 ||
118					cipherSuiteTLS13ByID(hs.hello.cipherSuite) == nil ||
119					hs.hello.serverShare.group != X25519 || len(hs.hello.serverShare.data) != 32 {
120					break f
121				}
122			}
123			// Modify the sent length of the corresponding type of handshake packet
124			// then reset s2cSaved and handshakeLen
125			hs.c.out.handshakeLen[i] = handshakeLen
126			s2cSaved = s2cSaved[handshakeLen:]
127			handshakeLen = 0
128		} // End of traversal
129		// Mark the start time of the run
130		start := time.Now()
131		// Handshake with REALITY client
132		// That means sending modified Server Hello,
133		// Change Cipher Spec and Encrypted Extensions
134		err = hs.handshake()
135		if config.Show {
136			fmt.Printf("REALITY remoteAddr: %v\ths.handshake() err: %v\n", remoteAddr, err) //for debug
137		}
138		if err != nil {
139			break
140		}
141		// Run the coroutine to handle the connection with dest. At this time, the REALITY handshake has already ended.
142		// The connection to dest is no longer needed.
143		// The purpose of using coroutines is to avoid blocking communication with the client.
144		go func() {
145			if handshakeLen-len(s2cSaved) > 0 {
146				io.ReadFull(target, buf[:handshakeLen-len(s2cSaved)])
147			}
148			if n, err := target.Read(buf); !hs.c.isHandshakeComplete.Load() {
149				if err != nil {
150					conn.Close()
151				}
152				if config.Show {
153					fmt.Printf("REALITY remoteAddr: %v\ttime.Since(start): %v\tn: %v\terr: %v\n", remoteAddr, time.Since(start), n, err)
154				}
155			}
156		}()
157		// Wait for the client to return TLS Finished information
158		err = hs.readClientFinished()
159		if config.Show {
160			fmt.Printf("REALITY remoteAddr: %v\ths.readClientFinished() err: %v\n", remoteAddr, err)
161		}
162		if err != nil {
163			break
164		}
165		hs.c.isHandshakeComplete.Store(true)
166		break
167	}
168	// Unlock, cancel monopolization of current task
169	mutex.Unlock()
170	// Check if the REALITY server did not send a ServerHello.
171	// This is usually triggered when dest returns an invalid ServerHello
172	// or before dest returns ServerHello.
173	if hs.c.out.handshakeLen[0] == 0 {
174		// Determine whether dest does not process ClientHello correctly
175		if hs.c.conn == conn {
176			waitGroup.Add(1)
177			go func() {
178				// Forward all traffic to dest directly
179				io.Copy(target, underlying)
180				waitGroup.Done()
181			}()
182		}
183		// Write client connection content to s2cSaved
184		conn.Write(s2cSaved)
185		// Forward all traffic to dest directly
186		io.Copy(underlying, target)
187		// When io.Copy() returns, it means that dest has closed the connection. 
188		// The forwarding channel to the client should also be closed at this time
189		underlying.CloseWrite()
190	}
191	// Notify the waiting group that the coroutine has completed running
192	waitGroup.Done()
193}()

 1// REALITY/blob/main/handshake_server_tls13.go#L55-L59
 2// func init is executed when the package it is in is imported
 3func init() {
 4    // Defines the x509 certificate template
 5	certificate := x509.Certificate{SerialNumber: &big.Int{}}
 6    // Generate a 64-byte ed25519 private key
 7	// _ means ignore and discard the value
 8	_, ed25519Priv, _ = ed25519.GenerateKey(rand.Reader)
 9    // Generate a temporary x509 certificate using the previous template
10	// I don't know why the REALITY server intercepted
11	// Bytes 33-64 of the private key ed25519Priv
12	// Public key for the temporary certificate
13	signedCert, _ = x509.CreateCertificate(rand.Reader, &certificate, &certificate, ed25519.PublicKey(ed25519Priv[32:]), ed25519Priv)
14}
15
16// REALITY/blob/main/handshake_server_tls13.go#L74-L85
17// (Again) calculate preMasterKey
18// The key value calculated this time
19// is assigned to hs.sharedKey
20{
21	hs.suite = cipherSuiteTLS13ByID(hs.hello.cipherSuite)
22	c.cipherSuite = hs.suite.id
23	hs.transcript = hs.suite.hash.New()
24	
25	key, _ := generateECDHEKey(c.config.rand(), X25519)
26	copy(hs.hello.serverShare.data, key.PublicKey().Bytes())
27	peerKey, _ := key.Curve().NewPublicKey(hs.clientHello.keyShares[hs.clientHello.keyShares[0].group].data)
28	hs.sharedKey, _ = key.ECDH(peerKey)
29
30	c.serverName = hs.clientHello.serverName
31}
32
33// REALITY/blob/main/handshake_server_tls13.go#L94-L106
34// Modify the value of the temporary certificate signature
35{
36	// Store the temporary certificate in the certificate array
37	signedCert := append([]byte{}, signedCert...)
38
39	// Initialize the hmac calculation object h
40	// Use preMasterKey as the key
41	h := hmac.New(sha512.New, c.AuthKey)
42	// Write bytes 33-64 of the ed25519 private key to the buffer h
43	h.Write(ed25519Priv[32:])
44	// Calculate the hmac value of the buffer data and write it
45	// starting from byte 65 of the temporary certificate
46	h.Sum(signedCert[:len(signedCert)-64])
47
48	// Constructs a complete certificate object
49	hs.cert = &Certificate{
50		Certificate: [][]byte{signedCert},
51		PrivateKey:  ed25519Priv,
52	}
53	// Identifies the signature algorithm as ed25519
54	hs.sigAlg = Ed25519
55}

 1// Block until all coroutines in the waiting group have completed running
 2waitGroup.Wait()
 3// Close the connection with dest
 4target.Close()
 5if config.Show {
 6	fmt.Printf("REALITY remoteAddr: %v\ths.c.handshakeStatus: %v\n", remoteAddr, hs.c.isHandshakeComplete.Load()) //for debug
 7}
 8// Determine whether the handshake with the REALITY client has ended
 9if hs.c.isHandshakeComplete.Load() {
10	// Return the connection to the caller
11	return hs.c, nil
12}
13// If the handshake with the REALITY client has not ended normally,
14// close the connection with the client
15conn.Close()
16// Return the error to the caller
17return nil, errors.New("REALITY: processed invalid connection")

 1// Xray-core/transport/internet/reality/reality.go#L82-L104
 2func (c *UConn) VerifyPeerCertificate(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error {
 3	// Since the utls package does not provide low-level access and modification to certificates
 4	// Here, the reflect package in Go is used to obtain the memory address of the certificate array
 5	// And the original data is converted to a Go array by operating pointers and type assertions
 6	p, _ := reflect.TypeOf(c.Conn).Elem().FieldByName("peerCertificates")
 7	certs := *(*([]*x509.Certificate))(unsafe.Pointer(uintptr(unsafe.Pointer(c.Conn)) + p.Offset))
 8	// Convert the public key in the first certificate in the certificate array to
 9	// ed25519.PublicKey type
10	// Confirm the public key type by checking whether an error is reported
11	if pub, ok := certs[0].PublicKey.(ed25519.PublicKey); ok {
12		// Initialize hmac calculation object h
13		// Use preMasterKey as key
14		h := hmac.New(sha512.New, c.AuthKey)
15		// Write the certificate public key to h's buffer
16		h.Write(pub)
17		// h.Sum calculates and returns the hmac value of the buffer data
18		// Determine whether the hmac value is
19		// completely consistent with the certificate signature
20		if bytes.Equal(h.Sum(nil), certs[0].Signature) {
21			// Indicates that the REALITY server authentication has passed
22			c.Verified = true
23			return nil
24		}
25	}
26	... // The original verification logic of the crypto/tls package is omitted here
27}