From 321db6f39732d7d7b287ef1f6af234249cf3e4b0 Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Sun, 22 May 2022 18:27:59 -0700
Subject: [PATCH] Documentation

---
 README.md                   | 30 +++++++++++++++++++++++-------
 src/crypto-secret/secret.cr |  5 +++--
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index bb69d03..f596fa9 100644
--- a/README.md
+++ b/README.md
@@ -18,16 +18,14 @@ If you have a high security or high performance application see [which secret ty
 * Leaking data in to logs by overriding `inspect`
 * Wiping memory when the secret is no longer in use
 
-Each implementation may add additional protections
-
-* `Crypto::Secret::Key` - May use mlock, mprotect and canaries in future versions
-* `Crypto::Secret::Large` - May use mprotect in future versions
+### Provided secret classes
+* `Crypto::Secret::Guarded` - Guard pages, mprotect, doesn't appear in core dumps (os dependent)
+* `Crypto::Secret::Bidet` - Wipe only.  Low overhead.
 * `Crypto::Secret::Not` - It's not secret.  Doesn't wipe and no additional protection.
-
+* `Crypto::Secret::Todo` - Uses mlock, mprotect and canaries in future versions
 
 Secret providers may implement additional protections via:
-* `#noaccess`, `#readonly` or `#readwrite`
-* Using [mprotect]() to control access
+* `#noaccess`, `#readonly` or `#readwrite` via `mprotect`
 * Encrypting the data when not in use
 * Deriving keys on demand from a HSM
 * Preventing the Secret from entering swap ([mlock]())
@@ -95,6 +93,24 @@ secret = Crypto::Secret::Bidet.new size_in_bytes
 secret.move_from slice
 ```
 
+### Optionally change the security level
+
+The default should be sufficient for most applications.  Do not change unless you have special needs.
+
+Password managers or cryptocurrency wallets may prefer :strong or :paranoid.
+
+Blockchain verifiers or apps that only handle high volume public info may prefer :lax.
+
+```crystal
+# Choose one
+Crypto::Secret::Config.setup :paranoid
+Crypto::Secret::Config.setup :strong
+#Crypto::Secret::Config.setup :default # automatic
+Crypto::Secret::Config.setup :lax
+```
+
+See [#setup](https://didactic-drunk.github.io/crypto-secret.cr/main/Crypto/Secret/Config.html) for further information.
+
 ## What is a Secret?
 
 <strike>Secrets are Keys</strike>
diff --git a/src/crypto-secret/secret.cr b/src/crypto-secret/secret.cr
index d6e6993..493a136 100644
--- a/src/crypto-secret/secret.cr
+++ b/src/crypto-secret/secret.cr
@@ -4,8 +4,9 @@ require "./class_methods"
 # Interface to hold sensitive information (often cryptographic keys)
 #
 # ## Which class should I use?
-# * `Crypto::Secret::Key` - Use with small (<= 4096 bytes) keys
-# * `Crypto::Secret::Large` - Use for decrypted data that may stress mlock limits
+# * `Crypto::Secret::Todo` - Use with small (<= 4096 bytes) keys
+# * `Crypto::Secret::Guarded` - Use for decrypted data that may stress mlock limits
+# * `Crypto::Secret::Bidet` - Wipe only with no other protection.  General use and fast.
 # * `Crypto::Secret::Not` - Only use when you're sure the data isn't secret.  0 overhead.  No wiping.
 #
 # Other shards may provide additional `Secret` types ([sodium.cr](https://github.com/didactic-drunk/sodium.cr))