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.14 2005/09/22 05:35:24 des 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 .It Cm nullok
  98 Normally, keys with no passphrase are ignored for authentication
  99 purposes.
 100 If this option is set, keys with no passphrase will be taken into
 101 consideration, allowing the user to log in with a blank 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 want_agent"
 127 .It Cm want_agent
 128 Start an agent even if no keys were decrypted during the
 129 authentication phase.
 130 .El
 131 .Sh FILES
 132 .Bl -tag -width ".Pa $HOME/.ssh/identity" -compact
 133 .It Pa $HOME/.ssh/identity
 134 SSH1 RSA key
 135 .It Pa $HOME/.ssh/id_rsa
 136 SSH2 RSA key
 137 .It Pa $HOME/.ssh/id_dsa
 138 SSH2 DSA key
 139 .El
 140 .Sh SEE ALSO
 141 .Xr ssh-agent 1 ,
 142 .Xr pam.conf 5 ,
 143 .Xr pam 8
 144 .Sh AUTHORS
 145 The
 146 .Nm
 147 module was originally written by
 148 .An -nosplit
 149 .An "Andrew J. Korty" Aq ajk@iu.edu .
 150 The current implementation was developed for the
 151 .Fx
 152 Project by
 153 ThinkSec AS and NAI Labs, the Security Research Division of Network
 154 Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035
 155 .Pq Dq CBOSS ,
 156 as part of the DARPA CHATS research program.
 157 This manual page was written by
 158 .An "Mark R V Murray" Aq markm@FreeBSD.org .