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