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

See Also

452       mod_perl 2.0 documentation.
453

Copyright

455       mod_perl 2.0 and its core modules are copyrighted under The Apache
456       Software License, Version 2.0.
457

Authors

459       The mod_perl development team and numerous contributors.
460
461
462
463perl v5.8.8                       2006-11-19     docs::api::Apache2::Access(3)