Overview
| Comment: | iterate on rasuir |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
e15188634a12da9f3f882af3158914c5 |
| User & Date: | lexi on 2023-01-29 21:16:50 |
| Other Links: | manifest | tags |
Context
|
2023-01-29
| ||
| 21:47 | fixes check-in: 46da53de26 user: lexi tags: trunk | |
| 21:16 | iterate on rasuir check-in: e15188634a user: lexi tags: trunk | |
| 19:21 | add rasuir spec, other updates check-in: 6bda93a905 user: lexi tags: trunk | |
Changes
Added spec/nimtas.ct version [22aa494f33].
1 +# nimtas protocol 2 +the nimtas protocol is a very simple authentication/identification protocol suitable for embedding in other protocols. 3 + 4 +## definitions 5 +an italicized form indicates a formally specified sequence of bytes. parameters (e.g. the length of an integer form) are placed in angle brackets after the identifier. if the form is bound to a name in context, it is followed by a [`:] and a name in variable notation. 6 +* [*byte], [*byte<1>] ==> one octet 7 +* [*byte<[$N]>] ==> [!byte] [!byte<[=N-1]>] 8 +* [*int<[$N]>] ==> [!byte<[=N / 8]>] interpreted as a little-endian unsigned integer (e.g. [!int<32>] represents an unsigned little-endian 32-bit integer) 9 +* [*byte-sequence<[$L]>] ==> [!int<[$L]>:[$N]] [!byte<[$N]>], with no specific semantics. that is, a variable-length byte sequence whose size prefix is [$L] bits long 10 + 11 +##overview 12 +nimtas is composed of two procedures, the [>proc-id] and the authentication procedure. the identity procedure is a [*strict subset] of the authentication procedure and for some clients may be sufficient. formally, the [>proc-auth] is the protocol entry point. 13 + 14 +the initial connection handshake is the responsibility of the containing protocol. 15 + 16 +###proc-auth authentication procedure 17 +: to authenticate by identity alone, client immediately follows the [>proc-id] 18 +: to authenticate by challenge: 19 +:: client transmits: 20 +::: [`0x10] indicating challenge auth 21 +::: a [!byte] naming a supported type of challenge 22 +:::: [`0x00] = passphrase/prompt 23 +:::: [`0x01] = SHA3 nonce hash 24 +:::: [`0x02] = libsodium asymmetric signature 25 +:::: [`0x03] = SCRAM 26 +:::: [`0x04] = U2F 27 +:::: [`0xFF] [!int<32>:[$method-number]] = private challenge method 28 +::: client follows the [>proc-id] 29 +:: if the server does not support the selected challenge type, it sends {m.n status-fail} and closes the connection. 30 +:: otherwise, the following steps are repeated until authentication is complete: 31 +::: if authentication is complete, exit loop and jump to ["[report]] 32 +::: otherwise, server sends {m.n status-data} followed by [!byte-sequence<16>:[$challenge-blob]], the meaning of which depends on the selected challenge method 33 +::: client sends [!byte-sequence<16>:[$challenge-response]] 34 +: ["[report]] server reports authentication status 35 +:: if the authentication failed, xmit {m.n status-fail} and close the connection 36 +:: if the authentication succeeded, xmit {m.n status-ok} 37 + 38 +! other authentication methods may be defined later. a server that encounters an unknown authentication method must transmit {m.n status-fail} and close the connection, as it cannot know how to interpret any further communications from the client 39 + 40 +###proc-id identity procedure 41 +! the identity procedure is a [*strict subset] of the [>proc-auth] 42 + 43 +: to identify anonymously, client transmits byte [`0x00]. 44 +: to identify externally, client transmits byte [`0x01]. this method indicates that identity is already coded by the connection or challenge context, similar to the SASL EXTERNAL method. possible uses cases include connection over UNIX domain socket, over TLS, or when authenticating via a type of challenge that also supplies identification data. 45 +: to identify by shortname, client transmits byte [`0x02] followed by a [!byte-sequence<8>]. this may be a PSK, a URI, a literal text name, an OID, or anything else depending on what the server is configured to recognize. 46 +: to identify by longname, client transmits byte [`0x03] followed by a [!byte-sequence<16>]. this is identical to the above but allows longer values. technically these are different forms of the "name" authentication method; the difference is relevant only at the byte-level 47 +: to identify by private method, client transmits byte [`0x0f] followed by 48 +:: [!int<32>:[$method-number]] 49 +:: [!byte-sequence<16>:[$auth-blob]] 50 + 51 +! note that bytes [`0x04]~[`0x0e] are reserved for potential future identification methods. a server that encounters a method it doesn't understand must immediately send {m.n stats-fail} and close the connection. 52 + 53 +##m magic numbers 54 + n: ‹[*[#1]]› 55 + 56 ++ ID + value + 57 +| status-ok | [`0xFF] | 58 +| status-data | [`0xF0] | 59 +| status-fail | [`0x00] |
Modified spec/rasuir.ct from [13ce85cdbb] to [d1e6e704c3].
17 17 * [*sigint<[$N]>] ==> like the above, but interpreted as a two's-complement signed integer 18 18 * [*byte-sequence<[$L]>] ==> [!int<[$L]>:[$N]] [!byte<[$N]>], with no specific semantics. that is, a variable-length byte sequence whose size prefix is [$L] bits long 19 19 * [*string] ==> [!byte-sequence<8>] interpreted as a UTF-8 string 20 20 * [*text] ==> [!byte-sequence<16>] interpreted as a UTF-8 string 21 21 * [*bitmap] ==> [!int<16>:[$pxl-width]] [!byte-sequence<8>:[$map]] 22 22 * [*state] ==> 23 23 *: if on the root menu: [`0x00] 24 -*: if on a menu with an ID between [`1]-[`127] and the opaque [$ref] value is [`0] ("null"): the menu number cast to [!int<8>] (e.g. [`0x00 4A] --> [`0x4A]) 25 -*: if on a menu between [`128]-[`383] with a null [$ref] value: [`0x80] [!int<8>:[=mode - 128]] 24 +*: if on a menu with an ID between [`1]~[`127] and the opaque [$ref] value is [`0] ("null"): the menu number cast to [!int<8>] (e.g. [`0x00 4A] --> [`0x4A]) 25 +*: if on a menu between [`128]~[`383] with a null [$ref] value: [`0x80] [!int<8>:[=mode - 128]] 26 26 *: if on a menu greater than [`383] with a null [$ref]: [`0x81] [!int<16>:[$mode]]. this form is also valid if the number is lower than [`383], and can be used where logical simplicity is more important than compact signalling 27 27 *: otherwise: 28 28 *:: let [$ref-len] be the length in bytes of the [$ref] value, maximum 8 (0 is valid, in which case no [$ref] sequence is sent) 29 29 *:: let [$mode-range] be [`0] if [$mode] is between [`0] and [`255], [`1] otherwise 30 -*:: let [$signal-byte] be [`([$ref-len] << 1) | [$mode]-[$range]] 31 -*:: send [!int<8>:[$signal-byte]] [!int<[=8 + 8*mode-range]>:[$mode]] [!int<[$ref-len*8]>:[$ref]] 30 +*:: let [$signal-byte] be [`([$ref-len] << 1) | [$mode-range]] 31 +*:: send [!int<8>:[$signal-byte]] [!int<[`8 + 8*[$mode-range]]>:[$mode]] [!int<[`[$ref-len]*8]>:[$ref]] 32 32 * [*link] ==> [!int<8>:[$role]] [!state:[$target]] 33 33 34 34 ## outline 35 - 36 35 : client connects to server 37 36 : client transmits {m.n con-ack} 38 -: client authenticates by one of the following 39 -:: to authenticate anonymously, client transmits byte [`0x00]. 40 -:: to authenticate by shortname, client transmits byte [`0x01] followed by a [!byte-sequence<8>]. this may be a PSK, a URI, a literal text name, an OID, or anything else depending on what the server is configured to recognize. 41 -:: to authenticate by longname, client transmits byte [`0x01] followed by a [!byte-sequence<16>]. this is identical to the above but allows to longer values. technically these are different forms of the "name" authentication method; the difference is relevant only at the byte-level 42 -:: other authentication methods may be defined later. a server that encounters an unknown authentication method must transmit an error and close the connection, as it cannot know how to interpret any further communications from the client 43 -: server reports authentication status 44 -:: if the authentication failed, xmit {m.n status-fail} and close the connection 45 -:: if the authentication succeeded, xmit {m.n status-ok} 37 +: server responds {m.n status-ok} 38 +: client and server authenticate using the [>nimtas authentication protocol]. for an anonymous connection, this is as simple as the dialogue “C: [`0x00] / S: {m.n status-ok}” 46 39 : client transmits a command 47 40 :: {m.n cmd-get} retrieves a menu. it takes the form [!state] [!action] 48 41 :: {m.n cmd-hint} transmits a hint to the server. it takes the form [!int<8>:[$hint]] [!byte-sequence<16>] 49 42 :: {m.n cmd-meta} requests metadata from the server. it takes the form [!int<16>] 50 43 :: {m.n cmd-end} closes the connection. it takes no arguments 51 44 : server issues [>rep reply] 52 45 : while command was not {m.n cmd-end}, previous two steps repeat 53 46 : peers disconnect 47 + nimtas: file:nimtas.ct 48 + 54 49 55 50 ##rep server replies 56 51 all replies begin with a one-byte status code. 57 52 58 53 ### cmd-get reply 59 -the hint reply code may be: 54 +the get reply code may be: 60 55 * {m.n status-ok}: the request was valid but the current display should not be changed 61 56 * {m.n status-fail}: the request was not valid 62 57 * {m.n status-ignore}: the action did nothing 63 58 * {m.n status-data}: the request was valid and a form is being returned to display. 64 59 65 60 if the reply is {m.n status-data}, it is followed by the header [!byte:[$flags]] [!int<16>:[$widget-count]] 66 61 * [$flags] is a bitmask