generate canary.py script to check signatures from other server.

Author: unverbuggt

README.md

@@ -29,7 +29,7 @@ The content is encrypted with AES-256 in Python using PyCryptodome, and decrypte
 * ~~Rework password handling or inventory of some sort~~
 * ~~Rework crypto (PBKDF2 + AES256)~~
 * ~~Save the generated random keys instead of passwords to session( or local) storage~~
-* Sign generated generated and javascript files used in encrypted pages to make it more tamper proof
+* ~~Sign generated generated and javascript files used in encrypted pages to make it more tamper proof~~
 * ~~Add check for latin1 encoding in passwords, as it pycryptodome's implementation of PBKDF2 requires it~~
 * ~~find an equivalent way to define multiple passwords in the password inventory as global password~~
 * ~~make it possible to define passwords in external yaml file(s)~~
@@ -706,6 +706,37 @@ some_image_1_bb80db433751833b8f8b4ad23767c0fc.jpg
 
 > The file name obfuscation is currently applied to the whole site - not just the encrypted pages...
 
+### Signing of generated files
+
+An attacker would most likely have a hard time brute forcing your encrypted content, given a good
+password entropy. It would be much easier for him to fish for passwords by modifying the
+generated pages, if he is able to hack your web space.
+
+This feature will sign all encrypted pages and used javascript files with Ed25519. It will also generate
+an example [canary script](https://en.wikipedia.org/wiki/Domestic_canary#Miner's_canary), which can be
+customized to alert if files were modified.
+
+> **NOTE** If Mkdocs is running with `mkdocs serve`, then signature verification of encrypted pages
+> will most likely fail, because the files are modified by Mkdocs to enable live reload.
+
+```yaml
+      sign_files: 'signatures.json'
+      sign_key: 'encryptcontent.key' #optional
+      canary_template_path: '/path/to/canary.tpl.py' #optional
+```
+
+First an Ed25519 private key is generated at "encryptcontent.key" (besides `mkdocs.yml`), however you can supply an
+existing private key as long as it's in PEM format.
+
+After generation the signatures are saved to "signatures.json" in `site_dir`, so this file also needs to be uploaded
+to the web space. The canary script will download this file and compare the URLs to its own list and then download
+all files and verify the signatures.
+
+As long as the private key used for signing remains secret, the canary script will be able to determine
+if someone tampered with the files on the server. But you should run the canary script from another machine
+that is not related to the server, otherwise the attacker could also modify the canary script or sign with his
+private key instead.
+
 # Contributing
 
 From reporting a bug to submitting a pull request: every contribution is appreciated and welcome.

encryptcontent/canary.tpl.py

@@ -0,0 +1,40 @@
+import json
+import base64
+from Crypto.Hash import SHA512
+from Crypto.PublicKey import ECC
+from Crypto.Signature import eddsa
+from urllib.request import urlopen
+
+publickey = """{{ public_key }}"""
+
+signature_url = '{{ signature_url }}'
+
+urls_to_verify = {{ urls_to_verify }}
+
+def __verify_url__(url, signature, verifier):
+    h = SHA512.new()
+    with urlopen(url) as response:
+        h.update(response.read())
+    try:
+        verifier.verify(h, signature)
+        return True
+    except ValueError:
+        return False
+
+verifier = eddsa.new(ECC.import_key(publickey), 'rfc8032')
+
+print("NOTE: Checking of generated pages while 'mkdocs serve' will fail, because they are modified with the livereload script")
+
+try:
+    with urlopen(signature_url) as response:
+        signatures = json.loads(response.read())
+        for url in urls_to_verify:
+            if url not in signatures.keys():
+                print(url + ": MISSING!") # signature_url modified or just need to recreate canary script?
+            else:
+                if __verify_url__(url, base64.b64decode(signatures[url]), verifier):
+                    print(url + ": ok")
+                else:
+                    print(url + ": FAILED!") # file modified!
+except:
+    print("Couldn't download signatures!")

encryptcontent/plugin.py

@@ -84,6 +84,7 @@ class encryptContentPlugin(BasePlugin):
         ('html_extra_vars', config_options.Type(dict, default={})),
         ('js_template_path', config_options.Type(string_types, default=str(os.path.join(PLUGIN_DIR, 'decrypt-contents.tpl.js')))),
         ('js_extra_vars', config_options.Type(dict, default={})),
+        ('canary_template_path', config_options.Type(string_types, default=str(os.path.join(PLUGIN_DIR, 'canary.tpl.py')))),
         # others features
         ('encrypted_something', config_options.Type(dict, default={})),
         ('search_index', config_options.Choice(('clear', 'dynamically', 'encrypted'), default='encrypted')),
@@ -315,6 +316,9 @@ def on_config(self, config, **kwargs):
         logger.debug('Load JS template from file: "{file}".'.format(file=str(self.config['js_template_path'])))
         with open(self.config['js_template_path'], 'r') as template_js:
             self.setup['js_template'] = template_js.read()
+        logger.debug('Load canary template from file: "{file}".'.format(file=str(self.config['canary_template_path'])))
+        with open(self.config['canary_template_path'], 'r') as template_html:
+            self.setup['canary_template'] = template_html.read()
 
         # Check if hljs feature need to be enabled, based on theme configuration
         if ('highlightjs' in config['theme']._vars
@@ -361,6 +365,8 @@ def on_config(self, config, **kwargs):
         # Get path to site in case of subdir in site_url
         self.setup['site_path'] = urlsplit(config.data["site_url"] or '/').path[1::]
 
+        self.setup['config_path'] = Path(config['config_file_path']).parents[0]
+
         self.setup['search_plugin_found'] = False
         encryptcontent_plugin_found = False
         for plugin in config['plugins']:
@@ -421,8 +427,7 @@ def on_config(self, config, **kwargs):
                 self.setup['level_keystore'][level] = new_entry
 
         if self.config['sign_files']:
-            configpath = Path(config['config_file_path']).parents[0]
-            sign_key_path = configpath.joinpath(self.config['sign_key'])
+            sign_key_path = self.setup['config_path'].joinpath(self.config['sign_key'])
             if not exists(sign_key_path):
                 logger.info('Generating signing key and saving to "{file}".'.format(file=str(self.config['sign_key'])))
                 key = ECC.generate(curve='Ed25519')
@@ -470,8 +475,7 @@ def on_pre_build(self, config, **kwargs):
         if self.config['selfhost'] and self.config['selfhost_download']:
             logger.info('Downloading cryptojs for self-hosting (if needed)...')
             if self.config['selfhost_dir']:
-                configpath = Path(config['config_file_path']).parents[0]
-                dlpath = configpath.joinpath(self.config['selfhost_dir'] + '/assets/javascripts/cryptojs/')
+                dlpath = self.setup['config_path'].joinpath(self.config['selfhost_dir'] + '/assets/javascripts/cryptojs/')
             else:
                 dlpath = Path(config.data['docs_dir'] + '/assets/javascripts/cryptojs/')
             dlpath.mkdir(parents=True, exist_ok=True)
@@ -774,7 +778,7 @@ def on_post_build(self, config, **kwargs):
                 new_entry = {}
                 if self.config['selfhost']:
                     new_entry['file'] = Path(config.data["site_dir"] + '/assets/javascripts/cryptojs/' + jsurl[0].rsplit('/',1)[1])
-                    new_entry['url'] = config.data["site_url"] + '/assets/javascripts/cryptojs/' + jsurl[0].rsplit('/',1)[1]
+                    new_entry['url'] = config.data["site_url"] + 'assets/javascripts/cryptojs/' + jsurl[0].rsplit('/',1)[1]
                 else:
                     new_entry['file'] =  ""
                     new_entry['url'] = "https:" + jsurl[0]
@@ -838,3 +842,12 @@ def on_post_build(self, config, **kwargs):
                 sign_file_path = Path(config.data["site_dir"] + '/' + self.config['sign_files'])
                 with open(sign_file_path, "w") as file:
                     file.write(json.dumps(signatures))
+
+            canary_file = self.setup['config_path'].joinpath('canary.py')
+            if not exists(canary_file):
+                canary_py = Template(self.setup['canary_template']).render({
+                    'public_key': self.setup['sign_key'].public_key().export_key(format='PEM'),
+                    'signature_url' : config.data["site_url"] + self.config['sign_files']
+                })
+                with open(canary_file, 'w') as file:
+                    file.write(canary_py)

setup.py

@@ -49,6 +49,7 @@ def read(fname):
     package_data={'encryptcontent': [
         '*.tpl.js',
         '*.tpl.html',
+        '*.tpl.py',
         'contrib/templates/search/*.js'
     ]},
     include_package_data=True