1.\" $OpenBSD: readpassphrase.3,v 1.7 2001/12/15 15:37:51 millert Exp $ 2.\" 3.\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 18.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 19.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 20.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 21.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 22.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 23.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 25.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 26.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/lib/libc/gen/readpassphrase.3,v 1.4.2.3 2003/03/15 15:11:05 trhodes Exp $ 29.\" 30.Dd December 7, 2001 31.Dt READPASSPHRASE 3 32.Os 33.Sh NAME 34.Nm readpassphrase 35.Nd get a passphrase from the user 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/types.h 40.In readpassphrase.h 41.Ft "char *" 42.Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags" 43.Sh DESCRIPTION 44The 45.Fn readpassphrase 46function displays a prompt to, and reads in a passphrase from, 47.Pa /dev/tty . 48If this file is inaccessible 49and the 50.Dv RPP_REQUIRE_TTY 51flag is not set, 52.Fn readpassphrase 53displays the prompt on the standard error output and reads from the standard 54input. 55In this case it is generally not possible to turn off echo. 56.Pp 57Up to 58.Fa bufsiz 59\- 1 characters (one is for the 60.Dv NUL ) 61are read into the provided buffer 62.Fa buf . 63Any additional 64characters and the terminating newline (or return) character are discarded. 65.Pp 66The 67.Fn readpassphrase 68function 69takes the following optional 70.Fa flags : 71.Pp 72.Bl -tag -width ".Dv RPP_REQUIRE_TTY" -compact 73.It Dv RPP_ECHO_OFF 74turn off echo (default behavior) 75.It Dv RPP_ECHO_ON 76leave echo on 77.It Dv RPP_REQUIRE_TTY 78fail if there is no tty 79.It Dv RPP_FORCELOWER 80force input to lower case 81.It Dv RPP_FORCEUPPER 82force input to upper case 83.It Dv RPP_SEVENBIT 84strip the high bit from input 85.El 86.Pp 87The calling process should zero the passphrase as soon as possible to 88avoid leaving the cleartext passphrase visible in the process's address 89space. 90.Sh RETURN VALUES 91Upon successful completion, 92.Fn readpassphrase 93returns a pointer to the null-terminated passphrase. 94If an error is encountered, the terminal state is restored and 95a 96.Dv NULL 97pointer is returned. 98.Sh FILES 99.Bl -tag -width ".Pa /dev/tty" -compact 100.It Pa /dev/tty 101.El 102.Sh EXAMPLES 103The following code fragment will read a passphrase from 104.Pa /dev/tty 105into the buffer 106.Fa passbuf . 107.Bd -literal -offset indent 108char passbuf[1024]; 109 110\&... 111 112if (readpassphrase("Response: ", passbuf, sizeof(passbuf), 113 RPP_REQUIRE_TTY) == NULL) 114 errx(1, "unable to read passphrase"); 115 116if (compare(transform(passbuf), epass) != 0) 117 errx(1, "bad passphrase"); 118 119\&... 120 121memset(passbuf, 0, sizeof(passbuf)); 122.Ed 123.Sh ERRORS 124.Bl -tag -width Er 125.It Bq Er EINTR 126The 127.Fn readpassphrase 128function was interrupted by a signal. 129.It Bq Er EINVAL 130The 131.Fa bufsiz 132argument was zero. 133.It Bq Er EIO 134The process is a member of a background process attempting to read 135from its controlling terminal, the process is ignoring or blocking 136the 137.Dv SIGTTIN 138signal or the process group is orphaned. 139.It Bq Er EMFILE 140The process has already reached its limit for open file descriptors. 141.It Bq Er ENFILE 142The system file table is full. 143.It Bq Er ENOTTY 144There is no controlling terminal and the 145.Dv RPP_REQUIRE_TTY 146flag was specified. 147.El 148.Sh SIGNALS 149The 150.Fn readpassphrase 151function 152will catch the following signals: 153.Pp 154.Bl -tag -compact -width ".Dv SIGQUIT" 155.It Dv SIGINT 156.It Dv SIGHUP 157.It Dv SIGQUIT 158.It Dv SIGTERM 159.It Dv SIGTSTP 160.It Dv SIGTTIN 161.It Dv SIGTTOU 162.El 163.Pp 164When one of the above signals is intercepted, terminal echo will 165be restored if it had previously been turned off. 166If a signal handler was installed for the signal when 167.Fn readpassphrase 168was called that handler is then executed. 169If no handler was previously installed for the signal then the 170default action is taken as per 171.Xr sigaction 2 . 172.Pp 173The 174.Dv SIGTSTP , SIGTTIN , 175and 176.Dv SIGTTOU 177signals (stop signal generated from keyboard or due to terminal I/O 178from a background process) are treated specially. 179When the process is resumed after it has been stopped, 180.Fn readpassphrase 181will reprint the prompt and the user may then enter a passphrase. 182.Sh SEE ALSO 183.Xr sigaction 2 , 184.Xr getpass 3 185.Sh STANDARDS 186The 187.Fn readpassphrase 188function is an 189extension and should not be used if portability is desired. 190.Sh HISTORY 191The 192.Fn readpassphrase 193function first appeared in 194.Ox 2.9 . 195