bcrypt-ruby 3.0.1 → 3.1.0

data/.gitignore

@@ -6,3 +6,4 @@ doc
 pkg
 *.class
 tmp/
+.DS_Store

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - "1.8.7"
+  - "1.9.2"
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+script: bundle exec rake

data/CHANGELOG

@@ -39,9 +39,14 @@
 2.1.2  Sep 16 2009
   - Fixed support for Solaris, OpenSolaris.
 
-3.0.0 Aug 24, 2011
+3.0.0  Aug 24 2011
   - Bcrypt C implementation replaced with a public domain implementation.
   - License changed to MIT
 
-3.0.1
+3.0.1  Sep 12 2011
   - create raises an exception if the cost is higher than 31. GH #27
+
+3.1.0  May 07 2013
+  - Add BCrypt::Password.valid_hash?(str) to check if a string is a valid bcrypt password hash
+  - BCrypt::Password cost should be set to DEFAULT_COST if nil
+  - Add BCrypt::Engine.cost attribute for getting/setting a default cost externally

data/Gemfile

@@ -1,2 +1,2 @@
-source :rubygems
+source 'https://rubygems.org'
 gemspec

data/Gemfile.lock

@@ -1,29 +1,35 @@
 PATH
   remote: .
   specs:
-    bcrypt-ruby (3.0.0)
+    bcrypt-ruby (3.1.0)
 
 GEM
-  remote: http://rubygems.org/
+  remote: https://rubygems.org/
   specs:
-    diff-lcs (1.1.2)
-    rake (0.8.7)
-    rake-compiler (0.7.5)
+    diff-lcs (1.2.4)
+    json (1.7.3)
+    json (1.7.3-java)
+    rake (10.0.4)
+    rake-compiler (0.8.3)
       rake
-    rspec (2.5.0)
-      rspec-core (~> 2.5.0)
-      rspec-expectations (~> 2.5.0)
-      rspec-mocks (~> 2.5.0)
-    rspec-core (2.5.1)
-    rspec-expectations (2.5.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.5.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
 
 PLATFORMS
   java
   ruby
+  x86-mingw32
 
 DEPENDENCIES
   bcrypt-ruby!
   rake-compiler
+  rdoc
   rspec

data/README.md

@@ -5,6 +5,8 @@ An easy way to keep your users' passwords secure.
 * http://bcrypt-ruby.rubyforge.org/
 * http://github.com/codahale/bcrypt-ruby/tree/master
 
+[![Build Status](https://travis-ci.org/codahale/bcrypt-ruby.png?branch=master)](https://travis-ci.org/codahale/bcrypt-ruby)
+
 ## 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
@@ -24,7 +26,7 @@ re-hash those passwords. This vulernability only affected the JRuby gem.
 
 ## How to install bcrypt
 
-    sudo gem install bcrypt-ruby
+    gem install bcrypt-ruby
 
 The bcrypt-ruby gem is available on the following ruby platforms:
 
@@ -34,6 +36,10 @@ The bcrypt-ruby gem is available on the following ruby platforms:
 
 ## How to use `bcrypt()` in your Rails application
 
+*Note*: Rails versions >= 3 ship with `ActiveModel::SecurePassword` which uses bcrypt-ruby.
+`has_secure_password` [docs](http://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html#method-i-has_secure_password) 
+implements a similar authentication strategy to the code below.
+
 ### The _User_ model
 
     require 'bcrypt'
@@ -165,6 +171,20 @@ The default cost factor used by bcrypt-ruby is 10, which is fine for session-bas
 stateless authentication architecture (e.g., HTTP Basic Auth), you will want to lower the cost factor to reduce your
 server load and keep your request times down. This will lower the security provided you, but there are few alternatives.
 
+To change the default cost factor used by bcrypt-ruby, use `BCrypt::Engine.cost = new_value`:
+
+    BCrypt::Password.create('secret').cost
+      #=> 10, the default provided by bcrypt-ruby
+
+    # set a new default cost
+    BCrypt::Engine.cost = 8
+    BCrypt::Password.create('secret').cost
+      #=> 8
+
+The default cost can be overridden as needed by passing an options hash with a different cost:
+
+    BCrypt::Password.create('secret', :cost => 6).cost  #=> 6
+
 ## More Information
 
 `bcrypt()` is currently used as the default password storage hash in OpenBSD, widely regarded as the most secure operating

data/Rakefile

@@ -1,10 +1,10 @@
 require 'rspec/core/rake_task'
-require 'rake/gempackagetask'
+require 'rubygems/package_task'
 require 'rake/extensiontask'
 require 'rake/javaextensiontask'
 require 'rake/contrib/rubyforgepublisher'
 require 'rake/clean'
-require 'rake/rdoctask'
+require 'rdoc/task'
 require 'benchmark'
 
 CLEAN.include(
@@ -37,14 +37,14 @@ RSpec::Core::RakeTask.new(:rcov) do |t|
 end
 
 desc 'Generate RDoc'
-rd = Rake::RDocTask.new do |rdoc|
+RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = 'doc/rdoc'
   rdoc.options += GEMSPEC.rdoc_options
   rdoc.template = ENV['TEMPLATE'] if ENV['TEMPLATE']
   rdoc.rdoc_files.include(*GEMSPEC.extra_rdoc_files)
 end
 
-Rake::GemPackageTask.new(GEMSPEC) do |pkg|
+Gem::PackageTask.new(GEMSPEC) do |pkg|
   pkg.need_zip = true
   pkg.need_tar = true
 end

data/bcrypt-ruby.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'bcrypt-ruby'
-  s.version = '3.0.1'
+  s.version = '3.1.0'
 
   s.summary = "OpenBSD's bcrypt() password hashing algorithm."
   s.description = <<-EOF
@@ -14,6 +14,7 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'rake-compiler'
   s.add_development_dependency 'rspec'
+  s.add_development_dependency 'rdoc'
 
   s.has_rdoc = true
   s.rdoc_options += ['--title', 'bcrypt-ruby', '--line-numbers', '--inline-source', '--main', 'README.md']
@@ -25,4 +26,5 @@ Gem::Specification.new do |s|
   s.email = "coda.hale@gmail.com"
   s.homepage = "http://bcrypt-ruby.rubyforge.org"
   s.rubyforge_project = "bcrypt-ruby"
+  s.license = "MIT"
 end

data/ext/jruby/bcrypt_jruby/BCrypt.java

@@ -386,7 +386,7 @@ public class BCrypt {
 	private static String encode_base64(byte d[], int len)
 		throws IllegalArgumentException {
 		int off = 0;
-		StringBuffer rs = new StringBuffer();
+		StringBuilder rs = new StringBuilder();
 		int c1, c2;
 
 		if (len <= 0 || len > d.length)
@@ -439,7 +439,7 @@ public class BCrypt {
 	 */
 	private static byte[] decode_base64(String s, int maxolen)
 		throws IllegalArgumentException {
-		StringBuffer rs = new StringBuffer();
+		StringBuilder rs = new StringBuilder();
 		int off = 0, slen = s.length(), olen = 0;
 		byte ret[];
 		byte c1, c2, c3, c4, o;
@@ -651,7 +651,7 @@ public class BCrypt {
 		byte passwordb[], saltb[], hashed[];
 		char minor = (char)0;
 		int rounds, off = 0;
-		StringBuffer rs = new StringBuffer();
+		StringBuilder rs = new StringBuilder();
 
 		if (salt.charAt(0) != '$' || salt.charAt(1) != '2')
 			throw new IllegalArgumentException ("Invalid salt version");
@@ -704,7 +704,7 @@ public class BCrypt {
 	 * @return	an encoded salt value
 	 */
 	public static String gensalt(int log_rounds, SecureRandom random) {
-		StringBuffer rs = new StringBuffer();
+		StringBuilder rs = new StringBuilder();
 		byte rnd[] = new byte[BCRYPT_SALT_LEN];
 
 		random.nextBytes(rnd);

data/ext/mri/bcrypt_ext.c

@@ -4,31 +4,6 @@
 static VALUE mBCrypt;
 static VALUE cBCryptEngine;
 
-#ifdef RUBY_VM
-#  define RUBY_1_9
-#endif
-
-#ifdef RUBY_1_9
-
-/* When on Ruby 1.9+, we will want to unlock the GIL while performing
- * expensive calculations, for greater concurrency. Do not do this for
- * cheap calculations because locking/unlocking the GIL incurs some overhead as well.
- */
-#define GIL_UNLOCK_COST_THRESHOLD 9
-
-typedef struct {
-    char       *output;
-    const char *key;
-    const char *salt;
-} BCryptArguments;
-
-static VALUE bcrypt_wrapper(void *_args) {
-    BCryptArguments *args = (BCryptArguments *)_args;
-    return (VALUE)ruby_bcrypt(args->output, args->key, args->salt);
-}
-
-#endif /* RUBY_1_9 */
-
 /* Given a logarithmic cost parameter, generates a salt for use with +bc_crypt+.
 */
 static VALUE bc_salt(VALUE self, VALUE prefix, VALUE count, VALUE input) {

data/ext/mri/extconf.rb

@@ -9,31 +9,9 @@ if RUBY_PLATFORM == "java"
     f.puts "\t@true"
   end
   exit 0
-elsif defined?(RUBY_ENGINE) && RUBY_ENGINE == "maglev"
-  # Maglev doesn't support C extensions, fall back to compiling an FFI usable
-  # library
-  File.open('Makefile', 'w') do |f|
-    f.puts <<-MAKEFILE
-CFLAGS = -fPIC
-OBJS = bcrypt.o blowfish.o
-DLIB = bcrypt_ext.so
-OS ?= $(strip $(shell uname -s | tr '[:upper:]' '[:lower:]'))
-ifeq ($(OS),darwin)
-	DLIB = bcrypt_ext.dylib
-	CFLAGS += -dynamiclib
-endif
-
-all: $(OBJS)
-	cc -shared -o $(DLIB) $(OBJS)
-install:
-	install $(DLIB) "../../lib/"
-clean:
-	$(RM) $(OBJS) bcrypt_ext.so
-    MAKEFILE
-  end
-  exit 0
 else
   require "mkmf"
+  have_header('ruby/util.h')
   dir_config("bcrypt_ext")
   create_makefile("bcrypt_ext")
 end

data/ext/mri/wrapper.c

@@ -24,7 +24,11 @@
 #endif
 
 #include <ruby.h>
+#ifdef HAVE_RUBY_UTIL_H
+#include <ruby/util.h>
+#else
 #include <util.h>
+#endif
 
 #define CRYPT_OUTPUT_SIZE		(7 + 22 + 31 + 1)
 #define CRYPT_GENSALT_OUTPUT_SIZE	(7 + 22 + 1)

data/lib/bcrypt.rb

@@ -1,4 +1,7 @@
-# A wrapper for OpenBSD's bcrypt/crypt_blowfish password-hashing algorithm.
+# A Ruby library implementing OpenBSD's bcrypt()/crypt_blowfish algorithm for
+# hashing passwords.
+module BCrypt
+end
 
 if RUBY_PLATFORM == "java"
   require 'java'
@@ -6,191 +9,7 @@ else
   require "openssl"
 end
 
-if defined?(RUBY_ENGINE) and RUBY_ENGINE == "maglev"
-  require 'bcrypt_engine'
-else
-  require 'bcrypt_ext'
-end
-
-# A Ruby library implementing OpenBSD's bcrypt()/crypt_blowfish algorithm for
-# hashing passwords.
-module BCrypt
-  module Errors
-    class InvalidSalt   < StandardError; end  # The salt parameter provided to bcrypt() is invalid.
-    class InvalidHash   < StandardError; end  # The hash parameter provided to bcrypt() is invalid.
-    class InvalidCost   < StandardError; end  # The cost parameter provided to bcrypt() is invalid.
-    class InvalidSecret < StandardError; end  # The secret parameter provided to bcrypt() is invalid.
-  end
-
-  # A Ruby wrapper for the bcrypt() C extension calls and the Java calls.
-  class Engine
-    # The default computational expense parameter.
-    DEFAULT_COST    = 10
-    # The minimum cost supported by the algorithm.
-    MIN_COST        = 4
-    # Maximum possible size of bcrypt() salts.
-    MAX_SALT_LENGTH = 16
-
-    if RUBY_PLATFORM != "java"
-      # C-level routines which, if they don't get the right input, will crash the
-      # hell out of the Ruby process.
-      private_class_method :__bc_salt
-      private_class_method :__bc_crypt
-    end
-
-    # Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates
-    # a bcrypt() password hash.
-    def self.hash_secret(secret, salt, cost = nil)
-      if valid_secret?(secret)
-        if valid_salt?(salt)
-          if cost.nil?
-            cost = autodetect_cost(salt)
-          end
-
-          if RUBY_PLATFORM == "java"
-            Java.bcrypt_jruby.BCrypt.hashpw(secret.to_s, salt.to_s)
-          else
-            __bc_crypt(secret.to_s, salt)
-          end
-        else
-          raise Errors::InvalidSalt.new("invalid salt")
-        end
-      else
-        raise Errors::InvalidSecret.new("invalid secret")
-      end
-    end
-
-    # Generates a random salt with a given computational cost.
-    def self.generate_salt(cost = DEFAULT_COST)
-      cost = cost.to_i
-      if cost > 0
-        if cost < MIN_COST
-          cost = MIN_COST
-        end
-        if RUBY_PLATFORM == "java"
-          Java.bcrypt_jruby.BCrypt.gensalt(cost)
-        else
-          prefix = "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"
-          __bc_salt(prefix, cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH))
-        end
-      else
-        raise Errors::InvalidCost.new("cost must be numeric and > 0")
-      end
-    end
-
-    # Returns true if +salt+ is a valid bcrypt() salt, false if not.
-    def self.valid_salt?(salt)
-      !!(salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/)
-    end
-
-    # Returns true if +secret+ is a valid bcrypt() secret, false if not.
-    def self.valid_secret?(secret)
-      secret.respond_to?(:to_s)
-    end
-
-    # Returns the cost factor which will result in computation times less than +upper_time_limit_in_ms+.
-    #
-    # Example:
-    #
-    #   BCrypt.calibrate(200)  #=> 10
-    #   BCrypt.calibrate(1000) #=> 12
-    #
-    #   # should take less than 200ms
-    #   BCrypt::Password.create("woo", :cost => 10)
-    #
-    #   # should take less than 1000ms
-    #   BCrypt::Password.create("woo", :cost => 12)
-    def self.calibrate(upper_time_limit_in_ms)
-      40.times do |i|
-        start_time = Time.now
-        Password.create("testing testing", :cost => i+1)
-        end_time = Time.now - start_time
-        return i if end_time * 1_000 > upper_time_limit_in_ms
-      end
-    end
-
-    # Autodetects the cost from the salt string.
-    def self.autodetect_cost(salt)
-      salt[4..5].to_i
-    end
-  end
-
-  # A password management class which allows you to safely store users' passwords and compare them.
-  #
-  # Example usage:
-  #
-  #   include BCrypt
-  #
-  #   # hash a user's password  
-  #   @password = Password.create("my grand secret")
-  #   @password #=> "$2a$10$GtKs1Kbsig8ULHZzO1h2TetZfhO4Fmlxphp8bVKnUlZCBYYClPohG"
-  #
-  #   # store it safely
-  #   @user.update_attribute(:password, @password)
-  #
-  #   # read it back
-  #   @user.reload!
-  #   @db_password = Password.new(@user.password)
-  #
-  #   # compare it after retrieval
-  #   @db_password == "my grand secret" #=> true
-  #   @db_password == "a paltry guess"  #=> false
-  #
-  class Password < String
-    # The hash portion of the stored password hash.
-    attr_reader :checksum
-    # The salt of the store password hash (including version and cost).
-    attr_reader :salt
-    # The version of the bcrypt() algorithm used to create the hash.
-    attr_reader :version
-    # The cost factor used to create the hash.
-    attr_reader :cost
-
-    class << self
-      # Hashes a secret, returning a BCrypt::Password instance. Takes an optional <tt>:cost</tt> option, which is a
-      # logarithmic variable which determines how computational expensive the hash is to calculate (a <tt>:cost</tt> of
-      # 4 is twice as much work as a <tt>:cost</tt> of 3). The higher the <tt>:cost</tt> the harder it becomes for
-      # attackers to try to guess passwords (even if a copy of your database is stolen), but the slower it is to check
-      # users' passwords.
-      #
-      # Example:
-      #
-      #   @password = BCrypt::Password.create("my secret", :cost => 13)
-      def create(secret, options = { :cost => BCrypt::Engine::DEFAULT_COST })
-        raise ArgumentError if options[:cost] > 31
-        Password.new(BCrypt::Engine.hash_secret(secret, BCrypt::Engine.generate_salt(options[:cost]), options[:cost]))
-      end
-    end
-
-    # Initializes a BCrypt::Password instance with the data from a stored hash.
-    def initialize(raw_hash)
-      if valid_hash?(raw_hash)
-        self.replace(raw_hash)
-        @version, @cost, @salt, @checksum = split_hash(self)
-      else
-        raise Errors::InvalidHash.new("invalid hash")
-      end
-    end
-
-    # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
-    def ==(secret)
-      super(BCrypt::Engine.hash_secret(secret, @salt))
-    end
-    alias_method :is_password?, :==
-
-  private
-    # Returns true if +h+ is a valid hash.
-    def valid_hash?(h)
-      h =~ /^\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}$/
-    end
-
-    # call-seq:
-    #   split_hash(raw_hash) -> version, cost, salt, hash
-    #
-    # Splits +h+ into version, cost, salt, and hash and returns them in that order.
-    def split_hash(h)
-      _, v, c, mash = h.split('$')
-      return v, c.to_i, h[0, 29].to_str, mash[-31, 31].to_str
-    end
-  end
-end
+require 'bcrypt_ext'
+require 'bcrypt/error'
+require 'bcrypt/engine'
+require 'bcrypt/password'

data/lib/bcrypt/engine.rb

@@ -0,0 +1,120 @@
+module BCrypt
+  # A Ruby wrapper for the bcrypt() C extension calls and the Java calls.
+  class Engine
+    # The default computational expense parameter.
+    DEFAULT_COST    = 10
+    # The minimum cost supported by the algorithm.
+    MIN_COST        = 4
+    # Maximum possible size of bcrypt() salts.
+    MAX_SALT_LENGTH = 16
+
+    if RUBY_PLATFORM != "java"
+      # C-level routines which, if they don't get the right input, will crash the
+      # hell out of the Ruby process.
+      private_class_method :__bc_salt
+      private_class_method :__bc_crypt
+    end
+
+    @cost = nil
+
+    # Returns the cost factor that will be used if one is not specified when
+    # creating a password hash.  Defaults to DEFAULT_COST if not set.
+    def self.cost
+      @cost || DEFAULT_COST
+    end
+
+    # Set a default cost factor that will be used if one is not specified when
+    # creating a password hash.
+    #
+    # Example:
+    #
+    #   BCrypt::Engine::DEFAULT_COST            #=> 10
+    #   BCrypt::Password.create('secret').cost  #=> 10
+    #
+    #   BCrypt::Engine.cost = 8
+    #   BCrypt::Password.create('secret').cost  #=> 8
+    #
+    #   # cost can still be overridden as needed
+    #   BCrypt::Password.create('secret', :cost => 6).cost  #=> 6
+    def self.cost=(cost)
+      @cost = cost
+    end
+
+    # Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates
+    # a bcrypt() password hash.
+    def self.hash_secret(secret, salt, cost = nil)
+      if valid_secret?(secret)
+        if valid_salt?(salt)
+          if cost.nil?
+            cost = autodetect_cost(salt)
+          end
+
+          if RUBY_PLATFORM == "java"
+            Java.bcrypt_jruby.BCrypt.hashpw(secret.to_s, salt.to_s)
+          else
+            __bc_crypt(secret.to_s, salt)
+          end
+        else
+          raise Errors::InvalidSalt.new("invalid salt")
+        end
+      else
+        raise Errors::InvalidSecret.new("invalid secret")
+      end
+    end
+
+    # Generates a random salt with a given computational cost.
+    def self.generate_salt(cost = self.cost)
+      cost = cost.to_i
+      if cost > 0
+        if cost < MIN_COST
+          cost = MIN_COST
+        end
+        if RUBY_PLATFORM == "java"
+          Java.bcrypt_jruby.BCrypt.gensalt(cost)
+        else
+          prefix = "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"
+          __bc_salt(prefix, cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH))
+        end
+      else
+        raise Errors::InvalidCost.new("cost must be numeric and > 0")
+      end
+    end
+
+    # Returns true if +salt+ is a valid bcrypt() salt, false if not.
+    def self.valid_salt?(salt)
+      !!(salt =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/)
+    end
+
+    # Returns true if +secret+ is a valid bcrypt() secret, false if not.
+    def self.valid_secret?(secret)
+      secret.respond_to?(:to_s)
+    end
+
+    # Returns the cost factor which will result in computation times less than +upper_time_limit_in_ms+.
+    #
+    # Example:
+    #
+    #   BCrypt::Engine.calibrate(200)  #=> 10
+    #   BCrypt::Engine.calibrate(1000) #=> 12
+    #
+    #   # should take less than 200ms
+    #   BCrypt::Password.create("woo", :cost => 10)
+    #
+    #   # should take less than 1000ms
+    #   BCrypt::Password.create("woo", :cost => 12)
+    def self.calibrate(upper_time_limit_in_ms)
+      40.times do |i|
+        start_time = Time.now
+        Password.create("testing testing", :cost => i+1)
+        end_time = Time.now - start_time
+        return i if end_time * 1_000 > upper_time_limit_in_ms
+      end
+    end
+
+    # Autodetects the cost from the salt string.
+    def self.autodetect_cost(salt)
+      salt[4..5].to_i
+    end
+  end
+
+end

data/lib/bcrypt/error.rb

@@ -0,0 +1,22 @@
+module BCrypt
+
+  class Error < StandardError  # :nodoc:
+  end
+
+  module Errors  # :nodoc:
+
+    # The salt parameter provided to bcrypt() is invalid.
+    class InvalidSalt < BCrypt::Error; end
+
+    # The hash parameter provided to bcrypt() is invalid.
+    class InvalidHash < BCrypt::Error; end
+
+    # The cost parameter provided to bcrypt() is invalid.
+    class InvalidCost < BCrypt::Error; end
+
+    # The secret parameter provided to bcrypt() is invalid.
+    class InvalidSecret < BCrypt::Error; end
+
+  end
+
+end

data/lib/bcrypt/password.rb

@@ -0,0 +1,87 @@
+module BCrypt
+  # A password management class which allows you to safely store users' passwords and compare them.
+  #
+  # Example usage:
+  #
+  #   include BCrypt
+  #
+  #   # hash a user's password
+  #   @password = Password.create("my grand secret")
+  #   @password #=> "$2a$10$GtKs1Kbsig8ULHZzO1h2TetZfhO4Fmlxphp8bVKnUlZCBYYClPohG"
+  #
+  #   # store it safely
+  #   @user.update_attribute(:password, @password)
+  #
+  #   # read it back
+  #   @user.reload!
+  #   @db_password = Password.new(@user.password)
+  #
+  #   # compare it after retrieval
+  #   @db_password == "my grand secret" #=> true
+  #   @db_password == "a paltry guess"  #=> false
+  #
+  class Password < String
+    # The hash portion of the stored password hash.
+    attr_reader :checksum
+    # The salt of the store password hash (including version and cost).
+    attr_reader :salt
+    # The version of the bcrypt() algorithm used to create the hash.
+    attr_reader :version
+    # The cost factor used to create the hash.
+    attr_reader :cost
+
+    class << self
+      # Hashes a secret, returning a BCrypt::Password instance. Takes an optional <tt>:cost</tt> option, which is a
+      # logarithmic variable which determines how computational expensive the hash is to calculate (a <tt>:cost</tt> of
+      # 4 is twice as much work as a <tt>:cost</tt> of 3). The higher the <tt>:cost</tt> the harder it becomes for
+      # attackers to try to guess passwords (even if a copy of your database is stolen), but the slower it is to check
+      # users' passwords.
+      #
+      # Example:
+      #
+      #   @password = BCrypt::Password.create("my secret", :cost => 13)
+      def create(secret, options = {})
+        cost = options[:cost] || BCrypt::Engine.cost
+        raise ArgumentError if cost > 31
+        Password.new(BCrypt::Engine.hash_secret(secret, BCrypt::Engine.generate_salt(cost), cost))
+      end
+
+      def valid_hash?(h)
+        h =~ /^\$[0-9a-z]{2}\$[0-9]{2}\$[A-Za-z0-9\.\/]{53}$/
+      end
+    end
+
+    # Initializes a BCrypt::Password instance with the data from a stored hash.
+    def initialize(raw_hash)
+      if valid_hash?(raw_hash)
+        self.replace(raw_hash)
+        @version, @cost, @salt, @checksum = split_hash(self)
+      else
+        raise Errors::InvalidHash.new("invalid hash")
+      end
+    end
+
+    # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
+    def ==(secret)
+      super(BCrypt::Engine.hash_secret(secret, @salt))
+    end
+    alias_method :is_password?, :==
+
+  private
+
+    # Returns true if +h+ is a valid hash.
+    def valid_hash?(h)
+      self.class.valid_hash?(h)
+    end
+
+    # call-seq:
+    #   split_hash(raw_hash) -> version, cost, salt, hash
+    #
+    # Splits +h+ into version, cost, salt, and hash and returns them in that order.
+    def split_hash(h)
+      _, v, c, mash = h.split('$')
+      return v, c.to_i, h[0, 29].to_str, mash[-31, 31].to_str
+    end
+  end
+
+end

data/spec/bcrypt/error_spec.rb

@@ -0,0 +1,37 @@
+require File.expand_path(File.join(File.dirname(__FILE__), "..", "spec_helper"))
+
+describe "Errors" do
+
+  shared_examples "descends from StandardError" do
+    it "can be rescued as a StandardError" do
+      described_class.should < StandardError
+    end
+  end
+
+  shared_examples "descends from BCrypt::Error" do
+    it "can be rescued as a BCrypt::Error" do
+      described_class.should < BCrypt::Error
+    end
+  end
+
+  describe BCrypt::Error do
+    include_examples "descends from StandardError"
+  end
+
+  describe BCrypt::Errors::InvalidCost do
+    include_examples "descends from BCrypt::Error"
+  end
+
+  describe BCrypt::Errors::InvalidHash do
+    include_examples "descends from BCrypt::Error"
+  end
+
+  describe BCrypt::Errors::InvalidSalt do
+    include_examples "descends from BCrypt::Error"
+  end
+
+  describe BCrypt::Errors::InvalidSecret do
+    include_examples "descends from BCrypt::Error"
+  end
+
+end

data/spec/bcrypt/password_spec.rb

@@ -40,6 +40,38 @@ describe "Reading a hashed password" do
     }.should raise_error(ArgumentError)
   end
 
+  specify "the cost should be set to the default if nil" do
+    BCrypt::Password.create("hello", :cost => nil).cost.should equal(BCrypt::Engine::DEFAULT_COST)
+  end
+
+  specify "the cost should be set to the default if empty hash" do
+    BCrypt::Password.create("hello", {}).cost.should equal(BCrypt::Engine::DEFAULT_COST)
+  end
+
+  specify "the cost should be set to the passed value if provided" do
+    BCrypt::Password.create("hello", :cost => 5).cost.should equal(5)
+  end
+
+  specify "the cost should be set to the global value if set" do
+    BCrypt::Engine.cost = 5
+    BCrypt::Password.create("hello").cost.should equal(5)
+    # unset the global value to not affect other tests
+    BCrypt::Engine.cost = nil
+  end
+
+  specify "the cost should be set to an overridden constant for backwards compatibility" do
+    # suppress "already initialized constant" warning
+    old_verbose, $VERBOSE = $VERBOSE, nil
+    old_default_cost = BCrypt::Engine::DEFAULT_COST
+
+    BCrypt::Engine::DEFAULT_COST = 5
+    BCrypt::Password.create("hello").cost.should equal(5)
+
+    # reset default to not affect other tests
+    BCrypt::Engine::DEFAULT_COST = old_default_cost
+    $VERBOSE = old_verbose
+  end
+
   specify "should read the version, cost, salt, and hash" do
     password = BCrypt::Password.new(@hash)
     password.version.should eql("2a")
@@ -80,3 +112,12 @@ describe "Validating a generated salt" do
     BCrypt::Engine.valid_salt?(BCrypt::Engine.generate_salt).should eq(true)
   end
 end
+
+describe "Validating a password hash" do
+  specify "should not accept an invalid password" do
+    BCrypt::Password.valid_hash?("i_am_so_not_valid").should be_false
+  end
+  specify "should accept a valid password" do
+    BCrypt::Password.valid_hash?(BCrypt::Password.create "i_am_so_valid").should be_true
+  end
+end

metadata

@@ -1,65 +1,83 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: bcrypt-ruby
-version: !ruby/object:Gem::Version 
-  hash: 5
+version: !ruby/object:Gem::Version
+  version: 3.1.0
   prerelease: 
-  segments: 
-  - 3
-  - 0
-  - 1
-  version: 3.0.1
 platform: ruby
-authors: 
+authors:
 - Coda Hale
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-12 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake-compiler
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
   name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id002
-description: "    bcrypt() is a sophisticated and secure hash algorithm designed by The OpenBSD project\n    for hashing passwords. bcrypt-ruby provides a simple, humane wrapper for safely handling\n    passwords.\n"
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "    bcrypt() is a sophisticated and secure hash algorithm designed
+  by The OpenBSD project\n    for hashing passwords. bcrypt-ruby provides a simple,
+  humane wrapper for safely handling\n    passwords.\n"
 email: coda.hale@gmail.com
 executables: []
-
-extensions: 
+extensions:
 - ext/mri/extconf.rb
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.md
 - COPYING
 - CHANGELOG
+- lib/bcrypt/engine.rb
+- lib/bcrypt/error.rb
+- lib/bcrypt/password.rb
 - lib/bcrypt.rb
-- lib/bcrypt_engine.rb
-files: 
+files:
 - .gitignore
 - .rspec
+- .travis.yml
 - CHANGELOG
 - COPYING
 - Gemfile
@@ -77,48 +95,49 @@ files:
 - ext/mri/ow-crypt.h
 - ext/mri/wrapper.c
 - lib/bcrypt.rb
-- lib/bcrypt_engine.rb
+- lib/bcrypt/engine.rb
+- lib/bcrypt/error.rb
+- lib/bcrypt/password.rb
 - spec/TestBCrypt.java
 - spec/bcrypt/engine_spec.rb
+- spec/bcrypt/error_spec.rb
 - spec/bcrypt/password_spec.rb
 - spec/spec_helper.rb
 homepage: http://bcrypt-ruby.rubyforge.org
-licenses: []
-
+licenses:
+- MIT
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --title
 - bcrypt-ruby
 - --line-numbers
 - --inline-source
 - --main
 - README.md
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: -315332781
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: -315332781
 requirements: []
-
 rubyforge_project: bcrypt-ruby
-rubygems_version: 1.8.8
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: OpenBSD's bcrypt() password hashing algorithm.
 test_files: []
-

data/lib/bcrypt_engine.rb

@@ -1,34 +0,0 @@
-require 'ffi'
-
-module BCrypt
-  class Engine
-    extend FFI::Library
-
-    BCRYPT_MAXSALT = 16
-    BCRYPT_SALT_OUTPUT_SIZE = 7 + (BCRYPT_MAXSALT * 4 + 2) / 3 + 1
-    BCRYPT_OUTPUT_SIZE = 128
-
-    ffi_lib File.expand_path("../bcrypt_ext", __FILE__)
-
-    attach_function :ruby_bcrypt, [:buffer_out, :string, :string], :string
-    attach_function :ruby_bcrypt_gensalt, [:buffer_out, :uint8, :pointer], :string
-
-    def self.__bc_salt(cost, seed)
-      buffer_out = FFI::Buffer.alloc_out(BCRYPT_SALT_OUTPUT_SIZE, 1)
-      seed_ptr = FFI::MemoryPointer.new(:uint8, BCRYPT_MAXSALT)
-      seed.bytes.to_a.each_with_index { |b, i| seed_ptr.int8_put(i, b) }
-      out = ruby_bcrypt_gensalt(buffer_out, cost, seed_ptr)
-      seed_ptr.free
-      buffer_out.free
-      out || ""
-    end
-
-    def self.__bc_crypt(key, salt, cost)
-      buffer_out = FFI::Buffer.alloc_out(BCRYPT_OUTPUT_SIZE, 1)
-      out = ruby_bcrypt(buffer_out, key || "", salt)
-      buffer_out.free
-      out && out.any? ? out : nil
-    end
-  end
-end
-