Ensure it's ECNet2 time

Author: migeyel

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "Lua.runtime.version": "Lua 5.3",
+}

README.md

@@ -1 +1,192 @@
-# ecnet
+# ECNet2
+ECNet2 is an encrypted networking library for CC:Tweaked. You can find usage
+examples in the examples directory.
+
+## Dependencies
+- [CCryptolib](https://github.com/migeyel/ccryptolib) >=1.1.0 (you still need to
+  initialize the random generator yourself)
+- [RedRun](https://gist.github.com/MCJack123/473475f07b980d57dd2bd818026c97e8)
+
+## Goals
+- Let the user manage the lifetime of connections.
+- Minimize the work done by the responder before they accept a handshake.
+- Let the user pick a "protocol" (channel, namespace, ...) to talk through.
+- Strong assurances for traffic authenticity and confidentiality.
+- High efficiency in both computation and bandwidth usage.
+- Best-effort hiding of relevant parties' identities.
+- Best-effort handling of network abuse.
+
+## Non-goals
+- Authenticated multicast or broadcast of messages.
+
+# API Reference
+
+### `ecnet2.open(modem: string)`
+Opens a modem for communications.
+
+### `ecnet2.close([modem: string])`
+Closes a modem for communications.
+
+### `ecnet2.isOpen([modem: string])`
+Returns whether a modem is open for communications.
+
+### `ecnet2.address(): string`
+Returns the address for connecting to this device.
+
+### `ecnet2.Protocol(interface: IProtocol): Protocol`
+Creates a protocol from a given interface.
+
+## Type `IProtocol`
+A table containing a description for a protocol.
+
+### `IProtocol.name: string`
+The protocol's name.
+
+### `Iprotocol.serialize(object: any): string`
+A serializer for protocol objects.
+
+### `IProtocol.deserialize(str: string): any`
+A deserializer for protocol objects.
+
+## Type `Protocol`
+A namespace for interpreting messages received over connections.
+
+### `Procotol:connect(address: string, modem: string): Connection`
+Creates a new connection using this protocol and a modem.
+
+### `Protocol:listen(): Listener`
+Creates a listener for this protocol on all open modems.
+
+## Type `Listener`
+A listener for incoming connection requests.
+
+### `Listener.id: string`
+The listener's ID, used in resolving `ecnet2_request` events.
+
+### `Listener:accept(reply: any[, request: Request]): Connection`
+Accepts a request and builds a connection. Waits for the next request if none
+are provided.
+
+Throws `"invalid listener for this request"` if the supplied request isn't meant
+for this listener.
+
+Returns a dummy connection if the request is malformed, or if the request has
+already been accepted.
+
+## Type `Connection`
+An encrypted tunnel operating over a network.
+
+### `Connection.id: string`
+The connection's ID, used in `ecnet2_message` events.
+
+### `Connection:send(message: any)`
+Sends a message.
+
+Throws `"can't send on an incomplete connection"` until at least one
+message has been received.
+
+### `Connection:receive([timeout: number]): string, any`
+Yields until a message is received. Returns the sender and contents, or nil on
+timeout.
+
+## Events
+### `"ecnet2_request", listenerId: string, request: Request, side: string`
+A connection request.
+- `listenerId` - The `id` field of the listener that received this request.
+- `request` - The request to pass on to the `accept` method.
+- `side` - Which modem the request was received through.
+
+### `"ecnet2_message", connectionId: string, sender: string, message: any`
+A message in a connection.
+- `connectionId` - The `id` field of the connection that received this message.
+- `sender` - The sender's address.
+- `message` - The deserialized message data.
+
+# Technical Details
+
+## Descriptors
+Every ECNet2 packet has a 32 byte prefix known as the *descriptor*. Descriptors
+allow the receiver to know whether it is supposed to process a packet.
+Furthermore, secret descriptors allow for some resistance against decryption
+failure denial-of-service attacks on networks with no wormholes.
+
+The listener descriptor is defined as `BLAKE3(BLAKE3(pk .. BLAKE3(protocol)))`,
+where `pk` is the listener's public key and `protocol` is the protocol name.
+
+The connection descriptors are derived from the current decryption key, which is
+ratcheted every time a new message is received.
+
+## Handshake
+We use the noise XK handshake, its pattern is:
+```
+XK:
+  <- s
+  ...
+  -> e, es
+  <- e, ee
+  -> s, se
+```
+
+The contents of each handshake payload are:
+### `-> e, es`
+This payload currently contains only padding.
+
+### `<- e, ee`
+This payload contains a user-defined reply and padding. Neither the user nor
+ECNet know who the initiator is. As a result, naive assumptions match exactly
+what the payload security properties (2, 1) are.
+
+### `-> s, se`
+This payload contains a user-defined message and padding. The naive assumptions
+match exactly what the payload security properties (2, 5) are.
+
+### Why _K?
+We need the initiator to have a secret descriptor at the first response,
+otherwise an attacker could trigger decryption failures arbitrarily, throwing
+the entire connection away. We could try restarting the connection again, but
+that's difficult to model in the interface.
+
+### Why not IK?
+1. The initiator's identity claim is vulnerable to replay attack, so we can't
+assume anything until their first transport message, making IK pointless.
+2. IK has an `ss` token, which is harder to protect against timing attacks on
+the result of the DH operation, while `es` and `se` are a bit safer.
+3. IK hides identity more poorly than XK.
+
+### Why not NK?
+Authenticating the initiatior makes the API simpler from the user's point of
+view, since they don't have to handle whether the message has a sender or not.
+
+## Size Limits
+
+### `accept()` Reply Argument
+The message size limit is 2¹⁵ - 1 = 32767 bytes. The other half of the payload
+is reserved for ECNet metadata.
+
+### Initiator's First Message
+The message size limit is 2¹⁵ - 1 = 32767 bytes. The other half of the payload
+is reserved for ECNet metadata.
+
+### Other Messages
+50 bytes of overhead:
+- 32 bytes for the descriptor
+- 1 byte for packet type information
+- At least 1 byte for padding
+- 16 bytes for the message's tag
+
+Since noise allows packets of at most 2¹⁶ - 1 bytes in length, the message size
+limit is 2¹⁶ - 1 - 50 = 65485 bytes.
+
+## Handshake Model
+The XK handshake is modeled into `Connection` and `Listener` objects. The second
+payload is modeled as a `reply` parameter to `accept`, while the third payload
+is modeled as a regular message:
+```
+Handshake payloads:
+connect() -> e, es, ""    -> os.pullEvent("ecnet2_request")
+receive() <- e, ee, reply <- accept(reply)
+send(msg) -> s, se, msg   -> receive()
+
+Transport:
+receive() <- msg <- send(msg)
+send(msg) -> msg -> receive()

ecnet2/CipherState.lua

@@ -0,0 +1,74 @@
+local class = require "ecnet2.class"
+local aead = require "ccryptolib.aead"
+local chacha = require "ccryptolib.chacha20"
+
+--- A symmetric encryption cipher state, containing a key and a numeric nonce.
+--- @class ecnet2.CipherState
+--- @field private k string? The current key.
+--- @field private n number The current nonce.
+local CipherState = class "ecnet2.CipherState"
+
+--- @param key string? A 32-byte key to initialize the state with.
+function CipherState:initialise(key)
+    self.k = key
+    self.n = 0
+end
+
+--- Whether the state has a key or not.
+--- @return boolean
+function CipherState:hasKey()
+    return self.k ~= nil
+end
+
+--- Sets the nonce to the given value.
+--- @param nonce number
+function CipherState:setNonce(nonce)
+    self.n = nonce
+end
+
+--- Rekeys the cipher.
+function CipherState:rekey()
+    self.k = chacha.crypt(self.k, ("<I12"):pack(2 ^ 64 - 1), ("\0"):rep(32), 8)
+end
+
+--- Computes the cipher descriptor.
+--- @return string
+function CipherState:descriptor()
+    local c = chacha.crypt(self.k, ("<I12"):pack(2 ^ 64 - 1), ("\0"):rep(64), 8)
+    return c:sub(33)
+end
+
+--- Encrypts a message. Returns the plaintext itself when no key is set.
+--- @param ad string Associated data to authenticate.
+--- @param plaintext string The plaintext to encrypt
+--- @return string ciphertext The encrypted text.
+function CipherState:encryptWithAd(ad, plaintext)
+    if self:hasKey() then
+        local nonce = ("<I12"):pack(self.n)
+        local ctx, tag = aead.encrypt(self.k, nonce, plaintext, ad, 8)
+        self.n = self.n + 1
+        return ctx .. tag
+    else
+        return plaintext
+    end
+end
+
+--- Decrypts a message.
+--- @param ad string Associated data to authenticate.
+--- @param ciphertext string The ciphertext to decrypt.
+--- @return string? plaintext The decrypted plaintext, or nil on failure.
+function CipherState:decryptWithAd(ad, ciphertext)
+    if self:hasKey() then
+        if #ciphertext < 16 then return end
+        local ctx, tag = ciphertext:sub(1, -17), ciphertext:sub(-16)
+        local nonce = ("<I12"):pack(self.n)
+        -- On decryption failure, increment nonce and return nil.
+        local plaintext = aead.decrypt(self.k, nonce, tag, ctx, ad, 8)
+        self.n = self.n + 1
+        return plaintext
+    else
+        return ciphertext
+    end
+end
+
+return CipherState

ecnet2/Connection.lua

@@ -0,0 +1,84 @@
+local class = require "ecnet2.class"
+local ecnetd = require "ecnet2.ecnetd"
+local addressEncoder = require "ecnet2.addressEncoder"
+local modems = require "ecnet2.modems"
+local uid = require "ecnet2.uid"
+
+--- An encrypted tunnel operating over a modem.
+--- @class ecnet2.Connection
+--- @field _state ecnet2.HandshakeState The current handshake state.
+--- @field _protocol ecnet2.Protocol The connection's protocol.
+--- @field _side string The modem name this connection is routing through.
+--- @field _handler function The packet handler function.
+--- @field id string The connection's ID, used in `ecnet2_message` events.
+local Connection = class "ecnet2.Connection"
+
+--- @param state ecnet2.HandshakeState
+--- @param protocol ecnet2.Protocol
+--- @param side string
+function Connection:initialise(state, protocol, side)
+    self.id = uid()
+    self._protocol = protocol
+    self._side = side
+    self._handler = function(m, _) return self:_handle(m, _) end
+    self._state = state
+    if state.d then ecnetd.handlers[state.d] = self._handler end
+end
+
+--- @param newState ecnet2.HandshakeState
+function Connection:_setState(newState)
+    if self._state.d then ecnetd.handlers[self._state.d] = nil end
+    if newState.d then ecnetd.handlers[newState.d] = self._handler end
+    self._state = newState
+end
+
+--- Handles an incoming packet, modifying the state.
+--- @param packet string
+--- @param _ string
+function Connection:_handle(packet, _)
+    local newState, msg = self._state.resolve(packet)
+    self:_setState(newState)
+    if not msg then return end
+    local deserialize = self._protocol._interface.deserialize
+    local ok, message = pcall(deserialize, msg)
+    if ok then
+        os.queueEvent("ecnet2_message", self.id, self._state.pk, message)
+    end
+end
+
+--- Sends a message.
+---
+--- Throws `"can't send on an incomplete connection"` until at least one
+--- message has been received.
+---
+--- @param message any The message object.
+function Connection:send(message)
+    local str = self._protocol._interface.serialize(message)
+    assert(type(str) == "string", "serializer returned non-string")
+    assert(self._state.maxlen, "can't send on an incomplete connection")
+    assert(#str <= self._state.maxlen, "serialized message is too large")
+    local newState, data = self._state.send(str)
+    self:_setState(newState)
+    if data then modems.transmit(self._side, data) end
+end
+
+--- Yields until a message is received. Returns the sender and contents, or nil
+--- on timeout.
+--- @param timeout number?
+--- @return string? sender
+--- @return any message
+function Connection:receive(timeout)
+    local timer = -1
+    if timeout then timer = os.startTimer(timeout) end
+    while true do
+        local event, p1, p2, p3 = os.pullEvent()
+        if event == "timer" and p1 == timer then
+            return
+        elseif event == "ecnet2_message" and p1 == self.id then
+            os.cancelTimer(timer)
+            return addressEncoder.encode(p2), p3
+        end
+    end
+end
+
+return Connection