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