From 973e1ecb4ba1599e2dacbd3dbf0ff387b0ea6f2c Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Thu, 17 Jun 2021 03:16:34 -0700
Subject: [PATCH] Add Crypto::Secret::Key & Crypto::Secret::Large

---
 README.md                   |  3 +++
 spec/crypto_secret_spec.cr  |  5 ++++-
 src/crypto-secret/key.cr    | 12 ++++++++++++
 src/crypto-secret/large.cr  | 13 +++++++++++++
 src/crypto-secret/not.cr    |  4 ++++
 src/crypto-secret/secret.cr |  7 +++++++
 6 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 src/crypto-secret/key.cr
 create mode 100644 src/crypto-secret/large.cr

diff --git a/README.md b/README.md
index 4267c62..66b34d8 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,9 @@ Secrets hold sensitive information
 
 The Secret interface manages limited time access to a secret and securely erases the secret when no longer needed.
 
+Multiple `Secret` classes exist.  Most of the time you shouldn't need to change the `Secret` type - the cryptographic library should have sane defaults.
+If you have a high security or high performance application see [which secret type should I choose?]()
+
 Secret providers may implement additional protections via:
 * `#noaccess`, `#readonly` or `#readwrite`
 * Using [mprotect]() to control access
diff --git a/spec/crypto_secret_spec.cr b/spec/crypto_secret_spec.cr
index a2b7fc8..7a58ecf 100644
--- a/spec/crypto_secret_spec.cr
+++ b/spec/crypto_secret_spec.cr
@@ -1,7 +1,10 @@
 require "./spec_helper"
 require "../src/crypto-secret/test"
 require "../src/crypto-secret/not"
-require "../src/crypto-secret/bidet"
+require "../src/crypto-secret/large"
+require "../src/crypto-secret/key"
 
 test_secret_class Crypto::Secret::Not
 test_secret_class Crypto::Secret::Bidet
+test_secret_class Crypto::Secret::Large
+test_secret_class Crypto::Secret::Key
diff --git a/src/crypto-secret/key.cr b/src/crypto-secret/key.cr
new file mode 100644
index 0000000..870fe85
--- /dev/null
+++ b/src/crypto-secret/key.cr
@@ -0,0 +1,12 @@
+require "./bidet"
+
+module Crypto::Secret
+  # Use this class for holding small amounts of sensitive data such as encryption keys
+  #
+  # Underlying implentation subject to change
+  #
+  # TODO: mlock
+  # TODO: mprotect
+  class Key < Bidet
+  end
+end
diff --git a/src/crypto-secret/large.cr b/src/crypto-secret/large.cr
new file mode 100644
index 0000000..f92144d
--- /dev/null
+++ b/src/crypto-secret/large.cr
@@ -0,0 +1,13 @@
+require "./bidet"
+
+module Crypto::Secret
+  # Use this class as a default when holding possibly large amounts of data that may stress mlock limits
+  #
+  # Suitable uses: holding decrypted data
+  #
+  # no mlock
+  #
+  # Implementation subject to change
+  class Large < Bidet
+  end
+end
diff --git a/src/crypto-secret/not.cr b/src/crypto-secret/not.cr
index d5c8ee3..e770913 100644
--- a/src/crypto-secret/not.cr
+++ b/src/crypto-secret/not.cr
@@ -3,6 +3,10 @@ require "./stateless"
 module Crypto::Secret
   # A not very secret `Secret`, but fast
   #
+  # Suitable uses:
+  # * Holding decrypted data that is NOT secret
+  # * Verification keys that are public (use with care)
+  #
   # * 0 overhead
   # * Not locked in memory
   # * Not access protected
diff --git a/src/crypto-secret/secret.cr b/src/crypto-secret/secret.cr
index 8fe9bd4..594da2c 100644
--- a/src/crypto-secret/secret.cr
+++ b/src/crypto-secret/secret.cr
@@ -6,6 +6,13 @@ require "./class_methods"
 # **Only for direct use by cryptographic library authors**
 #
 # For all other applications use a preexisting class that includes `Crypto::Secret`
+#
+# # 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::Not - Won't get wiped but 0 overhead.  Only use when you're sure the data isn't secret
+#
+# Other shards may provide additional `Secret` types (sodium.cr)
 @[Experimental]
 module Crypto::Secret
   class Error < Exception