update documentation: kdf caching and share link generation

Author: unverbuggt

README.md

@@ -38,7 +38,7 @@ The content is encrypted with AES-256 in Python using PyCryptodome and decrypted
 * ~~localStorage option is rather useless now (being unsafe to start with). Fix it nevertheless by saving credentials instead of keys~~
 * Update/Restructure documentation
 * Quick share links
-* Implement keystore cache to speed up build time
+* ~~Implement keystore cache to speed up build time~~
 
 ## Todos for 3.1.x
 * optional server side keystore (allows throtteling)
@@ -60,6 +60,7 @@ The content is encrypted with AES-256 in Python using PyCryptodome and decrypted
 		* [Add button](#Add-button)
 		* [Tag encrypted page](#Tag-encrypted-page)
 		* [Remember password](#Remember-password)
+		* [Share link generation](#Share-link-generation)
 	* [Modify generated pages](#Modify-generated-pages)
 		* [Encrypt something](#Encrypt-something)
 		* [Inject decrypt-form.tpl to theme](#Inject-decrypt-form.tpl-to-theme)
@@ -91,7 +92,7 @@ Install the package from source with pip:
 ```bash
 cd mkdocs-encryptcontent-plugin/
 python setup.py sdist bdist_wheel
-pip install --force-reinstall --no-deps dist/mkdocs_encryptcontent_plugin-3.0.0.dev3-py3-none-any.whl
+pip install --force-reinstall --no-deps dist/mkdocs_encryptcontent_plugin-3.0.0.dev4-py3-none-any.whl
 ```
 
 Enable the plugin in your `mkdocs.yml`:
@@ -462,6 +463,29 @@ plugins:
         remember_prefix: secretsite_
 ```
 
+### Share link generation
+
+It is possible to share valid credentials by adding them to the hash part of the URL.
+The plugin can also generate share links for certain pages if the metag tag `sharelink: true`
+is defined in markdown.
+It will use the first credential for the pages level or the pages password.
+The credentials for auto-generated links are base64url encoded.
+
+```yaml
+plugins:
+    - encryptcontent:
+        sharelinks: True
+        sharelinks_output: 'sharelinks.txt' # generated share links are saved here
+```
+> One condition applies: The user name must not contain the ":" character (Passwords may use that character).
+
+However if `sharelinks: True` is enabled in the plugin configuration you can generate share links yourself:\
+`https://your-domain.com/your-site/protected-page/#!username:password` for user/password or\
+`https://your-domain.com/your-site/protected-page/#!password` for only password.
+
+> Then another condition applies: If non-aphanumeric characters are used in user/password,
+> they need to be URLencoded (f.ex. %20 = space character). Some browsers may do that automatically (Do a copy/paste from the browsers address bar then).
+
 title: Modify pages
 
 ## Modify generated pages
@@ -864,6 +888,22 @@ plugins:
         selfhost_dir: 'theme_overrides'
 ```
 
+#### KDF key generation caching
+
+Either way (webcrypto or crypto-js) the [KDF](https://en.wikipedia.org/wiki/Key_derivation_function)
+key generation needs to be done for each credential.
+This may take some additional time when building the site, especially when there are many different ones.
+That's why these keys and salt are cached by default to a yaml file named "encryptcontent.cache".
+
+```yaml
+plugins:
+    - encryptcontent:
+        cache_file: 'encryptcontent.cache' # change file name if needed
+```
+
+Caching can be disabled by setting `cache_file: ''`.
+
+
 ### File name obfuscation
 
 Imagine your pages contain many images and you labeled them "1.jpg", "2.jpg" and so on for some reason.

documentation/docs/features/index.md

@@ -122,3 +122,26 @@ plugins:
         remember_password: False
         remember_prefix: secretsite_
 ```
+
+### Share link generation
+
+It is possible to share valid credentials by adding them to the hash part of the URL.
+The plugin can also generate share links for certain pages if the metag tag `sharelink: true`
+is defined in markdown.
+It will use the first credential for the pages level or the pages password.
+The credentials for auto-generated links are base64url encoded.
+
+```yaml
+plugins:
+    - encryptcontent:
+        sharelinks: True
+        sharelinks_output: 'sharelinks.txt' # generated share links are saved here
+```
+> One condition applies: The user name must not contain the ":" character (Passwords may use that character).
+
+However if `sharelinks: True` is enabled in the plugin configuration you can generate share links yourself:\
+`https://your-domain.com/your-site/protected-page/#!username:password` for user/password or\
+`https://your-domain.com/your-site/protected-page/#!password` for only password.
+
+> Then another condition applies: If non-aphanumeric characters are used in user/password,
+> they need to be URLencoded (f.ex. %20 = space character). Some browsers may do that automatically (Do a copy/paste from the browsers address bar then).

documentation/docs/features/security.md

@@ -31,6 +31,22 @@ plugins:
         selfhost_dir: 'theme_overrides'
 ```
 
+#### KDF key generation caching
+
+Either way (webcrypto or crypto-js) the [KDF](https://en.wikipedia.org/wiki/Key_derivation_function)
+key generation needs to be done for each credential.
+This may take some additional time when building the site, especially when there are many different ones.
+That's why these keys and salt are cached by default to a yaml file named "encryptcontent.cache".
+
+```yaml
+plugins:
+    - encryptcontent:
+        cache_file: 'encryptcontent.cache' # change file name if needed
+```
+
+Caching can be disabled by setting `cache_file: ''`.
+
+
 ### File name obfuscation
 
 Imagine your pages contain many images and you labeled them "1.jpg", "2.jpg" and so on for some reason.

documentation/docs/index.md

@@ -34,7 +34,7 @@ The content is encrypted with AES-256 in Python using PyCryptodome and decrypted
 * ~~localStorage option is rather useless now (being unsafe to start with). Fix it nevertheless by saving credentials instead of keys~~
 * Update/Restructure documentation
 * Quick share links
-* Implement keystore cache to speed up build time
+* ~~Implement keystore cache to speed up build time~~
 
 ## Todos for 3.1.x
 * optional server side keystore (allows throtteling)

documentation/docs/installation.md

@@ -13,7 +13,7 @@ Install the package from source with pip:
 ```bash
 cd mkdocs-encryptcontent-plugin/
 python setup.py sdist bdist_wheel
-pip install --force-reinstall --no-deps dist/mkdocs_encryptcontent_plugin-3.0.0.dev3-py3-none-any.whl
+pip install --force-reinstall --no-deps dist/mkdocs_encryptcontent_plugin-3.0.0.dev4-py3-none-any.whl
 ```
 
 Enable the plugin in your `mkdocs.yml`:

documentation/encryptcontent.cache

@@ -0,0 +1,28 @@
+kdf_iterations: 100000
+obfuscate:
+  Crawler be gone!: 6c85ed748c5c1145fdc8a184e24d4b65cab4a2fdfa6d04271bd45d0d75252f10;fc94a75a1c37d86949e102c19c471661
+  Kriechtier hau ab!: 5bb63ecf17cd85bb16f67cf62a6faa9bcf6d7cb1c3f357e1dadab310408edb81;a26ae8eefa2054396aed5e9945d647f0
+password:
+  Password if PASSWORD2_FROM_ENV undefined or empty: cdcb0e2f5611344df32232f4924a865d8575829493e0c32fc0a877c44b615fed;0c10711b75c50efe30ea520cbf45d72e
+  acid: 28819579c5f6f09ce77b3eca8b3ffa4638980388aba6092d2bd31431965efed9;5f6a7fe0244d998db0b93fdac8d9d215
+  flashlight: e1f34579953e15abed57884ac190d21c16184eb8143c543c8caf79044273d86f;e53b6f4203b78ac25d87145a95cd16ff
+  fryingpan: e9c73a136b667b2a8097002956bf251b17c5f72ab62fba558ba94df01a0e88ce;145ad52d80fdfddcf368620e6e42f30d
+  "mu\xDF": b2b71e06b6d827dc547be0f13642293940fc37062dcbf25e4b05b1a7f8e7b025;3c6cffa4ccb427bc1a41ce70973a9c7d
+  "m\xE4h": e40f992f4c2e665772f7ee472479c5769fc446c758712d5a6c2ba3f58f029f4d;df67e8df334cd52598802858529c1b26
+  "m\xE9h": 1f034099dac99d3355b009964d36d3cd9038a5f2d579f2cf4625dccaa01a5e5d;0f43a7ea19bb0a91cde51a9f717bc02d
+  "m\xF6h": ffe781807607b03beeaa2da3d61f9df24b296ef233bef4301846b488219762c3;d9ae674a7cc325233f1906915c8c107c
+  "m\xFCh": 4c31fc043fc53597220e199302eb0c4271e979978a3c527d358eb85be7a6f8b6;fb1462be9891c5f042c9d8c0eb492df4
+  passport: 0f0ab4b95363dfd03388fecb20f6e1cd247447ffeb51cfd01d757fb667234b6c;fbfa54194fe497b3cd4568edefe7049a
+  sassy: a5f91c014f6e1a4058a76304c95286d0735bfcce1fcb18957cc368e6cadb467e;018b2abdaaa6a23b5ba2380e1940e1d0
+  scientist: 657695a37e6271255afb9a89f4d229adcd86622261eee6fe63279909fe181114;0f5bc292cb6556858f6cd266fa4b49e7
+  squirrel: a97a5457d52dd77268b41d8e682144eb70396d37bd83747aa327b116cd31bc89;d360001094f15126b41f0124c55bf5fc
+  village: 3e86bec768a2cf5133a5d725386cd912d311b85ccaa083a93bd99fbe01127174;c32d42db5370e16d21211e3b9f2541e1
+userpass:
+  alice: faa7dd08aff2d7392330b3f570387d5384613cc01141f4919acd63e304360acf;c96bc316cde85658b243a9dc1b4f935e
+  bob: fdf567751b44a365f2e0f4dcf7f242c7e4d22b71a3ccd333ba6487fac85afe16;f5c92b67eba7bff15e5be06d3e7770b2
+  carlos: a6e884623832f1b25c1fb93e17e414f5bc176df7148db4a791e1839af8e96811;37c94e8d06eec2da656e350564ed164b
+  carol: b0ae627d2cd6809503098061e23afe38d770448cfc1eba3341a2fbfb0cec7f13;d77bd6fa44661ee2cf6c4bc4ac8b106e
+  charlie: 3434c70d48452b0416efe9dd1a8e1d51556190a149a87a9876f3cf156d19db52;bea92c4320faa6351e01a3f1cd79c59e
+  dan: aca8328553babc6b5701b35784f57db73904a1475efd20dfdb26db535c818687;89b4866e04f0b06ba8dedabe3bf3a634
+  dave: a2f6a86312d8dfd58fdd906fec79a499f48c2b7548a5a9962d75eb6558afcef1;f8532f4785686e438f2bc8f2627483fc
+  david: 41f3725e4e57467100e76b6dfa9b7dcd6b5aaa506e7cea9274e999110a3ce6f1;35bb13beb676f6e34d6bfbc3e24a6c45

documentation/mkdocs.yml

@@ -138,6 +138,7 @@ plugins:
         #kdf_pow: 4
         webcrypto: true
         sign_files: 'encryptcontent-plugin.json'
+        cache_file: 'encryptcontent.cache'
         hash_filenames:
           extensions:
             - 'png'

setup.py

@@ -11,7 +11,7 @@ def read(fname):
 
 setup(
     name='mkdocs-encryptcontent-plugin',
-    version='3.0.0.dev3',
+    version='3.0.0.dev4',
     author='unverbuggt',
     author_email='[email protected]',
     description='A MkDocs plugin that encrypt/decrypt markdown content with AES',