lib/libc/gen/getpass.3

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