xref: /dragonfly/lib/libc/gen/readpassphrase.3 (revision 65cc0652) 
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