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