bcrypt-ruby 1.0.0

data/COPYING

@@ -0,0 +1,32 @@
+Copyright 2007 Coda Hale <coda.hale@gmail.com>
+
+This product includes software developed by Niels Provos.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. All advertising materials mentioning features or use of this software
+   must display the following acknowledgement:
+
+   This product includes software developed by Niels Provos.
+    
+4. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -0,0 +1,158 @@
+= bcrypt-ruby
+
+An easy way to keep your users' passwords secure.
+
+== Why you should use bcrypt
+
+If you store user passwords in the clear, then an attacker who steals a copy of your database has a giant list of emails
+and passwords. Some of your users will only have one password -- for their email account, for their banking account, for
+your application. A simple hack could escalate into massive identity theft.
+
+It's your responsibility as a web developer to make your web application secure -- blaming your users for not being
+security experts is not a professional response to risk.
+
+bcrypt allows you to easily harden your application against these kinds of attacks.
+
+== How to install bcrypt
+
+  sudo gem install bcrypt-ruby
+  
+You'll need a working compiler. (Win32 folks should use Cygwin or um, something else.)
+
+== How to use bcrypt in your Rails application
+
+=== The +User+ model
+
+  require 'bcrypt'
+  
+  class User < ActiveRecord::Base
+    # users.hash in the database is a :string
+    include BCrypt
+    
+    def password
+      @password ||= Password.new(hash)
+    end
+    
+    def password=(new_password)
+      @password = Password.create(new_password)
+      self.hash = @password
+    end
+    
+  end
+
+=== Creating an account
+
+  def create
+    @user = User.new(params[:user])
+    @user.password = params[:password]
+    @user.save!
+  end
+
+=== Authenticating a user
+
+  def login
+    @user = User.find_by_email(params[:email])
+    if @user.password == params[:password]
+      give_token
+    else
+      redirect_to home_url
+    end
+  end
+
+=== If a user forgets their password?
+
+  # assign them a random one and mail it to them, asking them to change it
+  def forgot_password
+    @user = User.find_by_email(params[:email])
+    random_password = Array.new(10).map { (65 + rand(58)).chr }.join
+    @user.password = random_password
+    @user.save!
+    Mailer.create_and_deliver_password_change(@user, random_password)
+  end
+
+== How to use bcrypt-ruby in general
+
+  require 'bcrypt'
+  
+  my_password = BCrypt::Password.create("my password") #=> "$2a$10$vI8aWBnW3fID.ZQ4/zo1G.q1lRps.9cGLcZEiGDMVr5yUP1KUOYTa"
+  
+  my_password.version              #=> "2a"
+  my_password.cost                 #=> 10
+  my_password == "my password"     #=> true
+  my_password == "not my password" #=> false
+  
+  my_password = BCrypt::Password.new("$2a$10$vI8aWBnW3fID.ZQ4/zo1G.q1lRps.9cGLcZEiGDMVr5yUP1KUOYTa")
+  my_password == "my password"     #=> true
+  my_password == "not my password" #=> false
+
+Check the rdocs for more details -- BCrypt, BCrypt::Password.
+
+== How bcrypt() works
+
+bcrypt() is a hashing algorithm designed by Niels Provos and David Mazières of the OpenBSD Project.
+
+Hash algorithms take a chunk of data (e.g., your user's password) and create a "digital fingerprint," or hash, of it.
+Because this process is not reversible, there's no way to go from the hash back to the password.
+
+In other words:
+
+  hash(p) #=> <unique gibberish>
+
+You can store the hash and check it against a hash made of a potentially valid password:
+
+  <unique gibberish> =? hash(just_entered_password)
+
+But even this has weaknesses -- attackers can just run lists of possible passwords through the same algorithm, store the
+results in a big database, and then look up the passwords by their hash:
+
+  PrecomputedPassword.find_by_hash(<unique gibberish>).password #=> "secret1"
+
+The solution to this is to add a small chunk of random data -- called a salt -- to the password before it's hashed:
+
+  hash(salt + p) #=> <really unique gibberish>
+
+The salt is then stored along with the hash in the database, and used to check potentially valid passwords:
+
+  <really unique gibberish> =? hash(salt + just_entered_password)
+  
+bcrypt-ruby automatically handles the storage and generation of these salts for you.
+
+Adding a salt means that an attacker has to have a gigantic database for each unique salt -- for a salt made of 4
+letters, that's 456,976 different databases. Pretty much no one has that much storage space, so attackers try a
+different, slower method -- throw a list of potential passwords at each individual password:
+
+  hash(salt + "aadvark") =? <really unique gibberish>
+  hash(salt + "abacus")  =? <really unique gibberish>
+  etc.
+  
+This is much slower than the big database approach, but most hash algorithms are pretty quick -- and therein lies the
+problem. Hash algorithms aren't usually designed to be slow, they're designed to turn gigabytes of data into secure
+fingerprints as quickly as possible. bcrypt(), though, is designed to be computationally expensive:
+
+  Ten thousand iterations:
+               user     system      total        real
+  md5      0.070000   0.000000   0.070000 (  0.070415)
+  bcrypt  22.230000   0.080000  22.310000 ( 22.493822)
+
+If an attacker was using Ruby to check each password, they could check ~140,000 passwords a second with MD5 but only
+~450 passwords a second with bcrypt().
+
+In addition, bcrypt() allows you to increase the amount of work required to hash a password as computers get faster. Old
+passwords will still work fine, but new passwords can keep up with the times.
+
+bcrypt() is currently used as the default password storage hash in OpenBSD, widely regarded as the most secure operating
+system available. 
+
+
+For a more technical explanation of the algorithm and its design criteria, please read Niels Provos and David Mazières'
+Usenix99 paper:
+http://www.usenix.org/events/usenix99/provos.html
+
+If you'd like more down-to-earth advice regarding cryptography, I suggest reading <i>Practical Cryptography</i> by Niels
+Ferguson and Bruce Schneier:
+http://www.schneier.com/book-practical.html
+
+= Etc
+
+Author  :: Coda Hale <coda.hale@gmail.com>
+Website :: http://blog.codahale.com

data/Rakefile

@@ -0,0 +1,78 @@
+gem "rspec"
+require "spec/rake/spectask"
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require 'rake/clean'
+require 'rake/rdoctask'
+
+PKG_NAME = "bcrypt-ruby"
+PKG_VERSION   = "1.0.0"
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+PKG_FILES = FileList[
+  '[A-Z]*',
+  'lib/**/*.rb', 
+  'spec/**/*.rb', 
+  'ext/*.c',
+  'ext/*.h',
+  'ext/*.rb'
+]
+
+task :default => [:spec]
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--color','--backtrace','--diff']
+  t.rcov = true
+  t.rcov_dir = 'doc/output/coverage'
+  t.rcov_opts = ['--exclude', 'spec\/spec,spec\/.*_spec.rb']
+end
+
+desc "Run all specs and store html output in doc/output/report.html"
+Spec::Rake::SpecTask.new('spec_html') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--diff','--format html','--backtrace','--out doc/output/report.html']
+end
+
+desc 'Generate RDoc'
+rd = Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'doc/output/rdoc'
+  rdoc.options << '--title' << 'bcrypt-ruby' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.template = ENV['TEMPLATE'] if ENV['TEMPLATE']
+  rdoc.rdoc_files.include('README', 'COPYING', 'lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Blah."
+  s.description = <<-EOF
+    Woot.
+  EOF
+
+  s.files = PKG_FILES.to_a
+  s.require_path = 'lib'
+
+  s.has_rdoc = true
+  s.rdoc_options = rd.options
+  s.extra_rdoc_files = rd.rdoc_files.to_a
+  
+  s.extensions = FileList["ext/extconf.rb"].to_a
+  
+  s.autorequire = 'bcrypt'
+  s.author = ["Coda Hale"]
+  s.email = "coda.hale@gmail.com"
+  s.homepage = "http://bcrypt-ruby.rubyforge.org"
+  s.rubyforge_project = "bcrypt-ruby"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+task :compile do
+  Dir.chdir('./ext')
+  system "ruby extconf.rb"
+  system "make"
+end

data/ext/bcrypt.c

@@ -0,0 +1,334 @@
+/*	$OpenBSD: bcrypt.c,v 1.22 2007/02/20 01:44:16 ray Exp $	*/
+
+/*
+ * Modified by <coda.hale@gmail.com> on 2007-02-27:
+ *
+ *   - Changed bcrypt_gensalt to accept a random seed as a parameter,
+ *     to remove the code's dependency on arc4random(), which isn't
+ *     available on Linux. 
+ */
+
+/*
+ * Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. All advertising materials mentioning features or use of this software
+ *    must display the following acknowledgement:
+ *      This product includes software developed by Niels Provos.
+ * 4. The name of the author may not be used to endorse or promote products
+ *    derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/* This password hashing algorithm was designed by David Mazieres
+ * <dm@lcs.mit.edu> and works as follows:
+ *
+ * 1. state := InitState ()
+ * 2. state := ExpandKey (state, salt, password) 3.
+ * REPEAT rounds:
+ *	state := ExpandKey (state, 0, salt)
+ *      state := ExpandKey(state, 0, password)
+ * 4. ctext := "OrpheanBeholderScryDoubt"
+ * 5. REPEAT 64:
+ * 	ctext := Encrypt_ECB (state, ctext);
+ * 6. RETURN Concatenate (salt, ctext);
+ *
+ */
+
+#if 0
+#include <stdio.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <string.h>
+#include "blf.h"
+
+/* This implementation is adaptable to current computing power.
+ * You can have up to 2^31 rounds which should be enough for some
+ * time to come.
+ */
+
+#define BCRYPT_VERSION '2'
+#define BCRYPT_MAXSALT 16	/* Precomputation is just so nice */
+#define BCRYPT_BLOCKS 6		/* Ciphertext blocks */
+#define BCRYPT_MINROUNDS 16	/* we have log2(rounds) in salt */
+
+char   *bcrypt_gensalt(u_int8_t, u_int8_t *);
+
+static void encode_salt(char *, u_int8_t *, u_int16_t, u_int8_t);
+static void encode_base64(u_int8_t *, u_int8_t *, u_int16_t);
+static void decode_base64(u_int8_t *, u_int16_t, u_int8_t *);
+
+static char    encrypted[_PASSWORD_LEN];
+static char    gsalt[7 + (BCRYPT_MAXSALT * 4 + 2) / 3 + 1];
+static char    error[] = ":";
+
+const static u_int8_t Base64Code[] =
+"./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+
+const static u_int8_t index_64[128] = {
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
+	255, 255, 255, 255, 255, 255, 0, 1, 54, 55,
+	56, 57, 58, 59, 60, 61, 62, 63, 255, 255,
+	255, 255, 255, 255, 255, 2, 3, 4, 5, 6,
+	7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+	17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27,
+	255, 255, 255, 255, 255, 255, 28, 29, 30,
+	31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
+	41, 42, 43, 44, 45, 46, 47, 48, 49, 50,
+	51, 52, 53, 255, 255, 255, 255, 255
+};
+#define CHAR64(c)  ( (c) > 127 ? 255 : index_64[(c)])
+
+static void
+decode_base64(u_int8_t *buffer, u_int16_t len, u_int8_t *data)
+{
+	u_int8_t *bp = buffer;
+	u_int8_t *p = data;
+	u_int8_t c1, c2, c3, c4;
+	while (bp < buffer + len) {
+		c1 = CHAR64(*p);
+		c2 = CHAR64(*(p + 1));
+
+		/* Invalid data */
+		if (c1 == 255 || c2 == 255)
+			break;
+
+		*bp++ = (c1 << 2) | ((c2 & 0x30) >> 4);
+		if (bp >= buffer + len)
+			break;
+
+		c3 = CHAR64(*(p + 2));
+		if (c3 == 255)
+			break;
+
+		*bp++ = ((c2 & 0x0f) << 4) | ((c3 & 0x3c) >> 2);
+		if (bp >= buffer + len)
+			break;
+
+		c4 = CHAR64(*(p + 3));
+		if (c4 == 255)
+			break;
+		*bp++ = ((c3 & 0x03) << 6) | c4;
+
+		p += 4;
+	}
+}
+
+static void
+encode_salt(char *salt, u_int8_t *csalt, u_int16_t clen, u_int8_t logr)
+{
+	salt[0] = '$';
+	salt[1] = BCRYPT_VERSION;
+	salt[2] = 'a';
+	salt[3] = '$';
+
+	snprintf(salt + 4, 4, "%2.2u$", logr);
+
+	encode_base64((u_int8_t *) salt + 7, csalt, clen);
+}
+/* Generates a salt for this version of crypt.
+   Since versions may change. Keeping this here
+   seems sensible.
+ */
+
+char *
+bcrypt_gensalt(u_int8_t log_rounds, u_int8_t *rseed)
+{
+	if (log_rounds < 4)
+		log_rounds = 4;
+	else if (log_rounds > 31)
+		log_rounds = 31;
+
+	encode_salt(gsalt, rseed, BCRYPT_MAXSALT, log_rounds);
+	return gsalt;
+}
+/* We handle $Vers$log2(NumRounds)$salt+passwd$
+   i.e. $2$04$iwouldntknowwhattosayetKdJ6iFtacBqJdKe6aW7ou */
+
+char   *
+bcrypt(const char *key, const char *salt)
+{
+	blf_ctx state;
+	u_int32_t rounds, i, k;
+	u_int16_t j;
+	u_int8_t key_len, salt_len, logr, minor;
+	u_int8_t ciphertext[4 * BCRYPT_BLOCKS] = "OrpheanBeholderScryDoubt";
+	u_int8_t csalt[BCRYPT_MAXSALT];
+	u_int32_t cdata[BCRYPT_BLOCKS];
+	int n;
+
+	/* Discard "$" identifier */
+	salt++;
+
+	if (*salt > BCRYPT_VERSION) {
+		/* How do I handle errors ? Return ':' */
+		return error;
+	}
+
+	/* Check for minor versions */
+	if (salt[1] != '$') {
+		 switch (salt[1]) {
+		 case 'a':
+			 /* 'ab' should not yield the same as 'abab' */
+			 minor = salt[1];
+			 salt++;
+			 break;
+		 default:
+			 return error;
+		 }
+	} else
+		 minor = 0;
+
+	/* Discard version + "$" identifier */
+	salt += 2;
+
+	if (salt[2] != '$')
+		/* Out of sync with passwd entry */
+		return error;
+
+	/* Computer power doesn't increase linear, 2^x should be fine */
+	n = atoi(salt);
+	if (n > 31 || n < 0)
+		return error;
+	logr = (u_int8_t)n;
+	if ((rounds = (u_int32_t) 1 << logr) < BCRYPT_MINROUNDS)
+		return error;
+
+	/* Discard num rounds + "$" identifier */
+	salt += 3;
+
+	if (strlen(salt) * 3 / 4 < BCRYPT_MAXSALT)
+		return error;
+
+	/* We dont want the base64 salt but the raw data */
+	decode_base64(csalt, BCRYPT_MAXSALT, (u_int8_t *) salt);
+	salt_len = BCRYPT_MAXSALT;
+	key_len = strlen(key) + (minor >= 'a' ? 1 : 0);
+
+	/* Setting up S-Boxes and Subkeys */
+	Blowfish_initstate(&state);
+	Blowfish_expandstate(&state, csalt, salt_len,
+	    (u_int8_t *) key, key_len);
+	for (k = 0; k < rounds; k++) {
+		Blowfish_expand0state(&state, (u_int8_t *) key, key_len);
+		Blowfish_expand0state(&state, csalt, salt_len);
+	}
+
+	/* This can be precomputed later */
+	j = 0;
+	for (i = 0; i < BCRYPT_BLOCKS; i++)
+		cdata[i] = Blowfish_stream2word(ciphertext, 4 * BCRYPT_BLOCKS, &j);
+
+	/* Now do the encryption */
+	for (k = 0; k < 64; k++)
+		blf_enc(&state, cdata, BCRYPT_BLOCKS / 2);
+
+	for (i = 0; i < BCRYPT_BLOCKS; i++) {
+		ciphertext[4 * i + 3] = cdata[i] & 0xff;
+		cdata[i] = cdata[i] >> 8;
+		ciphertext[4 * i + 2] = cdata[i] & 0xff;
+		cdata[i] = cdata[i] >> 8;
+		ciphertext[4 * i + 1] = cdata[i] & 0xff;
+		cdata[i] = cdata[i] >> 8;
+		ciphertext[4 * i + 0] = cdata[i] & 0xff;
+	}
+
+
+	i = 0;
+	encrypted[i++] = '$';
+	encrypted[i++] = BCRYPT_VERSION;
+	if (minor)
+		encrypted[i++] = minor;
+	encrypted[i++] = '$';
+
+	snprintf(encrypted + i, 4, "%2.2u$", logr);
+
+	encode_base64((u_int8_t *) encrypted + i + 3, csalt, BCRYPT_MAXSALT);
+	encode_base64((u_int8_t *) encrypted + strlen(encrypted), ciphertext,
+	    4 * BCRYPT_BLOCKS - 1);
+	return encrypted;
+}
+
+static void
+encode_base64(u_int8_t *buffer, u_int8_t *data, u_int16_t len)
+{
+	u_int8_t *bp = buffer;
+	u_int8_t *p = data;
+	u_int8_t c1, c2;
+	while (p < data + len) {
+		c1 = *p++;
+		*bp++ = Base64Code[(c1 >> 2)];
+		c1 = (c1 & 0x03) << 4;
+		if (p >= data + len) {
+			*bp++ = Base64Code[c1];
+			break;
+		}
+		c2 = *p++;
+		c1 |= (c2 >> 4) & 0x0f;
+		*bp++ = Base64Code[c1];
+		c1 = (c2 & 0x0f) << 2;
+		if (p >= data + len) {
+			*bp++ = Base64Code[c1];
+			break;
+		}
+		c2 = *p++;
+		c1 |= (c2 >> 6) & 0x03;
+		*bp++ = Base64Code[c1];
+		*bp++ = Base64Code[c2 & 0x3f];
+	}
+	*bp = '\0';
+}
+#if 0
+void
+main()
+{
+	char    blubber[73];
+	char    salt[100];
+	char   *p;
+	salt[0] = '$';
+	salt[1] = BCRYPT_VERSION;
+	salt[2] = '$';
+
+	snprintf(salt + 3, 4, "%2.2u$", 5);
+
+	printf("24 bytes of salt: ");
+	fgets(salt + 6, sizeof(salt) - 6, stdin);
+	salt[99] = 0;
+	printf("72 bytes of password: ");
+	fpurge(stdin);
+	fgets(blubber, sizeof(blubber), stdin);
+	blubber[72] = 0;
+
+	p = crypt(blubber, salt);
+	printf("Passwd entry: %s\n\n", p);
+
+	p = bcrypt_gensalt(5);
+	printf("Generated salt: %s\n", p);
+	p = crypt(blubber, p);
+	printf("Passwd entry: %s\n", p);
+}
+#endif