First draft version

1 files changed, 26 insertions, 0 deletions

diff --git a/ARCHITECTURE b/ARCHITECTURE
new file mode 100644
index 0000000..617aea1
--- /dev/null
+++ b/ARCHITECTURE
@@ -0,0 +1,26 @@
+API Keys:
+
+paste uses 96 bit API keys which are stored as SHA-256 hashes.
+
+The keys are transmitted as base64 (RFC 4648) encoded Bearer tokens with
+no padding.
+
+The length is long enough to be secure against any and all forms of brute
+force but short enough that the base64 encoding is only 16 characters
+meaning it can be easily typed out.
+
+Coincidentally, 96 is also evenly divisible by 6 so the base64 encoding
+has no padding.
+
+Base64 was chosen as the limited use of symbols makes it easier to type.
+
+Storing the keys as plain SHA-256 is sufficiently secure as:
+- Brute forcing the keys would, as mentioned before, be infeasible.
+- If someone recovers the hash, they would have an easier time brute
+  forcing, but still infeasible with current computing power.
+- There is a timing attack but it would require predictably generating
+  hashes with longer and longer prefixes which is infeasible.
+
+But, to further reduce the chances of a recovered hash being brute
+forced, a KDF with a small number of rounds could be used to seriously
+increase the time required.