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