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