generate README.md from documentation folder

Author: unverbuggt

.gitignore

@@ -8,3 +8,4 @@ deploy.cmd
 documentation/encryptcontent.key
 documentation/canary.py
 documentation/theme_override/assets/
+documentation/__pycache__/

README.md

@@ -0,0 +1,41 @@
+<div id="mkdocs-encrypted-content" style="display:none">{{ ciphertext_bundle }}</div>
+<div id="mkdocs-decrypted-content">
+    <form id="mkdocs-decrypt-form"{% if form_class %} class="{{ form_class }}"{% endif %}>
+        <h1>{{ summary }}</h1>
+        {% if encryption_info_message %}<p>{{ encryption_info_message }}</p>{% endif %}
+        <div class="w3-row-padding" style="padding-left: 0px;">
+        {%- if obfuscate %}
+        <input type="hidden" id="mkdocs-content-password" value="{{ obfuscate_password }}" />
+        {%- else %}
+            {%- if uname %}
+          <div class="w3-third">
+            <input{% if input_class %} class="{{ input_class }}"{% endif %} type="text" id="mkdocs-content-user" placeholder="{{ placeholder_user }}" />
+          </div>
+            {%- endif %}
+          <div class="w3-third">
+            <input{% if input_class %} class="{{ input_class }}"{% endif %} type="password" id="mkdocs-content-password" placeholder="{{ placeholder }}" />
+          </div>
+        {%- endif %}
+        {%- if password_button %}
+          <div class="w3-third">
+            <button{% if button_class %} class="{{ button_class }}"{% endif %} id="mkdocs-decrypt-button">{{ password_button_text }}</button>
+          </div>
+        {% endif -%}
+        </div>
+        <p id="mkdocs-decrypt-msg"></p>
+    </form>
+</div>
+
+<script type="text/javascript">
+var encryptcontent_id = "{{ encryptcontent_id }}";
+var encryptcontent_path = "{{ encryptcontent_path }}";
+var decryption_failure_message = {{ decryption_failure_message }};
+var encryptcontent_keystore = {{ encryptcontent_keystore }};
+var encryptcontent_obfuscate = {{ obfuscate }};
+{% if inject_something %}var inject_something = {{ inject_something }};{% endif -%}
+{% if delete_something %}var delete_something = "{{ delete_something }}";{%- endif %}
+</script>
+{% for library in js_libraries %}
+<script type="text/javascript" src="{{ library }}"></script>
+{%- endfor %}
+<script type="text/javascript" src="{{ base_path }}assets/javascripts/decrypt-contents.js" defer></script>

documentation/decrypt-form.tpl.html

@@ -0,0 +1,77 @@
+# How does this work?
+
+For every `password` and for every `level` we generate a random 256 bit key.
+This key will be used for AES-256 encryption on every page with the same `password` or same `level`.
+Optionally search entries and [encrypt something](#encrypt-something)<!--todo--> on that page are also encrypted with the same key.
+
+This random secret key (needed for deciphering the pages content) is then encrypted to a keystore with another key that is derived from
+the defined credentials (a password or a username/password pair).
+If the credential is reused on another `level`, then its random key is also encrypted in the same keystore.
+The function to derive the key to the keystore (PBKDF2) can be adjusted in calculation cycles
+to hopefully throttle the number of passwords a brute force attacker is able to try per second.
+
+![](img/howitworks.svg)
+
+#### AES
+
+Is a symmetric encryption algorithm. Symmetric means it uses the same secret key for encryption and decryption.
+The size of the secret keys used in this plugin is 256 Bit (or 32 Bytes).\
+Additionally a random (16 Bytes) initialization vector (called IV) is used (and added to the cyphertext)
+to make sure the same plaintext will always result in a different cyphertext even if the same secret key is used
+for encryption.
+
+#### KDF
+
+A **K**ey **D**erivation **F**unction a one-way key generation algorithm,
+so it is not possible to reverse the function to retrieve a lost password.\
+The password is salted, meaning if two people used the same password it would lead to different keys (similar to IV in AES).\
+It is equipped with adjustable difficulty `kdf_pow`. The difficulty has significant weight on the build time and also
+the time needed to decrypt a page, so it shouldn't be increased to any value.\
+The algorithm used (PBKDF2) is not really state-of-the-art, meaning compared to better alternatives like bcrypt, scrypt or argon2
+it is easier to crack with hardware acceleration, however it is supported in both crypto-js and webcrypto and
+is significantly better than MD5 (which was used on all versions prior to 3.x) for key derivation.\
+The secret key derived from PBKDF2 is used to decrypt the keystore containing different keys to decrypt the content.
+
+# A word on password strength
+
+The strength of a password can be measured in entropy or "possibilities to try" (for a brute force attacker).
+
+\[
+S = C^{L} * T
+\]
+
+**S** is the time it takes to try all possibilities (on average a password is found after trying half the possibilities),
+**C** being the number of different characters the password is made of, **L** being the length of the password
+and **T** the time it takes to try one password.
+
+For example take a tree character password with just lower case letters like "abc".  
+The number of lower case letters is 26, so a three character password leads to 26 * 26 * 26 = 17 576 possibilities to try.
+
+Now take a three character password which also includes upper case letters like "aBc".  
+The number of possibilities per character doubles to 52, so the three character password leads to 52 * 52 * 52 = 140 608 possibilities.
+So compared to "abc" we got **eight times** more entropy in this case.
+
+So what happens if we add one character and still only use lower case letters, like "abcd"?  
+It's 26^4 = 456 976 with a four character password, that's **26 times** more entropy compared to only using three lower case characters.
+
+It's easier to get higher entropy by increasing password size, than with adding more different characters or symbols.
+An attacker could also have watched (or heard) you type the password (paying attention to the use of the shift key,
+space bar or numeric keypad) and this way cross out character that you couldn't possibly have used.
+
+So, to put it mildly: Every web page that forces you to use at least lower/upper case AND a number AND a symbol,
+BUT only forces you to use eight characters of password size is not steering you to the right measures to gain entropy.
+
+But, to be fair: A web page can take measures to seriously throttle the passwords try-able per second on the server side
+or f.ex. use captchas after the third failed try. Although there were and most likely will be bad or failed examples of those measures.
+
+This Mkdocs plugin can currently only take additional counter-measures to brute force attacks in form of PBKDF2.
+PBKDF2 itself is more or less obsolete, because it got no defense against being run in parallel, so we should
+consider it to not having a big effect on **T**.
+Other options like bcrypt, scrypt od argon2 exist, but pbkdf2 is the only option
+currently available in crypto-js and webcrypto. However there may be limitations that render the other option impractical,
+like logner build times and high computing or memory requirements on mobile devices.
+So you should really be interested in choosing a **long** password or pass phrases
+(read the [Diceware article on Wikipedia](https://en.wikipedia.org/wiki/Diceware), [xkcd webcomic on password strength](https://xkcd.com/936/)
+and [this blogpost](https://blog.benpri.me/blog/2019/01/13/why-you-shouldnt-be-using-bcrypt-and-scrypt/)).
+
+

documentation/docs/explanations.md

@@ -0,0 +1,124 @@
+title: Features
+
+# Features
+
+### Override default templates
+
+Related to [issue #32](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/32)
+
+You can override the default templates with your own templates by providing an actual replacement
+path in the `html_template_path` *(HTML)* and `js_template_path` *(JS)* directives. 
+Overridden templates **completely** replace the default templates. You **must** therefore copy the
+default templates as a starting point to keep this plugin working.
+
+```yaml
+plugins:
+    - encryptcontent:
+        html_template_path: "/root/real/path/mkdocs_poc/my_html_template.html"
+        js_template_path: "/root/real/path/mkdocs_poc/my_js_template.js"
+        form_class: 'md-content__inner md-typeset'
+        input_class: 'md-input'
+        button_class: 'md-button md-button--primary'
+```
+
+Use `form_class`, `input_class` and `button_class` to optionally set a CSS class for the password input field and the button.
+
+When overriding the default templates, you can add and use your own Jinja variables
+and enrich your template, by defining `html_extra_vars` and `js_extra_vars` directives in key/value format.
+Added values can be used in your Jinja templates via the variable `extra`.
+
+```yaml
+plugins:
+    - encryptcontent:
+        html_extra_vars:
+            my_extra: "extra value"
+            <key>: <value>
+        js_extra_vars:
+            my_extra: "extra value"
+            <key>: <value>
+```
+
+For example, you can modify your HTML template, to add a new title with your own text variable.
+
+```jinja
+[ ... ] 
+<h2>{{ extra.my_extra }}</h2>
+[ ... ]
+```
+
+> **NOTE** Issues related to template override will not be addressed.
+
+### Add button
+
+Add `password_button: True` in plugin configuration variable, to add a button to the right of the password field.
+
+When enabled, it allows to decrypt the content just like the classic keypress ENTER.
+
+Optionally, you can add `password_button_text: 'custom_text_button'` to customize the button text.
+ 
+```yaml
+plugins:
+    - encryptcontent:
+        password_button: True
+        password_button_text: 'custom_text_button'
+```
+
+### Tag encrypted page
+
+> **Enable by default**
+
+Related to [issue #7](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/7)
+
+This feature adds an additional attribute `encrypted` with value `True` to the mkdocs type `mkdocs.nav.page` object.
+
+You can add `tag_encrypted_page: False` in plugin configuration, to disable tagging of encrypted pages. 
+
+When enabled, it is possible to use the `encrypted` attribute in the jinja template of your theme, as a condition to perform custom modification.
+
+```jinja
+{%- for nav_item in nav %}
+    {% if nav_item.encrypted %}
+        <!-- Do something --> 
+    {% endif %}
+{%- endfor %}
+```
+
+For example, you can use conditional check to add a custom class:
+
+```jinja
+<a {% if nav_item.encrypted %}class="mkdocs-encrypted-class"{% endif %}href="{{ nav_item.url|url }}">{{ nav_item.title }}</a>
+```
+
+### Remember password
+
+Related to [issue #6](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/6)
+
+By default the plugin will save the decrypted AES keys to session storage of the browser (can be disabled by setting `remember_keys: False`).
+This is enabled for convenience, so you are able to browse between multiple encrypted pages without having to re-enter the password.
+
+Additionally it is possible to save the entered user/password in session storage (setting `remember_password: True`). Use this for
+additional convenience during `mkdocs serve`, because the AES key are regenerated every time MkDocs starts
+(rendering the old ones invalid and requiring to re-enter a valid credential again).
+
+To avoid problems when multiple sites are hosted within the same domain, it is possible to customize the name of
+the keys saved to storage with `remember_prefix`.
+
+> **This feature is not really secure !** decryption keys are store in clear text inside session storage.
+>
+> Instead of using these features, I recommend to use a password manager with its browser plugin.
+> For example **KeepassXC** allows you to detect the password field
+> `mkdocs-content-password` and fill it automatically in a much more secure way.
+
+It is also possible to save the used credentials permanently to local storage (setting `session_storage: False`), but
+this should only be done for testing purposes. The local storage of a browser is most likely readable
+for every other process that can access the file system. 
+
+The session storage however should only be located in memory and be forgotten after the browser tab is closed.
+
+```yaml
+plugins:
+    - encryptcontent:
+        remember_keys : True
+        remember_password: False
+        remember_prefix: secretsite_
+```

documentation/docs/features/index.md

@@ -0,0 +1,121 @@
+title: Javascript extensions
+
+## Javascript extensions
+
+### Reload user-defined scripts
+
+Related to [issue #14](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/14)
+
+You can set `reload_scripts:` in your `mkdocs.yml` with list of script sources
+or script ids, to reload and execute some js lib after decryption process.
+
+```yaml
+plugins:
+    - encryptcontent:
+        reload_scripts:
+            - 'js/example.js'
+            - '#autoexec'
+```
+
+It is also possible to reload a script id like `<script id="autoexec">console.log('test');</script>`
+that was encrypted within the page
+(related to [issue #30](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/30)).
+
+
+### HighlightJS support
+
+> **Enable by default**
+
+If HighlightJS module is detected in your theme to improve code color rendering, reload renderer after
+decryption process.
+If HighlightJS module is not correctly detected, you can force the detection by adding `hljs: True`
+on the plugin configuration
+or set `hljs: False` to disable this feature.
+
+When enabled the following part of the template is added to force reloading decrypted content.
+
+```jinja
+{% if hljs %}
+document.getElementById("mkdocs-decrypted-content").querySelectorAll('pre code').forEach((block) => {
+    hljs.highlightElement(block);
+});
+{% endif %}
+```
+
+
+### Arithmatex support
+
+> **Enable by default**
+
+Related to [issue #12](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/12)
+
+If Arithmatex markdown extension is detected in your markdown extensions to improve math equations rendering,
+reload renderer after decryption process.
+If the Arithmatex markdown extension is not correctly detected, you can force the detection by adding
+`arithmatex: True` on the plugin configuration
+or set `arithmatex: False` to disable this feature.
+ 
+When enabled, the following part of the template is added to force math equations rendering on decrypted content.
+
+```jinja
+{% if arithmatex %}
+MathJax.typesetPromise()
+{% endif %}
+```
+
+> **NOTE** It has been tested in Arithmatex `generic` mode only. 
+
+
+### Mermaid2 support
+
+> **Enable by default**
+
+Related to [issue #22](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/issues/22)
+
+If mermaid2 plugin is detected in your configuration to generate graph from text, reload renderer after
+decryption process.
+If the Mermaid2 plugin is not correctly detected, you can force the detection by adding `mermaid2: True`
+on the plugin configuration
+or set `mermaid2: False` to disable this feature.
+ 
+When enabled, the following part of the template is added to force graph rendering on decrypted content.
+
+```jinja
+{% if mermaid2 %}
+mermaid.contentLoaded();
+{% endif %}
+```
+
+> **NOTE** it currently only works with mermaid version < 10. Also encryptcontent needs to be injected,
+> because the mermaid2 plugin otherwise won't detect the page content correctly.
+
+activate the plugin like this:
+
+```yaml
+plugins:
+    - mermaid2:
+        version: 9.4.3
+
+markdown_extensions:
+    - pymdownx.blocks.html
+```
+
+Example usage:
+
+````
+password: 1234
+inject_id: inject
+
+
+/// html | div#inject
+
+```mermaid
+graph LR
+    hello --> world
+    world --> again
+    again --> hello
+```
+
+///
+````
+