1.\" $OpenBSD: readpassphrase.3,v 1.3 2001/08/06 10:42:25 mpech Exp $ 2.\" $FreeBSD$ 3.\" 4.\" Copyright (c) 2000 Todd C. Miller <Todd.Miller@courtesan.com> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote products 16.\" derived from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 19.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 20.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 22.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 23.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 24.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 25.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 26.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 27.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd November 20, 2000 30.Dt READPASSPHRASE 3 31.Os 32.Sh NAME 33.Nm readpassphrase 34.Nd get a passphrase from the user 35.Sh SYNOPSIS 36.Fd #include <readpassphrase.h> 37.Ft char * 38.Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags" 39.Sh DESCRIPTION 40The 41.Fn readpassphrase 42function displays a prompt to, and reads in a passphrase from, 43.Pa /dev/tty . 44If this file is inaccessible 45and the 46.Dv RPP_REQUIRE_TTY 47flag is not set, 48.Fn readpassphrase 49displays the prompt on the standard error output and reads from the standard 50input. 51In this case it is generally not possible to turn off echo. 52.Pp 53Up to 54.Fa bufsiz 55- 1 characters (one is for the NUL) are read into the provided buffer 56.Fa buf . 57Any additional 58characters and the terminating newline (or return) character are discarded. 59.Pp 60.Fn readpassphrase 61takes the following optional 62.Fa flags : 63.Pp 64.Bd -literal -offset indent -compact 65RPP_ECHO_OFF turn off echo (default behavior) 66RPP_ECHO_ON leave echo on 67RPP_REQUIRE_TTY fail if there is no tty 68RPP_FORCELOWER force input to lower case 69RPP_FORCEUPPER force input to upper case 70RPP_SEVENBIT strip the high bit from input 71.Ed 72.Pp 73The calling process should zero the passphrase as soon as possible to 74avoid leaving the cleartext passphrase visible in the process's address 75space. 76.Sh RETURN VALUES 77On success, 78.Fn readpassphrase 79returns a pointer to the null-terminated passphrase. 80If the 81.Dv RPP_REQUIRE_TTY 82flag is set and 83.Pa /dev/tty 84is inaccessible, 85.Fn readpassphrase 86returns a null pointer. 87.Sh EXAMPLES 88The following code fragment will read a passphrase from 89.Pa /dev/tty 90into the buffer 91.Fa passbuf. 92.Bd -literal -offset indent 93char passbuf[1024]; 94 95\&... 96 97if (readpassphrase("Response: ", passbuf, sizeof(passbuf), 98 RPP_REQUIRE_TTY) == NULL) 99 errx(1, "unable to read passphrase"); 100 101if (compare(transform(passbuf), epass) != 0) 102 errx(1, "bad passphrase"); 103 104\&... 105 106memset(passbuf, 0, sizeof(passbuf)); 107.Ed 108.Sh FILES 109.Bl -tag -width /dev/tty -compact 110.It Pa /dev/tty 111.El 112.Sh SEE ALSO 113.Xr getpass 3 114.Sh HISTORY 115The 116.Fn readpassphrase 117function first appeared in 118.Ox 2.9 . 119