Additional documentation; copy results

marvin-toolkit/Cargo.toml

@@ -9,5 +9,5 @@ clap = { version = "4", features = ["derive"] }
 rsa = "0.9"
 
 [patch.crates-io]
-rsa = { git = "https://github.com/xuganyu96/RSA", branch = "const-crypto-biguint" }
+rsa = { git = "https://github.com/RustCrypto/RSA", branch = "const-crypto-biguint" }
 crypto-bigint = { git = "https://github.com/RustCrypto/crypto-bigint", branch = "master" }

marvin-toolkit/README.md

@@ -1,10 +1,56 @@
 # Marvin tool-kit integration
 This document describes the procedure for replicating the analysis for the Marvin attack. This analysis is best done on a container for reproducibility.
 
+**TL;DR**:
 ```bash
 docker build -t marvin:latest .
-docker run --rm \
+
+# Compile RustCrypto/RSA 0.9 then Run the analysis using RSA 2048 and with 
+# 100000 repeat
+docker run -d --rm \
+    --name marvin \
+    marvin:latest
+
+# Use "docker logs -f marvin" to read live output
+```
+
+## Adjusting analysis parameters
+For more help on the options pass in the `-h` flag in the `docker run` command:
+
+```
+docker run ... marvin:latest -h
+```
+
+There are two main parameters of the analysis: RSA key size and the number of repetitions during ciphertext generation.
+
+RSA key size is specified through `-s <1024|2048|4096>`. The number of repetition is specified through `-n <num>`. A larger repetition number will increase the confidence of the analysis, but will make the analysis take longer. The default key size is 2048 and the default repetition count is 100,000.
+
+```bash
+# Run analysis for RSA 4096 with 1 million repetition
+docker run -d --rm \
     --name marvin \
-    -v /home/ec2-user/RSA/marvin-toolkit/Cargo.toml:/home/rustcrypto/marvin-toolkit/example/rust-crypto/Cargo.toml \
+    marvin:latest -s 4096 -n 1000000
+```
+
+## Extracting keys, ciphertexts, and analysis results (WIP)
+After the analysis is done, the generate keys, ciphertexts, and the analysis outputs are all copied into the directory `/home/rustcrypto/marvin-toolkit/outputs`. To extract and preserve these artifacts, mount a volume into this directory, such as using a bind mount:
+
+```bash
+HOST_OUTPUT_DIR="..."
+mkdir -p ${HOST_OUTPUT_DIR}
+chmod a+rw ${HOST_OUTPUT_DIR}
+
+# Mount
+docker run -d --rm --name "marvin" \
+    -v ${HOST_OUTPUT_DIR}:/home/rustcrypto/marvin-toolkit/outputs \
     marvin:latest
 ```
+
+## Compile test harness with custom `Cargo.toml`
+The test harness is compiled at container run-time, so a custom `Cargo.toml` can be passed into the container at runtime to compile the test harness using custom versions of `RustCrypto/RSA` and/or `RustCrypto/crypto-bigint`:
+
+```bash
+docker run -d --rm --name "marvin" \
+    -v /host/path/Cargo.toml:/home/rustcrypto/marvin-toolkit/example/rust-crypto/Cargo.toml \
+    marvin:latest
+```

marvin-toolkit/entrypoint.sh

@@ -124,4 +124,10 @@ PYTHONPATH=tlsfuzzer marvin-venv/bin/python3 tlsfuzzer/tlsfuzzer/extract.py \
 -o rsa${size}_repeat/ \
 --clock-frequency 1000
 PYTHONPATH=tlsfuzzer marvin-venv/bin/python3 tlsfuzzer/tlsfuzzer/analysis.py \
--o rsa${size}_repeat/ --verbose
+-o rsa${size}_repeat/ --verbose
+
+# Copy over the keys and the results, if the results directory exists
+if [[ -d ~/marvin-toolkit/outputs ]]; then
+  copy -r rsa${size} ~/marvin-toolkit/outputs/keys
+  copy -r rsa${size}_repeat ~/marvin-toolkit/outputs/results
+fi