Add Crypto::Secret::Key & Crypto::Secret::Large

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

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

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

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

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

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