From 10cf3cf11a596f7d7345c57c7c5ab8669b78c078 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Mon, 5 Feb 2024 09:55:18 +0100 Subject: [PATCH] [doc] Doc improvements --- README.md | 8 +++-- wiki/1-Getting-started.md | 71 ++++++++++++++++++++++++++++++--------- wiki/2-Examples.md | 27 ++------------- wiki/3-FAQ.md | 2 +- 4 files changed, 63 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index d688ea0..d86914b 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ ### Data security framework for Clojure -**Tempel** is a lightweight encryption framework that wraps the JVM's native crypto facilities to provide a **high-level Clojure API** that is: idiomatic, simple, and **easy-to-use** even for non-experts. +**Tempel** is a lightweight encryption *framework* that wraps the JVM's native crypto facilities to provide a **particularly high-level Clojure API** for easily protecting your users' data. -It incorporates **best practices and reasonable defaults** to help simplify many common data security needs. +More than another collection of crypto utils, Tempel offers a **coherent and opinionated API for secure data management** and is focused on helping you with the [toughest parts](../../wiki/1-Getting-started#challenges) of actually **using encryption in practice**. + +Its [tiny API](../../wiki/1-Getting-started#api-overview) and focus on **smart keychains** helps shield you from unnecessary and error-prone complexity, greatly simplifying the most common data security needs. ## Latest release/s @@ -33,7 +35,7 @@ Note that Tempel is [not intended](../../wiki/3-Faq#can-i-decrypt-tempel-data-wi ## Roadmap -Tempel has a fixed scope, and is **fully complete**. I'm happy with its design and implementation, and believe it meets all its objectives in its current form. I'm not anticipating significant changes. +Tempel has a **fixed scope**, and is **fully complete**. I'm happy with its design and implementation, and believe it meets all its objectives in its current form. I'm not anticipating significant changes. Still, given the sensitivity of the problem domain, I plan to approach Tempel's official stable release as a phased rollout to allow time for feedback before locking things down: diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index f5897a1..da29701 100644 --- a/wiki/1-Getting-started.md +++ b/wiki/1-Getting-started.md @@ -61,7 +61,7 @@ There's broadly two kinds of encryption to be aware of: 1. [⧉ Symmetric encryption](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) is the easiest to understand and is just like using a password. The *same* secret "**symmetric key**" will be used for both encryption *and* decryption (hence the term "symmetric"). The most common symmetric algorithm is [⧉ AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard). -2. [⧉ Asymmetric encryption](https://en.wikipedia.org/wiki/Public-key_cryptography) (or "public-key" encryption) is more complex, but also supports a wider range of situations. Asymmetric encryption uses "key pairs". A **key pair** consists of two *different but related* keys (hence the term "asymmetric"): one secret "**private key**", and one related "**public key**" that's generally safe to share (i.e. not secret). Some common asymmetric algorithms are [⧉ RSA](https://en.wikipedia.org/wiki/RSA_(algorithm)) and [⧉ Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange). +2. [⧉ Asymmetric encryption](https://en.wikipedia.org/wiki/Public-key_cryptography) (or "public-key" encryption) is more complex, but also supports a wider range of situations. Asymmetric encryption uses "keypairs". A **keypair** consists of two *different but related* keys (hence the term "asymmetric"): one secret "**private key**", and one related "**public key**" that's generally safe to share (i.e. not secret). Some common asymmetric algorithms are [⧉ RSA](https://en.wikipedia.org/wiki/RSA_(algorithm)) and [⧉ Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange). In many cases, asymmetric encryption schemes will also use symmetric encryption. These "**hybrid schemes**" will generally use asymmetric techniques to safely exchange a **symmetric key** between parties. Further communications can then safely be done via symmetric encryption (which is usually simpler and faster). @@ -71,18 +71,20 @@ Working with encryption can be tough. Some of the most stressful and error-prone - Understanding **what keys you'll need** (algorithms, parameters, etc.). - Understanding how **the various algorithms/schemes fit together** (when and how to use hybrid schemes, etc.). -- **Managing keys** (keeping algorithms and parameters up-to-date, rotating keys, etc.). -- Doing all the above without introducing vulnerabilities, and without being dragged into a rat's nest of complexity irrelevant to your application. +- **Maintaining best-practices over time** (e.g. auto migrating from compromised algorithms, auto incrementing work factors, etc.). +- **Key management** (key rotation, password resets, admin backups, etc.). -Tempel was designed to try help with each of these. +Many of these can be **tough to get right** - needing non-trivial understanding, experience, and effort. And getting even one thing wrong can mean **compromised or completely inaccessible data**. + +Tempel was designed to try help with each of these, letting you **focus on your application** - not on the rat's nest of becoming a security expert. ## Keychains As mentioned in the [quick intro](#quick-intro), encryption means **keys**. You'll need various kinds of keys to interact with Tempel's API. -But instead of bogging you down with details, Tempel uses a concept called "**key chains**". +But instead of bogging you down with details, Tempel uses a concept called "**keychains**". -Analogous to physical key chains, these are Clojure objects that hold 0 or more keys of various types for various purposes. +Analogous to physical keychains, these are Clojure objects that hold 0 or more keys of various types for various purposes. Tempel `KeyChain`s: @@ -124,8 +126,8 @@ Deref a `KeyChain` to get detailed info about it: Note that Alice's `KeyChain` contains: - 1x 256 bit symmetric key -- 1x 3072 bit RSA key pair (private + public) -- 1x 3072 but DH key pair (private + public) +- 1x 3072 bit RSA keypair (private + public) +- 1x 3072 but DH keypair (private + public) It's not important to understand yet what any of that means. These are reasonable defaults that'll work well together to support the entire Tempel API. Each key/pair was randomly and securely generated when we called `tempel/keychain`, based on the options present in `tempel/*config*`. @@ -163,14 +165,51 @@ Equality works as you'd expect for `KeyChain`s: alice-keychain) ; => true ``` -## What next +## API overview + +Tempel's API is small, easy to use, easy to browse, and has extensive beginner-oriented docstrings. It includes: + +### Keychain basics + +`KeyChain`s are the main way you'll interact with the rest of Tempel's API: + +Function | Use to +-- | -- +[`keychain`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain) | Create a new `KeyChain`, default opts are reasonable. +[`keychain-encrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`). +[`keychain-decrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`). + +- You'll usually have 1 `KeyChain` per user: created and encrypted on sign-up, then decrypted on log-in and retained while the user remains logged in. +- Deref a `KeyChain` to see its contents. +- The default `keychain` options will return a `KeyChain` that includes all the keys necessary to fully support Tempel's entire API. -So now that we have one or more `KeyChain`s, what can we do with them? +### Data protection -See the [examples](./2-Examples) for task-oriented ideas, and/or check the extensive docstrings of Tempel's main API functions: +Function | Complement | Use to +---- | ---- | ---- +[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password. +[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[]. +[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt. +[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt. +[`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) | [`signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) | Sign data, and verify signed data. Useful for proving ownership, detecting tampering, etc. + +### Supporting utils + +Miscellaneous stuff that's used less frequently: + +Function | Use to +-- | -- +[`public-data`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) | Return any public (unencrypted) data associated with encrypted data. +[`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key) | Add symmetric key/s to `KeyChain`. +[`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair) | Add asymmetric keypair/s to `KeyChain`. +[`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove) | Remove key/s from `KeyChain`. +[`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) | Update priority of key/s in `KeyChain`. + +- Manual keychain management is rarely needed in practice, but useful when you need it! +- See [`aad-help`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-aad-help) for info about Tempel's "Additional Authenticated Data" (AAD) support. +- See [`akm-help`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-akm-help) for info about Tempel's "Additional Keying Material" (AKM) support. +- See [`*config*`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-*config*) for info about Tempel's global config options. + +## What next -- [`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) -- [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) -- [`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) -- [`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) -- [`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) \ No newline at end of file +See the [examples](./2-Examples) for task-oriented ideas! \ No newline at end of file diff --git a/wiki/2-Examples.md b/wiki/2-Examples.md index 0c5be4b..bb12730 100644 --- a/wiki/2-Examples.md +++ b/wiki/2-Examples.md @@ -226,33 +226,9 @@ Performance tip: when using this approach, make sure to use a random byte[] key ) ``` -# Key management - -Tempel includes the following utils for basic key management: - -- [`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key) -- [`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair) -- [`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove) -- [`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) -- [`keychain-normalize-priorities`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-normalize-priorities) - -These should cover the most common needs. More advanced key management can quickly become a complex topic and is beyond the scope of Tempel's built-in API or these docs. - # Encryption -Tempel's main API functions are easy to browse, easy to use, and have extensive docstrings: - -- Functions to encrypt data begin with `encrypt-` -- Functions to decrypt data begin with `decrypt-` - -A quick overview: - -Encrypt with | Decrypt with | Common use --- | -- | -- -[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password. -[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[]. -[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt. -[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt. +See [here](./1-Getting-started#data-protection) for an overview of Tempel's data protection API. ## Symmetric @@ -287,6 +263,7 @@ Using [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso. ``` ## Asymmetric + ### Send secret message to user Example use case: allow users to submit a bug report, ensuring that it's viewable only by the intended recipient (e.g. engineering department). diff --git a/wiki/3-FAQ.md b/wiki/3-FAQ.md index b5bce79..1b7d427 100644 --- a/wiki/3-FAQ.md +++ b/wiki/3-FAQ.md @@ -4,7 +4,7 @@ Tempel presumes that you'll do both encryption and decryption *using Tempel*, with **Clojure on the JVM**. -This limitation allows Tempel to implement unique features and keep its API and codebase small and simple. +This limitation is a **conscious choice** to enable unique benefits. For example: Tempel's encrypted payloads contain information about the encryption algorithms and parameters used. This enables the **automatic selection of keys** in keychains, and enables **automatic and backwards-compatible algorithm and parameter upgrades over time**. # How secure is Tempel?