NAME

Ruby/Password - password handling for Ruby

SYNOPSIS

require 'password'

begin
  password = Password.get("New password")
  p = Password.new(password)
  p.check
rescue Password::WeakPassword => reason
  puts reason
  retry
end

DESCRIPTION

Ruby/Password is a collection of password handling routines for Ruby, including an interface to CrackLib for the purposes of testing password strength.

CLASS METHODS

Password.new(password): This creates a new instance of the Password class for password.
Password.get(message = "Password"): This obtains a password from the keyboard, using buffered line input. If message is given, it is used as the password prompt. This method also returns a new instance of the Password class.
Password.getc(message = "Password", mask = '*'): This obtains a password from the keyboard, using unbuffered character input. If message is given, it is used as the password prompt. mask will be echoed to the terminal as each keypress is entered.
Password.echo(on = true, masked = false): This turns echoing to the terminal either on or off. If turning echoing off and masked is true, the keyboard is put into unbuffered mode, allowing the retrieval of characters one at a time. masked has no effect when turning echoing on.
Password.random(length = 8): This generates a random password by drawing bytes from the system entropy pool /dev/urandom and Base64-encoding them.

INSTANCE METHODS

Password#crypt(type = Password::DES, salt = '')

This encrypts the password, using the salt provided. If salt is not given, a random one will be generated and used. If type is set to Password::MD5 and the underlying C library supports it, an MD5 algorithm will be used to encrypt the password instead of the DES algorithm. If the C library does not support this, a CryptError exception will be raised.

Password#check(dict = nil)

This interfaces to LibCrack to check the strength of the password. If dict is given, it is the path to the CrackLib dictionary, minus the file's extension, so if the dictionary is located at /usr/lib/cracklib_dict.pwd, you would pass a dict of /usr/lib/cracklib_dict . If it is not given, the dictionary found at build time will be used. If a path is given that does not lead to a legible dictionary, a Password::BadDictionary exception is raised.

On success, true is returned. On failure, a Password::WeakPassword exception is raised.

CONSTANTS

Password::MD5: When passed to the Password#crypt method, an MD5 algorithm will be used instead of the DES algorithm to encrypt the password.
Password::DES: By default, this is passed to the Password#crypt method to generate a DES- encrypted password.

AUTHOR

Written by Ian Macdonald <ian@caliban.org>

COPYRIGHT

Copyright (C) 2002-2003 Ian Macdonald

This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.

BUGS

Send all bug reports, enhancement requests and patches to the author.

HISTORY

$Id: password.rb,v 1.13 2003/11/12 09:25:40 ianmacd Exp $