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

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 2001 Mark R V Murray
	2	.\" All rights reserved.
	3	.\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
	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.14 2005/09/22 05:35:24 des Exp $
	36	.\" $DragonFly: src/lib/pam_module/pam_ssh/pam_ssh.8,v 1.1 2005/07/12 23:26:49 joerg Exp $
	37	.\"
	38	.Dd November 26, 2001
	39	.Dt PAM_SSH 8
	40	.Os
	41	.Sh NAME
	42	.Nm pam_ssh
	43	.Nd authentication and session management with SSH private keys
	44	.Sh SYNOPSIS
	45	.Op Ar service-name
	46	.Ar module-type
	47	.Ar control-flag
	48	.Pa pam_ssh
	49	.Op Ar options
	50	.Sh DESCRIPTION
	51	The
	52	SSH
	53	authentication service module for PAM,
	54	.Nm
	55	provides functionality for two PAM categories:
	56	authentication
	57	and session management.
	58	In terms of the
	59	.Ar module-type
	60	parameter, they are the
	61	.Dq Li auth
	62	and
	63	.Dq Li session
	64	features.
	65	.Ss SSH Authentication Module
	66	The
	67	SSH
	68	authentication component
	69	provides a function to verify the identity of a user
	70	.Pq Fn pam_sm_authenticate ,
	71	by prompting the user for a passphrase and verifying that it can
	72	decrypt the target user's SSH key using that passphrase.
	73	.Pp
	74	The following options may be passed to the authentication module:
	75	.Bl -tag -width ".Cm use_first_pass"
	76	.It Cm use_first_pass
	77	If the authentication module
	78	is not the first in the stack,
	79	and a previous module
	80	obtained the user's password,
	81	that password is used
	82	to authenticate the user.
	83	If this fails,
	84	the authentication module returns failure
	85	without prompting the user for a password.
	86	This option has no effect
	87	if the authentication module
	88	is the first in the stack,
	89	or if no previous modules
	90	obtained the user's password.
	91	.It Cm try_first_pass
	92	This option is similar to the
	93	.Cm use_first_pass
	94	option,
	95	except that if the previously obtained password fails,
	96	the user is prompted for another password.
	97	.It Cm nullok
	98	Normally, keys with no passphrase are ignored for authentication
	99	purposes.
	100	If this option is set, keys with no passphrase will be taken into
	101	consideration, allowing the user to log in with a blank password.
	102	.El
	103	.Ss SSH Session Management Module
	104	The
	105	SSH
	106	session management component
	107	provides functions to initiate
	108	.Pq Fn pam_sm_open_session
	109	and terminate
	110	.Pq Fn pam_sm_close_session
	111	sessions.
	112	The
	113	.Fn pam_sm_open_session
	114	function starts an SSH agent,
	115	passing it any private keys it decrypted
	116	during the authentication phase,
	117	and sets the environment variables
	118	the agent specifies.
	119	The
	120	.Fn pam_sm_close_session
	121	function kills the previously started SSH agent
	122	by sending it a
	123	.Dv SIGTERM .
	124	.Pp
	125	The following options may be passed to the session management module:
	126	.Bl -tag -width ".Cm want_agent"
	127	.It Cm want_agent
	128	Start an agent even if no keys were decrypted during the
	129	authentication phase.
	130	.El
	131	.Sh FILES
	132	.Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
	133	.It Pa $HOME/.ssh/identity
	134	SSH1 RSA key
	135	.It Pa $HOME/.ssh/id_rsa
	136	SSH2 RSA key
	137	.It Pa $HOME/.ssh/id_dsa
	138	SSH2 DSA key
	139	.El
	140	.Sh SEE ALSO
	141	.Xr ssh-agent 1 ,
	142	.Xr pam.conf 5 ,
	143	.Xr pam 8
	144	.Sh AUTHORS
	145	The
	146	.Nm
	147	module was originally written by
	148	.An -nosplit
	149	.An "Andrew J. Korty" Aq ajk@iu.edu .
	150	The current implementation was developed for the
	151	.Fx
	152	Project by
	153	ThinkSec AS and NAI Labs, the Security Research Division of Network
	154	Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
	155	.Pq Dq CBOSS ,
	156	as part of the DARPA CHATS research program.
	157	This manual page was written by
	158	.An "Mark R V Murray" Aq markm@FreeBSD.org .