lib/libc/gen/readpassphrase.3

   1 .\"     $OpenBSD: readpassphrase.3,v 1.17 2007/05/31 19:19:28 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2000, 2002 Todd C. Miller <Todd.Miller@courtesan.com>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" Sponsored in part by the Defense Advanced Research Projects
  18 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
  19 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
  20 .\"
  21 .\" $FreeBSD: head/lib/libc/gen/readpassphrase.3 215236 2010-11-13 10:38:06Z delphij $
  22 .\"
  23 .Dd August 21, 2016
  24 .Dt READPASSPHRASE 3
  25 .Os
  26 .Sh NAME
  27 .Nm readpassphrase
  28 .Nd get a passphrase from the user
  29 .Sh LIBRARY
  30 .Lb libc
  31 .Sh SYNOPSIS
  32 .In sys/types.h
  33 .In readpassphrase.h
  34 .Ft "char *"
  35 .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
  36 .Sh DESCRIPTION
  37 The
  38 .Fn readpassphrase
  39 function displays a prompt to, and reads in a passphrase from,
  40 .Pa /dev/tty .
  41 If this file is inaccessible
  42 and the
  43 .Dv RPP_REQUIRE_TTY
  44 flag is not set,
  45 .Fn readpassphrase
  46 displays the prompt on the standard error output and reads from the standard
  47 input.
  48 In this case it is generally not possible to turn off echo.
  49 .Pp
  50 Up to
  51 .Fa bufsiz
  52 \- 1 characters (one is for the
  53 .Dv NUL )
  54 are read into the provided buffer
  55 .Fa buf .
  56 Any additional
  57 characters and the terminating newline (or return) character are discarded.
  58 .Pp
  59 The
  60 .Fn readpassphrase
  61 function
  62 takes the following optional
  63 .Fa flags :
  64 .Pp
  65 .Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact
  66 .It Dv RPP_ECHO_OFF
  67 turn off echo (default behavior)
  68 .It Dv RPP_ECHO_ON
  69 leave echo on
  70 .It Dv RPP_REQUIRE_TTY
  71 fail if there is no tty
  72 .It Dv RPP_FORCELOWER
  73 force input to lower case
  74 .It Dv RPP_FORCEUPPER
  75 force input to upper case
  76 .It Dv RPP_SEVENBIT
  77 strip the high bit from input
  78 .It Dv RPP_STDIN
  79 force read of passphrase from stdin
  80 .El
  81 .Pp
  82 The calling process should zero the passphrase as soon as possible to
  83 avoid leaving the cleartext passphrase visible in the process's address
  84 space.
  85 .Sh RETURN VALUES
  86 Upon successful completion,
  87 .Fn readpassphrase
  88 returns a pointer to the null-terminated passphrase.
  89 If an error is encountered, the terminal state is restored and
  90 a
  91 .Dv NULL
  92 pointer is returned.
  93 .Sh FILES
  94 .Bl -tag -width ".Pa /dev/tty" -compact
  95 .It Pa /dev/tty
  96 .El
  97 .Sh EXAMPLES
  98 The following code fragment will read a passphrase from
  99 .Pa /dev/tty
 100 into the buffer
 101 .Fa passbuf .
 102 .Bd -literal -offset indent
 103 char passbuf[1024];
 104
 105 \&...
 106
 107 if (readpassphrase("Response: ", passbuf, sizeof(passbuf),
 108     RPP_REQUIRE_TTY) == NULL)
 109         errx(1, "unable to read passphrase");
 110
 111 if (compare(transform(passbuf), epass) != 0)
 112         errx(1, "bad passphrase");
 113
 114 \&...
 115
 116 memset(passbuf, 0, sizeof(passbuf));
 117 .Ed
 118 .Sh ERRORS
 119 .Bl -tag -width Er
 120 .It Bq Er EINTR
 121 The
 122 .Fn readpassphrase
 123 function was interrupted by a signal.
 124 .It Bq Er EINVAL
 125 The
 126 .Fa bufsiz
 127 argument was zero.
 128 .It Bq Er EIO
 129 The process is a member of a background process attempting to read
 130 from its controlling terminal, the process is ignoring or blocking
 131 the
 132 .Dv SIGTTIN
 133 signal or the process group is orphaned.
 134 .It Bq Er EMFILE
 135 The process has already reached its limit for open file descriptors.
 136 .It Bq Er ENFILE
 137 The system file table is full.
 138 .It Bq Er ENOTTY
 139 There is no controlling terminal and the
 140 .Dv RPP_REQUIRE_TTY
 141 flag was specified.
 142 .El
 143 .Sh SIGNALS
 144 The
 145 .Fn readpassphrase
 146 function
 147 will catch the following signals:
 148 .Pp
 149 .Bl -tag -compact -width ".Dv SIGQUIT"
 150 .It Dv SIGALRM
 151 .It Dv SIGHUP
 152 .It Dv SIGINT
 153 .It Dv SIGPIPE
 154 .It Dv SIGQUIT
 155 .It Dv SIGTERM
 156 .It Dv SIGTSTP
 157 .It Dv SIGTTIN
 158 .It Dv SIGTTOU
 159 .El
 160 .Pp
 161 When one of the above signals is intercepted, terminal echo will
 162 be restored if it had previously been turned off.
 163 If a signal handler was installed for the signal when
 164 .Fn readpassphrase
 165 was called that handler is then executed.
 166 If no handler was previously installed for the signal then the
 167 default action is taken as per
 168 .Xr sigaction 2 .
 169 .Pp
 170 The
 171 .Dv SIGTSTP , SIGTTIN ,
 172 and
 173 .Dv SIGTTOU
 174 signals (stop signal generated from keyboard or due to terminal I/O
 175 from a background process) are treated specially.
 176 When the process is resumed after it has been stopped,
 177 .Fn readpassphrase
 178 will reprint the prompt and the user may then enter a passphrase.
 179 .Sh SEE ALSO
 180 .Xr sigaction 2 ,
 181 .Xr getpass 3
 182 .Sh STANDARDS
 183 The
 184 .Fn readpassphrase
 185 function is an
 186 extension and should not be used if portability is desired.
 187 .Sh HISTORY
 188 The
 189 .Fn readpassphrase
 190 function first appeared in
 191 .Ox 2.9 .