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