devise-argon2 1.1.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6710d39a7495e895f798cb907b4d4e4d67fa0f39fd3141d2a4d76d6da0c0b7a4
-  data.tar.gz: 48086d611acd10f4d91b2ccfa229bac0abe6f587abdae1a3b3df154c6d2d6408
+  metadata.gz: d036bff0c949c49457df0df4a4ac902d4ed0e65e84fd26f2940bfcc973b6bcc3
+  data.tar.gz: 82024dfd476f476514c5548b4aac5a93c49ffffad6fe33252c153381d0b803c1
 SHA512:
-  metadata.gz: 9e1be2f0b26ca41bb61ea3f42d1bfae79e59b1a670fe23574d1453138173caa8e4267266a169d9bfcc15bead58be9fb8009d70d183bf18a22967682ba58c095a
-  data.tar.gz: 22671a23d33b2de4c6c5ee5e50d1e5eb6a46009c338612256138b8ad72ff05cef442854c9f6ceab4f7a42934fbbafad0d213ce898c9c6ce6916c58625bed0335
+  metadata.gz: fb3857086fc9f31fd22bec613c3fe9e93534234036db242c49b1e5aae6ac9340611916e62ec92f84e67b8fafe97610b6d947c98df7846e62d91d9e550586689b
+  data.tar.gz: b7e523688dab140c94d9aed10232a57a1dcb144b437073d8ec41952fe0595f8713215d5ed9658701927f50182d2cf49adb0fd7bc5792d21255edaf70ffa603f5

data/.github/workflows/test.yml

@@ -0,0 +1,66 @@
+name: Test suite
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', '3.2', 'ruby-head']
+        rails-version: ['~> 7.0', '~> 6.1']
+        argon2-version: ['2.2', '2.3']
+        orm:
+          - adapter: active_record
+          - adapter: mongoid
+            mongoid-version: 8.1.2
+          - adapter: mongoid
+            mongoid-version: 8.0.6
+          - adapter: mongoid
+            mongoid-version: 7.5.4
+        include:
+          - rails-version: '~> 6.1'
+            ruby-version: '3.1'
+            argon2-version: '2.3'
+            devise-version: '4.8'
+            orm:
+              adapter: active_record
+          - rails-version: '~> 7.1'
+            ruby-version: '3.1'
+            argon2-version: '2.3'
+            devise-version: '4.9'
+            orm:
+              adapter: active_record
+          - rails-version: '~> 7.1'
+            ruby-version: '3.2'
+            argon2-version: '2.3'
+            devise-version: '4.9'
+            orm:
+              adapter: active_record
+          - rails-version: '~> 7.1'
+            ruby-version: '3.1'
+            argon2-version: '2.1'
+            devise-version: '4.9'
+            orm:
+              adapter: active_record
+    env:
+      RAILS_VERSION: ${{ matrix.rails-version  || '~> 7.0'}}
+      MONGOID_VERSION: ${{ matrix.orm.mongoid-version || '8.1.2'}}
+      ORM: ${{ matrix.orm.adapter }}
+      ARGON2_VERSION: ${{ matrix.argon2-version }}
+      DEVISE_VERSION: ${{ matrix.devise-version || '~> 4.9' }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby ${{ matrix.ruby-version }}
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - uses: supercharge/mongodb-github-action@1.10.0
+      if: ${{ matrix.orm.adapter == 'mongoid' }}
+    - name: Setup rails test environment
+      run: |
+        cd spec/rails_app
+        RAILS_ENV=test bin/rails db:setup
+    - name: Run tests
+      run: bundle exec rspec

data/.gitignore

@@ -12,6 +12,9 @@ lib/bundler/man
 pkg
 rdoc
 spec/reports
+spec/rails_app/log/*
+spec/rails_app/tmp/*
+spec/rails_app/db/test.sqlite3*
 test/tmp
 test/version_tmp
 tmp

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog 
+
+## Unreleased
+
+## [2.0.1] - 2023-10-18
+
+### Added
+- Add Argon2 and devise to the test suite
+- Add @moritzhoeppner as an author
+
+### Fixed
+- Fix work factors implementation
+
+## [2.0.0] - 2023-10-16
+
+### Added
+- Expose Argon2 options for configuring hashing work factors
+- Add support for migration v1 hashes
+- Add support for migrating bcrypt hashes
+- Add tests for Mongoid
+- Add Changelog :)
+ 
+### Changed
+- Change salting / peppering mechanism
+- Change CI from Travis to GitHub Actions
+ 
+### Removed 
+- Remove `devise-encryptable` dependency
+- Remove superflous dependency on devise `password_salt` column
+
+Thank you to @moritzhoeppner for the significant contributions to this release!
+

data/Gemfile

@@ -1,10 +1,15 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in gvoe_auth-client.gemspec
 gemspec
 
 gem 'rspec'
 gem 'simplecov'
-gem 'activesupport'
-gem 'activemodel'
-gem 'pry'
+gem 'activerecord'
+gem 'sqlite3'
+gem 'rails', ENV['RAILS_VERSION'] || '~> 7.0'
+gem 'argon2', ENV['ARGON2_VERSION'] || '~> 2.3'
+gem 'devise', ENV['DEVISE_VERSION'] || '~> 4.9'
+
+if ENV['ORM'] == 'mongoid'
+  gem 'mongoid', ENV['MONGOID_VERSION'] || '~> 7.5'
+end

data/README.md

@@ -1,41 +1,125 @@
-devise-argon2 [![Build Status](https://secure.travis-ci.org/erdostom/devise-argon2.png)][Continuous Integration] [![Gem Version](https://badge.fury.io/rb/devise-argon2.svg)](https://badge.fury.io/rb/devise-argon2)
-=============
+# devise-argon2 
+[![Gem Version](https://badge.fury.io/rb/devise-argon2.svg)](https://badge.fury.io/rb/devise-argon2)
+![](https://github.com/erdostom/devise-argon2/actions/workflows/test.yml/badge.svg)
 
-**A [devise-encryptable] password encryptor that uses [argon2]**
+A ruby gem that gives Devise models which use `database_authenticatable` the ability to hash
+passwords with Argon2id.
 
-  * [Continuous Integration]
+## Installation
 
-[Continuous Integration]: http://travis-ci.org/erdostom/devise-argon2 "Continuous integration @ travis-ci.org"
-
-[argon2]: https://github.com/technion/ruby-argon2
-[devise]: https://github.com/plataformatec/devise
-[devise-encryptable]: https://github.com/plataformatec/devise-encryptable
-
-## Why use Argon2?
-
-Argon2 won Password Hashing Competition and offers additional security compared to the default `bcrypt` by adding a memory cost. More info:
-
-- https://github.com/P-H-C/phc-winner-argon2
-- https://hynek.me/articles/storing-passwords/
+```
+bundle add devise-argon2
+```
 
 ## Usage
 
-Assuming you have [devise] (>= 2.1) and the [devise-encryptable] plugin
-set up in your application, add `devise-argon2` to your `Gemfile` and `bundle`:
-
-    gem 'devise-argon2'
+Add `devise :argon2` to your Devise model. For example:
+
+```
+class User < ApplicationRecord
+  devise :database_authenticatable, :argon2
+end
+```
+
+Now the password of a newly created user will be hashed with Argon2id. Existing BCrypt hashes will
+continue to work; if the password of a user is hashed with BCrypt, the Argon2id hash will replace
+the existing hash as soon as a user signs in (more specifically: as soon as `valid_password?`
+is called with a valid password).
+
+## Configuration
+
+### Argon2 options
+
+For Argon2 hashing the gem [ruby-argon2](https://github.com/technion/ruby-argon2) is used, which
+provides FFI bindings to the
+[Argon 2 reference implementation](https://github.com/P-H-C/phc-winner-argon2).
+`ruby-argon2` can be configured by passing parameters like `profile`, `t_cost`, `m_cost`, `p_cost`,
+or `secret` to `Argon2::Password.new`. These parameters can be set like this:
+
+```
+class User < ApplicationRecord
+  devise :database_authenticatable,
+    :argon2,
+    argon2_options: { t_cost: 3, p_cost: 2 }
+end
+```
+
+If the the configured work factors differ from the work factors of the hash in the database, the
+password will be re-hashed as soon as `valid_password?` is called with a valid password.
+
+### Pepper/secret key
+
+The [Argon 2 reference implementation](https://github.com/P-H-C/phc-winner-argon2#library) has a
+built-in pepper which is called `secret`. This Argon2 secret key can be set like this:
+
+```
+class User < ApplicationRecord
+  devise :database_authenticatable,
+    :argon2,
+    argon2_options: { secret: ENV['ARGON2_SECRET_KEY'] }
+end
+```
+
+Traditionally, peppers in Devise are configured by setting `config.pepper` in `devise.rb`. This
+option in honored but `argon2_options[:secret]` takes precedence over `config.pepper`. Specifically:
+- `config.pepper` is used as secret key for new hashes if and only if `argon2_options[:secret]` is
+not set.
+- The verification of existing BCrypt hashes is not touched, so it continues to use `config.pepper`
+as pepper.
+
+## Updating from version 1
+
+With version 2 come two major changes: First, `devise-encryptable` is no longer needed. Second, the mechanism for salting
+and peppering has changed: Salts are now managed by Argon2 and the pepper is passed as secret key
+parameter. If you have existing hashes in your database that have been generated by
+devise-argon2 v1, you'll need to set `:migrate_from_devise_argon2_v1` in `argon2_options`.
+
+With this option your existing hashes will continue to work as the old mechanism for salting and
+peppering is used if and only if `password_salt` is truthy. The first time you pass a valid
+password to `valid_password?`, the hash will be updated and `password_salt` will be set to `nil`.
+The next time you call `valid_password?` the new salting and peppering mechanism will be used
+because `password_salt` is not truthy anymore.
+
+As soon as all `password_salt` fields are set to `nil`, you can delete the column from the database
+and remove `:migrate_from_devise_argon2_v1` from `argon2_options`.
+
+Please note that this works only if your database table has a field `password_salt`.
+
+### Upgrade Steps
+
+1. Update your `Gemfile` to use `devise-argon2` version 2: `gem 'devise-argon2', '~> 2.0'`
+1. Remove `devise-encryptable` from your `Gemfile`
+1. Run `bundle install`
+1. Remove the line `config.encryptor = :argon2` from `config/initializers/devise.rb`
+1. Change your Devise model by removing `:encryptable` and adding `:argon2, argon2_options: { migrate_from_devise_argon2_v1: true }`
+    1. It should now look something like this
+   
+```
+class User < ApplicationRecord
+  devise :database_authenticatable,
+    :argon2,
+    argon2_options: { migrate_from_devise_argon2_v1: true }
+end
+```
+
+That's it, you're done! Your users will now be able to log in with their existing passwords and their passwords will be migrated to the V2 format the next time they log in.
+
+---
+
+Once all of your users' passwords are migrated to the V2 format:
+   1. Remove the `argon2_options { migrated_from_devise_argon2_v1: true }` line from your Devise model
+   1. Delete the `password_salt` column from your database using a migration like this:
+```
+class RemovePasswordSaltFromUsers < ActiveRecord::Migration[7.1]
+  def change
+    remove_column :users, :password_salt, :string
+  end
+end
+```
+
+Note: If you do this before all of your users' passwords are migrated to the V2 format, they will be unable to log 
+in with their current passwords.
 
-Then open up your [devise] configuration,`config/initializers/devise.rb` and configure your encryptor to be `argon2`:
-
-    # config/initializers/devise.rb
-    Devise.setup do |config|
-      # ..
-      config.encryptor = :argon2
-      # ...
-    end
-
-It is also recommended to uncomment (or add) `config.pepper` with a random
-string that will be used in addition to the per-user `password_salt` when hashing.
 
 ## Contributing
 
@@ -45,6 +129,10 @@ string that will be used in addition to the per-user `password_salt` when hashin
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-## Copyright
+## Contributors
+
+Please see here for full list of contributors: https://github.com/erdostom/devise-argon2/graphs/contributors
+
+## License
 
 Released under MIT License.

data/devise-argon2.gemspec

@@ -1,23 +1,26 @@
 # -*- encoding: utf-8 -*-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "devise/encryptable/encryptors/argon2/version"
+require "devise-argon2/version"
 
 Gem::Specification.new do |gem|
-  gem.name          = "devise-argon2"
-  gem.version       = Devise::Encryptable::Encryptors::ARGON2_VERSION
-  gem.authors       = ["Tamas Erdos"]
-  gem.email         = ["tamas at tamaserdos com"]
-  gem.description   = %q{A devise-encryptable password encryptor that uses Argon2}
-  gem.summary       = %q{A devise-encryptable password encryptor that uses Argon2}
-  gem.homepage      = "https://github.com/erdostom/devise-argon2"
+  gem.name = "devise-argon2"
+  gem.version = Devise::Argon2::ARGON2_VERSION
+  gem.authors = ["Tamas Erdos", "Moritz Höppner"]
+  gem.email = ["tamas at tamaserdos com"]
+  gem.description = %q{Enables Devise to hash passwords with Argon2id}
+  gem.summary = %q{Enables Devise to hash passwords with Argon2id}
+  gem.license = 'MIT'
+  gem.homepage = "https://github.com/erdostom/devise-argon2"
 
-  gem.files         = `git ls-files`.split($/)
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.files = `git ls-files`.split($/)
+  gem.executables = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_dependency 'devise', '>= 2.1.0'
-  gem.add_dependency 'devise-encryptable', '>= 0.2.0'
-  gem.add_dependency 'argon2', '~> 2.0'
+  gem.add_dependency 'devise', '~> 4.0'
+  gem.add_dependency 'argon2', '~> 2.1'
+
+
+  gem.post_install_message = "Version 2 of devise-argon2 introduces breaking changes, please see README.md for details."
 end

data/lib/devise-argon2/model.rb

@@ -0,0 +1,101 @@
+require 'argon2'
+
+module Devise
+  module Models
+    module Argon2
+      def valid_password?(password)
+        is_valid = hash_needs_update = false
+        
+        if ::Argon2::Password.valid_hash?(encrypted_password)
+          if migrate_hash_from_devise_argon2_v1?
+            is_valid = ::Argon2::Password.verify_password(
+              "#{password}#{password_salt}#{self.class.pepper}",
+              encrypted_password
+            )
+            hash_needs_update = true
+          else
+            argon2_secret = (self.class.argon2_options[:secret] || self.class.pepper)
+            is_valid = ::Argon2::Password.verify_password(
+              password,
+              encrypted_password,
+              argon2_secret
+            )
+            hash_needs_update = outdated_work_factors?
+          end
+        else
+          # Devise models are included in a fixed order, see
+          # https://github.com/heartcombo/devise/blob/f6e73e5b5c8f519f4be29ac9069c6ed8a2343ce4/lib/devise/models.rb#L79.
+          # Since we don't specify where this model should be inserted when we call add_module,
+          # it will be inserted at the end, i.e. after DatabaseAuthenticatable (see
+          # https://github.com/heartcombo/devise/blob/f6e73e5b5c8f519f4be29ac9069c6ed8a2343ce4/lib/devise.rb#L393). 
+          # So we can call DatabaseAuthenticable's valid_password? with super.
+          is_valid = super
+          hash_needs_update = true
+        end
+
+        update_hash(password) if is_valid && hash_needs_update
+
+        is_valid
+      end
+
+      protected
+
+      def password_digest(password)
+        hasher_options = self.class.argon2_options.except(:migrate_from_devise_argon2_v1)
+        hasher_options[:secret] ||= self.class.pepper
+        hasher = ::Argon2::Password.new(hasher_options)
+        hasher.create(password)
+      end
+
+      private
+
+      def update_hash(password)
+        attributes = { encrypted_password: password_digest(password) }
+        attributes[:password_salt] = nil if migrate_hash_from_devise_argon2_v1?
+
+        self.assign_attributes(attributes)
+        self.save if self.persisted?
+      end
+
+      def outdated_work_factors?
+        hash_format = ::Argon2::HashFormat.new(encrypted_password)
+        current_work_factors = {
+          t_cost: hash_format.t_cost,
+          m_cost: hash_format.m_cost,
+          p_cost: hash_format.p_cost
+        }
+        current_work_factors != configured_work_factors
+      end
+
+      def configured_work_factors
+        # Since version 2.3.0 the argon2 gem exposes the default work factors via constants, see
+        # https://github.com/technion/ruby-argon2/commit/d62ecf8b4ec6b8c1651fade5a5ebdc856e8aef42
+        work_factors = {
+          t_cost: defined?(::Argon2::Password::DEFAULT_T_COST) ? ::Argon2::Password::DEFAULT_T_COST : 2,
+          m_cost: defined?(::Argon2::Password::DEFAULT_M_COST) ? ::Argon2::Password::DEFAULT_M_COST : 16,
+          p_cost: defined?(::Argon2::Password::DEFAULT_P_COST) ? ::Argon2::Password::DEFAULT_P_COST : 1
+        }.merge(self.class.argon2_options.slice(:t_cost, :m_cost, :p_cost))
+
+        # Since version 2.3.0 the argon2 gem supports defining work factors with named profiles, see
+        # https://github.com/technion/ruby-argon2/commit/6312a8fb3a6c6c5e771a736572e63d47485e8613
+        if self.class.argon2_options[:profile] && defined?(::Argon2::Profiles)
+          work_factors.merge!(::Argon2::Profiles[self.class.argon2_options[:profile]])
+        end
+
+        work_factors[:m_cost] = (1 << work_factors[:m_cost])
+
+        work_factors
+      end
+
+      def migrate_hash_from_devise_argon2_v1?
+        self.class.argon2_options[:migrate_from_devise_argon2_v1] &&
+          defined?(password_salt) &&
+          password_salt
+      end
+
+      module ClassMethods
+        Devise::Models.config(self, :argon2_options)
+      end
+    end
+  end
+end

data/lib/devise-argon2/version.rb

@@ -0,0 +1,5 @@
+module Devise
+  module Argon2
+    ARGON2_VERSION = '2.0.1'
+  end
+end

data/lib/devise-argon2.rb

@@ -1,4 +1,9 @@
 require 'devise'
-require 'devise-encryptable'
-require "devise/encryptable/encryptors/argon2/version"
-require "devise/encryptable/encryptors/argon2"
+require 'devise-argon2/version'
+
+module Devise
+  add_module(:argon2, :model => 'devise-argon2/model')
+  
+  mattr_accessor :argon2_options
+  @@argon2_options = {}
+end