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