mirror of
https://github.com/jedisct1/libsodium.git
synced 2024-12-23 20:15:19 -07:00
Deprecate the single-file documentation, link to the gitbook one
This commit is contained in:
Frank Denis
parent
e309c92e9b
commit
626cc3ba99
432
README.markdown
432
README.markdown
@ -4,434 +4,26 @@
|
||||
|
||||
============
|
||||
|
||||
[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.
|
||||
Sodium is a new, easy-to-use software library for encryption,
|
||||
decryption, signatures, password hashing and more.
|
||||
|
||||
NaCl's goal is to provide all of the core operations needed to build
|
||||
It is a portable, cross-compilable, installable, packageable
|
||||
fork of [NaCl](http://nacl.cr.yp.to/), with a compatible API, and an
|
||||
extended API to improve usability even further.
|
||||
|
||||
Its goal is to provide all of the core operations needed to build
|
||||
higher-level cryptographic tools.
|
||||
|
||||
Sodium is a portable, cross-compilable, installable, packageable
|
||||
fork of NaCl (based on the latest released upstream version [nacl-20110221](http://hyperelliptic.org/nacl/nacl-20110221.tar.bz2)), with a compatible API.
|
||||
|
||||
The design choices, particularly in regard to the Curve25519
|
||||
Diffie-Hellman function, emphasize security (whereas NIST curves
|
||||
emphasize "performance" at the cost of security), and "magic
|
||||
constants" in NaCl/Sodium have clear rationales.
|
||||
|
||||
The same cannot be said of NIST curves, where the specific origins of
|
||||
certain constants are not described by the standards.
|
||||
|
||||
And despite the emphasis on higher security, primitives are faster
|
||||
across-the-board than most implementations of the NIST standards.
|
||||
|
||||
## 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 performs tests at run-time, so that the same binary package can
|
||||
still run everywhere.
|
||||
|
||||
Sodium is tested on a variety of compilers and operating systems,
|
||||
Sodium supports a variety of compilers and operating systems,
|
||||
including Windows (with MingW or Visual Studio, x86 and x64), iOS and Android.
|
||||
|
||||
## Installation
|
||||
## Documentation
|
||||
|
||||
Sodium is a shared library with a machine-independent set of
|
||||
headers, so that it can easily be used by 3rd party projects.
|
||||
The documentation is a work-in-progress, and is being written using
|
||||
Gitbook:
|
||||
|
||||
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](https://download.libsodium.org/libsodium/releases/),
|
||||
then follow the ritual:
|
||||
|
||||
$ ./configure
|
||||
$ make && make check
|
||||
# make install
|
||||
|
||||
Pre-compiled Win32 packages are available for download at the same
|
||||
location.
|
||||
|
||||
Integrity of source tarballs can currently be checked using PGP or
|
||||
verified DNS queries (`dig +dnssec +short txt <file>.download.libsodium.org`
|
||||
returns the SHA256 of any file available for download).
|
||||
|
||||
## Pre-built binaries
|
||||
|
||||
Pre-built libraries for Visual studio 2010, 2012 and 2013, both for
|
||||
x86 and x64, are available for download at
|
||||
https://download.libsodium.org/libsodium/releases/ , courtesy of
|
||||
Samuel Neves (@sneves).
|
||||
|
||||
## Bindings for other languages
|
||||
|
||||
* C++: [sodiumpp](https://github.com/rubendv/sodiumpp)
|
||||
* Common LISP [cl-sodium](https://github.com/orthecreedence/cl-sodium)
|
||||
* Erlang: [Erlang-NaCl](https://github.com/tonyg/erlang-nacl)
|
||||
* Erlang: [Salt](https://github.com/freza/salt)
|
||||
* Haskell: [Saltine](https://github.com/tel/saltine)
|
||||
* Idris: [Idris-Sodium](https://github.com/edwinb/sodium-idris)
|
||||
* Java: [Kalium](https://github.com/abstractj/kalium)
|
||||
* Java JNI: [Kalium-JNI](https://github.com/joshjdevl/kalium-jni)
|
||||
* Julia: [Sodium.jl](https://github.com/amitmurthy/Sodium.jl)
|
||||
* LUA: [lua-sodium](https://github.com/morfoh/lua-sodium)
|
||||
* .NET: [libsodium-net](https://github.com/adamcaudill/libsodium-net)
|
||||
* NodeJS: [node-sodium](https://github.com/paixaop/node-sodium)
|
||||
* Objective C: [NAChloride](https://github.com/gabriel/NAChloride)
|
||||
* Objective C: [libsodium-objc](https://github.com/damiancarrillo/libsodium-objc)
|
||||
* OCaml: [ocaml-sodium](https://github.com/dsheets/ocaml-sodium)
|
||||
* Perl: [Crypto-Sodium](https://github.com/mgregoro/Crypt-Sodium)
|
||||
* Pharo/Squeak: [Crypto-NaCl](http://www.eighty-twenty.org/index.cgi/tech/smalltalk/nacl-for-squeak-and-pharo-20130601.html)
|
||||
* PHP: [PHP-Sodium](https://github.com/alethia7/php-sodium)
|
||||
* PHP: [libsodium-php](https://github.com/jedisct1/libsodium-php)
|
||||
* Python: [PyNaCl](https://github.com/dstufft/pynacl)
|
||||
* Python: [PySodium](https://github.com/stef/pysodium)
|
||||
* Racket: part of [CRESTaceans](https://github.com/mgorlick/CRESTaceans/tree/master/bindings/libsodium)
|
||||
* Ruby: [RbNaCl](https://github.com/cryptosphere/rbnacl)
|
||||
* Ruby: [Sodium](https://github.com/stouset/sodium)
|
||||
* Rust: [Sodium Oxide](https://github.com/dnaq/sodiumoxide)
|
||||
|
||||
## 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>
|
||||
|
||||
This is not required, however, before any other libsodium functions, it
|
||||
is recommended to call:
|
||||
|
||||
sodium_init();
|
||||
|
||||
This will pick optimized implementations of some primitives, if they
|
||||
appear to work as expected after running some tests, and these will be
|
||||
used for subsequent operations.
|
||||
It will also initialize the pseudorandom number generator.
|
||||
This function should only be called once, and before performing any other
|
||||
operations.
|
||||
Doing so is required to ensure thread safety of all the functions provided by
|
||||
the library.
|
||||
|
||||
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. This holds
|
||||
true for `crypto_sign_keypair()` and `crypto_box_keypair()` as well.
|
||||
|
||||
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)`.
|
||||
|
||||
In order to compare memory zones in constant time, Sodium provides:
|
||||
|
||||
int sodium_memcmp(const void * const b1_, const void * const b2_,
|
||||
size_t size);
|
||||
|
||||
`sodium_memcmp()` returns `0` if `size` bytes at `b1_` and `b2_` are
|
||||
equal, another value if they are not. Unlike `memcmp()`,
|
||||
`sodium_memcmp()` cannot be used to put `b1_` and `b2_` into a defined
|
||||
order.
|
||||
|
||||
And a convenience function for converting a binary buffer to a
|
||||
hexadecimal string:
|
||||
|
||||
char * sodium_bin2hex(char * const hex, const size_t hexlen,
|
||||
const unsigned char *bin, const size_t binlen);
|
||||
|
||||
Sensitive data should not be swapped out to disk, especially if swap
|
||||
partitions are not encrypted. Libsodium provides the `sodium_mlock()`
|
||||
function to lock pages in memory before writing sensitive content to
|
||||
them:
|
||||
|
||||
int sodium_mlock(void *addr, size_t len);
|
||||
|
||||
Once done with these pages, they can be unlocked with
|
||||
`sodium_munlock()`. This function will zero the data before unlocking
|
||||
the pages.
|
||||
|
||||
int sodium_munlock(void * addr, size_t len);
|
||||
|
||||
## Easy interfaces to `crypto_box` and `crypto_secretbox`
|
||||
|
||||
`crypto_box` and `crypto_secretbox` require prepending
|
||||
`crypto_box_ZEROBYTES` or `crypto_secretbox_ZEROBYTE` extra bytes to the
|
||||
message, and making sure that these are all zeros.
|
||||
A similar padding is required to decrypt the ciphertext. And this
|
||||
padding is actually larger than the MAC size,
|
||||
`crypto_box_MACBYTES`/`crypto_secretbox_MACBYTES`.
|
||||
|
||||
This API, as defined by NaCl, can be confusing. And while using a
|
||||
larger buffer and two pointers is not an issue for native C
|
||||
applications, this might not be an option when another runtime is
|
||||
controlling the allocations.
|
||||
|
||||
Libsodium provides an easy, higher-level interface to these operations.
|
||||
|
||||
int crypto_box_easy(unsigned char *c, const unsigned char *m,
|
||||
unsigned long long mlen, const unsigned char *n,
|
||||
const unsigned char *pk, const unsigned char *sk);
|
||||
|
||||
This function encrypts and authenticates a message `m` using the
|
||||
sender's secret key `sk`, the receiver's public key `pk` and a nonce
|
||||
`n`, which should be `crypto_box_NONCEBYTES` bytes long.
|
||||
The ciphertext, including the MAC, will be copied to `c`, whose length
|
||||
should be `len(m) + crypto_box_MACBYTES`, and that doesn't require to be
|
||||
initialized.
|
||||
|
||||
int crypto_box_open_easy(unsigned char *m, const unsigned char *c,
|
||||
unsigned long long clen, const unsigned char *n,
|
||||
const unsigned char *pk, const unsigned char *sk);
|
||||
|
||||
This function verifies and decrypts a ciphertext `c` as returned by
|
||||
`crypto_box_easy()`, whose length is `clen`, using the nonce `n`, the
|
||||
receiver's secret key `sk`, and the sender's public key `pk`. The
|
||||
message is stored to `m`, whose length should be at least `len(c) -
|
||||
crypto_box_MACBYTES` and that doesn't require to be initialized.
|
||||
|
||||
Similarily, secret-key authenticated encryption provide "easy" wrappers:
|
||||
|
||||
int crypto_secretbox_easy(unsigned char *c, const unsigned char *m,
|
||||
unsigned long long mlen, const unsigned char *n,
|
||||
const unsigned char *k);
|
||||
|
||||
int crypto_secretbox_open_easy(unsigned char *m, const unsigned char *c,
|
||||
unsigned long long clen,
|
||||
const unsigned char *n,
|
||||
const unsigned char *k);
|
||||
|
||||
The length of the ciphertext, which will include the MAC, is
|
||||
`len(m) + crypto_secretbox_MACBYTES`, and the length of the buffer for
|
||||
the decrypted message doesn't have to be more than `len(c) -
|
||||
crypto_secretbox_MACBYTES`.
|
||||
|
||||
The "easy" interface is as fast as the traditional NaCl API and
|
||||
doesn't require any memory allocations.
|
||||
|
||||
## New operations
|
||||
|
||||
### crypto_shorthash
|
||||
|
||||
A lot of applications and programming language implementations have
|
||||
been recently found to be vulnerable to denial-of-service attacks when
|
||||
a hash function with weak security guarantees, like Murmurhash 3, was
|
||||
used to construct a hash table.
|
||||
|
||||
In order to address this, Sodium provides the “shorthash” function,
|
||||
currently implemented using SipHash-2-4. This very fast hash function
|
||||
outputs short, but unpredictable (without knowing the secret key)
|
||||
values suitable for picking a list in a hash table for a given key.
|
||||
|
||||
See `crypto_shorthash.h` for details.
|
||||
|
||||
### crypto_generichash
|
||||
|
||||
This hash function provides:
|
||||
|
||||
* A variable output length (up to `crypto_generichash_BYTES_MAX` bytes)
|
||||
* A variable key length (from no key at all to
|
||||
`crypto_generichash_KEYBYTES_MAX` bytes)
|
||||
* A simple interface as well as a streaming interface.
|
||||
|
||||
`crypto_generichash` is currently being implemented using
|
||||
[Blake2](https://blake2.net/).
|
||||
|
||||
### crypto_pwhash (scrypt)
|
||||
|
||||
High-level functions for password hashing are not defined yet: they will
|
||||
eventually be wrappers for the winning function of the ongoing
|
||||
[Password Hashing Competition](https://password-hashing.net/).
|
||||
|
||||
Meanwhile, the [scrypt](http://www.tarsnap.com/scrypt.html) function is
|
||||
available through explicitly-named functions, and will remain available
|
||||
in the library even after the PHC.
|
||||
|
||||
int crypto_pwhash_scryptsalsa208sha256(unsigned char *out,
|
||||
unsigned long long outlen,
|
||||
const char *passwd,
|
||||
unsigned long long passwdlen,
|
||||
const unsigned char *salt,
|
||||
unsigned long long opslimit,
|
||||
size_t memlimit);
|
||||
|
||||
This function derives `outlen` bytes from a password `passwd` and a
|
||||
salt `salt` that has to be `crypto_pwhash_scryptsalsa208sha256_SALTBYTES`
|
||||
bytes long.
|
||||
|
||||
The function will use at most `memlimit` bytes of memory and `opslimit`
|
||||
is the maximum number of iterations to perform. Making the function
|
||||
memory-hard and CPU intensive by increasing these parameters might increase
|
||||
security.
|
||||
|
||||
Although password storage was not the primary goal of the scrypt
|
||||
function, it can still be used for this purpose:
|
||||
|
||||
int crypto_pwhash_scryptsalsa208sha256_str
|
||||
(char out[crypto_pwhash_scryptsalsa208sha256_STRBYTES],
|
||||
const char *passwd,
|
||||
unsigned long long passwdlen,
|
||||
unsigned long long opslimit,
|
||||
size_t memlimit);
|
||||
|
||||
This function returns a `crypto_pwhash_scryptsalsa208sha256_STRBYTES`
|
||||
bytes C string (the length includes the final `\0`) suitable for storage.
|
||||
The string is guaranteed to only include ASCII characters.
|
||||
|
||||
The function will use at most `memlimit` bytes of memory and `opslimit`
|
||||
is the maximum number of iterations to perform. These parameters are
|
||||
included in the output string, and do not need to be stored separately.
|
||||
|
||||
The function automatically generates a random salt, which is also
|
||||
included in the output string.
|
||||
|
||||
int crypto_pwhash_scryptsalsa208sha256_str_verify
|
||||
(const char str[crypto_pwhash_scryptsalsa208sha256_STRBYTES],
|
||||
const char *passwd,
|
||||
unsigned long long passwdlen);
|
||||
|
||||
This function verifies that hashing the plaintext password `passwd`
|
||||
results in the stored hash value included in `str` when using the same
|
||||
parameters.
|
||||
|
||||
`0` is returned if the passwords are matching, `-1` is they are not.
|
||||
The plaintext password should be locked in memory using
|
||||
`sodium_mlock()` and immediately zeroed out and unlocked after this
|
||||
function returns, using `sodium_munlock()`.
|
||||
|
||||
## ChaCha20Poly1305
|
||||
|
||||
Sodium supports the ChaCha20Poly1305 Authenticated Encryption with
|
||||
Additional Data (AEAD) construction, as documented in the
|
||||
[nir-cfrg-chacha20-poly1305-04](http://tools.ietf.org/html/draft-nir-cfrg-chacha20-poly1305-04)
|
||||
draft.
|
||||
|
||||
int crypto_aead_chacha20poly1305_encrypt(unsigned char *c,
|
||||
unsigned long long *clen,
|
||||
const unsigned char *m,
|
||||
unsigned long long mlen,
|
||||
const unsigned char *ad,
|
||||
unsigned long long adlen,
|
||||
const unsigned char *nsec,
|
||||
const unsigned char *npub,
|
||||
const unsigned char *k);
|
||||
|
||||
This function encrypts the message `m` of length `mlen` with the key
|
||||
`k` (whose size is `crypto_aead_chacha20poly1305_KEYBYTES` bytes)
|
||||
and nonce `n` (whose size is `crypto_aead_chacha20poly1305_NPUBBYTES`).
|
||||
|
||||
`c` must be at least `mlen + crypto_aead_chacha20poly1305_ABYTES` long.
|
||||
|
||||
`nsec` should be NULL.
|
||||
|
||||
The function fills the first bytes of `c` with a tag authenticating both the
|
||||
encrypted message and additional data `ad` whose length is `adlen` bytes.
|
||||
|
||||
The output of the previous function can be verified and decrypted using:
|
||||
|
||||
int crypto_aead_chacha20poly1305_decrypt(unsigned char *m,
|
||||
unsigned long long *mlen,
|
||||
unsigned char *nsec,
|
||||
const unsigned char *c,
|
||||
unsigned long long clen,
|
||||
const unsigned char *ad,
|
||||
unsigned long long adlen,
|
||||
const unsigned char *npub,
|
||||
const unsigned char *k);
|
||||
|
||||
`clen` is the length of the ciphertext, as generated by the previous
|
||||
function: it is equal to the length of the plaintext message +
|
||||
`crypto_aead_chacha20poly1305_ABYTES`.
|
||||
|
||||
If the MAC can be verified, the plaintext is copied to `m` and the
|
||||
function returns `0`.
|
||||
If the verification fails, the function returns `-1`.
|
||||
|
||||
The length of the additional data can be `0`.
|
||||
|
||||
`nsec` should be NULL.
|
||||
|
||||
## Constants available as functions
|
||||
|
||||
In addition to constants for key sizes, output sizes and block sizes,
|
||||
Sodium provides these values through function calls, so that using
|
||||
them from different languages is easier.
|
||||
|
||||
## CurveCP
|
||||
|
||||
CurveCP tools are part of a different project,
|
||||
[libchloride](https://github.com/jedisct1/libchloride).
|
||||
If you are interested in an embeddable CurveCP implementation, take a
|
||||
look at [libcurvecpr](https://github.com/impl/libcurvecpr).
|
||||
|
||||
## 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`.
|
||||
[libsodium documentation](http://doc.libsodium.org)
|
||||
|
||||
## License
|
||||
|
||||
[ISC license](http://en.wikipedia.org/wiki/ISC_license).
|
||||
|
||||
See the `COPYING` file for details, `AUTHORS` for designers and
|
||||
implementors, and `THANKS` for contributors.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user