lib/pam_module/pam_ssh/pam_ssh.8

   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 .\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.15 2011/10/07 12:58:33 des Exp $
  36 .\"
  37 .Dd December 24, 2011
  38 .Dt PAM_SSH 8
  39 .Os
  40 .Sh NAME
  41 .Nm pam_ssh
  42 .Nd authentication and session management with SSH private keys
  43 .Sh SYNOPSIS
  44 .Op Ar service-name
  45 .Ar module-type
  46 .Ar control-flag
  47 .Pa pam_ssh
  48 .Op Ar options
  49 .Sh DESCRIPTION
  50 The
  51 SSH
  52 authentication service module for PAM,
  53 .Nm
  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 .It Cm nullok
  97 Normally, keys with no passphrase are ignored for authentication
  98 purposes.
  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.
 101 .El
 102 .Ss SSH Session Management Module
 103 The
 104 SSH
 105 session management component
 106 provides functions to initiate
 107 .Pq Fn pam_sm_open_session
 108 and terminate
 109 .Pq Fn pam_sm_close_session
 110 sessions.
 111 The
 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
 117 the agent specifies.
 118 The
 119 .Fn pam_sm_close_session
 120 function kills the previously started SSH agent
 121 by sending it a
 122 .Dv SIGTERM .
 123 .Pp
 124 The following options may be passed to the session management module:
 125 .Bl -tag -width ".Cm want_agent"
 126 .It Cm want_agent
 127 Start an agent even if no keys were decrypted during the
 128 authentication phase.
 129 .El
 130 .Sh FILES
 131 .Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
 132 .It Pa $HOME/.ssh/identity
 133 SSH1 RSA key
 134 .It Pa $HOME/.ssh/id_rsa
 135 SSH2 RSA key
 136 .It Pa $HOME/.ssh/id_dsa
 137 SSH2 DSA key
 138 .It Pa $HOME/.ssh/id_ecdsa
 139 SSH2 ECDSA key
 140 .El
 141 .Sh SEE ALSO
 142 .Xr ssh-agent 1 ,
 143 .Xr pam.conf 5 ,
 144 .Xr pam 8
 145 .Sh AUTHORS
 146 .An -nosplit
 147 The
 148 .Nm
 149 module was originally written by
 150 .An Andrew J. Korty Aq Mt ajk@iu.edu .
 151 The current implementation was developed for the
 152 .Fx
 153 Project by
 154 ThinkSec AS and NAI Labs, the Security Research Division of Network
 155 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
 156 .Pq Dq CBOSS ,
 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 .