view release on metacpan or  search on metacpan

SecSess.pm  view on Meta::CPAN

sub requested_uri {
	my $self = shift;
	my($r) = @_;
	my($u, %args, $requrl);

	%args = $r->args;
	unless ($requrl = $args{url}) { # will already be wrapped
		$u = Apache::URI->parse($r);
		$requrl = $self->wrap_uri($u->unparse);
	}
	return $requrl;
}

## (un)wrap a URI, with more armor than Apache::Util::escape_uri
sub wrap_uri {
	my $self = shift;
	my($u) = @_;
	$u = encode_base64($u, '');
    $u =~ tr/\+\/\=/-._/;
	return $u;
}
sub unwrap_uri {
	my $self = shift;
	my($u) = @_;
    $u =~ tr/\-\.\_/+\/=/;
	return decode_base64($u);
}

1;

__END__

#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
# 		Man Page
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
#

=head1 NAME

Apache::SecSess - Secure Apache session management library

=head1 SYNOPSIS

  In startup.pl,

    $My::obj = Apache::SecSess::Cookie::X509->new(...)

  In httpd.conf,

    <Location /protected>
      PerlAuthenHandler $My::obj->authen
      ...
    </Location>

  See section EXAMPLE below for more details.

=head1 DESCRIPTION

This package is a software library for managing HTTP and HTTPS 
session security within the Apache mod_perl framework.  It offers the 
flexibility to securely configure distributed web services, across 
multiple hosts and domains, consistent with a common security policy.

In a complex environment, there could be several Perl objects whose 
methods are specific Apache phase handlers designed to manage a user's 
session lifecycle, including: initiating, renewing and terminating the
session.  Each of these objects is an instance of some subclass of 
Apache::SecSess, which treats a particular security paradigm.

=head1 CLASS HIERARCHY

Below is a diagram of the class hierarchy

  SecSess
   `+-Cookie
    | `+--BasicAuth (for debugging)
    |  +--LoginForm
    |  +--X509
    |  +--X509PIN
    |  `--URL
    `-URL
      `---Cookie

SecSess contains (in addition to common code) all Apache phase handlers
(Currently only  PerlAuthenHandler are needed).  At this level credentials
and status are considered opaque objects. The important methods are:

->authen() Used to protect underlying resources.  Checks credentials for freshness and validity.

->issue()  Used as the "initial" identity authentication before issuing credentials (cookies or mangled URLs) used by ->authen().

->renew()  Will re-issue credentials if proper conditions are satisfied

->delete() Will delete credentials where relevant (i.e. deletes cookies).

At one level beneath SecSess (SecSess::Cookie.pm and SecSess::URL.pm),
are the methods for interpreting and manipulating credentials.

At the lowest level, are subclasses which "know" how to interpret the
*initial* identifying information during the issuance of credentials.
So, *::Cookie::LoginForm presents the client with a user/password
login form for identification.  And thus the difference between 
*::Cookie::URL and *::URL::Cookie is that the former will issue cookies
after validating an URL credential, and the latter will "issue" an URL
credential (typically it will redirect to a resource with realm=cred in
the URL) after validating a cookie.

=head1 CREDENTIAL FORMAT

Credentials in Apache::SecSess have a similar format:

    URL Credentials (defined in Apache::SecSess::URL):
        realm=E_k(md5(hash),hash)

    Cookie Credentials: (defined in Apache::SecSess::Cookie):
        realm:qop,authqop=E_k(md5(hash),hash)

The string 'realm' is any symbol (without obvious special characters 
':', '=', etc) which is used to identify cooperating security services,
thus providing a way to put credentials into their own namespace.