Lack of examples / tests.

[hickscorp]

We're evaluating this library and we're having a very hard time understanding how to use it.
A small paragraph on how its internal types translate to libsodium would be great.
We found several behaviours but they don't seem to be called from anywhere - so understanding what inputs should be used is quite puzzling.

[ArteMisc]

We found several behaviours but they don't seem to be called from anywhere

Could you name which behaviour(s) in particular?

If there are any specific modules/use cases/primitives you require examples/docs/tests for, I will start there. This library could indeed use some more documentation.

While it may not be the best documentation, looking at the original C NIF code (https://github.com/ArteMisc/libsalty/blob/master/src/salty_nif.c) might give some insight into the mapping between elixir's in-/output parameters and the ones in libsodium.

[tuupola]

If it is any help here is how I am using Salty.Aead.Xchacha20poly1305Ietf:

https://github.com/tuupola/branca-elixir/blob/master/lib/branca.ex#L213-L220

[hickscorp]

@ArteMisc @tuupola Thanks for the update, and BTW impressive work on the NIF side of things.

Regarding behaviours, for example, Salty.Box. It's being implemented by several modules, but since it's not being called by any, it's not obvious why the modules have to implement it. This is not really an issue once things get a bit more documented.

I think there should be documentation (maybe in the form of doctest so it's always up to date) for secret box and sealed boxes first. This is most likely why people would turn on using this sort of lib - to be able to perform encryption / signing in a more advanced fashion.

I think setting up something like would be great:

• How to generate RSA keys.
• How to generate a public key from its private version.
• How to encrypt using the public key, decrypt using the private key.
• How to sign using the private key.

And indeed a bit of AES cryptography too, for example, how to generate an AES key and how encrypt something with it.

Also, I would suggest that some coverage could be produced for those modules, because this is where we looked first, but none of the interesting bits had test cases - which is fine in the sense that we don't want to cover libsodium itself - just use the awesomeness of ExUnit to provide working examples that never break.

[ArteMisc]

In most cases within this library, the behaviours can be seen as the equivalent of an interface in other languages. So in the example of Salty.Box, the behaviour is implemented by Salty.Box.Curve25519xchacha20poly1305 and Salty.Box.Curve25519xsalsa20poly1305, such that any application using them can switch between using either implementation by simply referencing a different module.

I think there should be documentation (maybe in the form of doctest so it's always up to date) for secret box and sealed boxes first.

Box and Secretbox indeed seem like the best places to start, along with Sign, as these are probably the most common uses for libsodium in general. I will get working on those first.

I think setting up something like would be great:

How to generate RSA keys.

RSA is not implemented in libsodium, and as a result is not implemented by these bindings either. The primitives provided for similar cryptographic operations are based on X25519 (DH) and Ed25519 (signatures), in libsodium's crypto_box and crypto_sign functions. If signatures and encryption (through box) are what you're looking for, those are examples I can provide. If you need RSA specifically, that is outside of the scope of this library, but should be included in Erlang's standard libraries through OpenSSL.

And indeed a bit of AES cryptography too, for example, how to generate an AES key and how encrypt something with it.

While libsodium provides bindings for AES-GCM on platforms that support it through hardware instructions, this support is limited. Any other form of AES is not included in the library nor in these bindings. Libsodium's alternatives are based on XChacha20Poly1305/XSalsa20Poly1305. As with RSA, this library may or may not be the right fit for your requirements.