bcrypt-ruby 1.0.0 → 2.0.0

data/CHANGELOG

@@ -0,0 +1,8 @@
+1.0.0  Feb 27 2007
+ - Initial release.
+ 
+2.0.0  Mar 07 2007
+ - Removed BCrypt::Password#exactly_equals -- use BCrypt::Password#eql? instead.
+ - Added BCrypt::Password#is_password?.
+ - Refactored out BCrypt::Internals into more useful BCrypt::Engine.
+ - Added validation of secrets -- nil is not healthy.

data/Rakefile

@@ -4,9 +4,10 @@ require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
 require 'rake/clean'
 require 'rake/rdoctask'
+require "benchmark"
 
 PKG_NAME = "bcrypt-ruby"
-PKG_VERSION   = "1.0.0"
+PKG_VERSION   = "2.0.0"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -16,6 +17,14 @@ PKG_FILES = FileList[
   'ext/*.h',
   'ext/*.rb'
 ]
+CLEAN.include(
+  "ext/*.o",
+  "ext/*.bundle",
+  "ext/*.so"  
+)
+CLOBBER.include(
+  "doc/coverage"
+)
 
 task :default => [:spec]
 
@@ -24,30 +33,34 @@ 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_dir = 'doc/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']
+namespace :spec do
+  desc "Run all specs and store html output in doc/specs.html"
+  Spec::Rake::SpecTask.new('html') do |t|
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.spec_opts = ['--diff','--format html','--backtrace','--out doc/specs.html']
+  end
 end
 
 desc 'Generate RDoc'
 rd = Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'doc/output/rdoc'
+  rdoc.rdoc_dir = 'doc/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')
+  rdoc.rdoc_files.include('README', 'COPYING', 'CHANGELOG', 'lib/**/*.rb')
 end
 
 spec = Gem::Specification.new do |s|
   s.name = PKG_NAME
   s.version = PKG_VERSION
-  s.summary = "Blah."
+  s.summary = "OpenBSD's bcrypt() password hashing algorithm."
   s.description = <<-EOF
-    Woot.
+    bcrypt() is a sophisticated and secure hash algorithm designed by The OpenBSD project
+    for hashing passwords. bcrypt-ruby provides a simple, humane wrapper for safely handling
+    passwords.
   EOF
 
   s.files = PKG_FILES.to_a
@@ -71,8 +84,19 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.need_tar = true
 end
 
-task :compile do
+task :compile => [:clean] do
   Dir.chdir('./ext')
   system "ruby extconf.rb"
   system "make"
-end
+end
+
+task :benchmark do
+  TESTS = 100
+  TEST_PWD = "this is a test"
+  require "lib/bcrypt"
+  Benchmark.bmbm do |results|
+    4.upto(10) do |n|
+      results.report("cost #{n}:") { TESTS.times { BCrypt::Password.create(TEST_PWD, :cost => n) } }
+    end
+  end
+end

data/ext/bcrypt_ext.c

@@ -4,7 +4,7 @@ char   *bcrypt_gensalt(u_int8_t, u_int8_t *);
 char   *bcrypt(const char *, const char *);
 
 VALUE mBCrypt;
-VALUE mBCryptInternals;
+VALUE cBCryptEngine;
 
 /* Given a logarithmic cost parameter, generates a salt for use with +bc_crypt+.
  */
@@ -21,8 +21,8 @@ static VALUE bc_crypt(VALUE self, VALUE key, VALUE salt) {
 /* Create the BCrypt and BCrypt::Internals modules, and populate them with methods. */
 void Init_bcrypt_ext(){
 	mBCrypt = rb_define_module("BCrypt");
-	mBCryptInternals = rb_define_module_under(mBCrypt, "Internals");
+	cBCryptEngine = rb_define_class_under(mBCrypt, "Engine", rb_cObject);
 	
-	rb_define_method(mBCryptInternals, "__bc_salt", bc_salt, 2);
-	rb_define_method(mBCryptInternals, "__bc_crypt", bc_crypt, 2);
+	rb_define_singleton_method(cBCryptEngine, "__bc_salt", bc_salt, 2);
+	rb_define_singleton_method(cBCryptEngine, "__bc_crypt", bc_crypt, 2);
 }

data/lib/bcrypt.rb

@@ -1,40 +1,46 @@
 # A wrapper for OpenBSD's bcrypt/crypt_blowfish password-hashing algorithm.
 
-$: << "ext"
-require "bcrypt_ext"
+require "ext/bcrypt_ext"
 require "openssl"
 
 # A Ruby library implementing OpenBSD's bcrypt()/crypt_blowfish algorithm for
 # hashing passwords.
-module BCrypt
+module BCrypt  
   module Errors # :nodoc:
-    # The salt parameter provided to bcrypt() is invalid.
-    class InvalidSalt < Exception; end
-    # The hash parameter provided to bcrypt() is invalid.
-    class InvalidHash < Exception; end
-    # The cost parameter provided to bcrypt() is invalid.
-    class InvalidCost < Exception; end
+    class InvalidSalt   < Exception; end  # The salt parameter provided to bcrypt() is invalid.
+    class InvalidHash   < Exception; end  # The hash parameter provided to bcrypt() is invalid.
+    class InvalidCost   < Exception; end  # The cost parameter provided to bcrypt() is invalid.
+    class InvalidSecret < Exception; end  # The secret parameter provided to bcrypt() is invalid.
   end
   
-  # The default computational expense parameter.
-  DEFAULT_COST = 10
-  
-  module Internals # :nodoc:
-    # contains the C-level methods and other internally bits
-    
-    # Maximum length of salts.
+  # A Ruby wrapper for the bcrypt() extension calls.
+  class Engine
+    # The default computational expense parameter.
+    DEFAULT_COST    = 10
+    # Maximum possible size of bcrypt() salts.
     MAX_SALT_LENGTH = 16
     
-    # Wrap this in some error checking otherwise it'll explode.
-    def _bc_crypt(key, salt)
-      if valid_salt?(salt)
-        __bc_crypt(key, salt)
+    # 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
+    
+    # Given a secret and a valid salt (see BCrypt::Engine.generate_salt) calculates
+    # a bcrypt() password hash.
+    def self.hash(secret, salt)
+      if valid_secret?(secret)
+        if valid_salt?(salt)
+          __bc_crypt(secret, salt)
+        else
+          raise Errors::InvalidSalt.new("invalid salt")
+        end
       else
-        raise Errors::InvalidSalt.new("invalid salt")
+        raise Errors::InvalidSecret.new("invalid secret")
       end
     end
     
-    def _bc_salt(cost = DEFAULT_COST)
+    # Generates a random salt with a given computational cost.
+    def self.generate_salt(cost = DEFAULT_COST)
       if cost.to_i > 0
         __bc_salt(cost, OpenSSL::Random.random_bytes(MAX_SALT_LENGTH))
       else
@@ -42,29 +48,35 @@ module BCrypt
       end
     end
     
-    def valid_salt?(s)
-      s =~ /^\$[0-9a-z]{2,}\$[0-9]{2,}\$[A-Za-z0-9\.\/]{22,}$/
+    # 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
-  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
+    
+    # Returns true if +secret+ is a valid bcrypt() secret, false if not.
+    def self.valid_secret?(secret)
+      !secret.nil?
+    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
   end
   
@@ -109,11 +121,9 @@ module BCrypt
       # Example:
       # 
       #   @password = BCrypt::Password.create("my secret", :cost => 13)
-      def create(secret, options = { :cost => DEFAULT_COST })
-        Password.new(_bc_crypt(secret, _bc_salt(options[:cost])))
+      def create(secret, options = { :cost => BCrypt::Engine::DEFAULT_COST })
+        Password.new(BCrypt::Engine.hash(secret, BCrypt::Engine.generate_salt(options[:cost])))
       end
-    private
-      include Internals
     end
     
     # Initializes a BCrypt::Password instance with the data from a stored hash.
@@ -126,12 +136,11 @@ module BCrypt
       end
     end
     
-    alias_method :exactly_equals, :==
-    
     # Compares a potential secret against the hash. Returns true if the secret is the original secret, false otherwise.
     def ==(secret)
-      self.exactly_equals(self.class._bc_crypt(secret, @salt))
+      super(BCrypt::Engine.hash(secret, @salt))
     end
+    alias_method :is_password?, :==
     
   private
     # Returns true if +h+ is a valid hash.

data/spec/bcrypt/{internals_spec.rb → engine_spec.rb}

@@ -1,35 +1,49 @@
 require File.join(File.dirname(__FILE__), "..", "spec_helper")
 
+context "The BCrypt engine" do
+  specify "should calculate the optimal cost factor to fit in a specific time" do
+    first = BCrypt::Engine.calibrate(100)
+    second = BCrypt::Engine.calibrate(300)
+    second.should >(first + 1)
+  end
+end
+
 context "Generating BCrypt salts" do
-  include BCrypt::Internals
   
   specify "should produce strings" do
-    _bc_salt.should be_an_instance_of(String)
+    BCrypt::Engine.generate_salt.should be_an_instance_of(String)
   end
   
   specify "should produce random data" do
-    _bc_salt.should_not equal(_bc_salt)
+    BCrypt::Engine.generate_salt.should_not equal(BCrypt::Engine.generate_salt)
   end
   
   specify "should raise a InvalidCostError if the cost parameter isn't numeric" do
-    lambda { _bc_salt('woo') }.should raise_error(BCrypt::Errors::InvalidCost)
+    lambda { BCrypt::Engine.generate_salt('woo') }.should raise_error(BCrypt::Errors::InvalidCost)
+  end
+  
+  specify "should raise a InvalidCostError if the cost parameter isn't greater than 0" do
+    lambda { BCrypt::Engine.generate_salt(-1) }.should raise_error(BCrypt::Errors::InvalidCost)
   end
 end
 
 context "Generating BCrypt hashes" do
-  include BCrypt::Internals
   
   setup do
-    @salt = _bc_salt
+    @salt = BCrypt::Engine.generate_salt(4)
     @password = "woo"
   end
   
   specify "should produce a string" do
-    _bc_crypt(@password, @salt).should be_an_instance_of(String)
+    BCrypt::Engine.hash(@password, @salt).should be_an_instance_of(String)
+  end
+  
+  specify "should raise an InvalidSalt error if the salt is invalid" do
+    lambda { BCrypt::Engine.hash(@password, 'nino') }.should raise_error(BCrypt::Errors::InvalidSalt)
   end
   
-  specify "should raise an InvalidSaltError if the salt is invalid" do
-    lambda { _bc_crypt(@password, 'nino') }.should raise_error(BCrypt::Errors::InvalidSalt)
+  specify "should raise an InvalidSecret error if the secret is invalid" do
+    lambda { BCrypt::Engine.hash(nil, @salt) }.should raise_error(BCrypt::Errors::InvalidSecret)
   end
   
   specify "should be interoperable with other implementations" do
@@ -42,7 +56,7 @@ context "Generating BCrypt hashes" do
       ["0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789", "$2a$05$abcdefghijklmnopqrstuu", "$2a$05$abcdefghijklmnopqrstuu5s2v8.iXieOjg/.AySBTTZIIVFJeBui"]
     ]
     for secret, salt, test_vector in test_vectors
-      _bc_crypt(secret, salt).should eql(test_vector)
+      BCrypt::Engine.hash(secret, salt).should eql(test_vector)
     end
   end
 end

data/spec/bcrypt/password_spec.rb

@@ -4,7 +4,7 @@ context "Creating a hashed password" do
   
   setup do
     @secret = "wheedle"
-    @password = BCrypt::Password.create(@secret)
+    @password = BCrypt::Password.create(@secret, :cost => 4)
   end
   
   specify "should return a BCrypt::Password" do
@@ -15,6 +15,9 @@ context "Creating a hashed password" do
     lambda { BCrypt::Password.new(@password) }.should_not raise_error
   end
   
+  specify "should raise an InvalidSecret exception if the secret is nil" do
+    lambda { BCrypt::Password.create(nil) }.should raise_error(BCrypt::Errors::InvalidSecret)
+  end
 end
 
 context "Reading a hashed password" do

metadata

@@ -3,15 +3,15 @@ rubygems_version: 0.9.1
 specification_version: 1
 name: bcrypt-ruby
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
-date: 2007-02-27 00:00:00 -08:00
-summary: Blah.
+  version: 2.0.0
+date: 2007-03-07 00:00:00 -08:00
+summary: OpenBSD's bcrypt() password hashing algorithm.
 require_paths: 
 - lib
 email: coda.hale@gmail.com
 homepage: http://bcrypt-ruby.rubyforge.org
 rubyforge_project: bcrypt-ruby
-description: Woot.
+description: bcrypt() is a sophisticated and secure hash algorithm designed by The OpenBSD project for hashing passwords. bcrypt-ruby provides a simple, humane wrapper for safely handling passwords.
 autorequire: bcrypt
 default_executable: 
 bindir: bin
@@ -29,13 +29,13 @@ post_install_message:
 authors: 
 - - Coda Hale
 files: 
+- CHANGELOG
 - COPYING
 - Rakefile
 - README
 - lib/bcrypt.rb
 - spec/spec_helper.rb
-- spec/bcrypt/bcrypt_spec.rb
-- spec/bcrypt/internals_spec.rb
+- spec/bcrypt/engine_spec.rb
 - spec/bcrypt/password_spec.rb
 - ext/bcrypt.c
 - ext/bcrypt_ext.c
@@ -54,6 +54,7 @@ rdoc_options:
 extra_rdoc_files: 
 - README
 - COPYING
+- CHANGELOG
 - lib/bcrypt.rb
 executables: []
 

data/spec/bcrypt/bcrypt_spec.rb

@@ -1,9 +0,0 @@
-require File.join(File.dirname(__FILE__), "..", "spec_helper")
-
-context "BCrypt" do
-  specify "should calculate the optimal cost factor to fit in a specific time" do
-    first = BCrypt.calibrate(100)
-    second = BCrypt.calibrate(300)
-    second.should >(first + 1)
-  end
-end