tweak docs

documentation/README.md

@@ -8,13 +8,11 @@
 
 # YVM
 
-## Service Features
-
 This service offers two distinct features:
 The user can either upload and run Java bytecode or can store and retrieve
 notes via the YNotes app.
 
-## YVM Architecture
+## Architecture
 
 The core of the service is the _yvm_, a
 toy-[JVM](https://en.wikipedia.org/wiki/Java_virtual_machine).
@@ -44,9 +42,11 @@ The PHP code then invokes the `yvm`, which interprets Java bytecode.
 ```
 
 Depending on the used feature, the `yvm` either interprets the user-supplied
-class file or the `Notes` class that implements the _YNotes_ app.
+class file or the `Notes` class[^Notes] that implements the _YNotes_ app.
+
+[^Notes]: c.f. `/service/Notes.java`
 
-### YVM features
+### YVM Capabilities
 
 The `yvm` supports:
 
@@ -60,9 +60,9 @@ The `yvm` supports:
 - Some more native methods to allow the `Notes` class to do I/O.
 
 It does neither support `long`, `float` and `double`, nor instantiating objects
-via `new`[^1], nor invoking non-static methods.
+via `new`[^new], nor invoking non-static methods, nor inheritance.
 
-[^1]: Note that arrays differ in this case from Objects, as they are
+[^new]: Note that arrays differ in this case from Objects, as they are
   created by the supported `newarray` and `anewarray` instructions as opposed
   to the unsupported `new` instruction.
 
@@ -71,20 +71,22 @@ via `new`[^1], nor invoking non-static methods.
 #### Run Code
 
 1. The user uploads a Java [class
-   file](https://docs.oracle.com/javase/specs/jvms/se20/html/jvms-4.html) as
-   obtained by compiling Java code with `javac` via the web form.
+   file](https://docs.oracle.com/javase/specs/jvms/se20/html/jvms-4.html)[^compile]
+   via the web form.
 1. The PHP script saves the file into the `classes/` folder and invokes the
    `yvm` to run it.
 1. The `yvm` interprets the code. If it encounters a reference to another class
-   `$CLASS`, it tries to load the classfile `classes/$class.class`.
+   `$CLASS`, it tries to load the classfile `classes/$CLASS.class`.
 1. The PHP script collects the yvm's exit code, `stdout` and `stderr` and
    displays this output back to the user.
    It also generates a `replay_id` to allow the re-execution of the uploaded
    class file.
 
+[^compile]: As obtained by compiling Java code with `javac`
+
 #### YNotes
 
-Note that the user interacts with the HTML/PHP which invokes `yvm` which
+Note that the user interacts with the HTML/PHP code which invokes `yvm` which
 interprets the `Notes.class`, that is stored in `classes/`.
 
 1. The user opens the YNotes Subpage.
@@ -94,9 +96,9 @@ interprets the `Notes.class`, that is stored in `classes/`.
         current time in `notes/`.
     1. The name of the newly created directory is set as a cookie with the key
        `token` to identify the user.
-1. The `token` cookie is read and `Notes` with arguments `l` (for "list) and
-   `$token` (value of the token).
-    1. `Notes` prints the content of the directory `$token`.
+1. The `token` cookie is read and `Notes` is run with arguments `l` (for
+   "list") and `$token` (value of the token).
+    1. `Notes` lists the content of the directory `$token`.
     1. The output is displayed back to the user as a list of notes.
 1. If the user creates a note via the web form, `Notes` is run with arguments
    `a` (for "add"), `$token`, `$name` (of note) and `$content` (of note).
@@ -193,5 +195,8 @@ Thus, an attacker can create a class `Foo` that prints the private `secret_...`
 fields of the class containing the flag, whose name is known from the attack
 info.
 
+Note that the `yvm` crashes when calling the `main(String[] args)` method of
+another class, so this attack vector can be ruled out.
+
 The vuln is fixed by raising an error when a private field is accessed from a
 different class.