~wip

taoensso · Oct 16, 2023 · d33129d · d33129d
1 parent 9fbe05c
commit d33129d
Show file tree

Hide file tree

Showing 8 changed files with 118 additions and 215 deletions.
diff --git a/project.clj b/project.clj
@@ -8,7 +8,7 @@
    :url  "https://www.eclipse.org/legal/epl-v10.html"}
 
   :dependencies
-  [[com.taoensso/encore "3.68.0"]]
+  [[com.taoensso/encore "3.69.0"]]
 
   :profiles
   {;; :default [:base :system :user :provided :dev]
@@ -25,8 +25,7 @@
      *unchecked-math*     false #_:warn-on-boxed}
 
     :dependencies
-    [[org.clojure/test.check "1.1.1"]
-     [com.taoensso/timbre    "6.3.1"]]}
+    [[org.clojure/test.check "1.1.1"]]}
 
    :graal-tests
    {:dependencies [[org.clojure/clojure "1.11.1"]

diff --git a/src/taoensso/tempel.clj b/src/taoensso/tempel.clj
@@ -9,37 +9,35 @@
 
   Abbreviations:
     pbkdf - password based key derivation function
-    aad   - additional associated data (see also `doc-aad`)
-    akm   - additional keying material (see also `doc-akm`)
+    aad   - additional associated data (see also `aad-help`)
+    akm   - additional keying material (see also `akm-help`)
     kek   - key encryption key (key used to encrypt another key)
     cnt   -           content
     ecnt  - encrypted content"
 
   {:author "Peter Taoussanis (@ptaoussanis)"}
   (:require
    [taoensso.encore :as enc  :refer [have have?]]
-   [taoensso.tempel.bytes :as bytes]
+   [taoensso.encore.bytes :as bytes]
    [taoensso.tempel.df    :as df]
    [taoensso.tempel.impl  :as impl]
    [taoensso.tempel.pbkdf :as pbkdf]
    [taoensso.tempel.keys  :as keys]))
 
 (comment
   (remove-ns 'taoensso.tempel)
-  (:public (enc/interns-overview)))
+  (:api (enc/interns-overview)))
 
-(enc/assert-min-encore-version [3 68 0])
+(enc/assert-min-encore-version [3 69 0])
 
 ;;;; TODO
-;; - Confirm: would 512-bit (64 byte) keys be possible?
-;; - Move bytes API to encore? (For use by Carmine, Nippy, etc.)
 ;; - General review: API, impln, tests
-;; - Initial README and Wiki content (see sketch IMPORT_DOCS.md)
-;; - Extra (generative?) tests?
-
 ;; - Check Signal's algos:
 ;;   - "Double Ratchet Algorithm", Ref. <https://www.signal.org/docs/specifications/doubleratchet/?ref=crnkovic.dev>
 ;;   - "X3DH", Ref. <https://signal.org/docs/specifications/x3dh/>
+;;
+;; - Extra (generative?) tests?
+;; - Initial README and Wiki content (see sketch IMPORT_DOCS.md)
 
 ;;;; Aliases
 
@@ -70,7 +68,7 @@
 
 ;;;; Doc vars
 
-(def doc-aad
+(def aad-help
   "\"Additional Authenticated Data\" (AAD) is optional arbitrary byte[] data that
   may be provided to many of Tempel's API functions (e.g. `encrypt-with-X` when
   using an AEAD cipher).
@@ -94,9 +92,10 @@
     - File or data integrity checks (hashes, etc.)
     - Cryptographic signatures
     - Arbitrary Clojure data via Nippy, Ref. <https://github.com/taoensso/nippy>"
-  nil)
 
-(def doc-akm
+  "See docstring")
+
+(def akm-help
   "\"Additional Keying Material\" (AKM) is optional arbitrary byte[] data that
   may be provided to many of Tempel's API functions (e.g. `encrypt-with-X`).
 
@@ -116,12 +115,13 @@
     - Protocol-specific values
     - Security credentials or certificates
     - Arbitrary Clojure data via Nippy, Ref. <https://github.com/taoensso/nippy>"
-  nil)
+
+  "See docstring")
 
 ;;;; Config
 
 (enc/defonce default-keypair-creator_
-  "Default stateful KeyPair generator with options:
+  "Default stateful `KeyPair` generator with options:
   {:buffer-len 16, :n-threads [:perc 10]}"
   (delay (impl/keypair-creator {:buffer-len 16, :n-threads [:perc 10]})))
 
@@ -167,7 +167,7 @@
 
     `:hash-algo` ∈ #{:md5 :sha-1 *:sha-256 :sha-512}
       Hash algorithm used for internal HMACs, etc.
-      Default: `:sha-256`, and there's usually no good reason to change this.
+      Default: `:sha-256`, there's usually no good reason to change this.
 
     `:pbkdf-algo` ∈ #{*:scrypt-r8p1-v1 :pbkdf2-hmac-sha-256-v1}
       Algorithm to use for password-based key stretching.
@@ -192,7 +192,7 @@
     `: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 `doc-aad` docstring).
+      in order to use `:ba-aad` options (see `aad-help` docstring).
 
       Default: `:aes-gcm-128-v1`, a good general-purpose symmetric cipher with
       AEAD support.
@@ -242,7 +242,7 @@
 
   default-config)
 
-(defn get-config "Implementation detail" [opts] (conj (or *config* {}) opts))
+(defn ^:no-doc get-config "Implementation detail" [opts] (enc/fast-merge *config* opts))
 (comment (get-config {}))
 
 ;;;; Public data
@@ -252,7 +252,7 @@
   (unencrypted) data embedded in the byte[].
 
   Possible keys:
-    `:ba-aad`          - See `doc-aad` docstring.
+    `:ba-aad`          - See `aad-help` docstring.
     `:keychain`        - Public-key part of encrypted `KeyChain`
     `:key-id`          - See `:embed-key-ids?` option of `encrypt-X` API
     `:receiver-key-id` - ''
@@ -339,8 +339,8 @@
             :ba-aad ?ba-aad))
 
         (enc/unexpected-arg! env-kid
-          :expected :envelope-with-public-data
-          :context  `public-data)))))
+          {:expected :envelope-with-public-data
+           :context  `public-data})))))
 
 (defn- public-data-test
   [ba-tempel-output]
@@ -367,14 +367,14 @@
       :cnt (bytes/utf8-?ba->str ?ba-cnt))
 
     (enc/unexpected-arg! return-kind
-      :expected #{:ba-content :ba-aad :as-map}
-      :context  context)))
+      {:expected #{:ba-content :ba-aad :as-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 `doc-aad` docstring)
+    - Optional unencrypted AAD (see `aad-help` docstring)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a password (string, byte[], or char[]).
@@ -384,8 +384,8 @@
   Decrypt output with: `decrypt-with-password`.
 
   Options:
-    `:ba-aad` - See `doc-aad` docstring
-    `:ba-akm` - See `doc-akm` dosctring
+    `:ba-aad` - See `aad-help` docstring
+    `:ba-akm` - See `akm-help` dosctring
 
   Relevant `*config*` keys (see that var's docstring for details):
     `hash-algo`, `sym-cipher-algo`, `pbkdf-algo`, `pbkdf-nwf`, `embed-key-ids?`"
@@ -487,15 +487,15 @@
   "Uses a symmetric cipher to encrypt the given byte[] content and return
   a byte[] that includes:
     - The encrypted content
-    - Optional unencrypted AAD (see `doc-aad` docstring)
+    - Optional unencrypted AAD (see `aad-help` docstring)
     - 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 `doc-aad` docstring
-    `:ba-akm` - See `doc-akm` docstring
+    `:ba-aad` - See `aad-help` docstring
+    `:ba-akm` - See `akm-help` docstring
 
   Relevant `*config*` keys (see that var's docstring for details):
     `hash-algo`, `sym-cipher-algo`, `embed-key-ids?`"
@@ -584,7 +584,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 `doc-aad` docstring)
+    - Optional unencrypted AAD (see `aad-help` docstring)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a `KeyChain` (see `keychain`) or `KeyPair` (see `keypair-create`).
@@ -597,8 +597,8 @@
   Decrypt output byte[] with: `decrypt-with-1-keypair`.
 
   Options:
-    `:ba-aad` - See `doc-aad` docstring
-    `:ba-akm` - See `doc-akm` docstring
+    `:ba-aad` - See `aad-help` docstring
+    `:ba-akm` - See `akm-help` docstring
 
   Relevant `*config*` keys (see that var's docstring for details):
     `hash-algo`, `sym-cipher-algo`, `asym-cipher-algo`, `embed-key-ids`?"
@@ -756,10 +756,10 @@
           (return-val env-kid return ba-cnt nil))
 
         (enc/unexpected-arg! env-kid
-          :context `decrypt-with-1-keypair
-          :expected
-          {:encrypted-with-1-keypair-hybrid-v1
-           :encrypted-with-1-keypair-simple-v1})))))
+          {:context `decrypt-with-1-keypair
+           :expected
+           #{:encrypted-with-1-keypair-hybrid-v1
+             :encrypted-with-1-keypair-simple-v1}})))))
 
 (comment
   (let [kc     (keychain)
@@ -770,7 +770,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 `doc-aad` docstring)
+    - Optional unencrypted AAD (see `aad-help` docstring)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes `KeyChain`s (see `keychain`) and/or `KeyPair`s (see `keypair-create`).
@@ -788,8 +788,8 @@
   Decrypt output byte[] with: `decrypt-with-2-keypairs`.
 
   Options:
-    `:ba-aad` - See `doc-aad` docstring
-    `:ba-akm` - See `doc-akm` docstring
+    `:ba-aad` - See `aad-help` docstring
+    `:ba-akm` - See `akm-help` docstring
 
   Relevant `*config*` keys (see that var's docstring for details):
     `hash-algo`, `ka-algo`, `sym-cipher-algo`, `embed-key-ids?`"
@@ -921,7 +921,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 `doc-aad` docstring)
+    - Optional unencrypted AAD     (see `aad-help` docstring)
     - Envelope data necessary for verification (specifies algorithms, etc.)
 
   Basically produces:

diff --git a/src/taoensso/tempel/bytes.clj b/src/taoensso/tempel/bytes.clj
@@ -15,7 +15,7 @@
 
 (comment
   (remove-ns 'taoensso.tempel.bytes)
-  (:public (enc/interns-overview)))
+  (:api (enc/interns-overview)))
 
 ;;;; Aliases
 
@@ -205,8 +205,8 @@
      (seqable? x) (byte-array   x)
      :else
      (enc/unexpected-arg! x
-       :context  `as-ba
-       :expected '#{byte-array string char-array int seqable}))))
+       {:context  `as-ba
+        :expected '#{byte-array string char-array int seqable}}))))
 
 (comment (vec (as-ba 16 "hello")))
 
@@ -238,8 +238,8 @@
     (bytes?  x) (.toCharArray ^String (utf8-ba->str x))
     :else
     (enc/unexpected-arg! x
-      :context  `as-ca
-      :expected '#{char-array string byte-array})))
+      {:context  `as-ca
+       :expected '#{char-array string byte-array}})))
 
 ;;;; Byte streams
 
@@ -264,7 +264,8 @@
         acc))
     0 spec))
 
-(defmacro with-out [[dos-sym ?baos-sym] buffer-len & body]
+(defmacro with-out
+  [[dos-sym ?baos-sym] buffer-len & body]
   (let [baos-sym (or ?baos-sym '__baos)
         buffer-len
         (if (vector? buffer-len)
@@ -276,7 +277,8 @@
             ~(with-meta baos-sym {:tag 'java.io.ByteArrayOutputStream})]
          ~@body))))
 
-(defmacro with-in [[din-sym ?bais-sym] ba & body]
+(defmacro with-in
+  [[din-sym ?bais-sym] ba & body]
   (let [bais-sym (or ?bais-sym '__bais)]
     `(with-in* ~ba
        (fn [~(with-meta din-sym  {:tag 'java.io.DataInput})

diff --git a/src/taoensso/tempel/df.clj b/src/taoensso/tempel/df.clj
@@ -12,7 +12,7 @@
 
 (comment
   (remove-ns 'taoensso.tempel.df)
-  (:public (enc/interns-overview)))
+  (:api (enc/interns-overview)))
 
 ;;;; IDs
 ;; - `kid` => keyword id, used to uniquely identify some algo/kit/etc.