Add support for ChaCha20-Poly1305 AEAD

README.md

@@ -23,13 +23,29 @@ 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
+- **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.
 
+## 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.
+
+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 user feedback before locking things down:
+
+| Phase | Date    | Release       | Appropriate for
+| :-:   | :--     | :--           | :--
+|  ➤    | 2023-11 | `v1.0-alpha`  | Dev/testing with disposable data
+|       | 2024-01 | `v1.0-beta`   | Dev/testing with disposable data
+|       | 2024-03 | `v1.0-RC`     | Staging, with ephemeral or low-value data
+|       | 2024-05 | `v1.0` final  | Production, with real data
+
+`v1.0` final will be considered "**done**"- the library is expected to need+see only minimal maintance from that point.
+
 ## Disclaimer
 
 **Important**: while Tempel has been written and tested with care, the nature of the problem domain inevitably means that bugs and/or misuse can be **especially harmful and/or easy to make**.
@@ -38,19 +54,15 @@ Bugs and/or misuse could lead to [security vulnerabilities](../../wiki/3-FAQ#how
 
 Please be **very careful** evaluating Tempel and/or other cryptographic libraries/frameworks before use, especially new libraries/frameworks like Tempel!
 
+## Security
+
+See [here](../../security) for **security advisories** and/or to **report security vulnerabilities**.
+
 ## Documentation
 
 - [Full documentation][GitHub wiki] (**getting started** and more)
 - Auto-generated API reference: [Codox][Codox docs], [clj-doc][clj-doc docs]
 
-## Security advisories
-
-No advisories as of last README update. If any security vulnerabilities are discovered, they will be listed here along with an appropriate CVE.
-
-## Security reports
-
-To report a possible security vulnerability, **please email me** at `my first name at taoensso.com`. For particularly sensitive content, you may encrypt your message with my [public PGP/GPG key](https://www.taoensso.com/pgp). Thank you! - Peter Taoussanis
-
 ## Funding
 
 You can [help support][sponsor] continued work on this project, thank you!! 🙏

SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Security Advisories
+
+All security advisories will be posted [on GitHub](https://github.com/taoensso/tempel/security/advisories).
+
+## Reporting a Vulnerability
+
+Please report possible security vulnerabilities [via GitHub](https://github.com/taoensso/tempel/security/advisories), or by emailing me at `my first name at taoensso.com`. You may encrypt emails with [my public PGP/GPG key](https://www.taoensso.com/pgp).
+
+Thank you!
+\- [Peter Taoussanis](https://www.taoensso.com)

src/taoensso/tempel.clj

@@ -10,8 +10,8 @@
   Abbreviations:
     External:
       pbkdf - Password Based Key Derivation Function
-      aad   - Additional Associated Aata (see also `aad-help`)
-      akm   - Additional Keying Material (see also `akm-help`)
+      aad   - Additional Associated Aata (see `aad-help`)
+      akm   - Additional Keying Material (see `akm-help`)
       kek   - Key encryption key (key used to encrypt another key)
       cnt   - Unencrypted content
       ecnt  - Encrypted   content
@@ -205,14 +205,14 @@
       and resources spent during normal operation.
 
       The `:ref-<num>-msecs` keywords take approximately the described amount of
-      time on a 2020 M1 Macbook Pro. See also `pbkdf-nwf-estimate` docstring.
+      time on a 2020 M1 Macbook Pro. See `pbkdf-nwf-estimate`.
 
       Default: `:ref-100-msecs`, a reasonable value for many logins.
 
     `:sym-cipher-algo` ∈ #{*:aes-gcm-128-v1 :aes-gcm-256-v1}
       The symmetric cipher algorithm to use. A cipher that supports \"AEAD\"
       (Authenticated Encryption with Associated Data) must generally be provided
-      in order to use `:ba-aad` options (see `aad-help` docstring).
+      in order to use `:ba-aad` options (see `aad-help`).
 
       Default: `:aes-gcm-128-v1`, a good general-purpose symmetric cipher with
       AEAD support.
@@ -223,7 +223,7 @@
 
     `:keypair-creator` ∈ #{<function> <delay>}
       The function to use when generating asymmetric keypairs.
-      See the `keypair-create` and `keypair-creator` docstrings for details.
+      See `keypair-create`, `keypair-creator` for details.
 
       Default: `default-keypair-creator_`, which uses up to 10% of threads
       to buffer up to 16 keypairs per type.
@@ -232,13 +232,13 @@
 
     `:symmetric-keys`
       Symmetric keys to add to new `KeyChain`s.
-      See the `keychain` docstring for details.
+      See `keychain` for details.
 
       Default: a single random symmetric key.
 
     `:asymmetric-keypairs`
       Asymmetric keypairs to add to new `KeyChain`s.
-      See the `keychain` docstring for details.
+      See `keychain` for details.
 
       Default:
         - A single new `:rsa-3072` keypair, and
@@ -336,7 +336,7 @@
   (unencrypted) data embedded in the byte[].
 
   Possible keys:
-    `:ba-aad`          - See `aad-help` docstring.
+    `:ba-aad`          - See `aad-help`
     `:keychain`        - Public-key part of encrypted `KeyChain`
     `:key-id`          - See `:embed-key-ids?` option of `encrypt-X` API
     `:receiver-key-id` - ''
@@ -463,7 +463,7 @@
   (case return-kind
     :ba-content ?ba-cnt
     :ba-aad     ?ba-aad
-    :as-map
+    :map
     (enc/assoc-some {}
       :ba-content ?ba-cnt
       :ba-aad     ?ba-aad)
@@ -474,14 +474,14 @@
       :cnt (bytes/?utf8-ba->?str ?ba-cnt))
 
     (enc/unexpected-arg! return-kind
-      {:expected #{:ba-content :ba-aad :as-map}
+      {:expected #{:ba-content :ba-aad :map}
        :context  context})))
 
 (defn encrypt-with-password
   "Uses a symmetric cipher to encrypt the given byte[] content and return
   a byte[] that includes:
     - The encrypted content
-    - Optional unencrypted AAD (see `aad-help` docstring)
+    - Optional unencrypted AAD (see `aad-help`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a password (string, byte[], or char[]).
@@ -491,10 +491,10 @@
   Decrypt output with: `decrypt-with-password`.
 
   Options:
-    `:ba-aad` - See `aad-help` docstring
-    `:ba-akm` - See `akm-help` dosctring
+    `:ba-aad` - See `aad-help`
+    `:ba-akm` - See `akm-help`
 
-    And see `*config*` docstring for details:
+    And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `pbkdf-algo`, `pbkdf-nwf`,
       `embed-key-ids?`, `embed-hmac?`, `backup-key`, `backup-opts`."
 
@@ -563,7 +563,7 @@
   Return value depends on `:return` option:
     `:ba-content` - Returns decrypted byte[] content (default)
     `:ba-aad`     - Returns verified unencrypted embedded ?byte[] AAD
-    `:as-map`     - Returns {:keys [ba-aad ba-content]} map
+    `:map`        - Returns {:keys [ba-aad ba-content]} map
 
   Takes a password (string, byte[], or char[]). Password will be \"stretched\"
   using an appropriate \"Password-Based Key Derivation Function\" (PBKDF).
@@ -636,17 +636,17 @@
   "Uses a symmetric cipher to encrypt the given byte[] content and return
   a byte[] that includes:
     - The encrypted content
-    - Optional unencrypted AAD (see `aad-help` docstring)
+    - Optional unencrypted AAD (see `aad-help`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a `KeyChain` (see `keychain`) or byte[] key.
   Decrypt output with: `decrypt-with-symmetric-key`.
 
   Options:
-    `:ba-aad` - See `aad-help` docstring
-    `:ba-akm` - See `akm-help` docstring
+    `:ba-aad` - See `aad-help`
+    `:ba-akm` - See `akm-help`
 
-    And see `*config*` docstring for details:
+    And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `embed-key-ids?`,
       `backup-key`, `backup-opts`."
 
@@ -711,7 +711,7 @@
   Return value depends on `:return` option:
     `:ba-content` - Returns decrypted byte[] content (default)
     `:ba-aad`     - Returns verified unencrypted embedded ?byte[] AAD
-    `:as-map`     - Returns {:keys [ba-aad ba-content]} map
+    `:map`        - Returns {:keys [ba-aad ba-content]} map
 
   Takes a `KeyChain` (see `keychain`) or byte[] key.
   Will throw on decryption failure (bad key, etc.)."
@@ -783,7 +783,7 @@
   "Uses a symmetric or hybrid (symmetric + asymmetric) scheme to encrypt the
   given content byte[] and return a byte[] that includes:
     - The encrypted content
-    - Optional unencrypted AAD (see `aad-help` docstring)
+    - Optional unencrypted AAD (see `aad-help`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a `KeyChain` (see `keychain`) or `KeyPair` (see `keypair-create`).
@@ -796,10 +796,10 @@
   Decrypt output byte[] with: `decrypt-with-1-keypair`.
 
   Options:
-    `:ba-aad` - See `aad-help` docstring
-    `:ba-akm` - See `akm-help` docstring
+    `:ba-aad` - See `aad-help`
+    `:ba-akm` - See `akm-help`
 
-    And see `*config*` docstring for details:
+    And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `asym-cipher-algo`,
       `embed-key-ids`, `backup-key`, `backup-opts`."
 
@@ -919,7 +919,7 @@
   Return value depends on `:return` option:
     `:ba-content` - Returns decrypted byte[] content (default)
     `:ba-aad`     - Returns verified unencrypted embedded ?byte[] AAD
-    `:as-map`     - Returns {:keys [ba-aad ba-content]} map
+    `:map`        - Returns {:keys [ba-aad ba-content]} map
 
   Takes a `KeyChain` (see `keychain`) or `KeyPair` (see `keypair-create`).
   Key algorithm must support use as an asymmetric cipher.
@@ -1043,7 +1043,7 @@
   "Uses a hybrid (symmetric + asymmetric) scheme to encrypt the given content
   byte[] and return a byte[] that includes:
     - The encrypted content
-    - Optional unencrypted AAD (see `aad-help` docstring)
+    - Optional unencrypted AAD (see `aad-help`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes `KeyChain`s (see `keychain`) and/or `KeyPair`s (see `keypair-create`).
@@ -1061,10 +1061,10 @@
   Decrypt output byte[] with: `decrypt-with-2-keypairs`.
 
   Options:
-    `:ba-aad` - See `aad-help` docstring
-    `:ba-akm` - See `akm-help` docstring
+    `:ba-aad` - See `aad-help`
+    `:ba-akm` - See `akm-help`
 
-    And see `*config*` docstring for details:
+    And see `*config*` for details:
       `hash-algo`, `ka-algo`, `sym-cipher-algo`,
       `embed-key-ids?`, `backup-key`, `backup-opts`."
 
@@ -1141,7 +1141,7 @@
   Return value depends on `:return` option:
     `:ba-content` - Returns decrypted byte[] content (default)
     `:ba-aad`     - Returns verified unencrypted embedded ?byte[] AAD
-    `:as-map`     - Returns {:keys [ba-aad ba-content]} map
+    `:map`        - Returns {:keys [ba-aad ba-content]} map
 
   Takes `KeyChain`s (see `keychain`) and/or `KeyPair`s (see `keypair-create`).
   Key algorithm must support key agreement.
@@ -1238,7 +1238,7 @@
   "Cryptographically signs the given content byte[] and returns a byte[]
   that includes:
     - Optional unencrypted content (see `embed-content?` option below)
-    - Optional unencrypted AAD     (see `aad-help` docstring)
+    - Optional unencrypted AAD     (see `aad-help`)
     - Envelope data necessary for verification (specifies algorithms, etc.)
 
   Produces:
@@ -1255,11 +1255,11 @@
   Verify with: `signed`.
 
   Options:
-    `:ba-aad`         - See `aad-help` docstring
-    `:ba-akm`         - See `akm-help` dosctring
+    `:ba-aad`         - See `aad-help`
+    `:ba-akm`         - See `akm-help`
     `:embed-content?` - See usage info above
 
-    And see `*config*` docstring for details:
+    And see `*config*` for details:
       `hash-algo`, `sig-algo`, `embed-key-ids?`."
 
   #_(df/reference-data-formats :signed-v1)
@@ -1318,7 +1318,7 @@
   Return value depends on `:return` option:
     `:ba-content` - Returns verified ?byte[] content (when embedded)
     `:ba-aad`     - Returns verified ?byte[] AAD     (when embedded)
-    `:as-map`     - Returns {:keys [ba-aad ba-content]} map (default)
+    `:map`        - Returns {:keys [ba-aad ba-content]} map (default)
 
   Returns nil when verification fails.
 
@@ -1333,10 +1333,10 @@
   {:arglists
    '([ba-signed signer-key-pub &
       [{:keys [ba-content return ba-akm]
-        :or   {return :as-map}}]])}
+        :or   {return :map}}]])}
 
   [ba-signed signer-key-pub & [opts]]
-  (let [{:keys [ba-content return] :or {return :as-map}} opts
+  (let [{:keys [ba-content return] :or {return :map}} opts
         {:keys [ba-akm] :as opts+}
         (get-opts+ opts)]
 
@@ -1372,4 +1372,4 @@
 (comment
   (let [kc        (keychain)
         ba-signed (sign (as-ba "cnt") kc {:ba-aad (as-ba "aad")})]
-    (signed ba-signed kc {:return :as-map #_:_test})))
+    (signed ba-signed kc {:return :map #_:_test})))