altpass 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+*.swp
+/.rvmrc
+/Gemfile.lock
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in altpass.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Alex Batko
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+Altpass
+=======
+
+A Ruby gem and command-line utility for *generating passwords* derived from *hand-alternating*, *visually unambiguous*, *alphanumeric characters*.
+
+Example
+-------
+
+`nXH3ix9w`
+
+General Characteristics
+-----------------------
+
+ * alternates hands (currently only supports `QWERTY` [keyboard layout](http://en.wikipedia.org/wiki/Keyboard_layout))
+ * always starts with a lower-case character (left-hand first for odd-length passwords; right if even)
+ * always ends with a left-hand character (so that the right-hand can finalize the hand alternation by hitting `Enter`/`Return`)
+ * all characters are alphanumeric; there are no symbols (so the passwords highlight when double-clicked)
+ * all characters are visually unambigous (some fonts make it difficult/impossible to distinguish *zero* and *capital 'o'*, or *one* and *lowercase 'L'*, and *uppercase i*, etc. so such characters are purposely not used)
+
+The "memorizable" pattern
+-------------------------
+
+ * the "memorizable" pattern is: lower, UPPER, UPPER, *number*, lower, lower, *number*, lower
+ * this pattern repeats for longer passwords
+
+At a glance, a password such as `nXH3ix9w` looks incredibly difficult to memorize, but practicing it 5-10 times usually does the trick, particularly after first taking note of the pattern.
+
+Options
+-------
+
+ * make passwords of any *length* (`:length => [0-9]+`)
+ * use the *memorizable* pattern or not (`:memorizable => true|false`)
+ * show the sample sets and number of *permutations* (`:permutations => [vvv]`) (more `v`'s increase verbosity)
+
+Defaults
+--------
+
+ * `:length => 8`
+ * `:memorizable => true`
+
+Examples of Gem Usage 
+---------------------
+
+Return a *default* password:
+
+    Altpass.generate
+     => "uGL4ox7f"
+
+Return an *odd-length* password, not using the memorizable pattern:
+
+    Altpass.generate(:length => 15, :memorizable => false)
+     => "cH5L3jwyw9XPw8V"
+
+Return an *even-length* password, not using the memorizable pattern:
+
+    Altpass.generate(:length => 16, :memorizable => false)
+     => "uV7AhspqySkBUwhs"
+
+Return the *number of permutations*:
+
+    Altpass.permutations(:length => 16, :memorizable => false)
+     => 2869959681148181529600
+
+Print the *sample sets* and *permutation calculation* of a default password, and return the *number of permutations*:
+
+    Altpass.permutations(:length => 8, :memorizable => true, :permutations => 'vvv')
+    sample sets:
+    ["y", "u", "i", "o", "p", "h", "j", "k", "n", "m"]
+    ["Q", "W", "E", "R", "T", "A", "S", "D", "F", "G", "Z", "X", "C", "V", "B"]
+    ["Y", "U", "P", "H", "J", "K", "L", "N", "M"]
+    ["2", "3", "4", "5"]
+    ["y", "u", "i", "o", "p", "h", "j", "k", "n", "m"]
+    ["q", "w", "e", "r", "t", "a", "s", "d", "f", "g", "z", "x", "c", "v"]
+    ["7", "8", "9"]
+    ["q", "w", "e", "r", "t", "a", "s", "d", "f", "g", "z", "x", "c", "v"]
+    10 * 15 * 9 * 4 * 10 * 14 * 3 * 14 permutations
+     => 31752000
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'altpass'
+
+And then execute:
+
+    $ bundle
+
+**Or** install it yourself:
+
+    $ gem install altpass
+
+The Command-Line Utility
+========================
+
+The command-line utility, `altpass.rb`, is built into the gem.
+
+Example
+--------
+
+    $ altpass.rb 
+    nF7zHTNrjtYRmxod
+
+Options
+-------
+
+    Usage: altpass.rb [options]
+        -l, --length [INTEGER>0]         Password length
+        -m, --memorizable [true|false]   Use the memorizable pattern or not
+        -p, --permutations [vvv]         Show permutation size; verbosity increases with v's
+        -s, --switches                   Show password switches
+        -h, --help                       Show this message
+
+Configuration
+-------------
+
+### Program defaults
+
+The program itself comes with the following defaults:
+
+    options[:length] = 8
+    options[:memorizable] = true
+    options[:permutations] = false
+    options[:switches] = false
+
+### File override
+
+Overrides program defaults.
+
+    cat ~/.altpass.yaml 
+    :length: 16
+    :memorizable: false
+
+### Command-line override
+
+Command-line options override everything mentioned above. See *Command-line Options* above.
+
+Examples of Command-Line Usage
+------------------------------
+
+These examples assume the above mentioned *Configuration* section is in effect.
+
+    $ altpass.rb 
+    nF7zHTNrjtYRmxod
+
+    $ altpass.rb -p
+    oDKfhfYznFN3j4Nv
+    2,869,959,681,148,181,529,600 permutations
+
+    $ altpass.rb --length 8 --memorizable true
+    kSU5yx9e
+
+    $ altpass.rb -l8 -mt -pvvv -s
+    jXJ3oc7z
+    sample sets:
+    ["y", "u", "i", "o", "p", "h", "j", "k", "n", "m"]
+    ["Q", "W", "E", "R", "T", "A", "S", "D", "F", "G", "Z", "X", "C", "V", "B"]
+    ["Y", "U", "P", "H", "J", "K", "L", "N", "M"]
+    ["2", "3", "4", "5"]
+    ["y", "u", "i", "o", "p", "h", "j", "k", "n", "m"]
+    ["q", "w", "e", "r", "t", "a", "s", "d", "f", "g", "z", "x", "c", "v"]
+    ["7", "8", "9"]
+    ["q", "w", "e", "r", "t", "a", "s", "d", "f", "g", "z", "x", "c", "v"]
+    10 * 15 * 9 * 4 * 10 * 14 * 3 * 14 permutations
+    31,752,000 permutations
+    --length 8 --memorizable true
+
+Contributing
+============
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my_new_feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my_new_feature`)
+5. Create new Pull Request
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc 'Run tests'
+task default: :test

data/altpass.gemspec

@@ -0,0 +1,24 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'altpass/version'
+
+Gem::Specification.new do |gem|
+	gem.name          = 'altpass'
+	gem.version       = Altpass::VERSION
+
+	gem.authors       = ['Alex Batko']
+	gem.email         = ['alexbatko@gmail.com']
+
+	gem.summary       = %q{Generate passwords derived from hand-alternating, visually unambiguous, alphanumeric characters}
+	gem.description   = "#{gem.summary}. This is a Ruby gem and command-line utility. Formerly known as 'alexpass'."
+
+	gem.homepage      = 'https://github.com/abatko/altpass'
+
+	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.license       = 'MIT'
+end
+

data/bin/altpass.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+
+require 'altpass'  # for actually generating the Altpass passwords
+require 'optparse' # for command-line options parsing
+require 'yaml'     # for loading the YAML configuration file, if present
+
+# defaults
+options = {}
+options[:length] = 8
+options[:memorizable] = true
+options[:permutations] = false
+options[:switches] = false
+
+# YAML configuration file overrides the defaults below
+CONFIGURATION_FILE = "#{ENV['HOME']}/.altpass.yaml"
+yaml_defaults = YAML.load_file(CONFIGURATION_FILE) if File.exist?(CONFIGURATION_FILE) && File.readable?(CONFIGURATION_FILE)
+options = options.merge(yaml_defaults) unless yaml_defaults.nil?
+
+# command-line options override yaml_defaults
+OptionParser.new do |opts|
+	opts.banner = 'Usage: altpass.rb [options]'
+
+	opts.on('-l', '--length [INTEGER>0]', OptionParser::DecimalInteger, 'Password length') do |l|
+		unless l > 0
+			puts 'argument to -l must be > 0'
+			puts opts ; exit
+		end
+		options[:length] = l
+	end
+
+	opts.on('-m [t|f]', '--memorizable [true|false]', 'Use the memorizable pattern or not') do |m|
+		case m
+		when /^(t|true)\Z/
+			options[:memorizable] = true
+		when /^(f|false)\Z/
+			options[:memorizable] = false
+		else
+			puts 'argument to -m must be [true|t|false|f]'
+			puts opts ; exit
+		end
+	end
+
+	opts.on('-p', '--permutations [vvv]', 'Show permutation size; verbosity increases with v\'s') do |p|
+		if !p.nil? && p !~ /^v+\Z/
+			puts 'argument to -p must be v\'s'
+			puts opts ; exit
+		end
+		options[:permutations] = p.nil? ? 'v' : p+'v'
+	end
+
+	opts.on('-s', '--switches', 'Show password switches') do |s|
+		options[:switches] = s
+	end
+
+	opts.on_tail('-h', '--help', 'Show this message') do
+		puts opts ; exit
+	end
+end.parse!
+
+def show_permutations(options)
+	permutations = Altpass.permutations(options)
+	# print the number of permutations after adding commas to it
+	puts permutations.to_s.reverse.scan(/(?:\d*\.)?\d{1,3}-?/).join(',').reverse + ' permutations'
+end
+
+puts Altpass.generate(:length => options[:length], :memorizable => options[:memorizable])
+
+show_permutations(options) if options[:permutations]
+
+puts "--length #{options[:length]} --memorizable #{options[:memorizable]}" if options[:switches]
+

data/lib/altpass/version.rb

@@ -0,0 +1,4 @@
+module Altpass
+  VERSION = '0.1.0'
+end
+

data/lib/altpass.rb

@@ -0,0 +1,92 @@
+require 'altpass/version'
+
+module Altpass
+
+	DEFAULT_LENGTH = 8
+	DEFAULT_OPTIONS = {:length => DEFAULT_LENGTH, :memorizable => true}
+
+	# character sets divided by touch typing hands
+	LN = '12345'.split('')                    # Left-hand Numbers
+	RN = '67890' .split('')                   # Right       ''
+	LL = ('qwert'+'asdfg'+'zxcvb').split('')  # Left-hand Lowercase letters
+	RL = ('yuiop'+'hjkl'+'nm').split('')      # Right       ''        ''
+	LU = LL.collect {|c| c.capitalize}        # Left-hand Uppercase letters
+	RU = RL.collect {|c| c.capitalize}        # Right       ''        ''
+
+	AMBIGUOUS =
+		'1lI0O' + # visually ambiguous
+		'6b'      # left/right ambiguous
+
+	# patterns for even and odd length passwords;
+	# alternating hands, with the last always being on the left;
+	# only the first in each subset takes part in the "memorizable" pattern: LUUNLLNL
+	@pattern_even = [[RL], [LU, LN, LL], [RU, RN, RL], [LN, LL, LU], [RL, RU, RN], [LL, LU, LN], [RN, RL, RU], [LL]]
+
+	@pattern_odd  = [[LL], [RU, RN, RL], [LU, LN, LL], [RN, RL, RU], [LL, LU, LN], [RL, RU, RN], [LN, LL, LU], [RL]]
+
+	# return a password
+	def self.generate(options={})
+		options = self._verify_options(options)
+		password = ''
+		iterations = options[:length]/DEFAULT_LENGTH + 1
+		iterations.times { password += self._generate(options) }
+		password.slice(0...options[:length])
+	end
+
+	# return the number of permutations,
+	# and additionally print out details when options[:permutations] contains v's
+	def self.permutations(options={})
+		options = self._verify_options(options)
+		p = 1
+		pattern = options[:length].even? ? @pattern_even : @pattern_odd
+		plen = pattern.length
+		samples = []
+		(0...options[:length]).each { |i|
+			samples[i] = (options[:memorizable] ? pattern[i%plen][0] : pattern[i%plen].flatten).reject{|c| AMBIGUOUS.include?(c)}
+			p *= samples[i].length # take the product of all sample sizes to get the total number of permutations
+		}
+		if options[:permutations] =~ /^v{3,}\Z/
+			puts 'sample sets:'
+			samples.each {|s|
+				puts s.inspect
+			}
+		end
+		puts "#{samples.collect {|s| s.length}.join(' * ')} permutations" if options[:permutations] =~ /^v{2,}\Z/
+		p
+	end
+
+private
+
+	# verify and return an options hash, after merging the default options with the incoming ones
+	def self._verify_options(options=nil)
+		raise ArgumentError, "expected a Hash, but got: #{options.inspect}" unless options.kind_of?(Hash)
+		options = DEFAULT_OPTIONS.merge(options)
+		raise ArgumentError, "expected :memorizable to be boolean, but got: #{options[:memorizable].inspect}" unless options[:memorizable].kind_of?(TrueClass) || options[:memorizable].kind_of?(FalseClass)
+		raise ArgumentError, "expected :length to be a Fixnum, but got: #{options[:length].inspect}" unless options[:length].kind_of?(Fixnum)
+		raise ArgumentError, "expected :length > 0, but got: #{options[:length]}" unless options[:length] > 0
+		options
+	end
+
+	# generate and return a string, having a parity-appropriate pattern, where each character is sampled from the appropriate character set (depending on whether :memorizable is true or false)
+	def self._generate(options={})
+		options = self._verify_options(options)
+		pattern = options[:length].even? ? @pattern_even : @pattern_odd
+		return pattern.collect { |i|
+			s =''
+			loop do
+				s = _sample(i[options[:memorizable] ? 0 : rand(i.length)])
+				break unless AMBIGUOUS.include?(s)
+			end
+			s
+		}.join.slice(0..-1)
+	end
+
+	# pick a random element from the given array
+	def self._sample(a=[])
+		raise ArgumentError, "expected an Array, but got: #{a.class}" unless a.kind_of?(Array)
+		raise ArgumentError, 'expected a non-empty Array, but got an empty one' unless a.length > 0
+		a[rand(a.length)]
+	end
+
+end
+

data/test/test_altpass.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+require 'test_helper'
+
+class AltpassTest < Test::Unit::TestCase
+
+  def test__generate__default_length
+    assert_equal Altpass::DEFAULT_LENGTH, Altpass.generate.length
+  end
+
+  def test__generate__random_length
+    random_length = rand(20)+1
+    assert_equal random_length, Altpass.generate(:length=>random_length).length
+  end
+
+  def test__generate__raise_exception_for_non_hash_argument
+    non_hash_argument = 10 
+    exception = assert_raise(ArgumentError) { Altpass.generate(non_hash_argument) }
+    assert_equal "expected a Hash, but got: #{non_hash_argument}", exception.message
+  end
+
+  def test__generate__raise_exception_for_bad_memorizable_hash_value_type
+    non_boolean = {:memorizable => 10}
+    exception = assert_raise(ArgumentError) { Altpass.generate(non_boolean) }
+    assert_equal "expected :memorizable to be boolean, but got: #{non_boolean[:memorizable].inspect}", exception.message
+  end
+
+  def test__generate__raise_exception_for_bad_length_hash_value_type
+    non_fixnum = {:length => 'A'}
+    exception = assert_raise(ArgumentError) { Altpass.generate(non_fixnum) }
+    assert_equal "expected :length to be a Fixnum, but got: #{non_fixnum[:length].inspect}", exception.message
+  end
+
+  def test_raise_exception_for_fixnum_argument_less_than_one_to_generate_to_length
+    fixnum_argument = {:length => 0}
+    exception = assert_raise(ArgumentError) { Altpass.generate(fixnum_argument) }
+    assert_equal "expected :length > 0, but got: #{fixnum_argument[:length].inspect}", exception.message
+  end
+
+  def test__sample
+    assert_equal 'a', Altpass._sample(['a'])
+    assert_equal 'a', Altpass._sample(['a', 'a', 'a'])
+    random_element = Altpass._sample(['a', 'b', 'c'])
+    assert_equal String, random_element.class
+    assert_equal 1, random_element.length
+  end
+
+  def test__sample_raise_exception_for_non_array_argument
+    exception = assert_raise(ArgumentError) { Altpass._sample({}) }
+    assert_equal "expected an Array, but got: Hash", exception.message
+  end
+
+  def test__sample_raise_exception_for_empty_array_argument
+    exception = assert_raise(ArgumentError) { Altpass._sample([]) }
+    assert_equal "expected a non-empty Array, but got an empty one", exception.message
+  end
+
+  def test__permutations
+    # these hardcoded values will need to be updated if/when the character set lengths change
+    assert_equal 31752000, Altpass.permutations
+    assert_equal 53572004640, Altpass.permutations(:memorizable => false)
+    assert_equal 60011280000, Altpass.permutations(:memorizable => true, :length => 11)
+    assert_equal 544505855160960, Altpass.permutations(:memorizable => false, :length => 11)
+  end
+
+end
+

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'test/unit'
+#require 'altpass'
+require './lib/altpass.rb'
+

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: altpass
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Alex Batko
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-14 00:00:00.000000000Z
+dependencies: []
+description: Generate passwords derived from hand-alternating, visually unambiguous,
+  alphanumeric characters. This is a Ruby gem and command-line utility. Formerly known
+  as 'alexpass'.
+email:
+- alexbatko@gmail.com
+executables:
+- altpass.rb
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- altpass.gemspec
+- bin/altpass.rb
+- lib/altpass.rb
+- lib/altpass/version.rb
+- test/test_altpass.rb
+- test/test_helper.rb
+homepage: https://github.com/abatko/altpass
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Generate passwords derived from hand-alternating, visually unambiguous, alphanumeric
+  characters
+test_files:
+- test/test_altpass.rb
+- test/test_helper.rb