From cosign wiki

[edit] Cosign Authentication Filter Specification

[edit] Introduction

The Cosign authentication filter is an Apache API implementation that is installed on any web server using use a central Cosign server for authentication ( see diagram of Cosign for basic information ). This filter need not be installed on the central servers and does not accept user passwords.

Implementations of this filter exist for Apache 1.3.X, Apache 2.X, ISAPI, and J2EE 1.3 and 1.4.

These pages are based on the document Cosign Authentication Filter Specification, April 2006, Draft XII, by Johanna Bromberg Craig, Kevin McGowan, and Wesley Craig.

[edit] Module Layer

Upon receipt of a request, the Apache API Cosign authentication filter (mod_cosign) checks for the presence of a valid service cookie. If a cookie is presented by the user that matches a cookie in mod_cosign's local cookie database, then mod_cosign will communicate with cosignd to verify the cookie. These tests result in one of seven possible states:

cookie valid: The presented service cookie is valid, and the IP address is correct (only when enabled; will not work with firewalls/NAT). In addition, the presented username matches the username associated with this cookie, and the user is not currently logged out.
no cookie: The user has not presented a cookie for this service.
bad cookie: The service cookie presented by the user is not in the service's cookie database.
wrong ip: The user's IP address does not match that of the presented cookie. This check is optional and can be (or should be? is there an option to toggle this?) disabled for use behind firewalls and load balancers.
wrong user: The presented username does not match the username associated with this cookie.
logged out: The user has logged out from the central Cosign server.
unknown: An unexpected error has occurred.

[edit] Valid Cookie Response

When mod_cosign responds to the cookie valid state, it updates the time field in the cookie database and returns a value of DECLINED, indicating that, since all cookie checks have passed, the module declines to do anything further with the request. DECLINED causes the request to pass normally through the remainder of the request/response loop, and the requested resource is delivered normally. Before returning a value of DECLINED, mod_cosign must make the following environment variables available to the remainder of the request/response loop, including any child processes, such as CGI scripts, and embedded interpreters, such as mod_perl or php:

AUTHTYPE: "Cosign"
COSIGN_SERVICE: The Cosign service name that governs this directory or location.
REMOTE_USER: The username value of the authenticated user.
COSIGN_FACTOR: All of the factors that have been satisfied by the authenticated user.
REMOTE_REALM: The user's initial (first) authenticated factor (defined for backwards-compatibility).
KRB5CCNAME: If Kerberos is used: The path to the user's Kerberos 5 credentials.

[edit] Other Cookie Responses

When mod_cosign responds to any other cookie state, it generates a new, random service cookie value. New cookie values, which are generated by OpenSSL, are comprised of 128-character strings of random bytes, to which cosign-, and the service name defined by the CosignService directive, are prepended.

For example, a cookie generated with a CosignService value of example might look like the following:

cosign-example=oFxNMqPjNuSraSYoO8i+lIqDA9ZrzU1UDfsbp2JaHvm6mRP5jhRoIR...

In addition to the Cosign service name and the 128-charater string, the current time, in seconds, is appended to the end of the cookie when it is sent in the header; however, the current time is not included in the query string for redirect. When a cookie is retrieved from the browser, this time stamp is validated against the cookie's expire time, which defaults to 24 hours. If the cookie has expired, a new cookie is set. For example:

cosign-example=oFxNMqPjNuSraSYo...RP5jhR/1111088339

After generating a new cookie, mod_cosign then prints a set-cookie header with the service cookie and returns a value of REDIRECT. The user is redirected to the central CosignRedirect URL (see Apache Configuration) with the service cookie appended to the query string.

[edit] Data Storage Layer

The cookie database is implemented as a portion of the UNIX server's file system. A record is a normal file whose lookup key, or file name, is the random value issued as the user's service cookie value (see Module Layer). The data stored in each record includes:

username: The username value of the authenticated user. Identical to the value of REMOTE_USER.
realm: The first factor with which the user has authenticated.
factor: All factors with which the user has authenticated.
ip address: The IP address of the user's browser.
k5ticket: The path to the user's Kerberos 5 ticket (if applicable).
time: The last recorded validation time for the user (stored in the value of mtime.

[edit] Network Layer

The network layer of mod_cosign is responsible for:

Establishing and maintaining SSL-encrypted connections to the central cosignd server
Keeping status on connections
Implementing failover from one cosignd to another
Load balancing by randomizing IP addresses of available Cosign servers before beginning to establish new connections, and
Performing the actual protocol interaction with cosignd.

To be evaluated:

To further distinguish between re-tryable errors, we'd need to make cosignd return yet-another-class of return code, say 6xx or 1xx. In the 6xx case, the cosign clients should 1) retry other servers, but 2) if all fail it's a real error. This protects from the case where the server is inappropriately returning 6xx *and* the case where the client is causing the server to appropriately return 6xx.

If the filter cannot open a connection to all cosignd servers, or if it fails in the negotiation of an SSL-encrypted session with all cosignd servers, it returns a 503 "HTTP_SERVICE_UNAVAILABLE" error.

[edit] Protocol

An example session:

	CHECK service_cookie
	RETRIEVE service_cookie "tgt" | "cookies"
	STARTTLS [ 2 ]
	NOOP: no op.
	QUIT: quit

[edit] Apache Configuration

mod_cosign recognizes the following configuration directives:

[edit] CosignHostname

Syntax: CosignHostname fully-qualified-domain-name
Default: cosign.example.edu
Server configuration context: VirtualHost

[edit] CosignPort

Syntax: CosignService integer
Default: 6663
Server configuration context: VirtualHost, Location, Directory

[edit] CosignService

Syntax: CosignService service-name
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignRedirect

Syntax: CosignRedirect URL
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignPostErrorRedirect

Syntax: CosignPostErrorRedirect URL
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignRequireFactor

Syntax: CosignRequireFactor Factor1[Factor2...FactorN]
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignFactorSuffix

Syntax: CosignFactorSuffix FactorSuffix
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignFactorSuffixIgnore

Syntax: CosignFactorSuffixIgnore On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignFilterDB

Syntax: CosignFilterDB Path
Default: /var/cosign/filter
Server configuration context: VirtualHost

[edit] CosignProxyDB

Syntax: CosignProxyDB Path
Default: /var/cosign/proxy
Server configuration context: VirtualHost

[edit] CosignFilterHashLength

Syntax: CosignFilterHashLength 0|1|2
Default: 0
Server configuration context: VirtualHost

[edit] CosignTicketPrefix

Syntax: CosignTicketPrefix Path
Default: /ticket
Server configuration context: VirtualHost

[edit] CosignProtected

Syntax: CosignProtected On|Off
Default: On
Server configuration context: VirtualHost, Location, Directory, .htaccess

[edit] CosignSiteEntry

Syntax: CosignSiteEntry URL
Default: None
Server configuration context: VirtualHost, Location, Directory

[edit] CosignAllowPublicAccess

Syntax: CosignAllowPublicAccess On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignHttpOnly

Syntax: CosignHttpOnly On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignCrypto

Syntax: CosignCrypto <key file> <cert file> <ca directory>
Default: /var/cosign/certs/key.pem /var/cosign/certs/cert.pem /var/cosign/certs/CA
Server configuration context: VirtualHost, Location, Directory

[edit] CosignCookieExpireTime

Syntax: CosignCookieExpireTime time-in-seconds
Default: 86400 (24 hours)
Server configuration context: VirtualHost

[edit] CosignGetProxyCookies

Syntax: CosignGetProxyCookies On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignGetProxyKerberosTickets

Syntax: CosignGetKerberosTickets On|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignGetProxyKerberosSetupGSS

Syntax: CosignGetKerberosSetupGSSOn|Off
Default: Off
Server configuration context: VirtualHost, Location, Directory

[edit] CosignCheckIP

Syntax: CosignCheckIP never|initial|always
Default: initial
Server configuration context: VirtualHost

--John DeStefano 11:17, 16 November 2006 (EST)

cosign wiki:CosignFilterSpec