Skip to content

PasteFerry (隔空贴): clipboard and file sync across macOS, Windows and Linux. Direct-first, end-to-end encrypted. Optional official access: no server to host. Independent self-hosting remains available.

refactor(core): share signing and verification of signaling messages

baiyuze083d705e357e
diff --git a/client-core/internal/transport/signaling/client.go b/client-core/internal/transport/signaling/client.go
index 4f75404..394c656 100644
--- a/client-core/internal/transport/signaling/client.go
+++ b/client-core/internal/transport/signaling/client.go
@@ -3,13 +3,14 @@
//
// 信任模型:服务器只是个转发通道。所有经它转发的消息都由发送方用设备私钥签名,
// 接收方用配对时存下的对端公钥验签——服务器改不了内容,也冒充不了任何一方。
-// 验签失败的消息直接丢弃。
+// 验签失败的消息直接丢弃。签名与校验见 transport/signed。
+//
+// 服务器是可选的:地址为空时客户端什么也不做,设备只在局域网里互相发现。
package signaling
import (
"context"
"crypto/ed25519"
- cryptorand "crypto/rand"
"errors"
"fmt"
"log/slog"
@@ -21,6 +22,7 @@ import (
"google.golang.org/protobuf/proto"
"github.com/baiyuze/copysync/client-core/internal/identity"
+ "github.com/baiyuze/copysync/client-core/internal/transport/signed"
pb "github.com/baiyuze/copysync/proto/gen/copysync/v1"
)
@@ -28,8 +30,6 @@ const (
maxMessageBytes = 256 << 10
dialTimeout = 15 * time.Second
writeTimeout = 10 * time.Second
- // 防重放:拒绝时间戳偏离过大的消息
- maxClockSkew = 5 * time.Minute
)
// Handlers 是调用方关心的事件。均在客户端的读循环中同步调用,
@@ -52,9 +52,7 @@ type Client struct {
log *slog.Logger
handlers Handlers
- // PublicKeyOf 返回已配对设备的公钥,用于验签。返回 nil 表示未配对,
- // 此时来自该设备的消息一律丢弃。
- publicKeyOf func(deviceID string) ed25519.PublicKey
+ verifier *signed.Verifier
// DeviceInfo 提供每次握手时上报的设备名与已配对列表
deviceInfo func() (name, platform string, pairedIDs []string)
@@ -62,16 +60,20 @@ type Client struct {
conn *websocket.Conn
url string
connected bool
-
- // 防重放:记录近期见过的 nonce
- seenNonces map[string]time.Time
+ // urlChanged 在地址变化时唤醒正在等待的 Run,立即按新地址连接
+ urlChanged chan struct{}
}
type Options struct {
- Identity *identity.Identity
- URL string
- Logger *slog.Logger
- Handlers Handlers
+ Identity *identity.Identity
+ URL string
+ Logger *slog.Logger
+ Handlers Handlers
+ // Verifier 校验转发来的信令。与局域网通道共用一个,同一条信令两条路都到时只处理一次。
+ // 为空时按 PublicKeyOf 自建一个。
+ Verifier *signed.Verifier
+ // PublicKeyOf 返回已配对设备的公钥,用于验签。返回 nil 表示未配对,
+ // 此时来自该设备的消息一律丢弃。
PublicKeyOf func(deviceID string) ed25519.PublicKey
DeviceInfo func() (name, platform string, pairedIDs []string)
}
@@ -81,19 +83,23 @@ func New(opts Options) *Client {
if log == nil {
log = slog.Default()
}
+ verifier := opts.Verifier
+ if verifier == nil {
+ verifier = signed.NewVerifier(opts.Identity.DeviceID, opts.PublicKeyOf)
+ }
return &Client{
- identity: opts.Identity,
- url: opts.URL,
- log: log,
- handlers: opts.Handlers,
- publicKeyOf: opts.PublicKeyOf,
- deviceInfo: opts.DeviceInfo,
- seenNonces: make(map[string]time.Time),
+ identity: opts.Identity,
+ url: opts.URL,
+ log: log,
+ handlers: opts.Handlers,
+ verifier: verifier,
+ deviceInfo: opts.DeviceInfo,
+ urlChanged: make(chan struct{}, 1),
}
}
-// SetURL 更换信令服务器地址,下次重连生效。
-// 当前连接会被断开,以便立即切换。
+// SetURL 更换信令服务器地址,立即生效。
+// 当前连接会被断开,以便立即切换;地址为空表示不用服务器。
func (c *Client) SetURL(url string) {
c.mu.Lock()
changed := c.url != url
@@ -101,9 +107,16 @@ func (c *Client) SetURL(url string) {
conn := c.conn
c.mu.Unlock()
- if changed && conn != nil {
+ if !changed {
+ return
+ }
+ if conn != nil {
conn.Close(websocket.StatusNormalClosure, "切换服务器")
}
+ select {
+ case c.urlChanged <- struct{}{}:
+ default:
+ }
}
func (c *Client) URL() string {
@@ -119,24 +132,43 @@ func (c *Client) Connected() bool {
}
// Run 维持与信令服务器的连接,断线后自动重连,直到 ctx 取消。
+// 没配地址时空等,直到 SetURL 给出地址。
func (c *Client) Run(ctx context.Context) {
- backoff := time.Second
+ const initialBackoff = time.Second
const maxBackoff = 30 * time.Second
+ backoff := initialBackoff
for ctx.Err() == nil {
- err := c.session(ctx)
+ if c.URL() == "" {
+ select {
+ case <-ctx.Done():
+ return
+ case <-c.urlChanged:
+ backoff = initialBackoff
+ continue
+ }
+ }
+
+ established, err := c.session(ctx)
if ctx.Err() != nil {
return
}
if err != nil {
c.log.Debug("信令连接中断", "err", err, "重试间隔", backoff)
}
+ // 连上过就从头计时:服务器重启后应当很快重连,而不是沿用上次的长间隔
+ if established {
+ backoff = initialBackoff
+ }
// 加抖动,避免服务器重启后所有设备同时涌入
jitter := time.Duration(rand.Int63n(int64(backoff / 2)))
select {
case <-ctx.Done():
return
+ case <-c.urlChanged:
+ backoff = initialBackoff
+ continue
case <-time.After(backoff + jitter):
}
if backoff < maxBackoff {
@@ -145,24 +177,24 @@ func (c *Client) Run(ctx context.Context) {
}
}
-// session 完成一次完整的连接生命周期。
-func (c *Client) session(ctx context.Context) error {
+// session 完成一次完整的连接生命周期。established 表示握手成功过。
+func (c *Client) session(ctx context.Context) (established bool, err error) {
url := c.URL()
if url == "" {
- return errors.New("未配置信令服务器地址")
+ return false, errors.New("未配置信令服务器地址")
}
dialCtx, cancel := context.WithTimeout(ctx, dialTimeout)
conn, _, err := websocket.Dial(dialCtx, url, nil)
cancel()
if err != nil {
- return fmt.Errorf("连接 %s: %w", url, err)
+ return false, fmt.Errorf("连接 %s: %w", url, err)
}
conn.SetReadLimit(maxMessageBytes)
defer conn.Close(websocket.StatusNormalClosure, "")
if err := c.handshake(ctx, conn); err != nil {
- return fmt.Errorf("握手: %w", err)
+ return false, fmt.Errorf("握手: %w", err)
}
c.mu.Lock()
@@ -184,7 +216,8 @@ func (c *Client) session(ctx context.Context) error {
}
}()
- return c.readLoop(ctx, conn)
+ err = c.readLoop(ctx, conn)
+ return true, err
}
// handshake 应答服务器的 challenge,证明本机持有该公钥对应的私钥。
@@ -266,62 +299,21 @@ func (c *Client) readLoop(ctx context.Context, conn *websocket.Conn) error {
//
// 这是整个信任模型的落点:服务器能转发任意字节,但伪造不出对端的签名。
// 任何验签不过的消息都当作攻击丢弃,不向上层暴露。
-func (c *Client) handleForwarded(signed *pb.Signed) {
- from := signed.GetFromDeviceId()
- pub := c.publicKeyOf(from)
- if pub == nil {
- c.log.Warn("丢弃未配对设备的消息", "from", from)
- return
- }
- if !ed25519.Verify(pub, signed.GetPayload(), signed.GetSignature()) {
- c.log.Warn("丢弃签名无效的消息", "from", from)
- return
- }
-
- var msg pb.SignalMessage
- if err := proto.Unmarshal(signed.GetPayload(), &msg); err != nil {
- c.log.Warn("丢弃无法解析的消息", "from", from, "err", err)
- return
- }
-
- // 防重放:时间戳超出容忍范围,或 nonce 重复出现过
- ts := time.Unix(msg.GetTimestampUnix(), 0)
- if skew := time.Since(ts); skew > maxClockSkew || skew < -maxClockSkew {
- c.log.Warn("丢弃时间戳异常的消息", "from", from, "偏差", skew)
+func (c *Client) handleForwarded(s *pb.Signed) {
+ from, msg, err := c.verifier.Verify(s)
+ switch {
+ case errors.Is(err, signed.ErrReplay):
+ // 局域网那条路往往先到,这份是重复的,正常现象
+ c.log.Debug("丢弃重复的消息", "from", from)
return
- }
- if c.seenNonce(msg.GetNonce()) {
- c.log.Warn("丢弃重放的消息", "from", from)
+ case err != nil:
+ c.log.Warn("丢弃转发来的消息", "from", from, "原因", err)
return
}
if c.handlers.OnSignal != nil {
- c.handlers.OnSignal(from, &msg)
- }
-}
-
-// seenNonce 记录并判断 nonce 是否重复,同时清理过期条目。
-func (c *Client) seenNonce(nonce []byte) bool {
- if len(nonce) == 0 {
- return false
- }
- key := string(nonce)
-
- c.mu.Lock()
- defer c.mu.Unlock()
-
- now := time.Now()
- if _, dup := c.seenNonces[key]; dup {
- return true
- }
- // 超出时钟容忍窗口的 nonce 不可能再被接受,可以安全丢弃
- for k, t := range c.seenNonces {
- if now.Sub(t) > maxClockSkew*2 {
- delete(c.seenNonces, k)
- }
+ c.handlers.OnSignal(from, msg)
}
- c.seenNonces[key] = now
- return false
}
// ─────────────────────────── 发送 ───────────────────────────
@@ -341,28 +333,19 @@ func (c *Client) send(ctx context.Context, env *pb.ClientEnvelope) error {
return writeProto(ctx, conn, env)
}
-// Signal 向对端发送一条已签名的信令。
+// Signal 签名后经服务器发给对端。
func (c *Client) Signal(ctx context.Context, to string, msg *pb.SignalMessage) error {
- msg.ToDeviceId = to
- msg.TimestampUnix = time.Now().Unix()
- if msg.Nonce == nil {
- nonce := make([]byte, 16)
- if _, err := cryptorand.Read(nonce); err != nil {
- return err
- }
- msg.Nonce = nonce
- }
-
- payload, err := proto.Marshal(msg)
+ s, err := signed.Sign(c.identity, to, msg)
if err != nil {
return err
}
+ return c.SendSigned(ctx, s)
+}
+
+// SendSigned 请服务器转发一条已签名的信令。
+func (c *Client) SendSigned(ctx context.Context, s *pb.Signed) error {
return c.send(ctx, &pb.ClientEnvelope{
- Payload: &pb.ClientEnvelope_Forward{Forward: &pb.Signed{
- Payload: payload,
- Signature: c.identity.Sign(payload),
- FromDeviceId: c.identity.DeviceID,
- }},
+ Payload: &pb.ClientEnvelope_Forward{Forward: s},
})
}
diff --git a/client-core/internal/transport/signed/signed.go b/client-core/internal/transport/signed/signed.go
new file mode 100644
index 0000000..8db745a
--- /dev/null
+++ b/client-core/internal/transport/signed/signed.go
@@ -0,0 +1,132 @@
+// Package signed 负责信令的签名与校验,供服务器和局域网两条通道共用。
+//
+// 信任模型与通道无关:无论信令经服务器转发还是在局域网里直接收发,
+// 发送方都用设备私钥签名,接收方用配对时存下的公钥验签。转发的一方——
+// 服务器,或同一网络里的任何人——改不了内容,也冒充不了任何一方。
+//
+// 两条通道共用同一个 Verifier,也就共用同一份 nonce 记录:同一条信令
+// 从两条路都到达时,只有先到的那份会被交给上层。
+package signed
+
+import (
+ "crypto/ed25519"
+ cryptorand "crypto/rand"
+ "errors"
+ "sync"
+ "time"
+
+ "google.golang.org/protobuf/proto"
+
+ "github.com/baiyuze/copysync/client-core/internal/identity"
+ pb "github.com/baiyuze/copysync/proto/gen/copysync/v1"
+)
+
+// MaxClockSkew 是防重放的时间窗:时间戳偏离超过它的消息一律拒收。
+const MaxClockSkew = 5 * time.Minute
+
+var (
+ ErrUnknownSender = errors.New("发送方未配对")
+ ErrBadSignature = errors.New("签名无效")
+ ErrMalformed = errors.New("消息无法解析")
+ ErrStale = errors.New("时间戳超出容忍范围")
+ ErrReplay = errors.New("重复的消息")
+ ErrWrongRecipient = errors.New("消息不是发给本机的")
+)
+
+// Sign 给消息填上收件人、时间戳与 nonce,签名后返回可直接发送的 Signed。
+// 会改写 msg。
+func Sign(id *identity.Identity, to string, msg *pb.SignalMessage) (*pb.Signed, error) {
+ msg.ToDeviceId = to
+ msg.TimestampUnix = time.Now().Unix()
+ if msg.Nonce == nil {
+ nonce := make([]byte, 16)
+ if _, err := cryptorand.Read(nonce); err != nil {
+ return nil, err
+ }
+ msg.Nonce = nonce
+ }
+ payload, err := proto.Marshal(msg)
+ if err != nil {
+ return nil, err
+ }
+ return &pb.Signed{
+ Payload: payload,
+ Signature: id.Sign(payload),
+ FromDeviceId: id.DeviceID,
+ }, nil
+}
+
+// Verifier 校验收到的 Signed。
+type Verifier struct {
+ selfID string
+ // publicKeyOf 返回已配对(或正在配对)设备的公钥;nil 表示不认识
+ publicKeyOf func(deviceID string) ed25519.PublicKey
+ now func() time.Time
+
+ mu sync.Mutex
+ seen map[string]time.Time
+}
+
+func NewVerifier(selfID string, publicKeyOf func(deviceID string) ed25519.PublicKey) *Verifier {
+ return &Verifier{
+ selfID: selfID,
+ publicKeyOf: publicKeyOf,
+ now: time.Now,
+ seen: make(map[string]time.Time),
+ }
+}
+
+// Verify 验签并防重放。通过时返回发送方与消息。
+//
+// 签名不覆盖 from_device_id(服务器会改写它),所以必须按 from 去查公钥:
+// 冒用别人的 from 只会让验签失败。
+func (v *Verifier) Verify(s *pb.Signed) (string, *pb.SignalMessage, error) {
+ from := s.GetFromDeviceId()
+ pub := v.publicKeyOf(from)
+ if pub == nil {
+ return from, nil, ErrUnknownSender
+ }
+ if !identity.Verify(pub, s.GetPayload(), s.GetSignature()) {
+ return from, nil, ErrBadSignature
+ }
+
+ var msg pb.SignalMessage
+ if err := proto.Unmarshal(s.GetPayload(), &msg); err != nil {
+ return from, nil, ErrMalformed
+ }
+ if msg.GetToDeviceId() != v.selfID {
+ return from, nil, ErrWrongRecipient
+ }
+ ts := time.Unix(msg.GetTimestampUnix(), 0)
+ if skew := v.now().Sub(ts); skew > MaxClockSkew || skew < -MaxClockSkew {
+ return from, nil, ErrStale
+ }
+ if v.seenNonce(msg.GetNonce()) {
+ return from, nil, ErrReplay
+ }
+ return from, &msg, nil
+}
+
+// seenNonce 记录并判断 nonce 是否重复,同时清理过期条目。
+func (v *Verifier) seenNonce(nonce []byte) bool {
+ if len(nonce) == 0 {
+ return false
+ }
+ key := string(nonce)
+
+ v.mu.Lock()
+ defer v.mu.Unlock()
+
+ now := v.now()
+ if _, dup := v.seen[key]; dup {
+ return true
+ }
+ // 超出时钟容忍窗口的 nonce 不可能再被接受,可以安全丢弃
+ for k, t := range v.seen {
+ if now.Sub(t) > MaxClockSkew*2 {
+ delete(v.seen, k)
+ }
+ }
+ v.seen[key] = now
+ return false
+}
diff --git a/client-core/internal/transport/signed/signed_test.go b/client-core/internal/transport/signed/signed_test.go
new file mode 100644
index 0000000..c06f572
--- /dev/null
+++ b/client-core/internal/transport/signed/signed_test.go
@@ -0,0 +1,103 @@
+package signed
+
+import (
+ "crypto/ed25519"
+ "errors"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "google.golang.org/protobuf/proto"
+
+ "github.com/baiyuze/copysync/client-core/internal/identity"
+ pb "github.com/baiyuze/copysync/proto/gen/copysync/v1"
+)
+
+func newIdentity(t *testing.T) *identity.Identity {
+ t.Helper()
+ id, err := identity.LoadOrCreate(filepath.Join(t.TempDir(), "identity.json"))
+ if err != nil {
+ t.Fatal(err)
+ }
+ return id
+}
+
+func keysOf(ids ...*identity.Identity) func(string) ed25519.PublicKey {
+ return func(deviceID string) ed25519.PublicKey {
+ for _, id := range ids {
+ if id.DeviceID == deviceID {
+ return id.PublicKey
+ }
+ }
+ return nil
+ }
+}
+
+func ping() *pb.SignalMessage {
+ return &pb.SignalMessage{Payload: &pb.SignalMessage_Ping{Ping: &pb.Ping{SentAtUnix: 1}}}
+}
+
+func TestSignAndVerify(t *testing.T) {
+ alice, bob := newIdentity(t), newIdentity(t)
+ v := NewVerifier(bob.DeviceID, keysOf(alice))
+
+ s, err := Sign(alice, bob.DeviceID, ping())
+ if err != nil {
+ t.Fatal(err)
+ }
+ from, msg, err := v.Verify(s)
+ if err != nil {
+ t.Fatalf("验签失败: %v", err)
+ }
+ if from != alice.DeviceID || msg.GetPing() == nil {
+ t.Fatalf("from=%s msg=%v", from, msg)
+ }
+}
+
+// 同一条信令从服务器和局域网两条路都到达时,只交给上层一次。
+func TestReplayAcrossChannelsIsDropped(t *testing.T) {
+ alice, bob := newIdentity(t), newIdentity(t)
+ v := NewVerifier(bob.DeviceID, keysOf(alice))
+
+ s, _ := Sign(alice, bob.DeviceID, ping())
+ copied := proto.Clone(s).(*pb.Signed)
+ if _, _, err := v.Verify(s); err != nil {
+ t.Fatal(err)
+ }
+ if _, _, err := v.Verify(copied); !errors.Is(err, ErrReplay) {
+ t.Fatalf("第二份应当被当作重复消息,得到 %v", err)
+ }
+}
+
+// 局域网里谁都能把截到的消息转发给第三台设备:收件人不是本机的一律拒收。
+func TestWrongRecipientIsRejected(t *testing.T) {
+ alice, bob, carol := newIdentity(t), newIdentity(t), newIdentity(t)
+ carolVerifier := NewVerifier(carol.DeviceID, keysOf(alice))
+
+ s, _ := Sign(alice, bob.DeviceID, ping())
+ if _, _, err := carolVerifier.Verify(s); !errors.Is(err, ErrWrongRecipient) {
+ t.Fatalf("发给 bob 的消息不该被 carol 接受,得到 %v", err)
+ }
+}
+
+func TestRejectsUnknownForgedAndStale(t *testing.T) {
+ alice, bob, mallory := newIdentity(t), newIdentity(t), newIdentity(t)
+ v := NewVerifier(bob.DeviceID, keysOf(alice))
+
+ s, _ := Sign(mallory, bob.DeviceID, ping())
+ if _, _, err := v.Verify(s); !errors.Is(err, ErrUnknownSender) {
+ t.Errorf("未配对设备: %v", err)
+ }
+
+ // mallory 冒用 alice 的 ID:签名对不上 alice 的公钥
+ s.FromDeviceId = alice.DeviceID
+ if _, _, err := v.Verify(s); !errors.Is(err, ErrBadSignature) {
+ t.Errorf("冒用 ID: %v", err)
+ }
+
+ old, _ := Sign(alice, bob.DeviceID, ping())
+ v.now = func() time.Time { return time.Now().Add(MaxClockSkew + time.Minute) }
+ if _, _, err := v.Verify(old); !errors.Is(err, ErrStale) {
+ t.Errorf("过期消息: %v", err)
+ }
+}