git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

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