pog19 1.1.1

data/lib/random_string_generator.rb

@@ -0,0 +1,291 @@
+##
+# = random_string_generator.rb
+#
+# Copyright (c) 2007 Operis Systems, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# 
+require File.join(File.dirname(__FILE__), 'character_ranges.rb')
+
+##
+# == RandomStringGenerator Class
+#
+# RandomStringGenerator provides the functionality to generate random Strings.
+# It could be called RandomPasswordGenerator; however, this is not a highly secure
+# generator.  It depends on the security of the rand() method.  An acceptable usage 
+# of this might be the generation of temporary passwords.  See the SECURITY_NOTES file.
+#
+#
+# === Generating a Random Password
+# 
+# This is how to generate a random String with the default settings (see
+# RandomStringGenerator.new for list of options)
+# 
+#   rsg = RandomStringGenerator.new
+#   str = rsg.generate => #<String>
+# 
+# This will generate a random String of length 10, with no duplicate 
+# characters, and not using an uppercase characters.
+# 
+#   rsg = RandomStringGenerator.new( 10, :no_duplicates => true, :upper_alphas => false )
+#   str = rsg.generate => #<String>
+# 
+# 
+# === Changing the length and options between generations
+# 
+#   rsg = RandomStringGenerator.new
+#   str = rsg.generate
+# 
+# Now change the options and length and call generate
+# 
+#   rsg.set_options( :special => 'qwerty', :no_duplicates => true)
+#   rsg.length = 6
+#   str = rsg.generate
+# 
+# 
+# === Generate a WEP key
+# 
+# This will generate a 64 bit WEP key in hexidecimal format
+# 
+#   wep_64b_hex = RandomStringGenerator.generate_wep( 64 )
+# 
+# This will generate a 128 bit WEP key in ASCII format.  (Note that ASCII WEP 
+# keys are not as secure as hexidecimal keys)
+# 
+#   wep_128b_ascii = RandomStringGenerator.generate_wep( 128, :ascii )
+# 
+# 
+# === Shuffle a String
+#
+# You can shuffle a string inplace (destructively) or you can shuffle the 
+# String into a new one.
+# 
+# Inplace:
+# 
+#   str = 'foobar'
+#   RandomStringGenerator.shuffle_string! str
+# 
+# +str+ is now shuffled.
+# 
+# New String:
+# 
+#   str = 'foobar'
+#   new_str = RandomStringGenerator.shuffle_string str
+# 
+# +str+ is not touched
+# +new_str+ is a shuffled version of +str+
+# 
+class RandomStringGenerator
+  include CharacterRanges
+  
+  attr_accessor :length
+  attr_reader :options
+  
+  ##
+  # Initializes a new random string generator.
+  #
+  # +len+ is the length of the string you wish to have generated.  Default is 8.
+  #
+  # Options:
+  #
+  # <tt>:no_duplicates</tt>::       no duplicate characters, default is false
+  # <tt>:lower_alphas</tt>::        include lower alpha characters, default is true
+  # <tt>:upper_alphas</tt>::        include upper alpha characters, default is true
+  # <tt>:numerals</tt>::            include numeral characters, default is true
+  # <tt>:symbols</tt>::             include symbol characters, default is false
+  # <tt>:single_quotes</tt>::       include single quote characters, default is false
+  # <tt>:double_quotes</tt>::       include double quote characters, default is false
+  # <tt>:backtick</tt>::            include tick characters, default is false
+  # <tt>:special</tt>::             use a special string or array of ranges, overrides all other inclusion options
+  #
+  def initialize( len = 8, options = {} )
+    @length = len
+    @options = { :lower_alphas => true,
+      :upper_alphas => true,
+      :numerals     => true,
+      :no_duplicates=> false}.merge options
+    
+  end
+  
+  ##
+  # Set the given options in 
+  #
+  # See RandomStringGenerator.new for the list of options.
+  #
+  def set_option( opts = {} )
+    @options.merge!( opts )
+  end
+  
+  ##
+  # Generate a password.
+  # 
+  def generate
+    set_characters_array
+    
+    # safety check for no_duplicates running out of characters
+    if @options[:no_duplicates] && @characters.length < @length
+      raise RuntimeError, "Too few options to have no duplicates."
+    end
+    shuffle_characters_array
+    
+    # generate the password
+    p = String.new
+    for i in 0...@length
+      p << rand_char( @options[:noduplicates] )
+    end
+    return RandomStringGenerator.shuffle_string!(p)
+  end
+
+  ##
+  # Get a random character from the characters array.  Set the parameter to 
+  # +true+ to remove the character from the list after it's been returned. 
+  #
+  def rand_char( delete_after_get = false )
+    i = rand_index
+    end_i = i + @characters.length
+    
+    until @characters[ i % @characters.length ].ord > 0 do # Walk until you find a non-0 character
+      raise "No more characters." if i == end_i
+      i += 1
+    end
+    c = @characters[ i % @characters.length ].chr # c is now the character we will return
+    @characters[ i % @characters.length ] = 0.chr if delete_after_get # set the character to 0 (indicating deletedness)
+    return c
+  end
+  
+  ##
+  # Shuffles the given string (destructively aka. inplace)
+  #
+  def self.shuffle_string!( str )
+    scramblers = Array.new(8)
+    for i in 0...(str.length/2)
+      scrambler_1 = rand(0xffffffff)
+      scrambler_2 = rand(0xffffffff)
+      for j in 0...4
+        scramblers[j] = ((scrambler_1 & (0xff<<j*8)) >> j*8) % str.length
+      end
+      for j in 4...8 
+        scramblers[j] = ((scrambler_2 & (0xff<<(j-4)*8)) >> (j-4)*8) % str.length
+        # offset the wrap around to the end of the string
+        scramblers[j] = (scramblers[j] + (0xff%str.length)) % str.length
+      end
+      
+      # do the scrambling
+      t = str[scramblers[0]]
+      7.times { |j| str[scramblers[j]] = str[scramblers[j+1]] }
+      str[scramblers[7]] = t
+    end
+    return str
+  end
+  
+  ##
+  # Returns a shuffled version of the given string.
+  #
+  def self.shuffle_string( str )
+    RandomStringGenerator.shuffle_string!( str.dup )
+  end
+  
+  ##
+  # Scramble the characters array
+  # 
+  def shuffle_characters_array
+    RandomStringGenerator.shuffle_string!( @characters )
+  end
+  
+  ##
+  # Set the characters array to the set that we can use to generate a new 
+  # password.
+  #
+  def set_characters_array
+    if @options.has_key? :special # set to special if it's there
+      set_characters_from_special( @options[:special] )
+    else # set by the given ranges
+      ranges = Array.new
+      @options.each do |opt, val| # run through options
+        unless opt == :length || opt == :no_duplicates || val == false 
+          ranges << self.send("range_#{opt.to_s}")
+        end
+      end
+      set_characters_from_ranges ranges.flatten
+    end
+  end
+  
+  
+  ##
+  # Generates a WEP key
+  #
+  # +bits+:     The number of bits for the encryption policy (ie. 64, 128, 152, 256)
+  # +output+::  Either <tt>:hex</tt> or <tt>:ascii</tt> (hex is more secure)
+  #
+  def self.generate_wep( bits, output = :hex )
+    raise "Not a valid number of bits for a WEP key." unless [64,128,152,256].include? bits
+    
+    case output
+    when :hex
+      rsg = RandomStringGenerator.new((bits-24)/8, :special => [0..0xff])
+      key = rsg.generate
+      return key.unpack("H#{key.length*2}").at(0) if output == :hex
+    when :ascii
+      rsg = RandomStringGenerator.new((bits-24)/8, :special => [0x20..0x7e])
+      key = rsg.generate
+      return key
+    else
+      raise "Invalid output type."
+    end
+  end
+  
+  protected
+
+  ##
+  # Get a random index of the characters array
+  #
+  def rand_index
+    j = rand(@characters.length**4)
+    i = 0
+    for k in 0...4
+      i += (j & (0xff<<k*8)) >> k*8
+    end
+    i %= @characters.length
+  end
+  
+  ##
+  # Set the characters array using the :special options variable to the set we
+  # can use to generate a new pasword.
+  #
+  def set_characters_from_special( special )
+    if special.is_a? Array # check that each value of the array is a range
+      special.each do |r|
+        raise ArgumentError, ":special must either be a String or an Array of Ranges." unless r.is_a? Range
+      end
+      set_characters_from_ranges special
+    elsif special.is_a? String
+      @characters = special
+    else # must either be a string or array of ranges
+      raise ArgumentError, ":special must either be a String or an Array of Ranges."
+    end
+  end
+  
+  ##
+  # Set the characters array by the @ranges variable to the set that we can 
+  # use to generate a new password.
+  # 
+  def set_characters_from_ranges( ranges )
+    @characters = String.new
+    ranges.each do |r|
+      for i in r
+        @characters << i.chr
+      end
+    end
+    @characters
+  end
+end

data/lib/salt.rb

@@ -0,0 +1,135 @@
+##
+# = salt.rb
+#
+# Copyright (c) 2007 Operis Systems, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# 
+require File.join(File.dirname(__FILE__), 'random_string_generator.rb')
+
+##
+# == Salt Class
+#
+# Salt encapsulates a password's salt and provides functionality for password 
+# salting and random salt generation.
+#
+#
+# === What is a "password salt"?
+# 
+# A "password salt" is a string that is added to a password string to obscure
+# the password when it is hashed to keep the password hash from being cracked.
+#
+# See http://en.wikipedia.org/wiki/Salt_(cryptography)
+#
+#
+# === Setting up a new Salt
+# 
+# This generates a new, random salt, with end placement
+#
+#   s = Salt.new 
+# 
+# This creates the salt 'foobar', with split placement.
+#
+#   s = Salt.new('foobar')
+# 
+# This generates a new, random salt of length 9, with end placement
+#
+#   s = Salt.new( :new, :end, :length => 9)
+# or
+#   s = Salt.new( Salt.generate( 8 ) )
+#
+#
+# === Salting a password
+# 
+# This will salt the password 'foobar'
+#
+#   s = s.salt('foobar')
+#
+#
+# === What is salt placement?
+# 
+# "salt placement" is where the salt will go in the password.  For example, 
+# "beginning" salt placement would prepend the salt to the password prior to
+# hashing, and "split" salt placement would prepend the first half and
+# append the second half.
+#
+class Salt
+  attr_accessor :string
+  attr_reader :placement
+  
+  ##
+  # Initializes a new Salt instance with the given +string+ and +placement+
+  # 
+  # See Salt.placement= for +placement+ options
+  # 
+  # Options:
+  # 
+  # <tt>:length</tt>:     the length for a new salt. (default is 8)
+  #
+  def initialize( string = :new, placement = :end, options = {} )
+    @placement  = placement.to_sym
+    @string     = (string == :new ? 
+                   Salt.generate_str(options[:length] || 8) : string)
+  end
+
+  ##
+  # Set the salt's placement
+  # 
+  # Valid placements: <tt>:end</tt> (default), <tt>:beginning</tt>, <tt>:split</tt>
+  #
+  def placement=( new_placement )
+    @placement = new_placement.to_sym
+  end
+  
+  ##
+  # Returns the given password, salted.
+  #
+  def salt_password( password )
+    case placement.to_sym
+    when :end
+      password.to_s + string
+    when :beginning
+      string + password.to_s
+    when :split
+      string[0...(string.length/2).floor] + password.to_s + string[(string.length/2).floor...string.length]
+    else
+      raise RuntimeError, "#{placement.to_s} is an invalid salt placement."
+    end
+  end
+  
+  ##
+  # Returns the salt string.
+  # 
+  # Same as calling Salt#string
+  # 
+  def to_s
+    string.to_s
+  end
+  
+  ##
+  # Generate a salt string of the given length (default is 8).
+  # 
+  def self.generate_str(length = 8)
+    RandomStringGenerator.new( length, { :lower_alphas => true,
+                                         :upper_alphas => true,
+                                         :numerals     => true,
+                                         :symbols      => true }).generate
+  end
+  
+  ##
+  # Returns +true+ if the given salt is equivilent to this salt, +false+ otherwise
+  #
+  def eql?( salt )
+    self.to_s.eql?(salt.to_s) && self.placement.eql?(salt.placement)
+  end
+end

data/lib/string.rb

@@ -0,0 +1,15 @@
+##
+# Add the sanitize! method to the String class
+#
+class String
+  
+  ##
+  # Sanitize the String *completely* from memory.  This is non-reversible.
+  #
+  def sanitize
+    for i in 0...self.length
+      self[i] = 0
+    end
+    self.delete!("\000")
+  end
+end

data/pog1-9.gemspec

@@ -0,0 +1,20 @@
+require 'rubygems'
+
+version = File.read('VERSION').strip
+raise "no version" if version.empty?
+
+spec = Gem::Specification.new do |s|
+  s.name = 'pog19'
+  s.version = version 
+  s.author = 'Operis Systems, LLC'
+  s.email = ''
+  s.homepage = 'http://pog.rubyforge.org/'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'A Ruby gem for simplifying random password generation'
+  s.description = s.summary + ', password strength testing, password hashing and salting, and password-hash authentication.'
+  s.files = Dir['**/*'].delete_if { |f| f =~ /(cvs|gem|svn)$/i }
+  s.require_path = 'lib'
+  s.rdoc_options << '--all' << '--inline-source' << '--main' << 'lib/*.rb'
+  s.has_rdoc = true
+  s.rubyforge_project = 'pog'
+end

data/test/tc_password.rb

@@ -0,0 +1,122 @@
+# Copyright (c) 2007 Operis Systems, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+require 'test/unit'
+require 'base64'
+require File.join( File.dirname(__FILE__), '..', 'lib', 'pog.rb' )
+
+TEST_PASS = '/O0op;G75wu3saMv|N9&DA?I*/!3-gqHUe9{VZL{M3YVoYUQ]6q{]Poz%c)V#T,i=g.G8>&'
+
+class TC_Password < Test::Unit::TestCase
+  def test_to_s
+    password = Password.new( TEST_PASS )
+    assert_equal(TEST_PASS, password.to_s)
+    
+    password = Password.new( :new )
+    assert_equal false, password.to_s.empty?
+  end
+  
+  def test_hash
+    pass = Password.new( TEST_PASS )
+    
+    # test digests
+    assert_equal Digest::SHA256.digest(TEST_PASS), 
+                 pass.hash,
+                 'hash generation failed for SHA256 digest'
+                 
+    pass.digest = :sha512
+    assert_equal Digest::SHA512.digest(TEST_PASS), 
+                 pass.hash,
+                 'hash generation failed for SHA512 digest'
+                 
+    pass.digest = :sha384
+    assert_equal Digest::SHA384.digest(TEST_PASS), 
+                 pass.hash,
+                 'hash generation failed for SHA384 digest'
+                 
+    pass.digest = :sha1
+    assert_equal Digest::SHA1.digest(TEST_PASS), 
+                 pass.hash,
+                 'hash generation failed for SHA1 digest'
+                 
+    pass.digest = :md5
+    assert_equal Digest::MD5.digest(TEST_PASS), 
+                 pass.hash,
+                 'hash generation failed for MD5 digest'
+                 
+    # test formats
+    pass.digest = :sha256
+    
+    assert_equal Digest::SHA256.hexdigest(TEST_PASS), 
+                 pass.hash( :hex ), 
+                 'hash generation failed for default (hexidecimal) format'
+                 
+    assert_equal Base64.encode64( Digest::SHA256.digest(TEST_PASS) ).gsub(/\s+/, ''), 
+                 pass.hash( :base64 ),
+                 'hash generation failed for base64 format'
+  end
+
+  def test_authenticate
+    pass = Password.new( TEST_PASS, Salt.new )
+
+    assert pass.authenticate(Digest::SHA256.digest(TEST_PASS + pass.salt.to_s))
+    assert_equal false, pass.authenticate(Digest::SHA256.digest(pass.salt.to_s + TEST_PASS))
+    
+    assert pass.authenticate(Digest::SHA1.digest(TEST_PASS + pass.salt.to_s))
+    assert pass.authenticate(Digest::SHA384.hexdigest(TEST_PASS + pass.salt.to_s))
+    assert pass.authenticate(Digest::SHA512.digest(TEST_PASS + pass.salt.to_s))
+    
+    md5_b64 = [Digest::MD5.digest(TEST_PASS + pass.salt.to_s)].pack('m').gsub(/\s+/, '')
+    assert pass.authenticate( md5_b64 )
+    
+    assert_raise(RuntimeError) {pass.authenticate(md5_b64+'#')}
+  end
+  
+  def test_setters
+    salt = Salt.new
+    p = Password.new :new, Salt.new, :sha512
+    
+    p.password = TEST_PASS
+    assert_same(p.password, TEST_PASS)
+    
+    p.salt = salt
+    assert_same(p.salt, salt)
+    
+    p.salt = salt.to_s
+    assert(p.salt.eql?(salt))
+    
+    assert_raise(ArgumentError) { p.hash(:foo) }
+
+    assert_raise(RuntimeError) { p.digest = :foo }
+  end
+  
+  def test_sanitize
+    test_pass = TEST_PASS.dup
+    p = Password.new( test_pass )
+    assert_equal(nil, p.sanitize)
+    
+    assert_equal('', p.to_s)
+    assert_equal(nil, p.password)
+
+    assert_equal Digest::SHA256.digest(TEST_PASS), 
+                 p.hash
+    assert_same(p.password, nil)
+    assert_equal(test_pass, '')
+
+    for i in 0...test_pass.length
+      assert_equal test_pass[i], 0
+    end
+    
+    assert_raise(RuntimeError) {p.rehash}
+  end
+end