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. 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.