[mod] Rename help vars

This'll be the naming scheme consistent across Tempel, Telemere,
and other new libs.

examples.clj

@@ -433,7 +433,7 @@ admin-public-keychain
 ;;;; Public data
 
 ;; Tempel has extensive support for "**Additional Authenticated Data**" /
-;; "**Additional Associated Data**", see `aad-help` for details.
+;; "**Additional Associated Data**", see `help:aad` for details.
 
 ;; And see `public-data` for a util that can help identify Tempel output,
 ;; and access public (unencrypted) info embedded in Tempel output.

src/taoensso/tempel.clj

@@ -10,8 +10,8 @@
   Abbreviations:
     External:
       pbkdf - Password Based Key Derivation Function
-      aad   - Additional Associated Aata (see `aad-help`)
-      akm   - Additional Keying Material (see `akm-help`)
+      aad   - Additional Associated Aata (see `help:aad`)
+      akm   - Additional Keying Material (see `help:akm`)
       kek   - Key encryption key (key used to encrypt another key)
       cnt   - Unencrypted content
       ecnt  - Encrypted   content
@@ -84,7 +84,7 @@
 
 ;;;; Doc vars
 
-(def aad-help
+(def help:aad
   "\"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).
@@ -111,7 +111,7 @@
 
   "See docstring")
 
-(def akm-help
+(def help:akm
   "\"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`).
 
@@ -212,7 +212,7 @@
     `:sym-cipher-algo` ∈ #{*:aes-gcm-128-v1 :aes-gcm-256-v1 :chacha20-poly1305-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`).
+      in order to use `:ba-aad` options (see `help:aad`).
 
       Default: `:aes-gcm-128-v1`, a good general-purpose symmetric cipher with
       AEAD support.
@@ -282,7 +282,7 @@
         key/password, *OR* with this optional secondary (backup) `KeyChain`
         (see `keychain`) or `KeyPair` (see `keypair-create`).
 
-        NB: this backup key will be able to decrypt *without* AKM (see `akm-help`).
+        NB: this backup key will be able to decrypt *without* AKM (see `help:akm`).
 
       When decrypting:
         When data was encrypted with support for a backup key, use this
@@ -336,7 +336,7 @@
   (unencrypted) data embedded in the byte[].
 
   Possible keys:
-    `:ba-aad`          - See `aad-help`
+    `:ba-aad`          - See `help:aad`
     `:keychain`        - Public-key part of encrypted `KeyChain`
     `:key-id`          - See `:embed-key-ids?` option of `encrypt-X` API
     `:receiver-key-id` - ''
@@ -481,7 +481,7 @@
   "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`)
+    - Optional unencrypted AAD (see `help:aad`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a password (string, byte[], or char[]).
@@ -491,8 +491,8 @@
   Decrypt output with: `decrypt-with-password`.
 
   Options:
-    `:ba-aad` - See `aad-help`
-    `:ba-akm` - See `akm-help`
+    `:ba-aad` - See `help:aad`
+    `:ba-akm` - See `help:akm`
 
     And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `pbkdf-algo`, `pbkdf-nwf`,
@@ -636,15 +636,15 @@
   "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`)
+    - Optional unencrypted AAD (see `help:aad`)
     - 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`
-    `:ba-akm` - See `akm-help`
+    `:ba-aad` - See `help:aad`
+    `:ba-akm` - See `help:akm`
 
     And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `embed-key-ids?`,
@@ -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`)
+    - Optional unencrypted AAD (see `help:aad`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes a `KeyChain` (see `keychain`) or `KeyPair` (see `keypair-create`).
@@ -796,8 +796,8 @@
   Decrypt output byte[] with: `decrypt-with-1-keypair`.
 
   Options:
-    `:ba-aad` - See `aad-help`
-    `:ba-akm` - See `akm-help`
+    `:ba-aad` - See `help:aad`
+    `:ba-akm` - See `help:akm`
 
     And see `*config*` for details:
       `hash-algo`, `sym-cipher-algo`, `asym-cipher-algo`,
@@ -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`)
+    - Optional unencrypted AAD (see `help:aad`)
     - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Takes `KeyChain`s (see `keychain`) and/or `KeyPair`s (see `keypair-create`).
@@ -1061,8 +1061,8 @@
   Decrypt output byte[] with: `decrypt-with-2-keypairs`.
 
   Options:
-    `:ba-aad` - See `aad-help`
-    `:ba-akm` - See `akm-help`
+    `:ba-aad` - See `help:aad`
+    `:ba-akm` - See `help:akm`
 
     And see `*config*` for details:
       `hash-algo`, `ka-algo`, `sym-cipher-algo`,
@@ -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`)
+    - Optional unencrypted AAD     (see `help:aad`)
     - Envelope data necessary for verification (specifies algorithms, etc.)
 
   Produces:
@@ -1255,8 +1255,8 @@
   Verify with: `signed`.
 
   Options:
-    `:ba-aad`         - See `aad-help`
-    `:ba-akm`         - See `akm-help`
+    `:ba-aad`         - See `help:aad`
+    `:ba-akm`         - See `help:akm`
     `:embed-content?` - See usage info above
 
     And see `*config*` for details:

src/taoensso/tempel/keys.clj

@@ -935,7 +935,7 @@
 
     - Unencrypted:
       - Any public keys in keychain (retrieve with `public-data`)
-      - Optional AAD (see `aad-help`)
+      - Optional AAD (see `help:aad`)
       - Envelope data necessary for decryption (specifies algorithms, etc.)
 
   Output can be safely stored (e.g. in a database).
@@ -947,8 +947,8 @@
     `:password`   - String, byte[], or char[]             as with `encrypt-with-password`
     `:key-sym`    - `KeyChain` (see `keychain`) or byte[] as with `encrypt-with-symmetric-key`
 
-    `:ba-aad`     - See `aad-help`
-    `:ba-akm`     - See `akm-help`
+    `:ba-aad`     - See `help:aad`
+    `:ba-akm`     - See `help:akm`
     `:ba-content` - Optional additional byte[] content that should be encrypted
                     and included in output for retrieval with `keychain-decrypt`.
 

wiki/1-Getting-started.md

@@ -206,10 +206,10 @@ Function | Use to
 [`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) | Update priority of key/s in a `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 [`help:aad`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aaad) for info about Tempel's "Additional Authenticated Data" (AAD) support.
+- See [`help:akm`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aakm) 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
 
-See the [examples](./2-Examples) for task-oriented ideas!
+See the [examples](./2-Examples) for task-oriented ideas!

wiki/2-Examples.md

@@ -332,10 +332,10 @@ This is an advanced version of the last example and would require a custom schem
 
 # Public data
 
-Tempel has extensive support for "**Additional Authenticated Data**" / "**Additional Associated Data**", see [`aad-help`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-aad-help) for details.
+Tempel has extensive support for "**Additional Authenticated Data**" / "**Additional Associated Data**", see [`help:aad`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aaad) for details.
 
 And see [`public-data`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) for a util that can help identify Tempel output, and access public (unencrypted) info embedded in Tempel output.
 
 # Signing
 
-See [`tempel/sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) and [`tempel/signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) for details.
+See [`tempel/sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) and [`tempel/signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) for details.

wiki/3-FAQ.md

@@ -100,4 +100,4 @@ These include things like:
 - Long-term *key management*.
 - Long-term *maintenance of algorithms and parameters* (scaling work factors and/or adjusting algorithms to keep up with best practice and moving hardware targets over time).
 - A consistent and easy-to-use API for *encrypting data with backup keys* so that it's always possible to reset a user's password, even when the user's data is fully encrypted at rest and the user's key is never stored.
-- A consistent and easy-to-use API for [AAD](https://taoensso.github.io/tempel/taoensso.tempel.html#var-aad-help), [AKM](https://taoensso.github.io/tempel/taoensso.tempel.html#var-akm-help), and [extracting public data](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) from encrypted payloads.
+- A consistent and easy-to-use API for [AAD](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aaad), [AKM](https://taoensso.github.io/tempel/taoensso.tempel.html#var-help.3Aakm), and [extracting public data](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) from encrypted payloads.