view release on metacpan or  search on metacpan

SecSess.pm  view on Meta::CPAN

=head2 Credential Arguments

  authRealm => <realm>

Defines string 'realm' as identifying tag for credentials as described
above in CREDENTIAL FORMAT.

  secretFile => <filename>

The first line of this file is used to create the secret encryption 
key for credentials as described above in CREDENTIAL FORMAT.  This
secret key is never given to users and should never leave the system
servers.

=head2 Timing Arguments

  lifeTime => <minutes>

Session will expire after the specified number of minutes.

  idleTime => <minutes> 

A session idle for the specified number of minutes will time out.

  renewRate => <minutes>

A session which is constantly active will have a transparent
renewal (resetting an implicit 'idle timer') every period of the 
specified number of minutes.

=head2 Quality of Protection Arguments

minSessQOP => 128, minAuthQOP => 128, authQOP => 128, sessQOP => 128

When credentials are validated during a request, two checks of the 
qualities of protection (QOP's) are made, namely that

        qop >= minSessQOP
and 
        authqop >= minAuthQOP

where qop and authqop indicate the session and user authentication 
protection or strength roughly measured in bits.  They are the signed 
values appearing *inside* the credential hash described above.  In the 
case of cookies, where multiple credentials with different security 
levels are may be present at request time, only the strongest credentials 
are used to make this determination.  (The cleartext pairs (qop,authqop) 
are sorted lexicographically to determine which cookies to use.  The
cleartext values are not trusted.)
  
The QOP parameters are separated to allow flexibility in the threat model.
In the simplest paradigm (and first demo examples), qop=0 and authqop=40, 
which merely indicates that the user ID's and passwords are protected with 
SSL but the web docs acquired with them are not.  This is somewhat common 
over intranets.  Under the stronger threat model of an active adversary
who controls the untrusted network, true end-to-end security is 
required, but we may still wish to separate session and authentication 
qualities of protection.  For example, if all SSL sessions never drop
below 128-bits, we may still choose to allow weaker strength during user 
authentication, say with a 20-bit PIN or one-time password.  Scientific 
cryptography cannot always afford to distinguish between an attack which 
costs 2^20 computations and one which succeeds with probability 1/2^20, 
because with 1 million users, the two situations are identical.  But, for
practical risk assessment, it may be perfectly acceptable to trade strong
session credentials for weak login credentials.

The values of qop and authqop issued are determined by the
Apache::SecSess object in all cases.  For URL credentials they come
directly from arguments sessQOP and authQOP, respectively.  For cookie
credentials, they come from the hash keys of the argument cookieDomain
described below.
 
Note that no attempt is made to check the correctness of the QOP
settings against the values of the httpd.conf directive SSLCipherSuite.
This would be mistake in fact because the session strength is dependent
on global factors as described in README.  Nevertheless, you should 
check your assumptions about your local site's openssl with the script 
utils/minstren which prints the weakest cipher strength for common 
SSLCipherSuite arguments.  At my site, I was surprised to find 
ALL:!ADH:!EXP:!EXP56 => 56 bits.

=head2 Cookie Domain Argument

  cookieDomain => <hashref>

The cookieDomain argument expects a hash reference of the form:

        { 'qop,authqop' => 'domain_string', ...  }

where 'domain_string' is literally the HTTP Set-Cookie domain string, and 
where the integers 'qop' and 'authqop' serve to define the session and 
authentication qualities of protections as described above.  A cookie will
be issued with the given domain and of the given strengths for each entry
in this hash.  The HTTP Set-Cookie secure flag is set if and only if 'qop' 
is nonzero.  As a convenient shorthand,

        int => 'domain_string'

is equivalent to

        'int,int' => 'domain_string'

Here are some examples taken from the demo.

      cookieDomain => {0 => '.acme.com', 40 => '.acme.com'}

will set two cookies for the .acme.com domain: a non-secure one of
form 'realm:0,0=value', and a secure one of form 'realm:40,40=value'.

      cookieDomain => {'0,40' => 'lysander.acme.com'}

will set a single non-secure cookie for the given host.  This is a
common paradigm for protecting passwords over an intranet.

      cookieDomain => {
        0 => '.acme.com',
        40 => '.acme.com',           # weak wildcard domain
        '64,128' => '.sec.acme.com', # stronger wildcard domain
        128 => 'milt.sec.acme.com'
      }

SecSess.pm  view on Meta::CPAN

  </Location>

where the authen() method is of an object of class 
Apache::SecSess::Cookie::URL instantiated as: 

  $Acme::noam = Apache::SecSess::Cookie::URL->new(
    dbo => Apache::SecSess::DBI->new(...),
    secretFile => 'ckysec.txt',
    lifeTime => 1440, idleTime => 60, renewRate => 5,
    minSessQOP => 128, minAuthQOP => 128,
    authRealm => 'Acme',
    cookieDomain => { 128 => 'noam.acme.org' },
    authenURL => 'https://stu.transacme.com/chain',
    defaultURL => 'https://noam.acme.org/protected',
    renewURL => 'https://noam.acme.org/renew',
    timeoutURL => 'https://noam.acme.org/signout/timeout.html'
  );
  
Like any other subclass of Apache::SecSess::Cookie, URL.pm will
issue cookies based on the presentation of some identifying information,
and authenURL defines where to go to get that information.  The difference
is that it now points to a new DNS domain: stu.transacme.com.  

That 'remote login' is protected by

  <Location /chain>
    PerlAuthenHandler $Acme::chain->issue
  	...
  </Location> 

i.e., the issue() method of the object $Acme::chain which is instantiated
as

  $Acme::chain = Apache::SecSess::URL::Cookie->new(
    dbo => Apache::SecSess::DBI->new(...),
    secretFile => 'ckysec.txt',
    lifeTime => 1440, idleTime => 60, renewRate => 5,
    sessQOP => 128, authQOP => 128,
    minSessQOP => 128, minAuthQOP => 128,
    authRealm => 'Acme',
    authenURL => 'https://stu.transacme.com/authen',
    chainURLS => [
      'https://milt.sec.acme.com/authen', 
      'https://noam.acme.org/authen'
    ],
    issueURL => 'https://stu.transacme.com/chain',
    defaultURL => 'https://stu.transacme.com/protected',
    renewURL => 'https://stu.transacme.com/renew',
    timeoutURL => 'https://stu.transacme.com/signout/timeout.html'
  );

If no cookies are present, the client will be redirected again to
https://stu.transacme.com/authen or the issue() method of a standard
Cookie-based login:

  <Location /authen>
    PerlAuthenHandler $Acme::stu->issue
    ...
  </Location>

where $Acme::stu is an instance of, say Apache::SecSess::Cookie::X509,
just as in the previous example.

But if and when cookies are present, $Acme::chain->issue will walk
through the URL's listed in the chainURLS argument eventually getting
to https://noam.acme.org/authen protected by

  <Location /authen>
    PerlAuthenHandler $Acme::noam->issue
    ...
  </Location>

which is the cookie issuing URL and issue() method, corresponding to the 
original request.

When all the URL-chaining is done, the issue() method of $Acme::chain,
will automatically redirect back to https://noam.acme.org/protected.

=head1 SEE ALSO

See the README in the original distribution for further security 
architecture and motivation.

See RFC2109 and RFC2965, which describe the HTTP cookie protocol, and 
RFC2964 (BCP44) which presents some important caveats.

See demo/httpdconf/startup.pl and corresponding .conf files for complete 
working examples.

=head1 AUTHORS

John Pliam (pliam@atbash.com) coding and crypto protocols.

Jim Krajewski (jimk@echosoft.com) tips and techniques too numerous to mention.

=cut