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