Skip to content

Commit

Permalink
[doc] Move API links to cljdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
ptaoussanis committed Apr 11, 2024
1 parent e05a029 commit 99aa95d
Show file tree
Hide file tree
Showing 4 changed files with 29 additions and 29 deletions.
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ See for intro and usage:
## Documentation

- [Wiki][GitHub wiki] (getting started, usage, etc.)
- API reference: [Codox][Codox docs], [clj-doc][clj-doc docs]
- API reference: [cljdoc][cljdoc docs], [Codox][Codox docs]

## Roadmap

Expand Down Expand Up @@ -132,7 +132,7 @@ Licensed under [EPL 1.0](LICENSE.txt) (same as Clojure).
<!-- Project -->

[Codox docs]: https://taoensso.github.io/tempel/
[clj-doc docs]: https://cljdoc.org/d/com.taoensso/tempel/
[cljdoc docs]: https://cljdoc.org/d/com.taoensso/tempel/

[Clojars SVG]: https://img.shields.io/clojars/v/com.taoensso/tempel.svg
[Clojars URL]: https://clojars.org/com.taoensso/tempel
Expand Down
34 changes: 17 additions & 17 deletions wiki/1-Getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ Note that Alice's `KeyChain` contains:

It's not important to understand yet what any of that means. These are reasonable defaults that'll work well together to support the entire Tempel API. Each key/pair was randomly and securely generated when we called `tempel/keychain`, based on the options present in `tempel/*config*`.

`tempel/*config*` is an important var. Its [default value](https://taoensso.github.io/tempel/taoensso.tempel.html#var-default-config) should be reasonable for most users, but it'd be worth at least familiarizing yourself with what's in there. [Its docstring](https://taoensso.github.io/tempel/taoensso.tempel.html#var-*config*) includes extensive documentation.
`tempel/*config*` is an important var. Its [default value](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#default-config) should be reasonable for most users, but it'd be worth at least familiarizing yourself with what's in there. [Its docstring](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#*config*) includes extensive documentation.

The content of `KeyChain`s can be updated: keys can be added or removed, and key priorities can be adjusted. But for many simple uses you won't need to do any of that under normal circumstances.

Expand Down Expand Up @@ -175,9 +175,9 @@ Tempel's API is small, easy to use, easy to browse, and has extensive beginner-o

Function | Use to
-- | --
[`keychain`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain) | Create a new `KeyChain`, default opts are reasonable.
[`keychain-encrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
[`keychain-decrypt`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
[`keychain`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain) | Create a new `KeyChain`, default opts are reasonable.
[`keychain-encrypt`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-encrypt) | Encrypt a `KeyChain` (with password, byte[], or another `KeyChain`).
[`keychain-decrypt`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-decrypt) | Decrypt a `KeyChain` (with password, byte[], or another `KeyChain`).

- You'll usually have 1 `KeyChain` per user: created and encrypted on sign-up, then decrypted on log-in and retained while the user remains logged in.
- Deref a `KeyChain` to see its contents.
Expand All @@ -187,28 +187,28 @@ Function | Use to

Function | Complement | Use to
---- | ---- | ----
[`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) | [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password) | Encrypt & decrypt data with the same password.
[`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
[`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
[`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
[`sign`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-sign) | [`signed`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-signed) | Sign data, and verify signed data. Useful for proving ownership, detecting tampering, etc.
[`encrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-password) | [`decrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-password) | Encrypt & decrypt data with the same password.
[`encrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-symmetric-key) | [`decrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-symmetric-key) | Encrypt & decrypt data with the same `KeyChain` or byte[].
[`encrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) | [`decrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) | Encrypt data with recipient's public `KeyChain`. Only the recipient can decrypt.
[`encrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs) | [`decrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs) | Encrypt data with sender's private `KeyChain` and recipient's public `KeyChain`. Either party can decrypt.
[`sign`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#sign) | [`signed`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#signed) | Sign data, and verify signed data. Useful for proving ownership, detecting tampering, etc.

### Supporting utils

Miscellaneous stuff that's used less frequently:

Function | Use to
-- | --
[`public-data`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-public-data) | Return any public (unencrypted) data associated with encrypted data.
[`keychain-add-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-symmetric-key) | Add symmetric key/s to a `KeyChain`.
[`keychain-add-asymmetric-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-add-asymmetric-keypair) | Add asymmetric keypair/s to a `KeyChain`.
[`keychain-remove`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-remove) | Remove key/s from a `KeyChain`.
[`keychain-update-priority`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-keychain-update-priority) | Update priority of key/s in a `KeyChain`.
[`public-data`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#public-data) | Return any public (unencrypted) data associated with encrypted data.
[`keychain-add-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-add-symmetric-key) | Add symmetric key/s to a `KeyChain`.
[`keychain-add-asymmetric-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-add-asymmetric-keypair) | Add asymmetric keypair/s to a `KeyChain`.
[`keychain-remove`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#keychain-remove) | Remove key/s from a `KeyChain`.
[`keychain-update-priority`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#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 [`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.
- See [`help:aad`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:aad) for info about Tempel's "Additional Authenticated Data" (AAD) support.
- See [`help:akm`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:akm) for info about Tempel's "Additional Keying Material" (AKM) support.
- See [`*config*`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#*config*) for info about Tempel's global config options.

## What next

Expand Down
18 changes: 9 additions & 9 deletions wiki/2-Examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This just means that we want it to take about 2 seconds to transform a password

Note that it's a handy feature of Tempel to easily support different work factors like this on a per-item basis.

See the `*config*` [docstring](https://taoensso.github.io/tempel/taoensso.tempel.html#var-*config*) for more info on the `:pbkdf-nwf` option, etc.
See the `*config*` [docstring](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#*config*) for more info on the `:pbkdf-nwf` option, etc.

## Create user account

Expand Down Expand Up @@ -234,7 +234,7 @@ See [here](./1-Getting-started#data-protection) for an overview of Tempel's data

Example use case: allow users to encrypt their data so that only they can view or modify it.

Using [`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-password) and [`decrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-password):
Using [`encrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-password) and [`decrypt-with-password`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-password):

```clojure
;;; Symmetric encryption with a password
Expand All @@ -244,7 +244,7 @@ Using [`encrypt-with-password`](https://taoensso.github.io/tempel/taoensso.tempe
(= (nippy/thaw ba-decrypted) {:my-secret-data? true}))
```

Using [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-symmetric-key) and [`decrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-decrypt-with-symmetric-key):
Using [`encrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-symmetric-key) and [`decrypt-with-symmetric-key`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#decrypt-with-symmetric-key):

```clojure
;;; Symmetric encryption with `KeyChain`
Expand All @@ -268,7 +268,7 @@ Using [`encrypt-with-symmetric-key`](https://taoensso.github.io/tempel/taoensso.

Example use case: allow users to submit a bug report, ensuring that it's viewable only by the intended recipient (e.g. engineering department).

Using [`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) and [`decrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair):
Using [`encrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) and [`decrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair):

```clojure
(let [alice-secret-keychain (tempel/keychain {}) ; Only Alice will have this
Expand All @@ -292,7 +292,7 @@ Example use case: allow 2 users to participate in a private conversation viewabl

This is an example of [⧉ end-to-end](https://en.wikipedia.org/wiki/End-to-end_encryption) (E2EE) encryption.

Using [`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs) and [`decrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs):
Using [`encrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs) and [`decrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs):

```clojure
(let [alice-secret-keychain (tempel/keychain {}) ; Only Alice will have this
Expand Down Expand Up @@ -328,14 +328,14 @@ This is an advanced version of the last example and would require a custom schem

- Have 1 user act as the group/room owner.
- Have the owner generate a random symmetric key for the group/room.
- Have the owner distribute the shared key to every other user via [`encrypt-with-1-keypair`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-1-keypair) or [`encrypt-with-2-keypairs`](https://taoensso.github.io/tempel/taoensso.tempel.html#var-encrypt-with-2-keypairs), etc.
- Have the owner distribute the shared key to every other user via [`encrypt-with-1-keypair`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-1-keypair) or [`encrypt-with-2-keypairs`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#encrypt-with-2-keypairs), etc.

# Public data

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.
Tempel has extensive support for "**Additional Authenticated Data**" / "**Additional Associated Data**", see [`help:aad`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:aad) 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.
And see [`public-data`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#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://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#sign) and [`tempel/signed`](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#signed) for details.
2 changes: 1 addition & 1 deletion wiki/3-FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-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.
- A consistent and easy-to-use API for [AAD](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:aad), [AKM](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#help:akm), and [extracting public data](https://cljdoc.org/d/com.taoensso/tempel/CURRENT/api/taoensso.tempel#public-data) from encrypted payloads.

0 comments on commit 99aa95d

Please sign in to comment.