From 838dba270523812d13270ee29eddb944e03d3644 Mon Sep 17 00:00:00 2001
From: Didactic Drunk <1479616+didactic-drunk@users.noreply.github.com>
Date: Sun, 13 Jun 2021 19:00:53 -0700
Subject: [PATCH] README.md: What? Why?

---
 README.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 59 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f946640..8b8b6f7 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,19 @@
 ![GitHub commits since latest release (by date) for a branch](https://img.shields.io/github/commits-since/didactic-drunk/crypto-secret.cr/latest)
 [![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://didactic-drunk.github.io/crypto-secret.cr/main)
 
-Interface intended to hold sensitive information.
+Secrets hold sensitive information
+
+The Secret interface manages limited time access to the secret and securely erasing the secret when no longer needed.
+
+Secret providers may implement additional protections via:
+* `#noaccess`, `#readonly` or `readwrite`.
+* Using [mprotect]() to control access
+* Encrypting the data when not in use
+* Deriving keys on demand from a HSM
+* Preventing the Secret from entering swap ([mlock]())
+* Preventing the Secret from entering core dumps
+* Other
+
 
 ## Installation
 
@@ -24,11 +36,45 @@ Interface intended to hold sensitive information.
 require "crypto-secret/not"
 
 not_secret = Crypto::Secret::Not.new 32
+not_secret.wipe do
+  not_secret.readonly do |slice|
+    # May only read slice
+  end
+  not_secret.readwrite do |slice|
+    # May read or write to slice
+  end
+end # Secret is erased
 ```
 
+## What is a Secret?
+
+<strike>Secrets are Keys</strike>
+That's complicated and specific to the application.  Some examples:
+
+* Passwords
+* A crypto key is always a Secret.  Except when used for verification (sometimes)
+* A decrypted password vault (but it's not a Key)
+
+Not secrets:
+
+* Digest output.  Except when used for key derivation, then it's a Secret, including the Digest state
+* IO::Memory or writing a file.  Except when the file is a password vault, cryptocurrency wallet, encrypted mail/messages, goat porn, maybe normal porn, sometimes scat porn, occassionally furry, not vanilla porn
+
+## Why?
+
+The Secret interface is designed to handle varied levels of confidentiality with a unified API for cryptography libraries.
+
+There is no one size fits all solution.  Different applications have different security requirements.  Sometimes for the same algorithm.
+
+A master key (kgk) may reside on a HSM and generate subkeys on demand.
+Or for most applications the master key may use best effort protection using a combination of [guard pages, mlock, mprotect].
+Other keys in the same application may handle a high volume of messages where [guard pages, mlock, mprotect] overhead is too high.
+A key verifying a public key signature may not be Secret.
+
+
 ## Implementing a new Secret holding class
 
-**Intended for use by crypto library authors**
+**Only intended for use by crypto library authors**
 
 ```
 class MySecret
@@ -39,18 +85,26 @@ class MySecret
     # optionally mlock
   end
 
-  def to_slice : Bytes
-    # Return a slice
-    # Slice.new pointer, size
+  def to_slice(& : Bytes -> Nil)
+    # yield Slice.new(pointer, size)
+  ensure
+    # optionally reencrypt or signal HSM
+  end
+
+  def bytesize : Int32
+    # return the size
   end
 
   # optionally override [noaccess, readonly, readwrite]
+  # optionally override (almost) any other method with implementation specific version
 end
 
 ```
 
 ## Contributing
 
+**Open a discussion before creating PR's**
+
 1. Fork it (<https://github.com/your-github-user/crypto-secret/fork>)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)