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