gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 2001 Mark R V Murray
	2	.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
	3	.\" Copyright (c) 2004-2011 Dag-Erling Smørgrav
	4	.\" All rights reserved.
	5	.\"
	6	.\" This software was developed for the FreeBSD Project by ThinkSec AS and
	7	.\" NAI Labs, the Security Research Division of Network Associates, Inc.
	8	.\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
	9	.\" DARPA CHATS research program.
	10	.\"
	11	.\" Redistribution and use in source and binary forms, with or without
	12	.\" modification, are permitted provided that the following conditions
	13	.\" are met:
	14	.\" 1. Redistributions of source code must retain the above copyright
	15	.\" notice, this list of conditions and the following disclaimer.
	16	.\" 2. Redistributions in binary form must reproduce the above copyright
	17	.\" notice, this list of conditions and the following disclaimer in the
	18	.\" documentation and/or other materials provided with the distribution.
	19	.\" 3. The name of the author may not be used to endorse or promote
	20	.\" products derived from this software without specific prior written
	21	.\" permission.
	22	.\"
	23	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	24	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	25	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	26	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	27	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	28	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	29	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	30	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	31	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	32	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	33	.\" SUCH DAMAGE.
	34	.\"
	35	.\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.15 2011/10/07 12:58:33 des Exp $
	36	.\"
	37	.Dd December 24, 2011
	38	.Dt PAM_SSH 8
	39	.Os
	40	.Sh NAME
	41	.Nm pam_ssh
	42	.Nd authentication and session management with SSH private keys
	43	.Sh SYNOPSIS
	44	.Op Ar service-name
	45	.Ar module-type
	46	.Ar control-flag
	47	.Pa pam_ssh
	48	.Op Ar options
	49	.Sh DESCRIPTION
	50	The
	51	SSH
	52	authentication service module for PAM,
	53	.Nm
	54	provides functionality for two PAM categories:
	55	authentication
	56	and session management.
	57	In terms of the
	58	.Ar module-type
	59	parameter, they are the
	60	.Dq Li auth
	61	and
	62	.Dq Li session
	63	features.
	64	.Ss SSH Authentication Module
	65	The
	66	SSH
	67	authentication component
	68	provides a function to verify the identity of a user
	69	.Pq Fn pam_sm_authenticate ,
	70	by prompting the user for a passphrase and verifying that it can
	71	decrypt the target user's SSH key using that passphrase.
	72	.Pp
	73	The following options may be passed to the authentication module:
	74	.Bl -tag -width ".Cm use_first_pass"
	75	.It Cm use_first_pass
	76	If the authentication module
	77	is not the first in the stack,
	78	and a previous module
	79	obtained the user's password,
	80	that password is used
	81	to authenticate the user.
	82	If this fails,
	83	the authentication module returns failure
	84	without prompting the user for a password.
	85	This option has no effect
	86	if the authentication module
	87	is the first in the stack,
	88	or if no previous modules
	89	obtained the user's password.
	90	.It Cm try_first_pass
	91	This option is similar to the
	92	.Cm use_first_pass
	93	option,
	94	except that if the previously obtained password fails,
	95	the user is prompted for another password.
	96	.It Cm nullok
	97	Normally, keys with no passphrase are ignored for authentication
	98	purposes.
	99	If this option is set, keys with no passphrase will be taken into
	100	consideration, allowing the user to log in with a blank password.
	101	.El
	102	.Ss SSH Session Management Module
	103	The
	104	SSH
	105	session management component
	106	provides functions to initiate
	107	.Pq Fn pam_sm_open_session
	108	and terminate
	109	.Pq Fn pam_sm_close_session
	110	sessions.
	111	The
	112	.Fn pam_sm_open_session
	113	function starts an SSH agent,
	114	passing it any private keys it decrypted
	115	during the authentication phase,
	116	and sets the environment variables
	117	the agent specifies.
	118	The
	119	.Fn pam_sm_close_session
	120	function kills the previously started SSH agent
	121	by sending it a
	122	.Dv SIGTERM .
	123	.Pp
	124	The following options may be passed to the session management module:
	125	.Bl -tag -width ".Cm want_agent"
	126	.It Cm want_agent
	127	Start an agent even if no keys were decrypted during the
	128	authentication phase.
	129	.El
	130	.Sh FILES
	131	.Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
	132	.It Pa $HOME/.ssh/identity
	133	SSH1 RSA key
	134	.It Pa $HOME/.ssh/id_rsa
	135	SSH2 RSA key
	136	.It Pa $HOME/.ssh/id_dsa
	137	SSH2 DSA key
	138	.It Pa $HOME/.ssh/id_ecdsa
	139	SSH2 ECDSA key
	140	.El
	141	.Sh SEE ALSO
	142	.Xr ssh-agent 1 ,
	143	.Xr pam.conf 5 ,
	144	.Xr pam 8
	145	.Sh AUTHORS
	146	.An -nosplit
	147	The
	148	.Nm
	149	module was originally written by
	150	.An Andrew J. Korty Aq Mt ajk@iu.edu .
	151	The current implementation was developed for the
	152	.Fx
	153	Project by
	154	ThinkSec AS and NAI Labs, the Security Research Division of Network
	155	Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
	156	.Pq Dq CBOSS ,
	157	as part of the DARPA CHATS research program.
	158	This manual page was written by
	159	.An Mark R V Murray Aq Mt markm@FreeBSD.org .