Author: dylan
Date: 2005-06-25 19:16:31 -0400 (Sat, 25 Jun 2005)
New Revision: 823
Added:
trunk/docs/spec/Haver/Spec/
trunk/docs/spec/Haver/Spec/Auth.pod
Modified:
trunk/
trunk/docs/spec/Haver/Spec.pod
Log:
[EMAIL PROTECTED]: dylan | 2005-06-25 19:16:23 -0400
documented auth protocol, I think...
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
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1189
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
27e50396-46e3-0310-8b22-ae223a1f35ce:/local:212
e9404bb1-7af0-0310-a7ff-e22194cd388b:/haver/local:1193
edfcd8bd-4ce7-0310-a97e-bb1efd40edf3:/local:238
Added: trunk/docs/spec/Haver/Spec/Auth.pod
===================================================================
--- trunk/docs/spec/Haver/Spec/Auth.pod 2005-06-25 09:57:39 UTC (rev 822)
+++ trunk/docs/spec/Haver/Spec/Auth.pod 2005-06-25 23:16:31 UTC (rev 823)
@@ -0,0 +1,120 @@
+=head1 NAME
+
+Haver::Spec::Auth - The authentication extension.
+
+=head1 DESCRIPTION
+
+This document describes the authentication extension to L<Haver::Spec>.
+
+=head1 BEGIN YOUR FEAR
+
+The client must advertize it understands the auth extension. It does this by
mentioning
+'auth' in the second arg of C:HAVER, like so:
+
+ C: HAVER CoolClient/1.10 auth
+
+If the client does not advertize, the server will assume it does not
understand any AUTH:
+commands. If the client requests a name that is registered and does not
advertize it
+supports auth, the server will fail it with B<auth.impossible>.
+Otherwise:
+
+ C: IDENT vadim
+ S: AUTH:TYPES basic foo bar baz
+ C: AUTH:TYPE basic
+ S: AUTH:BASIC $nonce sha1,md5
+ C: AUTH:BASIC $hash $response
+
+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>.
+
+$hash is one of the names listed in the second argument 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 $hash. The $response is always base64 encoded.
+
+See also L</PASSCODES> for instructions on creating a passcode.
+
+Thus, $response can be generated with the following perl function:
+
+ use Digest::MD5 'md5_base64';
+ use Digest::SHA1 'sha1_base64';
+
+ sub response {
+ my ($hash, $nonce, $passcode) = @_;
+ if ($hash eq 'sha1') {
+ return sha1_base64($nonce . $passcode);
+ } elsif ($hash eq 'md5') {
+ return md5_base64($nonce . $passcode);
+ }
+ }
+
+=head1 YOU FAIL
+
+This extension introduces a few new errors.
+
+=head2 auth.impossible
+
+Raised when the client does not understand the auth extension.
+
+=head2 auth.fail
+
+Raised when authentication did not work because the passcode or whatever was
wrong.
+
+=head2 unknown.hash
+
+Raised when the hashing algorithm requested by the client is unknown to the
server.
+
+=head1 PASSCODES
+
+First, the problem: The server admin can't be trusted knowing the user's
password.
+They might use it else where, for example. So the first idea that comes to
mind is to hash
+it. Bingo, the server admin does not know the password now. But the server
admin knows the
+hash! So they can still login to other haver servers that the user has
accounts on.
+
+So, we hash the concatenation of the user's password and the hostname of the
server.
+Now the hash is specific to the server, the admin can't figure out the hash
for the user
+on other servers.
+
+But, the admin, being very evil, can find out what users have the same
password.
+To prevent this, we hash the user's password, the user's name, and the
hostname of the
+server.
+
+This is something the client does, of course. It is very important the clients
hash things
+in the same way. Thus all clients must use the sha1() hash function, and
base64 encode its
+results.
+
+Thus, to generate passcodes in perl, the following function is used.
+
+ use Digest::SHA1 'sha1_base64';
+
+ sub passcode {
+ my ($user, $password, $host) = @_;
+ sha1_base64("$password$host$user");
+ }
+
+=head1 AUTHOR
+
+Dylan William Hardison, E<lt>[EMAIL PROTECTED]<gt>,
+with many thanks to muffin and bdonlan. Lots of ideas floated around, I just
cherry-picked
+them to create this scheme.
+
+=head1 SEE ALSO
+
+L<http://www.haverdev.org/>.
+
+=head1 COPYRIGHT and LICENSE
+
+Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.
+
+This module is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This module is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this module; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Modified: trunk/docs/spec/Haver/Spec.pod
===================================================================
--- trunk/docs/spec/Haver/Spec.pod 2005-06-25 09:57:39 UTC (rev 822)
+++ trunk/docs/spec/Haver/Spec.pod 2005-06-25 23:16:31 UTC (rev 823)
@@ -171,12 +171,6 @@
Dylan William Hardison, E<lt>[EMAIL PROTECTED]<gt>
-=begin comment
-
-add your name, too!
-
-=end
-
=head1 SEE ALSO
L<http://www.haverdev.org/>.
