How to build the site reproducibly?

[oprypin]

What I want:

• Get any mkdocs site (sources) that uses the "encryptcontent" plugin https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/blob/version3/documentation/mkdocs.yml is definitely a suitable example
• Run mkdocs build --site-dir site1
• Run mkdocs build --site-dir site2
• Compare the directories and have them be identical (with diff -r site1 site2).

What I get instead:

Huge diffs https://github.com/mkdocs/regressions/actions/runs/6826747067/job/18567340779

Why I want this:

I check many random mkdocs sites and plugins to ensure that any change to mkdocs itself does not disrupt their function. So in my case the two mkdocs build commands actually use a different version of mkdocs but that's irrelevant here. This would allow me to add this plugin to my test coverage. Otherwise I won't be able to do that.

---

It's probably obvious to the plugin's author why this happens and it looks very intentional. The content is encrypted with random salt every time? https://github.com/search?q=repo%3Aunverbuggt%2Fmkdocs-encryptcontent-plugin+get_random_bytes%28&type=code

I would propose to add an environment variable such as MKDOCS_ENCRYPTCONTENT_CONSTANT_SALT that would be able to replace these random calls if present, or something like that.

[unverbuggt]

The content is encrypted with random salt every time?

yes, kind of: the intialization vector (called IV) of every AES encrypted string is randomized every time. This measure ensures, that the same plain text leads to different ciphertext.
Also, all AES keys are randomized every build, but this isn't exactly a security measure (at least I can't think of a reason that would strictly require this). It's more a measure to ensure that the AES keys are random, as they remain secret (and are decrypted though the KDF keys).

So the only way to safely encrypt the pages and make sure that every build produces the same output would be to save all IVs and all AES keys. As this would require a huge amount of effort it's not really something I'd invest time into.

If you only do this for testing (to check if mkdocs and all of it's plugins produce the same output), then I'd go for an insecure test mode that would set all IVs to a fixed value and also set all AES keys to different but deterministic values. Also display huge warnings to never upload this page anywhere.
Is this something that would help you do what you want?

[oprypin]

Thanks! Regarding the last paragraph: yes that is exactly what I'm asking for

[unverbuggt]

I've pushed changes that should lead to constant ciphertext output when insecure_test: true is defined. Please try it by cloning/installing the current development version and adding the following under the plugin configuration of mkdocs.yml:

    - encryptcontent:
        insecure_test: true

[oprypin]

Great! Thank you very much. It worked perfectly. https://github.com/mkdocs/regressions/actions/runs/6840922769/job/18600695060

Now just one more thing- I am actually interested in using this exact MkDocs site for my testing: https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/blob/version3/documentation/mkdocs.yml -ideally without creating a fork of it just for the purposes of setting this config option in mkdocs.yml

https://github.com/mkdocs/regressions/commit/6763245b4baa444bcf43837daadac74c3cf97099 To try this out, for now I added a workaround to edit the file on the fly, but if it could be avoided, that would be great.

So if you could please additionally edit this file https://github.com/unverbuggt/mkdocs-encryptcontent-plugin/blob/version3/documentation/mkdocs.yml so that it includes such a config:

    - encryptcontent:
        insecure_test: !ENV [MKDOCS_ENCRYPTCONTENT_INSECURE_TEST, false]

-that would really help me.

[unverbuggt]

yes, sure.

[oprypin]

Thanks!