From 14be80ff10ef66f73d3e71df716b1cb6e5ed207c Mon Sep 17 00:00:00 2001 From: Peter Taoussanis Date: Tue, 12 Mar 2024 09:14:16 +0100 Subject: [PATCH] [mod] Rename help vars This'll be the naming scheme consistent across Tempel, Telemere, and other new libs. --- examples.clj | 2 +- src/taoensso/tempel.clj | 44 ++++++++++++++++++------------------ src/taoensso/tempel/keys.clj | 6 ++--- wiki/1-Getting-started.md | 6 ++--- wiki/2-Examples.md | 4 ++-- wiki/3-FAQ.md | 2 +- 6 files changed, 32 insertions(+), 32 deletions(-) diff --git a/examples.clj b/examples.clj index e345f16..b0ede9c 100644 --- a/examples.clj +++ b/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. diff --git a/src/taoensso/tempel.clj b/src/taoensso/tempel.clj index 2ae8d37..7a06068 100644 --- a/src/taoensso/tempel.clj +++ b/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: diff --git a/src/taoensso/tempel/keys.clj b/src/taoensso/tempel/keys.clj index 8bcf6db..c034607 100644 --- a/src/taoensso/tempel/keys.clj +++ b/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`. diff --git a/wiki/1-Getting-started.md b/wiki/1-Getting-started.md index dd6a493..bd91781 100644 --- a/wiki/1-Getting-started.md +++ b/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! \ No newline at end of file +See the [examples](./2-Examples) for task-oriented ideas! diff --git a/wiki/2-Examples.md b/wiki/2-Examples.md index bb12730..ff366ac 100644 --- a/wiki/2-Examples.md +++ b/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. \ No newline at end of file +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. diff --git a/wiki/3-FAQ.md b/wiki/3-FAQ.md index 1b7d427..1c813ec 100644 --- a/wiki/3-FAQ.md +++ b/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. \ No newline at end of file +- 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.