From cosign wiki

Contents 1 Cosign Authentication Filter Specification 1.1 Introduction 1.2 Module Layer 1.2.1 Valid Cookie Response 1.2.2 Other Cookie Responses 1.3 Data Storage Layer 1.4 Network Layer 1.5 Protocol 1.6 Apache Configuration 1.6.1 CosignHostname 1.6.2 CosignPort 1.6.3 CosignService 1.6.4 CosignRedirect 1.6.5 CosignPostErrorRedirect 1.6.6 CosignRequireFactor 1.6.7 CosignFactorSuffix 1.6.8 CosignFactorSuffixIgnore 1.6.9 CosignFilterDB 1.6.10 CosignProxyDB 1.6.11 CosignFilterHashLength 1.6.12 CosignTicketPrefix 1.6.13 CosignProtected 1.6.14 CosignSiteEntry 1.6.15 CosignAllowPublicAccess 1.6.16 CosignHttpOnly 1.6.17 CosignCrypto 1.6.18 CosignCookieExpireTime 1.6.19 CosignGetProxyCookies 1.6.20 CosignGetProxyKerberosTickets 1.6.21 CosignGetProxyKerberosSetupGSS 1.6.22 CosignCheckIP

Cosign Authentication Filter Specification

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.

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.

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.

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.

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.

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.

Protocol

An example session:

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

Apache Configuration

mod_cosign recognizes the following configuration directives:

CosignHostname

Syntax

CosignHostname fully-qualified-domain-name

Default

cosign.example.edu

Server configuration context

VirtualHost

CosignPort

Syntax

CosignService integer

Default

6663

Server configuration context

VirtualHost, Location, Directory

CosignService

Syntax

CosignService service-name

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignRedirect

Syntax

CosignRedirect URL

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignPostErrorRedirect

Syntax

CosignPostErrorRedirect URL

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignRequireFactor

Syntax

CosignRequireFactor Factor1[Factor2...FactorN]

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignFactorSuffix

Syntax

CosignFactorSuffix FactorSuffix

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignFactorSuffixIgnore

Syntax

CosignFactorSuffixIgnore On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

CosignFilterDB

Syntax

CosignFilterDB Path

Default

/var/cosign/filter

Server configuration context

VirtualHost

CosignProxyDB

Syntax

CosignProxyDB Path

Default

/var/cosign/proxy

Server configuration context

VirtualHost

CosignFilterHashLength

Syntax

CosignFilterHashLength 0|1|2

Default

0

Server configuration context

VirtualHost

CosignTicketPrefix

Syntax

CosignTicketPrefix Path

Default

/ticket

Server configuration context

VirtualHost

CosignProtected

Syntax

CosignProtected On|Off

Default

On

Server configuration context

VirtualHost, Location, Directory, .htaccess

CosignSiteEntry

Syntax

CosignSiteEntry URL

Default

None

Server configuration context

VirtualHost, Location, Directory

CosignAllowPublicAccess

Syntax

CosignAllowPublicAccess On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

CosignHttpOnly

Syntax

CosignHttpOnly On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

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

CosignCookieExpireTime

Syntax

CosignCookieExpireTime time-in-seconds

Default

86400 (24 hours)

Server configuration context

VirtualHost

CosignGetProxyCookies

Syntax

CosignGetProxyCookies On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

CosignGetProxyKerberosTickets

Syntax

CosignGetKerberosTickets On|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

CosignGetProxyKerberosSetupGSS

Syntax

CosignGetKerberosSetupGSSOn|Off

Default

Off

Server configuration context

VirtualHost, Location, Directory

CosignCheckIP

Syntax

CosignCheckIP never|initial|always

Default

initial

Server configuration context

VirtualHost

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