From 2172ea27b8baf9d4dc2c61bbdb01b2fd83ccf9e9 Mon Sep 17 00:00:00 2001
From: Peter Taoussanis <peter@taoensso.com>
Date: Wed, 6 Mar 2024 11:13:17 +0100
Subject: [PATCH] [nop] Update README

---
 README.md    | 58 ++++++++++++++++++++++++++++++++++++++++++++--------
 examples.clj | 38 ++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 4653a31..cae599d 100644
--- a/README.md
+++ b/README.md
@@ -23,24 +23,64 @@ See [here][GitHub releases] for earlier releases.
 ## Why Tempel?
 
 - **Easy-to-use, high-level API** focused on [common tasks](../../wiki/2-Examples) like logins, encryption, signing, etc.
-- **Reasonable defaults** including choice of algorithms and work factors
-- **Future-proof data formats** with auto-updated algorithms and work factors over time
-- Support for [⧉ symmetric](https://en.wikipedia.org/wiki/Symmetric-key_algorithm), [⧉ asymmetric](https://en.wikipedia.org/wiki/Public-key_cryptography) (public-key), and [⧉ end-to-end](https://en.wikipedia.org/wiki/End-to-end_encryption) (E2EE) encryption
-- Automatic [⧉ scrypt](https://en.wikipedia.org/wiki/Scrypt) and [⧉ pbkdf2](https://en.wikipedia.org/wiki/PBKDF2) support for easy **password-based key stretching**
+- **Reasonable defaults** including choice of algorithms and work factors.
+- **Future-proof data formats** with auto-updated algorithms and work factors over time.
+- Support for [⧉ symmetric](https://en.wikipedia.org/wiki/Symmetric-key_algorithm), [⧉ asymmetric](https://en.wikipedia.org/wiki/Public-key_cryptography) (public-key), and [⧉ end-to-end](https://en.wikipedia.org/wiki/End-to-end_encryption) (E2EE) encryption.
+- Automatic [⧉ scrypt](https://en.wikipedia.org/wiki/Scrypt) and [⧉ pbkdf2](https://en.wikipedia.org/wiki/PBKDF2) support for easy **password-based key stretching**.
 - Simple **key management API** for password resets, key rotations, etc.
-- Beginner-oriented [documentation](#documentation) and docstrings
-- **Comprehensive test suite** with >60k unit tests
+- Extensive **beginner-oriented** [documentation](#documentation), docstrings, examples, etc.
+- **Comprehensive test suite** with >60k unit tests.
 
-Note that Tempel is [not intended](../../wiki/3-Faq#can-i-decrypt-tempel-data-with-other-tools) for interop with other cryptographic tools/APIs.
+Note that Tempel is [not intended](../../wiki/3-Faq#can-i-decrypt-tempel-data-with-other-tools) for interop with other cryptographic tools/APIs!
 
 ## Video demo
 
-See for  intro and usage:
+See for intro and usage:
 
 <a href="https://www.youtube.com/watch?v=sULZVFhR848" target="_blank">
- <img src="https://img.youtube.com/vi/sULZVFhR848/maxresdefault.jpg" alt="Tempel demo video" width="640" border="0" />
+ <img src="https://img.youtube.com/vi/sULZVFhR848/maxresdefault.jpg" alt="Tempel demo video" width="480" border="0" />
 </a>
 
+## Quick example
+
+```clojure
+(require
+  '[taoensso.tempel :as tempel]
+  '[taoensso.nippy  :as nippy])
+
+;; Create a new private `KeyChain`:
+(def my-keychain! (tempel/keychain))
+;; => {:n-sym 1, :n-prv 2, :n-pub 2, :secret? true}
+
+;; Use our `KeyChain` to encrypt some data:
+(def my-encrypted-data
+  (tempel/encrypt-with-symmetric-key
+    (nippy/freeze "My secret data")
+    my-keychain!)) ; => Encrypted bytes
+
+;; Get back the original unencrypted data:
+(nippy/thaw
+  (tempel/decrypt-with-symmetric-key
+    my-encrypted-data my-keychain!)) ; => "My secret data"
+
+;; It's safe to store encrypted `KeyChain`s:
+(def my-encrypted-keychain
+  (tempel/encrypt-keychain my-keychain!
+    {:password "My password"})) ; => Encrypted bytes
+
+;; Get back the original unencrypted `KeyChain`:
+(= my-keychain!
+  (tempel/decrypt-keychain my-encrypted-keychain
+    {:password "My password"})) ; => true
+
+;; `KeyChain`s also support:
+;;   - `encrypt-with-1-keypair`
+;;   - `encrypt-with-2-keypairs`
+;;   - `sign`
+
+;; See docstrings and/or wiki for more info!
+```
+
 ## Documentation
 
 - [Wiki][GitHub wiki] (getting started, usage, etc.)
diff --git a/examples.clj b/examples.clj
index 56bb4b6..e345f16 100644
--- a/examples.clj
+++ b/examples.clj
@@ -6,6 +6,44 @@
 
 (comment (remove-ns 'examples))
 
+;;;; README quick example
+
+(require
+  '[taoensso.tempel :as tempel]
+  '[taoensso.nippy  :as nippy])
+
+;; Create a new private `KeyChain`:
+(def my-keychain! (tempel/keychain))
+;; => {:n-sym 1, :n-prv 2, :n-pub 2, :secret? true}
+
+;; Use our `KeyChain` to encrypt some data:
+(def my-encrypted-data
+  (tempel/encrypt-with-symmetric-key
+    (nippy/freeze "My secret data")
+    my-keychain!)) ; => Encrypted bytes
+
+;; Get back the original unencrypted data:
+(nippy/thaw
+  (tempel/decrypt-with-symmetric-key
+    my-encrypted-data my-keychain!)) ; => "My secret data"
+
+;; It's safe to store encrypted `KeyChain`s:
+(def my-encrypted-keychain
+  (tempel/encrypt-keychain my-keychain!
+    {:password "My password"})) ; => Encrypted bytes
+
+;; Get back the original unencrypted `KeyChain`:
+(= my-keychain!
+  (tempel/decrypt-keychain my-encrypted-keychain
+    {:password "My password"})) ; => true
+
+;; `KeyChain`s also support:
+;;   - `encrypt-with-1-keypair`
+;;   - `encrypt-with-2-keypairs`
+;;   - `sign`
+
+;; See docstrings and/or wiki for more info!
+
 ;;;; Basic `KeyChain` usage
 
 ;; Let's create a new `KeyChain` object for our user Alice.