libsodium-net, or better said, libsodium for .NET, is a C# wrapper around libsodium. For those that don't know, libsodium is a portable implementation of Daniel Bernstein's fantastic NaCl library. If you aren't familiar with NaCl, I highly suggest that you look into libsodium and NaCl before using this library.
NaCl is a great library in that its designed has made the right choices on what to implement and how - something most developers don't know how to do. So by using it (or a wrapper), many of those details are abstracted away where you don't need to worry about them. NaCl itself is less than portable C, only targeted for *nix systems; libsodium solves this by making it portable and making a few minor changes to better suite being distributed as a compiled binary.
Crypto is hard - much harder than your average developer understands. There is much going on in the world today, privacy is at risk like never before - many complain, few act. To avoid falling into the complainers group, I've started this effort to make these tools readily available to the .NET community in hopes they will be used to further the goals of defending personal privacy and security.
TL;DR: Experimental.
This is still a work in progress, as such the API is subject to change and there may be bugs that have been missed. Currently, not all of libsodium is implemented; though the most used methods should be; if there's anything that you need that libsodium supports that this library doesn't, please open an issue - or better, open a pull request.
The following methods have been implemented and have at least basic unit tests in place to ensure they are producing the expected output. (Listed in no particular order)
Sodium.PublicKeyAuth.GenerateKeyPair() - Generates a public/private Ed25519 key pair based on a random seed. The public key is 32 bytes, the private key is 64 bytes.
Sodium.PublicKeyAuth.GenerateKeyPair() - Generates a public/private Ed25519 key pair based on the provided seed to allow deterministic key generation. The public key is 32 bytes, the private key is 64 bytes, seed must be 32 bytes.
Sodium.PublicKeyAuth.Sign() - Signs a message with Ed25519, based on the supplied 64 byte private key.
Sodium.PublicKeyAuth.Verify() - Verifies the signature and returns the clear-text message using Ed25519 and the supplied 32-byte public key. Throws a CryptographicException if verification fails.
Sodium.PublicKeyBox.GenerateKeyPair() - Generates a public/private Curve25519-XSalsa20-Poly1305 key pair based on a random seed. The public key is 32 bytes, the private key is 32 bytes.
Sodium.PublicKeyBox.Create() - Encrypts a message using the sender's private key, and the recipient's public key. Both keys are 32 bytes. Encryption / signing is performed via Curve25519-XSalsa20-Poly1305.
Sodium.PublicKeyBox.Open() - Decrypts and verifies the sender's signature using the recipient's private key and the sender's public key. Both keys are 32 bytes. Throws a CryptographicException if verification fails.
Sodium.SecretBox.Create() - This method encrypts and authenticates a message. This is currently implemented via XSalsa20 and Poly1305.
Details:
- Key length: 32 bytes
- Nonce length: 24 bytes
Note: As in any crypto system, it's important to avoid reusing a nonce, so the nonce should either be randomly generated or consist of a non-repeatable message ID. To minimize risks, my recommendation is to randomly generate the nonce.
Sodium.SecretBox.Open() - This method retrieves the message encrypted via SecretBox.Create(). To decrypt and authenticate the data, you pass the key, nonce, and cipher text; if there is an issue decrypting the message, you will receive a generic CryptographicException - the exact reason for the failure isn't provided.
Sodium.OneTimeAuth.Sign() - Provides messages authentication via Poly1305. The method takes a messages (as UTF-8 string or byte array), a 32 byte key (that must be used only once), and returns a 16 bytes signature.
For this to be secure, it's required that the signing key only be used once.
Sodium.OneTimeAuth.Verify() - This verifies a signature generated via crypto_onetimeauth. To do so, it requires the original message, the 16 byte signature, and the 32 byte key.
Sodium.SecretKeyAuth.Sign() - Provides messages authentication via HMAC-SHA512-256. The method takes a messages (as UTF-8 string or byte array), a 32 byte key, and returns a 32 bytes signature.
Sodium.SecretKeyAuth.Verify() - This verifies a signature generated via crypto_auth. To do so, it requires the original message, the 32 byte signature, and the 32 byte key.
Sodium.StreamEncryption.Encrypt() - Encrypts a message via XSalsa20 using a 32 byte key and a 24 byte nonce. As always, it's critical that the nonce never be reused. This provides encryption only, not authentication.
Sodium.StreamEncryption.Decrypt() - Decrypts messages via XSalsa20.
Sodium.CryptoHash.Hash() - This hashes a message (UTF-8 encoded string or byte[]) using the default algorithm, currently SHA-512. A byte array is returned.
The Sodium.CryptoHash class also includes the following methods:
SHA512()- Compute a SHA-512 hash (for compatibility if the default algorithm is ever changed). (crypto_hash_sha512)SHA256()- Compute a SHA-256 hash. (crypto_hash_sha256)
Sodium.GenericHash.Hash() - This is a multi-purpose fast hash, that has variable output size and an optional key. As with the CryptoHash methods, the input can be a UTF-8 encoded string, or a byte array, and a byte array is returned.
This is the most flexible hashing option; and the one I would recommend the most.
This is currently based on BLAKE2b, and has the following properties:
- Variable output from 16 to 64 bytes.
- Optional keyed mode, accepting a key from 16 to 64 bytes.
Note: Only libsodium's simplified interface is currently supported; the streaming interface is not implemented at this time.
Sodium.ShortHash.Hash() - Short, high-speed hashing, currently implanted via SipHash-2-4 and produces an 8 byte hash.
Sodium.SodiumCore.SodiumVersionString() - This returns the version string on the libsodium library in use. Note, this is not the version of libsodium-net.
Sodium.SodiumCore.GetRandomBytes() - Gets a number of random bytes, suitable for use as a key or nonce. In classes where appropriate, there are GenerateKey() and/or GenerateNonce() functions that return a byte array of the correct size.
There are a small number of additional methods that extended or simplify the usage of this library.
Sodium.Utilities.HexToBinary() - This method converts a lower-case hex-encoded string to a byte array.
Sodium.Utilities.BinaryToHex() - This method takes a byte array, and produces a lower-case hex-encoded string.
This library can be built in Visual Studio 2010 and MonoDevelop 3.x, and targets .NET 4.0; it is compiled against libsodium v0.4.5.
Any method that takes a String, has an overload that accepts a byte array; Strings are assumed to be UTF8; if this is not the case, please convert it to bytes yourself and use the overloads that accept byte arrays.
Starting with version 0.3.0, all files are GPG signed to simplify validation. Files are signed with key ID 0x22CAD57A659CA2BC, fingerprint: E88AA5A5EB1162B8CAE0A52422CAD57A659CA2BC. You can find the key on keys.gnupg.net or on my personal web site.
NaCl has been released to the public domain to avoid copyright issues. libsodium is subject to the ISC license, and this software is subject to the MIT license (see LICENSE).