Source

skerl / README.org

* skerl
** Overview
=skerl= is a NIF wrapper around Skein hashing functions

** Quick Start
   You must have [[http://erlang.org/download.html][Erlang/OTP R13B04]] or later and a GNU-style build
   system to compile and run =skerl=.

#+BEGIN_SRC shell
git clone git://github.com/basho/skerl.git
cd skerl
make
#+END_SRC

   Start up an Erlang shell with the path to =skerl= included.

#+BEGIN_SRC shell
cd path/to/skerl/ebin
erl
#+END_SRC

   Hash a binary by calling =skerl:hash/2= with the desired number of
   bits for the resulting hash:

#+BEGIN_SRC erlang
1> Bits = 256.
256
2> Data = <<"foobarbazquux">>.
<<"foobarbazquux">>
3> {ok, Hash} = skerl:hash(Bits, Data).
{ok,<<206,36,175,108,168,91,124,11,181,108,144,164,36,
      216,130,110,241,197,98,180,65,120,56,225,1,255,54,
      ...>>}
4> bit_size(Hash).
256
#+END_SRC

   You may find =skerl:hexhash/2= more useful, as it returns a
   hexadecimal-encoded string representing the hash:

#+BEGIN_SRC erlang
5> HexHash = skerl:hexhash(Bits, Data).      
<<"ce24af6ca85b7c0bb56c90a424d8826ef1c562b4417838e101ff3627dcc000bc">>
#+END_SRC

** The Skein Hash

The underlying hashing code in Skerl is the reference implementation
of Skein from the official NIST submission.

Skein is a [[http://csrc.nist.gov/groups/ST/hash/sha-3/Round3/submissions_rnd3.html][finalist candidate in the NIST competition to become SHA-3]].

It is a hash function designed by 
Niels Ferguson, Stefan Lucks, Bruce Schneier, Doug Whiting, Mihir
Bellare, Tadayoshi Kohno, Jon Callas, and Jesse Walker.

Details on the algorithm as submitted and known analysis can be found
at [[http://ehash.iaik.tugraz.at/wiki/Skein][ecrypt]].

A [[http://www.schneier.com/skein1.3.pdf][full paper on Skein]]
by the designers has been published.

The [[http://www.skein-hash.info/][official Skein page]] uses the headline:

Fast, Secure, Simple, Flexible, Efficient. And it rhymes with "rain."

** Contributing
   We encourage contributions to =skerl= from the community.

   1) Fork the =skerl= repository on [[https://github.com/basho/skerl][Github]].
   2) Clone your fork or add the remote if you already have a clone of
      the repository.
#+BEGIN_SRC shell
git clone git@github.com:yourusername/skerl.git
# or
git remote add mine git@github.com:yourusername/skerl.git
#+END_SRC
   3) Create a topic branch for your change.
#+BEGIN_SRC shell
git checkout -b some-topic-branch
#+END_SRC
   4) Make your change and commit. Use a clear and descriptive commit
      message, spanning multiple lines if detailed explanation is
      needed.
   5) Push to your fork of the repository and then send a pull-request
      through Github.
#+BEGIN_SRC shell
git push mine some-topic-branch
#+END_SRC
   6) A Basho engineer or community maintainer will review your patch
      and merge it into the main repository or send you feedback.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.