Clarify degree of compatibility with libsodium?

[snej]

I'm currently using Monocypher, but about to add a 3rd party library that uses libSodium. I don't mind linking both libraries, but I'm not clear on whether I can take keys created with one library and use them with the other.

For example, can I generate a key-pair with libsodium's crypto_sign_keypair() and then pass those keys to Monocypher's crypto_sign? Will the resulting signature be recognized by libsodium?

The "Why Monocypher" page implies that Monocypher is derived from NaCl, as of course is libsodium, which would imply that they use compatible algorithms and data structures; but I'm still unsure. It would be nice if the docs stated something about compatibility.

[LoupVaillant]

Compatibility is as follows:

• Low-level primitives follow the same standards, and thus are compatible.

• Monocypher’s crypto_lock() is the same as Libsodium’s crypto_aead_xchacha20poly1305_ietf_encrypt_detached()

• Monocypher’s crypto_sign() is not compatible with Libsodium. You want crypto_ed25519_sign() instead. (The reason for the incompatibility is because crypto_sign() reuses BLAKE2b instead of SHA512).

• Monocypher’s Argon2i is compatible with Libsodium’s crypto_pwhash(), provided you use the crypto_pwhash_ALG_ARGON2I13 flag. Also, Monocypher supports 1 and 2 passes for conformity reasons, while Libsodium chose to crash instead for safety reasons (attacker advantage is much bigger with less than 3 passes).

• Elligator implementations are not compatible. Monocypher’s crypto_hidden_to_curve() maps representative to Montgomery curve points, while Libsodium’s crypto_core_ed25519_from_uniform() maps to Edwards points. Also, Monocypher does not project the point to the prime order subgroup (the low-order component is naturally ignored by most subsequent operations). And most importantly, Monocypher supports the reverse map, which Libsodium does not.

As far as I know Elligator is the only hard incompatibility between the two libraries. For almost everything else, there’s a way for Libdodium to do what Monocypher does. The reverse is not true. Unlike Libsodium, Monocypher aims to provide "one true way" of doing things. You’ll most likely need to make some changes or additions to make the two compatible.

Or, if you don’t care about compatibility and can shoulder the maintenance of the patch, you could rip out Libsodium from your 3rd party library, and replace everything with Monocypher’s equivalent. If that library is well written, its interface with the crypto library should be small enough to be easily severed.

The "Why Monocypher" page implies that Monocypher is derived from NaCl,

Monocypher followed the philosophy behind NaCl, and took most of its primitives. But it never aimed for full compatibility. The compatibility it does have is mostly a consequence of existing NaCl libraries getting so many things right.

[snej]

Thanks very much!

[fscoto]

@LoupVaillant Shouldn't this go on the website somewhere (subpage of Why Monocypher?)? This is useful information and libsodium interoperability may influence whether people choose Monocypher.

[LoupVaillant]

Yes @fscoto it should, which is why the issue is still open. I’ll fix it as you suggests.

[LoupVaillant]

Done at last!

Anything to add, or can we close this issue?

[snej]

Looks good!

[fscoto]

@LoupVaillant,

Done at last!

Anything to add, or can we close this issue?

Nit: ChaCha20, not Chacha20. See 0eabd81445d096eca59b14586f5716649ef12527.

Is "pro tip" appropriate for documentation?

Other than that ok fscoto

[LoupVaillant]

Good points, thanks. Should be corrected now.