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 610 2012-05-26 14:03:45Z des $
  30 .\"
  31 .Dd May 26, 2012
  32 .Dt PAMTEST 1
  33 .Os
  34 .Sh NAME
  35 .Nm pamtest
  36 .Nd PAM policy tester
  37 .Sh SYNOPSYS
  38 .Nm
  39 .Op Fl dkMPsv
  40 .Op Fl H Ar rhost
  41 .Op Fl h Ar host
  42 .Op Fl t Ar tty
  43 .Op Fl U Ar ruser
  44 .Op Fl u Ar user
  45 .Ar service
  46 .Op Ar command ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility offers an easy way to test PAM modules and policies from the
  51 command line.
  52 .Pp
  53 The
  54 .Nm
  55 utility loads the PAM policy specified by the
  56 .Ar service
  57 argument, starts a PAM transaction by calling
  58 .Xr pam_start 3 ,
  59 then executes the primitives specified by the remaining command-line
  60 arguments.
  61 Finally, it ends the transaction by calling
  62 .Xr pam_end 3 .
  63 .Pp
  64 The commands are:
  65 .Bl -tag -width 6n
  66 .It Cm authenticate , Cm auth
  67 Call
  68 .Xr pam_authenticate 3 .
  69 .It Cm acct_mgmt , Cm account
  70 Call
  71 .Xr pam_acct_mgmt 3 .
  72 .It Cm chauthtok , Cm change
  73 Call
  74 .Xr pam_chauthtok 3
  75 with the
  76 .Dv PAM_CHANGE_EXPIRED_AUTHTOK
  77 flag set.
  78 .It Cm forcechauthtok , Cm forcechange
  79 Call
  80 .Xr pam_chauthtok 3
  81 with no flags set.
  82 .It Cm setcred , Cm establish_cred
  83 Call
  84 .Xr pam_setcred 3
  85 with the
  86 .Dv PAM_ESTABLISH_CRED
  87 flag set.
  88 .It Cm open_session , Cm open
  89 Call
  90 .Xr pam_open_session 3 .
  91 .It Cm close_session , Cm close
  92 Call
  93 .Xr pam_close_session 3 .
  94 .It Cm unsetcred , Cm delete_cred
  95 Call
  96 .Xr pam_setcred 3
  97 with the
  98 .Dv PAM_DELETE_CRED
  99 flag set.
 100 .It Cm listenv , Cm env
 101 Call
 102 .Xr pam_getenvlist 3
 103 and print the contents of the list it returns.
 104 .El
 105 .Pp
 106 The following options are available:
 107 .Bl -tag -width Fl
 108 .It Fl d
 109 Enables debug messages within the OpenPAM library.
 110 See
 111 .Xr openpam_log 3
 112 for details.
 113 .It Fl H Ar rhost
 114 Specify the name of the fictitious remote host.
 115 The default is to use the name of the local host.
 116 .It Fl h Ar host
 117 Specify the name of the local host.
 118 The default is to use the result of calling
 119 .Xr gethostname 3 .
 120 .It Fl k
 121 Keep going even if one of the commands fails.
 122 .It Fl M
 123 Disable path, ownership and permission checks on module files.
 124 .It Fl P
 125 Disable service name validation and path, ownership and permission
 126 checks on policy files.
 127 .It Fl s
 128 Set the
 129 .Dv PAM_SILENT
 130 flag when calling the
 131 .Xr pam_authenticate 3 ,
 132 .Xr pam_acct_mgmt 3 ,
 133 .Xr pam_chauthok 3 ,
 134 .Xr pam_setcred 3 ,
 135 .Xr pam_open_session 3
 136 and
 137 .Xr pam_close_session 3
 138 primitives.
 139 .It Fl t Ar tty
 140 Specify the name of the tty.
 141 The default is to use the result of calling
 142 .Xr ttyname 3 .
 143 .It Fl U Ar ruser
 144 Specify the name of the supplicant (remote user).
 145 .It Fl u Ar user
 146 Specify the name of the principal (local user).
 147 .It Fl v
 148 Enables debug messages from
 149 .Nm
 150 itself.
 151 .El
 152 .Sh EXAMPLES
 153 Simulate a typical PAM transaction using the
 154 .Dq system
 155 policy:
 156 .Bd -literal -offset indent
 157 pamtest -v system auth account change setcred open close unsetcred
 158 .Ed
 159 .Sh SEE ALSO
 160 .Xr openpam 3 ,
 161 .Xr pam 3 ,
 162 .Xr pam.conf 5
 163 .Sh AUTHORS
 164 The
 165 .Nm
 166 utility and this manual page were written by
 167 .An Dag-Erling Sm\(/orgrav Aq des@des.no .
 168 .Sh BUGS
 169 The
 170 .Nm
 171 utility does not (yet) support setting and getting individual PAM
 172 items or environment variables.
 173 .Pp
 174 The
 175 .Nm
 176 utility does not afford the user complete control over the flags
 177 passed to the
 178 .Xr pam_authenticate 3 ,
 179 .Xr pam_acct_mgmt 3 ,
 180 .Xr pam_chauthok 3 ,
 181 .Xr pam_setcred 3 ,
 182 .Xr pam_open_session 3
 183 and
 184 .Xr pam_close_session 3
 185 primitives.