argon2-simple 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa42378563834f98797412c3e4f186260635e601
+  data.tar.gz: 30cb086dbc01db9855aeeb01b36c7022b7393330
+SHA512:
+  metadata.gz: 4bca1680496f4c9775fc2cbdea611df59fbb304ab7ad9ae7be523891c5fd07d4948b64c9ab0ba1f023fd3ea8c4adf6065de4ae45716948ef8c15a660c717b016
+  data.tar.gz: 25544e0be398dbcfa435d7104e5a5c114161103d96bdf074cac974909cb541063dc6c04ee37ad1b08fdc0a5e1944eba57fb6ddc5d452cfa443f769b8110250f1

data/README.md

@@ -0,0 +1,92 @@
+# Argon2::Simple
+
+Argon2::Simple provides a wrapper around Argon2. Argon2::Simple simplifies the
+process of creating passwords hashes and checking submitted passwords against
+those hashes.
+
+To hash a password, use the `hash` method:
+
+```
+pw_clear = 'my password'
+hashed = Argon2::Simple.hash(pw_clear)
+puts hashed  # => $argon2i$v=19$m=65536,t=2,p=1$K4BXPfBeuZSnqxia/abuRQ$0+jibsWcClNY+HHSXxQlsEi/RboEScY8XM5mh4ehFlA
+```
+To check a submitted password against the hash, use the `check` method:
+
+```
+# check against clear password
+puts Argon2::Simple.check(pw_clear, hashed) # => true
+
+# check against incorrect password
+puts Argon2::Simple.check('whatever', hashed) # => false
+```
+
+Because Argon2 is one of the most secure hashing algorithms in the world, it is
+also one of the slowest. To speed things up, Argon2::Simple caches successful
+password checks. This benefits applications which tend to get the same
+successful passwords repeatedely, such as a web site that stores an
+authentication token in a cookie.
+
+By default, Argon2::Simple caches the last 100 successful passwords. You can
+change that limit with the `reset` method. So, for example, to set it to 1,000:
+
+```
+Argon2::Simple.reset 1000
+```
+
+To turn off caching, reset with 0:
+
+```
+Argon2::Simple.reset 0
+```
+
+The following test shows the advantage of caching. The test is run first with the
+default caching of 100, then with no caching.
+
+```
+def tester
+   pw_clear = 'my password'
+   hashed = Argon2::Simple.hash(pw_clear)
+   
+   puts Benchmark.measure {
+      100.times do
+         Argon2::Simple.check(pw_clear, hashed)
+      end
+   }
+end
+
+tester()                # run with default cache
+Argon2::Simple.reset 0  # turn off caching
+tester()                # run without cache
+```
+
+That outputs benchmarks something like this:
+
+```
+ 0.210000   0.050000   0.260000 (  0.277293)
+22.040000   4.240000  26.280000 ( 26.440273)
+```
+
+So for just 100 checks, the time went from about 1/20 of a second to over 4
+seconds. Obviously, if your application tends to get a lot of incorrect
+passwords then the cache doesn't help. I'm thinking of adding the feature that
+it can also cache unsuccessful authentication attempts. Let me know if that
+would be helpful.
+
+## Install
+
+```
+gem install argon2-simple
+```
+
+## Author
+
+Mike O'Sullivan
+mike@idocs.com
+
+## History
+
+| version | date         | notes           |
+|---------|--------------|-----------------|
+| 0.0.2   | Nov 10, 2018 | Initial upload. |
+

data/lib/argon2/simple.rb

@@ -0,0 +1,85 @@
+require 'argon2'
+require 'lru_redux'
+
+#==============================================================================
+# Argon2::Simple
+#
+module Argon2::Simple
+	@@cache = nil
+	
+	##
+	# Resets the cache. By default sets the cache limit to 100:
+	# 
+	#   Argon2::Simple.reset
+	# 
+	# The optional parameter sets the cache to the given number. So to set it
+	# to 1000:
+	# 
+	#   Argon2::Simple.reset 1000
+	# 
+	# To have no cache, set the max to 0:
+	# 
+	#   Argon2::Simple.reset 0
+	def self.reset(max=100)
+		if max > 0
+			@@cache = LruRedux::Cache.new(max)
+		else
+			@@cache = nil
+		end
+	end
+	
+	# reset
+	self.reset
+	
+	##
+	# Accepts a clear password and returns its hashed value.
+	# 
+	#   hashed = Argon2::Simple.hash(pw_clear)
+	def self.hash(pw_clear)
+		return Argon2::Password.new.create(pw_clear)
+	end
+	
+	##
+	# Accepts a clear password and a hashed value. Returns true if the clear
+	# password matches the hash. Does not throw any exceptions if the hash is
+	# not a valid Argon2 hash.
+	# 
+	#   ok = Argon2::Simple.check(pw_clear, hashed)
+	# 
+	def self.check(pw_clear, pw_hashed)
+		# must have both values as strings
+		pw_clear.is_a?(String) or return false
+		pw_hashed.is_a?(String) or return false
+		
+		# check cache
+		if @@cache
+			if acceptables = @@cache[pw_hashed]
+				if acceptables[pw_clear]
+					return true
+				end
+			end
+		end
+		
+		# It wasn't in the cache, so check the hard way.
+		# NOTE: Argon2 crashes if the string being checked isn't a valid hash.
+		# That seems stupid to me, because if it's not a valid hash then
+		# it's not the right password. But whatever. We handle the exception
+		# quietly here by just returning false.
+		begin
+			if Argon2::Password.verify_password(pw_clear, pw_hashed)
+				if @@cache
+					@@cache[pw_hashed] ||= LruRedux::Cache.new(10)
+					@@cache[pw_hashed][pw_clear] = true
+				end
+				return true
+			else
+				return false
+			end
+		rescue
+			return false
+		end
+	end
+end
+#
+# Argon2::Simple
+#==============================================================================

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: argon2-simple
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Mike O'Sullivan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-11-10 00:00:00.000000000 Z
+dependencies: []
+description: Simplifies the process of hashing a password with Argon2 and checking
+  if a submitted password matches a hash.
+email: mike@idocs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/argon2/simple.rb
+homepage: https://rubygems.org/gems/argon2-simple
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2.1
+signing_key: 
+specification_version: 4
+summary: Simple and efficient interface for the Argon2 module
+test_files: []