Is there any defintion of the protocl used between the gateway and auth server to verify users and communicate. I see lots of good information in the Intoduction.txt defining classes and sort of a high level abstract of what goes on between the gateway and the auth server, but i don't see message formats, transport mechanisms, state machine things, and what not.
I think there is a place for this as lots of people are trying to write c versions of the gateway to run on embedded hardwares and defining independently of the source code things referred to in it; like the ticket, what punching the ticket means, what http codes are sent back forth and what they mean, etcetera, could be really helpful.
I have started below with some VERY rough beginnings after looking through the gateway src for too many hours.
1.3 Terminology
- connection::A transport layer virtual circuit established between two programs for the purpose of communication.;
- message
- The basic unit of NOCAT communication, consisting of a HTTP GETs, POSTs, REDIRECTs and status codes.;
- ticket
- The concept describing the nocat state information passed between gateways and clients, clients and auth servers, auth servers and gateways. Tickets can be punched, authenticated, verified, thrown in someone's face, and so much more.;
- gateway
- A program implementing the gateway side of the nocat protocol;
- auth server
- A program implementing the auth server side of the nocat protocol.;
4 NOCAT Message
- 4.1 Message Types NOCAT messages consist HTTP Gets, POSTs, REDIRECTs, and status codes sent from the gateway to auth server and auth server to gateway. 4.2 NOCAT HTTP REDIRECTs
- Redirects are used by the gateway and auth server. The Gateway uses http 302 page moved or redirect to get the client to the auth server for authentication, and also to pass along state information(a nocat ticket) about the client. The format of the http 302 message is as follows. HTTP/1.1 302 Moved
Location: https://AuthServiceAddr/cgi-bin/login?token=token_value&timeout=timeout_value&redirect=original_destination_url_of_client&mac=clients_mac_address <html> <body bgcolor="white" text="black"> You should be redirected now. If not, click <a href="https://auth.nocat.net/cgi-bin/login?token=%241%241%24HQPsTAITd3i2jrLKlchyq%2f&timeout=600&redirect=http%3a%2f%2farchives%2emath%2eutk%2eedu%2ftopics%2fnumberTheory%2ehtml&mac=00%3a02%3a2D%3a1E%3a4F%3a25">here.</a> </body> </html>
The AuthServiceAddr comes from the nocat.conf file on the gateway. The token,timeout,redirect,and mac are part of a NOCAT concept called a ticket.
- The format of the nocat http post request is as follows. POST, mac_address
- Redirects are used by the gateway and auth server. The Gateway uses http 302 page moved or redirect to get the client to the auth server for authentication, and also to pass along state information(a nocat ticket) about the client. The format of the http 302 message is as follows. HTTP/1.1 302 Moved
BEGIN PGP SIGNED MESSAGE
- Hash: SHA1
Timeout IdleTimeout Token clients_token Mode renew|possibly something else Mac clients_mac User username Action Permit|DENY|possibly something else line=
BEGIN PGP SIGNATURE
- Posts are used by the auth server. The auth server sends an http post message to a gateway after the authentication process has been completed for a user. (To complete this part someone will have to look through the auth server code). The Post will have a destiantion ip address of the gateway that generated the ticket, a uri of the client|users mac gotten from the redirect issued by this gateway to the client,
a timeout matching the IdleTimeout from nocat.conf(i think), the token contained in the redirect request which started the authentication of this user, the mode of this ticket, the username gotten during the actual clients https ineraction with the auth server(the one inputed at the auth server login page), the action that the gateway is supposed to take for this user|client, and all of it wrapped in pgp signature of the auth server.
- 4.4 NOCAT HTTP GETs
- nocat http gets are received by both the gateway and auth servers. The gateway receives http gets when a user is asking to be logged out. The logout request will have a destination ip address of the gateway a user is wanting to logout from, and a uri of /logout. Other data might be included in the get but is ignored by the gateway. Upon receiving logout request the gateway will modify it's the firewall rules to denial for that user|mac|client. Once the firewall modifications have been completed and the state for that peer|user|client updated the gateway will send an HTTP 302 redirect(page moved) to the user with a url of LogoutURL taken from the nocat.conf file. The auth server receives gets from the user|client after they have been redirected by a gateway. Possibly other gets are received by the auth server but someone will have to examine that code to see. The format of the gets received by the auth server that i know of match the Location in the redirect messages sent by a gateways.
- http 302 redirects are used by the gateway and auth server. The gateway uses http redirect to send users to the auth servers loging.html page. http 200 ok message are sent by gateways and auth servers. The gateway uses ok messages after having punched a ticket received by an auth server. This tells the auth server that the ticket associated with this socket was successfully punched. Meaning the pgp stuff was verified, the user ticket info like tokens and mac addresses matched and that the firewall rules have been modified for that user|mac according to the action contained in the nocat http post request that opened this socket. HTTP/1.1 400 Session Expired messages are sent by gateways in response to auth server posts for which there is no state information.
5. NOCAT Ticket
- The format of a ticket is in name value pairs serperated by ='s signs put into either an HTTP POST or REDIRECT messages. Also when a tickets as been authenticated for a user the uri field of the post messages sending the ticket back to the gateway will contain the mac of the user|client. This is also in the name value pairs and maybe is redundant? The redirect messages are sent by gateways after receiving connections on the NOCAT port with destination ip addresses other then itself. See the Firewall section for information on how these request are made to arrive here. When a gateway receives messages with destination ip address other then itself, a ticket is generated containing a radomly generated token, a timeout which comes from the
LoginTimeout directive in the nocat.conf file, a redirect to the original url the client requested which is the url of the request received on the nocat port by the gateway which started this process, and the mac of the client.
5 NOCAT States.
- 5.1 NOCAT gateway states
- 5.1.a Locked
- When a gateway is in LOCKED state the firewall rules are the same as CLOSED state. So the firewall will redirect clients to the gateway port with their original destination ip address. When the gateway is locked down it should reply with a NOCAT HTTP redirect sending the users to a url explaining something about the lockdown.
- When a gateway is closed the firewall rules send every http connection
to the nocat port GatewayPort with their original destination ip addresses. The gateway then
- When a gateway is open it is only open for individual clients|users|macs. A gateway who has an open state in it's relationship to a client has firewall rules allowing that client to pass through according to the action put onto the ticket by the auth server. So i guess when a gateway is open to a client you could just say that that client is in authenticated state.
- 5.2.a Unknown
- When a client is unknown to a gateway it can be 802.11 associated, have an ip address received from dhcp server running on gateway, or many other things, but it cannot have any nocat state or information about itself
- When a client is logging in it has state information about it self in the gateway. This state information is in i guess the form of a ticket. The client has sent some outbound traffic which was redirected via firewall rules
to the gateway listening on the GatewayPort. The gateway then created a ticket for the client, gave it to him, and the client is logging into the auth server mentioned in the ticket.
- The client has been issued a ticket, presented the ticket to an auth server, been authenticated by that auth server, the auth server has forwarded (NOCAT http post) that ticket to the originating gateway, the gateway has punched(verified the contents and action put on the ticket by that auth server) the ticket and opened up it's firewall rules for that client|mac|user accordingly.
- The client has state information in the gateway as well as the gateways auth server. However he was unable to be authenticated. He has gone through identical processes to an authenticated user, except the ticket was not punched by the gateway. Rather the gateway found and action put onto the ticket by the auth server of; deny, bar, kickout, call the police, or something.
- 5.3.a Issued 5.3.b Punched
- 5.1.a Locked
6 NOCAT Firewall interactions