]> git.r.bdr.sh - rbdr/tiny-command-pal/blob - README.md
Add message definition
[rbdr/tiny-command-pal] / README.md
1 # tiny-command-pal (tcpal)
2
3 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.
4
5 ## Configuration
6
7 tcpal is configured using a TOML located in `XDG_CONFIG_HOME` called tcpal.toml
8
9 A typical tcpal config looks like this
10
11 ```
12 [publish_blog]
13 command = 'echo {{payload}} > ~/posts/incoming.gmi && blog --add ~/posts/incoming.gmi'
14 authorized_keys = [
15 ssh-ed25519 AAAA...ZZZ ruben
16 ]
17 authorized_hosts = [
18 192.168.1.10,
19 192.168.0.0/24
20 ]
21 ```
22
23 - `command` is the command to execute. {{payload}} will be replaced with the contents of the signed payload. Can't be longer than 255 bytes.
24 - `authorized_keys` is an array of public ed25519 keys that are allowed to run this command.
25 - `authorized_hosts` is an array of hosts that are authorized to run this command. 0.0.0.0 is not allowed.
26
27 At least one entry is required in both of the authorized arrays, otherwise the command won't be executed.
28
29 ## The Process
30
31 TBD
32
33 ## The Messages
34
35 - Message IDs 00-79 are reserved for clients.
36 - Message IDs 80-FF are reserved for servers.
37
38 ### The Authorization Check Message (0x00)
39
40 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.
41
42 ```
43 ## Header, 4 bytes
44 1. Magic Byte (0x7C), 1 byte
45 2. Command Message Flag (0x01), 1 byte
46 3. Length of command in bytes (0x00-0xFF), 1 byte
47 4. Start of Text Byte (0x02), 1 byte
48 ## The Command (Variable)
49 1. The command, Up to 255 bytes in length, must correspond to the value in header field 3
50 2. Unit Separator Byte (0x1F), 1 byte
51 3. The signature of the command, signed by a private ed25519 key, 64 bytes
52 4. End of Text Byte (0x03), 1 byte
53 ## Footer, 1 byte
54 2. End of Transmission Byte (0x04), 1 byte
55 ```
56
57 ### The Authorization Response Message (0x80)
58
59 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.
60
61 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.
62
63 ```
64 ## Header, 3 bytes
65 1. Magic Byte (0x7C), 1 byte
66 2. Authorization Response Message Flag (0x80), 1 byte
67 3. Start of Text Byte (0x02), 1 byte
68 ## The Command, 67 bytes
69 1. Authorization Response Code (0x00-0xFF), 1 byte
70 2. Record Separator Byte (0x1E), 1 byte
71 3. The signature of the command, signed by the server's private ed25519 key, 64 bytes
72 4. End of Transmission Byte (0x04), 1 byte
73 ```
74
75 The codes are as follows:
76
77 - 00 Authorized
78 - 40 Unrecognized Command
79 - 41 Unauthorized Host
80 - 42 Unauthorized Key
81 - 50 Unknown Error
82
83 ### The Command Message (0x01)
84
85 This is an actual command.
86
87 ```
88 ## Header, 8 bytes
89 1. Magic Byte (0x7C), 1 byte
90 2. Command Message Flag (0x01), 1 byte
91 3. Length of command in bytes (0x00-0xFF), 1 byte
92 4. Length of payload (0x00000000-0xFFFFFFFF), 4 bytes
93 5. Start of Text Byte (0x02), 1 byte
94 ## The Command (Variable)
95 1. The command, Up to 255 bytes in length, must correspond to the value in header field 3
96 2. Unit Separator Byte (0x1F), 1 byte
97 3. The signature of the command, signed by a private ed25519 key, 64 bytes
98 4. Record Separator Byte (0x1E), 1 byte
99 ## The Payload (Variable)
100 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.
101 2. Unit Separator Byte (0x1F)
102 3. The signature of the payload, signed by the same private ed25519 key as the command, 64 bytes
103 4. End of Text Byte (0x03), 1 byte
104 ## Footer, 1 byte
105 2. End of Transmission Byte (0x04), 1 byte
106 ```
107
108 ### The Command Result Message (0x81)
109
110 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.
111
112 If authorization is anything other than 0x00, then exit status will always be 0x00.
113
114 ```
115 ## Header, 3 bytes
116 1. Magic Byte (0x7C), 1 byte
117 2. Authorization Response Message Flag (0x80), 1 byte
118 3. Start of Text Byte (0x02), 1 byte
119 ## Body, 69 Bytes
120 1. Authorization Response Code (0x00-0xFF), 1 byte
121 2. Record Separator Byte (0x1E), 1 byte
122 3. Command Exit Status Code (0x00-0xFF), 1 byte
123 4. Record Separator Byte (0x1E), 1 byte
124 5. The signature of the command, signed by the server's private ed25519 key, 64 bytes
125 6. End of Transmission Byte (0x04), 1 byte
126 ```
127
128 The authorization codes are the same as for the authorization response message.