Differences

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

--- pawsd:protocol [2026/02/07 19:54] – created winter
+++ pawsd:protocol [2026/02/11 18:07] (current) – [Zones, services and records] flags bitfield description winter
@@ Line 6: / Line 6: @@
-The PawSD protocol is designed around a simple request-response architecture that allows it to work over a variety of underlying transports. All a transport has to provide is a way for a client to send some bytes to a server and for the server to send some bytes back in response.
+The PawSD protocol is designed around a simple request-response architecture that allows it to work over a variety of underlying [[transports]]. All a transport has to provide is a way for a client to send some bytes to a server and for the server to send some bytes back in response. It is imperative to choose transports that provide some form of data integrity, i.e. preventing malicious third parties from modifying data in-transit between the client and server.
 Unless otherwise specified, the protocol uses big-endian byte and bit order, and no padding.
@@ 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 96: / Line 98: @@
 | public key        | varies  | [_]u8 |
 | service index     | 2 bytes | u16   |
+Design note: although the length of the public key is implicitly given by the key type field (e.g. an ed25519 key will always be 32 bytes long), we still explicitly state its length, so that implementations that don't support a given key type can still parse the request properly, even if just to show a more useful error message.
 Response payload:
@@ Line 106: / 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.