1.\" $OpenBSD: readpassphrase.3,v 1.14 2004/04/16 10:48:39 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 June 28, 2002 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 null-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 SIGTTIN signal or the process group is orphaned. 113.It Bq Er EMFILE 114The process has already reached its limit for open file descriptors. 115.It Bq Er ENFILE 116The system file table is full. 117.It Bq Er ENOTTY 118There is no controlling terminal and the 119.Dv RPP_REQUIRE_TTY 120flag was specified. 121.El 122.Sh SIGNALS 123.Fn readpassphrase 124will catch the following signals: 125.Bd -literal -offset indent 126SIGALRM 127SIGHUP 128SIGINT 129SIGPIPE 130SIGQUIT 131SIGTERM 132SIGTSTP 133SIGTTIN 134SIGTTOU 135.Ed 136.Pp 137When one of the above signals is intercepted, terminal echo will 138be restored if it had previously been turned off. 139If a signal handler was installed for the signal when 140.Fn readpassphrase 141was called that handler is then executed. 142If no handler was previously installed for the signal then the 143default action is taken as per 144.Xr sigaction 2 . 145.Pp 146The 147.Dv SIGTSTP , 148.Dv SIGTTIN 149and 150.Dv SIGTTOU 151signals (stop signals generated from keyboard or due to terminal I/O 152from a background process) are treated specially. 153When the process is resumed after it has been stopped, 154.Fn readpassphrase 155will reprint the prompt and the user may then enter a passphrase. 156.Sh SEE ALSO 157.Xr sigaction 2 , 158.Xr getpass 3 159.Sh STANDARDS 160The 161.Fn readpassphrase 162function is an 163.Ox 164extension and should not be used if portability is desired. 165.Sh HISTORY 166The 167.Fn readpassphrase 168function first appeared in 169.Ox 2.9 . 170