1.\" $NetBSD: getpass.3,v 1.22 2012/04/14 10:34:29 wiz Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)getpass.3 8.1 (Berkeley) 6/4/93 31.\" 32.Dd April 13, 2012 33.Dt GETPASS 3 34.Os 35.Sh NAME 36.Nm getpass 37.Nd get a password 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.Ft char * 43.Fn getpass "const char *prompt" 44.Ft char * 45.Fn getpass_r "const char *prompt" "char *buf" "size_t buflen" 46.Ft char * 47.Fn getpassfd "const char *prompt" "char *buf" "size_t buflen" "int *fd" "int flags" "int timeout" 48.Sh DESCRIPTION 49The 50.Fn getpass 51function displays a prompt to, and reads in a password from, 52.Pa /dev/tty . 53If this file is not accessible, 54.Fn getpass 55displays the prompt on the standard error output and reads from the standard 56input. 57.Pp 58The password may be up to 59.Xr sysconf 3 60.Dv _SC_PASS_MAX 61characters in length. 62Any additional 63characters and the terminating newline character are discarded. 64.Pp 65.Fn getpass 66turns off character echoing while reading the password. 67.Pp 68.Fn getpass_r 69is similar to 70.Fn getpass 71only it puts its result in 72.Fa buf 73for up to 74.Fa buflen 75characters. 76If the 77.Fa buf 78argument is 79.Dv NULL , 80then a buffer will be dynamically allocated. 81.Pp 82The 83.Fn getpassfd 84function allows one to specify the three file descriptors corresponding to 85.Dv stdin , 86.Dv stdout , 87and 88.Dv stderr 89in the 90.Fa fd 91argument, or if 92.Fa fd 93is 94.Dv NULL , 95.Fn getpassfd 96first attempts to open 97.Pa /dev/tty 98and if that fails, defaults to 99.Dv STDIN_FILENO 100for input and 101.Dv STDERR_FILENO 102for output. 103.Pp 104The behavior of 105.Fn getpassfd 106is controlled by the 107.Fa flags 108argument: 109.Bl -tag -width GETPASS_FORCE_UPPER 110.It Dv GETPASS_NEED_TTY 111Fail if we are unable to set the tty modes like we want. 112.It Dv GETPASS_FAIL_EOF 113Fail if we get the end-of-file character instead of returning the result so far. 114.It Dv GETPASS_BUF_LIMIT 115Beep when the buffer limit is reached, instead of silently absorbing it. 116.It Dv GETPASS_NO_SIGNAL 117Don't make ttychars send signals. 118.It Dv GETPASS_NO_BEEP 119Don't beep if we erase past the beginning of the buffer or we try to enter past 120the end. 121.It Dv GETPASS_ECHO_STAR 122Echo a 123.Sq * 124for each character entered. 125.It Dv GETPASS_ECHO 126Echo characters as they are typed. 127.It Dv GETPASS_ECHO_NL 128Echoes a newline if successful. 129.It Dv GETPASS_7BIT 130Mask the high bit for each entered character. 131.It Dv GETPASS_FORCE_LOWER 132Lowercase each entered character. 133.It Dv GETPASS_FORCE_UPPER 134Uppercase each entered character. 135.El 136.Pp 137Finally if the 138.Fa timeout 139argument is non zero, 140.Fn getpassfd 141will wait for 142.Fa timeout 143seconds for input after each character before returning an error, instead of 144waiting forever. 145.Sh RETURN VALUES 146The 147.Fn getpass 148function returns a pointer to the NUL terminated password, or an empty 149string on error. 150The 151.Fn getpass_r 152and 153.Fn getpassfd 154functions return a pointer to the NUL terminated password, or 155.Dv NULL 156on error. 157.Sh FILES 158.Bl -tag -width /dev/tty -compact 159.It Pa /dev/tty 160.El 161.Sh SEE ALSO 162.Xr crypt 3 163.Sh STANDARDS 164The 165.Fn getpass 166function appeared in 167.St -susv2 , 168but it was already marked as legacy. 169The function was removed in the 170.St -p1003.1-2001 171standard. 172.Sh HISTORY 173A 174.Fn getpass 175function appeared in 176.At v7 . 177The 178.Fn getpass_r 179and 180.Fn getpassfd 181functions appeared in 182.Nx 7.0 . 183.Sh BUGS 184The 185.Fn getpass 186function leaves its result in an internal static object and returns 187a pointer to that object. 188Subsequent calls to 189.Fn getpass 190will modify the same object. 191.Sh SECURITY CONSIDERATIONS 192The calling process should zero the password as soon as possible to 193avoid leaving the cleartext password visible in the process's address 194space. 195.Pp 196Historically 197.Nm 198accepted and returned a password if it could not modify the terminal 199settings to turn echo off (or if the input was not a terminal). 200In this implementation, only terminal input is accepted. 201