release/src/router/libsodium/README.markdown

   1 [![Build Status](https://travis-ci.org/jedisct1/libsodium.png?branch=master)](https://travis-ci.org/jedisct1/libsodium?branch=master)
   2
   3 ![libsodium](https://raw.github.com/jedisct1/libsodium/master/logo.png)
   4 ============
   5
   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.
   9
  10 NaCl's goal is to provide all of the core operations needed to build
  11 higher-level cryptographic tools.
  12
  13 Sodium is a portable, cross-compilable, installable, packageable
  14 crypto library based on NaCl, with a compatible API.
  15
  16 ## Portability
  17
  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.
  21
  22 Sodium performs tests at run-time, so that the same binary package can
  23 still run everywhere.
  24
  25 Sodium is tested on a variety of compilers and operating systems,
  26 including Windows, iOS and Android.
  27
  28 ## Installation
  29
  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.
  32
  33 The library is built using autotools, making it easy to package.
  34
  35 Installation is trivial, and both compilation and testing can take
  36 advantage of multiple CPU cores.
  37
  38 Download a
  39 [tarball of libsodium](http://download.dnscrypt.org/libsodium/releases/),
  40 then follow the ritual:
  41
  42     ./configure
  43     make && make check && make install
  44
  45 Pre-compiled Win32 packages are available for download at the same
  46 location.
  47
  48 ## Comparison with vanilla NaCl
  49
  50 Sodium does not ship C++ bindings. These might be part of a distinct
  51 package.
  52
  53 The default public-key signature system in NaCl was a prototype that
  54 shouldn't be used any more.
  55
  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.
  59
  60 For backward compatibility, the previous system is still compiled in,
  61 as `crypto_sign_edwards25519sha512batch*`.
  62
  63 ## Additional features
  64
  65 The Sodium library provides some convenience functions in order to retrieve
  66 the current version of the package and of the shared library:
  67
  68     const char *sodium_version_string(void);
  69     const int   sodium_library_version_major(void);
  70     const int   sodium_library_version_minor(void);
  71
  72 Headers are installed in `${prefix}/include/sodium`.
  73
  74 A convenience header includes everything you need to use the library:
  75
  76     #include <sodium.h>
  77
  78 This is not required, however, before any other libsodium function, you can
  79 call:
  80
  81     sodium_init();
  82
  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.
  86
  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).
  92
  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.
  98
  99     uint32_t randombytes_random(void);
 100
 101 Return a random 32-bit unsigned value.
 102
 103     void     randombytes_stir(void);
 104
 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.
 108
 109     uint32_t randombytes_uniform(const uint32_t upper_bound);
 110
 111 Return a value between 0 and upper_bound using a uniform distribution.
 112
 113     void     randombytes_buf(void * const buf, const size_t size);
 114
 115 Fill the buffer `buf` with `size` random bytes.
 116
 117     int      randombytes_close(void);
 118
 119 Close the file descriptor or the handle for the cryptographic service
 120 provider.
 121
 122 A custom implementation of these functions can be registered with
 123 `randombytes_set_implementation()`.
 124
 125 In addition, Sodium provides a function to securely wipe a memory
 126 region:
 127
 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)`.
 133
 134 In order to compare memory zones in constant time, Sodium proides:
 135
 136     int      sodium_memcmp(const void * const b1_, const void * const b2_,
 137                            size_t size);
 138
 139 ## New operations
 140
 141 ### crypto_shorthash
 142
 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.
 147
 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.
 152
 153 See `crypto_shorthash.h` for details.
 154
 155 ### crypto_generichash
 156
 157 This hash function provides:
 158
 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.
 163
 164 `crypto_generichash` is currently being implemented using
 165 [Blake2](https://blake2.net/).
 166
 167 ## Constants available as functions
 168
 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.
 172
 173 ## Bindings for other languages
 174
 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)
 182
 183 ## CurveCP
 184
 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).
 189
 190 ## Mailing list
 191
 192 A mailing-list is available to discuss libsodium.
 193
 194 In order to join, just send a random mail to `sodium-subscribe` {at}
 195 `pureftpd`{dot}`org`.