Class: Password

Inherits:
Object
  • Object
show all
Includes:
EncodingTranslation
Defined in:
lib/password.rb

Overview

Password Class

Password encapsulates a password and provides functionality for hashing, hash-based authentication, and random password generation.

Setting up a new Password object

This will create a new Password object using no salt and the default, SHA256 digest.

p = Password.new( 'foobar' )

This will create a new Password object using a new, random salt and the SHA512 digest.

p = Password.new( 'foobar', Salt.new, :sha512 )

This will create a new, random password (using default random generation options – see Password.new) using no salt, and the default, SHA256 digest.

p = Password.new( :new )

This will create a new, random password of length 10 (and using default random generation options – see Password.new) using no salt, and the MD5 digest.

p = Password.new( :new, nil, :md5, :length => 10 )

Getting the hash

This hash will give the hash in binary format.

hash = p.hash

This hash will give the hash in hexidecimal format.

hash = p.hash( :hex )

Authenticating a password

This will authenticate the Password p using String auth_hash_data that was gotten from a database.

authenticated = p.authenticate( auth_hash_data ) => true/false

Generating a random password

See Password.new for all options. The same options may be passed to the constructor’s generation_options parameter with the password set as :new to generate a new random password.

p = Password.new( :new, nil, :sha256, :length => 8, 
                                      :no_duplicates => true )

Sanitizing the password from memory

This will clear the plain-text password String from memory, destructively.

p.sanitize

Changing the salt and digest

When you change/set the password, salt, or digest, you will automatically regenerate the hash that is stored within the Password instance.

p.salt = Salt.new
p.digest = :sha1

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from EncodingTranslation

#b64_to_bin, #bin_to_b64, #bin_to_hex, #hex_to_bin

Constructor Details

#initialize(password, salt = nil, digest = :sha256, generation_options = {}) ⇒ Password

Initialize a new Password object

When password is a String, it is set as the password.

When password is :new; a new, random password is generated via RandomStringGenerator with the given generation_options.

salt: see Password.salt= digest: see Password.digest=

Generation Options

:length

length of the password, default is 8

:no_duplicates

no duplicate characters, default is false

:lower_alphas

include lower alpha characters, default is true

:upper_alphas

include upper alpha characters, default is true

:numerals

include numeral characters, default is true

:symbols

include symbol characters, default is false

:single_quotes

include single quote characters, default is false

:double_quotes

include double quote characters, default is false

:backtick

include tick characters, default is false

:special

use a special string or array of ranges, overrides all other inclusion options



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/password.rb', line 130

def initialize( password, salt = nil, digest = :sha256, generation_options = {} )
  if password == :new
    len = generation_options.delete(:length)
    @password = RandomStringGenerator.new( len || 8, generation_options ).generate
  else
    @password = password
  end
  @salt = salt
  @digest = digest
  rehash
end

Instance Attribute Details

#digest ⇒ Object

Returns the value of attribute digest.



104
105
106
 
# File 'lib/password.rb', line 104

def digest
  @digest
end

#password ⇒ Object

Returns the value of attribute password.



104
105
106
 
# File 'lib/password.rb', line 104

def password
  @password
end

#salt ⇒ Object

Returns the value of attribute salt.



104
105
106
 
# File 'lib/password.rb', line 104

def salt
  @salt
end

Instance Method Details

#authenticate(auth_hash_data) ⇒ Object

Attempts to authenticate the given password against the given hash. The salt used to create the given hash MUST match the salt of this Password object. The digest and format of the given hash are automatically detected.



239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/password.rb', line 239

def authenticate( auth_hash_data )
  f, d = detect_type( auth_hash_data )

  h = generate_hash( generate_salted(password, salt), d )
  
  # convert h to proper format
  case f
  when :hex
    h = bin_to_hex h
  when :base64
    h = bin_to_b64 h
  end
  
  auth_hash_data.eql?(h)
end

#hash(format = :binary) ⇒ Object

Gets the hash, or generates one if one hasn’t already been generated, and stores it for future use.

format must be one of: :binary (default), :hex, :base64



198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'lib/password.rb', line 198

def hash( format = :binary )
  case format.to_sym
  when :binary, :bin
    return @hash
  when :hex, :hexidecimal
    return bin_to_hex(@hash)
  when :base64
    return bin_to_b64(@hash)
  else
    raise ArgumentError, "#{format.to_s} is an invalid format."
  end
end

#rehash ⇒ Object

Rehash the password.

If you



216
217
218
219
220
221
222
223
224
 
# File 'lib/password.rb', line 216

def rehash
  raise "Password has not been set or has been sanitized." unless @password
  
  # Do the salting
  salted = generate_salted( password, salt )
  
  # Do the hashing
  @hash = generate_hash( salted, digest )
end

#sanitize ⇒ Object

Santizes the password from the object and from memory.

*WARNING: THIS WILL DESTROY THE ORIGINAL PASSWORD STRING ALSO*

Exampe:

original_pass = "foobar"
p = Password.new(original_pass)
p.sanitize
puts original_pass => ""



162
163
164
165
166
 
# File 'lib/password.rb', line 162

def sanitize
  return unless @password
  @password.sanitize
  @password = nil
end

#to_s ⇒ Object

Returns the password string, or an empty string if the password has not been set or has been sanitized



229
230
231
 
# File 'lib/password.rb', line 229

def to_s
  password || ''
end