From 8444759abdc3c2fd317abe7a7c74054d82fc0225 Mon Sep 17 00:00:00 2001
From: haskal <haskal@awoo.systems>
Date: Sat, 5 Jun 2021 13:36:49 -0400
Subject: [PATCH] update readme

---
 README.md              | 28 +++++++++++++++++++++++++++-
 clocktower/__init__.py |  2 +-
 setup.py               |  2 +-
 3 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index df985f3..cf78f4d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,29 @@
 # clocktower
 
-meow meow meow
+clocktower is a python package implementing efficient strategies for executing adaptive timing side
+channel attacks. the goal is to use statistics to guide public input guesses in order to reveal the
+secret with a given level of statistical significance in a minimum number of rounds. the current
+strategy already significantly outperforms the naive non-adaptive strategy, and thus can be used as
+a framework for mounting attacks
+
+## howto
+
+currently the model is that a correct guess will result in a longer time taken to execute, and all
+incorrect guesses will take the same (lower) time to execute  
+more abstraction is planned for different target models
+
+```
+import clocktower
+
+# default input space: 0-255
+# default significance level: 0.01
+mgr = clocktower.ClocktowerManager()
+
+# when next_guess() returns None, the algoritm has a statistically significant answer
+while (guess := mgr.next_guess()) is not None:
+    # execute the guess and get the result
+    timing_value = run_attack(guess)
+    mgr.update(guess, timing_value)
+
+print(mgr.get_best_guess())
+```
diff --git a/clocktower/__init__.py b/clocktower/__init__.py
index 68d4b74..d0f8c52 100644
--- a/clocktower/__init__.py
+++ b/clocktower/__init__.py
@@ -1,4 +1,4 @@
-from typing import Dict, List, Optional, Tuple
+from typing import Dict, Optional, Tuple
 
 import numpy as np
 # import numpy.typing as npt
diff --git a/setup.py b/setup.py
index 9e8b9b1..87616ff 100644
--- a/setup.py
+++ b/setup.py
@@ -6,7 +6,7 @@ with open("README.md", "r") as f:
 setup(
     name='clocktower',
     version='0.1',
-    description='Sample text',
+    description='optimal adaptive timing side channel attacks',
     long_description=long_description,
     long_description_content_type='text/markdown',
     url='https://awoo.systems',