Permalink
Browse files

update documentation

  • Loading branch information...
1 parent 15a9f59 commit 5145b694152e06a6471873f1a21b3f75367893f9 @mogest committed Jun 10, 2012
Showing with 73 additions and 5 deletions.
  1. +0 −5 README
  2. +73 −0 README.rdoc
View
5 README
@@ -1,5 +0,0 @@
-The beginnings of a library that wraps djb's NaCl "networking and cryptography" library.
-
-Find out more about that project at http://nacl.cace-project.eu/.
-
-This wrapper library licensed under the MIT licence. Copyright 2012 Roger Nesbitt.
View
@@ -0,0 +1,73 @@
+= NaCl
+
+A library that wraps part of djb's NaCl "networking and cryptography" library.
+
+Find out more about that project at http://nacl.cace-project.eu/.
+
+== Prerequisites
+
+This library requires MRI Ruby 1.8 or 1.9. It should work anywhere where NaCl compiles (most UNIXes).
+
+You must first install the NaCl C library before installing the gem. If you use homebrew on OS X, this is as simple as:
+
+ brew install nacl
+
+== Install
+
+ gem install nacl
+
+== How To Use
+
+=== Public-key Authenticated Encryption
+
+Want to provide <b>authenticated encryption</b>? Easy:
+
+ alice_pub, alice_sec = NaCl.crypto_box_keypair
+ bob_pub, bob_sec = NaCl.crypto_box_keypair
+
+ # Alice and Bob exchange their public keys.
+ # Now Alice can make a message for Bob:
+
+ nonce = SecureRandom.random_bytes(NaCl::BOX_NONCE_LENGTH)
+ ciphertext = NaCl.crypto_box("Meet me at the park at midnight", nonce, bob_pub, alice_sec)
+
+ # Alice then sends [ciphertext, nonce] to Bob and he can decrypt:
+
+ NaCl.crypto_box_open(ciphertext, nonce, alice_pub, bob_sec) # => "Meet me at the park at midnight"
+
+=== Public-key Authentication
+
+Just want to sign the text, but not encrypt it? No problem:
+
+ alice_pub, alice_sec = NaCl.crypto_sign_keypair
+
+ # Alice sends Bob her public key.
+ # Now Alice can make a message for Bob:
+
+ signed_text = NaCl.crypto_sign("Meet me at the park at midnight", alice_sec)
+
+ # Alice then sends [signed_text, nonce] to Bob and he can validate the signature:
+
+ NaCl.crypto_sign_open(signed_text, alice_pub) # => "Meet me at the park at midnight"
+
+ NaCl.crypto_sign_open(signed_text.gsub("park", "bus stop"), alice_pub) # raises NaCl::OpenError
+
+=== Secret-key Authenticated Encryption
+
+Secret key encryption requires that the two parties share a key beforehand using some secure channel.
+
+ key = SecureRandom.random_bytes(NaCl::SECRETBOX_KEY_LENGTH)
+
+ # Alice and Bob share the key by some secure means.
+ # Now Alice can make a message for Bob:
+
+ nonce = SecureRandom.random_bytes(NaCl::BOX_NONCE_LENGTH)
+ ciphertext = NaCl.crypto_secretbox("Meet me at the park at midnight", nonce, key)
+
+ # Alice then sends [ciphertext, nonce] to Bob and he can decrypt:
+
+ NaCl.crypto_secretbox_open(ciphertext, nonce, key) # => "Meet me at the park at midnght"
+
+== Licence
+
+This wrapper library licensed under the MIT licence. Copyright 2012 Roger Nesbitt.

0 comments on commit 5145b69

Please sign in to comment.