protocol: add AEAD encryption negotiation to v2 wire control channel (#5304)

Author: fatedier

README.md

@@ -13,6 +13,14 @@ frp is an open source project with its ongoing development made possible entirel
 
 <h3 align="center">Gold Sponsors</h3>
 <!--gold sponsors start-->
+<p align="center">
+  <a href="https://jb.gg/frp" target="_blank">
+    <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_jetbrains.jpg">
+	<br>
+	<b>The complete IDE crafted for professional Go developers</b>
+  </a>
+</p>
+
 <p align="center">
   <a href="https://github.com/beclab/Olares" target="_blank">
     <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_olares.jpeg">
@@ -32,24 +40,6 @@ If you're looking for a meeting recording API, consider checking out [Recall.ai]
 an API that records Zoom, Google Meet, Microsoft Teams, in-person meetings, and more.
 
 </div>
-
-<p align="center">
-  <a href="https://requestly.com/?utm_source=github&utm_medium=partnered&utm_campaign=frp" target="_blank">
-    <img width="480px" src="https://github.com/user-attachments/assets/24670320-997d-4d62-9bca-955c59fe883d">
-    <br>
-    <b>Requestly - Free & Open-Source alternative to Postman</b>
-    <br>
-    <sub>All-in-one platform to Test, Mock and Intercept APIs.</sub>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://jb.gg/frp" target="_blank">
-    <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_jetbrains.jpg">
-	<br>
-	<b>The complete IDE crafted for professional Go developers</b>
-  </a>
-</p>
 <!--gold sponsors end-->
 
 ## What is frp?

README_zh.md

@@ -15,6 +15,14 @@ frp 是一个完全开源的项目，我们的开发工作完全依靠赞助者
 
 <h3 align="center">Gold Sponsors</h3>
 <!--gold sponsors start-->
+<p align="center">
+  <a href="https://jb.gg/frp" target="_blank">
+    <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_jetbrains.jpg">
+	<br>
+	<b>The complete IDE crafted for professional Go developers</b>
+  </a>
+</p>
+
 <p align="center">
   <a href="https://github.com/beclab/Olares" target="_blank">
     <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_olares.jpeg">
@@ -34,24 +42,6 @@ If you're looking for a meeting recording API, consider checking out [Recall.ai]
 an API that records Zoom, Google Meet, Microsoft Teams, in-person meetings, and more.
 
 </div>
-
-<p align="center">
-  <a href="https://requestly.com/?utm_source=github&utm_medium=partnered&utm_campaign=frp" target="_blank">
-    <img width="480px" src="https://github.com/user-attachments/assets/24670320-997d-4d62-9bca-955c59fe883d">
-    <br>
-    <b>Requestly - Free & Open-Source alternative to Postman</b>
-    <br>
-    <sub>All-in-one platform to Test, Mock and Intercept APIs.</sub>
-  </a>
-</p>
-
-<p align="center">
-  <a href="https://jb.gg/frp" target="_blank">
-    <img width="420px" src="https://raw.githubusercontent.com/fatedier/frp/dev/doc/pic/sponsor_jetbrains.jpg">
-	<br>
-	<b>The complete IDE crafted for professional Go developers</b>
-  </a>
-</p>
 <!--gold sponsors end-->
 
 ## 为什么使用 frp ？

Release.md

@@ -10,9 +10,12 @@ This release introduces wire protocol v2 as a transition path for future frpc/fr
 
 **The default value of `transport.wireProtocol` remains `v1` in this release.** Users can keep the default for now. To test v2 early, upgrade both frpc and frps to versions that support it, then set `transport.wireProtocol = "v2"` in frpc. A v2-enabled frpc cannot connect to an older frps.
 
+When `transport.wireProtocol = "v2"` is enabled, the control channel uses negotiated AEAD encryption after the login handshake. Both frpc and frps must be upgraded to this release to use v2.
+
 v1 will be deprecated when v2 becomes the default in a future release. It will continue to be supported until v0.78.0 is released, and may be removed in v0.78.0 or later.
 
 ## Features
 
 * Added `transport.wireProtocol` for frpc to select the internal message protocol used between frpc and frps. Supported values are `v1` and `v2`.
 * Added client protocol visibility in the frps dashboard and `/api/clients` API. Online clients now report their negotiated protocol as `v1` or `v2`.
+* Wire protocol v2 now negotiates AEAD control-channel encryption. Supported algorithms are `xchacha20-poly1305` and `aes-256-gcm`; frpc advertises its preferred order based on local AES-GCM hardware support, and frps selects the first supported algorithm from that list.

client/control_session.go

@@ -74,17 +74,18 @@ func (d *controlSessionDialer) Dial(previousRunID string) (*SessionContext, erro
 		return nil, err
 	}
 
-	loginRespMsg, err := d.exchangeLogin(conn, loginMsg)
+	loginResult, err := d.exchangeLogin(conn, loginMsg)
 	if err != nil {
 		return nil, err
 	}
+	loginRespMsg := loginResult.resp
 	if loginRespMsg.Error != "" {
 		return nil, errors.New(loginRespMsg.Error)
 	}
 
 	var controlRW io.ReadWriter = conn
 	if d.clientSpec == nil || d.clientSpec.Type != "ssh-tunnel" {
-		controlRW, err = netpkg.NewCryptoReadWriter(conn, d.auth.EncryptionKey())
+		controlRW, err = d.newControlReadWriter(conn, loginResult.crypto)
 		if err != nil {
 			return nil, fmt.Errorf("create control crypto read writer: %w", err)
 		}
@@ -125,9 +126,16 @@ func (d *controlSessionDialer) buildLoginMsg(previousRunID string) (*msg.Login,
 	return loginMsg, nil
 }
 
-func (d *controlSessionDialer) exchangeLogin(conn net.Conn, loginMsg *msg.Login) (*msg.LoginResp, error) {
+type loginExchangeResult struct {
+	resp   *msg.LoginResp
+	crypto *wire.CryptoContext
+}
+
+func (d *controlSessionDialer) exchangeLogin(conn net.Conn, loginMsg *msg.Login) (*loginExchangeResult, error) {
 	rw := msg.NewV1ReadWriter(conn)
 	var wireConn *wire.Conn
+	var clientHello wire.ClientHello
+	var clientHelloPayload []byte
 
 	if d.common.Transport.WireProtocol == wire.ProtocolV2 {
 		if err := wire.WriteMagic(conn); err != nil {
@@ -136,14 +144,23 @@ func (d *controlSessionDialer) exchangeLogin(conn net.Conn, loginMsg *msg.Login)
 
 		wireConn = wire.NewConn(conn)
 		rw = msg.NewV2ReadWriterWithConn(wireConn)
-		hello := wire.DefaultClientHello(wire.BootstrapInfo{
+		var err error
+		clientHello, err = wire.NewClientHello(wire.BootstrapInfo{
 			Transport: d.common.Transport.Protocol,
 			TLS:       lo.FromPtr(d.common.Transport.TLS.Enable) || d.common.Transport.Protocol == "wss" || d.common.Transport.Protocol == "quic",
 			TCPMux:    lo.FromPtr(d.common.Transport.TCPMux),
 		})
-		if err := wireConn.WriteJSONFrame(wire.FrameTypeClientHello, hello); err != nil {
+		if err != nil {
+			return nil, err
+		}
+		clientHelloFrame, err := wire.NewJSONFrame(wire.FrameTypeClientHello, clientHello)
+		if err != nil {
 			return nil, err
 		}
+		if err := wireConn.WriteFrame(clientHelloFrame); err != nil {
+			return nil, err
+		}
+		clientHelloPayload = clientHelloFrame.Payload
 	}
 	if err := rw.WriteMsg(loginMsg); err != nil {
 		return nil, err
@@ -154,19 +171,50 @@ func (d *controlSessionDialer) exchangeLogin(conn net.Conn, loginMsg *msg.Login)
 		_ = conn.SetReadDeadline(time.Time{})
 	}()
 
+	var cryptoContext *wire.CryptoContext
 	if wireConn != nil {
+		serverHelloFrame, err := wireConn.ReadFrame()
+		if err != nil {
+			return nil, err
+		}
+		if serverHelloFrame.Type != wire.FrameTypeServerHello {
+			return nil, fmt.Errorf("unexpected frame type %d, want %d", serverHelloFrame.Type, wire.FrameTypeServerHello)
+		}
 		var serverHello wire.ServerHello
-		if err := wireConn.ReadJSONFrame(wire.FrameTypeServerHello, &serverHello); err != nil {
+		if err := wireConn.UnmarshalFrame(serverHelloFrame, &serverHello); err != nil {
 			return nil, err
 		}
 		if serverHello.Error != "" {
 			return nil, errors.New(serverHello.Error)
 		}
+		cryptoContext, err = wire.NewClientCryptoContext(clientHelloPayload, serverHelloFrame.Payload)
+		if err != nil {
+			return nil, err
+		}
 	}
 
 	var loginRespMsg msg.LoginResp
 	if err := rw.ReadMsgInto(&loginRespMsg); err != nil {
 		return nil, err
 	}
-	return &loginRespMsg, nil
+	return &loginExchangeResult{
+		resp:   &loginRespMsg,
+		crypto: cryptoContext,
+	}, nil
+}
+
+func (d *controlSessionDialer) newControlReadWriter(conn net.Conn, cryptoContext *wire.CryptoContext) (io.ReadWriter, error) {
+	if d.common.Transport.WireProtocol == wire.ProtocolV2 {
+		if cryptoContext == nil {
+			return nil, errors.New("missing v2 crypto negotiation")
+		}
+		return netpkg.NewAEADCryptoReadWriter(
+			conn,
+			d.auth.EncryptionKey(),
+			netpkg.AEADCryptoRoleClient,
+			cryptoContext.Algorithm,
+			cryptoContext.TranscriptHash,
+		)
+	}
+	return netpkg.NewCryptoReadWriter(conn, d.auth.EncryptionKey())
 }

client/control_session_test.go

@@ -29,6 +29,7 @@ import (
 	v1 "github.com/fatedier/frp/pkg/config/v1"
 	"github.com/fatedier/frp/pkg/msg"
 	"github.com/fatedier/frp/pkg/proto/wire"
+	netpkg "github.com/fatedier/frp/pkg/util/net"
 )
 
 type testConnector struct {
@@ -140,8 +141,17 @@ func TestControlSessionDialerDialV2(t *testing.T) {
 		}
 
 		wireConn := wire.NewConn(serverRaw)
+		clientHelloFrame, err := wireConn.ReadFrame()
+		if err != nil {
+			serverErrCh <- err
+			return
+		}
+		if clientHelloFrame.Type != wire.FrameTypeClientHello {
+			serverErrCh <- fmt.Errorf("unexpected frame type %d, want %d", clientHelloFrame.Type, wire.FrameTypeClientHello)
+			return
+		}
 		var hello wire.ClientHello
-		if err := wireConn.ReadJSONFrame(wire.FrameTypeClientHello, &hello); err != nil {
+		if err := wireConn.UnmarshalFrame(clientHelloFrame, &hello); err != nil {
 			serverErrCh <- err
 			return
 		}
@@ -160,11 +170,52 @@ func TestControlSessionDialerDialV2(t *testing.T) {
 			serverErrCh <- fmt.Errorf("unexpected user: %s", loginMsg.User)
 			return
 		}
-		if err := wireConn.WriteJSONFrame(wire.FrameTypeServerHello, wire.DefaultServerHello()); err != nil {
+		serverHello, err := wire.NewServerHello(hello)
+		if err != nil {
 			serverErrCh <- err
 			return
 		}
-		serverErrCh <- rw.WriteMsg(&msg.LoginResp{RunID: "run-v2"})
+		serverHelloFrame, err := wire.NewJSONFrame(wire.FrameTypeServerHello, serverHello)
+		if err != nil {
+			serverErrCh <- err
+			return
+		}
+		cryptoContext := wire.NewCryptoContext(
+			serverHello.Selected.Crypto.Algorithm,
+			clientHelloFrame.Payload,
+			serverHelloFrame.Payload,
+		)
+		if err := wireConn.WriteFrame(serverHelloFrame); err != nil {
+			serverErrCh <- err
+			return
+		}
+		if err := rw.WriteMsg(&msg.LoginResp{RunID: "run-v2"}); err != nil {
+			serverErrCh <- err
+			return
+		}
+
+		controlRW, err := netpkg.NewAEADCryptoReadWriter(
+			serverRaw,
+			[]byte("token"),
+			netpkg.AEADCryptoRoleServer,
+			cryptoContext.Algorithm,
+			cryptoContext.TranscriptHash,
+		)
+		if err != nil {
+			serverErrCh <- err
+			return
+		}
+		controlMsgRW := msg.NewReadWriter(controlRW, wire.ProtocolV2)
+		var ping msg.Ping
+		if err := controlMsgRW.ReadMsgInto(&ping); err != nil {
+			serverErrCh <- err
+			return
+		}
+		if ping.PrivilegeKey != "v2-ping" || ping.Timestamp != 12345 {
+			serverErrCh <- fmt.Errorf("unexpected ping: %+v", ping)
+			return
+		}
+		serverErrCh <- nil
 	}()
 
 	dialer := newTestControlSessionDialer(t, wire.ProtocolV2, connector, nil)
@@ -177,6 +228,7 @@ func TestControlSessionDialerDialV2(t *testing.T) {
 	require.NotNil(t, sessionCtx.Conn)
 	require.NotNil(t, sessionCtx.Connector)
 	require.False(t, connector.closed.Load())
+	require.NoError(t, sessionCtx.Conn.WriteMsg(&msg.Ping{PrivilegeKey: "v2-ping", Timestamp: 12345}))
 	require.NoError(t, <-serverErrCh)
 }
 

doc/agents/release.md

@@ -33,7 +33,51 @@ git commit -m "bump version to vX.Y.Z"
 git push origin dev
 ```
 
-## 3. Merge dev → master
+## 3. Pre-release Validation
+
+Run the standard e2e suite locally:
+
+```bash
+make e2e
+```
+
+For releases that touch compatibility-sensitive areas such as login, control
+connections, work connections, visitors, transport, or wire protocol handling,
+also run the manual compatibility e2e suite:
+
+```bash
+make e2e-compatibility
+make e2e-compatibility-floor
+```
+
+`make e2e-compatibility` builds the current `frps` and `frpc`, resolves the
+recent stable release baselines from GitHub, downloads or reuses their binaries,
+and tests current binaries against those historical releases. The default number
+of recent baselines is controlled by `FRP_COMPAT_BASELINE_COUNT` in the
+`Makefile`.
+
+Downloaded release binaries are cached under:
+
+```text
+.cache/e2e-compat/<version>/<os>_<arch>/
+```
+
+For a release validation run that must be exactly reproducible, pass an explicit
+baseline matrix instead of using the floating recent-release list:
+
+```bash
+FRP_COMPAT_BASELINE_VERSIONS="0.X.0 0.Y.0" make e2e-compatibility
+```
+
+Use `make e2e-compatibility-smoke` for a quick single-baseline check while
+iterating locally. If GitHub release metadata requests are rate-limited, set
+`GITHUB_TOKEN` or use `FRP_COMPAT_BASELINE_VERSIONS`.
+
+The compatibility floor is a support-policy decision, not a value that should
+change every release. Update `FRP_COMPAT_FLOOR_VERSION` only when the declared
+compatibility window changes.
+
+## 4. Merge dev → master
 
 Create a PR from `dev` to `master`:
 
@@ -43,7 +87,7 @@ gh pr create --base master --head dev --title "bump version"
 
 Wait for CI to pass, then merge using **merge commit** (not squash).
 
-## 4. Tag the Release
+## 5. Tag the Release
 
 ```bash
 git checkout master
@@ -52,7 +96,7 @@ git tag -a vX.Y.Z -m "bump version"
 git push origin vX.Y.Z
 ```
 
-## 5. Trigger GoReleaser
+## 6. Trigger GoReleaser
 
 Manually trigger the `goreleaser` workflow in GitHub Actions:
 

go.mod

@@ -5,7 +5,7 @@ go 1.25.0
 require (
 	github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5
 	github.com/coreos/go-oidc/v3 v3.14.1
-	github.com/fatedier/golib v0.6.0
+	github.com/fatedier/golib v0.7.0
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/mux v1.8.1
 	github.com/gorilla/websocket v1.5.0
@@ -30,6 +30,7 @@ require (
 	golang.org/x/net v0.52.0
 	golang.org/x/oauth2 v0.28.0
 	golang.org/x/sync v0.20.0
+	golang.org/x/sys v0.42.0
 	golang.org/x/time v0.10.0
 	golang.zx2c4.com/wireguard v0.0.0-20231211153847-12269c276173
 	gopkg.in/ini.v1 v1.67.0
@@ -68,7 +69,6 @@ require (
 	github.com/wlynxg/anet v0.0.5 // indirect
 	go.uber.org/automaxprocs v1.6.0 // indirect
 	golang.org/x/mod v0.33.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 	golang.org/x/tools v0.42.0 // indirect
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect