docs: add antora and write the CC book [WPB-23952]#1963
Open
docs: add antora and write the CC book [WPB-23952]#1963
Conversation
coriolinus
force-pushed
the
felix/antora
branch
from
767e0ee to
ea5d265
Compare
`antora.yml` defines the local documentation project. `antora-playbook.yml` defines all sources that contribute to the documentation site. It is best practice to have this in a separate repostiory as it configures the documentation without actually defining the content. For the start we place it here. Part of the configuration is the UI. We use the antora default UI for now. `ROOT` is the default module in antora. Every module can have `pages`, `partials`, and `examples`. Run `bunx antora antora-playbook.yml` to build the docs.
Under the hood it requires ruby and installing the gems.
`make antora` builds the antora documentation `make antora-attachments` pulls in the api docs as static assets, kotlin an ts for now.
GNU Make is sometimes a bit simplistic: if a step can produce multiple outputs, and N of those outputs are out of date, it will just run that step N times. This can be pretty time-consuming. The way to avoid this is to use `&:` syntax, which tells `Make` that all its targets are produced atomically, and a single run is sufficient. This is particularly important in rules which do some cleanup before running again.
In the first instance this is simple, we just literally exclude the autogenerated directory. In two more instances we have wildcards in place that search for files. The problems there were that those would not match the internal files (in the `wasm-bindgen` subdirectory) on the first run, because they would not yet exist, causing make to trigger a recompile on the second run when they did later exist. Listing them explicitly means that in combination with the `&:` token in the rule which generates them, we can see that they're all newer than the deps. In the other case where we had the wildcard, the generated code was always previously deleted ,so including it in the rule was pointless.
Humans don't have to keep track of the freshness or lifecycle of book attachments; that's the whole point of `make`. Instead, we just have one target, `cc-book`, which depends on the attachments being fresh and copied into the appropriate places.
coriolinus
force-pushed
the
felix/antora
branch
from
5869295 to
2235305
Compare
coriolinus
changed the title
|
|
||
| https://www.rfc-editor.org/rfc/rfc9420.html[RFC 9420], the Messaging Layer Security standard, solves the group-scaling problem that limits Proteus. | ||
| Rather than maintaining an independent session per client pair, MLS establishes a single shared group secret from which all members independently derive the same encryption keys. | ||
| Membership changes are managed through a _ratchet tree_ — a binary tree structure that lets any member compute the new shared secret after an add or remove using only O(log n) key operations rather than O(n²) messages. |
Member
There was a problem hiding this comment.
This is missing an imho essential bit of information, not just membership changes, but also sending application messages has O(log n) complexity (since any members with a mutual subtree receieve messages encrypted with the same key, i.e., the key of the root node of that subtree)
Contributor
There was a problem hiding this comment.
I thought that application messages are actually O(1), because once you have this shared group state, you end up with a symmetric AEAD key which requires exactly one encryption operation for that group/epoch.
cc-book/modules/ROOT/pages/mls.adoc
Outdated
|
|
||
| The fundamental unit of time in an MLS group is the _epoch_. | ||
| Each epoch has a distinct shared secret; when membership changes (or when keys are rotated for other reasons), the group advances to a new epoch and new keys are computed. | ||
| This is MLS's forward secrecy guarantee: compromise of the current epoch does not expose messages from any prior epoch. |
Member
There was a problem hiding this comment.
Maybe this is a good place also to mention post compromise security, the property that compromise of key material of the current epoch does not expose messages of any future epoch.
Turns out that OSX `cp -R` does something subtly different from Linux `cp -R`, and it's based on the presence of the trailing slash in the source of the copy. Happily, it looks like we can fix it by just getting rid of that slash. Therefore this commit.
| . Renamed TypeScript wrapper functions (this should be undone after we upgrade to uniffi 0.30.0). `transaction()` -> | ||
| `newTransaction()`, `findCredentials()` -> `getFilteredCredentials()` | ||
| ==== | ||
|
|
Member
There was a problem hiding this comment.
These lines can be removed
| :hide-uri-scheme: | ||
|
|
||
| This library is a simplified abstraction over the MLS and Proteus cryptographic protocols for end-to-end encrypted commmunication. | ||
| In addition, it provides end-to-end identity (E2EI) support. |
Member
There was a problem hiding this comment.
Maybe it's worth mentioning that E2EI means using x509 credentials?
| @@ -0,0 +1,90 @@ | |||
| = The Database | |||
|
|
|||
| The `Database` is CoreCrypto's keystore: the persistent store for all key material and cryptographic state. | |||
Member
There was a problem hiding this comment.
nit: we're also using the database for non-cryptographic data
Comment on lines
+73
to
+75
| == Arbitrary Data Storage | ||
|
|
||
| The context provides two methods for storing a single blob of arbitrary bytes in the keystore, associated with the device: |
Member
There was a problem hiding this comment.
Maybe mention that it's intended (but not limited) to be used as a checkpoint mechanism during initial sync/batch decryption?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's new in this PR
PR Submission Checklist for internal contributors
SQPIT-764feat(conversation-list): Sort conversations by most emojis in the title #SQPIT-764.