contrib/openpam/bin/pamtest/pamtest.1

   1 .\"-
   2 .\" Copyright (c) 2011 Dag-Erling Smørgrav
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote
  14 .\"    products derived from this software without specific prior written
  15 .\"    permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $Id: pamtest.1 816 2014-09-12 07:50:22Z des $
  30 .\"
  31 .Dd September 12, 2014
  32 .Dt PAMTEST 1
  33 .Os
  34 .Sh NAME
  35 .Nm pamtest
  36 .Nd PAM policy tester
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl dkMPsv
  40 .Op Fl H Ar rhost
  41 .Op Fl h Ar host
  42 .Op Fl T Ar timeout
  43 .Op Fl t Ar tty
  44 .Op Fl U Ar ruser
  45 .Op Fl u Ar user
  46 .Ar service
  47 .Op Ar command ...
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility offers an easy way to test PAM modules and policies from the
  52 command line.
  53 .Pp
  54 The
  55 .Nm
  56 utility loads the PAM policy specified by the
  57 .Ar service
  58 argument, starts a PAM transaction by calling
  59 .Xr pam_start 3 ,
  60 then executes the primitives specified by the remaining command-line
  61 arguments.
  62 Finally, it ends the transaction by calling
  63 .Xr pam_end 3 .
  64 .Pp
  65 The commands are:
  66 .Bl -tag -width 6n
  67 .It Cm authenticate , Cm auth
  68 Call
  69 .Xr pam_authenticate 3 .
  70 .It Cm acct_mgmt , Cm account
  71 Call
  72 .Xr pam_acct_mgmt 3 .
  73 .It Cm chauthtok , Cm change
  74 Call
  75 .Xr pam_chauthtok 3
  76 with the
  77 .Dv PAM_CHANGE_EXPIRED_AUTHTOK
  78 flag set.
  79 .It Cm forcechauthtok , Cm forcechange
  80 Call
  81 .Xr pam_chauthtok 3
  82 with no flags set.
  83 .It Cm setcred , Cm establish_cred
  84 Call
  85 .Xr pam_setcred 3
  86 with the
  87 .Dv PAM_ESTABLISH_CRED
  88 flag set.
  89 .It Cm open_session , Cm open
  90 Call
  91 .Xr pam_open_session 3 .
  92 .It Cm close_session , Cm close
  93 Call
  94 .Xr pam_close_session 3 .
  95 .It Cm unsetcred , Cm delete_cred
  96 Call
  97 .Xr pam_setcred 3
  98 with the
  99 .Dv PAM_DELETE_CRED
 100 flag set.
 101 .It Cm listenv , Cm env
 102 Call
 103 .Xr pam_getenvlist 3
 104 and print the contents of the list it returns.
 105 .El
 106 .Pp
 107 The following options are available:
 108 .Bl -tag -width Fl
 109 .It Fl d
 110 Enables debug messages within the OpenPAM library.
 111 See
 112 .Xr openpam_log 3
 113 for details.
 114 .It Fl H Ar rhost
 115 Specify the name of the fictitious remote host.
 116 The default is to use the name of the local host.
 117 .It Fl h Ar host
 118 Specify the name of the local host.
 119 The default is to use the result of calling
 120 .Xr gethostname 3 .
 121 .It Fl k
 122 Keep going even if one of the commands fails.
 123 .It Fl M
 124 Disable path, ownership and permission checks on module files.
 125 .It Fl P
 126 Disable service name validation and path, ownership and permission
 127 checks on policy files.
 128 .It Fl s
 129 Set the
 130 .Dv PAM_SILENT
 131 flag when calling the
 132 .Xr pam_authenticate 3 ,
 133 .Xr pam_acct_mgmt 3 ,
 134 .Xr pam_chauthok 3 ,
 135 .Xr pam_setcred 3 ,
 136 .Xr pam_open_session 3
 137 and
 138 .Xr pam_close_session 3
 139 primitives.
 140 .It Fl T Ar timeout
 141 Set the conversation timeout (in seconds) for
 142 .Xr openpam_ttyconv 3 .
 143 .It Fl t Ar tty
 144 Specify the name of the tty.
 145 The default is to use the result of calling
 146 .Xr ttyname 3 .
 147 .It Fl U Ar ruser
 148 Specify the name of the supplicant (remote user).
 149 .It Fl u Ar user
 150 Specify the name of the principal (local user).
 151 .It Fl v
 152 Enables debug messages from
 153 .Nm
 154 itself.
 155 .El
 156 .Sh EXAMPLES
 157 Simulate a typical PAM transaction using the
 158 .Dq system
 159 policy:
 160 .Bd -literal -offset indent
 161 pamtest -v system auth account change setcred open close unsetcred
 162 .Ed
 163 .Sh SEE ALSO
 164 .Xr openpam 3 ,
 165 .Xr pam 3 ,
 166 .Xr pam.conf 5
 167 .Sh AUTHORS
 168 The
 169 .Nm
 170 utility and this manual page were written by
 171 .An Dag-Erling Sm\(/orgrav Aq des@des.no .
 172 .Sh BUGS
 173 The
 174 .Nm
 175 utility does not (yet) support setting and getting individual PAM
 176 items or environment variables.
 177 .Pp
 178 The
 179 .Nm
 180 utility does not afford the user complete control over the flags
 181 passed to the
 182 .Xr pam_authenticate 3 ,
 183 .Xr pam_acct_mgmt 3 ,
 184 .Xr pam_chauthok 3 ,
 185 .Xr pam_setcred 3 ,
 186 .Xr pam_open_session 3
 187 and
 188 .Xr pam_close_session 3
 189 primitives.