git.r.bdr.sh - rbdr/tiny-command-pal/blob - 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. Authorization Check Message Flag (0x00), 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 1. End of Transmission Byte (0x04), 1 byte
  55 ```
  56
  57 ```
  58 All numbers in hexadecimal.
  59 ┌───────────────────┬──────────────────────────────────┬────┐
  60 │      HEADER       │               BODY               │FOOT│
  61 ├────┬────┬────┬────┼────┬─────────┬────┬────┬────┬────┼────┤
  62 │ 00 │ 01 │ 02 │ 03 │ 04 ┊ 04+CLEN │A+01│A+02┊A+41│A+42│A+43│
  63 ├────┼────┼────┼────┼────┴─────────┼────┼────┴────┼────┼────┤
  64 │ 7C │ 00 │CLEN│ 02 │   COMMAND    │ 1F │SIGNATURE│ 03 │ 04 │
  65 └────┴────┴────┴────┴──────────────┴────┴─────────┴────┴────┘
  66                                   A
  67 ```
  68
  69 ### The Authorization Response Message (0x80)
  70
  71 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.
  72
  73 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.
  74
  75 ```
  76 ## Header, 3 bytes
  77 1. Magic Byte (0x7C), 1 byte
  78 2. Authorization Response Message Flag (0x80), 1 byte
  79 3. Start of Text Byte (0x02), 1 byte
  80 ## The Command, 67 bytes
  81 1. Authorization Response Code (0x00-0xFF), 1 byte
  82 2. Record Separator Byte (0x1E), 1 byte
  83 3. The signature of the command, signed by the server's private ed25519 key, 64 bytes
  84 4. End of Text Byte (0x03), 1 byte
  85 ## Footer, 1 byte
  86 4. End of Transmission Byte (0x04), 1 byte
  87 ```
  88
  89 ```
  90 All numbers in hexadecimal.
  91 ┌──────────────┬────────────────────────┬────┐
  92 │    HEADER    │          BODY          │FOOT│
  93 ├────┬────┬────┼────┬────┬────┬────┬────┼────┤
  94 │ 00 │ 01 │ 02 │ 03 ┊ 04 │ 05 ┊ 44 │ 45 ┊ 41 │
  95 ├────┼────┼────┼────┼────┼────┴────┼────┼────┤
  96 │ 7C │ 80 │ 02 │AUTH│ 1E │SIGNATURE│ 03 │ 04 │
  97 └────┴────┴────┴────┴────┴─────────┴────┴────┘
  98 ```
  99
 100 The codes are as follows:
 101
 102 - 00 Authorized
 103 - 40 Unrecognized Command
 104 - 41 Unauthorized Host
 105 - 42 Unauthorized Key
 106 - 50 Unknown Error
 107
 108 ### The Command Message (0x01)
 109
 110 This is an actual command.
 111
 112 ```
 113 ## Header, 8 bytes
 114 1. Magic Byte (0x7C), 1 byte
 115 2. Command Message Flag (0x01), 1 byte
 116 3. Length of command in bytes (0x00-0xFF), 1 byte
 117 4. Length of payload (0x00000000-0xFFFFFFFF), 4 bytes
 118 5. Start of Text Byte (0x02), 1 byte
 119 ## The Command (Variable)
 120 1. The command, Up to 255 bytes in length, must correspond to the value in header field 3
 121 2. Unit Separator Byte (0x1F), 1 byte
 122 3. The signature of the command, signed by a private ed25519 key, 64 bytes
 123 4. Record Separator Byte (0x1E), 1 byte
 124 ## The Payload (Variable)
 125 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.
 126 2. Unit Separator Byte (0x1F)
 127 3. The signature of the payload, signed by the same private ed25519 key as the command, 64 bytes
 128 4. End of Text Byte (0x03), 1 byte
 129 ## Footer, 1 byte
 130 2. End of Transmission Byte (0x04), 1 byte
 131 ```
 132
 133 ```
 134 All numbers in hexadecimal.
 135 ┌─────────────────────────────┬─────────────────────────────────────────────────────────────────────┬────┐
 136 │           HEADER            │               BODY                               BODY               │FOOT│
 137 ├────┬────┬────┬────┬────┬────┼────┬─────────┬────┬────┬────┬────┬────┬─────────┬────┬────┬────┬────┼────┤
 138 │ 00 │ 01 │ 02 │ 03 ┊ 06 │ 07 │ 08 ┊ 07+CLEN │A+01│A+02┊A+41│A+42│A+43┊A+42+PLEN│B+01│B+02┊B+41│B+42│B+43│
 139 ├────┼────┼────┼────┴────┼────┼────┴─────────┼────┼────┴────┼────┼────┴─────────┼────┼────┴────┼────┼────┤
 140 │ 7C │ 01 │CLEN│   PLEN  │ 02 │   COMMAND    │ 1F │SIGNATURE│ 1E │   PAYLOAD    │ 1F │SIGNATURE│ 03 │ 04 │
 141 └────┴────┴────┴─────────┴────┴──────────────┴────┴─────────┴────┴──────────────┴────┴─────────┴────┴────┘
 142                                             A                                  B
 143 ```
 144
 145 ### The Command Result Message (0x81)
 146
 147 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.
 148
 149 If authorization is anything other than 0x00, then exit status will always be 0x00.
 150
 151 ```
 152 ## Header, 3 bytes
 153 1. Magic Byte (0x7C), 1 byte
 154 2. Command Result Message Flag (0x81), 1 byte
 155 3. Start of Text Byte (0x02), 1 byte
 156 ## Body, 69 Bytes
 157 1. Authorization Response Code (0x00-0xFF), 1 byte
 158 2. Record Separator Byte (0x1E), 1 byte
 159 3. Command Exit Status Code (0x00-0xFF), 1 byte
 160 4. Record Separator Byte (0x1E), 1 byte
 161 5. The signature of the command, signed by the server's private ed25519 key, 64 bytes
 162 6. End of Text Byte (0x03), 1 byte
 163 ## Footer, 1 byte
 164 1. End of Transmission Byte (0x04), 1 byte
 165 ```
 166
 167 ```
 168 All numbers in hexadecimal.
 169 ┌──────────────┬──────────────────────────────────┬────┐
 170 │    HEADER    │          BODY                    │FOOT│
 171 ├────┬────┬────┼────┬────┬────┬────┬────┬────┬────┼────┤
 172 │ 00 │ 01 │ 02 │ 03 ┊ 04 │ 05 ┊ 06 │ 07 ┊ 46 │ 47 ┊ 48 │
 173 ├────┼────┼────┼────┼────┼────┼────┼────┴────┼────┼────┤
 174 │ 7C │ 81 │ 02 │AUTH│ 1E │CODE│ 1E │SIGNATURE│ 03 │ 04 │
 175 └────┴────┴────┴────┴────┴────┴────┴─────────┴────┴────┘
 176 ```
 177
 178 The authorization codes are the same as for the authorization response message.