Ideas on how to convey additional contextual helpful information

[cipriancraciun]

As hinted in #18 by @mk-fg, some of the patterns tool output give estimates (in terms of token suitability for different cryptographic purposes or in terms of how easy it is to brute-force it).

I would like to open a discussion on how to better handle giving some context or additional information about these estimates. (Some solutions to follow as individual replies for better GitHub discussions thread management.)

[cipriancraciun]

One solution would be to just include inline where the estimate is given the contextual information.

Such a proposal was made by @mk-fg in #18 (comment) (see the (128b) text added):

\_  usable for:
    \_  cryptography (128b)  !! NO !!      with    -77.42  bits of margin
    \_  authentication (32b)    OK         with    +18.58  bits of margin

In general it might work for such cases where the additional information is very succinct (as targeted entropy bits), however in the general sense (like bruteforce estimates as discussed in #24) the information can be quite lengthy due to the various subtleties of the topic at hand.

[cipriancraciun]

Another solution would be to include some permanent links to pages providing the additional contextual information. Something like for example https://links.volution.ro/z-tokens/jagijedu (volution.ro is my own domain) that would most likely redirect the user to a page (perhaps hosted on GitHub) containing the desired information.

This might be an elegant solution:

• it might enable us to provide much richer reading experience (having the whole HTML at our disposal) as opposed to displaying things in the console;
• it also allows us to update the information if any issues or inaccuracies are found, and thus users using an older version of the tool might get up-to-date information without actually updating the binary;

There are also some issues:

• it requires internet access and a modern browser (assuming we don't serve plain text);
• we need to update the URLs on major releases, or when the estimation procedure drastically changes, thus users of older versions of the tool receive pertinent information to their version;
• obviously if my domain (or the domain we use) disappears, so does the documentation; (we might use something such as PURL for this -- now hosted by the Internet Archive -- but even that didn't prove itself to "permanent"...)

(Obviously I am more in favor of this solution than the previous one of including help inline.)

[cipriancraciun]

I'll reply to @mk-fg in here:

That way, if project changes hands, it'd retain such documentation, it'd be properly versioned and forkable, not locked into being online-only on third-party domain, etc etc

Indeed having my personal domain mixed into this might be an issue when the project changes hands, thus indeed having it hosted on something like GitHub Pages might be a solution. (Especially one that doesn't require buying a domain.)

However, GitHub has another issue: it's tied to the username or the organization, thus the links would actually be volution.github.io/z-tokens. One solution would be to create an organization just for this project, which at the moment I think is premature (as I don't know of any actual users of this project outside of myself and perhaps @mk-fg.)

[mk-fg]

Yeah, but I don't think links to project docs need to be that persistent.
In forks, those will need to be grepped-for and updated, same as any other links in the docs themselves, to e.g. releases or canonical project repo, and I think are generally understood to change across forks very well by both devs and foss users.

And for display in the tool, if .md files are in the project repo, I think link can say something like "See to doc/bruteforcing.md for details [link]", even if these docs aren't installed to /usr/share/doc/ locally and only one binary is distributed.
This can be a single line linking to a table-of-contents at the end of specific multi-concept output, doesn't have to be 5 places in there mentioning separate links and multiple .md files, when it'd be same 5 links in every "generate --details" output.

One loosely-related example that comes to mind is systemd, which does it like this ("Docs:" section listing both local and remote docs):

% systemctl status getty@tty1
● [email protected] - Getty on tty1
     Loaded: loaded (/usr/lib/systemd/system/[email protected]; enabled; preset: enabled)
     Active: active (running) since Sat 2024-01-06 20:13:40 +05; 1 day 19h ago
       Docs: man:agetty(8)
             man:systemd-getty-generator(8)
             https://0pointer.de/blog/projects/serial-console.html
   Main PID: 1417 (agetty)
...

[cipriancraciun]

Yeah, but I don't think links to project docs need to be that persistent.

This is another good point, one that I didn't voice explicitly, but I did have in mind: keep "customization" information (like tools names, project URL, issues URL, these additional contextual help URL's) in a well defined place, then forks only have to change it in one place. (It also helps being able to backport changes from forks without getting merge conflicts due to these mismatched customizations.)

---

And for display in the tool, if .md files are in the project repo, I think link can say something like "See to doc/bruteforcing.md for details [link]", [...]

Although I don't see non-developers using this tool very soon, I would like not to send the user to the "repository", but instead I would like to provide him with either embedded information, or something copy-pastable in a browser.

[mk-fg]

I think one way to do it would be to bundle such linked documentation in project repository, like you'd do with any other relevant docs (cryptsetup F.A.Q. for example).
And then you can link those over to nice mkdocs-material on e.g. z-tokens.github.io or in the official github repo.
That way, if project changes hands, it'd retain such documentation, it'd be properly versioned and forkable, not locked into being online-only on third-party domain, etc etc

[cipriancraciun]

As a third option, perhaps a compromise between the two previous ones (#25 (comment) and #25 (comment)), would be to embed in the executable some additional files and having them displayed as the result of a special flag, like for example:

## here `jagijedu` is a random token identifying the contextual information
z-tokens --explain jagijedu

## Explaining how bruteforce estimates are computed
=> updated information is vailable at https://links.volution.ro/z-tokens/jagijedu


...

This is similar to what rustc does, for example:

rustc --explain E0308

Expected type did not match the received type.

Erroneous code examples:
...

This has the advantage of working even without an internet connection (although it does display a link for further or perhaps more up-to-date information), and it also has the advantage of being always there where the user has the tool.

There are also some disadvantages though, first of all bloating the executable. But this is not an issue at the moment, because the executable is already quite bloated (due to the Rust and GlibC runtimes) and especially so in static builds.

[mk-fg]

Yeah, I think is kinda what Rust already does - bundling whole apps into one executable.
So it kinda makes sense to me to also bundle contents of doc/ repo subdir in there, and have its own "man" command.