From 9b803f9f171d9374da5e256082f1a468cc7664aa Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Tue, 17 Sep 2019 07:51:05 -0700
Subject: [PATCH] Document thread safety.

---
 README.md        |  3 +++
 THREAD_SAFETY.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 THREAD_SAFETY.md

diff --git a/README.md b/README.md
index f03c3d0..4f051a8 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,9 @@ Crystal bindings for the [libsodium API](https://libsodium.gitbook.io/doc/)
   - [x] All SecretKey's held in libsodium guarded memory.
   - [x] No heap allocations after #initialize when possible.
   - [x] Fast.  Benchmarks available in `benchmarks`.
+  - [x] [Most classes are safe to share between threads.](THREAD_SAFETY.md)
+    - [x] Tested with real crystal threads and will continue to work when crystal officially supports threading.
+  - [x] Most classes are safe to share between threads.  Even
   - [ ] Controlled memory wiping (by calling `.close`)
 
 ☑ Indicate specs are compared against test vectors from another source.
diff --git a/THREAD_SAFETY.md b/THREAD_SAFETY.md
new file mode 100644
index 0000000..d8087cf
--- /dev/null
+++ b/THREAD_SAFETY.md
@@ -0,0 +1,36 @@
+### Tested and provably thread safe.
+
+* Sodium::CryptoBox::*
+* Sodium::Cipher::Aead::XChaCha20Poly1305Ietf 
+* Sodium::SecretBox
+* Sodium::Sign::*
+
+Notes:
+* Only uses stack allocation.  Keys are stored in readonly memory.
+
+
+### Thread safe when hashing, deriving or creating keys **after** setting parameters.
+
+* Sodium::Password::Hash
+* Sodium::Password::Key
+* Sodium::Password::Key::Create
+
+Notes:
+* Don't change parameters between threads without a `Mutex`.
+
+### Keeps state.  
+* Sodium::Cipher::Chalsa subclasses.
+* Sodium::Cipher::SecretStream
+* Sodium::Digest::Blake2b
+* Sodium::Kdf
+
+Notes:
+* Use one instance per thread or wrap in a `Mutex`.
+
+### Not thread safe.  
+* Sodium::Nonce
+
+Notes:
+* Use `Nonce.random` with multiple threads or let the API provide the nonce's for you.
+* #increment isn't safe, not even when wrapped in a mutex unless you also wrap #encrypt/#decrypt within
+the same #synchronize call.