Libsodium: A modern, portable, easy to use crypto library

If you use a sufficiently narrow subset, my advice would be to do your bindings yourself. It’s thankless work, but it’s work you control, and you’ll be able to tailor your side to your liking.

Love it. Has a bit of passive aggressive pizzazz.

Its Daniel J Bernstein's world, we merely live in it:

- http://www.metzdowd.com/pipermail/cryptography/2016-March/02...

- https://cr.yp.to/highspeed/naclcrypto-20090310.pdf

He has implemented a WIDE range of crypto! At the same time, he a professional photographer!

And the nonce is not sent explicitly; the different parties compute it themselves the same way they agree on a shared secret.

When a ciphertext is received, the recipient knows what the nonce is expected to be, instead of having to trust an arbitrary one.

In the context of a stream of messages, it binds the nonce to a position in the stream, allowing detection of frames that have been replayed, reordered or lost.

But when the intent is to send independent messages, the nonce should be included with the ciphertext.

For constructions with a short nonce size, the ability to choose the nonce is also very useful to improve the security bounds, by using a key derivation function to derive a new key and nonce from a larger nonce.

By the way, for streams, libsodium has the `crypto_stream_*()` functions that greatly simplifies the implementation of protocols and file encryption.

  void
  crypto_aead_lock(
      uint8_t       *cipher_text,
      uint8_t        mac  [16],
      const uint8_t  key  [32],
      const uint8_t  nonce[24],
      const uint8_t *ad,         size_t ad_size,
      const uint8_t *plain_text, size_t text_size);

Yet another reason to let users specify the nonce is that portability stops me from accessing an RNG. Can’t produce random nonces without it, so I have to pass the burden to the user. (On the other hand, I get to run on tiny microcontrollers that don’t even have `malloc()`).

---

Speaking of streaming encryption, I have that too now, and unlike libsodium it’s compatible with the one-shot interface. Like libsodium, you only need to provide your nonce once.

If you use something like TLS, The key exchange is expanded to produce an IV. Then each record has an incremented number[1] and this number is mixed with the IV to form a unique IV[2] for the message.

[0]: https://doc.libsodium.org/secret-key_cryptography/encrypted-... [1]: https://www.rfc-editor.org/rfc/rfc8446#section-5.3 [2]: https://www.rfc-editor.org/rfc/rfc8446#appendix-E.2

My guess is they wanted to maintain compatibility with NaCl.

More rarely, you want to save space/reduce overhead by using a deterministic IV scheme. Either all 0 because you picked a random key and you _really_ care about space saving, or you're very very sure you can safely count IVs (0, 1, 2, ..) without ever reusing a single one.

In those rare cases you don't want to transmit the IV, you just know what the value is supposed to be on both sides. More complexity and danger, but a small percentage of users get to save a few bytes.

Once the files are on the system, you use command-line switches to tell the compiler where to look for headers and which libraries to link to. Libraries are often loaded dynamically when the binary is started, so they are not actually included in the file.

Because maintaining the correct switches is a bit of a pain, there are tools like `pkg-config` to generate them for you. And there are tools like `autoconf` and `automake` to generate build scripts to orchestrate those tools.

In libraries it's pretty common for APIs to a library to be fairly stable, so the function signatures generally don't change very much in the headers. This is also why your application can be dynamically linked to different versions of a library.

There are obviously limitations and that's when people come into the equation. For example, OS distribution maintainers juggle these dependencies for you.

https://mesonbuild.com/Wrapdb-projects.html

https://mesonbuild.com/Wrap-dependency-system-manual.html

meson will download and build the libraries automatically and give you a variable which you pass as a regular dependency into the built target:

https://github.com/qemu/qemu/tree/005ad32358f12fe9313a4a0191...

https://github.com/harfbuzz/harfbuzz/tree/main/subprojects

https://github.com/harfbuzz/harfbuzz/blob/37457412b3212463c5...

Or, if you're using proper operating systems, they're managed by the usual package manager, just like everything else.

Some "single-file" libraries only have the one header, so you can use that one file. Though they often require a bit of trickery to be compiled correctly, so I prefer those with two file, one .h header and one .c source.

Some libraries are popular enough that they’re distributed in your package manager of choice: whatever your Linux/BSD distribution uses, Nix, a Cargo-like repository in some cases… In this case you can download that package and depend on it.

All working libraries can be built from source, one way or another. They each have their own preferred build system though. Most can be installed from source, so you don’t need to be aware of their build system to use it. But if you take on the dependency like that now your users will depend on the library so it’s not exactly free.

Some libraries offer several or all of the above.

Managing updates depend on how you integrate the library. If you use it as a system dependency, your users need to download and update the correct version themselves. Package managers can help there (use Ubuntu/Nix/Ports, get security updates for free… if you trust them to be quick enough, which they will be if the library is popular). The alternative is to ship your own copy of the library yourself, either by building it at home with their build system and manually importing headers & .so/.dll, or absorb their source code into your own build system (you’re on your own but you have full control).

Which is best is… up to who you’re speaking to. To oversimplify the issue, I’d say distro maintainers don’t trust developers to deliver security updates in time, so they want everyone to use .so and dynamic linking everywhere so security updates can happen in a timely manner. On the other hand developers don’t trust distro maintainers to do regular updates in a timely manner, so they’re stuck to old versions of their favourite libraries. Those who do both… maybe have gone insane from the cognitive dissonance?

(Not razzing you or anything; I just genuinely found that question startling, having started programming in the 1990s.)

It also doesn’t hurt that there is basically 1 header and 1 source file (2 of each with the options), which you can trivially copy & paste into your project.

If performance is not a priority, but you need something small, simple, and easy to embed, libhydrogen can come in handy.

I actually use it more than libsodium.