Include lib/Makefile.inc in pam_modules' Makefile.inc.
[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.\"
6a3bc796 35.\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.14 2005/09/22 05:35:24 des Exp $
f8bdfa2d
JS
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.
6a3bc796
PA
97.It Cm nullok
98Normally, keys with no passphrase are ignored for authentication
99purposes.
100If this option is set, keys with no passphrase will be taken into
101consideration, allowing the user to log in with a blank password.
f8bdfa2d
JS
102.El
103.Ss SSH Session Management Module
104The
105SSH
106session management component
107provides functions to initiate
108.Pq Fn pam_sm_open_session
109and terminate
110.Pq Fn pam_sm_close_session
111sessions.
112The
113.Fn pam_sm_open_session
114function starts an SSH agent,
115passing it any private keys it decrypted
116during the authentication phase,
117and sets the environment variables
118the agent specifies.
119The
120.Fn pam_sm_close_session
121function kills the previously started SSH agent
122by sending it a
123.Dv SIGTERM .
124.Pp
125The following options may be passed to the session management module:
126.Bl -tag -width ".Cm want_agent"
127.It Cm want_agent
128Start an agent even if no keys were decrypted during the
129authentication phase.
130.El
131.Sh FILES
132.Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
133.It Pa $HOME/.ssh/identity
134SSH1 RSA key
135.It Pa $HOME/.ssh/id_rsa
136SSH2 RSA key
137.It Pa $HOME/.ssh/id_dsa
138SSH2 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
145The
146.Nm
147module was originally written by
148.An -nosplit
149.An "Andrew J. Korty" Aq ajk@iu.edu .
150The current implementation was developed for the
151.Fx
152Project by
153ThinkSec AS and NAI Labs, the Security Research Division of Network
154Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
155.Pq Dq CBOSS ,
156as part of the DARPA CHATS research program.
157This manual page was written by
158.An "Mark R V Murray" Aq markm@FreeBSD.org .