Hi Graham, hi list,
the attached patch adds documetnation to the SASL machanisms in
Authen::SASL.
It may not be perfect as I am no naticve english speaker but better than
nothing.
Peter
--
Peter Marschall
eMail: [EMAIL PROTECTED]
--- Authen-SASL/lib/Authen/SASL/Perl/ANONYMOUS.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/ANONYMOUS.pm
@@ -31,3 +31,64 @@
}
1;
+
+__END__
+
+=head1 NAME
+
+Authen::SASL::Perl::ANONYMOUS - Anynymous Authentication class
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'ANONYMOUS',
+ callback => {
+ authname => $mailaddress
+ },
+ );
+
+=head1 DESCRIPTION
+
+This method implements the client part of the ANONYMOUS SASL algorithm,
+as described in RFC 2245 resp. in IETF Draft draft-ietf-sasl-anon-03.txt
+from February 2004.
+
+=head2 CALLBACK
+
+The callbacks used are:
+
+=over 4
+
+=item authname
+
+email address or UTF-8 encoded string to be used as
+trace information for the server
+
+=back
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
+
+=head1 AUTHORS
+
+Software written by Graham Barr <[EMAIL PROTECTED]>,
+documentation written by Peter Marschall <[EMAIL PROTECTED]>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2002-2004 Graham Barr.
+All rights reserved. This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+Documentation Copyright (c) 2004 Peter Marschall.
+All rights reserved. This documentation is distributed,
+and may be redistributed, under the same terms as Perl itself.
+
+=cut
--- Authen-SASL/lib/Authen/SASL/Perl/CRAM_MD5.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/CRAM_MD5.pm
@@ -39,3 +39,68 @@
}
1;
+
+__END__
+
+=head1 NAME
+
+Authen::SASL::Perl::CRAM_MD5 - CRAM MD5 Authentication class
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'CRAM-MD5',
+ callback => {
+ user => $user,
+ pass => $pass
+ },
+ );
+
+=head1 DESCRIPTION
+
+This method implements the client part of the CRAM-MD5 SASL algorithm,
+as described in RFC 2195 resp. in IETF Draft draft-ietf-sasl-crammd5-02.txt
+from January 2004.
+
+=head2 CALLBACK
+
+The callbacks used are:
+
+=over 4
+
+=item user
+
+The username to be used for authentication
+
+=item pass
+
+The user's password to be used for authentication
+
+=back
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
+
+=head1 AUTHORS
+
+Software written by Graham Barr <[EMAIL PROTECTED]>,
+documentation written by Peter Marschall <[EMAIL PROTECTED]>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2002-2004 Graham Barr.
+All rights reserved. This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+Documentation Copyright (c) 2004 Peter Marschall.
+All rights reserved. This documentation is distributed,
+and may be redistributed, under the same terms as Perl itself.
+
+=cut
--- Authen-SASL/lib/Authen/SASL/Perl/DIGEST_MD5.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/DIGEST_MD5.pm
@@ -121,7 +121,7 @@
=head1 SYNOPSIS
- use Authen::SASL;
+ use Authen::SASL qw(Perl);
$sasl = Authen::SASL->new(
mechanism => 'DIGEST-MD5',
@@ -134,7 +134,11 @@
=head1 DESCRIPTION
-This method implements the DIGEST MD5 SASL algorithm, as described in RFC-2831.
+This method implements the client part of the DIGEST-MD5 SASL algorithm,
+as described in RFC-2831.
+
+This module only implements the I<auth> operation which offers authentication
+but neither integrity protection not encryption.
=head2 CALLBACK
@@ -142,6 +146,10 @@
=over 4
+=item authname
+
+The authorization id to use after successful authentication
+
=item user
The username to be used in the response
@@ -158,18 +166,20 @@
=head1 SEE ALSO
-L<Authen::SASL>
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
=head1 AUTHORS
Graham Barr, Djamel Boudjerda (NEXOR) Paul Connolly, Julian Onions (NEXOR)
Please report any bugs, or post any suggestions, to the perl-ldap mailing list
-<[EMAIL PROTECTED]>
+<[EMAIL PROTECTED]>
=head1 COPYRIGHT
-Copyright (c) 2003 Graham Barr, Djamel Boudjerda, Paul Connolly, Julian Onions and Nexor.
+Copyright (c) 2003 Graham Barr, Djamel Boudjerda, Paul Connolly, Julian Onions
+and Nexor.
All rights reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
--- Authen-SASL/lib/Authen/SASL/Perl/EXTERNAL.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/EXTERNAL.pm
@@ -34,3 +34,61 @@
1;
+__END__
+
+=head1 NAME
+
+Authen::SASL::Perl::EXTERNAL - External Authentication class
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'EXTERNAL',
+ callback => {
+ user => $user
+ },
+ );
+
+=head1 DESCRIPTION
+
+This method implements the client part of the EXTERNAL SASL algorithm,
+as described in RFC 2222.
+
+=head2 CALLBACK
+
+The callbacks used are:
+
+=over 4
+
+=item user
+
+The username to be used for authentication
+
+=back
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
+
+=head1 AUTHORS
+
+Software written by Graham Barr <[EMAIL PROTECTED]>,
+documentation written by Peter Marschall <[EMAIL PROTECTED]>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 1998-2004 Graham Barr.
+All rights reserved. This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+Documentation Copyright (c) 2004 Peter Marschall.
+All rights reserved. This documentation is distributed,
+and may be redistributed, under the same terms as Perl itself.
+
+=cut
--- Authen-SASL/lib/Authen/SASL/Perl/LOGIN.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/LOGIN.pm
@@ -39,3 +39,66 @@
1;
+__END__
+
+=head1 NAME
+
+Authen::SASL::Perl::LOGIN - Login Authentication class
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'LOGIN',
+ callback => {
+ user => $user,
+ pass => $pass
+ },
+ );
+
+=head1 DESCRIPTION
+
+This method implements the client part of the LOGIN SASL algorithm,
+as described in IETF Draft draft-murchison-sasl-login-00.txt from August 2003.
+
+=head2 CALLBACK
+
+The callbacks used are:
+
+=over 4
+
+=item user
+
+The username to be used for authentication
+
+=item pass
+
+The user's password to be used for authentication
+
+=back
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
+
+=head1 AUTHORS
+
+Software written by Graham Barr <[EMAIL PROTECTED]>,
+documentation written by Peter Marschall <[EMAIL PROTECTED]>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2002-2004 Graham Barr.
+All rights reserved. This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+Documentation Copyright (c) 2004 Peter Marschall.
+All rights reserved. This documentation is distributed,
+and may be redistributed, under the same terms as Perl itself.
+
+=cut
--- Authen-SASL/lib/Authen/SASL/Perl/PLAIN.pm
+++ Authen-SASL/lib/Authen/SASL/Perl/PLAIN.pm
@@ -34,3 +34,72 @@
}
1;
+
+__END__
+
+=head1 NAME
+
+Authen::SASL::Perl::PLAIN - Plain Login Authentication class
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'PLAIN',
+ callback => {
+ user => $user,
+ pass => $pass
+ },
+ );
+
+=head1 DESCRIPTION
+
+This method implements the client part of the PLAIN SASL algorithm,
+as described in RFC 2595 resp. IETF Draft draft-ietf-sasl-plain-04.txt
+from February 2004.
+
+=head2 CALLBACK
+
+The callbacks used are:
+
+=over 4
+
+=item authname
+
+The authorization id to use after successful authentication
+
+=item user
+
+The username to be used for authentication
+
+=item pass
+
+The user's password to be used for authentication
+
+=back
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Perl>
+
+=head1 AUTHORS
+
+Software written by Graham Barr <[EMAIL PROTECTED]>,
+documentation written by Peter Marschall <[EMAIL PROTECTED]>.
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2002-2004 Graham Barr.
+All rights reserved. This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+Documentation Copyright (c) 2004 Peter Marschall.
+All rights reserved. This documentation is distributed,
+and may be redistributed, under the same terms as Perl itself.
+
+=cut
--- Authen-SASL/lib/Authen/SASL/Perl.pod 1970-01-01 01:00:00.000000000 +0100
+++ Authen-SASL/lib/Authen/SASL/Perl.pod
@@ -0,0 +1,127 @@
+# Copyright (c) 2004 Peter Marschall <[EMAIL PROTECTED]>. All rights reserved.
+# This program is free software; you can redistribute it and/or
+# modify it under the same terms as Perl itself.
+
+=head1 NAME
+
+Authen::SASL::Perl -- Perl implementation of the SASL Authentication framework
+
+=head1 SYNOPSIS
+
+ use Authen::SASL qw(Perl);
+
+ $sasl = Authen::SASL->new(
+ mechanism => 'CRAM-MD5 PLAIN ANONYMOUS',
+ callback => {
+ user => $user,
+ pass => \&fetch_password
+ }
+ );
+
+=head1 DESCRIPTION
+
+B<Authen::SASL::Perl> is the pure Perl implementation of SASL mechanisms
+in the B<Authen::SASL> framework.
+
+At the time of this writing it provides the client part implementation
+for the following SASL mechanisms:
+
+=over 4
+
+=item ANONYMOUS
+
+The Anonymous SASL Mechanism as defined in RFC 2245 resp.
+in IETF Draft draft-ietf-sasl-anon-03.txt from February 2004
+provides a method to anonymously access internet services.
+
+Since it does no authentication it does not need to send
+any confidential information such as passwords in plain text
+over the network.
+
+
+=item CRAM-MD5
+
+The CRAM-MD5 SASL Mechanism as defined in RFC2195 resp.
+in IETF Draft draft-ietf-sasl-crammd5-02.txt from January 2004
+offers a simple challenge-response authentication mechanism.
+
+Since it is a challenge-response authentication mechanism
+no passwords are transferred in clear-text over the wire.
+
+Due to the simplicity of the protocol CRAM-MD5 is susceptible
+to replay and dictionary attacks, so DIGEST-MD5 should be used
+in preferrence.
+
+
+=item DIGEST-MD5
+
+The DIGEST-MD5 SASL Mechanism as defined in RFC 2831 resp.
+in IETF Draft draft-ietf-sasl-rfc2831bis-03.txt from February 2004
+offers the HTTP Digest Access Authentication as SASL mechanism.
+
+Like CRAM-MD5 it is a challenge-response authentication
+method that does not send plain text passwords over the network.
+
+Compared to CRAM-MD5, DIGEST-MD5 prevents chosen plaintext
+attacks, and permits the use of third party authentication servers,
+so that it is recommended to use DIGEST-MD5 instead of CRAM-MD5
+when possible.
+
+
+=item EXTERNAL
+
+The EXTERNAL SASL mechanism as defined in RFC 2222
+allows the use of external authentication systems as SASL mechanisms.
+
+
+=item LOGIN
+
+The LOGIN SASL Mechanism as defined in IETF Draft
+draft-murchison-sasl-login-00.txt from August 2003 allows the
+combination of username and clear-text password to be used
+in a SASL mechanism.
+
+It does does not provide a security layer and sends the credentials
+in clear over the wire.
+Thus this mechanism should not be used without adequate security
+protection.
+
+
+=item PLAIN
+
+The Plain SASL Mechanism as defined in RFC 2595 resp. IETF Draft
+draft-ietf-sasl-plain-04.txt from February 2004 is another
+SASL mechanism that allows username and clear-text password
+combinations in SASL environments.
+
+Like LOGIN it sends the credentials in clear over the network
+and should not be used without sufficient security protection.
+
+=back
+
+
+=head1 SEE ALSO
+
+L<Authen::SASL>,
+L<Authen::SASL::Cyrus::ANONYMOUS>,
+L<Authen::SASL::Cyrus::CRAM_MD5>,
+L<Authen::SASL::Cyrus::DIGEST_MD5>,
+L<Authen::SASL::Cyrus::EXTERNAL>,
+L<Authen::SASL::Cyrus::LOGIN>,
+L<Authen::SASL::Cyrus::PLAIN>
+
+=head1 AUTHOR
+
+Peter Marschall <[EMAIL PROTECTED]>
+
+Please report any bugs, or post any suggestions, to the perl-ldap mailing list
+<[EMAIL PROTECTED]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2004 Peter Marschall.
+All rights reserved. This document is distributed, and may be redistributed,
+under the same terms as Perl itself.
+
+=cut
+
