diff --git a/images/salt-mine-turda.jpg b/images/salt-mine-turda.jpg new file mode 100644 index 00000000..04a557e7 Binary files /dev/null and b/images/salt-mine-turda.jpg differ diff --git a/posts/tutorial-sodium-plugin.md b/posts/tutorial-sodium-plugin.md new file mode 100644 index 00000000..85ed82ec --- /dev/null +++ b/posts/tutorial-sodium-plugin.md @@ -0,0 +1,98 @@ +--- +title: Changing the cryptography library in your CryptPad server +date: 2024-10-03 +author: "Fabrice Mouhartem" +cover: /images/salt-mine-turda.jpg +summary: A tutorial to explain why and how to change the backend cryptography library on your cryptpad server +tags: +- tutorials +- administration +- configuration +- performance +- security +--- + +
+ +![Cover image: Salt mine of Turda, Romania.](/images/salt-mine-turda.jpg "Cover Image: Salt mine of Turda") +
+Salt mine of Turda, Romania. From Wikimedia Commons +under CC0 license. +
+
+ +⚠️ This tutorial is intended for system administrators. However, the introduction +can be of interest to anyone who is curious about the inner working of CryptPad. + +## 🧑‍🏫 Introduction + +When running CryptPad on your server, you may notice that under load, some +CryptPad processes are consuming a lot of computational resources. So far, there +is nothing surprising. However, doing a bit of profiling about these +computations, we noticed that the heavy lifting was done by signature +verifications. The reason being that the server proceeds with data validation +before storage to avoid being spammed by false patches. Even if they won’t +affect the final state of the file as they won’t be displayed with an invalid +signature, they still need to be processed by the clients, potentially allowing +to _denial of service_ attacks. + +Well, that’s good, but it doesn’t help us with our load issue. +However, looking at how CryptPad is designed, we remark that both the server and +the client are written in javascript. +This allows us to share common libraries between the server and the client· +Thus it guarantees the same behaviour for both for fundamental building blocks. +It also stands true for the cryptographic library that is used to perform those +essential operations for CryptPad. +[TweetNaCl](https://github.com/dchest/tweetnacl-js) has been picked as a +lightweight full-javascript library to ensure browser-portability for the +client. +However, this portability constraint is not relevant for servers, and the +lack of low-level optimisation is actually what cause of the bottleneck we +described previously. + +To keep the codebase legible, and as it’s not a problem for small instances, we +decided to address this problem using CryptPad’s plugin system. Then providing +sane defaults for reasonable-sized instances, while making possible to easily +swap the cryptographic library used by the server. The goal of this tutorial is +to show how to do it in practice. + +## 🔩 Installing the plugin + +1. To install the plugin, the first step is to download it at the right place. +From your CryptPad installation directory: + +```bash +cd lib/plugins +git clone https://github.com/cryptpad/cryptpad-sodium-plugin.git sodium +``` + +2. Then, install its dependencies: + +```bash +cd sodium/ +npm ci +``` + +3. Restart your CryptPad server. + +And that’s it, your server should use its native implementation of _libsodium_ +now. + +⚠️ If step 2 is omitted, the server would silently fall back to `TweetNaCl`. + +## 🔧 Use another library? + +For signatures, CryptPad uses the EdDSA algorithm over the +[`ed25519`](https://en.wikipedia.org/wiki/EdDSA#Ed25519) curve. +If you want to run another implementation of it, you can make a copy of our +[`cryptpad-sodium-plugin`](https://github.com/cryptpad/cryptpad-sodium-plugin/tree/main) +plugin and edit the +[`index.js`](https://github.com/cryptpad/cryptpad-sodium-plugin/blob/main/index.js) +file to provide another implementation for the `open` (combined mode +verification) and `detachedVerify` (detached mode verification) functions. + +Please note that if you do that and run it in production, under the +[AGPL-3](https://www.gnu.org/licenses/agpl-3.0.en.html) licence, you are to make +the source code of the plugin available. +Feel free to contact us at if you want us to advertise +your back-end crypto plugin as a community contribution 🙂