Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion auth.proto
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,10 @@ message Auth {

// Random bytes appended so that the encrypted message size varies
// across sessions. Defeats traffic-analysis fingerprinting of the
// Auth frame; the Node ignores the contents.
// Auth frame; the Node ignores the contents. MUST NOT exceed 1024
// bytes. The Node SHOULD enforce this ceiling as a raw-wire length
// check before deserialising the message, so that an unauthenticated
// peer cannot force a large pre-HMAC allocation.
bytes padding = 6;

// Version of the APN client software sending the request, in the
Expand Down
49 changes: 12 additions & 37 deletions welcome.proto
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,20 @@ package proto;

// Outcome of the Node's check of the preceding Auth message.
enum Status {
// Zero-value sentinel. Proto3 defaults missing / unrecognised enum
// fields to 0, so a truncated Welcome would otherwise deserialise
// as OK. Clients MUST reject STATUS_UNSPECIFIED as a hard error.
STATUS_UNSPECIFIED = 0;

// Authentication succeeded; the rest of the Welcome carries the
// assigned tunnel address.
OK = 1;
OK = 0;

// Authentication failed; see Welcome.error for the reason.
ERROR = 2;
ERROR = 1;
}

// Welcome is the Node's reply to Auth. It is sent exactly once per
// session, immediately after the Node decides whether to accept the
// client. On OK the client switches to tunnel mode and begins
// exchanging IP/Ping/Pong frames; on STATUS_UNSPECIFIED or ERROR
// it disconnects.
// exchanging IP/Ping/Pong frames; on ERROR it disconnects.
message Welcome {
// Whether the Node accepted the Auth message. Clients MUST reject
// STATUS_UNSPECIFIED as a protocol error (truncated / malformed
// frame).
// Whether the Node accepted the Auth message.
Status status = 1;

// Human-readable build tag of the Node, e.g. "1.2.3"; surfaced in
Expand All @@ -40,46 +32,29 @@ message Welcome {
// mismatch before falling back to the textual `major`.
uint32 minor = 6;

// IPv4 address (4 raw bytes, network byte order) assigned to the
// client inside the tunnel for the lifetime of this session. The
// client uses it as the source address of every encapsulated IPv4
// packet; IPv6 packets use `ip6` instead.
// IPv4 address (4 raw bytes) assigned to the client inside the
// tunnel for the lifetime of this session. The client uses it as
// the source address of every encapsulated IP packet.
bytes ip = 2;

// IPv6 address (16 raw bytes) assigned to the client inside the
// tunnel for the lifetime of this session, the counterpart of `ip`.
// The client uses it as the source of every encapsulated IPv6
// packet. Empty when the Node offers no IPv6 tunnel.
bytes ip6 = 9;

// Free-form error message explaining why authentication failed.
// Set only when `status == ERROR`; empty otherwise.
string error = 3;

// Random bytes appended so that the encrypted Welcome size varies
// across sessions, mirroring Auth.padding. MUST NOT exceed 1024
// bytes. The client SHOULD check the raw-wire frame length before
// deserialising the protobuf, so that a rogue Node cannot force a
// large allocation before the client inspects `status`.
// bytes.
bytes padding = 4;

// Public IPv4 (4 raw bytes, network byte order) of the client as
// observed by the Node — i.e. the address the client appears to
// come from on the public Internet. The client compares this to
// its local view to detect NAT and to populate analytics.
// Public IPv4 (4 raw bytes) of the client as observed by the Node
// — i.e. the address the client appears to come from on the
// public Internet. The client compares this to its local view to
// detect NAT and to populate analytics.
bytes home = 7;

// Public IPv6 (16 raw bytes) of the client as observed by the Node,
// the IPv6 counterpart of `home`. Empty when the client reached the
// Node over IPv4.
bytes home6 = 10;

// Node ID of the responding Node, taken verbatim from its APN_NID
// environment variable. The value carries a short prefix followed
// by a colon (e.g. "VLZ:" or "HTZ:") that the client surfaces in
// diagnostics and the tunnel header to hint at the hosting region.
// MUST be non-empty when status == OK; an empty nid silently
// breaks the prefix invariant. Node implementations should refuse
// to start when APN_NID is unset.
string nid = 8;
}