Import current pam_ssh from FreeBSD HEAD.
[dragonfly.git] / lib / pam_module / pam_ssh / pam_ssh.8
CommitLineData
f8bdfa2d
JS
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.13 2004/07/02 23:52:18 ru 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
51The
52SSH
53authentication service module for PAM,
54.Nm
55provides functionality for two PAM categories:
56authentication
57and session management.
58In terms of the
59.Ar module-type
60parameter, they are the
61.Dq Li auth
62and
63.Dq Li session
64features.
65.Ss SSH Authentication Module
66The
67SSH
68authentication component
69provides a function to verify the identity of a user
70.Pq Fn pam_sm_authenticate ,
71by prompting the user for a passphrase and verifying that it can
72decrypt the target user's SSH key using that passphrase.
73.Pp
74The following options may be passed to the authentication module:
75.Bl -tag -width ".Cm use_first_pass"
76.It Cm use_first_pass
77If the authentication module
78is not the first in the stack,
79and a previous module
80obtained the user's password,
81that password is used
82to authenticate the user.
83If this fails,
84the authentication module returns failure
85without prompting the user for a password.
86This option has no effect
87if the authentication module
88is the first in the stack,
89or if no previous modules
90obtained the user's password.
91.It Cm try_first_pass
92This option is similar to the
93.Cm use_first_pass
94option,
95except that if the previously obtained password fails,
96the user is prompted for another password.
97.El
98.Ss SSH Session Management Module
99The
100SSH
101session management component
102provides functions to initiate
103.Pq Fn pam_sm_open_session
104and terminate
105.Pq Fn pam_sm_close_session
106sessions.
107The
108.Fn pam_sm_open_session
109function starts an SSH agent,
110passing it any private keys it decrypted
111during the authentication phase,
112and sets the environment variables
113the agent specifies.
114The
115.Fn pam_sm_close_session
116function kills the previously started SSH agent
117by sending it a
118.Dv SIGTERM .
119.Pp
120The following options may be passed to the session management module:
121.Bl -tag -width ".Cm want_agent"
122.It Cm want_agent
123Start an agent even if no keys were decrypted during the
124authentication phase.
125.El
126.Sh FILES
127.Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
128.It Pa $HOME/.ssh/identity
129SSH1 RSA key
130.It Pa $HOME/.ssh/id_rsa
131SSH2 RSA key
132.It Pa $HOME/.ssh/id_dsa
133SSH2 DSA key
134.El
135.Sh SEE ALSO
136.Xr ssh-agent 1 ,
137.Xr pam.conf 5 ,
138.Xr pam 8
139.Sh AUTHORS
140The
141.Nm
142module was originally written by
143.An -nosplit
144.An "Andrew J. Korty" Aq ajk@iu.edu .
145The current implementation was developed for the
146.Fx
147Project by
148ThinkSec AS and NAI Labs, the Security Research Division of Network
149Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
150.Pq Dq CBOSS ,
151as part of the DARPA CHATS research program.
152This manual page was written by
153.An "Mark R V Murray" Aq markm@FreeBSD.org .