gen/FreeBSD/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$
  22 .\"
  23 .Dd May 31, 2007
  24 .Dt READPASSPHRASE 3
  25 .Os
  26 .Sh NAME
  27 .Nm readpassphrase
  28 .Nd get a passphrase from the user
  29 .Sh SYNOPSIS
  30 .In readpassphrase.h
  31 .Ft "char *"
  32 .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
  33 .Sh DESCRIPTION
  34 The
  35 .Fn readpassphrase
  36 function displays a prompt to, and reads in a passphrase from,
  37 .Pa /dev/tty .
  38 If this file is inaccessible
  39 and the
  40 .Dv RPP_REQUIRE_TTY
  41 flag is not set,
  42 .Fn readpassphrase
  43 displays the prompt on the standard error output and reads from the standard
  44 input.
  45 In this case it is generally not possible to turn off echo.
  46 .Pp
  47 Up to
  48 .Fa bufsiz
  49 \- 1 characters (one is for the
  50 .Dv NUL )
  51 are read into the provided buffer
  52 .Fa buf .
  53 Any additional
  54 characters and the terminating newline (or return) character are discarded.
  55 .Pp
  56 The
  57 .Fn readpassphrase
  58 function
  59 takes the following optional
  60 .Fa flags :
  61 .Pp
  62 .Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact
  63 .It Dv RPP_ECHO_OFF
  64 turn off echo (default behavior)
  65 .It Dv RPP_ECHO_ON
  66 leave echo on
  67 .It Dv RPP_REQUIRE_TTY
  68 fail if there is no tty
  69 .It Dv RPP_FORCELOWER
  70 force input to lower case
  71 .It Dv RPP_FORCEUPPER
  72 force input to upper case
  73 .It Dv RPP_SEVENBIT
  74 strip the high bit from input
  75 .It Dv RPP_STDIN
  76 force read of passphrase from stdin
  77 .El
  78 .Pp
  79 The calling process should zero the passphrase as soon as possible to
  80 avoid leaving the cleartext passphrase visible in the process's address
  81 space.
  82 .Sh RETURN VALUES
  83 Upon successful completion,
  84 .Fn readpassphrase
  85 returns a pointer to the NUL-terminated passphrase.
  86 If an error is encountered, the terminal state is restored and
  87 a
  88 .Dv NULL
  89 pointer is returned.
  90 .Sh FILES
  91 .Bl -tag -width ".Pa /dev/tty" -compact
  92 .It Pa /dev/tty
  93 .El
  94 .Sh EXAMPLES
  95 The following code fragment will read a passphrase from
  96 .Pa /dev/tty
  97 into the buffer
  98 .Fa passbuf .
  99 .Bd -literal -offset indent
 100 char passbuf[1024];
 101
 102 \&...
 103
 104 if (readpassphrase("Response: ", passbuf, sizeof(passbuf),
 105     RPP_REQUIRE_TTY) == NULL)
 106         errx(1, "unable to read passphrase");
 107
 108 if (compare(transform(passbuf), epass) != 0)
 109         errx(1, "bad passphrase");
 110
 111 \&...
 112
 113 memset(passbuf, 0, sizeof(passbuf));
 114 .Ed
 115 .Sh ERRORS
 116 .Bl -tag -width Er
 117 .It Bq Er EINTR
 118 The
 119 .Fn readpassphrase
 120 function was interrupted by a signal.
 121 .It Bq Er EINVAL
 122 The
 123 .Ar bufsiz
 124 argument was zero.
 125 .It Bq Er EIO
 126 The process is a member of a background process attempting to read
 127 from its controlling terminal, the process is ignoring or blocking
 128 the
 129 .Dv SIGTTIN
 130 signal, or the process group is orphaned.
 131 .It Bq Er EMFILE
 132 The process has already reached its limit for open file descriptors.
 133 .It Bq Er ENFILE
 134 The system file table is full.
 135 .It Bq Er ENOTTY
 136 There is no controlling terminal and the
 137 .Dv RPP_REQUIRE_TTY
 138 flag was specified.
 139 .El
 140 .Sh SIGNALS
 141 The
 142 .Fn readpassphrase
 143 function
 144 will catch the following signals:
 145 .Bd -literal -offset indent
 146 SIGALRM         SIGHUP          SIGINT
 147 SIGPIPE         SIGQUIT         SIGTERM
 148 SIGTSTP         SIGTTIN         SIGTTOU
 149 .Ed
 150 .Pp
 151 When one of the above signals is intercepted, terminal echo will
 152 be restored if it had previously been turned off.
 153 If a signal handler was installed for the signal when
 154 .Fn readpassphrase
 155 was called, that handler is then executed.
 156 If no handler was previously installed for the signal then the
 157 default action is taken as per
 158 .Xr sigaction 2 .
 159 .Pp
 160 The
 161 .Dv SIGTSTP , SIGTTIN
 162 and
 163 .Dv SIGTTOU
 164 signals (stop signals generated from keyboard or due to terminal I/O
 165 from a background process) are treated specially.
 166 When the process is resumed after it has been stopped,
 167 .Fn readpassphrase
 168 will reprint the prompt and the user may then enter a passphrase.
 169 .Sh SEE ALSO
 170 .Xr sigaction 2 ,
 171 .Xr getpass 3
 172 .Sh STANDARDS
 173 The
 174 .Fn readpassphrase
 175 function is an
 176 extension and should not be used if portability is desired.
 177 .Sh HISTORY
 178 The
 179 .Fn readpassphrase
 180 function first appeared in
 181 .Ox 2.9 .
 182 .Dv RPP_STDIN
 183 was introduced in OS X 10.12.