lib/libc/gen/readpassphrase.3

   1 .\"     $OpenBSD: readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $
   2 .\"
   3 .\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com>
   4 .\" 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. The name of the author may not be used to endorse or promote products
  15 .\"    derived from this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  19 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  20 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  21 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  23 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  25 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  26 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/lib/libc/gen/readpassphrase.3,v 1.4.2.3 2003/03/15 15:11:05 trhodes Exp $
  29 .\" $DragonFly: src/lib/libc/gen/readpassphrase.3,v 1.5 2008/04/15 08:11:50 swildner Exp $
  30 .\"
  31 .Dd December 7, 2001
  32 .Dt READPASSPHRASE 3
  33 .Os
  34 .Sh NAME
  35 .Nm readpassphrase
  36 .Nd get a passphrase from the user
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In readpassphrase.h
  42 .Ft "char *"
  43 .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn readpassphrase
  47 function displays a prompt to, and reads in a passphrase from,
  48 .Pa /dev/tty .
  49 If this file is inaccessible
  50 and the
  51 .Dv RPP_REQUIRE_TTY
  52 flag is not set,
  53 .Fn readpassphrase
  54 displays the prompt on the standard error output and reads from the standard
  55 input.
  56 In this case it is generally not possible to turn off echo.
  57 .Pp
  58 Up to
  59 .Fa bufsiz
  60 \- 1 characters (one is for the
  61 .Dv NUL )
  62 are read into the provided buffer
  63 .Fa buf .
  64 Any additional
  65 characters and the terminating newline (or return) character are discarded.
  66 .Pp
  67 The
  68 .Fn readpassphrase
  69 function
  70 takes the following optional
  71 .Fa flags :
  72 .Pp
  73 .Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact
  74 .It Dv RPP_ECHO_OFF
  75 turn off echo (default behavior)
  76 .It Dv RPP_ECHO_ON
  77 leave echo on
  78 .It Dv RPP_REQUIRE_TTY
  79 fail if there is no tty
  80 .It Dv RPP_FORCELOWER
  81 force input to lower case
  82 .It Dv RPP_FORCEUPPER
  83 force input to upper case
  84 .It Dv RPP_SEVENBIT
  85 strip the high bit from input
  86 .El
  87 .Pp
  88 The calling process should zero the passphrase as soon as possible to
  89 avoid leaving the cleartext passphrase visible in the process's address
  90 space.
  91 .Sh RETURN VALUES
  92 Upon successful completion,
  93 .Fn readpassphrase
  94 returns a pointer to the null-terminated passphrase.
  95 If an error is encountered, the terminal state is restored and
  96 a
  97 .Dv NULL
  98 pointer is returned.
  99 .Sh FILES
 100 .Bl -tag -width ".Pa /dev/tty" -compact
 101 .It Pa /dev/tty
 102 .El
 103 .Sh EXAMPLES
 104 The following code fragment will read a passphrase from
 105 .Pa /dev/tty
 106 into the buffer
 107 .Fa passbuf .
 108 .Bd -literal -offset indent
 109 char passbuf[1024];
 110
 111 \&...
 112
 113 if (readpassphrase("Response: ", passbuf, sizeof(passbuf),
 114     RPP_REQUIRE_TTY) == NULL)
 115         errx(1, "unable to read passphrase");
 116
 117 if (compare(transform(passbuf), epass) != 0)
 118         errx(1, "bad passphrase");
 119
 120 \&...
 121
 122 memset(passbuf, 0, sizeof(passbuf));
 123 .Ed
 124 .Sh ERRORS
 125 .Bl -tag -width Er
 126 .It Bq Er EINTR
 127 The
 128 .Fn readpassphrase
 129 function was interrupted by a signal.
 130 .It Bq Er EINVAL
 131 The
 132 .Fa bufsiz
 133 argument was zero.
 134 .It Bq Er EIO
 135 The process is a member of a background process attempting to read
 136 from its controlling terminal, the process is ignoring or blocking
 137 the
 138 .Dv SIGTTIN
 139 signal or the process group is orphaned.
 140 .It Bq Er EMFILE
 141 The process has already reached its limit for open file descriptors.
 142 .It Bq Er ENFILE
 143 The system file table is full.
 144 .It Bq Er ENOTTY
 145 There is no controlling terminal and the
 146 .Dv RPP_REQUIRE_TTY
 147 flag was specified.
 148 .El
 149 .Sh SIGNALS
 150 The
 151 .Fn readpassphrase
 152 function
 153 will catch the following signals:
 154 .Pp
 155 .Bl -tag -compact
 156 .It Dv SIGINT
 157 .It Dv SIGHUP
 158 .It Dv SIGQUIT
 159 .It Dv SIGTERM
 160 .It Dv SIGTSTP
 161 .It Dv SIGTTIN
 162 .It Dv SIGTTOU
 163 .El
 164 .Pp
 165 When one of the above signals is intercepted, terminal echo will
 166 be restored if it had previously been turned off.
 167 If a signal handler was installed for the signal when
 168 .Fn readpassphrase
 169 was called that handler is then executed.
 170 If no handler was previously installed for the signal then the
 171 default action is taken as per
 172 .Xr sigaction 2 .
 173 .Pp
 174 The
 175 .Dv SIGTSTP , SIGTTIN ,
 176 and
 177 .Dv SIGTTOU
 178 signals (stop signal generated from keyboard or due to terminal I/O
 179 from a background process) are treated specially.
 180 When the process is resumed after it has been stopped,
 181 .Fn readpassphrase
 182 will reprint the prompt and the user may then enter a passphrase.
 183 .Sh SEE ALSO
 184 .Xr sigaction 2 ,
 185 .Xr getpass 3
 186 .Sh STANDARDS
 187 The
 188 .Fn readpassphrase
 189 function is an
 190 extension and should not be used if portability is desired.
 191 .Sh HISTORY
 192 The
 193 .Fn readpassphrase
 194 function first appeared in
 195 .Ox 2.9 .