lib/pam_module/pam_ssh/pam_ssh.8

   1 .\" Copyright (c) 2001 Mark R V Murray
   2 .\" All rights reserved.
   3 .\" Copyright (c) 2001-2003 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.13 2004/07/02 23:52:18 ru Exp $
  36 .\" $DragonFly: src/lib/pam_module/pam_ssh/pam_ssh.8,v 1.1 2005/07/12 23:26:49 joerg Exp $
  37 .\"
  38 .Dd November 26, 2001
  39 .Dt PAM_SSH 8
  40 .Os
  41 .Sh NAME
  42 .Nm pam_ssh
  43 .Nd authentication and session management with SSH private keys
  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 .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 use_first_pass
  77 If the authentication module
  78 is not the first in the stack,
  79 and a previous module
  80 obtained the user's password,
  81 that password is used
  82 to authenticate the user.
  83 If this fails,
  84 the authentication module returns failure
  85 without prompting the user for a password.
  86 This option has no effect
  87 if the authentication module
  88 is the first in the stack,
  89 or if no previous modules
  90 obtained the user's password.
  91 .It Cm try_first_pass
  92 This option is similar to the
  93 .Cm use_first_pass
  94 option,
  95 except that if the previously obtained password fails,
  96 the user is prompted for another password.
  97 .El
  98 .Ss SSH Session Management Module
  99 The
 100 SSH
 101 session management component
 102 provides functions to initiate
 103 .Pq Fn pam_sm_open_session
 104 and terminate
 105 .Pq Fn pam_sm_close_session
 106 sessions.
 107 The
 108 .Fn pam_sm_open_session
 109 function starts an SSH agent,
 110 passing it any private keys it decrypted
 111 during the authentication phase,
 112 and sets the environment variables
 113 the agent specifies.
 114 The
 115 .Fn pam_sm_close_session
 116 function kills the previously started SSH agent
 117 by sending it a
 118 .Dv SIGTERM .
 119 .Pp
 120 The following options may be passed to the session management module:
 121 .Bl -tag -width ".Cm want_agent"
 122 .It Cm want_agent
 123 Start an agent even if no keys were decrypted during the
 124 authentication phase.
 125 .El
 126 .Sh FILES
 127 .Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
 128 .It Pa $HOME/.ssh/identity
 129 SSH1 RSA key
 130 .It Pa $HOME/.ssh/id_rsa
 131 SSH2 RSA key
 132 .It Pa $HOME/.ssh/id_dsa
 133 SSH2 DSA key
 134 .El
 135 .Sh SEE ALSO
 136 .Xr ssh-agent 1 ,
 137 .Xr pam.conf 5 ,
 138 .Xr pam 8
 139 .Sh AUTHORS
 140 The
 141 .Nm
 142 module was originally written by
 143 .An -nosplit
 144 .An "Andrew J. Korty" Aq ajk@iu.edu .
 145 The current implementation was developed for the
 146 .Fx
 147 Project by
 148 ThinkSec AS and NAI Labs, the Security Research Division of Network
 149 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
 150 .Pq Dq CBOSS ,
 151 as part of the DARPA CHATS research program.
 152 This manual page was written by
 153 .An "Mark R V Murray" Aq markm@FreeBSD.org .