Class: Password
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
-
#digest ⇒ Object
Returns the value of attribute digest.
-
#password ⇒ Object
Returns the value of attribute password.
-
#salt ⇒ Object
Returns the value of attribute salt.
Instance Method Summary collapse
-
#authenticate(auth_hash_data) ⇒ Object
Attempts to authenticate the given password against the given hash.
-
#hash(format = :binary) ⇒ Object
Gets the hash, or generates one if one hasn’t already been generated, and stores it for future use.
-
#initialize(password, salt = nil, digest = :sha256, generation_options = {}) ⇒ Password
constructor
Initialize a new Password object.
-
#rehash ⇒ Object
Rehash the password.
-
#sanitize ⇒ Object
Santizes the password from the object and from memory.
-
#to_s ⇒ Object
Returns the password string, or an empty string if the password has not been set or has been sanitized.
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, = {} ) if password == :new len = .delete(:length) @password = RandomStringGenerator.new( len || 8, ).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
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 |