149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
|
|
============
|
|
|
|
[NaCl](http://nacl.cr.yp.to/) (pronounced "salt") is a new easy-to-use
|
|
high-speed software library for network communication, encryption,
|
|
decryption, signatures, etc.
|
|
|
|
NaCl's goal is to provide all of the core operations needed to build
|
|
higher-level cryptographic tools.
|
|
|
|
Sodium is a portable, cross-compilable, installable, packageable,
|
|
API-compatible version of NaCl.
|
|
|
|
## Portability
|
|
|
|
In order to pick the fastest working implementation of each primitive,
|
|
NaCl performs tests and benchmarks at compile-time. Unfortunately, the
|
|
resulting library is not guaranteed to work on different hardware.
|
|
|
|
Sodium only ships portable reference implementations.
|
|
|
|
Optimized implementations (including NEON optimizations) will eventually
|
|
be supported, but tests and benchmarks will be performed at run-time,
|
|
so that the same binary package can still run everywhere.
|
|
|
|
Sodium is tested on a variety of compilers and operating systems,
|
|
including Windows, iOS and Android.
|
|
|
|
## Installation
|
|
|
|
Sodium is a shared library with a machine-independent set of
|
|
headers, so that it can easily be used by 3rd party projects.
|
|
|
|
The library is built using autotools, making it easy to package.
|
|
|
|
Installation is trivial, and both compilation and testing can take
|
|
advantage of multiple CPU cores.
|
|
|
|
Download a
|
|
[tarball of libsodium](http://download.dnscrypt.org/libsodium/releases/),
|
|
then follow the ritual:
|
|
|
|
./configure
|
|
make && make check && make install
|
|
|
|
## Comparison with vanilla NaCl
|
|
|
|
Sodium does not ship C++ bindings. These might be part of a distinct
|
|
package.
|
|
|
|
The default public-key signature system in NaCl was a prototype that
|
|
shouldn't be used any more.
|
|
|
|
Sodium ships with the SUPERCOP reference implementation of
|
|
[Ed25519](http://ed25519.cr.yp.to/), and uses this system by default
|
|
for `crypto_sign*` operations.
|
|
|
|
For backward compatibility, the previous system is still compiled in,
|
|
as `crypto_sign_edwards25519sha512batch*`.
|
|
|
|
## Additional features
|
|
|
|
The Sodium library provides some convenience functions in order to retrieve
|
|
the current version of the package and of the shared library:
|
|
|
|
const char *sodium_version_string(void);
|
|
const int sodium_library_version_major(void);
|
|
const int sodium_library_version_minor(void);
|
|
|
|
Headers are installed in `${prefix}/include/sodium`.
|
|
|
|
A convenience header includes everything you need to use the library:
|
|
|
|
#include <sodium.h>
|
|
|
|
Before doing anything else with the library, call:
|
|
|
|
sodium_init();
|
|
|
|
This function is not thread-safe. No other Sodium functions should be
|
|
called until it successfully returns.
|
|
|
|
And if you need to release memory and other resources possibly
|
|
allocated by the library, call:
|
|
|
|
sodium_shutdown();
|
|
|
|
After fork()ing, call:
|
|
|
|
sodium_reinit();
|
|
|
|
Sodium also provides helper functions to generate random numbers,
|
|
leveraging `/dev/urandom` or `/dev/random` on *nix and the cryptographic
|
|
service provider on Windows. The interface is similar to
|
|
`arc4random(3)`. It is `fork(2)`-safe but not thread-safe.
|
|
|
|
uint32_t randombytes_random(void);
|
|
|
|
Return a random 32-bit unsigned value.
|
|
|
|
void randombytes_stir(void);
|
|
|
|
Generate a new key for the pseudorandom number generator. The file
|
|
descriptor for the entropy source is kept open, so that the generator
|
|
can be reseeded even in a chroot() jail.
|
|
|
|
uint32_t randombytes_uniform(const uint32_t upper_bound);
|
|
|
|
Return a value between 0 and upper_bound using a uniform distribution.
|
|
|
|
void randombytes_buf(void * const buf, const size_t size);
|
|
|
|
Fill the buffer `buf` with `size` random bytes.
|
|
|
|
int randombytes_close(void);
|
|
|
|
Close the file descriptor or the handle for the cryptographic service
|
|
provider.
|
|
|
|
A custom implementation of these functions can be registered with
|
|
`randombytes_set_implementation()`.
|
|
|
|
In addition, Sodium provides a function to securely wipe a memory
|
|
region:
|
|
|
|
void sodium_memzero(void * const pnt, const size_t size);
|
|
|
|
Warning: if a region has been allocated on the heap, you still have
|
|
to make sure that it can't get swapped to disk, possibly using
|
|
`mlock(2)`.
|
|
|
|
## Bindings for other languages
|
|
|
|
* Ruby: [RbNaCl](https://github.com/cryptosphere/rbnacl)
|
|
* Python: [PyNaCl](https://github.com/dstufft/pynacl)
|
|
* Java: [Kalium](https://github.com/abstractj/kalium)
|
|
|
|
## CurveCP
|
|
|
|
CurveCP tools are part of a different project,
|
|
[libchloride](https://github.com/jedisct1/libchloride)
|
|
|
|
## Mailing list
|
|
|
|
A mailing-list is available to discuss libsodium.
|
|
|
|
In order to join, just send a random mail to `sodium-subscribe` {at}
|
|
`pureftpd`{dot}`org`.
|