e2e

Documentation

Overview

Package e2e implements the end-to-end encryption layer that wraps every peer-to-peer connection in git-lan. No application bytes ever cross the wire unencrypted.

The scheme is deliberately small and conventional:

• Ephemeral X25519 keys are exchanged per connection (forward secrecy).
• A shared secret is derived via X25519 ECDH.
• HKDF-SHA256 expands it into two *directional* ChaCha20-Poly1305 keys, so compromise of one direction's key does not affect the other.
• Each frame carries a 12-byte nonce: a 32-bit random prefix fixed at handshake time plus a 64-bit monotonically increasing counter.
• Receivers reject any nonce that does not strictly advance, defeating replay and reordering.

Index

• Constants
• Variables
• type EncryptedConn
  • func Client(conn net.Conn) (*EncryptedConn, error)
  • func ClientAuth(conn net.Conn, identity *ecdh.PrivateKey) (*EncryptedConn, []byte, error)
  • func Server(conn net.Conn) (*EncryptedConn, error)
  • func ServerAuth(conn net.Conn, identity *ecdh.PrivateKey) (*EncryptedConn, []byte, error)
  • func (c *EncryptedConn) Close() error
  • func (c *EncryptedConn) LocalAddr() net.Addr
  • func (c *EncryptedConn) Read(p []byte) (int, error)
  • func (c *EncryptedConn) RemoteAddr() net.Addr
  • func (c *EncryptedConn) SetDeadline(t time.Time) error
  • func (c *EncryptedConn) SetReadDeadline(t time.Time) error
  • func (c *EncryptedConn) SetWriteDeadline(t time.Time) error
  • func (c *EncryptedConn) Write(p []byte) (int, error)

Constants

const (
	KeySize       = 32 // ChaCha20-Poly1305 key
	NonceSize     = 12 // ChaCha20-Poly1305 nonce
	TagSize       = 16 // Poly1305 auth tag
	LenPrefixSize = 4  // big-endian payload length
	// MaxFrameSize bounds a single encrypted frame's plaintext to keep memory
	// bounded against a hostile or buggy peer.
	MaxFrameSize = 1 << 20 // 1 MiB
)

Frame and key sizes.

Variables

var (
	// ErrReplay is returned when a frame's nonce does not strictly advance.
	ErrReplay = errors.New("e2e: replayed or out-of-order nonce")
	// ErrFrameTooLarge is returned when a peer announces an oversized frame.
	ErrFrameTooLarge = errors.New("e2e: frame exceeds maximum size")
	// ErrHandshake is returned when the handshake fails or is malformed.
	ErrHandshake = errors.New("e2e: handshake failed")
	// ErrFingerprintMismatch indicates a trusted peer presented an identity
	// key that does not match its pinned fingerprint - a possible MITM.
	ErrFingerprintMismatch = errors.New("e2e: peer identity does not match pinned fingerprint")
)

Types

type EncryptedConn

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

EncryptedConn wraps a net.Conn so that every byte read or written is transparently encrypted with ChaCha20-Poly1305 using the directional keys negotiated during the handshake. It implements net.Conn, so it is a drop-in replacement anywhere a plain connection is used - including as the transport under git's pkt-line protocol.

Wire frame:

[4 bytes  big-endian payload length L]
[12 bytes nonce]
[L bytes  ciphertext || 16-byte Poly1305 tag]

The 4-byte length is authenticated as additional data, so an attacker cannot silently truncate or extend a frame without the tag check failing.

func Client

func Client(conn net.Conn) (*EncryptedConn, error)

Client performs the handshake as the initiator and returns an encrypted connection over conn.

func ClientAuth

func ClientAuth(conn net.Conn, identity *ecdh.PrivateKey) (*EncryptedConn, []byte, error)

ClientAuth performs an authenticated handshake as the initiator and returns the encrypted connection together with the peer's identity public key.

func Server

func Server(conn net.Conn) (*EncryptedConn, error)

Server performs the handshake as the responder and returns an encrypted connection over conn.

func ServerAuth

func ServerAuth(conn net.Conn, identity *ecdh.PrivateKey) (*EncryptedConn, []byte, error)

ServerAuth performs an authenticated handshake as the responder.

func (*EncryptedConn) Close

func (c *EncryptedConn) Close() error

func (*EncryptedConn) LocalAddr

func (c *EncryptedConn) LocalAddr() net.Addr

func (*EncryptedConn) Read

func (c *EncryptedConn) Read(p []byte) (int, error)

Read returns decrypted plaintext. It satisfies io.Reader: it may return fewer bytes than a full frame, buffering the remainder for the next call.

func (*EncryptedConn) RemoteAddr

func (c *EncryptedConn) RemoteAddr() net.Addr

func (*EncryptedConn) SetDeadline

func (c *EncryptedConn) SetDeadline(t time.Time) error

func (*EncryptedConn) SetReadDeadline

func (c *EncryptedConn) SetReadDeadline(t time.Time) error

func (*EncryptedConn) SetWriteDeadline

func (c *EncryptedConn) SetWriteDeadline(t time.Time) error

func (*EncryptedConn) Write

func (c *EncryptedConn) Write(p []byte) (int, error)

Write encrypts p and sends it as one or more frames. It satisfies io.Writer semantics: on success it returns len(p), nil.