This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Authen/PIN, Next: Authen/Prot, Prev: Authen/PAM, Up: Module List Create and verify strong PIN numbers ************************************ NAME ==== Authen::PIN - Create and verify strong PIN numbers SYNOPSIS ======== use Authen::PIN; my $pinset = new Authen::PIN ('PPPCCP123HHHHHHHV', $start # Optional ); $pinset->set($start); # Preferred $pinset->inc($inc); $pinset->pin($pass_through, $serial); # OR $pinset->pin($serial); # undef $pass_through DESCRIPTION =========== This module provides an interface to create crypto-strong PIN numbers for applications such as calling cards that require a number that is difficult to guess and that might convey hidden information. It is based on templates, that define how the resulting PIN number will be constructed by combining the following components: *Pass through values* This is represented in the template with the letter 'P'. It is copied as is to the resulting PIN. Digits are passed to the template from left to right. If the supplied value in the call to `->pin' is too short, it will be left-padded with zeros. Counters Represented in the template with the letter 'C'. This is a regular counter that starts at the value passed to `->set' or $start (if specified) and is incremented for each call to `->pin' by whatever value was passed to `->inc' (or 1 by default). Hashes These are represented by the letter 'H'. When calling `->pin($pass, $serial)', the concatenation of `$pass' and `$serial' are passed through the MD5 function and the result converted to a string of digits. This string is replaced, from left to right, into the supplied template. There is a limit in the number of digits that a hash can generate. Using more than 20 or so digits is discouraged as this might result in PIN numbers that are not strong enough. In practice, a PIN number with such a large number of digits is probably of little use. *Verification digit* It is represented with the 'V' character in the template. When found, a checksum of the PIN constructed so far will be calculated and placed at the current position. This is usually used as the last digit in the PIN template, to allow for a digit that allows for the simple discard of bogus PIN number, avoiding more expensive database operations in a complete application. The algorythm used for this checksum, is the same used by credit cards, as implemented by Business::Creditcard. *Literal digits* Digits in the range 0-9 are copied to the resulting PIN. AUTHOR ====== Luis E. Munoz CHANGES ======= 1. Fri Jan 12 15:51:03 2001 original version; created by h2xs 1.19 2. Thu Mar 01 18:15:00 2001 modified to use Number::Encode to achieve a more robust PIN digit distribution WARRANTY ======== This code has the same warranty that Perl itself. SEE ALSO ======== perl(1), Digest::MD5.  File: pm.info, Node: Authen/Prot, Next: Authen/SASL, Prev: Authen/PIN, Up: Module List Perl extension for accessing protected password database ******************************************************** NAME ==== Authen::Prot - Perl extension for accessing protected password database SYNOPSIS ======== use Authen::Prot; Authen::Prot::setprpwent(); $pw = Authen::Prot->getprpwent(); $pw = Authen::Prot->getprpwuid(0); $pw = Authen::Prot->getprpwnam('daemon'); print "$pw->ufld_fd_name\n"; $pw->ufld_fd_slogin(time); $pw->putprpwnam(); $crypt = Authen::Prot::bigcrypt('test', 'test'); # not avail on DEC/OSF Authen::Prot::endprpwent(); DESCRIPTION =========== The Authen::Prot module provides access to the protected password database via the getprpwent, getprpwuid, getprpwnam, getprpwaid, setprpwent, endprpwent, and putprpwnam system calls available on those Unix systems using the Protected Password database written by SecureWare Inc. (c). METHODS ------- The availability of some of the methods below will depend on how the Protected Password database has been implemented on your system. $crypt = Authen::Prot::bigcrypt($key, $salt) Encrypted $key using the bigcrypt(3) system call if available and returns the result. Not available on DEC/OSF, via this package yet. $pw = Authen::Prot::getprpwent() This method returns a reference to a blessed Authen::Prot object. You may then use this reference to retrieve values of fields in the protected password database. When this method is first called it returns the first entry in the database, on each subsequent call it returns the next entry. See getprpwent(3) for further information on which records are returned. $pw = Authen::Prot::getprpwuid($uid) This method returns a reference to a blessed Authen::Prot object if an entry with a uid of that passed is found, otherwise it will return undef. You may then use this reference to retrieve values of fields in the protected password database. See getprpwuid(3) for further information on how records are returned. $pw = Authen::Prot::getprpwaid($aid) This method returns a reference to a blessed Authen::Prot object if an entry with a aid of that passed is found, otherwise it will return undef. You may then use this reference to retrieve values of fields in the protected password database. See getprpwaid(3) for further information on how records are returned. $pw = Authen::Prot::getprpwnam($name) This method returns a reference to a blessed Authen::Prot object if an entry with a login name of that passed is found, otherwise it will return undef. You may then use this reference to retrieve values of fields in the protected password database. See getprpwnam(3) for further information on how records are returned. Authen::Prot::setprpwent() Calling setprpwent effectively rewinds the pointer into the protected password databases so that a subsequent call to getprpwent will return the first record. See setprpwent(3) for further information on the function of this method. Authen::Prot::endprpwent() Calling endprpwent effectively closes the protected password database. See endprpwent(3) for further information on the function of this method. $pw->putprpwnam() This method commits a Prot object to the protected password database. Setting $pw->uflg_fg_name to 0 will delete the corresponding entry. See putprpwnam(3) for further information on the function of this method. $pw->pr_struct_field_name() / $pw->pr_struct_field_name($value) The fields available from the methods described above, depend on the definition of the pr_struct structure in the `/usr/include/prot.h' on your system, and the information available I have to interpret them. This module will attempt to parse your `prot.h' file and generate a XS function for each field available on your system. The pr_struct typically consists of four structures given the name of ufld, sfld, uflg and sflg for User fields, System fields, User flags and System flags respectively. To allow for the syntax differences between C and Perl the field names have been re-written replacing the struct . with a _ in Perl. For example the User field login name would be referenced in C as: ufld.fd_name and in Perl as: $pw->ufld_fd_name COPYRIGHT ========= The Protected Password database library by SecureWare Inc. (c) is classified as containing Confidential information so I am unable to include the field descriptions in this document. Please refer to the man pages referenced below and to the `/usr/include/prot.h' header file for further information. EXAMPLES ======== The test.pl file provides examples of the methods available via this extension common to most platforms. AUTHOR ====== Paul Gampe . I would appreciate it if you could send me an email if you starting using this package, so I can notify you of updates, and get an idea of what platforms it is compatible with. FILES ===== `/usr/include/prot.h' COPYRIGHT ========= Copyright (c) 1997-98 Paul Gampe. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. SEE ALSO ======== getprpwent(3), getprpwuid(3), getprpwnam(3), getprpwaid(3), setprpwent(3), endprpwent(3), putprpwnam(3), perl(1).  File: pm.info, Node: Authen/SASL, Next: Authen/Smb, Prev: Authen/Prot, Up: Module List SASL Authentication base class ****************************** NAME ==== Authen::SASL - SASL Authentication base class SYNOPSIS ======== use Authen::SASL; $sasl = Authen::SASL->new('CRAM-MD5', password => $pass); DESCRIPTION =========== SASL is a generic mechanism for authentication used by several network protocols. *Authen::SASL* provides an implementation that all protocols should be able to share. There are many different encryption methods that can be used with SASL. These are implemented as sub-classes of *Authen::SASL*. For example the package that implements the CRAM-MD5 SASL is called Authen::SASL::CRAM_MD5. Note that the - is eplaced with an _. Authen::SASL::CRAM_MD5 also inherits from *Authen::SASL*. This means that the following two statements give identical results $sasl = Authen::SASL->new('CRAM-MD5', password => $pass); $sasl = Authen::SASL::CRAM_MD5->new(password => $pass); the difference being that the frst one will load the Authen::SASL::CRAM_MD5 package for you when this code is run for the first time. If you use the second method then you must require the package yourself. METHODS ======= SEE ALSO ======== `Authen::SASL::CRAM_MD5|Authen::SASL::CRAM_MD5' in this node AUTHOR ====== Graham Barr Please report any bugs, or post any suggestions, to the perl-ldap mailing list COPYRIGHT ========= Copyright (c) 1998-2000 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.  File: pm.info, Node: Authen/Smb, Next: Authen/TacacsPlus, Prev: Authen/SASL, Up: Module List Perl extension to authenticate against an SMB server **************************************************** NAME ==== Authen::Smb - Perl extension to authenticate against an SMB server SYNOPSIS ======== use Authen::Smb; my $authResult = Authen::Smb::authen('myUser', 'myPassword', 'myPDC', 'myBDC', 'myNTDomain'); if ( $authResult == Authen::Smb::NO_ERROR ) { print "User successfully authenticated.\n"; } else { print "User not authenticated with error level $authResult\n"; } DESCRIPTION =========== Authen::Smb allows you to authenticate a user against an NT domain. You can specify both a primary and a backup server to use for authentication. The NT names of the machines should be used for specifying servers. An authentication request will return one of four values: NTV_NO_ERROR (0) NTV_SERVER_ERROR (1) NTV_PROTOCOL_ERROR (2) NTV_LOGON_ERROR (3) NTV_NO_ERROR is the only return value possible for a successful authentication. All other return values indicate failure, of one sort or another. EXPORT_OK constants =================== NTV_LOGON_ERROR NTV_NO_ERROR NTV_PROTOCOL_ERROR NTV_SERVER_ERROR AUTHOR ====== Patrick Michael Kane, modus@pr.es.to Based on the smbval library from the samba package SEE ALSO ======== perl(1).  File: pm.info, Node: Authen/TacacsPlus, Next: Authen/Ticket, Prev: Authen/Smb, Up: Module List Perl extension for authentication using tacacs+ server ****************************************************** NAME ==== Authen::TacacsPlus - Perl extension for authentication using tacacs+ server SYNOPSIS ======== use Authen::TacacsPlus; $tac = new Authen::TacacsPlus(Host=>$server, Key=>$key, [Port=>'tacacs'], [Timeout=>15]); $tac->authen($username,$passwords); Authen::TacacsPlus::errmsg(); $tac->close(); DESCRIPTION =========== Authen::TacacsPlus allows you to authenticate using tacacs+ server. $tac = new Authen::TacacsPlus(Host=>$server, Key=>$key, [Port=>'tacacs'], [Timeout=>15]); Opens new session with tacacs+ server on host $server, encrypted with key $key. Undefined object is returned if something wrong (check errmsg()). Authen::TacacsPlus::errmsg(); Returns last error message. $tac->authen($username,$password,$authen_type); Tries an authentication with $username and $password. 1 is returned if authenticaton succeded and 0 if failed (check errmsg() for reason). $authen_type is an optional argument that specifies what type of authentication to perform. Allowable options are: Authen::TacacsPlus::TAC_PLUS_AUTHEN_TYPE_ASCII (default) Authen::TacacsPlus::TAC_PLUS_AUTHEN_TYPE_PAP Authen::TacacsPlus::TAC_PLUS_AUTHEN_TYPE_CHAP ASCII uses Tacacs+ version 0, and will authenticate against the "login" or "global" password on the Tacacs+ server. If no authen_type is specified, it defaults to this type of authentication. PAP uses Tacacs+ version 1, and will authenticate against the "pap" or "global" password on the Tacacs+ server. CHAP uses Tacacs+ version 1, and will authenticate against the "chap" or "global" password on the Tacacs+ server. With CHAP, the password if formed by the concatenation of chap id + chap challenge + chap response Ther is example code in test.pl $tac->close(); Closes session with tacacs+ server. EXAMPLE ======= use Authen::TacacsPlus; $tac = new Authen::TacacsPlus(Host=>'foo.bar.ru',Key=>'9999'); unless ($tac){ print "Error: ",Authen::TacacsPlus::errmsg(),"\n"; exit(1); } if ($tac->authen('john','johnpass')){ print "Granted\n"; } else { print "Denied: ",Authen::TacacsPlus::errmsg(),"\n"; } $tac->close(); AUTHOR ====== Mike Shoyher, msh@corbina.net, msh@apache.lexa.ru Mike McCauley, mikem@open.com.au BUGS ==== only authentication is supported only one session may be active (you have to close one session before opening another one) SEE ALSO ======== perl(1).  File: pm.info, Node: Authen/Ticket, Next: Authen/Ticket/Client, Prev: Authen/TacacsPlus, Up: Module List Perl extension for implementing ticket authentication ***************************************************** NAME ==== Authen::Ticket - Perl extension for implementing ticket authentication SYNOPSIS ======== PerlHandler Authen::Ticket or PerlAccessHandler Authen::Ticket ErrorDocument 403 http://ticket.tamu.edu/TicketMaster/ DESCRIPTION =========== Authen::Ticket provides the mod_perl framework for using the Authen::Ticket::Server and Authen::Ticket::Client classes as Apache handlers. To create custom handlers, derive a class (My::Authen) from Authen::Ticket: package My::Authen; use vars (qw/@ISA/); @ISA = (qw/Authen::Ticket/); In addition to My::Authen, the server and client classes are also required: package My::Authen::Server; use vars (qw/@ISA/); @ISA = (qw/Authen::Ticket::Server/); sub authenticate { my($self, $u) = @_; my $t = { }; # do stuff return $t; # hash ref to ticket contents } package My::Authen::Client; use vars (qw/@ISA/); @ISA = (qw/Authen::Ticket::Client/); See the documentation for each of Authen::Ticket::Server and Authen::Ticket::Client for a list of methods that may be implemented. AUTHOR ====== James G. Smith COPYRIGHT ========= Copyright (c) 1999, Texas A&M University. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SEE ALSO ======== perl(1), Authen::Ticket::Client(3), Authen::Ticket::Server(3).  File: pm.info, Node: Authen/Ticket/Client, Next: Authen/Ticket/Server, Prev: Authen/Ticket, Up: Module List Authentication code for the client website ****************************************** NAME ==== Authen::Ticket::Client - Authentication code for the client website DESCRIPTION =========== Authen::Ticket::Client contains the basic tools required to decode and reconstruct the information in a ticket. See Authen::Ticket for the mod_perl access handler using Authen::Ticket::Client. METHODS ======= decode_cookie($class, $ticket) This subroutine returns the decoded version of the ticket. This is the place to put decryption of the cookie or other checks that do not depend on understanding the information within the ticket. The default version decodes from base 64. The return value is the decoded string representation of the ticket. deconstruct_cookie($class, $ticket) This subroutine breaks the ticket apart into field values. The return value is a hash reference containing the key/value pairs. This subroutine should only be concerned with ensuring a properly constructed ticket. initialize() This subroutine may be used to perform particular class initialization beyond the defaults provided by Ticket::Authen::Client->new. Any configuration variables for the httpd configuration file should be placed in the %__PACKAGE__::DEFAULTS hash. AUTHOR ====== James G. Smith, COPYRIGHT ========= Copyright (c) 1999, Texas A&M University. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SEE ALSO ======== perl(1), Authen::Ticket(3), Authen::Ticket::Server(3)  File: pm.info, Node: Authen/Ticket/Server, Next: Authen/Ticket/Signature, Prev: Authen/Ticket/Client, Up: Module List Perl extension for implementing ticket authentication. ****************************************************** NAME ==== Authen::Ticket::Server - Perl extension for implementing ticket authentication. DESCRIPTION =========== Authen::Ticket::Server is an abstract class which provides the skeleton upon which a full ticket issuing master authentication server may be built. With appropriate subroutine definitions, the resulting class may provided authentication for either trusted or untrusted client sites. The class may be used to implement a ticket server either as a mod_perl handler (see Authen::Ticket) or as a CGI script (using the object methods). If the server class is a sub-class of Authen::Ticket::Signature (or comparable class), the ticket will automatically be signed. SERVER OBJECT ============= Authen::Ticket::Server provides an object encapsulating most of the information required to authenticate a user and generate tickets. The following values are contained in the object: $server = new Authen::Ticket::Server; $$server{_r} -> Apache request object iff running under mod_perl $$server{stdout} -> object to print to for HTML pages $$server{query} -> CGI-like object for generating HTML and accessing form data $$server{request_uri} $$server{TicketDomain} -> domain for which ticket is valid $$server{TicketExpires} -> default ticket lifetime The class constructor will work with sub-classes without modification. Sub-class initialization should be placed in the initialize subroutine. SUB-CLASSING ============ A sub-class is required to override any of the methods mentioned in this documentation (e.g., authentication method, HTML forms). Two variables are required in the sub-class package. @ISA This array determines the classes the sub-class will inherit from. For a fully functioning server, this must include Authen::Ticket::Server. If the tickets are to be signed, Authen::Ticket::Signature is recommended. %DEFAULTS This hash contains the default values (or undef) for the configuration options required by the sub-class. These are set in the httpd configuration with the PerlSetVar directive. These are available in the $self hash reference. Example package My::Ticket::Server; @ISA = (qw/Authen::Ticket::Server Authen::Ticket::Signature/); %DEFAULTS = ( TicketUserDatabase => 'mysql:users', TicketDatabaseUser => undef, TicketDatabasePassword => undef, TicketUserFields => 'table:userfield:passwordfield', ); GENERAL METHODS =============== The following methods need not be redefined in any sub-classes. $server = new Authen::Ticket::Server([$r], [%options]) This will return an initialized server object. If $r is a reference and the code is running under mod_perl, then $$server{_r} will be set to $r. Otherwise, all the arguments are taken to belong to a hash defining the default configuration. This method is used in Authen::Ticket->handler and is useful in CGI scripts implementing a ticket server. However, the preferred use of the Authen::Ticket modules is in a mod_perl environment. SUB-CLASS FUNCTIONS =================== The following conventions are used in these sections: $server -> server object $u -> hashref of user authentication information $t -> hashref of ticket information $s -> additional information for inclusion in a message SUB-CLASS REQUIRED FUNCTIONS ============================ Any sub-class of Authen::Ticket::Server must define the following subroutines: $t = $server->authenticate($u) This subroutine returns a hashref of information to be placed in the ticket if the user is authenticated. If the person is not authenticated, it should return undef. The following values are added to $t by $server->handler after authenticated returns successfully: fields -> comma separated list of fields in %$t uid -> $u->{user} ip -> browser IP information depending on $u->{security} expiry -> expiration time of the ticket The default implementation will place a warning in the log file (if running under mod_perl) and refuse authentication. SUB-CLASS RECOMMENDED FUNCTIONS =============================== Any sub-class of Authen::Ticket::Server should define the following subroutines: $q = $server->get_query_object This subroutine returns an object used to retrieve form values and format HTML. This must be CGI or another class that implements the CGI interface (e.g., a sub-class of CGI). The default implementation will return a valid CGI object of type $CGI::DefaultClass. This routine is used in the object constructor to initialize part of the object. $o = $server->get_stdout_object This subroutine returns an object to be used as STDOUT. This must support the $o->print() syntax. The default implementation will return the object to which STDOUT is tied (usually Apache->request object). This routine is used in the object constructor to initialize part of the object. $u = $server->get_userinfo This subroutine returns a hash reference to the information on the authenticating person. Some massaging of the data may take place. This routine transfers data from the input form to an internal representation for further processing. The following fields are expected for correct authentication: user -> username password -> password duration -> lifetime of the ticket security -> {weak,medium,strong} extent to which the browser IP is used The default implementation will pull the above values from the query object. $c = $server->construct_cookie(%$t) This subroutine returns an intermediate value for the ticket. This routine may combine the values in %$t in any manner deemed necessary as long as the client website can deconstruct them. $c = $server->encode_cookie($c) This subroutine encodes the cookie. This may involve encryption or other transforms. However, Authen::Ticket::Signature provides the code for signing tickets. The default implementation base_64 encodes the cookie. SUB-CLASS MISCELLANEOUS FUNCTIONS ================================= Any sub-class of Authen::Ticket::Server may define the following subroutines: $server->no_cookie_error_message($s) This subroutine returns an HTML page to be sent to the browser when the ticket server has detected a lack of support for cookies. $server->no_user_password_error_message($s) This subroutine returns an HTML page to be sent to the browser when the server needs the authentication information from the user. The optional $s parameter will contain any error messages from the previous authentication attempt if there was one. $uri is the URI of the page the server will return to when the user has successfully authenticated. $server->go_to_uri_message This subroutine returns an HTML page to be sent to the browser when the user has successfully authenticated. This page does not need to redirect the browser to $uri. $uri is provided to help those browsers that cannot redirect themselves automatically. AUTHOR ====== James G. Smith COPYRIGHT ========= Copyright (c) 1999, Texas A&M University. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SEE ALSO ======== perl(1), Authen::Ticket(3), Authen::Ticket::Client(3).  File: pm.info, Node: Authen/Ticket/Signature, Next: AuthenIMAP, Prev: Authen/Ticket/Server, Up: Module List Authen::Ticket::Signature - Support for signing authentication tickets SYNOPSIS ======== As key server: SetHandler perl-script PerlSetHandler Authen::Ticket::Signature PerlSetVar TicketSignaturePublicKey http://keys.my.com/keys/${id} PerlSetVar TicketSignatureId General As part of ticket server: package My::Ticket::Server; @ISA = (qw/Authen::Ticket::Server Authen::Ticket::Signature/); As part of ticket client: package My::Ticket::Client; @ISA = (qw/Authen::Ticket::Client Authen::Ticket::Signature/); DESCRIPTION =========== Authen::Ticket::Signature provides the framework for signing and verifying tickets. The El Gamal algorithm is included in the code as a good default signing algorithm. The default key length is 512 bits. If IPC::Shareable is available, keys are cached in shared memory across processes. This is a virtual requirement for a multiprocess Apache ticket server since all tickets should be signed by the same key. This is only a memory issue for client websites if several keys might need to be cached simultaneously. Different keys may be cached with each having an identifying name. This name is used to retrieve the public portion of the key from the key server. The key to be retrieved for use in signing or verification is determined by the server configuration. METHODS ======= Adding Authen::Ticket::Signature to the @ISA array for the ::Client or ::Server class will add the following methods to that class. Any may be overridden, though only generate_key, sign_ticket, and verify_ticket are recommended. All numbers are expected to be objects of type OpenSSL::BN. handler This routine provides the key server functionality. Only public keys may be requested. The path-info part of the request is the name of a key. For example, if http://my.com/keys is the location of the key server, then http://my.com/keys/general will return the public key of the default key for signing tickets. $self->get_public_key This routine will return the public key as appropriate according to the server configuration. If the key is not available in memory, an attempt will be made to fetch the key either from a remote server or the file system. A public key is a hash reference with the various parts of the key. This is algorithm dependent. The El Gamal routine will return the following hashref: { 'y' => $y, 'p' => $p, 'g' => $g } This is returned by the key server as the string "y:$y;p:$p;g:$g" with the values in hexadecimal. $self->get_private_key This routine will return the private key as appropriate according to the server configuration. If the required key is not available in cache, it will be generated. Since the private key is only to be used on the machine it is generated on, it does not make sense to fetch the private key from any particular location. A private key is a hash reference with the various parts of the key. This is algorithm dependent. The El Gamal routine will return the following hashref: { 'x' => $x, 'p' => $p, 'g' => $g } $self->generate_key( $key_length ) This routine must return the private and public key parts with a nominal key length of $key_length. See the get_{private,public}_key routines for the format of the key parts. The actual value returned is an array of the format: ( { private_key }, { public_key } ) $self->sign_ticket( $ticket ) This routine should attach a signature to $ticket and return the resulting value. The format used must be understood by $self->verify_ticket. The $ticket will have already been passed through $self->construct_ticket and $self->encode_ticket. $self->verify_ticket( $ticket ) This routine should verify the signature on the $ticket and return the encoded ticket without the signature (this would be the value that was passed to sign_ticket). The following must hold true: $self->verify_ticket($self->sign_ticket($ticket)) eq $ticket WHY EL GAMAL? ============= This code was produced and is maintained within the United States of America. As many are aware, export restrictions on cryptographic products exist. This section explains what algorithm was chosen and why it should not violate any export regulations. The El Gamal algorithms are not under any patent or licensing restrictions and may thus be used freely, though with export restrictions in mind. The default algorithm in Authen::Ticket::Signature is El Gamal. The supplied code IS NOT INTENDED to be used to encrypt messages. Other parts of the algorithm may be used for encryption, but the signature portions are not intended to encrypt and decrypt data. However, [Schneier 532] points out the ability to send subliminal messages using the signature algorithms. SHARED MEMORY ============= The code tries to use IPC::Shareable if it is already loaded. Apache can go into an endless spin with children being dieing and being created if the IPC::Shareable code causes a segfault during child initialization. This can happen when a previously created shared memory segment has not been properly disposed of and also cannot be connected to. If IPC::Shareable is not loaded during the server startup, the Authen::Ticket::Signature code will not try to use it. Therefore, you must load IPC::Shareable before loading Authen::Ticket::Signature or any class derived from it. AUTHOR ====== James G. Smith, Portions of code are based on [Orwant 552-554] and [Stein 320]. COPYRIGHT ========= Copyright (c) 1999, Texas A&M University. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SEE ALSO ======== perl(1), Authen::Ticket(3), Authen::Ticket::Server(3), Authen::Ticket::Client(3) Orwant, Jon, et. al. *Mastering Agorithms with Perl*, O'Reilly & Associates, 1999. Schneier, Bruce *Applied Cryptography*, 2nd ed., John Wiley & Sons, 1996. Stein, Lincoln, & Doug MacEachern. *Writing Apache Modules with Perl and C*, O'Reilly & Associates, 1999.  File: pm.info, Node: AuthenIMAP, Next: AutoLoader, Prev: Authen/Ticket/Signature, Up: Module List Authentication via an IMAP server ********************************* NAME ==== Apache::AuthenIMAP - Authentication via an IMAP server SYNOPSIS ======== # Configuration in httpd.conf PerlModule Apache::AuthenIMAP # Authentication in .htaccess AuthName IMAP AuthType Basic # authenticate via IMAP PerlAuthenHandler Apache::AuthenIMAP PerlSetVar Auth_IMAP_host imaphost.domain.foo require user fred The AuthType is limited to Basic. The require directive is limited to 'valid-user' and 'user user_1 user_2 ...'. DESCRIPTION =========== This module allows authentication against an IMAP server. LIST OF TOKENS ============== * Auth_IMAP_host The IMAP server host: either its name or its dotted quad IP number. This is passed as the PeerAddr option to IO::Socket::INET->new. * Auth_IMAP_port The port on which the IMAP server is listening: either its service name or its actual port number. This parameter defaults to "imap" which is the official service name for IMAP servers. The parameter is passed as the PeerPort option to IO::Socket::INET->new. CONFIGURATION ============= The module should be loaded upon startup of the Apache daemon. Add the following line to your httpd.conf: PerlModule Apache::AuthenIMAP PREREQUISITES ============= For AuthenIMAP you need to enable the appropriate call-back hook when making mod_perl: perl Makefile.PL PERL_AUTHEN=1 SEE ALSO ======== *Note Apache: Apache,, `mod_perl' in this node AUTHORS ======= * mod_perl by Doug MacEachern * Apache::AuthenIMAP by Malcolm Beattie COPYRIGHT ========= The Apache::AuthenIMAP module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: AutoLoader, Next: AutoSplit, Prev: AuthenIMAP, Up: Module List load subroutines only on demand ******************************* NAME ==== AutoLoader - load subroutines only on demand SYNOPSIS ======== package Foo; use AutoLoader 'AUTOLOAD'; # import the default AUTOLOAD subroutine package Bar; use AutoLoader; # don't import AUTOLOAD, define our own sub AUTOLOAD { ... $AutoLoader::AUTOLOAD = "..."; goto &AutoLoader::AUTOLOAD; } DESCRIPTION =========== The AutoLoader module works with the AutoSplit module and the `__END__' token to defer the loading of some subroutines until they are used rather than loading them all at once. To use AutoLoader, the author of a module has to place the definitions of subroutines to be autoloaded after an `__END__' token. (See *Note Perldata: (perl.info)perldata,.) The AutoSplit module can then be run manually to extract the definitions into individual files `auto/funcname.al'. AutoLoader implements an AUTOLOAD subroutine. When an undefined subroutine in is called in a client module of AutoLoader, AutoLoader's AUTOLOAD subroutine attempts to locate the subroutine in a file with a name related to the location of the file from which the client module was read. As an example, if `POSIX.pm' is located in `/usr/local/lib/perl5/POSIX.pm', AutoLoader will look for perl subroutines POSIX in `/usr/local/lib/perl5/auto/POSIX/*.al', where the `.al' file has the same name as the subroutine, sans package. If such a file exists, AUTOLOAD will read and evaluate it, thus (presumably) defining the needed subroutine. AUTOLOAD will then goto the newly defined subroutine. Once this process completes for a given function, it is defined, so future calls to the subroutine will bypass the AUTOLOAD mechanism. Subroutine Stubs ---------------- In order for object method lookup and/or prototype checking to operate correctly even when methods have not yet been defined it is necessary to "forward declare" each subroutine (as in `sub NAME;'). See `"SYNOPSIS"', *Note Perlsub: (perl.info)perlsub,. Such forward declaration creates "subroutine stubs", which are place holders with no code. The AutoSplit and AutoLoader modules automate the creation of forward declarations. The AutoSplit module creates an 'index' file containing forward declarations of all the AutoSplit subroutines. When the AutoLoader module is 'use'd it loads these declarations into its callers package. Because of this mechanism it is important that AutoLoader is always used and not required. Using AutoLoader's AUTOLOAD Subroutine -------------------------------------- In order to use AutoLoader's AUTOLOAD subroutine you must explicitly import it: use AutoLoader 'AUTOLOAD'; Overriding AutoLoader's AUTOLOAD Subroutine ------------------------------------------- Some modules, mainly extensions, provide their own AUTOLOAD subroutines. They typically need to check for some special cases (such as constants) and then fallback to AutoLoader's AUTOLOAD for the rest. Such modules should not import AutoLoader's AUTOLOAD subroutine. Instead, they should define their own AUTOLOAD subroutines along these lines: use AutoLoader; use Carp; sub AUTOLOAD { my $sub = $AUTOLOAD; (my $constname = $sub) =~ s/.*:://; my $val = constant($constname, @_ ? $_[0] : 0); if ($! != 0) { if ($! =~ /Invalid/ || $!{EINVAL}) { $AutoLoader::AUTOLOAD = $sub; goto &AutoLoader::AUTOLOAD; } else { croak "Your vendor has not defined constant $constname"; } } *$sub = sub { $val }; # same as: eval "sub $sub { $val }"; goto &$sub; } If any module's own AUTOLOAD subroutine has no need to fallback to the AutoLoader's AUTOLOAD subroutine (because it doesn't have any AutoSplit subroutines), then that module should not use AutoLoader at all. Package Lexicals ---------------- Package lexicals declared with my in the main block of a package using AutoLoader will not be visible to auto-loaded subroutines, due to the fact that the given scope ends at the `__END__' marker. A module using such variables as package globals will not work properly under the AutoLoader. The vars pragma (see `"vars"', *Note Perlmod: (perl.info)perlmod,) may be used in such situations as an alternative to explicitly qualifying all globals with the package namespace. Variables pre-declared with this pragma will be visible to any autoloaded routines (but will not be invisible outside the package, unfortunately). AutoLoader vs. SelfLoader ------------------------- The AutoLoader is similar in purpose to SelfLoader: both delay the loading of subroutines. SelfLoader uses the `__DATA__' marker rather than `__END__'. While this avoids the use of a hierarchy of disk files and the associated open/close for each routine loaded, SelfLoader suffers a startup speed disadvantage in the one-time parsing of the lines after `__DATA__', after which routines are cached. SelfLoader can also handle multiple packages in a file. AutoLoader only reads code as it is requested, and in many cases should be faster, but requires a mechanism like AutoSplit be used to create the individual files. *Note ExtUtils/MakeMaker: ExtUtils/MakeMaker, will invoke AutoSplit automatically if AutoLoader is used in a module source file. CAVEATS ======= AutoLoaders prior to Perl 5.002 had a slightly different interface. Any old modules which use AutoLoader should be changed to the new calling style. Typically this just means changing a require to a use, adding the explicit `'AUTOLOAD'' import if needed, and removing AutoLoader from `@ISA'. On systems with restrictions on file name length, the file corresponding to a subroutine may have a shorter name that the routine itself. This can lead to conflicting file names. The AutoSplit package warns of these potential conflicts when used to split a module. AutoLoader may fail to find the autosplit files (or even find the wrong ones) in cases where `@INC' contains relative paths, and the program does chdir. SEE ALSO ======== *Note SelfLoader: SelfLoader, - an autoloader that doesn't use external files.  File: pm.info, Node: AutoSplit, Next: Aviation/Report, Prev: AutoLoader, Up: Module List split a package for autoloading ******************************* NAME ==== AutoSplit - split a package for autoloading SYNOPSIS ======== autosplit($file, $dir, $keep, $check, $modtime); autosplit_lib_modules(@modules); DESCRIPTION =========== This function will split up your program into files that the AutoLoader module can handle. It is used by both the standard perl libraries and by the MakeMaker utility, to automatically configure libraries for autoloading. The `autosplit' interface splits the specified file into a hierarchy rooted at the directory $dir. It creates directories as needed to reflect class hierarchy, and creates the file `autosplit.ix'. This file acts as both forward declaration of all package routines, and as timestamp for the last update of the hierarchy. The remaining three arguments to `autosplit' govern other options to the autosplitter. $keep If the third argument, $keep, is false, then any pre-existing `*.al' files in the autoload directory are removed if they are no longer part of the module (obsoleted functions). $keep defaults to 0. $check The fourth argument, $check, instructs `autosplit' to check the module currently being split to ensure that it does include a use specification for the AutoLoader module, and skips the module if AutoLoader is not detected. $check defaults to 1. $modtime Lastly, the $modtime argument specifies that `autosplit' is to check the modification time of the module against that of the `autosplit.ix' file, and only split the module if it is newer. $modtime defaults to 1. Typical use of AutoSplit in the perl MakeMaker utility is via the command-line with: perl -e 'use AutoSplit; autosplit($ARGV[0], $ARGV[1], 0, 1, 1)' Defined as a Make macro, it is invoked with file and directory arguments; `autosplit' will split the specified file into the specified directory and delete obsolete `.al' files, after checking first that the module does use the AutoLoader, and ensuring that the module is not already currently split in its current form (the modtime test). The `autosplit_lib_modules' form is used in the building of perl. It takes as input a list of files (modules) that are assumed to reside in a directory lib relative to the current directory. Each file is sent to the autosplitter one at a time, to be split into the directory *lib/auto*. In both usages of the autosplitter, only subroutines defined following the perl *__END__* token are split out into separate files. Some routines may be placed prior to this marker to force their immediate loading and parsing. Multiple packages ----------------- As of version 1.01 of the AutoSplit module it is possible to have multiple packages within a single file. Both of the following cases are supported: package NAME; __END__ sub AAA { ... } package NAME::option1; sub BBB { ... } package NAME::option2; sub BBB { ... } package NAME; __END__ sub AAA { ... } sub NAME::option1::BBB { ... } sub NAME::option2::BBB { ... } DIAGNOSTICS =========== AutoSplit will inform the user if it is necessary to create the top-level directory specified in the invocation. It is preferred that the script or installation process that invokes AutoSplit have created the full directory path ahead of time. This warning may indicate that the module is being split into an incorrect path. AutoSplit will warn the user of all subroutines whose name causes potential file naming conflicts on machines with drastically limited (8 characters or less) file name length. Since the subroutine name is used as the file name, these warnings can aid in portability to such systems. Warnings are issued and the file skipped if AutoSplit cannot locate either the *__END__* marker or a "package Name;"-style specification. AutoSplit will also emit general diagnostics for inability to create directories or files.