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