wss

Documentation

Overview

客户端连接，用于 Face 或 Hand 连接到 Mind。

Package wss 提供应用层加密 WebSocket 通信，用于 Face-Mind-Hand 消息交换。

加密在应用层完成（AES-128-GCM），不依赖 TLS 证书。 重放防护由 protocol.Envelope 的 session/seq 提供；部署层可按需通过反向代理提供 TLS。

服务端连接管理，用于 Mind 接受 Face 和 Hand 的 WebSocket 连接。

Index

• Constants
• func ComputeSharedSecret(private *ecdh.PrivateKey, peerShare string) ([]byte, error)
• func DecryptEnvelopePayload[T any](c *AES128GCM, env *protocol.Envelope) (T, error)
• func GenerateKey() ([]byte, error)
• func NewEphemeralShare() (*ecdh.PrivateKey, string, error)
• func NewRegisterProof(keys SessionKeys, transcript protocol.HandshakeTranscript, ...) (protocol.RegisterProof, error)
• func ReadPayload[T any](c *SessionConn) (protocol.Envelope, T, error)
• func VerifyRegisterProof(keys SessionKeys, transcript protocol.HandshakeTranscript, ...) (protocol.RegisterProofClaims, error)
• type AES128GCM
  • func NewAES128GCM(key []byte) (*AES128GCM, error)
  • func (c *AES128GCM) Decrypt(data, aad []byte) ([]byte, error)
  • func (c *AES128GCM) Encrypt(plain, aad []byte) ([]byte, error)
  • func (c *AES128GCM) EncryptEnvelopePayload(env *protocol.Envelope, payload any) error
• type Client
  • func NewClient(serverURL string) *Client
  • func (c *Client) Connect() (*websocket.Conn, error)
  • func (c *Client) ConnectAndRegister(credentials Credentials) (*SessionConn, error)
  • func (c *Client) ConnectAndRegisterContext(ctx context.Context, credentials Credentials) (*SessionConn, error)
  • func (c *Client) ConnectContext(ctx context.Context) (*websocket.Conn, error)
• type Credentials
• type HandshakeError
  • func (e *HandshakeError) Error() string
  • func (e *HandshakeError) Permanent() bool
  • func (e *HandshakeError) Retryable() bool
• type Server
  • func NewServer() *Server
  • func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request) (*websocket.Conn, error)
• type SessionConn
  • func (c *SessionConn) Read() (env protocol.Envelope, err error)
  • func (c *SessionConn) RegisteredEnvelope() protocol.Envelope
  • func (c *SessionConn) Send(env protocol.Envelope) (err error)
  • func (c *SessionConn) SendPayload(msgID, messageType string, payload any) error
• type SessionKeys
  • func DeriveSessionKeys(token, applicationKey string, shared []byte, ...) (SessionKeys, error)

Constants

const (
	KeySize      = 16
	AlgAES128GCM = "AES-128-GCM"
	// MaxPlaintextPayload 是注册后单个解密 payload 的最大字节数。
	MaxPlaintextPayload = 7 << 20
	// MaxFrameSize 是 WebSocket 单帧 Envelope 的最大字节数。
	MaxFrameSize = 10 << 20
)

const (

	// ShareSize 是 X25519 公钥和共享秘密的固定字节数。
	ShareSize = 32
)

Functions

func ComputeSharedSecret

func ComputeSharedSecret(private *ecdh.PrivateKey, peerShare string) ([]byte, error)

ComputeSharedSecret 校验对端公钥编码并计算 X25519 共享秘密。 crypto/ecdh 对低阶点在 ECDH 阶段返回错误，因此无需额外的小子群检查。

func DecryptEnvelopePayload

func DecryptEnvelopePayload[T any](c *AES128GCM, env *protocol.Envelope) (T, error)

DecryptEnvelopePayload 解密 env.Payload 并反序列化为目标类型。

func GenerateKey

func GenerateKey() ([]byte, error)

GenerateKey 生成 16 字节 AES-128 随机密钥。

func NewEphemeralShare

func NewEphemeralShare() (*ecdh.PrivateKey, string, error)

NewEphemeralShare 生成一次性 X25519 密钥对，返回私钥及其标准 base64 公钥。 私钥用后即弃，使长期秘密事后泄露也无法重算历史会话密钥。

func NewRegisterProof

func NewRegisterProof(keys SessionKeys, transcript protocol.HandshakeTranscript, handInfo *protocol.HandInfo) (protocol.RegisterProof, error)

NewRegisterProof 创建绑定 transcript 且加密身份声明的 v2 GCM proof。

func ReadPayload

func ReadPayload[T any](c *SessionConn) (protocol.Envelope, T, error)

ReadPayload 读取消息并严格解码其 typed payload。

func VerifyRegisterProof

func VerifyRegisterProof(keys SessionKeys, transcript protocol.HandshakeTranscript, proof protocol.RegisterProof) (protocol.RegisterProofClaims, error)

VerifyRegisterProof 验证并解密 proof，返回通过角色约束检查的身份声明。

Types

type AES128GCM

type AES128GCM struct {
	// contains filtered or unexported fields
}

AES128GCM 封装 AES-128-GCM 加解密。

func NewAES128GCM

func NewAES128GCM(key []byte) (*AES128GCM, error)

NewAES128GCM 用 16 字节密钥创建加密器。

func (*AES128GCM) Decrypt

func (c *AES128GCM) Decrypt(data, aad []byte) ([]byte, error)

Decrypt 解密密文，aad 必须与加密时一致，否则因 GCM tag 验证失败返回错误。 密文必须至少 NonceSize() 字节。

func (*AES128GCM) Encrypt

func (c *AES128GCM) Encrypt(plain, aad []byte) ([]byte, error)

Encrypt 加密明文，aad 会参与认证但不放入密文。 返回 nonce || ciphertext。

func (*AES128GCM) EncryptEnvelopePayload

func (c *AES128GCM) EncryptEnvelopePayload(env *protocol.Envelope, payload any) error

EncryptEnvelopePayload 将 payload 序列化后加密写入 env.Payload。 调用前 env 必须已经带有最终的 msg_id/type/session_id/from/to/seq。

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client 是 WS 客户端，供 Face 和 Hand 使用以连接 Mind。

func NewClient

func NewClient(serverURL string) *Client

NewClient 创建 WS 客户端。

func (*Client) Connect

func (c *Client) Connect() (*websocket.Conn, error)

Connect 与服务器建立 WebSocket 连接。

func (*Client) ConnectAndRegister

func (c *Client) ConnectAndRegister(credentials Credentials) (*SessionConn, error)

ConnectAndRegister 连接服务端并完成 version 2 四步挑战握手。

func (*Client) ConnectAndRegisterContext

func (c *Client) ConnectAndRegisterContext(ctx context.Context, credentials Credentials) (*SessionConn, error)

ConnectAndRegisterContext 连接服务端并完成可由 context 取消的 version 2 四步挑战握手。

func (*Client) ConnectContext

func (c *Client) ConnectContext(ctx context.Context) (*websocket.Conn, error)

ConnectContext 与服务器建立可由 context 取消的 WebSocket 连接。

type Credentials

type Credentials struct {
	Label          string
	Type           protocol.PeerType
	Token          string
	ApplicationKey string
	Info           *protocol.HandInfo
}

Credentials 是四步注册所需的不可变身份凭据。

type HandshakeError

type HandshakeError struct {
	Code string
}

HandshakeError 是服务端返回的稳定握手错误。

func (*HandshakeError) Error

func (e *HandshakeError) Error() string

func (*HandshakeError) Permanent

func (e *HandshakeError) Permanent() bool

Permanent 报告客户端是否必须停止自动重试。

func (*HandshakeError) Retryable

func (e *HandshakeError) Retryable() bool

Retryable 报告客户端是否可使用 capped backoff 重试。

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server 接受来自 Face 和 Hand 的 WebSocket 连接。

func NewServer

func NewServer() *Server

NewServer 创建 WS 服务端。

func (*Server) Upgrade

func (s *Server) Upgrade(w http.ResponseWriter, r *http.Request) (*websocket.Conn, error)

Upgrade 将 HTTP 请求升级为 WebSocket 连接。

type SessionConn

type SessionConn struct {
	Conn    *websocket.Conn
	Session *protocol.Session
	// contains filtered or unexported fields
}

SessionConn 是完成注册后的加密客户端连接。

func (*SessionConn) Read

func (c *SessionConn) Read() (env protocol.Envelope, err error)

Read 读取、校验并解密一条业务消息。

func (*SessionConn) RegisteredEnvelope

func (c *SessionConn) RegisteredEnvelope() protocol.Envelope

RegisteredEnvelope 返回完成握手时收到的已解密 registered 消息。

func (*SessionConn) Send

func (c *SessionConn) Send(env protocol.Envelope) (err error)

Send 发送并加密业务 payload；调用方 Envelope.Payload 应由 NewEnvelope 创建。

func (*SessionConn) SendPayload

func (c *SessionConn) SendPayload(msgID, messageType string, payload any) error

SendPayload 创建、stamp 并加密一条 typed payload 消息。

type SessionKeys

type SessionKeys struct {
	Proof          [KeySize]byte
	ClientToServer [KeySize]byte
	ServerToClient [KeySize]byte
}

SessionKeys 是注册 transcript 派生的三把用途隔离密钥。

func DeriveSessionKeys

func DeriveSessionKeys(token, applicationKey string, shared []byte, transcript protocol.HandshakeTranscript) (SessionKeys, error)

DeriveSessionKeys 按 v3 transcript、ECDH 共享秘密和两项长期秘密 派生 proof、C→S 和 S→C 密钥。

shared 必须是 32 字节 X25519 输出。它使会话密钥无法仅由长期秘密重算， 从而同时提供前向保密和握手新鲜性。