docs: reflect current design

cmd/klefkictl/klefkictl_requests.go

@@ -182,7 +182,7 @@ func newSubmitKeyCommand() *cobra.Command {
 		Args:  cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			machineID := args[0]
-			// TODO(jaredallard): don't expect to be passed
+			// TODO(jaredallard): don't expect to be passed as an arg
 			passphrase := args[1]
 
 			kc, kcclose, err := client.Dial(cmd.Parent().Flag("hostname").Value.String())

docs/DESIGN.md

@@ -29,11 +29,13 @@ disk.
 
 ### Endpoints
 
-- `GetKey() string` - If connected to a client through
-  `SubmitKey`, returns the key, otherwise waits for a period of time
-  then the caller should retry the endpoint (polling).
+- `GetKey() string` - If a client has called `SubmitKey` for this
+  client, returns the key. Otherwise, registers the key request attempt.
+  A client can then call this endpoint again, after a key has been
+  submited to recieve the encrypted key.
 - `ListSessions() []MachineID` - Returns a list of machine IDs waiting
-  for a key to be provided.
+  for a key to be provided, as well as their public keys and last
+  attempt time.
 - `SubmitKey(key []byte, machineID string)` - If a session is present
   for the provided `machineID`, then the key is stored in memory on the
   server side and provided when `GetKey` is next called by the machine.
@@ -49,12 +51,17 @@ disk.
   signature check (public keys are stored on the server side).
   - This technically is vulnerable to replay attacks. However, the
     returned data is encrypted to the key holder. An attacker replaying
-    this would get encrypted data only.
+    this would get encrypted data only. Further mitigations are made by
+    signing the current date.
 
 ### Flow
 
 1. Machine A boots initramfs+kernel
-2. Machine A calls `GetKey()`
+2. Machine A calls `GetKey()`, gets no response
+3. User A calls `SubmitKey` with the provided machineID
+4. a) Server stores the key in memory (encrypted as provided by User A)
+5. Machine A gets encrypted key, decrypts it using private key
+6. Machine A unlocks
 
 ## Machine Registration