Differences

This shows you the differences between two versions of the page.

--- pawsd:protocol [2026/02/09 10:03] – [Verb 1: Fetch service] design note on key length field winter
+++ pawsd:protocol [2026/02/11 18:07] (current) – [Zones, services and records] flags bitfield description winter
@@ Line 61: / Line 61: @@
 The signature is calculated from the concatenation of the index, flags, record count, and records fields (i.e. the entire service in wire format except for the signature itself). The signature algorithm is not given in the service itself but will be specified as part of the service's identifier, such as when requesting it.
+The "flags" bitfield currently only contains one flag, identified by the presence or absence of the least significant bit (1), which, if set, indicates that another service follows this one in the zone (and therefore if unset indicates that this service is the final service in the zone). In future, more flags may be added without incrementing the protocol version unless it is necessary for clients to understand them.
 Records are just a list of tag-value pairs:
@@ Line 108: / Line 110: @@
 </WRAP>
+===== Verb 4096 (0x1000): Start authentication =====
+The client briefly identifies itself using a "client ID", which is an arbitrary byte sequence that needs to uniquely but persistently identify the client. For example, it could be some hash of the concatenation of: the client's implementation name, a random number saved on the client's storage, and some information about the server such as its IP address (to prevent cross-server tracking). The client ID allows the server to keep track of the authentication session across subsequent requests. The client also asks for access to a particular set of scopes.
+Request payload:
+^ Field      ^ Length    ^ Type      ^
+| client ID  | 16 bytes  | [16]u8    |
+| scopes     | ???       | //TODO//  |
+The server then returns either a "challenge set", or an auth token for the given scopes. The response payload therefore is:
+^ Field                ^ Length  ^ Type                  ^
+| completed?           | 1 byte  | boolean               |
+| token or challenges  | varies  | [32]u8 or challenges  |
+If "completed?" is true (1), the "token or challenges" field will be:
+^ Field                              ^ Length    ^ Type                    ^
+| conjunction                        | 1 byte    | enum (0 = or, 1 = and)  |
+| challenge count                    | 1 byte    | u8 (≥ 1)                |
+| challenge<sub>1</sub> ID           | 16 bytes  | [2]u64                  |
+| challenge<sub>1</sub> data length  | 4 bytes   | u32                     |
+| challenge<sub>1</sub> data         | varies    | [_]u8                   |
+| //challenge<sub>2</sub> ID, etc//  |           |                         |
+If the conjunction is "or", the client may choose any one of the contained challenges to solve; if it's "and", the client has to solve all of them. If the challenge count is 1, the conjunction is irrelevant. Consequently the client needs to send its challenge response(s) using the //Continue authentication// verb as follows.
+==== Challenges ====
+The structure of the "challenge data" and "response" fields are defined by each individual challenge. There is a [[challenges|non-exhaustive list of known challenges]].
+===== Verb 4097 (0x1001): Continue authentication =====
+The client sends one or multiple responses to challenges previously given by the server. (Note confusing terminology: in this case the "responses" are responses in the sense of a challenge-response exchange, but they are sent as part of the request payload in the protocol.)
+Request payload:
+^ Field                              ^ Length    ^ Type    ^
+| client ID                          | 16 bytes  | [16]u8  |
+| response count                     | 1 byte    | u8      |
+| challenge<sub>1</sub> ID           | 16 bytes  | [2]u64  |
+| response<sub>1</sub> length        | 4 bytes   | u32     |
+| response<sub>1</sub>               | varies    | [_]u8   |
+| //challenge<sub>2</sub> ID, etc//  |           |         |
+The response payload is identical to the //Start authentication// verb.