libsodium: Needed for Dnscrypto-proxy Release 1.3.0
[tomato.git] / release / src / router / libsodium / README.markdown
blob7c6a4ca279c021a96948b43fb687ffc8d5557006
1 [![Build Status](https://travis-ci.org/jedisct1/libsodium.png?branch=master)](https://travis-ci.org/jedisct1/libsodium?branch=master)
3 ![libsodium](https://raw.github.com/jedisct1/libsodium/master/logo.png)
4 ============
6 [NaCl](http://nacl.cr.yp.to/) (pronounced "salt") is a new easy-to-use
7 high-speed software library for network communication, encryption,
8 decryption, signatures, etc.
10 NaCl's goal is to provide all of the core operations needed to build
11 higher-level cryptographic tools.
13 Sodium is a portable, cross-compilable, installable, packageable
14 crypto library based on NaCl, with a compatible API.
16 ## Portability
18 In order to pick the fastest working implementation of each primitive,
19 NaCl performs tests and benchmarks at compile-time. Unfortunately, the
20 resulting library is not guaranteed to work on different hardware.
22 Sodium performs tests at run-time, so that the same binary package can
23 still run everywhere.
25 Sodium is tested on a variety of compilers and operating systems,
26 including Windows, iOS and Android.
28 ## Installation
30 Sodium is a shared library with a machine-independent set of
31 headers, so that it can easily be used by 3rd party projects.
33 The library is built using autotools, making it easy to package.
35 Installation is trivial, and both compilation and testing can take
36 advantage of multiple CPU cores.
38 Download a
39 [tarball of libsodium](http://download.dnscrypt.org/libsodium/releases/),
40 then follow the ritual:
42     ./configure
43     make && make check && make install
45 Pre-compiled Win32 packages are available for download at the same
46 location.
48 ## Comparison with vanilla NaCl
50 Sodium does not ship C++ bindings. These might be part of a distinct
51 package.
53 The default public-key signature system in NaCl was a prototype that
54 shouldn't be used any more.
56 Sodium ships with the SUPERCOP reference implementation of
57 [Ed25519](http://ed25519.cr.yp.to/), and uses this system by default
58 for `crypto_sign*` operations.
60 For backward compatibility, the previous system is still compiled in,
61 as `crypto_sign_edwards25519sha512batch*`.
63 ## Additional features
65 The Sodium library provides some convenience functions in order to retrieve
66 the current version of the package and of the shared library:
68     const char *sodium_version_string(void);
69     const int   sodium_library_version_major(void);
70     const int   sodium_library_version_minor(void);
72 Headers are installed in `${prefix}/include/sodium`.
74 A convenience header includes everything you need to use the library:
76     #include <sodium.h>
78 This is not required, however, before any other libsodium function, you can
79 call:
81     sodium_init();
83 This will pick optimized implementations of some primitives, if they
84 appear to work as expected after running some tests, and these will be
85 used for subsequent operations. It only need to be called once.
87 This function is not thread-safe. No other Sodium functions should be
88 called until it successfully returns. In a multithreading environment,
89 if, for some reason, you really need to call `sodium_init()` while some
90 other Sodium functions may be running in different threads, add locks
91 accordingly (both around `sodium_init()` and around other functions).
93 Sodium also provides helper functions to generate random numbers,
94 leveraging `/dev/urandom` or `/dev/random` on *nix and the cryptographic
95 service provider on Windows. The interface is similar to
96 `arc4random(3)`. It is `fork(2)`-safe but not thread-safe. This holds
97 true for `crypto_sign_keypair()` and `crypto_box_keypair()` as well.
99     uint32_t randombytes_random(void);
101 Return a random 32-bit unsigned value.
103     void     randombytes_stir(void);
105 Generate a new key for the pseudorandom number generator. The file
106 descriptor for the entropy source is kept open, so that the generator
107 can be reseeded even in a chroot() jail.
109     uint32_t randombytes_uniform(const uint32_t upper_bound);
111 Return a value between 0 and upper_bound using a uniform distribution.
113     void     randombytes_buf(void * const buf, const size_t size);
115 Fill the buffer `buf` with `size` random bytes.
117     int      randombytes_close(void);
119 Close the file descriptor or the handle for the cryptographic service
120 provider.
122 A custom implementation of these functions can be registered with
123 `randombytes_set_implementation()`.
125 In addition, Sodium provides a function to securely wipe a memory
126 region:
128     void     sodium_memzero(void * const pnt, const size_t size);
129     
130 Warning: if a region has been allocated on the heap, you still have
131 to make sure that it can't get swapped to disk, possibly using
132 `mlock(2)`.
134 In order to compare memory zones in constant time, Sodium proides:
136     int      sodium_memcmp(const void * const b1_, const void * const b2_,
137                            size_t size);
139 ## New operations
141 ### crypto_shorthash
143 A lot of applications and programming language implementations have
144 been recently found to be vulnerable to denial-of-service attacks when
145 a hash function with weak security guarantees, like Murmurhash 3, was
146 used to construct a hash table.
148 In order to address this, Sodium provides the “shorthash” function,
149 currently implemented using SipHash-2-4. This very fast hash function
150 outputs short, but unpredictable (without knowing the secret key)
151 values suitable for picking a list in a hash table for a given key.
153 See `crypto_shorthash.h` for details.
155 ### crypto_generichash
157 This hash function provides:
159 * A variable output length (up to `crypto_generichash_BYTES_MAX` bytes)
160 * A variable key length (from no key at all to
161   `crypto_generichash_KEYBYTES_MAX` bytes)
162 * A simple interface as well as a streaming interface.
164 `crypto_generichash` is currently being implemented using
165 [Blake2](https://blake2.net/).
167 ## Constants available as functions
169 In addition to constants for key sizes, output sizes and block sizes,
170 Sodium provides these values through function calls, so that using
171 them from different languages is easier.
173 ## Bindings for other languages
175 * Erlang: [Erlang-NaCl](https://github.com/tonyg/erlang-nacl)
176 * Java: [Kalium](https://github.com/abstractj/kalium)
177 * Julia: [Sodium.jl](https://github.com/amitmurthy/Sodium.jl)
178 * Python: [PyNaCl](https://github.com/dstufft/pynacl)
179 * Racket: part of [CRESTaceans](https://github.com/mgorlick/CRESTaceans/tree/master/bindings/libsodium)
180 * Ruby: [RbNaCl](https://github.com/cryptosphere/rbnacl)
181 * Ruby: [Sodium](https://github.com/stouset/sodium)
183 ## CurveCP
185 CurveCP tools are part of a different project,
186 [libchloride](https://github.com/jedisct1/libchloride).
187 If you are interested in an embeddable CurveCP implementation, take a
188 look at [libcurvecpr](https://github.com/impl/libcurvecpr).
190 ## Mailing list
192 A mailing-list is available to discuss libsodium.
194 In order to join, just send a random mail to `sodium-subscribe` {at}
195 `pureftpd`{dot}`org`.