From e0e4eea7053a5b233f6d3f02d1482abc790c7665 Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Mon, 13 Nov 2023 10:44:40 +0100 Subject: [PATCH] [doc] Misc housekeeping --- README.md | 4 ++-- wiki/3-FAQ.md | 35 ++++++++++++++++++++++++++++++++--- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 903b3a3..64e9b0a 100644 --- a/README.md +++ b/README.md @@ -23,10 +23,10 @@ See [here][GitHub releases] for earlier releases. - **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) and [⧉ asymmetric](https://en.wikipedia.org/wiki/Public-key_cryptography) (public-key) encryption +- 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 docstrings and [documentation](#documentation) +- Beginner-oriented [documentation](#documentation) and docstrings Note that Tempel is [not intended](../../wiki/3-Faq#can-i-decrypt-tempel-data-with-other-tools) for interop with other cryptographic tools/APIs. diff --git a/wiki/3-FAQ.md b/wiki/3-FAQ.md index 34d69c0..90d96fd 100644 --- a/wiki/3-FAQ.md +++ b/wiki/3-FAQ.md @@ -1,10 +1,10 @@ # Can I decrypt Tempel data with other tools? -**No**, Tempel is **explicitly not designed** for interop with other general-purpose cryptographic tools or portability between platforms/languages/etc. +**No**, Tempel is **intentionally not designed** for interop with other general-purpose cryptographic tools or portability between platforms/languages/etc. Tempel presumes that you'll do both encryption and decryption *using Tempel*, with **Clojure on the JVM**. -This limitation allows Tempel's API and codebase to be kept small and simple. +This limitation allows Tempel to implement unique features and keep its API and codebase small and simple. # How secure is Tempel? @@ -72,4 +72,33 @@ Tempel uses the JVM's crypto API, but wraps it to: Tempel does not implement ("roll") its own cryptographic primitives, though it *does* necessarily implement its own higher-level protocols and data formats. -See [here](#how-secure-is-tempel) for more info about Tempel's security risks. \ No newline at end of file +See [here](#how-secure-is-tempel) for more info about Tempel's security risks. + +# How does Tempel compare to [Buddy](https://github.com/funcool/buddy)? + +**tl;dr**: Tempel may be a possible alternative for some (but not all) parts of Buddy. There's functionality overlap, but Buddy offers some facilities that Tempel does not and vice versa. + +#### Tempel's limitations + +- No public API for *low-level cryptographic functionality* as in [buddy-core](https://github.com/funcool/buddy#buddy-core), [buddy-hashers](https://github.com/funcool/buddy#buddy-hashers), etc. +- No *authorization* functionality as in [buddy-auth](https://github.com/funcool/buddy#buddy-auth). +- [No support](#can-i-decrypt-tempel-data-with-other-tools) for interop with other tools. + +#### Tempel's strengths + +- A small, particularly easy-to-use high-level [API](./1-Getting-started#what-next) focused on [user keychains](./1-Getting-started#keychains) and keychain management. +- Data formats designed to easily support item-specific algorithms and parameters, and to support (auto)-updating these kinds of things over time. + +#### Tempel's objectives + +I've built a number of applications over the years that deal with encrypted user data. Tempel's basically designed to address the parts of that experience that I've repeatedly found most difficult/frustrating. + +In practice, that's usually key management (especially long-term), and transitioning algorithms and parameters over time (e.g. as you need to scale work factors and/or adjust algorithms to keep up with best practice and moving hardware targets). + +Getting all of that right can be quite a bear so Tempel's API is focused in that direction. + +As one example, by making it easy to encrypt data with a backup key so that it's possible to keep user data fully encrypted when at rest, never store the user's key, but still retain the possibility for the user's password to be reset. + +And I've often wanted things over the years like a consistent interface for [AAD](https://taoensso.github.io/tempel/taoensso.tempel.html#var-aad-help) and [AKM](https://taoensso.github.io/tempel/taoensso.tempel.html#var-akm-help) across different encryption algorithms, or a consistent interface for [extracting public data](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) from encrypted payloads. + +I don't want to have to think about things like this when designing an application with encrypted data, I just want it to work sensibly. \ No newline at end of file