Package: docums-encryptcontent-plugin
docums-encryptcontent-pluginThis plugin allows you to have password protected articles and pages in Docums.The content is encrypted with AES-256 in Python using PyCryptodome, and decrypted in the browser with Crypto-JS.It has been tested in Python Python 3.5+UsecaseI want to be able to protect the content of the page with a password.Define a password to protect each page independently or a global password to protect them all.If a global password exists, all articles and pages are protected with this password.If a password is defined in an article or a page, it is always used even if there is a global password.If a password is defined as an empty character string, the content is not protected.Table of ContentsInstallationUsageGlobal password protectionCustomizationFeaturesHighlightJS support(default)Arithmatex support(default)Tag encrypted page(default)Rebember passwordEncrypt somethingSearch index encryptionAdd buttonReload scriptsContributingInstallationInstall the package with pip:pipinstalldocums-encryptcontent-pluginInstall the package from source with pip:cddocums-encryptcontent-plugin/
python3setup.pysdistbdist_wheel
pip3installdist/docums_encryptcontent_plugin-2.0.1-py3-none-any.whlEnable the plugin in yourdocums.yml:plugins:-search:{}-encryptcontent:{}NOTE:If you have nopluginsentry in your configuration file yet, you'll likely also want to add thesearchplugin. Docums enables it by default if there is nopluginsentry set, but now you have to enable it explicitly.UsageAdd an meta tagpassword: secret_passwordin your markdown files to protect them.Global password protectionAddglobal_password: your_passwordin plugin configuration variable, to protect by default your articles with this passwordplugins:-encryptcontent:global_password:'your_password'If a password is defined in an article, it willALWAYSoverwrite the global password.NOTEKeep in mind that if thepassword:tag exists without value in an article, it willnot be protected!Extra vars customizationOptionally you can use some extra variables in plugin configuration to customize default messages.plugins:-encryptcontent:title_prefix:'[LOCK]'summary:'anotherinformationalmessagetoencryptedcontent'placeholder:'anotherpasswordplaceholder'decryption_failure_message:'anotherinformationalmessagewhendecryptionfail'encryption_info_message:'anotherinformationmessagewhenyoudonthaveacess!'Default prefix title is[Protected].Default summary message isThis content is protected with AES encryption..Default password palceholder isProvide password and press ENTER.Default decryption failure message isInvalid password..Defaut encryption information message isContact your administrator for access to this page..NOTEAdding a prefix to the title does not change the default navigation path !FeaturesHighlightJS supportEnable by defaultIf 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 addinghljs: Trueon the plugin configuration or sethljs: Falseto disable this feature.When enable the following part of the template is add to force reloading decrypted content.{%ifhljs%}document.getElementById("docums-decrypted-content").querySelectorAll('pre code').forEach((block) => {hljs.highlightBlock(block);});{%endif%}Arithmatex supportEnable by defaultIf 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 addingarithmatex: Trueon the plugin configuration or setarithmatex: Falseto disable this feature.When enable, the following part of the template is add to force math equations rendering on decrypted content.{%ifarithmatex%}MathJax.typesetPromise(){%endif%}NOTEIt has been tested in Arithmatexgenericmode only.Tag encrypted pageEnable by defaultThis feature add an additional attributeencryptedwith valueTrueto the docums typedocums.nav.pageobject.You can addtag_encrypted_page: Falsein plugin configuration, to disable tagging of encrypted pages.BUTThis feature is neccessary for others feature working correctly. If you disable this feature, do no useEncrypt Somethings,When enable, it becomes possible to useencryptedattribute in the jinja template of your theme, as a condition to perform custom modification.{%-fornav_iteminnav%}{%ifnav_item.encrypted%}<!-- Do something -->{%endif%}{%-endfor%}For example, in your theme template, you can use conditional check to add custom class :<a{%ifnav_item.encrypted%}class="docums-encrypted-class"{%endif%}href="{{nav_item.url|url}}">{{nav_item.title}}</a>Add buttonAddpassword_button: Truein plugin config variable, to add button to the right of the password field decrypt the content.Optionnally, you can addpassword_button_text: 'custome_text_button'to customize the button text.plugins:-encryptcontent:password_button:Truepassword_button_text:'custome_text_button'Rebember password:warning:This feature is not really secure !Password are store in clear text inside local storage.Instead of using this feature, I recommend to use a password manager with its web plugins.
For exampleKeepassXCallows you, with a simple keyboard shortcut, to detect the password fielddocums-content-passwordand to fill it automatically in a much more secure way.If you do not have password manager, you can setremember_password: Truein yourdocums.ymlto enable password remember feature.When enabled, each time you fill password form and pressEntera key on local storage is create with your password
as value. When you reload the page, if you already have an 'encryptcontent' key in the local storage of your browser,
the page will be automatically decrypted using the value previously created.By default, the key is created with a name relative to the page on which it was generated.
This 'relative' key will always be used as first attempt to decrypt the current page when loading.If your password is aglobal password, you can fill in the form fielddocums-content-password, then use the keyboard shortcutCTRL + ENTERinstead of the classicENTER.
The key that will be created with a generic name to making it accessible, by default, on all the pages of your site.The form of decryption remains visible as long as the content has not been successfully decrypted, which allows in case of error to retry.
All keys created with this feature on localstorage have an default expire time daly set to 24 hours, just cause ...However(optionally), its possible to change the default expire time by setting optionsdefault_expire_dalay: <number>in yourdocums.yml. Your configuration should look like this when you enabled this feature :plugins:-encryptcontent:remember_password:Truedefault_expire_dalay:24# <-- Default expire delay in hours (optional)NOTEThe expired elements of the localStorage are only deleted by the execution of the decrypt-content.js scripts and therefore by the navigation on the site. Secret items can therefore remain visible in local storage after their expiration dates.Encrypt somethingThetag encrypted page featureMUSTbe enabled (it's default) for this feature to work properly.Addencrypted_something: {}in the plugin configuration variable, to encrypt something else.The syntax of this new variableMUSTfollow the yaml format of a dictionary.
Child elements ofencrypted_somethingare build with a key<unique name>in string format and a list as value.
The list have to be contructed with the name of an HTML element<html tag>as first item andidorclassas the second item.plugins:-encryptcontent:encrypted_something:<uniq name>:[<html tag>,<'class' or 'id'>]The<unique name>key identifies the name of a specific element of the page that will be searched by beautifulSoup.
The first value of the<html tag>list identifies the type of HTML tag in which the name is present.
The second value of the list, as string'id'or'class', specifies the type of the attribute which contains the unique name in the html tag.Prefer to use an'id', however depending on the template of your theme, it is not always possible to use the id.
So we can use the class attribute to define your unique name inside html tag.
BeautifulSoup will encrypt all HTML elements discovered with the class.When the feature is enabled, you can use any methods(password, button, remember)to decrypt every elements encrypted on the page.By defaultevery child itemsare encrypted and the encrypted elements havestyle=display:noneto hide their content.How to use it :exploding_head: ?! ExamplesUse thepage.encryptedconditions to add attributes of type id or class in the HTML templates of your theme.
Each attribute is identified with a unique name and is contained in an html element.
Then add these elements in the format of a yaml dictionary under the variableencrypted_something.For example, encrypt ToC in a theme where ToC is under 'div' element like this :<div class=".."{%ifpage.encrypted%}id="docums-encrypted-toc"{%endif%}><ul class=".."><li class=".."><a href="{{toc_item.url}}">{{toc_item.title}}</a></li><li><a href="{{toc_item.url}}">{{toc_item.title}}</a></li></ul></div>Set your configuration like this :plugins:-encryptcontent:encrypted_something:docums-encrypted-toc:[div,id]Other example, with multiples target. In you Material Theme, you want to encrypt ToC content and Footer.Materiel generate 2<nav>structure with the same templatetoc.html, so you need to use aclassinstead of an id for this part.
The footer part, is generated by thefooter.htmltemplate in a classic div so anidis sufficientAfter modification, your template looks like this :<nav class="md-nav md-nav--secondary{%ifpage.encrypted%}docums-encrypted-toc{%endif%}" aria-label="{{lang.t('toc.title')}}"><label class="md-nav__title" for="__toc"> ... </label><ul class="md-nav__list" data-md-scrollfix> ... </ul></nav><footer class="md-footer"><div class="md-footer-nav"{%ifpage.encrypted%}id="docums-encrypted-footer"{%endif%}> ... </div><div class="md-footer-meta md-typeset"{%ifpage.encrypted%}id="docums-encrypted-footer-meta"{%endif%}></footer>Your configuration like this :plugins:-encryptcontent:encrypted_something:docums-encrypted-toc:[nav,class]docums-encrypted-footer:[div,id]docums-encrypted-footer-meta:[div,id]Search index encryptionDefault value is "encrypted":warning:The configuration mode "clear" of this functionality can cause DATA LEAKThe unencrypted content of each page is accessible through the search index.
Not encrypting the search index means completely removing the protection provided by this plugin.
You have been warnedThis feature allows you to control the behavior of the encryption plugin with the search index.
Three configuration modes are possible:clear: Search index is not encrypted. Search is possible even on protected pages.dynamically: Search index is encrypted on build. Search is possible once the pages have been decrypted ones.encrypted: Search index is encrypted on build. Search is not possible on all encrypted pages.You can setsearch_index: '<mode_name>'in yourdocums.ymlto change the search index encryption mode. Possible values areclear,dynamically,encrypted. The default mode is "encrypted".plugins:-encryptcontent:search_index:'dynamically'This functionality overwrite the index creation function of the “search” plug-in provided by docums. The modifications carried out make it possible to encrypt the content of the search indexafterthe default plugin has carried out these treatments(search configuration). It is therefore dependent on the default search plugin.When the configuration mode is set to "dynamically", thejavascripts contribution filesare used to override the default search plugin files provided by Docums. They include a process of decrypting and keeping the search index in a SessionStorage.NOTEThe mode 'dynamically' is currentlynot compatible with Material Theme!Add buttonAddpassword_button: Truein plugin configuration variable, to add button to the right of the password field.When enable, it allows to decrypt the content just like the classic keypress ENTER. If remember password feature is activated, use button to decrypt generate a 'relative' key on your local storage. You cannot use password button to create global password value.Optionnally, you can addpassword_button_text: 'custom_text_button'to customize the button text.plugins:-encryptcontent:password_button:Truepassword_button_text:'custom_text_button'Reload scriptsYou can setreload_scripts:in yourdocums.ymlwith list of script source, to reload and execute some js lib after decryption process.plugins:reload_scripts:-"./js/example.js"This feature use the following JQuery function to remove, add and reload javascripts.varreload_js=function(src){$('script[src="'+src+'"]').remove();$('<script>').attr('src',src).appendTo('head');};