perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache Access.pod Const.pod
Date Mon, 09 Aug 2004 00:26:23 GMT
stas        2004/08/08 17:26:23

  Modified:    src/docs/2.0/api/Apache Access.pod Const.pod
  Log:
  Apache::Access is complete
  
  Revision  Changes    Path
  1.6       +205 -40   modperl-docs/src/docs/2.0/api/Apache/Access.pod
  
  Index: Access.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Access.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -u -r1.5 -r1.6
  --- Access.pod	5 Aug 2004 08:36:50 -0000	1.5
  +++ Access.pod	9 Aug 2004 00:26:23 -0000	1.6
  @@ -10,8 +10,47 @@
   =head1 Synopsis
   
     use Apache::Access ();
  +  
  +  # allow only GET method
  +  $r->allow_methods(1, qw(GET));
  +  
  +  # Apache Options value
  +  $options = $r->allow_options();
  +  
  +  # Apache AllowOverride value
  +  $allow_override = $r->allow_overrides();
  +  
  +  # auth name ("foo bar")
  +  $auth_name = $r->auth_name();
  +  
  +  # auth type
  +  $auth_type = $r->auth_type();
  +  $r->auth_type("Digest");
  +  
  +  # Basic authentication process
  +  my($rc, $passwd) = $r->get_basic_auth_pw();
  +  
  +  # the login name of the remote user (RFC1413)
  +  $remote_logname = $r->get_remote_logname();
  +  
  +  # dynamically figure out which auth has failed
  +  $r->note_auth_failure();
  +  
  +  # note Basic auth failure
  +  $r->note_basic_auth_failure();
  +  
  +  # note Digest auth failure
  +  $r->note_digest_auth_failure();
  +  
  +  # Apache Request value(s)
  +  $requires = $r->requires();
  +  
  +  # Apache Satisfy value (as a number)
  +  $satisfy = $r->satisfies();
  +  
  +  # check whether some auth is configured
  +  $need_auth = $r->some_auth_required();
   
  -META: needs to be completed
   
   
   
  @@ -20,10 +59,12 @@
   
   =head1 Description
   
  -C<Apache::Access> provides an additional Perl API for
  -C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec|/Description>>
  -object. The API provided by this module deals with access,
  -authentication and authorization phases.
  +The API provided by this module deals with access, authentication and
  +authorization phases.
  +
  +C<Apache::Access> extends
  +C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec|/Description>>.
  +
   
   
   
  @@ -242,6 +283,7 @@
   
   
   
  +
   =head2 C<get_basic_auth_pw>
   
   Get the password from the request headers
  @@ -288,12 +330,9 @@
   
   =head2 C<get_remote_logname>
   
  -META: Autogenerated - needs to be reviewed/completed
  +Retrieve the login name of the remote user (RFC1413)
   
  -Retrieve the login name of the remote user.  Undef if it could not be
  -determined
  -
  -  $ret = $r->get_remote_logname();
  +  $remote_logname = $r->get_remote_logname();
   
   =over 4
   
  @@ -302,25 +341,33 @@
   
   The current request
   
  -=item ret: C<$ret> (string)
  +=item ret: C<$remote_logname> ( string )
   
  -The user logged in to the client machine
  +The username of the user logged in to the client machine, or an empty
  +string if it could not be determined via RFC1413, which involves
  +querying the client's identd or auth daemon.
   
   =item since: 1.99_12
   
   =back
   
  +Do not confuse this method with
  +C<L<$r-E<gt>user|docs::2.0::api::Apache::RequestRec/C_user_>>, which
  +provides the username provided by the user during the server
  +authentication.
   
   
   
   
  -=head2 C<note_auth_failure>
   
  -META: Autogenerated - needs to be reviewed/completed
  +
  +
  +
  +=head2 C<note_auth_failure>
   
   Setup the output headers so that the client knows how to authenticate
  -itself the next time, if an authentication request failed.  This function
  -works for both basic and digest authentication
  +itself the next time, if an authentication request failed.  This
  +function works for both basic and digest authentication
   
     $r->note_auth_failure();
   
  @@ -337,17 +384,24 @@
   
   =back
   
  +This method requires C<AuthType> to be set to C<Basic> or
  +C<Digest>. Depending on the setting it'll call either
  +C<L<$r-E<gt>note_basic_auth_failure|/C_note_basic_auth_failure_>> or
  +C<L<$r-E<gt>note_digest_auth_failure|/C_note_digest_auth_failure_>>.
  +
  +
   
   
   
   
  -=head2 C<note_basic_auth_failure>
   
  -META: Autogenerated - needs to be reviewed/completed
  +
  +
  +=head2 C<note_basic_auth_failure>
   
   Setup the output headers so that the client knows how to authenticate
  -itself the next time, if an authentication request failed.  This function
  -works only for basic authentication
  +itself the next time, if an authentication request failed.  This
  +function works only for basic authentication
   
     $r->note_basic_auth_failure();
   
  @@ -368,13 +422,15 @@
   
   
   
  -=head2 C<note_digest_auth_failure>
   
  -META: Autogenerated - needs to be reviewed/completed
  +
  +
  +
  +=head2 C<note_digest_auth_failure>
   
   Setup the output headers so that the client knows how to authenticate
  -itself the next time, if an authentication request failed.  This function
  -works only for digest authentication
  +itself the next time, if an authentication request failed.  This
  +function works only for digest authentication.
   
     $r->note_digest_auth_failure();
   
  @@ -395,20 +451,126 @@
   
   
   
  +
  +
   =head2 C<requires>
   
  +Retrieve information about all of the requires directives for this request
  +
  +  $requires = $r->requires
  +
  +=over 4
  +
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
  +The current request
   
  +=item ret: C<$requires> ( ARRAY ref )
   
  +Returns an array reference of hash references, containing information
  +related to the C<require> directive.
   
  +=item since: 1.99_12
   
  -=head2 C<satisfies>
  +=back
  +
  +This is normally used for access control.
  +
  +For example if the configuration had the following require directives:
  +
  +    Require user  goo bar
  +    Require group bar tar
  +
  +this method will return the following datastructure:
  +
  +  [
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'user goo bar'
  +    },
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'group bar tar'
  +    }
  +  ];
  +
  +The I<requirement> field is what was passed to the C<Require>
  +directive.  The I<method_mask> field is a bitmask which can be
  +modified by the C<Limit> directive, but normally it can be safely
  +ignored as it's mostly used internally. For example if the
  +configuration was:
  +
  +    Require user goo bar
  +    Require group bar tar
  +    <Limit POST>
  +       Require valid-user
  +    </Limit>
  +
  +and the request method was C<POST>, C<$r-E<gt>requires> will return:
  +
  +  [
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'user goo bar'
  +    },
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'group bar tar'
  +    }
  +    {
  +      'method_mask' => 4,
  +      'requirement' => 'valid-user'
  +    }
  +  ];
  +
  +But if the request method was C<GET>, it will return only:
  +
  +  [
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'user goo bar'
  +    },
  +    {
  +      'method_mask' => -1,
  +      'requirement' => 'group bar tar'
  +    }
  +  ];
   
  -META: Autogenerated - needs to be reviewed/completed
  +As you can see Apache gives you the requirements relevant for the
  +current request, so the I<method_mask> is irrelevant.
   
  -How the requires lines must be met.
  +It is also a good time to remind that in the general case, access
  +control directives should not be placed within a E<lt>LimitE<gt>
  +section.  Refer to the Apache documentation for more information.
   
  -  $ret = $r->satisfies();
  +Using the same configuration and assuming that the request was of type
  +POST, the following code inside an Auth handler:
  +
  +  my %require =
  +      map { my($k, $v) = split /\s+/, $_->{requirement}, 2; ($k, $v||'') }
  +      @{ $r->requires };
  +
  +will populate C<%require> with the following pairs:
  +
  +  'group' => 'bar tar',
  +  'user' => 'goo bar',
  +  'valid-user' => '',
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<satisfies>
  +
  +How the requires lines must be met. What's the applicable value of the
  +C<Satisfy> directive:
  +
  +  $satisfy = $r->satisfies();
   
   =over 4
   
  @@ -417,30 +579,33 @@
   
   The current request
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$satisfy> ( integer )
   
  -How the requirements must be met.  One of:
  +How the requirements must be met.  One of the C<L<Apache::Const
  +:satisfy constants|docs::2.0::api::Apache::Const/C__satisfy_>>:
   
  -  Apache::SATISFY_ANY    -- any of the requirements must be met.
  -  Apache::SATISFY_ALL    -- all of the requirements must be met.
  -  Apache::SATISFY_NOSPEC -- There are no applicable satisfy lines
  +C<L<Apache::SATISFY_ANY|docs::2.0::api::Apache::Const/C_Apache::SATISFY_ANY_>>,
  +C<L<Apache::SATISFY_ALL|docs::2.0::api::Apache::Const/C_Apache::SATISFY_ALL_>>
  +and
  +C<L<Apache::SATISFY_NOSPEC|docs::2.0::api::Apache::Const/C_Apache::SATISFY_NOSPEC_>>.
   
   =item since: 1.99_12
   
   =back
   
  +See the documentation for the C<Satisfy> directive in the Apache
  +documentation.
   
   
   
   
  -=head2 C<some_auth_required>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<some_auth_required>
   
  -Can be used within any handler to determine if any authentication
  -is required for the current request
  +Can be used within any handler to determine if any authentication is
  +required for the current request:
   
  -  $ret = $r->some_auth_required();
  +  $need_auth = $r->some_auth_required();
   
   =over 4
   
  @@ -449,9 +614,9 @@
   
   The current request
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$need_auth> ( boolean )
   
  -1 if authentication is required, 0 otherwise
  +TRUE if authentication is required, FALSE otherwise
   
   =item since: 1.99_12
   
  
  
  
  1.16      +6 -2      modperl-docs/src/docs/2.0/api/Apache/Const.pod
  
  Index: Const.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/Const.pod,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -u -r1.15 -r1.16
  --- Const.pod	8 Aug 2004 18:26:20 -0000	1.15
  +++ Const.pod	9 Aug 2004 00:26:23 -0000	1.16
  @@ -2267,7 +2267,8 @@
   
     use Apache::Const -compile => qw(:satisfy);
   
  -The C<:satisfy> group is for XXX constants.
  +The C<:satisfy> constants group is used in conjunction with
  +C<L<$r-E<gt>satisfies|docs::2.0::api::Apache::Access/C_satisfies_>>.
   
   
   
  @@ -2280,7 +2281,7 @@
   
   =back
   
  -
  +All of the requirements must be met.
   
   
   
  @@ -2292,6 +2293,7 @@
   
   =back
   
  +any of the requirements must be met.
   
   
   
  @@ -2303,6 +2305,8 @@
   =item since: 1.99_12
   
   =back
  +
  +There are no applicable satisfy lines
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message