Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ReadPassword(3)	      User Contributed Perl Documentation      ReadPassword(3)

NAME
       Term::ReadPassword - Asking the user for	a password

SYNOPSIS
	 use Term::ReadPassword;
	 while (1) {
	   my $password	= read_password('password: ');
	   redo	unless defined $password;
	   if ($password eq 'flubber') {
	     print "Access granted.\n";
	     last;
	   } else {
	     print "Access denied.\n";
	     redo;
	   }
	 }

DESCRIPTION
       This module lets	you ask	the user for a password	in the traditional
       way, from the keyboard, without echoing.

       This is not intended for	use over the web; user authentication over the
       web is another matter entirely. Also, this module should	generally be
       used in conjunction with	Perl's crypt() function, sold separately.

       The read_password function prompts for input, reads a line of text from
       the keyboard, then returns that line to the caller. The line of text
       doesn't include the newline character, so there's no need to use	chomp.

       While the user is entering the text, a few special characters are
       processed.  The character delete	(or the	character backspace) will back
       up one character, removing the last character in	the input buffer (if
       any). The character CR (or the character	LF) will signal	the end	of
       input, causing the accumulated input buffer to be returned. Control-U
       will empty the input buffer. And, optionally, the character Control-C
       may be used to terminate	the input operation. (See details below.) All
       other characters, even ones which would normally	have special purposes,
       will be added to	the input buffer.

       It is not recommended, though, that you use the as-yet-unspecified
       control characters in your passwords, as	those characters may become
       meaningful in a future version of this module. Applications which allow
       the user	to set their own passwords may wish to enforce this rule,
       perhaps with code something like	this:

	   {
	     # Naked block for scoping and redo
	     my	$new_pw	= read_password("Enter your new	password: ");
	     if	($new_pw =~ /([^\x20-\x7E])/) {
	       my $bad = unpack	"H*", $1;
	       print "Your password may	not contain the	";
	       print "character	with hex code $bad.\n";
	       redo;
	     } elsif (length($new_pw) <	5) {
	       print "Your password must be longer than	that!\n";
	       redo;
	     } elsif ($new_pw ne read_password("Enter it again:	")) {
	       print "Passwords	don't match.\n";
	       redo;
	     } else {
	       &change_password($new_pw);
	       print "Your password is now changed.\n";
	     }
	   }

       The second parameter to read_password is	the optional "idle_timeout"
       value. If it is a non-zero number and there is no keyboard input	for
       that many seconds, the input operation will terminate. Notice that this
       is not an overall time limit, as	the timer is restarted with each new
       character.

       The third parameter will	optionally allow the input operation to	be
       terminated by the user with Control-C. If this is not supplied, or is
       false, a	typed Control-C	will be	entered	into the input buffer just as
       any other character. In that case, there	is no way from the keyboard to
       terminate the program while it is waiting for input. (That is to	say,
       the normal ability to generate signals from the keyboard	is suspended
       during the call to read_password.)

       If the input operation terminates early (either because the
       idle_timeout was	exceeded, or because a Control-C was enabled and
       typed), the return value	will be	"undef". In either case, there is no
       way provided to discover	what (if anything) was typed before the	early
       termination, or why the input operation was terminated.

       So as to	discourage users from typing their passwords anywhere except
       at the prompt, any input	which has been "typed ahead" before the	prompt
       appears will be discarded. And whether the input	operation terminates
       normally	or not,	a newline character will be printed, so	that the
       cursor will not remain on the line after	the prompt.

BUGS
       Windows users will want Term::ReadPassword::Win32.

       This module has a poorly-designed interface, and	should be thoroughly
       rethought and probably re-united	with the Windows version.

       Users who wish to see password characters echoed	as stars may set
       $Term::ReadPassword::USE_STARS to a true	value. The bugs	are that some
       terminals may not erase stars when the user corrects an error, and that
       using stars leaks information to	shoulder-surfers.

SECURITY
       You would think that a module dealing with passwords would be full of
       security	features. You'd	think that, but	you'd be wrong.	For example,
       perl provides no	way to erase a piece of	data from memory. (It's	easy
       to erase	it so that it can't be accessed	from perl, but that's not the
       same thing as expunging it from the actual memory.) If you've entered a
       password, even if the variable that contained that password has been
       erased, it may be possible for someone to find that password, in
       plaintext, in a core dump. And that's just one potential	security hole.

       In short, if serious security is	an issue, don't	use this module.

LICENSE
       This program is free software; you may redistribute it, modify it, or
       both, under the same terms as Perl itself.

AUTHOR
       Tom Phoenix <rootbeer@redcat.com>. Copyright (C)	2007 Tom Phoenix.

SEE ALSO
       Term::ReadLine, "crypt" in perlfunc, and	your system's manpages for the
       low-level I/O operations	used here.

perl v5.32.0			  2007-12-14		       ReadPassword(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | SECURITY | LICENSE | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::ReadPassword&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help