authentication-logic 0.1.0

data/lib/auth/logic/crypto_providers/bcrypt.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "bcrypt"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      # The family of adaptive hash functions (BCrypt, SCrypt, PBKDF2)
+      # is the best choice for password storage today. They have the
+      # three properties of password hashing that are desirable. They
+      # are one-way, unique, and slow. While a salted SHA or MD5 hash is
+      # one-way and unique, preventing rainbow table attacks, they are
+      # still lightning fast and attacks on the stored passwords are
+      # much more effective. This benchmark demonstrates the effective
+      # slowdown that BCrypt provides:
+      #
+      #   require "bcrypt"
+      #   require "digest"
+      #   require "benchmark"
+      #
+      #   Benchmark.bm(18) do |x|
+      #     x.report("BCrypt (cost = 10:") {
+      #       100.times { BCrypt::Password.create("mypass", :cost => 10) }
+      #     }
+      #     x.report("BCrypt (cost = 4:") {
+      #       100.times { BCrypt::Password.create("mypass", :cost => 4) }
+      #     }
+      #     x.report("Sha512:") {
+      #       100.times { Digest::SHA512.hexdigest("mypass") }
+      #     }
+      #     x.report("Sha1:") {
+      #       100.times { Digest::SHA1.hexdigest("mypass") }
+      #     }
+      #   end
+      #
+      #                            user     system      total        real
+      #   BCrypt (cost = 10):  37.360000   0.020000  37.380000 ( 37.558943)
+      #   BCrypt (cost = 4):    0.680000   0.000000   0.680000 (  0.677460)
+      #   Sha512:               0.000000   0.000000   0.000000 (  0.000672)
+      #   Sha1:                 0.000000   0.000000   0.000000 (  0.000454)
+      #
+      # You can play around with the cost to get that perfect balance
+      # between performance and security. A default cost of 10 is the
+      # best place to start.
+      #
+      # Decided BCrypt is for you? Just install the bcrypt gem:
+      #
+      #   gem install bcrypt
+      #
+      # Tell acts_as_authentic to use it:
+      #
+      #   acts_as_authentic do |c|
+      #     c.crypto_provider = Authentication::Logic::CryptoProviders::BCrypt
+      #   end
+      #
+      # You are good to go!
+      class BCrypt
+        class << self
+          # This is the :cost option for the BCrpyt library. The higher the cost
+          # the more secure it is and the longer is take the generate a hash. By
+          # default this is 10. Set this to any value >= the engine's minimum
+          # (currently 4), play around with it to get that perfect balance between
+          # security and performance.
+          def cost
+            @cost ||= 10
+          end
+
+          def cost=(val)
+            if val < ::BCrypt::Engine::MIN_COST
+              raise ArgumentError, "Authentication::Logic's bcrypt cost cannot be set below the engine's " \
+                  "min cost (#{::BCrypt::Engine::MIN_COST})"
+            end
+            @cost = val
+          end
+
+          # Creates a BCrypt hash for the password passed.
+          def encrypt(*tokens)
+            ::BCrypt::Password.create(join_tokens(tokens), cost: cost)
+          end
+
+          # Does the hash match the tokens? Uses the same tokens that were used to
+          # encrypt.
+          def matches?(hash, *tokens)
+            hash = new_from_hash(hash)
+            return false if hash.blank?
+
+            hash == join_tokens(tokens)
+          end
+
+          # This method is used as a flag to tell Authentication::Logic to "resave" the
+          # password upon a successful login, using the new cost
+          def cost_matches?(hash)
+            hash = new_from_hash(hash)
+            if hash.blank?
+              false
+            else
+              hash.cost == cost
+            end
+          end
+
+          private
+
+          def join_tokens(tokens)
+            tokens.flatten.join
+          end
+
+          def new_from_hash(hash)
+            ::BCrypt::Password.new(hash)
+          rescue ::BCrypt::Errors::InvalidHash
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/md5/v2.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      class MD5
+        # A poor choice. There are known attacks against this algorithm.
+        class V2
+          class << self
+            attr_accessor :join_token
+
+            # The number of times to loop through the encryption.
+            def stretches
+              @stretches ||= 1
+            end
+            attr_writer :stretches
+
+            # Turns your raw password into a MD5 hash.
+            def encrypt(*tokens)
+              digest = tokens.flatten.join(join_token)
+              stretches.times { digest = Digest::MD5.digest(digest) }
+              digest.unpack1("H*")
+            end
+
+            # Does the crypted password match the tokens? Uses the same tokens that
+            # were used to encrypt.
+            def matches?(crypted, *tokens)
+              encrypt(*tokens) == crypted
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/md5.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      # A poor choice. There are known attacks against this algorithm.
+      class MD5
+        # V2 hashes the digest bytes in repeated stretches instead of hex characters.
+        autoload :V2, File.join(__dir__, "md5", "v2")
+
+        class << self
+          attr_accessor :join_token
+
+          # The number of times to loop through the encryption.
+          def stretches
+            @stretches ||= 1
+          end
+          attr_writer :stretches
+
+          # Turns your raw password into a MD5 hash.
+          def encrypt(*tokens)
+            digest = tokens.flatten.join(join_token)
+            stretches.times { digest = Digest::MD5.hexdigest(digest) }
+            digest
+          end
+
+          # Does the crypted password match the tokens? Uses the same tokens that
+          # were used to encrypt.
+          def matches?(crypted, *tokens)
+            encrypt(*tokens) == crypted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/scrypt.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "scrypt"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      # SCrypt is the default provider for Authentication::Logic. It is the only
+      # choice in the adaptive hash family that accounts for hardware
+      # based attacks by compensating with memory bound as well as cpu
+      # bound computational constraints. It offers the same guarantees
+      # as BCrypt in the way of one-way, unique and slow.
+      #
+      # Decided SCrypt is for you? Just install the scrypt gem:
+      #
+      #   gem install scrypt
+      #
+      # Tell acts_as_authentic to use it:
+      #
+      #   acts_as_authentic do |c|
+      #     c.crypto_provider = Authentication::Logic::CryptoProviders::SCrypt
+      #   end
+      class SCrypt
+        class << self
+          DEFAULTS = {
+            key_len: 32,
+            salt_size: 8,
+            max_time: 0.2,
+            max_mem: 1024 * 1024,
+            max_memfrac: 0.5
+          }.freeze
+
+          attr_writer :key_len, :salt_size, :max_time, :max_mem, :max_memfrac
+
+          # Key length - length in bytes of generated key, from 16 to 512.
+          def key_len
+            @key_len ||= DEFAULTS[:key_len]
+          end
+
+          # Salt size - size in bytes of random salt, from 8 to 32
+          def salt_size
+            @salt_size ||= DEFAULTS[:salt_size]
+          end
+
+          # Max time - maximum time spent in computation
+          def max_time
+            @max_time ||= DEFAULTS[:max_time]
+          end
+
+          # Max memory - maximum memory usage. The minimum is always 1MB
+          def max_mem
+            @max_mem ||= DEFAULTS[:max_mem]
+          end
+
+          # Max memory fraction - maximum memory out of all available. Always
+          # greater than zero and <= 0.5.
+          def max_memfrac
+            @max_memfrac ||= DEFAULTS[:max_memfrac]
+          end
+
+          # Creates an SCrypt hash for the password passed.
+          def encrypt(*tokens)
+            ::SCrypt::Password.create(
+              join_tokens(tokens),
+              key_len: key_len,
+              salt_size: salt_size,
+              max_mem: max_mem,
+              max_memfrac: max_memfrac,
+              max_time: max_time
+            )
+          end
+
+          # Does the hash match the tokens? Uses the same tokens that were used to encrypt.
+          def matches?(hash, *tokens)
+            hash = new_from_hash(hash)
+            return false if hash.blank?
+
+            hash == join_tokens(tokens)
+          end
+
+          private
+
+          def join_tokens(tokens)
+            tokens.flatten.join
+          end
+
+          def new_from_hash(hash)
+            ::SCrypt::Password.new(hash)
+          rescue ::SCrypt::Errors::InvalidHash
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha1/v2.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      class Sha1
+        # A poor choice. There are known attacks against this algorithm.
+        class V2
+          class << self
+            def join_token
+              @join_token ||= "--"
+            end
+            attr_writer :join_token, :stretches
+
+            # The number of times to loop through the encryption.
+            def stretches
+              @stretches ||= 10
+            end
+
+            # Turns your raw password into a Sha1 hash.
+            def encrypt(*tokens)
+              tokens = tokens.flatten
+              digest = tokens.shift
+              stretches.times do
+                digest = Digest::SHA1.digest([digest, *tokens].join(join_token))
+              end
+              digest.unpack1("H*")
+            end
+
+            # Does the crypted password match the tokens? Uses the same tokens that
+            # were used to encrypt.
+            def matches?(crypted, *tokens)
+              encrypt(*tokens) == crypted
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha1.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      # A poor choice. There are known attacks against this algorithm.
+      class Sha1
+        # V2 hashes the digest bytes in repeated stretches instead of hex characters.
+        autoload :V2, File.join(__dir__, "sha1", "v2")
+
+        class << self
+          def join_token
+            @join_token ||= "--"
+          end
+          attr_writer :join_token, :stretches
+
+          # The number of times to loop through the encryption.
+          def stretches
+            @stretches ||= 10
+          end
+
+          # Turns your raw password into a Sha1 hash.
+          def encrypt(*tokens)
+            tokens = tokens.flatten
+            digest = tokens.shift
+            stretches.times do
+              digest = Digest::SHA1.hexdigest([digest, *tokens].join(join_token))
+            end
+            digest
+          end
+
+          # Does the crypted password match the tokens? Uses the same tokens that
+          # were used to encrypt.
+          def matches?(crypted, *tokens)
+            encrypt(*tokens) == crypted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha256/v2.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Authentication
+  module Logic
+    # The acts_as_authentic method has a crypto_provider option. This allows you
+    # to use any type of encryption you like. Just create a class with a class
+    # level encrypt and matches? method. See example below.
+    #
+    # === Example
+    #
+    #   class MyAwesomeEncryptionMethod
+    #     def self.encrypt(*tokens)
+    #       # the tokens passed will be an array of objects, what type of object
+    #       # is irrelevant, just do what you need to do with them and return a
+    #       # single encrypted string. for example, you will most likely join all
+    #       # of the objects into a single string and then encrypt that string
+    #     end
+    #
+    #     def self.matches?(crypted, *tokens)
+    #       # return true if the crypted string matches the tokens. Depending on
+    #       # your algorithm you might decrypt the string then compare it to the
+    #       # token, or you might encrypt the tokens and make sure it matches the
+    #       # crypted string, its up to you.
+    #     end
+    #   end
+    module CryptoProviders
+      class Sha256
+        # = Sha256
+        #
+        # Uses the Sha256 hash algorithm to encrypt passwords.
+        class V2
+          class << self
+            attr_accessor :join_token
+
+            # The number of times to loop through the encryption.
+            def stretches
+              @stretches ||= 20
+            end
+            attr_writer :stretches
+
+            # Turns your raw password into a Sha256 hash.
+            def encrypt(*tokens)
+              digest = tokens.flatten.join(join_token)
+              stretches.times { digest = Digest::SHA256.digest(digest) }
+              digest.unpack1("H*")
+            end
+
+            # Does the crypted password match the tokens? Uses the same tokens that
+            # were used to encrypt.
+            def matches?(crypted, *tokens)
+              encrypt(*tokens) == crypted
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha256.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Authentication
+  module Logic
+    # The acts_as_authentic method has a crypto_provider option. This allows you
+    # to use any type of encryption you like. Just create a class with a class
+    # level encrypt and matches? method. See example below.
+    #
+    # === Example
+    #
+    #   class MyAwesomeEncryptionMethod
+    #     def self.encrypt(*tokens)
+    #       # the tokens passed will be an array of objects, what type of object
+    #       # is irrelevant, just do what you need to do with them and return a
+    #       # single encrypted string. for example, you will most likely join all
+    #       # of the objects into a single string and then encrypt that string
+    #     end
+    #
+    #     def self.matches?(crypted, *tokens)
+    #       # return true if the crypted string matches the tokens. Depending on
+    #       # your algorithm you might decrypt the string then compare it to the
+    #       # token, or you might encrypt the tokens and make sure it matches the
+    #       # crypted string, its up to you.
+    #     end
+    #   end
+    module CryptoProviders
+      # = Sha256
+      #
+      # Uses the Sha256 hash algorithm to encrypt passwords.
+      class Sha256
+        # V2 hashes the digest bytes in repeated stretches instead of hex characters.
+        autoload :V2, File.join(__dir__, "sha256", "v2")
+
+        class << self
+          attr_accessor :join_token
+
+          # The number of times to loop through the encryption.
+          def stretches
+            @stretches ||= 20
+          end
+          attr_writer :stretches
+
+          # Turns your raw password into a Sha256 hash.
+          def encrypt(*tokens)
+            digest = tokens.flatten.join(join_token)
+            stretches.times { digest = Digest::SHA256.hexdigest(digest) }
+            digest
+          end
+
+          # Does the crypted password match the tokens? Uses the same tokens that
+          # were used to encrypt.
+          def matches?(crypted, *tokens)
+            encrypt(*tokens) == crypted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha512/v2.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      class Sha512
+        # SHA-512 does not have any practical known attacks against it. However,
+        # there are better choices. We recommend transitioning to a more secure,
+        # adaptive hashing algorithm, like scrypt.
+        class V2
+          class << self
+            attr_accessor :join_token
+
+            # The number of times to loop through the encryption.
+            def stretches
+              @stretches ||= 20
+            end
+            attr_writer :stretches
+
+            # Turns your raw password into a Sha512 hash.
+            def encrypt(*tokens)
+              digest = tokens.flatten.join(join_token)
+              stretches.times do
+                digest = Digest::SHA512.digest(digest)
+              end
+              digest.unpack1("H*")
+            end
+
+            # Does the crypted password match the tokens? Uses the same tokens that
+            # were used to encrypt.
+            def matches?(crypted, *tokens)
+              encrypt(*tokens) == crypted
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers/sha512.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+
+module Authentication
+  module Logic
+    module CryptoProviders
+      # SHA-512 does not have any practical known attacks against it. However,
+      # there are better choices. We recommend transitioning to a more secure,
+      # adaptive hashing algorithm, like scrypt.
+      class Sha512
+        # V2 hashes the digest bytes in repeated stretches instead of hex characters.
+        autoload :V2, File.join(__dir__, "sha512", "v2")
+
+        class << self
+          attr_accessor :join_token
+
+          # The number of times to loop through the encryption.
+          def stretches
+            @stretches ||= 20
+          end
+          attr_writer :stretches
+
+          # Turns your raw password into a Sha512 hash.
+          def encrypt(*tokens)
+            digest = tokens.flatten.join(join_token)
+            stretches.times { digest = Digest::SHA512.hexdigest(digest) }
+            digest
+          end
+
+          # Does the crypted password match the tokens? Uses the same tokens that
+          # were used to encrypt.
+          def matches?(crypted, *tokens)
+            encrypt(*tokens) == crypted
+          end
+        end
+      end
+    end
+  end
+end

data/lib/auth/logic/crypto_providers.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Authentication
+  module Logic
+    # The acts_as_authentic method has a crypto_provider option. This allows you
+    # to use any type of encryption you like. Just create a class with a class
+    # level encrypt and matches? method. See example below.
+    #
+    # === Example
+    #
+    #   class MyAwesomeEncryptionMethod
+    #     def self.encrypt(*tokens)
+    #       # The tokens passed will be an array of objects, what type of object
+    #       # is irrelevant, just do what you need to do with them and return a
+    #       # single encrypted string. For example, you will most likely join all
+    #       # of the objects into a single string and then encrypt that string.
+    #     end
+    #
+    #     def self.matches?(crypted, *tokens)
+    #       # Return true if the crypted string matches the tokens. Depending on
+    #       # your algorithm you might decrypt the string then compare it to the
+    #       # token, or you might encrypt the tokens and make sure it matches the
+    #       # crypted string, its up to you.
+    #     end
+    #   end
+    module CryptoProviders
+      autoload :MD5,    "auth/logic/crypto_providers/md5"
+      autoload :Sha1,   "auth/logic/crypto_providers/sha1"
+      autoload :Sha256, "auth/logic/crypto_providers/sha256"
+      autoload :Sha512, "auth/logic/crypto_providers/sha512"
+      autoload :BCrypt, "auth/logic/crypto_providers/bcrypt"
+      autoload :SCrypt, "auth/logic/crypto_providers/scrypt"
+
+      # Guide users to choose a better crypto provider.
+      class Guidance
+        BUILTIN_PROVIDER_PREFIX = "Authentication::Logic::CryptoProviders::"
+        NONADAPTIVE_ALGORITHM = <<~EOS
+          You have selected %s as your auth-logic crypto provider. This algorithm
+          does not have any practical known attacks against it. However, there are
+          better choices.
+
+          Authentication::Logic has no plans yet to deprecate this crypto provider. However,
+          we recommend transitioning to a more secure, adaptive hashing algorithm,
+          like scrypt. Adaptive algorithms are designed to slow down brute force
+          attacks, and over time the iteration count can be increased to make it
+          slower, so it remains resistant to brute-force search attacks even in
+          the face of increasing computation power.
+
+          Use the transition_from_crypto_providers option to make the transition
+          painless for your users.
+        EOS
+        VULNERABLE_ALGORITHM = <<~EOS
+          You have selected %s as your auth-logic crypto provider. It is a poor
+          choice because there are known attacks against this algorithm.
+
+          Authentication::Logic has no plans yet to deprecate this crypto provider. However,
+          we recommend transitioning to a secure hashing algorithm. We recommend
+          an adaptive algorithm, like scrypt.
+
+          Use the transition_from_crypto_providers option to make the transition
+          painless for your users.
+        EOS
+
+        def initialize(provider)
+          @provider = provider
+        end
+
+        def impart_wisdom
+          return unless @provider.is_a?(Class)
+
+          # We can only impart wisdom about our own built-in providers.
+          absolute_name = @provider.name
+          return unless absolute_name.start_with?(BUILTIN_PROVIDER_PREFIX)
+
+          # Inspect the string name of the provider, rather than using the
+          # constants in our `when` clauses. If we used the constants, we'd
+          # negate the benefits of the `autoload` above.
+          name = absolute_name.demodulize
+          case name
+          when "MD5", "Sha1"
+            warn(format(VULNERABLE_ALGORITHM, name))
+          when "Sha256", "Sha512"
+            warn(format(NONADAPTIVE_ALGORITHM, name))
+          end
+        end
+      end
+    end
+  end
+end