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