Apache2::Access(3pm)

1docs::api::Apache2::AccUessesr(3C)ontributed Perl Documednotcast:i:oanpi::Apache2::Access(3)
2
3
4

NAME

6       Apache2::Access - A Perl API for Apache request object: Access,
7       Authentication and Authorization.
8

Synopsis

10         use Apache2::Access ();
11
12         # allow only GET method
13         $r->allow_methods(1, qw(GET));
14
15         # Apache Options value
16         $options = $r->allow_options();
17
18         # Apache AllowOverride value
19         $allow_override = $r->allow_overrides();
20
21         # which Options are allowed by AllowOverride (since Apache 2.2)
22         $allow_override_opts = $r->allow_override_opts();
23
24         # auth name ("foo bar")
25         $auth_name = $r->auth_name();
26
27         # auth type
28         $auth_type = $r->auth_type();
29         $r->auth_type("Digest");
30
31         # Basic authentication process
32         my ($rc, $passwd) = $r->get_basic_auth_pw();
33
34         # the login name of the remote user (RFC1413)
35         $remote_logname = $r->get_remote_logname();
36
37         # dynamically figure out which auth has failed
38         $r->note_auth_failure();
39
40         # note Basic auth failure
41         $r->note_basic_auth_failure();
42
43         # note Digest auth failure
44         $r->note_digest_auth_failure();
45
46         # Apache Request value(s)
47         $requires = $r->requires();
48
49         # Apache Satisfy value (as a number)
50         $satisfy = $r->satisfies();
51
52         # check whether some auth is configured
53         $need_auth = $r->some_auth_required();
54

Description

56       The API provided by this module deals with access, authentication and
57       authorization phases.
58
59       "Apache2::Access" extends "Apache2::RequestRec".
60

API

62       "Apache2::Access" provides the following functions and/or methods:
63
64   "allow_methods"
65       Specify which HTTP methods are allowed
66
67         $r->allow_methods($reset);
68         $r->allow_methods($reset, @methods);
69
70       obj: $r ( "Apache2::RequestRec object" )
71           The current request
72
73       arg1: $reset ( boolean )
74           If a true value is passed all the previously allowed methods are
75           removed. Otherwise the list is left intact.
76
77       opt arg2: @methods ( array of strings )
78           a list of HTTP methods to be allowed (e.g. "GET" and "POST")
79
80       ret: no return value
81       since: 2.0.00
82
83       For example: here is how to allow only "GET" and "POST" methods,
84       regardless to what was the previous setting:
85
86         $r->allow_methods(1, qw(GET POST));
87
88   "allow_options"
89       Retrieve the value of "Options" for this request
90
91         $options = $r->allow_options();
92
93       obj: $r ( "Apache2::RequestRec object" )
94           The current request
95
96       ret: $options ( integer )
97           the "Options" bitmask. Normally used with bitlogic operators
98           against "Apache2::Const :options constants".
99
100       since: 2.0.00
101
102       For example if the configuration for the current request was:
103
104         Options None
105         Options Indexes FollowSymLinks
106
107       The following applies:
108
109         use Apache2::Const -compile => qw(:options);
110         $r->allow_options & Apache2::Const::OPT_INDEXES;   # TRUE
111         $r->allow_options & Apache2::Const::OPT_SYM_LINKS; # TRUE
112         $r->allow_options & Apache2::Const::OPT_EXECCGI;   # FALSE
113
114   "allow_overrides"
115       Retrieve the value of "AllowOverride" for this request
116
117         $allow_override = $r->allow_overrides();
118
119       obj: $r ( "Apache2::RequestRec object" )
120           The current request
121
122       ret: $allow_override ( integer )
123           the "AllowOverride" bitmask. Normally used with bitlogic operators
124           against "Apache2::Const :override constants".
125
126       since: 2.0.00
127
128       For example if the configuration for the current request was:
129
130         AllowOverride AuthConfig
131
132       The following applies:
133
134         use Apache2::Const -compile => qw(:override);
135         $r->allow_overrides & Apache2::Const::OR_AUTHCFG; # TRUE
136         $r->allow_overrides & Apache2::Const::OR_LIMIT; # FALSE
137
138   "allow_override_opts"
139       Retrieve the bitmask of allowed "Options" set by "AllowOverride
140       Options=..."  for this request
141
142         $override_opts = $r->allow_override_opts();
143
144       Enabling single options was introduced in Apache 2.2. For Apache 2.0
145       this function returns "Apache2::Const::OPT_UNSET" |
146       "Apache2::Const::OPT_ALL" | "Apache2::Const::OPT_INCNOEXEC" |
147       "Apache2::Const::OPT_SYM_OWNER" | "Apache2::Const::OPT_MULTI", which
148       corresponds to the default value (if not set) for Apache 2.2.
149
150       obj: $r ( "Apache2::RequestRec object" )
151           The current request
152
153       ret: $override_opts ( integer )
154           the override options bitmask. Normally used with bitlogic operators
155           against "Apache2::Const :options constants".
156
157       since: 2.0.3
158
159       For example if the configuration for the current request was:
160
161         AllowOverride Options=Indexes,ExecCGI
162
163       The following applies:
164
165         use Apache2::Const -compile => qw(:options);
166         $r->allow_override_opts & Apache2::Const::OPT_EXECCGI; # TRUE
167         $r->allow_override_opts & Apache2::Const::OPT_SYM_LINKS; # FALSE
168
169   "auth_name"
170       Get/set the current Authorization realm (the per directory
171       configuration directive "AuthName"):
172
173         $auth_name = $r->auth_name();
174         $auth_name = $r->auth_name($new_auth_name);
175
176       obj: $r ( "Apache2::RequestRec object" )
177           The current request
178
179       opt arg1: $new_auth_name ( string )
180           If $new_auth_name is passed a new "AuthName" value is set
181
182       ret: "$" ( integer )
183           The current value of "AuthName"
184
185       since: 2.0.00
186
187       The "AuthName" directive creates protection realm within the server
188       document space. To quote RFC 1945 "These realms allow the protected
189       resources on a server to be partitioned into a set of protection
190       spaces, each with its own authentication scheme and/or authorization
191       database." The client uses the root URL of the server to determine
192       which authentication credentials to send with each HTTP request. These
193       credentials are tagged with the name of the authentication realm that
194       created them.  Then during the authentication stage the server uses the
195       current authentication realm, from "$r->auth_name", to determine which
196       set of credentials to authenticate.
197
198   "auth_type"
199       Get/set the type of authorization required for this request (the per
200       directory configuration directive "AuthType"):
201
202         $auth_type = $r->auth_type();
203         $auth_type = $r->auth_type($new_auth_type);
204
205       obj: $r ( "Apache2::RequestRec object" )
206           The current request
207
208       opt arg1: $new_auth_type ( string )
209           If $new_auth_type is passed a new "AuthType" value is set
210
211       ret: "$" ( integer )
212           The current value of "AuthType"
213
214       since: 2.0.00
215
216       Normally "AuthType" would be set to "Basic" to use the basic
217       authentication scheme defined in RFC 1945, Hypertext Transfer Protocol
218       -- HTTP/1.0. However, you could set to something else and implement
219       your own authentication scheme.
220
221   "get_basic_auth_pw"
222       Get the password from the request headers
223
224         my ($rc, $passwd) = $r->get_basic_auth_pw();
225
226       obj: $r ( "Apache2::RequestRec object" )
227           The current request
228
229       ret1: $rc ( "Apache2::Const constant" )
230           "Apache2::Const::OK" if the $passwd value is set (and assured a
231           correct value in "$r->user"); otherwise it returns an error code,
232           either "Apache2::Const::HTTP_INTERNAL_SERVER_ERROR" if things are
233           really confused, "Apache2::Const::HTTP_UNAUTHORIZED" if no
234           authentication at all seemed to be in use, or
235           "Apache2::Const::DECLINED" if there was authentication, but it
236           wasn't "Basic" (in which case, the caller should presumably decline
237           as well).
238
239       ret2: $ret (string)
240           The password as set in the headers (decoded)
241
242       since: 2.0.00
243
244       If "AuthType" is not set, this handler first sets it to "Basic".
245
246   "get_remote_logname"
247       Retrieve the login name of the remote user (RFC1413)
248
249         $remote_logname = $r->get_remote_logname();
250
251       obj: $r ( "Apache2::RequestRec object" )
252           The current request
253
254       ret: $remote_logname ( string )
255           The username of the user logged in to the client machine, or an
256           empty string if it could not be determined via RFC1413, which
257           involves querying the client's identd or auth daemon.
258
259       since: 2.0.00
260
261       Do not confuse this method with "$r->user", which provides the username
262       provided by the user during the server authentication.
263
264   "note_auth_failure"
265       Setup the output headers so that the client knows how to authenticate
266       itself the next time, if an authentication request failed.  This
267       function works for both basic and digest authentication
268
269         $r->note_auth_failure();
270
271       obj: $r ( "Apache2::RequestRec object" )
272           The current request
273
274       ret: no return value
275       since: 2.0.00
276
277       This method requires "AuthType" to be set to "Basic" or "Digest".
278       Depending on the setting it'll call either
279       "$r->note_basic_auth_failure" or "$r->note_digest_auth_failure".
280
281   "note_basic_auth_failure"
282       Setup the output headers so that the client knows how to authenticate
283       itself the next time, if an authentication request failed.  This
284       function works only for basic authentication
285
286         $r->note_basic_auth_failure();
287
288       obj: $r ( "Apache2::RequestRec object" )
289           The current request
290
291       ret: no return value
292       since: 2.0.00
293
294   "note_digest_auth_failure"
295       Setup the output headers so that the client knows how to authenticate
296       itself the next time, if an authentication request failed.  This
297       function works only for digest authentication.
298
299         $r->note_digest_auth_failure();
300
301       obj: $r ( "Apache2::RequestRec object" )
302           The current request
303
304       ret: no return value
305       since: 2.0.00
306
307   "requires"
308       Retrieve information about all of the requires directives for this
309       request
310
311         $requires = $r->requires
312
313       obj: $r ( "Apache2::RequestRec object" )
314           The current request
315
316       ret: $requires ( ARRAY ref )
317           Returns an array reference of hash references, containing
318           information related to the "require" directive.
319
320       since: 2.0.00
321
322       This is normally used for access control.
323
324       For example if the configuration had the following require directives:
325
326           Require user  goo bar
327           Require group bar tar
328
329       this method will return the following datastructure:
330
331         [
332           {
333             'method_mask' => -1,
334             'requirement' => 'user goo bar'
335           },
336           {
337             'method_mask' => -1,
338             'requirement' => 'group bar tar'
339           }
340         ];
341
342       The requirement field is what was passed to the "Require" directive.
343       The method_mask field is a bitmask which can be modified by the "Limit"
344       directive, but normally it can be safely ignored as it's mostly used
345       internally. For example if the configuration was:
346
347           Require user goo bar
348           Require group bar tar
349           <Limit POST>
350              Require valid-user
351           </Limit>
352
353       and the request method was "POST", "$r->requires" will return:
354
355         [
356           {
357             'method_mask' => -1,
358             'requirement' => 'user goo bar'
359           },
360           {
361             'method_mask' => -1,
362             'requirement' => 'group bar tar'
363           }
364           {
365             'method_mask' => 4,
366             'requirement' => 'valid-user'
367           }
368         ];
369
370       But if the request method was "GET", it will return only:
371
372         [
373           {
374             'method_mask' => -1,
375             'requirement' => 'user goo bar'
376           },
377           {
378             'method_mask' => -1,
379             'requirement' => 'group bar tar'
380           }
381         ];
382
383       As you can see Apache gives you the requirements relevant for the
384       current request, so the method_mask is irrelevant.
385
386       It is also a good time to remind that in the general case, access
387       control directives should not be placed within a <Limit> section.
388       Refer to the Apache documentation for more information.
389
390       Using the same configuration and assuming that the request was of type
391       POST, the following code inside an Auth handler:
392
393         my %require =
394             map { my ($k, $v) = split /\s+/, $_->{requirement}, 2; ($k, $v||'') }
395             @{ $r->requires };
396
397       will populate %require with the following pairs:
398
399         'group' => 'bar tar',
400         'user' => 'goo bar',
401         'valid-user' => '',
402
403   "satisfies"
404       How the requires lines must be met. What's the applicable value of the
405       "Satisfy" directive:
406
407         $satisfy = $r->satisfies();
408
409       obj: $r ( "Apache2::RequestRec object" )
410           The current request
411
412       ret: $satisfy ( integer )
413           How the requirements must be met.  One of the "Apache2::Const
414           :satisfy constants":
415
416           "Apache2::Const::SATISFY_ANY", "Apache2::Const::SATISFY_ALL" and
417           "Apache2::Const::SATISFY_NOSPEC".
418
419       since: 2.0.00
420
421       See the documentation for the "Satisfy" directive in the Apache
422       documentation.
423
424   "some_auth_required"
425       Can be used within any handler to determine if any authentication is
426       required for the current request:
427
428         $need_auth = $r->some_auth_required();
429
430       obj: $r ( "Apache2::RequestRec object" )
431           The current request
432
433       ret: $need_auth ( boolean )
434           TRUE if authentication is required, FALSE otherwise
435
436       since: 2.0.00
437

Copyright

442       mod_perl 2.0 and its core modules are copyrighted under The Apache
443       Software License, Version 2.0.
444

Authors

446       The mod_perl development team and numerous contributors.
447
448
449
450perl v5.36.0                      2022-07-21     docs::api::Apache2::Access(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors