sequel_password 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 35362ea38646639ac578a589a4d3165312474356
-  data.tar.gz: f2cc25b79d0a299e8f54705635404cfe707e1b9b
+  metadata.gz: b4483adb4a3a79018a1b330b14d7695c7695e508
+  data.tar.gz: d8129c412da70b141fe8ca6a7883b7ae0f876fd8
 SHA512:
-  metadata.gz: 06685b5e1e99c8b1688cf10b208c732ed3bfd46021ca824706d12e63921a797862d1105bb573f9268e975b1c75eebdb0a12361147e9b5e93bcd109a969963def
-  data.tar.gz: 1b4f6aefa06459f71bf315a350d104c1755c471a456969b238d377eb6c84a29cc52391add08f4f6187d4ad9975cc32645884a14fe3a9e8da333c7ec4cc999682
+  metadata.gz: c785779cf2df01c32339bb4175bb68a7b9184e2658c5a5914bc3fdf9d75d33b20f51b7ab2c950bb032c28107fe1885dc0811e0f033263cf2d0cf8e2b3e4957d8
+  data.tar.gz: 9dc83bf6afcc90646a7c0d46028f68a6ee0f4ed142400096dd2b57f1d4674b271e9cb8eb1103322dd0bd64e664c39d701c1a03790f7bca0bce99544ee803ca19

data/.gitignore

@@ -1,2 +1,4 @@
 coverage
 *.gem
+.yardoc
+doc/

data/README.md

@@ -3,10 +3,50 @@
 This sequel plugin adds authentication and password hashing to Sequel models.
 It supports pbkdf2 and bcrypt hashers.
 
-# Usage
+## Installation
+
+Install it directly using gem:
+
+```
+gem install sequel_password
+```
+
+Or adding it to your ``Gemfile``:
+
+```
+gem "sequel_password"
+```
+
+##  Usage
+
+### Configure
+
+A straightforward example, using the password column for storage explicitely,
+and using the default hashers:
 
 ```ruby
 class User < Sequel::Model
   plugin :password, column: :password
 end
 ```
+
+You can also specify a custom list of hashers to be used. The first hashers will
+be considered as the default, choose carefully:
+
+```ruby
+class User < Sequel::Model
+  plugin :password, hashers: {
+    pbkdf2_sha256: PBKDF2Hasher.new,
+    bcrypt_sha256: BCryptSHA256Hasher.new
+  }
+end
+```
+
+### Authenticate
+
+To authenticate users with their given plain text password:
+
+```ruby
+user = User[email: email]
+user && user.authenticate(password)
+```

data/lib/sequel_password/hashers.rb

@@ -7,22 +7,43 @@ require "securerandom"
 module Sequel
   module Plugins
     module Password
+      # @!attribute [r] algorithm
+      #   @return [Symbol] name of the alogorithm implemented by the hasher
+      # @abstract Subclass or override this class to implements a custom
+      #   Hasher.
       class Hasher
         attr_reader :algorithm
 
+        # Returns salt value to be used for hashing.
+        #
+        # @return [String] random salt value.
         def salt
           # 72 bits
           SecureRandom.hex(9)
         end
 
+        # Returns if the given password match the encoded password.
+        #
+        # @param [String] password in plain text
+        # @param [String] encoded password to be matched
+        # @return [Boolean] if password match encoded password.
         def verify(password, encoded)
           raise NotImplementedError
         end
 
+        # Returns given password encoded with the given salt.
+        #
+        # @param [String] password in plain text
+        # @param [String] salt to be used during hashing
+        # @return [String] given password hashed using the given salt
         def encode(password, salt)
           raise NotImplementedError
         end
 
+        # Returns if given encoded password needs to be updated.
+        #
+        # @param [String] encoded password
+        # @return [Boolean] if encoded password needs to be updated
         def must_update(encoded)
           false
         end
@@ -36,6 +57,8 @@ module Sequel
         end
       end
 
+      # PBKDF2Hasher implements a PBKDF2 password hasher using 24000 iterations
+      # by default.
       class PBKDF2Hasher < Hasher
         def initialize
           @algorithm = :pbkdf2_sha256
@@ -63,6 +86,7 @@ module Sequel
         end
       end
 
+      # BCryptSHA256Hasher implements a BCrypt password hasher using SHA256.
       class BCryptSHA256Hasher < Hasher
         def initialize
           @algorithm = :bcrypt_sha256
@@ -88,6 +112,7 @@ module Sequel
         end
       end
 
+      # BCryptHasher implements a BCrypt password hasher.
       class BCryptHasher < BCryptSHA256Hasher
         def initialize
           @algorithm = :bcrypt
@@ -96,6 +121,9 @@ module Sequel
         end
       end
 
+      # SHA1Hasher implements a SHA1 password hasher.
+      #
+      # @deprecated This hasher is present only for backward compatibility.
       class SHA1Hasher < Hasher
         def initialize
           @algorithm = :sha1

data/lib/sequel_password.rb

@@ -18,12 +18,23 @@ module Sequel
         end
       end
 
+      # @!attribute [r] column
+      #   @return [Symbol] name of the column where password is stored
+      # @!attribute [r] hashers
+      #   @return [Hash] hash of the algorithms and their corresponding Hasher
       module ClassMethods
         attr_reader :column, :hashers
 
         Plugins.inherited_instance_variables(self,
           "@column": :digest, "@hashers": {})
 
+        # Returns the given password hash. It will return an unusable
+        # hash if given password is nil.
+        #
+        # @param [String, nil] password to be hashed
+        # @param [String, nil] salt to be used during hashing
+        # @param [Symbol] algorithm to be used for hashing
+        # @return [String] the given password hashed
         def make_password(password, salt: nil, algorithm: :default)
           return "!#{SecureRandom.hex(20)}" if password.nil?
 
@@ -31,6 +42,10 @@ module Sequel
           hasher(algorithm).encode(password, salt)
         end
 
+        # Returns if encoded hash is a usable password.
+        #
+        # @param [String] encoded hash
+        # @return [Boolean] if password is usable
         def usable_password?(encoded)
           return false if encoded.nil? || encoded.start_with?("!")
 
@@ -38,6 +53,14 @@ module Sequel
           !hasher(algorithm).nil?
         end
 
+        # Check if password match, and upgrade to newest hashing algorithm
+        # if needed.
+        #
+        # @param [String] password in plain text
+        # @param [String] encoded password for comparision
+        # @param [Proc] setter accepting an encoded password
+        # @param [Symbol] algorithm to be used for hashing
+        # @return [Boolean] if password match encoded password
         def check_password(password, encoded, setter: nil, algorithm: :default)
           return false if password.nil? || !usable_password?(encoded)
 
@@ -61,6 +84,10 @@ module Sequel
       end
 
       module InstanceMethods
+        # Check if given password match the existing one.
+        #
+        # @param [String] password in plain text
+        # @return [Boolean] if given password match
         def authenticate(password)
           encoded = send(model.column)
           model.check_password(password, encoded, setter: method(:"#{model.column}="))
@@ -73,6 +100,7 @@ module Sequel
           super(attr, value || plain)
         end
 
+        # Sets the password as unusable.
         def set_unusable_password
           send("#{model.column}=", nil)
         end

data/sequel_password.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "sequel_password"
   gem.require_paths = ["lib"]
-  gem.version       = '0.2.0'
+  gem.version       = '0.2.1'
 
   gem.add_runtime_dependency 'sequel', '~> 4.21', '>= 4.21.0'
   gem.add_runtime_dependency 'bcrypt', '~> 3.1', '>= 3.1.10'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel_password
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Timothée Peignier
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-28 00:00:00.000000000 Z
+date: 2015-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -163,3 +163,4 @@ summary: Add passwords hashing to sequel models.
 test_files:
 - spec/sequel_password_spec.rb
 - spec/spec_helper.rb
+has_rdoc: