diff options
| -rw-r--r-- | protocol.txt | 46 |
1 files changed, 28 insertions, 18 deletions
diff --git a/protocol.txt b/protocol.txt index 7d912df..67317ab 100644 --- a/protocol.txt +++ b/protocol.txt @@ -3,12 +3,20 @@ the two participants, known as the user and the developer. The exact composition of the JSON objects is not described here; see Types.hs for the data types that JSON serialization instances are derived -from. The Activity type is the main message type. +from. -The first message in a debug-me session is sent by the user, and it has -Nothing as its prevActivity. All subsequent messages sent by either the -user or the developer must have a prevActivity that points to the Hash -of a previous message. So a chain of messages is built up. +The Activity type is the main message type. The user sends Activity +Seen messages, and the developer responds with Activity Entered. +There are also Control messages, which can be sent by either +party at any time, and do not affect IO to the console. + +The first message in a debug-me session is a Control sent by the +user, which establishes a session key (see below for details). The second +message is an Activity Seen. + +Activity Seen and Activity Entered messages have a prevActivity, +which points to the Hash of a previous Activity. (And is Nothing for the +first Activity Seen.) So a chain of messages is built up. The exact details about how these objects are hashed is not described here; see Hash.hs for the implementation. Note that the JSON strings are *not* @@ -28,7 +36,8 @@ entering "y" in response to "Display detailed reactor logs?" at the same time that a new "Vent core to atmosphere?" question was being displayed! The debug-me protocol is designed to prevent such conflicts of opinion. -The user only processes a new Activity Entered when either: +The user only processes a new Activity Entered when it meets one of these +requirements: 1. The Activity Entered has as its prevActivity the last Activity (Entered or Seen) that the user processed. @@ -44,9 +53,9 @@ When an Activity Entered does not meet these rules, the user sends it back in a Rejected message to let the developer know the input was not allowed. -The developer also checks the prevActivity of messages it receives -from the user, to make sure that it's receiving a valid chain of messages. -The developer accepts a new Activity Seen when either: +The developer also checks the prevActivity of Activity Seen messages it +receives from the user, to make sure that it's receiving a valid chain of +messages. The developer accepts a new Activity Seen when either: 1. The Activity Seen has a prevActivity that points to the last Activity Seen that the developer accepted. @@ -55,17 +64,18 @@ The developer accepts a new Activity Seen when either: that the developer accepted. At the start of the debug-me session, Ed25519 session key pairs are -generated by both the user and the developer. The very first -message in the protocol is the user sending their session pubic key. +generated by both the user and the developer. The first message +in the protocol is the user sending their session pubic key +in a Control message containing a SessionKey. -Before the developer can do anything, they must send a message with their -session key, and it must be accepted by the user. The developer must have -a gpg private key, which is used to sign their session key. +Before the developer can enter anything, they must send a SessionKey message +with their session key, and it must be accepted by the user. The developer +must have a gpg private key, which is used to sign their session key. (The user may have a gpg private key, which will sign their session key if available, but this is optional.) The user will reject session keys that are not signed by a gpg key or when the gpg key is not one they -trust. The user sends a SessionKeyAccepted message to indicate if they -accepted the developer's key or not. +trust. The user sends a SessionKeyAccepted/SessionKeyRejected message +to indicate if they accepted the developer's key or not. Note that there could be multiple developers, in which case each will send their session key before being able to do anything except observe @@ -73,5 +83,5 @@ the debug-me session. Each message in the debug-me session is signed by the party that sends it, using their session key. The hash of a message includes its signature, so -the activity chain proves who sent a message, and who sent the message its -prevActivity points to, etc. +the activity chain proves who sent a message, and who sent the message +before it, etc. |