From: Ruben Beltran del Rio <redacted>
Date: Sat, 10 Feb 2024 23:42:47 +0000 (+0100)
Subject: Add message definition
X-Git-Url: https://git.r.bdr.sh/rbdr/tiny-command-pal/commitdiff_plain/refs/heads/main?ds=inline

Add message definition
---

3d69dc4dfe5367a2fd97d7a2f032cce25650cf07
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f6e8a11
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# tiny-command-pal (tcpal)
+
+A server that listens for a signed command and payload, and executes a local command based on it. It's intended to be used on very low bandwidth networks.
+
+## Configuration
+
+tcpal is configured using a TOML located in `XDG_CONFIG_HOME` called tcpal.toml
+
+A typical tcpal config looks like this
+
+```
+[publish_blog]
+command = 'echo {{payload}} > ~/posts/incoming.gmi && blog --add ~/posts/incoming.gmi'
+authorized_keys = [
+    ssh-ed25519 AAAA...ZZZ ruben
+]
+authorized_hosts = [
+    192.168.1.10,
+    192.168.0.0/24
+]
+```
+
+- `command` is the command to execute. {{payload}} will be replaced with the contents of the signed payload. Can't be longer than 255 bytes.
+- `authorized_keys` is an array of public ed25519 keys that are allowed to run this command.
+- `authorized_hosts` is an array of hosts that are authorized to run this command. 0.0.0.0 is not allowed.
+
+At least one entry is required in both of the authorized arrays, otherwise the command won't be executed.
+
+## The Process
+
+TBD
+
+## The Messages
+
+- Message IDs 00-79 are reserved for clients.
+- Message IDs 80-FF are reserved for servers.
+
+### The Authorization Check Message (0x00)
+
+This command is used to confirm whether the current host is authorized to send the given command. While not necessary, it is recommended that clients do this to avoid sending the payload without confirming the identity of the server, and whether the command is allowed.
+
+```
+## Header, 4 bytes
+1. Magic Byte (0x7C), 1 byte
+2. Command Message Flag (0x01), 1 byte
+3. Length of command in bytes (0x00-0xFF), 1 byte
+4. Start of Text Byte (0x02), 1 byte
+## The Command (Variable)
+1. The command, Up to 255 bytes in length, must correspond to the value in header field 3
+2. Unit Separator Byte (0x1F), 1 byte
+3. The signature of the command, signed by a private ed25519 key, 64 bytes
+4. End of Text Byte (0x03), 1 byte
+## Footer, 1 byte
+2. End of Transmission Byte (0x04), 1 byte
+```
+
+### The Authorization Response Message (0x80)
+
+Sent as a response of the 0x00 message. It includes the authorization status of the client for the given command, as well as the signature of the command signed by the server.
+
+This signature should be used to confirm whether the client is talking to the right server. This is left up to the client and can be strict (eg. only accept responses from servers whose public key we have authorized before), flexible (eg. accept the first signature and ensure a server keeps the same signature), or it may choose to ignore this value completely.
+
+```
+## Header, 3 bytes
+1. Magic Byte (0x7C), 1 byte
+2. Authorization Response Message Flag (0x80), 1 byte
+3. Start of Text Byte (0x02), 1 byte
+## The Command, 67 bytes
+1. Authorization Response Code (0x00-0xFF), 1 byte
+2. Record Separator Byte (0x1E), 1 byte
+3. The signature of the command, signed by the server's private ed25519 key, 64 bytes
+4. End of Transmission Byte (0x04), 1 byte
+```
+
+The codes are as follows:
+
+- 00 Authorized
+- 40 Unrecognized Command
+- 41 Unauthorized Host
+- 42 Unauthorized Key
+- 50 Unknown Error
+
+### The Command Message (0x01)
+
+This is an actual command.
+
+```
+## Header, 8 bytes
+1. Magic Byte (0x7C), 1 byte
+2. Command Message Flag (0x01), 1 byte
+3. Length of command in bytes (0x00-0xFF), 1 byte
+4. Length of payload (0x00000000-0xFFFFFFFF), 4 bytes
+5. Start of Text Byte (0x02), 1 byte
+## The Command (Variable)
+1. The command, Up to 255 bytes in length, must correspond to the value in header field 3
+2. Unit Separator Byte (0x1F), 1 byte
+3. The signature of the command, signed by a private ed25519 key, 64 bytes
+4. Record Separator Byte (0x1E), 1 byte
+## The Payload (Variable)
+1. The payload, up to 4,294,967,295 bytes in length, must correspond to the value in header field 4. Encoding will be assumed to be Mac OS Roman.
+2. Unit Separator Byte (0x1F)
+3. The signature of the payload, signed by the same private ed25519 key as the command, 64 bytes
+4. End of Text Byte (0x03), 1 byte
+## Footer, 1 byte
+2. End of Transmission Byte (0x04), 1 byte
+```
+
+### The Command Result Message (0x81)
+
+Sent as a response to an 0x01 command, it includes the authorization code, the exit status of the command, and the signature of the command sent.
+
+If authorization is anything other than 0x00, then exit status will always be 0x00.
+
+```
+## Header, 3 bytes
+1. Magic Byte (0x7C), 1 byte
+2. Authorization Response Message Flag (0x80), 1 byte
+3. Start of Text Byte (0x02), 1 byte
+## Body, 69 Bytes
+1. Authorization Response Code (0x00-0xFF), 1 byte
+2. Record Separator Byte (0x1E), 1 byte
+3. Command Exit Status Code (0x00-0xFF), 1 byte
+4. Record Separator Byte (0x1E), 1 byte
+5. The signature of the command, signed by the server's private ed25519 key, 64 bytes
+6. End of Transmission Byte (0x04), 1 byte
+```
+
+The authorization codes are the same as for the authorization response message.