Documentation, documentation, documentation.

README.md

@@ -9,7 +9,41 @@ This library provides bindings for the NaCl cryptographic library for Erlang. Se
 
 This package draws heavy inspiration from "erlang-nacl" by Tony Garnock-Jones.
 
+In addition, I would like to thank Steve Vinoski and Sverker Eriksson for providing the Dirty Scheduler API in the first place.
+
 # Rationale
 
-Doing crypto right in Erlang is not that easy. The obvious way to handle this is by the use of NIF implementations, but most C code will run to its conclusion once set off for processing. This is a major problem for a system which needs to keep its latency safe. The solution taken by this library is to use the new Dirty Scheduler API of Erlang in order to provide a safe way to handle the long-running cryptographic processing. It keeps the cryptographic primitives on the dirty schedulers and thus it avoids the major problem.
+Doing crypto right in Erlang is not that easy. The obvious way to handle this is by the use of NIF implementations, but most C code will run to its conclusion once set off for processing. This is a major problem for a system which needs to keep its latency in check. The solution taken by this library is to use the new Dirty Scheduler API of Erlang in order to provide a safe way to handle the long-running cryptographic processing. It keeps the cryptographic primitives on the dirty schedulers and thus it avoids the major problem.
 
+Focus has first and foremost been on the correct use of dirty schedulers, without any regard for speed. The plan is to extend the underlying implementation, while keeping the API stable. In a future version, we might want to make simple short-lived crypto-calls directly on the Erlang scheduler rather than moving these to a separate scheduler and paying the price of scheduler invocation.
+
+Also, while the standard `crypto` bindings in Erlang does a great job at providing cryptographic primitives, these are based on OpenSSL, which is known to be highly problematic in many ways. It is not as easy to use the OpenSSL library correctly as it is with these bindings. Rather than providing a low-level cipher suite, NaCl provides intermediate level primitives constructed as to protect the user against typical low-level cryptographic gotchas and problems.
+
+# Overview
+
+The NaCl cryptographic library provides a number of different cryptographic primitives. In the following, we split up the different generic primitives and explain them briefly.
+
+*A note on Nonces:* The crypto API makes use of "cryptographic nonces", that is arbitrary numbers which are used only once. For these primitives to be secure it is important to consult the NaCl documentation on their choice. They are large values so generating them randomly ensures security, provided the random number generator uses a sufficiently large period. If you end up using, say, the nonce `7` every time in communication while using the same keys, then the security falls.
+
+The reason you can pick the nonce values is because some uses are better off using a nonce-construction based on monotonically increasing numbers, while other uses do not. The advantage of a sequence is that it can be used to reject older messages in the stream and protect against replay attacks. So the correct use is up to the application in many cases.
+
+## Public Key cryptography
+
+This implements standard Public/Secret key cryptography. The implementation roughly consists of two major sections:
+
+* *Authenticated encryption:* provides a `box` primitive which encrypts and then also authenticates a message. The reciever is only able to open the sealed box if they posses the secret key and the authentication from the sender is correct.
+* *Signatures:* allows one party to sign a message (not encrypting it) so another party can verify the message has the right origin.
+
+## Secret key cryptography
+
+This implements cryptography where there is a shared secret key between parties.
+
+* *Authenticated encryption:* provides a `secret box` primitive in which we can encrypt a message with a shared key `k`. The box also authenticates the message, so a message with an invalid key will be rejected as well. This protects against the application obtaining garbage data.
+* *Enryption:* provides streams of bytes based on a Key and a Nonce. These streams can be used to `XOR` with a message to encrypt it. No authentication is provided. The API allows for the system to `XOR` the stream for you while producing the stream.
+* *Authentication:* Provides an implementation of a Message Authentication Code (MAC).
+* *One Time Authentication:* Authenticate a message, but do so one-time. That is, a sender may *never* authenticate several messages under the same key. Otherwise an attacker can forge authenticators with enough time. The primitive is simpler and faster than the MAC authenticator however, so it is useful in some situations.
+
+## Low-level functions
+
+* *Hashing:* Cryptographically secure hashing
+* *String comparison:* Implements guaranteed constant-time string comparisons to protect against timing attacks.

doc/overview.edoc

@@ -0,0 +1,4 @@
+@author Jesper Louis Andersen
+
+@title  enacl - Erlang bindings for the NaCl cryptographic library
+

src/enacl.erl

@@ -1,3 +1,17 @@
+%%% @doc Module enacl implements bindings to the NaCl/libsodium crypto-library
+%%% <p>This module implements NIF bindings to the library known as NaCl (pronounced "salt").
+%%% The NaCl library provides a sane cryptographic interface to the world in an attempt to
+%%% make it harder to abuse and misuse cryptographic primitives.</p>
+%%% <p>This module implements an Erlang-idiomatic API to the underlying library. If in doubt
+%%% about a primitive, always consult the underlying documentation.</p>
+%%% <p>There are two libraries in existence: NaCl and libsodium, the latter being a more
+%%% portable variant of the NaCl library. The C-level API is interchangeable so we can run
+%%% on any of these underlying libraries as seen from the Erlang world. We simply have to
+%%% restrict ourselves to the portion of the code base which is overlapping.</p>
+%%% <p><b>Warning:</b> The cryptographic strength of your implementation is no stronger than
+%%% plaintext cryptography unless you take care in using these primitives correctly. Hence,
+%%% implementors should use these primitives with that in mind.</p>
+%%% @end.
 -module(enacl).
 
 %% Public key crypto
@@ -27,8 +41,34 @@
 %% Low level helper functions
 %% -----------------
 
+%% @doc hash/1 hashes data into a cryptographically secure checksum.
+%% <p>Given a binary, `Data' of any size, run a cryptographically secure hash algorithm to
+%% produce a checksum of the data. This can be used to verify the integrity of a data block
+%% since the checksum have the properties of cryptographic hashes in general.</p>
+%% <p>The currently selected primitive (Nov. 2014) is SHA-512</p>
+%% @end
+-spec hash(Data) -> Checksum
+  when Data :: binary(),
+       Checksum :: binary().
+
 hash(Bin) -> enacl_nif:crypto_hash(Bin).
+
+%% @doc verify_16/2 implements constant time 16-byte string verification
+%% <p>A subtle problem in cryptographic software are timing attacks where an attacker exploits
+%% early exist in string verification if the strings happen to mismatch. This allows the
+%% attacker to time how long verification took and thus learn the structure of the desired
+%% string to use. The verify_16/2 call will check two 16 byte strings for equality while
+%% guaranteeing the equality operation is constant time.</p>
+%% <p>If the strings are not exactly 16 bytes, the comparison function will fail with badarg.</p>
+%% <p>Verification returns a boolean. `true' if the strings match, `false' otherwise.</p>
+%% @end
+-spec verify_16(binary(), binary()) -> boolean().
 verify_16(X, Y) -> enacl_nif:crypto_verify_16(X, Y).
+
+%% @doc verify_32/2 implements constant time 32-byte string verification
+%% This function works as {@link verify_16/2} but does so on 32 byte strings.
+%% @end
+-spec verify_32(binary(), binary()) -> boolean().
 verify_32(X, Y) -> enacl_nif:crypto_verify_32(X, Y).
 
 %% Public Key Crypto