| blob | 3b133ff2db98b4d6005982bfb4bb0ab7eb888272 |
1 .\" $NetBSD: pam_ssh.8,v 1.4 2005/02/27 21:32:46 thorpej Exp $
2 .\" Copyright (c) 2001 Mark R V Murray
3 .\" All rights reserved.
4 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
5 .\" All rights reserved.
6 .\"
7 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
8 .\" NAI Labs, the Security Research Division of Network Associates, Inc.
9 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
10 .\" DARPA CHATS research program.
11 .\"
12 .\" Redistribution and use in source and binary forms, with or without
13 .\" modification, are permitted provided that the following conditions
14 .\" are met:
15 .\" 1. Redistributions of source code must retain the above copyright
16 .\" notice, this list of conditions and the following disclaimer.
17 .\" 2. Redistributions in binary form must reproduce the above copyright
18 .\" notice, this list of conditions and the following disclaimer in the
19 .\" documentation and/or other materials provided with the distribution.
20 .\" 3. The name of the author may not be used to endorse or promote
21 .\" products derived from this software without specific prior written
22 .\" permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.13 2004/07/02 23:52:18 ru Exp $
37 .\"
38 .Dd February 27, 2005
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 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 .El
97 .Ss SSH Session Management Module
98 The
99 SSH
100 session management component
101 provides functions to initiate
102 .Pq Fn pam_sm_open_session
103 and terminate
104 .Pq Fn pam_sm_close_session
105 sessions.
106 The
107 .Fn pam_sm_open_session
108 function starts an SSH agent,
109 passing it any private keys it decrypted
110 during the authentication phase,
111 and sets the environment variables
112 the agent specifies.
113 The
114 .Fn pam_sm_close_session
115 function kills the previously started SSH agent
116 by sending it a
117 .Dv SIGTERM .
118 .Pp
119 The following options may be passed to the session management module:
120 .Bl -tag -width ".Cm want_agent"
121 .It Cm want_agent
122 Start an agent even if no keys were decrypted during the
123 authentication phase.
124 .El
125 .Sh FILES
126 .Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
127 .It Pa $HOME/.ssh/identity
128 SSH1 RSA key
129 .It Pa $HOME/.ssh/id_rsa
130 SSH2 RSA key
131 .It Pa $HOME/.ssh/id_dsa
132 SSH2 DSA key
133 .El
134 .Sh SEE ALSO
135 .Xr ssh-agent 1 ,
136 .Xr pam.conf 5 ,
137 .Xr pam 8
138 .Sh AUTHORS
139 The
140 .Nm
141 module was originally written by
142 .An -nosplit
143 .An "Andrew J. Korty" Aq ajk@iu.edu .
144 The current implementation was developed for the
145 .Fx
146 Project by
147 ThinkSec AS and NAI Labs, the Security Research Division of Network
148 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
149 .Pq Dq CBOSS ,
150 as part of the DARPA CHATS research program.
151 This manual page was written by
152 .An "Mark R V Murray" Aq markm@FreeBSD.org .
153 .Sh SECURITY CONSIDERATIONS
154 The
155 .Nm
156 module implements what is fundamentally a password authentication scheme.
157 Care should be taken to only use this module over a secure session
158 .Po
159 secure TTY, encrypted session, etc.
160 .Pc ,
161 otherwise the user's SSH passphrase could be compromised.
162 .Pp
163 Additional consideration should be given to the use of
164 .Nm pam_ssh .
165 Users often assume that file permissions are sufficient to protect their
166 SSH keys, and thus use weak or no passphrases.
167 Since the system administrator has no effective means of enforcing
168 SSH passphrase quality, this has the potential to expose the system to
169 security risks.