lib/libpam/modules/pam_ssh/pam_ssh.8

   1 .\" Copyright (c) 2001 Mark R V Murray
   2 .\" All rights reserved.
   3 .\" Copyright (c) 2001 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 .\"
  35 .\" $FreeBSD: src/lib/libpam/modules/pam_ssh/pam_ssh.8,v 1.8.2.2 2002/07/03 21:41:30 des Exp $
  36 .\"
  37 .Dd November 26, 2001
  38 .Dt PAM_SSH 8
  39 .Os
  40 .Sh NAME
  41 .Nm pam_ssh
  42 .Nd SSH PAM module
  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 It also provides null functions for the remaining categories.
  65 .Ss SSH Authentication Module
  66 The
  67 SSH
  68 authentication component
  69 provides a function to verify the identity of a user
  70 .Pq Fn pam_sm_authenticate ,
  71 by prompting the user for a passphrase and verifying that it can
  72 decrypt the target user's SSH key using that passphrase.
  73 .Pp
  74 The following options may be passed to the authentication module:
  75 .Bl -tag -width ".Cm use_first_pass"
  76 .It Cm debug
  77 .Xr syslog 3
  78 debugging information at
  79 .Dv LOG_DEBUG
  80 level.
  81 .It Cm use_first_pass
  82 If the authentication module
  83 is not the first in the stack,
  84 and a previous module
  85 obtained the user's password,
  86 that password is used
  87 to authenticate the user.
  88 If this fails,
  89 the authentication module returns failure
  90 without prompting the user for a password.
  91 This option has no effect
  92 if the authentication module
  93 is the first in the stack,
  94 or if no previous modules
  95 obtained the user's password.
  96 .It Cm try_first_pass
  97 This option is similar to the
  98 .Cm use_first_pass
  99 option,
 100 except that if the previously obtained password fails,
 101 the user is prompted for another password.
 102 .El
 103 .Ss SSH Session Management Module
 104 The
 105 SSH
 106 session management component
 107 provides functions to initiate
 108 .Pq Fn pam_sm_open_session
 109 and terminate
 110 .Pq Fn pam_sm_close_session
 111 sessions.
 112 The
 113 .Fn pam_sm_open_session
 114 function starts an SSH agent,
 115 passing it any private keys it decrypted
 116 during the authentication phase,
 117 and sets the environment variables
 118 the agent specifies.
 119 The
 120 .Fn pam_sm_close_session
 121 function kills the previously started SSH agent
 122 by sending it a
 123 .Dv SIGTERM .
 124 .Pp
 125 The following options may be passed to the session management module:
 126 .Bl -tag -width ".Cm use_first_pass"
 127 .It Cm debug
 128 .Xr syslog 3
 129 debugging information at
 130 .Dv LOG_DEBUG
 131 level.
 132 .El
 133 .Sh FILES
 134 .Bl -tag -width ".Pa $HOME/.ssh2/id_dsa_*" -compact
 135 .It Pa $HOME/.ssh/identity
 136 SSH1/OpenSSH RSA key.
 137 .It Pa $HOME/.ssh/id_dsa
 138 OpenSSH DSA key.
 139 .It Pa $HOME/.ssh2/id_rsa_*
 140 SSH2 RSA keys.
 141 .It Pa $HOME/.ssh2/id_dsa_*
 142 SSH2 DSA keys.
 143 .El
 144 .Sh SEE ALSO
 145 .Xr ssh-agent 1 ,
 146 .Xr syslog 3 ,
 147 .Xr pam.conf 5 ,
 148 .Xr pam 8