From 1a1db528c8442bcf6b0aed55c8f89b7370bdc703 Mon Sep 17 00:00:00 2001 From: James Spencer Date: Sun, 9 Nov 2014 15:26:00 +1100 Subject: [PATCH] Use markdown in readme --- README.md | 211 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ab7188f --- /dev/null +++ b/README.md @@ -0,0 +1,211 @@ +### About. + + This package provides Erlang bindings for 'libsodium', a portable packaging + of NaCl cryptography library. The bindings are pretty complete, covering all + public APIs of all chosen primitives through NIF code in 'c_src/salt_nif.c' + and supporting Erlang modules. + + NaCl provides high-speed cryptographic primitives whose implementations + are resilient to side-channel attacks by design. The API exposes high-level + operations with clear security contracts and minimal space for user to + introduce undue risks accidentally. This is ideal for the working engineer + wishing to improve upon security aspects of his/her designs but unable or + unwilling to engage in fragile low-level cryptoplumbing. + + Most of the crypto is performed directly on scheduler threads without visible + side effects (aside from allocation of result terms) and without performing + any system or library calls (outside libsodium). Upper bound on execution + latency is imposed indirectly by limiting input block sizes throughout. + + This is not considered to be a problematic decision as it is likely that + networking applications will likewise prefer to limit maximum PDU size, and + storage applications are likely to operate on blocks of constant size. Fine + tuning of the limit may be desirable looking forward, current value of 16KB + is chosen arbitrarily. Future changes should be supported by measurements on + relevant CPUs with the target of one reduction per operation, or cca 1ms. + The author defines "relevant CPUs" as "enteprise class amd64 chips" :-). + + Key generation and RNG routines are (at least potentially) blocking and + are therefore perfomed on a worker thread via call too 'salt_server'. This + means all these calls get serialized and incur somewhat higher latency. It + is reasonable to expect key generation to only be performed at relatively + low frequencies. The same hopefully applies to random bytes generation. + +### References. + +Websites + + * Home of NaCl project: [http://nacl.cr.yp.to](http://nacl.cr.yp.to) + * Home of libsodium: [https://github.com/jedisct1/libsodium](https://github.com/jedisct1/libsodium) + * Home of Salt: [https://github.com/freza/salt](https://github.com/freza/salt) + + Papers + + **"The security impact of a new cryptographic library"** + + Daniel J. Bernstein, Tanja Lange, Peter Schwabe + [http://cr.yp.to/highspeed/coolnacl-20120725.pdf](http://cr.yp.to/highspeed/coolnacl-20120725.pdf) + + **"Cryptography in NaCl"** + + Daniel J. Bernstein + [http://cr.yp.to/highspeed/naclcrypto-20090310.pdf](http://cr.yp.to/highspeed/naclcrypto-20090310.pdf) + +### Credits and Licensing. + + The original NaCl code was released by Daniel J. Bernstein, Tanja Lange, + Peter Schwabe and contributors into the public domain. + + Libsodium, by Frank Denis and contributors, is subject to ISC license. + + Salt, by Jachym Holecek and contributors, is subject to a 2-clause BSD + license. + +### Compiling. + + * Install 'libsodium': + +```sh + $ git clone git@github.com:jedisct1/libsodium.git + $ ( cd libsodium && \ + ./configure --prefix="/usr/local" --disable-ssp --disable-pie \ + --disable-silent-rules && \ + make && make check && sudo make install && make clean ) +``` + + * Build 'salt', you'll need 'rebar' utility: + +```sh + $ git clone git@github.com:freza/salt.git + $ ( cd salt && rebar clean && rebar compile ) +``` + + * To run a simple self-test have a look at '_run' script. + + * The 'salt_test' module is also a good source of simple usage examples. + +### TODO + + * Verify current message/block size limit of 16KB corresponds to reasonable + latency. + * Also export BLAKE2b hash function, despite not having "chosen" status. + * Perform 'libsodium' initialization from worker thread before app startup + completes. + +### Data types. + + XXX document variables mentioned below, pretty obvious, + XXX also see include/salt.hrl + +### Public-key cryptography. + +```erlang + crypto_box_keypair() -> + {Public_key, Secret_key}. + + crypto_box(Plain_text, Nonce, Public_key, Secret_key) -> + Cipher_text. + + crypto_box_open(Cipher_text, Nonce, Public_key, Secret_key) -> + {ok, Plain_text} | forged_or_garbled. + + crypto_box_beforenm(Public_key, Secret_key) -> + Context. + + crypto_box_afternm(Plain_text, Nonce, Context) -> + Cipher_text. + + crypto_box_open_afternm(Cipher_text, Nonce, Context) -> + {ok, Plain_text} | forged_or_garbled. +``` + +## Scalar multiplication. + +```erlang + crypto_scalarmult(Integer, Group_p) -> + Group_q. + + crypto_scalarmult_base(Integer) -> + Group_q. +``` + +## Signatures. + +```erlang + crypto_sign_keypair() -> + {Public_key, Secret_key}. + + crypto_sign(Message, Secret_key) -> + Signed_msg. + + crypto_sign_open(Signed_msg, Public_key) -> + {ok, Verified_msg} | forged_or_garbled. +``` + +### Secret-key cryptography. + +## Authenticated encryption. + +```erlang + crypto_secretbox(Plain_text, Nonce, Secret_key) -> + Cipher_text. + + crypto_secretbox_open(Cipher_text, Nonce, Secret_key) -> + {ok, Plain_text} | forged_or_garbled. +``` + +## Encryption. + +```erlang + crypto_stream(Byte_cnt, Nonce, Secret_key) -> + Byte_stream. + + crypto_stream_xor(In_text, Nonce, Secret_key) -> + Out_text. +``` + +## Message authentication. + +```erlang + crypto_auth(Message, Secret_key) -> + Authenticator. + + crypto_auth_verify(Authenticator, Message, Secret_key) -> + authenticated | forged_or_garbled. +``` + +## Single-message authentication. + +```erlang + crypto_onetimeauth(Message, Secret_key) -> + Authenticator. + + crypto_onetimeauth_verify(Authenticator, Message, Secret_key) -> + authenticated | forged_or_garbled. +``` + +### Low-level functions. + +## Hashing. + +```erlang + crypto_hash(Message) -> + Hash_bin. +``` + +## String comparison. + +```erlang + crypto_verify_16(Bin_x, Bin_y) -> + equal | not_equal. + + crypto_verify_32(Bin_x, Bin_y) -> + equal | not_equal. +``` + +## Random number generator. + +```erlang + crypto_random_bytes(Cnt) -> + Bytes. +``` \ No newline at end of file