readme

cas 客户端文件

MOD_CAS INTRODUCTION

Mod_cas, the Apache module to protect static and dynamic content with CAS,
is in wide use at Yale and elsewhere; the code base, however, is not as
clean as the rest of the CAS distribution.

BUILDING

Mod_cas requires OpenSSL libraries to be installed in a path known to the
loader (and OpenSSL header files in a path known to the compiler).  To
build this version of mod_cas for Apache 2.x, perform the following steps:

 1) Edit the contents of cas.h to include your CAS server's configuration
 2) Install the contents of this directory beneath the 'modules' directory
    in Apache's source tree.
 3) Change to the root directory of Apache's source distribution and run
    ./buildconf
 4) Run ./configure --enable-cas (you will want --enable-cas=shared to
    build the dynamic shared object, mod_cas.so)
 5) Run make; this will build your server and mod_cas
 6) mod_cas.so will be located in modules/cas/.libs beneath Apache's
    server

INSTALLATION

To use the CAS module (mod_cas), mod_cas.so should be installed in an
appropriate path (typically the 'libexec' directory under the Apache
server root) and loaded with lines like

	LoadModule cas_module         modules/mod_cas.so

This syntax requires that the Apache server be configured with DSO
(Dynamic Shared Object) support.  See

	http://httpd.apache.org/docs/dso.html

for more information.

Furthermore, you must install the 'verisignserverca.pem' file (or a
corresponding CA certificaate for the signer of your CAS server) in the
location compiled into ssl_client.c (/usr/local/etc/verisignserverca.pem
by default) and make these files publicly readable.  These files allow CAS
ticket validation to proceed securely; right now, their locations arenot
configurable at runtime, but they should be.

You may also need to install the mod_dir.so module included with this
distribution (over the existing, standard one) if you want to use mod_cas
to protect entire directories and support directory indexing (e.g.,
automatic generation of HTML to list a directory's contents) seamlessly.

For the CAS module to be triggered, the AuthType must be set to "CAS" with
a line like

	AuthType CAS

in the server configuration (httpd.conf) file or a local .htaccess file.
The "Require" directive is supported with two modes: "valid-user," which
allows any CAS-authenticated user access to the protected resource, and
"user XXXX YYYY ZZZZ ....," where a list of authorized users is enumerated
on the command line.  Support for groups of users is forthcoming and may
depend on the nascent "Central Authorization Server," which acts as a
switch for access-control logic.

CONFIGURATION

For mod_cas, the following parameters are additionally supported in the
central configuration file but are not allowed in .htaccess; they are
intended to be set only be the server administrator and, with the
exception of CASLocalCacheInsecure, only once per server:

    CASLocalCacheFile

	A full pathname to a file that stores the local ticket cache.
	The directory containing this file should be writable
	by the web server.  Note that this requirement suggests that
	unrestricted CGI access given to end users may not be appropriate
	for a server that uses this module; the file should be kept
	private from all unprivileged users since it provides for the
	ability to impersonate users to the web server.

	There is no default value; if this parameter is not present,
	no ticket cache is used, and the other cache-related parameters
	are ignored.  A ticket cache is not necessary for mod_cas to
	function successfully; however, without a cache, the user needs
	to be redirected to CAS for every HTTP request.

    CASLocalCacheSize

	The number of tickets that are kept simultaneously in the cache,
	which is used to store session state to avoid excessive
	redirections back to CAS.  This value can be quite large, as
	the size of each entry is small (considerably less than 100
	bytes).

	The default value is 1000, which yields a cache file (and
	extra memory-usage by the web server) of about 40k.

    CASLocalCacheTimeout

	The extent in time (in seconds) of each cached ticket.  After
	this time runs out, the user's authenticated status is no longer
	cached, and the user must be redirected to CAS to establish
	"secondary" authentication again (where "primary" authentication
	is what CAS performs and "tertiary" authentication is based on
	the "tickets" we cache in the web server).

	The default value is 3600 (one hour).

     CASLocalCacheInsecure

	The cache works with both "secure" and "insecure" cookies.
	"Secure," in this context, has only browser-dependent meaning (see
	RFC 2109), but most browsers refuse to send "secure" cookies for
	requests that aren't for HTTPS URLs.

	This option is intended to be used to differentiate a secure
	virtual server from an insecure one.  Setting it "Off," which
	is the default, implies two things:  (a) the cookies that we
	send if preauthentication is handled in the current virtual
	server are marked "Secure," and (b) the ticket this cookie
	stores is internally recorded as a secure cookie.  Setting it
	"On" implies that cookies are NOT marked secure and that the
	tickets are marked "insecure" internally.

	The reason for this is to allow the same ticket cache to be
	used by a server that vends both SSL-protected and SSL-unprotected
	pages.  This option effectively segments the ticket cache, requiring
	one CAS authentication in "secure" space and one CAS authentication
	in "insecure" space.  That may seem pointless, for a user with
	CAS credentials can clearly authenticate in both contexts, but the
	rationale for this design is that a cookie used by mod_cas that
	proves preauthenticated status in a secure context should never be
	sent in the clear.  Likewise, a cookie generated by
	preauthentication to an insecure service should not be used by a
	secure service, lest the user be given a false sense of security
	(or an attacker be given a "back door" into a secure session).
	If used correctly, the end result of this option is that an
	attacker with access to the plaintext data stream of a user's
	HTTP session can never spoof the user's HTTPS session.

	NOTE:  When this option is set to "On," then individual users'
	sessions can be spoofed by someone with access to the plaintext
	stream that connects the two servers.  This is worth keeping in
	mind since it introduces a new vulnerability which may be
	acceptable in some cases but should be understood in ALL cases.
	(This vulnerability is no different from the one affecting
	the session-maintenance mechanism of a typical Java servlet
	container or other application environment.)

	ALSO NOTE:  This option is used to determine whether to use
	"http" or "https" as our callback scheme. Automatic detection of
	SSL isn't present since multiple modules can provide SSL but
	are implemented differently.  Therefore you must specify this
	option when not using SSL, irrespective of whether or not
	CASLocalCacheFile is specified.

    CASEGDFile

        If unspecified, mod_cas will use /dev/urandom as a source of
        entropy.  If this value is specified, it will use the EGD,
        accessed at the socket given by full file path (e.g.,
        /etc/egd-pool) specified by CASEGDFile.

        This feature has not yet been thoroughly tested, so we cannot
        yet guarantee its security; using /dev/urandom on systems that
        provide it (and installing it via kernel patches on systems that
        don't) is probably still a cleaner solution than using the EGD.