1ReadPassword(3)       User Contributed Perl Documentation      ReadPassword(3)
2
3
4

NAME

6       Term::ReadPassword - Asking the user for a password
7

SYNOPSIS

9         use Term::ReadPassword;
10         while (1) {
11           my $password = read_password('password: ');
12           redo unless defined $password;
13           if ($password eq 'flubber') {
14             print "Access granted.\n";
15             last;
16           } else {
17             print "Access denied.\n";
18             redo;
19           }
20         }
21

DESCRIPTION

23       This module lets you ask the user for a password in the traditional
24       way, from the keyboard, without echoing.
25
26       This is not intended for use over the web; user authentication over the
27       web is another matter entirely. Also, this module should generally be
28       used in conjunction with Perl's crypt() function, sold separately.
29
30       The read_password function prompts for input, reads a line of text from
31       the keyboard, then returns that line to the caller. The line of text
32       doesn't include the newline character, so there's no need to use chomp.
33
34       While the user is entering the text, a few special characters are
35       processed.  The character delete (or the character backspace) will back
36       up one character, removing the last character in the input buffer (if
37       any). The character CR (or the character LF) will signal the end of
38       input, causing the accumulated input buffer to be returned. Control-U
39       will empty the input buffer. And, optionally, the character Control-C
40       may be used to terminate the input operation. (See details below.) All
41       other characters, even ones which would normally have special purposes,
42       will be added to the input buffer.
43
44       It is not recommended, though, that you use the as-yet-unspecified
45       control characters in your passwords, as those characters may become
46       meaningful in a future version of this module. Applications which allow
47       the user to set their own passwords may wish to enforce this rule,
48       perhaps with code something like this:
49
50           {
51             # Naked block for scoping and redo
52             my $new_pw = read_password("Enter your new password: ");
53             if ($new_pw =~ /([^\x20-\x7E])/) {
54               my $bad = unpack "H*", $1;
55               print "Your password may not contain the ";
56               print "character with hex code $bad.\n";
57               redo;
58             } elsif (length($new_pw) < 5) {
59               print "Your password must be longer than that!\n";
60               redo;
61             } elsif ($new_pw ne read_password("Enter it again: ")) {
62               print "Passwords don't match.\n";
63               redo;
64             } else {
65               &change_password($new_pw);
66               print "Your password is now changed.\n";
67             }
68           }
69
70       The second parameter to read_password is the optional "idle_timeout"
71       value. If it is a non-zero number and there is no keyboard input for
72       that many seconds, the input operation will terminate. Notice that this
73       is not an overall time limit, as the timer is restarted with each new
74       character.
75
76       The third parameter will optionally allow the input operation to be
77       terminated by the user with Control-C. If this is not supplied, or is
78       false, a typed Control-C will be entered into the input buffer just as
79       any other character. In that case, there is no way from the keyboard to
80       terminate the program while it is waiting for input. (That is to say,
81       the normal ability to generate signals from the keyboard is suspended
82       during the call to read_password.)
83
84       If the input operation terminates early (either because the
85       idle_timeout was exceeded, or because a Control-C was enabled and
86       typed), the return value will be "undef". In either case, there is no
87       way provided to discover what (if anything) was typed before the early
88       termination, or why the input operation was terminated.
89
90       So as to discourage users from typing their passwords anywhere except
91       at the prompt, any input which has been "typed ahead" before the prompt
92       appears will be discarded. And whether the input operation terminates
93       normally or not, a newline character will be printed, so that the
94       cursor will not remain on the line after the prompt.
95

BUGS

97       Windows users will want Term::ReadPassword::Win32.
98
99       This module has a poorly-designed interface, and should be thoroughly
100       rethought and probably re-united with the Windows version.
101
102       Users who wish to see password characters echoed as stars may set
103       $Term::ReadPassword::USE_STARS to a true value. The bugs are that some
104       terminals may not erase stars when the user corrects an error, and that
105       using stars leaks information to shoulder-surfers.
106

SECURITY

108       You would think that a module dealing with passwords would be full of
109       security features. You'd think that, but you'd be wrong. For example,
110       perl provides no way to erase a piece of data from memory. (It's easy
111       to erase it so that it can't be accessed from perl, but that's not the
112       same thing as expunging it from the actual memory.) If you've entered a
113       password, even if the variable that contained that password has been
114       erased, it may be possible for someone to find that password, in
115       plaintext, in a core dump. And that's just one potential security hole.
116
117       In short, if serious security is an issue, don't use this module.
118

LICENSE

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

AUTHOR

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

SEE ALSO

127       Term::ReadLine, "crypt" in perlfunc, and your system's manpages for the
128       low-level I/O operations used here.
129
130
131
132perl v5.32.1                      2021-01-27                   ReadPassword(3)
Impressum