Skip to content

Commit

Permalink
~wip
Browse files Browse the repository at this point in the history
  • Loading branch information
ptaoussanis committed Oct 16, 2023
1 parent 9fbe05c commit 9cfe765
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 24 deletions.
44 changes: 23 additions & 21 deletions src/taoensso/tempel.clj
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
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"
Expand Down Expand Up @@ -70,7 +70,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).
Expand All @@ -94,9 +94,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`).
Expand All @@ -116,7 +117,8 @@
- Protocol-specific values
- Security credentials or certificates
- Arbitrary Clojure data via Nippy, Ref. <https://github.com/taoensso/nippy>"
nil)

"See docstring")

;;;; Config

Expand Down Expand Up @@ -192,7 +194,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.
Expand Down Expand Up @@ -252,7 +254,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` - ''
Expand Down Expand Up @@ -374,7 +376,7 @@
"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[]).
Expand All @@ -384,8 +386,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?`"
Expand Down Expand Up @@ -487,15 +489,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?`"
Expand Down Expand Up @@ -584,7 +586,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`).
Expand All @@ -597,8 +599,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`?"
Expand Down Expand Up @@ -770,7 +772,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`).
Expand All @@ -788,8 +790,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?`"
Expand Down Expand Up @@ -921,7 +923,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:
Expand Down
6 changes: 3 additions & 3 deletions src/taoensso/tempel/keys.clj
Original file line number Diff line number Diff line change
Expand Up @@ -845,7 +845,7 @@
- Unencrypted:
- Any public keys in keychain (retrieve with `public-data`)
- Optional AAD (see `doc-aad` docstring)
- Optional AAD (see `aad-help` docstring)
- Envelope data necessary for decryption (specifies algorithms, etc.)
Output can be safely stored (e.g. in a database).
Expand All @@ -854,8 +854,8 @@
See Tempel Wiki for detailed usage info, common patterns, examples, etc.
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
`:ba-content` - Optional additional byte[] content that should be encrypted
and included in output for retrieval with `keychain-decrypt`.
Expand Down

0 comments on commit 9cfe765

Please sign in to comment.