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