From cosign wiki

Current revision

[edit] Cosign Daemons

Cosign has two daemons: cosignd and monster. cosignd is responsible for implementing the server side of the Cosign protocol, as well as maintaining the Cosign cookie database and, optionally, replicating the LOGIN, REGISTER, and LOGOUT commands to all other cosignds in the server pool. monster is responsible for deleting old cookies (login or service) as well as corresponding Kerberos tickets from the database. monster also optionally replicates the logged in/out state and last update time for all of the login cookies in its database via the TIME command.

[edit] cosignd

cosignd, also known as the central daemon, is the server-side implementation of the Cosign protocol (see Cosign Daemon Protocol). The central daemon is responsible for maintaining the state of all Cosign sessions. This includes keeping track of which users have logged in, logged out, and idle timed-out. In addition, the daemon keeps track of all of the service cookies that represent the authenticated web applications a user has accessed. The daemon has the ability to replicate its cookie database to multiple hosts, so that a failure of one server does not constitute a failure of the entire system. The daemon answers queries of user identity from both the CGI and the filter and communicates with other daemons.

[edit] monster

monster serves two separate functions. In all cases, it is the mechanism by which old cookies and tickets can be deleted when they are no longer needed. In addition, in a replicated cosign environment, monster can be used to propagate the time stamps and state of the login cookies. If replication is activated, monster retrieves the host information for the other hosts in the Cosign pool and opens an SSL connection to the cosignds on all of the other Cosign hosts.

monster sleeps for timestamp-pushing-interval (120 seconds) between successive passes through the cookie database. monster stats each login cookie, checking to see if it is:
a) past the idle-time-out (4.5 hours, which is idle time + grey window from cosignd, + the usual loggedout_cache time in monster),
b) the hard-timeout (12 hours), or
c) if the cookie state is already logged out and the cookie is past the loggedout-keep-time (2 hours).

If the login cookie is past any of these three timeouts, the cookie and any corresponding Kerberos tickets are deleted. When monster encounters a service cookie, it looks up the corresponding login cookie and checks for timeouts, as specified above. If any are encountered, the daemon deletes the login cookie as well as the service cookie. If the service cookie’s corresponding login cookie has already been deleted, the service cookie is also deleted.

[edit] Local Cookie Stores

The daemon and filters use the following format for the local cookie store:
Filter
i IP address
p principal (user name)
r realm (first factor)
f all factors
k kerberos ticket path (optional, if built in)

For example:

i66.93.92.59
ptestuser
rUMICH.EDU
fUMICH.EDU mtoken
k/ticket/EjAP2EqDy-5

Daemon
v version
s state
i initial IP address
j subsequent IP address ( same as initial if no change)
p principal (user name)
r factor(s)
t time data was stored, in seconds, since 1970
k kerberos ticket path (optional, if built in)

For example:

v2
s1
i141.213.147.32
j141.213.147.32
ptestuser
rUMICH.EDU
t1150894952
k/ticket/EjAP2EqDy-5l

[edit] Protocol

cosignd currently supports the following protocol requests:

[edit] QUIT

Terminate session.

C: QUIT\r\n
S: 221 Service closing transmission channel\r\n

[edit] NOOP

Do nothing.

C: NOOP\r\n
S: 250 cosign vVERSION\r\n

[edit] HELP

Display help message.

C: HELP\r\n
S: 203 Slainte Mhath! http://weblogin.org\r\n

[edit] STARTTLS

Start TLS. This command must be given before a client can send a LOGIN, REGISTER, CHECK, LOGOUT, RETRIEVE, DAEMON, or TIME command.

S: 220 Collaborative Web Single Sign-On\r\n
C: STARTTLS\r\n
S: 220 Ready to start TLS\r\n
<TLS negotiation, further commands are under TLS layer>

As of Cosign version 2.x, the protocol version 2 is as follows:

S: 220 2 Collaborative Web Single Sign-On\r\n
C: STARTTLS 2\r\n
S: 220 Ready to start TLS\r\n
<TLS negotiation, further commands are under TLS layer>
S: 221 TLS successfully started.\r\n

The commands HELP, QUIT, and NOOP are the only ones available until STARTTLS is called. The exception to this behavior is when cosignd is running in TLS optional mode (-X) and the CN "NOTLS" is listed in cosign.conf. In this case, the full suite of commands is available regardless of whether STARTTLS is called.

Error Cases:

A 501 is issued if the syntax of the STARTTLS command is wrong, or if cosignd is unable to establish a TLS session with the client.

A 502 is issued in v2 if an unknown protocol version number (e.g., not 2) is given as the second argument of the STARTTLS command.

A 401 is issued if the host's CN does not appear in cosign.conf as either a CGI or a service, and the TLS optional flag (and corresponding NOTLS entry in cosign.conf) have not been set.

[edit] LOGIN

Associates a login cookie with a user, n-factors, IP address, and timestamp. Used by the CGI once the user has authenticated.

If no kerberos ticket is to be transferred, the protocol for LOGIN is as follows:

C: LOGIN login_cookie ip principal realm\r\n
S: 200 LOGIN successful: Cookie Stored.\r\n

The protocol for v2:

C: LOGIN login_cookie ip principal factor\r\n
S: 200 LOGIN successful: Cookie Stored.\r\n

If a kerberos ticket is to be transferred, a final argument, the literal kerberos, is appended to the LOGIN command:

C: LOGIN login_cookie ip principal realm kerberos\r\n

The protocol for v2:

C: LOGIN login_cookie ip principal factor kerberos\r\n
S: 300 LOGIN: Send length then file.\r\n
C: [size]\r\n
C: [data]
C: .\r\n
S: 201 LOGIN successful: Cookie & Ticket Stored.\r\n

Error Cases:

Issuing the LOGIN command for the same cookie multiple times will result in a 202 if no new factors are presented, or if the IP address has not changed.

A 402 is returned if the principal varies between the saved version of the cookie and the principal given in the command. All other errors in this case result in a 5xx.

A 401 is returned if a client issues the LOGIN command and its CN is not listed as a CGI in cosign.conf. All other errors, including malformed commands and system errors, cause cosignd to return a 5xx.

[edit] REGISTER

Associates a service cookie (cosign-[servicename]=) with a login cookie (cosign=). This command is used by the CGI.

C: REGISTER login_cookie ip service_cookie\r\n
S: 220 REGISTER successful: Cookie Stored.\r\n

Error Cases:

Issuing the REGISTER command for the same cookie multiple times will result in a 226 if the information matches exactly.

A 421 is issued if the user has already logged out, and a 422 is issued if the user's session has been idle logged out.

A 420 is returned if the client's CN is not listed as a CGI in cosign.conf.

52x errors are returned for bad syntax, invalid paths to the cookie database, or if the user's login cookie is in the grey window, during which, although a user may be logged out, cosignd returns an unknown (5xx) instead of logged out (4xx) to account for lag in the replication of logouts. The default grey window duration is 30 minutes.

[edit] LOGOUT

Invalidates a user's login cookie, causing any future CHECK commands to return a logged-out status. This is a centralized logout and is used by the CGI.

C: LOGOUT login_cookie ip\r\n
S: 210 LOGOUT successful: cookie no longer valid\r\n

Error Cases:

Issuing the LOGOUT command for the same cookie multiple times will result in a 411.

A 410 is returned if the client's CN is not listed as a CGI in cosign.conf. A variety of 51x errors are returned for bad syntax, invalid cookie paths, and miscellaneous system errors.

[edit] CHECK

Allows clients to retrieve information about a user based on the cookie presented to cosignd. This command is used by both the CGI and the filter (service).

C: CHECK service_cookie\r\n
S: 231 ip principal realm\r\n

C: CHECK login_cookie\r\n
S: 232 ip principal realm\r\n

The protocol for version 2:

C: CHECK service_cookie\r\n
S: 231 ip principal factor [factor2] [factorN]\r\n

C: CHECK login_cookie\r\n
S: 232 ip principal factor [factor2] [factorN]\r\n

Error Cases:

A 430 is returned if the client's CN is not listed as a CGI or a service in cosign.conf.

A 431 signifies an unknown cookie prefix, meaning that the cookie doesn't begin with cosign= or cosign-.

A 432 response indicates that the user is already logged out, while a 433 means the user's session has been idle logged-out.

53x response codes indicate bad syntax, invalid cookie paths, or that a login cookie is in the grey window (see REGISTER). Of particular note are the following entires, as they frequently appear in logs:

S: 533 CHECK: cookie not in db!\r\n

S: 534 CHECK: Who me? Dunno.\r\n

The 533 indicates that the service cookie was not found in that particular cosignd's cookie database, while a 534 means that the login cookie was not found in the cookie database. Neither of these errors are of particular concern, and both are mere side effects of Cosign's lossy replication.

[edit] RETRIEVE

Retrieve a Kerberos credential and/or proxy cookies for n-tier authentication.

The RETRIEVE command takes 2 different keywords: tgt and cookies. In either case, 54x responses are returned for bad syntax, login cookies in the grey window, invalid cookies, missing cookies, or any system errors. 44x responses are returned if the user is already logged out, the user's session has been idle logged-out, or the client has asked for a retrieve type other than tgt or cookies. Finally, a 442 is returned if the client's CN is not permitted as a service in cosign.conf.

[edit] tgt

The keyword "tgt" is used to signify that a client needs a user's tgt in order to perform a Kerberos-authenticated task on behalf of that user. In this case, the protocol looks like the following:

C: RETRIEVE service_cookie "tgt"\r\n
S: 240 Retrieving file\r\n
S: [size]\r\n
S: [data]
S: .\r\n

Error Cases:

A 441 is returned if the client's CN does not have the T flag set in cosign.conf. A 547 is issued if the user's Kerberos ticket cannot be read and a 548 stat() fails on the user's Kerberos ticket.

[edit] cookies

The other keyword is "cookies". This version of RETRIEVE creates and pre-registers service cookies for the user, as defined by the proxy file referenced in cosign.conf. The "cookies" keyword is for use with applications like UPortal and allows one Cosign service to proxy for several others.

C: RETRIEVE service_cookie "cookies"\r\n
S: 241-[cookiename] [hostname to use cookie with]
S: 241- ...
S: 241 Cookies registered and sent.

Error Cases:

A 443 is returned if the client's CN listing in cosign.conf doesn't have the P flag set. Any other error is a serious system error and will cause the server to drop the connection.

[edit] DAEMON

Part of replication, prevents the server from replicating to itself. This command is used by cosignd and monster.

C: DAEMON hostname\r\n
S: 271 Daemon flag set.\r\n

Error Cases:

If there is a syntax error in the command, or the gethostname() system call fails, cosignd will return a 57x. If the hostname given as the second argument matches the server's own hostname, the server has connected to itself and should, therefore, close the replication connection. This is accomplished by issuing:

S:  471 Schizophrenia!\r\n

If the CN is not permitted as a CGI in cosign.conf, a 470 is issued.

[edit] TIME

Allows daemons to propagate timestamp information and state for login cookies. This command is used by monster.

C: TIME\r\n
S: 360 TIME: Send timestamps.\r\n
C: login_cookie1 timestamp1 state1
C: login_cookie2 timestamp2 state2
C: ...
C: login_cookieN timestampN stateN
C: .
S: 260 TIME successful: we are now up-to-date\r\n

Error Cases:

If the CN of the host issuing the TIME command is not listed as a CGI in cosign.conf, the following error is returned:

S: 460 TIME: hostname not allowed to propogate time.\r\n

TIME takes only one argument: the keyword TIME. Any additional arguments will cause the following error:

S: 560 TIME: Wrong number of args.\r\n

[edit] More information:

SSO Overview

Cookies

Filter

CGIs

--John 11:29, 15 November 2006 (EST)