Author: dylan
Date: 2005-12-12 01:44:26 -0500 (Mon, 12 Dec 2005)
New Revision: 956
Added:
trunk/docs/manual/extensions.texi
trunk/docs/manual/messages.texi
Modified:
trunk/
trunk/docs/manual/def.texi
trunk/docs/manual/formats.texi
trunk/docs/manual/haver.texi
trunk/docs/manual/introduction.texi
trunk/docs/manual/protocol.texi
trunk/docs/spec/lib/Haver/Spec/Auth.pod
Log:
Worked on the haver manual; add a few bugfixes and details to the spec.
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/havercurs-objc:43089
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/winch/trunk:43192
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1691
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
+ 1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/havercurs-objc:43089
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk:11166
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/local/trunk-merge-10131:11178
1f59643a-e6e5-0310-bc24-f7d4c744f460:/haver/winch/trunk:43192
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1696
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
Modified: trunk/docs/manual/def.texi
===================================================================
--- trunk/docs/manual/def.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/def.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -1,10 +1,14 @@
@comment Texinfo definitions.
@set VERSION 5
-
[EMAIL PROTECTED] EDITION 1
[EMAIL PROTECTED] EDITIONTH 1st
[EMAIL PROTECTED] UPDATED 11 December 2005
[EMAIL PROTECTED] UPDATED-MONTH December 2005
[EMAIL PROTECTED] HAVE-AUTH yes
@alias cmd=command
[EMAIL PROTECTED] error=var
-
@c For everything except info format, @param is @var.
@ifnotinfo
@alias param=var
@@ -16,3 +20,4 @@
<\value\>
@end macro
@end ifinfo
+
Added: trunk/docs/manual/extensions.texi
===================================================================
--- trunk/docs/manual/extensions.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/extensions.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -0,0 +1,4 @@
[EMAIL PROTECTED] Extensions
[EMAIL PROTECTED] Extensions
+
+I haven't written this yet.
Modified: trunk/docs/manual/formats.texi
===================================================================
--- trunk/docs/manual/formats.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/formats.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -7,7 +7,7 @@
@menu
* Dates and Times:: The meaning of 1985-09-14 and such.
* Identifiers:: The name of the beast.
-* Commands:: Nobody likes feeling invalid.
+* Message names:: Nobody likes feeling invalid.
* Client Passcodes:: How a client encodes passwords.
@end menu
@@ -51,24 +51,27 @@
Identifiers beginning with @code{&} or containing @code{@@} are reserved by
the server.
[EMAIL PROTECTED] Commands
[EMAIL PROTECTED] Commands
-
-The command portion of a message must match the regex:
[EMAIL PROTECTED] Message names
[EMAIL PROTECTED] Message names
+
+Message names must match the perl-style regular expression:
@verb{!/[A-Z][A-Z:_-]+/!}.
+Failing to do this is a fatal error.
@node Client Passcodes
@section Client Passcodes
+
Passcodes are essentially the same thing as passwords. In fact, as far as the
server is concerned, they
are passwords. The primary purpose is to prevent server admins from reading
the password from
the user accounts, and to ensure that identical passwords on different servers
do not pose as great
-a security concern. Identical passwords on the same server are still
detectable.
+a security concern. Identical passwords on the same server are also not
detectable.
All clients must implement passcodes in the exact same way, or else users will
not be able to login
as the same account from different clients.
The passcode for a user on server $host (as given by the @cmd{HOST} server
message)
-with password $password is @code{sha1($password + $host + $user)} where
@code{+} indicates concatenation
+with password $password is @code{sha1($password + lc($host + $user))}
+where lc returns the all lower-case version of its argument, @code{+}
indicates concatenation
of strings and sha1 is the SHA1 hash function defined in @cite{RFC 3174} and
@cite{FIPS 180-1}.
The hash is encoded using Base64.
Modified: trunk/docs/manual/haver.texi
===================================================================
--- trunk/docs/manual/haver.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/haver.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -2,15 +2,20 @@
@comment %**start of header
@setfilename haver.info
@include def.texi
[EMAIL PROTECTED] The Divine Secrets of Haver ([EMAIL PROTECTED])
[EMAIL PROTECTED] The Divine Secrets of Haver
@syncodeindex fn cp
@comment %**end of header
@copying
+This is Edition @value{EDITION},
+last updated on @value{UPDATED},
+of @cite{The Divine Secrets of Haver},
+for haver protocol version @value{VERSION}.
+
Copyright @copyright{} 2004, 2005 Dylan Hardison.
@quotation
This work is licensed under the Creative Commons Attribution-ShareAlike
License. To view a copy of this
-license, visit @url{http://creativecommons.org/licenses/by-sa/2.0/}
+license, visit @url{http://creativecommons.org/@/licenses/@/by-sa/@/2.0/}
or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford,
California 94305, USA.
@end quotation
@end copying
@@ -25,6 +30,8 @@
@titlepage
@title The Divine Secrets of Haver
@subtitle A Journey into Madness
[EMAIL PROTECTED] @value{EDITIONTH} edition
[EMAIL PROTECTED] @value{UPDATED-MONTH}
@author Dylan William Hardison (@[EMAIL PROTECTED])
@author Bryan Donlan (@[EMAIL PROTECTED])
@page
@@ -43,15 +50,19 @@
@menu
-* Introduction::
-* Protocol::
-* Formats::
-* Index::
+* Introduction:: What is haver?
+* Protocol:: How to parse the protocol.
+* Messages:: How to speak Haverian.
+* Formats:: On the shape of dates, commands, etc.
+* Extensions:: All about extensions.
+* Index:: Help! I'm lost!
@end menu
@include introduction.texi
@include protocol.texi
[EMAIL PROTECTED] messages.texi
@include formats.texi
[EMAIL PROTECTED] extensions.texi
@node Index
@unnumbered Index
Modified: trunk/docs/manual/introduction.texi
===================================================================
--- trunk/docs/manual/introduction.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/introduction.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -22,13 +22,13 @@
Haver has also been a fascinating programming exercise.
@menu
-* Servers::
-* Clients::
-* Channels::
-* Entities::
+* Intro Servers::
+* Intro Clients::
+* Intro Channels::
+* Intro Entities::
@end menu
[EMAIL PROTECTED] Servers
[EMAIL PROTECTED] Intro Servers
@section Servers
Haver is (mostly) a client-server protocol.
@@ -36,17 +36,7 @@
Servers store metadata about each client, and also maintain the list of
channels.
@c expand!
[EMAIL PROTECTED]
-* Global Server List::
[EMAIL PROTECTED] menu
-
[EMAIL PROTECTED] Global Server List
[EMAIL PROTECTED] Global Server List
-
-There are plans to use a distributed hash table to keep track of all haver
servers
-world-wide. This is just a pipe dream for now.
-
[EMAIL PROTECTED] Clients
[EMAIL PROTECTED] Intro Clients
@section Clients
A haver client is any TCP/IP program that conforms to the haver protocol.
@@ -57,7 +47,7 @@
Services are privileged clients that may add new protocol commands, add new
virtual users called agents, and allow different forms of server linking.
[EMAIL PROTECTED] Channels
[EMAIL PROTECTED] Intro Channels
@section Channels
Channels are collections of users, as in IRC. Unlike IRC, channels are never
automagically
@@ -65,18 +55,19 @@
or that action may be restricted to users with the proper privledges.
@menu
-* Lobby::
+* Intro Lobby::
@end menu
[EMAIL PROTECTED] Lobby
[EMAIL PROTECTED] Intro Lobby
@subsection Lobby
-The lobby is like a special channel. It contains all the users, services, and
channels
+The lobby is a special channel. It contains all the users, services, and
channels
of the server. It goes by the name &lobby.
+It contains itself.
-One can neither join nor part &lobby.
+Clients can neither join (already there) nor part &lobby.
[EMAIL PROTECTED] Entities
[EMAIL PROTECTED] Intro Entities
@section Entities
Channels and clients share many common attributes, so it is useful to refer to
them
Added: trunk/docs/manual/messages.texi
===================================================================
--- trunk/docs/manual/messages.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/messages.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -0,0 +1,157 @@
[EMAIL PROTECTED] Copyright (C) 2005 Dylan William Hardison.
[EMAIL PROTECTED] See haver.texi for copyright details.
+
[EMAIL PROTECTED] Messages
[EMAIL PROTECTED] Messages
+
+This chapter explains the semantics of the haver protocol.
+It is broken into sections, where similar or related commands are grouped.
+
+This chapter includes messages from the Auth extension.
+
[EMAIL PROTECTED]
+* Login:: How to login to the server.
+* Channels:: How to open, join, part, close, etc.
+* Failures:: You are a failure.
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Login
[EMAIL PROTECTED] Login
+
+Upon connection, a haver client must speak the magic word.
+If it doesn't speak the magic word, the server must promptly break the
connection
+to the client without saying anything.
+
+The magic word [EMAIL PROTECTED]
+
[EMAIL PROTECTED] {Client Message} HAVER @var{version} [EMAIL PROTECTED]
[EMAIL PROTECTED] {Server Message} HAVER @var{host} @var{version} [EMAIL
PROTECTED]
+A haver client sends @cmd{HAVER} to the server in order to begin the login
process.
+It advertizes the software it is running (with @param{version}) and optionally
what
+extensions it supports (with @param{extensions}).
+
+A server is then obligated to reply with @cmd{HAVER}, advertizing the software
it is running,
+the extensions it supports (optionally), and the hostname it is running on
(with @param{host}).
+
[EMAIL PROTECTED] This next paragraph is copied from Haver::Spec, and was
written by Muffin.
+A client @strong{should} always check to make sure that the server's IP
address resolves to the same
+thing as @param{host} before sending anything. This will prevent server
owners from picking up
+people's passcodes (@pxref{Passcodes}) by making them think it's another
server.
+
+The usual format for @param{version} is @code{name of app/x.yz}.
+Two examples being ``Haver::Server/0.89'' and ``Haver::Client/0.90''.
+
[EMAIL PROTECTED], for more details on haver extensions.
[EMAIL PROTECTED] deffn
+
+Alternatively, you could say another special word, if you need to remove a
corpse.
+This magic corpse-removing command is called:
+
[EMAIL PROTECTED] {Client Message} GHOST [EMAIL PROTECTED] @var{name}.
+This message is identical to @cmd{IDENT} except:
+If there is already a client connected as @param{name},
+and the connecting client has the proper authority it will disconnect the
connected client
+and allow the connecting client to connect.
+
+Authority is determined thusly:
+If the connected client supports auth,
+then the connecting client must authenticate (if it supports auth, otherwise
fail with @error{auth.impossible})
+to have the proper authority.
+
+If the connected client doesn't support auth, and the connecting client has
the same IP address,
+then the connecting client has the proper authority.
+(This is the only way for servers that don't support auth).
[EMAIL PROTECTED] deffn
+
+The next phase of the login process is fairly easy: You say your name.
+Before doing this, you should understand that in haver (as in the real world),
+saying your name can often result in failure.
+
+In this chapter, whenever you see the phrase ``the server will fail [EMAIL
PROTECTED]''
+it means the server will end @samp{FAIL @param{cmd} @param{error} [EMAIL
PROTECTED]@dots{}]}.
[EMAIL PROTECTED], for more information of failure.
+
+If failure occures during authentication, the client may reissue @cmd{IDENT}.
+
+Now you are ready to announce your haverian name [EMAIL PROTECTED]
+
[EMAIL PROTECTED] {Client Message} IDENT [EMAIL PROTECTED] @var{name}
[EMAIL PROTECTED] {Server Message} HELLO [EMAIL PROTECTED] @var{name}
[EMAIL PROTECTED] {Server Message} AUTH:TYPES @[EMAIL PROTECTED]
+
+
+For the moment, let's pretend @param{namespace} doesn't exist. It is optional,
so, it might as well anyway.
+As for @param{name}, it must match the format described in @ref{Identifiers},
+or else the server will fail with @error{invalid.name}.
+
+If @param{name} already exists on the server, the server will fail with
@error{exists.user}.
+
+If the name contains either @code{&} or @code{@@}, the server will fail with
@error{reserved.name}.
+
+If no authentication is required, @cmd{HELLO} will be sent.
+
+If the client doesn't support the auth extension, and authentication is
required,
+the server will fail with @error{auth.impossible}.
+
+If the client does support the auth extension, and authentication is required,
+the server will send @cmd{AUTH:TYPES}.
+
+The parameter @param{types} of @cmd{AUTH:TYPES} is a list of authentication
methods the server supports.
+
+The client should respond to @cmd{AUTH:TYPES} with @cmd{AUTH:TYPE} or
@cmd{AUTH:CANT}.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Client Message} AUTH:TYPE @var{type}
+If @param{type} is not one of the types from @cmd{AUTH:TYPES},
+the server must disconnect the client with @samp{BYE bork I don't speak
french!}.
+
[EMAIL PROTECTED] is the name of a command the server will send to the client.
+By default, haver servers that support auth should have at least
@cmd{AUTH:BASIC}.
+Thus if the client sends @samp{AUTH:TYPE AUTH:BASIC}, the server will send
@cmd{AUTH:BASIC}.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Client Message} AUTH:CANT
+The client must issue this message if it can not use any of the types
presented by @cmd{AUTH:TYPES}.
+After issuing this message, the client may issue @cmd{IDENT} again.
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] {Server Message} AUTH:BASIC @var{nonce} @[EMAIL PROTECTED]
[EMAIL PROTECTED] {Client Message} AUTH:BASIC @var{digest} @var{response}
+The server sends @cmd{AUTH:BASIC} with a unique value (@param{nonce})
+and a list of digests.
+The client then picks one of the digests it understands and replies with
@cmd{AUTH:BASIC}.
+
+In the client's reply, @param{digest} must be one of digests listed in
@param{digests},
+or else the server will fail with @error{unknown.digest}.
+
+If the client sends the correct reply, the server will send @cmd{HELLO}.
+Otherwise, the server will fail with @error{auth.fail}.
+
+To compute @param{response},
+the client must use the folowing function,
+where D = the digest function, N = @param{nonce},
+and P = the passcode (as described in @ref{Passcodes}.)
+
[EMAIL PROTECTED]
+F(D, N, P) :=
+ base64( D(N + P) ).
+
+response := F(sha1, "foo", "EElFsCeSMqElRNX1h9jQUlcxIYo").
+response = "7Tl3mrDfWVKMnpfxw1BngNVz+4g"
[EMAIL PROTECTED] example
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] Channels
[EMAIL PROTECTED] Channels
+This section details with channel maintenance commands.
+
[EMAIL PROTECTED] {Client Message} JOIN @var{channel}
[EMAIL PROTECTED] {Server Message} JOIN @var{channel} @var{user}
+
+
[EMAIL PROTECTED] deffn
+
[EMAIL PROTECTED] Failures
[EMAIL PROTECTED] Failures
+
+I haven't written this yet.
Modified: trunk/docs/manual/protocol.texi
===================================================================
--- trunk/docs/manual/protocol.texi 2005-12-11 05:34:56 UTC (rev 955)
+++ trunk/docs/manual/protocol.texi 2005-12-12 06:44:26 UTC (rev 956)
@@ -10,9 +10,13 @@
There is an optional escaping mechanism, and support for Unicode.
These issues are explained next.
+This chapter only describes the syntax of the protocol. Semantics of the
protocol
+are explained in @ref{Messages}.
+
@menu
-* Character codes:: Unicode your friends.
+* Character codes:: Unicode is your friend.
* Parsing:: Banana Split.
+* Limits:: When the bartender says ``no''
@end menu
@node Character codes
@@ -25,9 +29,9 @@
@node Parsing
@section Parsing
-The protocol is delimited into lines separated by CR LF (0x0D 0x0A or "\r\n").
+The protocol is delimited into lines separated by CR LF (0x0D 0x0A or
``\r\n'').
Each line is further delimited by the Tab character (0x09) into a series of
tokens.
-The first of the tokens is called the command.
+The first of the tokens is called the message name or command.
The remaining tokens (if any) are refered to as the arguments.
The command and arguments together make up a message.
@@ -42,3 +46,10 @@
Currently there is no defined behavior for ASCII NUL characters in the
protocol.
Comments and suggestions on how to deal with them is welcome.
+
[EMAIL PROTECTED] Limits
[EMAIL PROTECTED] Limits
+
+A server @strong{must not} accept lines from a client that are longer than 4
kbytes (4098 bytes).
+Clients @strong{should} accept lines of any length.
+
Modified: trunk/docs/spec/lib/Haver/Spec/Auth.pod
===================================================================
--- trunk/docs/spec/lib/Haver/Spec/Auth.pod 2005-12-11 05:34:56 UTC (rev
955)
+++ trunk/docs/spec/lib/Haver/Spec/Auth.pod 2005-12-12 06:44:26 UTC (rev
956)
@@ -31,6 +31,9 @@
If the authentication is successful, the server will send HELLO as per normal.
If not, the server will fail the client with B<auth.fail>.
+If some perverted client sends an unknown auth type to AUTH:TYPE, it will
disconnect
+the client with a bork with C<$detail = "I don't speak french!">.
+
$digest is one of the parameters after the first parameter of S:AUTH:BASIC.
$response is the result of hashing the concatenation of $nonce and the user's
passcode
using the hash function named in $digest. The $response is always base64
encoded.
