From d03eefc49aebe452f8564a35cdfca51347c688d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Tue, 15 Mar 2022 16:05:00 +0100
Subject: [PATCH] docs(store-key): Improve the docs a bit

Co-authored-by: Denis Kasak <dkasak@termina.org.uk>
---
 crates/matrix-store-key/README.md  | 18 +++++++++---------
 crates/matrix-store-key/src/lib.rs | 13 ++++++++-----
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/crates/matrix-store-key/README.md b/crates/matrix-store-key/README.md
index e58ee11e4..b311713b2 100644
--- a/crates/matrix-store-key/README.md
+++ b/crates/matrix-store-key/README.md
@@ -38,9 +38,9 @@ fn main() -> anyhow::Result<()> {
 
 # ⚠️ Security Warning: Hazmat!
 
-This crate implements only the low-level block cipher function, and is intended
-for use for implementing higher-level constructions *only*. It is NOT
-intended for direct use in applications.
+This crate only implements the low-level block cipher function, to be used
+*only* as a building block for higher-level constructions. It is NOT intended
+for direct use in applications.
 
 USE AT YOUR OWN RISK!
 
@@ -51,9 +51,9 @@ A `StoreKey` consists of two randomly generated 32 byte-sized slices.
 The first 32 bytes are used to encrypt values. XChaCha20Poly1305 with a random
 nonce is used to encrypt each value. The nonce is saved with the ciphertext.
 
-The second 32 bytes are used as a seed to derive table specific keys that will
-be used to hash data. The data will then be hashed using the blake3 keyed hash
-using the table specific key.
+The second 32 bytes are used as a seed to derive table-specific keys, used in
+keyed hash construction to hash table data. Currently we use blake3 as the
+keyed hash construction.
 
 ```text
                 ┌───────────────────────────────────────┐
@@ -63,11 +63,11 @@ using the table specific key.
                 └───────────────────────────────────────┘
 ```
 
-The `StoreKey` has some Matrix specific assumptions built in which ensure that
+The `StoreKey` has some Matrix-specific assumptions built in, which ensure that
 the limits of the cryptographic primitives are not exceeded. If this crate is
-used for non-Matrix specific data users need to ensure:
+used for non-Matrix data, users need to ensure:
 
-1. That individual values are chunked, otherwise decryption might be succeptible
+1. That individual values are chunked, otherwise decryption might be susceptible
    to a DOS attack.
 2. The `StoreKey` is periodically rotated/rekeyed.
 
diff --git a/crates/matrix-store-key/src/lib.rs b/crates/matrix-store-key/src/lib.rs
index 597daf72a..b496b729d 100644
--- a/crates/matrix-store-key/src/lib.rs
+++ b/crates/matrix-store-key/src/lib.rs
@@ -211,19 +211,22 @@ impl StoreKey {
 
     /// Hash a key before it is inserted into the key/value store.
     ///
+    /// This prevents the key names from leaking to parties which do not have
+    /// the ability to decrypt the key/value store.
+    ///
     /// # Arguments
     ///
     /// * `table_name` - The name of the key/value table this key will be
     /// inserted into. This can also contain additional unique data. It will be
-    /// used to derive a table specific cryptographic key which will be used
+    /// used to derive a table-specific cryptographic key which will be used
     /// in a keyed hash function. This ensures data independence between the
     /// different tables of the key/value store.
     ///
-    /// * `key` - The key that should be hashed before it is inserted into the
-    /// key/value store.
+    /// * `key` - The key to be hashed, prior to insertion into the key/value
+    ///   store.
     ///
-    /// **Note**: a key that is hashed by this method can't be retrieved
-    /// anymore.
+    /// **Note**: This is a one-way transformation; you cannot obtain the
+    /// original key from its hash.
     ///
     /// # Examples
     ///