1.\" $NetBSD: getpass.3,v 1.23 2017/10/24 18:50:46 abhinav 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.Nm getpass_r , 38.Nm getpassfd 39.Nd get a password 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In unistd.h 44.Ft char * 45.Fn getpass "const char *prompt" 46.Ft char * 47.Fn getpass_r "const char *prompt" "char *buf" "size_t buflen" 48.Ft char * 49.Fn getpassfd "const char *prompt" "char *buf" "size_t buflen" "int *fd" "int flags" "int timeout" 50.Sh DESCRIPTION 51The 52.Fn getpass 53function displays a prompt to, and reads in a password from, 54.Pa /dev/tty . 55If this file is not accessible, 56.Fn getpass 57displays the prompt on the standard error output and reads from the standard 58input. 59.Pp 60The password may be up to 61.Xr sysconf 3 62.Dv _SC_PASS_MAX 63characters in length. 64Any additional 65characters and the terminating newline character are discarded. 66.Pp 67.Fn getpass 68turns off character echoing while reading the password. 69.Pp 70.Fn getpass_r 71is similar to 72.Fn getpass 73only it puts its result in 74.Fa buf 75for up to 76.Fa buflen 77characters. 78If the 79.Fa buf 80argument is 81.Dv NULL , 82then a buffer will be dynamically allocated. 83.Pp 84The 85.Fn getpassfd 86function allows one to specify the three file descriptors corresponding to 87.Dv stdin , 88.Dv stdout , 89and 90.Dv stderr 91in the 92.Fa fd 93argument, or if 94.Fa fd 95is 96.Dv NULL , 97.Fn getpassfd 98first attempts to open 99.Pa /dev/tty 100and if that fails, defaults to 101.Dv STDIN_FILENO 102for input and 103.Dv STDERR_FILENO 104for output. 105.Pp 106The behavior of 107.Fn getpassfd 108is controlled by the 109.Fa flags 110argument: 111.Bl -tag -width GETPASS_FORCE_UPPER 112.It Dv GETPASS_NEED_TTY 113Fail if we are unable to set the tty modes like we want. 114.It Dv GETPASS_FAIL_EOF 115Fail if we get the end-of-file character instead of returning the result so far. 116.It Dv GETPASS_BUF_LIMIT 117Beep when the buffer limit is reached, instead of silently absorbing it. 118.It Dv GETPASS_NO_SIGNAL 119Don't make ttychars send signals. 120.It Dv GETPASS_NO_BEEP 121Don't beep if we erase past the beginning of the buffer or we try to enter past 122the end. 123.It Dv GETPASS_ECHO_STAR 124Echo a 125.Sq * 126for each character entered. 127.It Dv GETPASS_ECHO 128Echo characters as they are typed. 129.It Dv GETPASS_ECHO_NL 130Echoes a newline if successful. 131.It Dv GETPASS_7BIT 132Mask the high bit for each entered character. 133.It Dv GETPASS_FORCE_LOWER 134Lowercase each entered character. 135.It Dv GETPASS_FORCE_UPPER 136Uppercase each entered character. 137.El 138.Pp 139Finally if the 140.Fa timeout 141argument is non zero, 142.Fn getpassfd 143will wait for 144.Fa timeout 145seconds for input after each character before returning an error, instead of 146waiting forever. 147.Sh RETURN VALUES 148The 149.Fn getpass 150function returns a pointer to the NUL terminated password, or an empty 151string on error. 152The 153.Fn getpass_r 154and 155.Fn getpassfd 156functions return a pointer to the NUL terminated password, or 157.Dv NULL 158on error. 159.Sh FILES 160.Bl -tag -width /dev/tty -compact 161.It Pa /dev/tty 162.El 163.Sh SEE ALSO 164.Xr crypt 3 165.Sh STANDARDS 166The 167.Fn getpass 168function appeared in 169.St -susv2 , 170but it was already marked as legacy. 171The function was removed in the 172.St -p1003.1-2001 173standard. 174.Sh HISTORY 175A 176.Fn getpass 177function appeared in 178.At v7 . 179The 180.Fn getpass_r 181and 182.Fn getpassfd 183functions appeared in 184.Nx 7.0 . 185.Sh BUGS 186The 187.Fn getpass 188function leaves its result in an internal static object and returns 189a pointer to that object. 190Subsequent calls to 191.Fn getpass 192will modify the same object. 193.Sh SECURITY CONSIDERATIONS 194The calling process should zero the password as soon as possible to 195avoid leaving the cleartext password visible in the process's address 196space. 197.Pp 198Historically 199.Nm 200accepted and returned a password if it could not modify the terminal 201settings to turn echo off (or if the input was not a terminal). 202In this implementation, only terminal input is accepted. 203