January 11, 2010

Process limiting in LTSP

Runaway processes can be a problem in LTSP systems. I've found in particular that Adobe's Acrobat Reader, Firefox, and flash can easily get out of control and suck up 100% of a processor. The cpulimit command (available in Ubuntu and Debian) can limit individual processes by intermittently forcing them to sleep. I wrote a small perl program to watch ongoing process usage and apply cpulimit to out of control processes as needed.

My script, cpu_governor, and the associated init.d startup script are here: cpu_governor.tgz. Let me know if you find any bugs. Thanks.

Posted by cayfo001 at 3:18 PM

July 3, 2008

U of MN Central Auth Mod_Perl2 Module

I've written a mod_perl2 module: UMN::CAH::Client::MP2 to work with UMN::CAH::Client::Store to provide a client implementation of the University of Minnesota Central Authentication Hub.

Currently ::MP2 is on version 0.0.3 and ::Store is on version 0.0.5. Both of these should still be considered ALPHA software, use it at your own risk. :)

You can find the latest version of ::Store here and the latest version of ::MP2 here.

Please feel free to send me your comments, questions or bug reports. Note that I did not implement a test suite with ::MP2 since I haven't figured out how to do it yet.

Below is the documentation (from the embedded POD).

NAME
    UMN::CAH::Client::MP2 - A mod_perl2 client implementation of the U of M
    single sign-on authentication.

VERSION
    This document describes UMN::CAH::Client::MP2 version 0.0.3

SYNOPSIS
  Recommended: using a persistent object:
      <perl>
        use UMN::CAH::Client::MP2;
        $Global::UMN::CAH::auth_object
          = UMN::CAH::Client::MP2
            ->new(
              allow_impersonation_by => [ 'cayfo001', ],
              acl_file => '/home/apache2/default_acl_file',
            );
      </Perl>

      <Directory /home/apache2/htdocs/restricted/>
        AuthType           Basic
        PerlAuthenHandler  $Global::UMN::CAH::auth_object->handler
        Require            valid-user
        PerlAuthzHandler   $Global::UMN::CAH::auth_object->handler
      </Directory>

  Alternative: using a new default object for each request:
      <Location /restricted_access>
        AuthType          Basic
        PerlAuthenHandler UMN::CAH::Client::MP2
        Require           valid-user
      </Location>

DESCRIPTION
    This is a mod_perl2 module to allow user authentication on the
    University of Minnesota's Central Authentication Hub (CAH, AKA
    "Cookieauth") single sign-on system. For more information on the CAH
    system and other implemenations please visit
    http://www1.umn.edu/is/cookieauth/.

    This module handles the mod_perl front-end to the authentication and
    authorization and relies on UMN::CAH::Client::Store to handle the
    back-end -- that is, the details of verifying client cookies against the
    U of M's servers and caching the responses.

    This module should be considered alpha software. It was developed on
    Debian and Ubuntu Linux and has only been tested under the Apache2
    prefork engine. I would welcome contributions and comments to fix bugs,
    make the code more portable, and any other general improvements.

INTERFACE
  new
    $object = UMN::CAH::Client::MP2->new( %config_options )

    Class method to create a new MP2 object. The object holds a link to the
    store and cache, so you should ideally call this in a Perl section of
    the apache config file. This same object can then be referenced without
    needing to create a new object again later.

    Each object is configured at creation. If different parts of your
    website need different configurations you can create multiple objects as
    needed.

    You can just use "UMN::CAH::Client::MP2" as an authentication handler as
    illustrated in the synopsis, but this will incur the object creation
    costs for each request and will only allow default configuration. Since
    there is no default acl_file, this method cannot be used as an
    authorization handler.

    The new method accepts named arguments to configure the object

    * acl_file
        Full path to file to use for authorization (only relevant if called
        in the PerlAuthzHandler). See below for the configuration
        information. Default: undef

    * allow_any_ip
        Array of IP addresses. Requests from these clients will not be
        checked for IP address consistency with the CAH cookie. Default: []

    * allow_impersonation_by
        Array of x500 ID's for clients who will be allowed to impersonate
        other clients on this website. See below for impersonation details.
        Default: []

    * https_port
        Port on which this webserver is running https. Any requests handled
        by the authentication object which are not under https will be
        redirected to the https port. Default: 443

    * auth_server
        The IP address or DNS name of the CAH server. Default: x500.umn.edu

    * auth_port
        The port on which to contact the CAH server. Default: 87

    * auth_modulename
        The X500 module to use for cookie authentication. Default: WEBCOOKIE

    * login_url
        The URL to which clients are directed to login to the U. Default:
        https://www.umn.edu/login

    * min_level
        Minimum acceptable authentication level. Default: 30

    * timeout_len
        Authentication timeout time in seconds. This is measured in time
        since the authentication cookie was originally created. This is not
        necessarily the same time as when the client first hit this website.
        Default: 10800 (three hours)

    * rolling_timeout_len
        Authentication timeout time in seconds since last activity on this
        authentication cache. Setting this to zero deactivates this feature.
        For example is set to 300, the authentication will be timed out if
        the user is not active on this website at least once every five
        minutes. Note that there no way to tell if they have been active on
        other U of M websites so this feature has limited usefulness.
        Default: 0 (inactive)

    * share_file
        Filename to provide to Cache::FastMmap as a cache file. Default:
        /tmp/UMN_CAH_Client_Store_Cache

    * enable_stats
        Passed through to Cache::FastMmap. Default: undef

    * expire_time
        Passed through to Cache::FastMmap. Default: undef

    * cache_size
        Passed through to Cache::FastMmap. Default: undef

    * page_size
        Passed through to Cache::FastMmap. Default: undef

    * num_pages
        Passed through to Cache::FastMmap. Default: undef

    * unlink_on_exit
        Passed through to Cache::FastMmap. Default: undef

  handler
    $object->handler

    The mod_perl entry point.

DIAGNOSTICS
    TODO

CONFIGURATION AND ENVIRONMENT
  ACL file
    The ACL file provides a very simple authorization mechanism. The file
    should be a sequence of lines where each line consists of one of two
    directives: "allow" or "deny", followed by white space and then either
    an x500 ID or the symbol "*". The ACL file is read from top to bottom
    and processing stops at the first line to match the current client's ID.
    The * will match any ID, so processing will never continue beyond a line
    with a * ID. If the matching line's directive is allow access is
    granted, otherwise it is denied. If processing reaches the end of the
    file without finding a match, access is denied by default. Blank lines
    are ignored as is anything on a line following the comment character: #.

    The ACL file is only consulted if UMN::CAH::Client::MP2 is called in the
    authorization phase (as a PerlAuthzHandler).

  Impersonation
    You can allow certain clients to impersonate others on a protected
    website. If the ID of the authenticated user matches one listed in the
    "allow_impersonation_by" option then they can choose to set the ID
    passed on to Apache and other applications to another string.

    Impersonation is done with a URL query in the form "impersonate=xxxxx".
    If the current authenticated user has impersonation permissions and the
    impersonate query is found in the current request then the effective ID
    associated with this authentication cookie is set to the specified
    string (xxxxx) and is used instead of the real ID to set Apache's user
    variable.

    A query of "impersonate=" (with an empty field after the = ) will reset
    the effective ID to that of the real user.

    The effect of this impersonation is limited to the area using the same
    authentication cache file. It has no effect on any other websites.

    Note that the authorization phase of UMN::CAH::Client::MP2 looks at the
    effective ID rather than the real ID and so will be affected by
    impersonation like any other script running under Apache.

DEPENDENCIES
     Test::More
     version
     Carp
     version
     UMN::CAH::Client::Store
     Apache2::RequestRec
     Apache2::RequestIO
     Apache2::Const
     Apache2::URI
     Apache2::Log
     Apache2::Connection
     APR::Request
     APR::URI
     ModPerl::Util
     Apache2::ModSSL

INCOMPATIBILITIES
    None reported.

BUGS AND LIMITATIONS
    Please report any bugs or feature requests to the author.

AUTHOR
    Steven Cayford "cayfo001@umn.edu"

LICENCE AND COPYRIGHT
    Copyright (c) 2008, Steven Cayford "<cayfo001@umn.edu>". All rights
    reserved.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
    BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
    EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
    ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
    YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
    NECESSARY SERVICING, REPAIR, OR CORRECTION.

    IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
    TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
    CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
    SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
    RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
    FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
    SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
    DAMAGES.
Posted by cayfo001 at 11:19 PM

June 20, 2008

New UMN central auth perl module

I've started working on a set of new perl modules to replace UMNCookieAuth. I've broken the backend and cacheing section of the module away from the mod_perl section, so the backend should be usable from any perl application and does not have to be embedded in apache.

I'm also trying to be more proactive about writing tests for my code so you should be able to run "make test" and have it tell you something meaningful.

So far I've completed what I think should be a functional backend. The primary module is UMN::CAH::Client::Store.pm. Store uses Cache::FastMmap to cache authentication lookups and refers to UMN::CAH::Client::Store::AuthHub.pm to handle the actual connection to the central auth hub. Cache::FastMmap is supposed to be cross-platform compatible now, so in theory this module will run on Windows in addition to the various *nix (it was developed on Debian) without any modifications. Please let me know if this is not the case.

This is ALPHA software.

You can find downloads of UMN::CAH::Client::Store here: UMN-CAH-Client-Store. You should be able to run "perl Makefile.PL; make; make test; make install". Read on for the perldocs:

NAME

UMN::CAH::Client::Store - A cacheing proxy object for the U of MN's
Central Authentication service.

VERSION

This document describes UMN::CAH::Client::Store version 0.0.3

SYNOPSIS

 use UMN::CAH::Client::Store;

 my $authhub = UMN::CAH::Client::Store::AuthHub->new();
 my $cookie_ref = $authhub->get_and_verify( 'EncodedCookieToken',
                                            {
                                              ip => '127.0.0.1',
                                            } );

 if ( $cookie_ref->{status} eq 'OK' ) {
   print( "Authenticated as user $cookie_ref->{euid}");
 }
 else {
   my $redirect_url = $authhub->redir_url( 'https://some.host.umn.edu/', $cookie_ref );
 }

DESCRIPTION

UMN::CAH::Client::Store creates a cacheing proxy object to handle the
interface to the University of Minnesota's Central Authentication Hub.
This module uses Cache::FastMmap and Store::AuthHub to handle the
cacheing and the connection to the authentication server.

INTERFACE

new

$object = Store->new( %options )

Returns a new Store object. You may specify the following named options:

 server => x500 server DNS name or IP address (x500.umn.edu by default),
 port => the port number on which to contact the server (87 by default),
 modulename => x500 module name to use (WEBCOOKIE by default),

 login_url    => url to redirect users to for login (default: https://www.umn.edu/login),
 min_level    => minimum authentication level accepted (default: 30),
 timeout_len  => authentication timeout in seconds (default: 10800),
 rolling_timeout_len => timeout since last activity in seconds (default: 0),

 share_file     => this and the following are passed through to Cache::FastMmap,
 enable_stats   =>
 expire_time    =>
 cache_size     =>
 page_size      =>
 num_pages      =>
 unlink_on_exit =>

authhub

$object = $store->authhub()

Accessor for the underlying Store::Authhub object created by new().

cache

$object = $store->cache()

Accessor for the underlying Cache::FastMmap object created by new().

get

$hash_ref = $store->get( 'token' )

Searches for the encoded cookie token in the cache or from the x500
server and returns a reference to a hash of the parsed response along
with a couple of extensions.

The resulting hash will have the following values: 

status => "OK|NO", # from x500 
level => "5|10|20|30|40|50", # from x500 
timestamp => time, #from x500 
ip => "xx.xx.xx.xx", # from x500 
id => "userid", # from x500
token => "encrypted string" # set by Store::AuthHub 
lastactive => time, # set by Store::AuthHub, updated by Store 
euid => "userid", # set by Store::AuthHub, updated by Store

The values for status, level, timestamp, ip, and id will come directly
from the server response. Other values are extensions of this module:
  token: the original encoded token,
  lastactive: the current timestamp updated for every get(),
  euid: a duplicate of the id field (the effective id)

If the status field is "NO" then the other fields will be blank or
undefined.

The "lastactive" field is ONLY updated if the "rolling_timeout_len"
option was specified when the store was created.

getandverify

$hash_ref = $store->get_and_verify( 'token', {requirements} )

Used to get and decode the token as the get() method and to confirm that
the IP address, authentication level, timeout, and rolling timeout are
all valid.

The requirements argument is a hash reference with optional arguments as
follows: 

ip => 'xx.xx.xx.xx'
ids => [ array of acceptable user ids ]

The hash returned by get_and_verify() will be the same as returned by
get() except that the status field may have the alternate values below:
IP: an IP mismatch LV: the authentication level is below minimum level
(min_level) EX: timeout or rolling timeout has expired ID: the cookie
euid was not in the ids list (if ids list provided)

Empty or undefined requirements are ignored.

redir_url

$url_string = $store->redir_url( 'callback url', $hash_ref )

A convenience method to get the appropriate url redirection given a
hashed cookie from get_and_verify().

A blank or undef hash_ref or one with "OK" or "NO" status will result in
a simple url redirection, other status codes will result in the
appropriate params added to the url.

set_euid

$hash_ref = $store->set_euid( 'token', 'id' )

Used for setting the euid in the cache, a blank or undef id resets it to
the real user. The first argument can be either the token or the cookie
hash itself. On success returns the new cookie, on failure returns
undef.

DIAGNOSTICS

"Error: minimum authentication level must be at least 10"

    According to the CAH documentation, sites should not accept level 5
    authentication so trying to do so will throw an error.

"Error: No token."

    Calling get or get_and_verify without a token throws an error.

"Error: invalid id list"

    Results from attempting to pass something other than an array ref to
    the "ids" requirement in get_and_verify.

"Error: SSL communication failure: %s"

    An error occurred when trying to contact the designated x500 server
    via SSL.

"Error: invalid response from x500 server: %s"

    The response from the server did not fit the pattern expected.

CONFIGURATION AND ENVIRONMENT

UMN::CAH::Client::Store requires no configuration files or environment
variables.

The cache file will by default be stored in UMN_CAH_Client_Store in the
temporary directory. The module uses File::Spec to attempt to be
OS-neutral, but I've only tested it on Debian so far.

DEPENDENCIES

 UMN::CAH::Client::Store::AuthHub
 Cache::FastMmap
 File::Spec;
 Net::SSLeay
 URI::Escape;

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to the author.

AUTHOR

Steven Cayford "<cayfo001@umn.edu>"

LICENCE AND COPYRIGHT

Copyright (c) 2008, Steven Cayford "<cayfo001@umn.edu>". All rights
reserved.

This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
Posted by cayfo001 at 4:43 PM

March 16, 2005

UMN::CookieAuth 0.1.4

Here's something I've written to imitate the University's apache cookieauth module using mod_perl. This is my first experiment with mod_perl, but it seems to work fairly well. Any comments are welcome.

Benefits:

  • You can use the included cookieauth_ctl script to browse the cookieauth shared memory cache to see what's being cached -- i.e. who's logged in.
  • You can set up your site to use local cookies which get their authentication from the central UMN authentication system, but thereafter don't grant access to any other UMN sites. Handy for dropping unneeded priviliges.
  • Easily hackable. (I mean: "easy to program extensions, etc." not "easy to crack"!)

Drawbacks

  • Probably slower than mod_cookieauth
  • Requires mod_perl

Download UMNCookieAuth-0.1.4.tgz

Here's the readme file:

NAME
    UMN::CookieAuth - Provides cookie authentication for apache 1.x via the
    University of Minnesota's central authentication system.

SYNOPSIS
     <Location /cookieauth>
       PerlAuthenHandler UMN::CookieAuth
       AuthType UMN::CookieAuth
       PerlAuthzHandler UMN::CookieAuth # optional if you're doing your own
                                        # authorization
       Require valid-user   # required lest apache
                            # skip the authentication
                            # phase altogether
       PerlSetVar <option name> "<option value>"
     </Location>

DESCRIPTION
    Provides cookie authentication against the University of Minnesota's
    cookieauth/x500 system for Apache 1.x using mod_perl. The authenticated
    user name will be placed in the Apache request object's "user" variable.

    Starting with version 0.1.4 the module will also do authorization if
    specified via PerlAuthzHandler and an ACL file is specified.

    This is beta software. It seems to work for me, but I wouldn't recommend
    deploying it anywhere without testing it yourself. This is my first
    attempt at doing something useful with mod_perl, so suggestions and/or
    criticism are welcome.

    This module is modeled after Chris Bongaarts' cookieauth module at
    http://www1.umn.edu/is/cookieauth/. Further documentation on the
    cookieauth system can be found there.

   Installation
    Place the UMN directory somewhere in perl's @INC path so mod_perl can
    find it. I use the "use lib" directive in a startup.pl script to add my
    modules directory to the path when running mod_perl, alternatively you
    could install it in system-wide perl module directory. If you want to
    use cookieauth_ctl, you'll need to place it in the parent directory of
    the UMN directory, install UMN::CookieAuth system-wide, or modify the
    script so it knows how to find the module.

    The first time the module is executed it will create a shared memory
    cache with permissions 0600. This cache will continue to exist even if
    you shut down apache. You can use the cookieauth_ctl script to browse
    the contents of the shared memory cache or ipcs and ipcrm to manipulate
    the shared memory. Note: to access the shared memory cookieauth_ctl will
    need to run as the web server user or root.

   Sequence of events
    If specified as a PerlAuthenHandler, UMN::CookieAuth will inspect each
    incoming request.

    First, if the request is plain http, the client is redirected to the
    secure port of the current server.

    If the request is over https, then we look for the authorization cookie.
    If the configuration specifies a local cookie (one set by us as
    described in "Local Cookies") then we'll look for that first and if
    unable to find it, fall back to the global cookie set by the central
    auth server. If no local cookie is specified we'll just look for the
    global cookie. If no cookies are found we'll redirect the client to the
    central auth login site.

    If we find a cookie we'll check in a cache in shared memory for it's
    decrypted value. If it's not already in the cache, we'll request it's
    decrypted value from the central auth server's X500 service and then
    store the decrypted value in the cache for the next request.

    If the cookie is invalid or expired, or the ip address does not match
    the client, or the authentication level is too low, then the client is
    redirected to the central auth login server.

    Otherwise if the cookie is good we set the apache user value to the user
    name retrieved from the decrypted cookie (which should be the user's UMN
    internet ID) and allow the client's request to proceed. If the
    configuration specifies to use a local cookie, there may be an
    additional redirect here simply to set the cookie with the remote
    browser.

    If the PerlAuthzHandler is specified, then we'll additionally look for
    the user name in an Access Control List file (see UMNCookieAuthACLFile).
    If the user is to be denied access we'll return a http forbidden
    response, otherwise access is granted and the request proceeds.

  CONFIGURATION OPTIONS
    Configuration options can be set in httpd.conf or .htaccess with the
    PerlSetVar directive. I've separated the options into two sections:
    "Things you may want to mess with" and "Things you probably don't want
    to mess with".

   Things you may want to mess with.
    UMNCookieAuthACLFile
        Default: "". Absolute path name to ACL file. The ACL file itself
        should be a series of line separated records in the form "allow
        {user_id}" or "deny {user_id}" (e.g. "allow cayfo001" or "deny
        cayfo001"). The special user_id value * matches all users. Upon
        finding a matching user_id the directive (allow or deny) is applied
        and the rest of the file is ignored. Falling off the end of the file
        without a match or failing to read the ACLFile both default to "deny
        *". Blank lines are ignored as is anything on a line following the
        comment character '#'. The ACLFile option is only applicable if you
        have specified UMN::CookieAuth as a PerlAuthzHandler, otherwise it
        will be ignored.

    UMNCookieAuthAllowAnyIP
        Default: "". Space or comma separated list of ip addresses for which
        we'll allow unmatched cookie ip addresses. Normally if the ip
        address encoded in the cookie does not match the remote client we
        reject the authentication and redirect them to the login site. If
        the remote client is coming through a load balancing proxy this
        could be a problem as their ip address would change.

    UMNCookieAuthDropUmnCookie
        Default: "never". Valid values are "never", "ifnew", and "always".
        See "Local Cookies".

    UMNCookieAuthHttpsPort
        Default: "443". HTTPS port for this server. If we get a plain http
        request we'll redirect to the current server using https on this
        port.

    UMNCookieAuthLevel
        Default: "30". U of M authentication level required to access the
        location. Values are 20 (new internet id password), 30 (standard
        internet id password), 40 (enterprise password), 50 (pgp)

    UMNCookieAuthLocalCookieName
        Default: "umnAuthV2Local". Name of the parallel cookie we may use
        for this local site. See "Local Cookies" below.

    UMNCookieAuthLogging
        Default: "1". Logging level, currently 0, 1, or 2 in increasing
        verbosity. Events should be reported in Apache's error.log.

    UMNCookieAuthMaxAge
        Default: "3600". Time in seconds until cookie expires. Retroactively
        calculated from the time the UM cookie was created.

    UMNCookieAuthMemoryKey
        Default: "UMCK". Four letter key for IPC shared memory cache. Once a
        cookie is decrypted, we store it in shared memory so all apache
        children can access it and save themselves a trip to the x500
        server. If you want to keep different servers separate you can use a
        different key here. Mostly useful for running a development version.
        If the module finds a shared memory cache at the specified key, but
        with a different cache version, it will increment the key and try
        again.

    UMNCookieAuthNewCookieLifetime
        Default: "300". Expiration time in seconds of the temporary cookie.

    UMNCookieAuthNewCookieName
        Default: "umnAuthTemp". Name of the one-shot, temporary cookie we
        use to track if this is a brand new login from the login server. See
        "Local Cookies" below.

    UMNCookieAuthUseLocalCookie
        Default: "never". Valid values are "never", "ifnew", and "always".
        See "Local Cookies".

   Things you probably don't want to mess with.
    These settings need to synchronize with the University's central
    authorization service so you probably won't want to tweak these unless
    that changes. Or if you've set up your own auth server.

    UMNCookieAuthCookieName
        Default: "umnAuthV2". Name of the authentication cookie doled out by
        the umn login server.

    UMNCookieAuthLoginSite
        Default: "https://www.umn.edu/login?desturl=%s". Site to redirect to
        for logins. The %s will be replaced by the url originally requested
        by the client.

    UMNCookieAuthQueryFormat
        Default: "WEBCOOKIE\t%s\n". How to format the query to the
        authentication server. The %s will be replaced by the encrypted
        cookie value. Currently recognized special characters are \t, \r,
        and \n. These should be spelled out as here, a literal \ followed by
        t, r, or n.

    UMNCookieAuthX500Host
        Default: "x500.umn.edu". X500 authentication server host. Used to
        decrypt the cookie value.

    UMNCookieAuthX500Port
        Default: "87". TCP port for x500 server.

  LOCAL COOKIES
    Local cookies are designed to allow a browser to access our site while
    dropping unneeded privileges to the rest of the university. Essentially
    we copy all the decrypted information from a valid global cookie into a
    cookie that we set ourselves and then--optionally--delete the global
    cookie. This leads to several configuration options based on the values
    of "UseLocalCookie" and "DropUmnCookie"

    If UseLocalCookie is set to "never" (the default) authentication will
    proceed as usual. The DropUmnCookie setting should have no effect in
    this case.

    If UseLocalCookie is set to "ifnew", then the module will look for the
    NewCookie, which should have been set during any redirection from here
    to the login site. If this NewCookie is found it is deleted and the
    LocalCookie is set instead with the same value and properties that are
    found in the primary UMN cookie. The local cookie will be used for
    authentication from then on. If this is not a new login, then
    authentication will revert to the UMN cookie.

    If UseLocalCookie is set to "always", then the local cookie will always
    be used even if we did not initiate the login process.

    If DropUmnCookie is set to "never" (the default) the UMN global cookie
    will not be affected. The remote user's browser will still hold a global
    cookie for the rest of the university.

    If DropUmnCookie is set to "ifnew", the UMN cookie will be deleted if we
    detect through the NewCookie that this is a new login initiated by us.
    This is probably the setting you want if you're using local cookies. If
    the remote user already had a global cookie (e.g. they logged into
    webmail before coming to our site), then they will still have global
    access after coming to our site.

    If DropUmnCookie is set to "always", the UMN cookie will be deleted
    regardless of how the authentication was initiated. This may cause some
    distress as any users will find themselves logged out of their
    pre-existing browser sessions after visiting our site.

  EXPORT
    None. This module uses the object oriented interface from mod_perl. If
    you want to use it without being under mod_perl (eg. to query the shared
    memory cache as the cookieauth_ctl script does) you can use
    UMN::CookieAuth->new() to give you a handler object, although anything
    that depends on mod_perl--such as setting cookies--will fail.

AUTHOR
    Steve Cayford <cayfo001 @ umn . edu>

REQUIRES
    Apache
    ssl
    mod_perl
    Apache::Constants
    Apache::Table
    Apache::URI
    Apache::Cookie
    Apache::Log
    CGI::Util
    IPC::ShareLite
    Storable
    Net::SSLeay

SEE ALSO
    *   cookieauth_ctl - Tool for examining the cookieauth shared memory
        cache. Needs work, though. Try 'cookieauth_ctl --help' for usage.

    *   Chris Bongaarts' apache module in C
        http://www1.umn.edu/is/cookieauth which inspired this perl
        version.

    *   mod_perl (http://apache.perl.org)

    *   perl (http://perl.org)

CHANGES
    0.1.4, 2005-03-14, by Steve
        Added ACLFile option and PerlAuthzHandler functionality. More
        documentation.

    0.1.3, 2005-02-01, by Steve
        Switched the whole module to an object. Improved logging. Added the
        whole local cookie concept, which meant rewriting the high level
        structure and probably introduced a bunch of new bugs. The shared
        memory cache is only cleaned based on a timer value, rather than
        every time through. Added AllowAnyIP option. Switched from
        Apache::Util::escape_uri() to CGI::Util::escape() -- not sure why
        Apache::Util wasn't working.

    0.1.2, 2004-12-30, by Steve
        Redirect to local https if http rather than straight to the login
        server.

    0.1.1, 2004-12-16, by Steve
        Pulled shared memory connection into a lexical variable reference in
        a function, added memory key config, added HttpsPort option, added
        documentation.

    0.1.0, 2004-10-28, by Steve
        Original working version.

BUGS
    Nothing serious that I'm aware of yet, but please contact me if you find
    anything.

TODO
    *   Perhaps a rolling timeout, where the timeout could be short (e.g. 5
        or 10 minutes), but each successful access resets the timeout. So
        this would timeout idle cookies, but not those making constant
        access. Along with this we'd probably need a timeout limit to force
        re-validation at some point.

    *   Do we need a separate CacheTimeout option to force re-validation of
        cookies as cookieauth does? I'm not sure what the security benefit
        is. This will need to use the LocalCookie value for the UMN cookie
        if necessary. And may require changing the clean_interval setting.

    *   Shared memory locking should be handled better. Need to use shared
        locks when possible.

    *   Should provide a "forbidden" page explaining the problem if
        credentials are too low or invalid IP rather than just redirecting
        to the login site.

    *   Should provide a logout method - especially for local cookies. Via
        the url? Perhaps just tack a ?UmnCookieAuthLogout on the end of the
        url. If we see this, delete the cookie(s) and redirect.

    *   Should there be an option to use a file as the cookie cache instead
        of shared memory?

    *   Suggestions?
Posted by cayfo001 at 4:49 PM