final tweaks to documentations, added intro and final presentation slidesHEADmaster

1 files changed, 23 insertions, 21 deletions

diff --git a/documentation/README.md b/documentation/README.md
index f507ecc..b664fc0 100644
--- a/documentation/README.md
+++ b/documentation/README.md
@@ -19,20 +19,21 @@ allows users to search for public models via model name. Registered user's
 uploads are saved to a private directory. This (theoretically) prevents other
 users from accessing their files.
 
-The service is hosted with socat, one process per client.
+The service is hosted with ncat, one process per client.
 
-Models are periodically cleaned up using files *last modified* date.
+Models are periodically checked for removal via their *last modified* date
+and tracked using index files.
 
 For both flagstores the **service returns the flag in plaintext**, which is
-vulnerable to detection by network filters and can lead to easy replication
-of exploits.
+vulnerable to detection by network filters. However, multiple sessions can be
+used to somewhat obfuscate the exploit mechanism.
 
 
 RCE Countermeasures
 ===================
 
 It is good practice to take preventitive measures against unintentional RCE,
-which can be used to cause havoc on vulnboxes and make services go mumble.
+which can be used to wreak havoc on vulnboxes and make services go mumble.
 
 For this reason, additional security features are enabled via compilation flags:
 
@@ -98,19 +99,20 @@ freadstr(FILE *f, char **dst)
 
 To determine whether the end-of-file was reached, the return value of `int
 fgetc(FILE *f)` is compared to the constant `EOF`, which has a value of `-1`.
-The problem lies in the fact, that this comparison is done following a demotion
-of the return value to `char` through the assignment and a subsequent promotion
-to `int`, which results in an arithmetic extension. As a result, reading the
-value char `0xff` would promote it to `0xffffffff` with a value of `-1`,
-preventing the function from reading the complete string.
+The problem lies in the fact that this comparison is done following a demotion
+of the return value to `char` through the assignment, and a subsequent promotion
+to `int`, which results in an arithmetic extension. As a result, a char with
+unsigned value `255` is cast to char (`0xff`) and then promoted to `-1`
+(`0xffffffff`). Since this value corresponds with `EOF`, it prevents the
+function from reading the complete string.
 
 This allows an attacker to cleverly truncate a string before it has ended to
 manipulate the content of strings which follow it. In this case, the model name
 is saved before the model hash in the information file. By adding a `0xff` to
-the end of our uploaded model's name, the model hash is read as an empty string
-following a `search` of the file's contents. Since any following `search` will use
-the previously loaded models hash to find the file via prefix match, any files
-uploaded by unregistered users may be accessed by a user.
+our uploaded model's name, we can control what value is loaded from the file for
+the model's hash. Since a `search last` will use the previously loaded models hash
+to find the file via prefix match, any files uploaded by unregistered users can
+be accessed by choosing this value accordingly.
 
 The flag is saved in the model name.
 
@@ -119,12 +121,12 @@ Exploiting
 ----------
 
 1. Open a session
-2. Run `upload` to upload an STL file and specify a model name ending in `0xff`
+2. Run `upload` to upload an STL file and specify a model name ending in
+	`0xff<target-hash-prefix>`
 3. Open a new session
-4. Run `search` with the same model name from **step 1** to load the parsed
-	information from the `info` file and trigger the truncation
-5. Run `search last` to use the cached hash which should be empty,
-	allowing you to accesss any files uploaded by unregistered users
+4. Run `search` with the same model name from **step 1** to load the malicious
+	model hash value
+5. Run `search last` to use the cached hash prefix to access the target file
 
 See the `exploit` method of the checker in `checker/src/checker.py`
 for an implementation in python.
@@ -208,12 +210,12 @@ previously, to log in as them and query information about their files.
 
 To calculate the preimage we repeatedly choose a seed for srand. For
 each seed, we XOR the values encoded in the hex-encoded hash with
-calls to rand(). If after generating each character the sum of the
+calls to `rand()`. If after generating each character the sum of the
 generated values is less than the seed we used, restart. Otherwise,
 we append some characters to make the sum of the input characters
 match the seed, such that the seed for srand mhash uses matches the
 one we chose. The actual value of these 'extra' chars is irrelevant,
-since mhash only processes the first 20 chars anyways.
+since mhash only processes the first 20 chars.
 
 See `checker/src/revhash/main.c` for an example implementation in C.