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.
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.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
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
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
35 .\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.15 2011/10/07 12:58:33 des Exp $
42 .Nd authentication and session management with SSH private keys
52 authentication service module for PAM,
54 provides functionality for two PAM categories:
56 and session management.
59 parameter, they are the
64 .Ss SSH Authentication Module
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.
73 The following options may be passed to the authentication module:
74 .Bl -tag -width ".Cm use_first_pass"
76 If the authentication module
77 is not the first in the stack,
79 obtained the user's password,
81 to authenticate the user.
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.
91 This option is similar to the
94 except that if the previously obtained password fails,
95 the user is prompted for another password.
97 Normally, keys with no passphrase are ignored for authentication
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.
102 .Ss SSH Session Management Module
105 session management component
106 provides functions to initiate
107 .Pq Fn pam_sm_open_session
109 .Pq Fn pam_sm_close_session
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
119 .Fn pam_sm_close_session
120 function kills the previously started SSH agent
124 The following options may be passed to the session management module:
125 .Bl -tag -width ".Cm want_agent"
127 Start an agent even if no keys were decrypted during the
128 authentication phase.
131 .Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
132 .It Pa $HOME/.ssh/identity
134 .It Pa $HOME/.ssh/id_rsa
136 .It Pa $HOME/.ssh/id_dsa
138 .It Pa $HOME/.ssh/id_ecdsa
149 module was originally written by
150 .An Andrew J. Korty Aq Mt ajk@iu.edu .
151 The current implementation was developed for the
154 ThinkSec AS and NAI Labs, the Security Research Division of Network
155 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
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 .