From c6802aa343a2aaf3598381b55563618a4f99c80d Mon Sep 17 00:00:00 2001 From: Frank Denis Date: Tue, 23 Apr 2013 14:18:45 -0700 Subject: [PATCH] Add some documentation. --- README.markdown | 53 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/README.markdown b/README.markdown index d0311dae..65bc73f1 100644 --- a/README.markdown +++ b/README.markdown @@ -73,12 +73,20 @@ A convenience header includes everything you need to use the library: #include -Before doing anything else with the library, call: +This is not required, however, before any other libsodium function, you can +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 only need to be called once. + This function is not thread-safe. No other Sodium functions should be -called until it successfully returns. +called until it successfully returns. In a multithreading environment, +if, for some reason, you really need to call `sodium_init()` while some +other Sodium functions may be running in different threads, add locks +accordingly (both around `sodium_init()` and around other functions). Sodium also provides helper functions to generate random numbers, leveraging `/dev/urandom` or `/dev/random` on *nix and the cryptographic @@ -120,6 +128,47 @@ 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 proides: + + int sodium_memcmp(const void * const b1_, const void * const b2_, + size_t size); + +## 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 high security margin while being fast as MD5 and providing more + flexibility +* A simple interface as well as a streaming interface. + +`crypto_generichash` is currently being implemented using +[Blake2](https://blake2.net/). + +## 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. + ## Bindings for other languages * Ruby: [RbNaCl](https://github.com/cryptosphere/rbnacl)