view release on metacpan or  search on metacpan

lib/Apache2/AuthCookie/Base.pm  view on Meta::CPAN

    my $auth_type = $r->auth_type;
    my $auth_name = $r->auth_name;

    my $cookie_name = $r->dir_config("${auth_name}CookieName") ||
                      "${auth_type}_${auth_name}";

    return $cookie_name;
}


sub cookie_string {
    my $self = shift;
    my %p = @_;
    for (qw/request key/) {
        croak "missing required parameter $_" unless defined $p{$_};
    }
    # its okay if value is undef here.

    my $r = $p{request};

    $p{value} = '' unless defined $p{value};

    my $string = sprintf '%s=%s', @p{'key','value'};

    my $auth_name = $r->auth_name;

    if (my $expires = $p{expires} || $r->dir_config("${auth_name}Expires")) {
        $expires = Apache::AuthCookie::Util::expires($expires);
        $string .= "; expires=$expires";
    }

    $string .= '; path=' . ( $self->get_cookie_path($r) || '/' );

    if (my $domain = $r->dir_config("${auth_name}Domain")) {
        $string .= "; domain=$domain";
    }

    if ($r->dir_config("${auth_name}Secure")) {
        $string .= '; secure';
    }

    # HttpOnly is an MS extension.  See
    # http://msdn.microsoft.com/workshop/author/dhtml/httponly_cookies.asp
    if ($r->dir_config("${auth_name}HttpOnly")) {
        $string .= '; HttpOnly';
    }

    # SameSite is an anti-CSRF cookie property.  See
    # https://www.owasp.org/index.php/SameSite
    if (my $samesite = $r->dir_config("${auth_name}SameSite")) {
        if ($samesite =~ /\A(strict|lax)\z/i) {
            $samesite = lc($1);
            $string .= "; SameSite=$samesite";
        }
    }

    return $string;
}


sub decoded_requires {
    my ($self, $r) = @_;

    my $reqs     = $r->requires or return;
    my $encoding = $self->requires_encoding($r);

    unless (is_blank($encoding)) {
        for my $req (@$reqs) {
            $$req{requirement} = Encode::decode($encoding, $$req{requirement});
        }
    }

    return $reqs;
}


sub decoded_user {
    my ($self, $r) = @_;

    my $user = $r->user;

    if (is_blank($user)) {
        return $user;
    }

    my $encoding = $self->encoding($r);

    if (!is_blank($encoding)) {
        $user = Encode::decode($encoding, $user);
    }

    return $user;
}


sub encoding {
    my ($self, $r) = @_;

    my $auth_name = $r->auth_name;

    return $r->dir_config("${auth_name}Encoding");
}


sub escape_uri {
    my ($r, $string) = @_;
    return Apache2::Util::escape_path($string, $r->pool);
}


sub get_cookie_path {
    my ($self, $r) = @_;

    my $auth_name = $r->auth_name;

    return $r->dir_config("${auth_name}Path");
}


sub handle_cache {
    my ($self, $r) = @_;

    my $auth_name = $r->auth_name;

    return unless $auth_name;

    unless ($r->dir_config("${auth_name}Cache")) {
        $r->no_cache(1);
        $r->err_headers_out->set(Pragma => 'no-cache');
    }
}


sub key {
    my ($self, $r) = @_;

    my $cookie_name = $self->cookie_name($r);

lib/Apache2/AuthCookie/Base.pm  view on Meta::CPAN

=head1 NAME

Apache2::AuthCookie::Base - Common Methods Shared by Apache2 and Apache2_4 AuthCookie Subclasses.

=head1 VERSION

version 3.32

=head1 DESCRIPTION

This module contains common code shared by AuthCookie for Apache 2.x and Apache 2.4.

=head1 METHODS

=head2 authenticate($r): int

This method is one you'll use in a server config file (httpd.conf, .htaccess,
...) as a PerlAuthenHandler.  If the user provided a session key in a cookie,
the C<authen_ses_key()> method will get called to check whether the key is
valid.  If not, or if there is no key provided, we redirect to the login form.

=head2 cookie_name($r): string

Return the name of the auth cookie for this request.  This is either
C<${auth_name}CookieName>, or AuthCookie's self generated name.

=head2 cookie_string(%args): string

Generate a cookie string. C<%args> are:

=over 4

=item *

request

The Apache request object

=item *

key

The Cookie name

=item *

value

the Cookie value

=item *

expires (optional)

When the cookie expires. See L<Apache::AuthCookie::Util/expires()>.  Uses C<${auth_name}Expires> if not giv

=back

All other cookie settings come from C<PerlSetVar> settings.

=head2 decoded_requires($r): arrayref

This method returns the C<< $r->requires >> array, with the C<requirement>
values decoded if C<${auth_name}RequiresEncoding> is in effect for this
request.

=head2 decoded_user($r): string

If you have set ${auth_name}Encoding, then this will return the decoded value of
C<< $r-E<gt>user >>.

=head2 encoding($r): string

Return the ${auth_name}Encoding setting that is in effect for this request.

=head2 escape_uri($r, $value): string

Escape the given string so it is suitable to be used in a URL.

=head2 get_cookie_path($r): string

Returns the value of C<PerlSetVar ${auth_name}Path>.

=head2 handle_cache($r): void

If C<${auth_name}Cache> is defined, this sets up the response so that the
client will not cache the result.  This sents C<no_cache> in the apache request
object and sends the appropriate headers so that the client will not cache the
response.

=head2 key($r): string

This method will return the current session key, if any.  This can be handy
inside a method that implements a C<require> directive check (like the
C<species> method discussed above) if you put any extra information like
clearances or whatever into the session key.

=head2 login($r): int

This method handles the submission of the login form.  It will call the
C<authen_cred()> method, passing it C<$r> and all the submitted data with names
like C<credential_#>, where # is a number.  These will be passed in a simple
array, so the prototype is C<$self-E<gt>authen_cred($r, @credentials)>.  After
calling C<authen_cred()>, we set the user's cookie and redirect to the URL
contained in the C<destination> submitted form field.

=head2 login_form($r): int

This method is responsible for displaying the login form. The default
implementation will make an internal redirect and display the URL you specified
with the C<PerlSetVar WhatEverLoginScript> configuration directive. You can
overwrite this method to provide your own mechanism.

=head2 login_form_status($r): int

This method returns the HTTP status code that will be returned with the login
form response.  The default behaviour is to return HTTP_FORBIDDEN, except for
some known browsers which ignore HTML content for HTTP_FORBIDDEN responses
(e.g.: SymbianOS).  You can override this method to return custom codes.

Note that HTTP_FORBIDDEN is the most correct code to return as the given
request was not authorized to view the requested page.  You should only change
this if HTTP_FORBIDDEN does not work.

=head2 logout($r): void

This is simply a convenience method that unsets the session key for you.  You
can call it in your logout scripts.  Usually this looks like
C<$r-E<gt>auth_type-E<gt>logout($r)>.