This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Audio/Wav, Next: Audio/Wav/Read, Prev: Audio/Tools/Time, Up: Module List Modules for reading & writing Microsoft Wav files. ************************************************** NAME ==== Audio::Wav - Modules for reading & writing Microsoft Wav files. SYNOPSIS ======== use Audio; my $buffer = 512; my $wav = new Audio::Wav; my $read = $wav -> read( 'testout.wav' ); my $write = $wav -> write( 'testcopy.wav', $read -> details() ); my $total = 0; my $length = $read -> length(); while ( $total < $length ) { my $left = $length - $total; $buffer = $left unless $left > $buffer; my $data = $read -> read_raw( $buffer ); last unless defined( $data ); $write -> write_raw( $data, $buffer ); $total += $buffer; } $write -> finish(); NOTES ===== All sample positions used are in byte offsets (*Note Audio/Tools/Time: Audio/Tools/Time, for conversion utilities) DESCRIPTION =========== These modules provide a method of reading & writing uncompressed Microsoft Wav files. It was developed on mswin32 so I'm not sure if this version has the correct byte order for big endian machines. AUTHOR ====== Nick Peskett - nick@soup.demon.co.uk SEE ALSO ======== L L L METHODS ======= new --- Returns a blessed Audio::Wav object. my $wav = new Audio::Wav; write ----- Returns a blessed Audio::Wav::Write object. my $details = { 'bits_sample' => 16, 'sample_rate' => 44100, 'channels' => 2, }; my $write = $wav -> write( 'testout.wav', $details ); See *Note Audio/Wav/Write: Audio/Wav/Write, for methods. read ---- Returns a blessed Audio::Wav::Read object. my $read = $wav -> read( 'testout.wav' ); See *Note Audio/Wav/Read: Audio/Wav/Read, for methods.  File: pm.info, Node: Audio/Wav/Read, Next: Audio/Wav/Write, Prev: Audio/Wav, Up: Module List Module for reading Microsoft Wav files. *************************************** NAME ==== Audio::Wav::Read - Module for reading Microsoft Wav files. SYNOPSIS ======== use Audio::Wav; my $wav = new Audio::Wav; my $read = $wav -> read( 'filename.wav' ); my $details = $read -> details(); DESCRIPTION =========== Reads Microsoft Wav files. AUTHOR ====== Nick Peskett - nick@soup.demon.co.uk SEE ALSO ======== *Note Audio/Wav: Audio/Wav, *Note Audio/Wav/Write: Audio/Wav/Write, NOTES ===== This module shouldn't be used directly, a blessed object can be returned from *Note Audio/Wav: Audio/Wav,. METHODS ======= file_name --------- Returns the file name. my $file = $read -> file_name(); get_info -------- Returns information contained within the wav file. my $info = $read -> get_info(); Returns a reference to a hash containing; (for example, a file marked up for use in Audio::Mix) { keywords => 'bpm:126 key:a', name => 'Mission Venice', artist => 'Nightmares on Wax' }; get_cues -------- Returns the cuepoints marked within the wav file. my $cues = $read -> get_cues(); Returns a reference to a hash containing; (for example, a file marked up for use in Audio::Mix) (position is byte offset) { 1 => { label => 'sig', position => 764343, note => 'first' }, 2 => { label => 'fade_in', position => 1661774, note => 'trig' }, 3 => { label => 'sig', position => 18033735, note => 'last' }, 4 => { label => 'fade_out', position => 17145150, note => 'trig' }, 5 => { label => 'end', position => 18271676 } } read_raw -------- Reads raw packed bytes from the current audio data position in the file. my $data = $self -> read_raw( $byte_length ); read ---- Returns the current audio data position sample across all channels. my @channels = $self -> read(); Returns an array of unpacked samples. Each element is a channel i.e ( left, right ). The numbers will be in the range; where $samp_max = ( 2 ** bits_per_sample ) / 2 -$samp_max to +$samp_max position -------- Returns the current audio data position (as byte offset). my $byte_offset = $read -> position(); move_to ------- Moves the current audio data position to byte offset. $read -> move_to( $byte_offset ); length ------ Returns the number of bytes of audio data in the file. my $audio_bytes = $read -> length(); details ------- Returns a reference to a hash of lots of details about the file. Too many to list here, try it with Data::Dumper..... use Data::Dumper; my $details = $read -> details(); print Data::Dumper->Dump([ $details ]);  File: pm.info, Node: Audio/Wav/Write, Next: AudioCD, Prev: Audio/Wav/Read, Up: Module List Module for writing Microsoft Wav files. *************************************** NAME ==== Audio::Wav::Write - Module for writing Microsoft Wav files. SYNOPSIS ======== use Audio::Wav; my $wav = new Audio::Wav; my $sample_rate = 44100; my $bits_sample = 16; my $details = { 'bits_sample' => $bits_sample, 'sample_rate' => $sample_rate, 'channels' => 1, }; my $write = $wav -> write( 'testout.wav', $details ); &add_sine( 200, 1 ); sub add_sine { my $hz = shift; my $length = shift; my $pi = ( 22 / 7 ) * 2; $length *= $sample_rate; my $max_no = ( 2 ** $bits_sample ) / 2; for my $pos ( 0 .. $length ) { $time = $pos / $sample_rate; $time *= $hz; my $val = sin $pi * $time; my $samp = $val * $max_no; $write -> write( $samp ); } } $write -> finish(); DESCRIPTION =========== Currently only writes to a file. AUTHOR ====== Nick Peskett - nick@soup.demon.co.uk SEE ALSO ======== *Note Audio/Wav: Audio/Wav, *Note Audio/Wav/Read: Audio/Wav/Read, NOTES ===== This module shouldn't be used directly, a blessed object can be returned from *Note Audio/Wav: Audio/Wav,. METHODS ======= finish ------ Finishes off & closes the current wav file. $write -> finish(); add_cue ------- Adds a cue point to the wav file. $write -> add_cue( $byte_offset, "label", "note" ); file_name --------- Returns the current filename (silly, I know). my $file = $write -> file_name(); write ----- Adds a sample to the current file. $write -> write( @sample_channels ); Each element in @sample_channels should be in the range of; where $samp_max = ( 2 ** bits_per_sample ) / 2 -$samp_max to +$samp_max write_raw --------- Adds a some pre-packed data to the current file. $write -> write_raw( $data, $data_length ); Where; $data is the packed data $data_length (optional) is the length in bytes of the data  File: pm.info, Node: AudioCD, Next: AudioCD/Mac, Prev: Audio/Wav/Write, Up: Module List Module for basic Audio CD control ********************************* NAME ==== AudioCD - Module for basic Audio CD control SYNOPSIS ======== use AudioCD; # see below DESCRIPTION =========== See `AudioCD::Mac' for more information. Right now, this module has support only for MacPerl. Please feel free to write other modules for Your Favorite Platform and let me know about it. AUTHOR ====== Chris Nandor `' http://pudge.net/ Copyright (c) 1998 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl Artistic License. VERSION ======= v0.20, Wednesday, December 9, 1998 Renamed to `AudioCD', added controls for Audio CD. v0.10, Thursday, October 8, 1998 First version, made for Mac OS to get CDDB TOC data. SEE ALSO ======== `CDDB.pm'  File: pm.info, Node: AudioCD/Mac, Next: Authen/ACE, Prev: AudioCD, Up: Module List MacPerl extension for controlling Audio CDs ******************************************* NAME ==== AudioCD::Mac - MacPerl extension for controlling Audio CDs SYNOPSIS ======== #!perl -w use AudioCD; use strict; my $cd = new AudioCD; $cd->volume(255); $cd->play(2); print "Now playing\n" if $cd->status == CD_PLAY; printf "Volume is %d\n", $cd->volume; sleep(5); $cd->pause; print "Now paused\n" if $cd->status == CD_PAUSE; sleep(5); $cd->volume(100); $cd->continue; print "Now playing\n" if $cd->status == CD_PLAY; printf "Volume is %d\n", $cd->volume; sleep(5); my @info = $cd->info; printf "Currently at track %d, %.2d:%.2d\n", @info[0..2]; $cd->stop; my $status = $cd->status; print "Now stopped\n" if ($status == CD_FINISH || $status == CD_STOP); if (do 'CDDB.pm') { # sold separately my $cddb = new CDDB; my @cddb_info = $cddb->calculate_id( $cd->cddb_toc ); my @discs = $cddb->get_discs(@cddb_info[0, 3, 4]); print "You were probably listening to $discs[0]->[2]\n"; } $cd->eject; DESCRIPTION =========== This is the MacPerl module to be used by the `AudioCD' module. Other modules can be written for other platforms, but this one is Mac specific, calling Mac OS APIs to control the CD player. FUNCTIONS ========= All functions except for new are methods that need to be called via the `AudioCD' object. All functions attempt to return undef and set $^E on failure, and unless otherwise specified, return 1 on success. Note that the data returned from the Mac OS APIs is often in BCD format, but the functions that return track and time data convert it to decimal. new Should be called from `AudioCD', not `AudioCD::Mac', but should work either way. Returns the object. status Returns the current status of the CD, one of: CD_PLAY, CD_PAUSE, CD_MUTE, CD_FINISH, CD_ERR, CD_STOP, CD_OFFLINE. info Returns an array of information about the CD, with two sets of times, one for the current track, one for the disc. The first item in the list is the current track number. # 0 1 2 3 4 5 6 ($t_number, $t_min, $t_sec, $t_frames, $a_min, $a_sec, $a_frames) = $cd->info; play([TRACK]) If called without a track number, will start from the first track if stopped, or continue if paused. Otherwise will start at specified track number, and continue until the CD is finished. stop Stops the CD. Time settings will likely be left at last play point, not at beginning of CD. pause Will pause the CD if it is playing, or continue playing if paused. continue Will continue playing if paused. eject Will unmount the volumes on the drive if any, and then eject the tray. volume([LEFT_VOLUME [, RIGHT_VOLUME]]) Sets the left and right channels to a valume from 0 to 255. Returns the left and right channel volumes, unless the two have the same value and the method is called in a scalar context, in which case it returns just one value. If `RIGHT_VOLUME' is not supplied, it will be set to the same value as supplied in `LEFT_VOLUME'. If not values are supplied, the current volume value(s) will be returned, and will remain unchanged. cd_toc Returns the table of contents in an anonymous array, where each element is another anonymous array, containing the track number [0] and the track's starting time offset from the beginning of the CD in minutes [1], seconds [2], and frames [3]. cddb_toc Returns the same as above, but in a format suitable for passing to the `CDDB' module. last_track Ideally, returns the last audio track number on the CD. If this turns out to be wrong, let me know. TODO ==== Change interface to work well with others (Tuomas' Linux code) Add support for multiple drives, multiple volumes on drive Add support for moving forward/backward in tracks, and scanning Add support for modes (stereo/mono/etc., random/program/repeat/etc.) Add support to add/extract data in the CD Remote Programs file Need good test suite ... don't know how this should work, since I won't have good data to test against. Maybe I should just play some tracks, change the volume, print out the number of tracks and have the user say whether or not it passes. AUTHOR ====== Chris Nandor `' http://pudge.net/ Copyright (c) 1998 Chris Nandor. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the Perl Artistic License. Special thanks to Matthias Neeracher for help with MacPerl XS and C, and Glenn Howes for his code examples that helped me understand this stuff. http://www.xnet.com/~grhowes/html/helpful.html For more info, check out Technote DV22: http://developer.apple.com/technotes/dv/dv_22.html HISTORY ======= v0.25, Thursday, December 11, 1998 Significant clean up of Perl and XS code, lots of misc. changes. Hopefully fixed cd_toc to give all the right values. Fixed eject problems. "no pointer is a pointer, too" -- Matthias Neeracher v0.20, Wednesday, December 9, 1998 Renamed to `AudioCD', added controls for Audio CD. v0.10, Thursday, October 8, 1998 First version, made for Mac OS to get CDDB TOC data. VERSION ======= v0.25, Thursday, December 11, 1998 SEE ALSO ======== CDDB.pm.  File: pm.info, Node: Authen/ACE, Next: Authen/Challenge/Basic, Prev: AudioCD/Mac, Up: Module List Perl extension for accessing a SecurID ACE server ************************************************* NAME ==== Authen::ACE - Perl extension for accessing a SecurID ACE server SYNOPSIS ======== use Authen::ACE; $ace = new Ace([config => /config/directory]) $ace->Check(code, username); $ace->PIN(PIN, [cancel]); $ace->Next(code); $ace->Auth([username]); DESCRIPTION =========== Authen::ACE provides a client interface to a Security Dynamics SecurID ACE server. SecurID authentication can be added to any Perl application using Authen::ACE. Instantiation of an object into the Authen::ACE class will establish a connection to the ACE server; destruction of the object will close the connection. Programs can then use the Check/PIN/Next methods to authorize a user. TTY programs can also use the Auth method, which handles all authorization tasks normally done by Check/PIN/Next. METHODS ======= new $ace = new Ace(["config" => "/config/directory"]) Creates a new Authen::ACE object. The config parameter specifies the location of the `sdconf.rec' file. It defaults to the value of the `VAR_ACE' environment variable, or the directory `/var/ace' if this variable isn't set. Check ($result,$info) = $ace->Check(code, username) This is the primary user authentication function. code is the PIN+token (or just the token if the user has no PIN), and username is the user's name, as it is listed in the ACE database. Check returns a two-element list. The first element contains the results of the check; the second element contains extra, result-specific information. Possible results for $result are ACM_OK The check succeeded. $info contains the shell specified for this user. ACM_ACCESS_DENIED The check failed. No other information is included. ACM_NEXT_CODE_REQUIRED The check succeeded, but requires a second token to finish the authentication. $info contains the number of seconds the server will waits for the next code. Authen::ACE::Next should be called with the next code upon receiving this result. ACM_NEW_PIN_REQUIRED A new PIN is required. $info is a ref to an anonymous hash with the following elements system_pin The system generated PIN. min_pin_len The minimum PIN length. max_pin_len The maximum PIN length. alphanumeric True is the PIN is allowed to be alphanumeric user_selectable Will have one of the values *CANNOT_CHOOSE_PIN*, *MUST_CHOOSE_PIN*, *USER_SELECTABLE*, which mean that the user must accept the system generated PIN, must choose his own PIN, or can do either. If the user accepts the system PIN or chooses his own, then a call should be made to Authen::ACE::PIN with the selected PIN. If the user rejects the system PIN, then a call should be made to Authen::ACE::PIN with the value of the *cancel* parameter set to 1. Next ($result,$info) = $ace->Next(code) This method should be called after receiving a ACM_NEXT_CODE_REQUIRED result from Check. code should be the next to display on the user's token. Return value is the same as for Authen::ACE::Check, except that there will never be a ACM_NEW_PIN_REQUIRED or ACM_NEXT_CODE_REQUIRED result. PIN $result = $ace->PIN(pin, [cancel]); This method should be called after receiving a ACM_NEW_PIN_REQUIRED result from Check. *pin* should be the new PIN, while *cancel* should be set to one if the user wishes to cancel the new PIN operation. Authen::ACE::PIN will return a result of either *ACM_NEW_PIN_ACCEPTED* or *ACM_NEW_PIN_REJECTED*. Auth ($result,$info) = $ace->Auth([username]); This method is a convenience method which will handle calling Check, and reading a new PIN or requesting the next token if required. It should only be called if the running process is attached to a tty. username will be determined by the real PID of the process running the program if it isn't passed as a parameter. The return value is the same as for Authen::ACE::Check, except that there will never be a ACM_NEW_PIN_REQUIRED or ACM_NEXT_CODE_REQUIRED result. AUTHOR ====== Dave Carrigan Copyright (C) 1997 Dave Carrigan, Interprovincial Pipe Line Inc. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), ACE/Server Administration Manual, ACE/Server Client API Guide  File: pm.info, Node: Authen/Challenge/Basic, Next: Authen/FAQ, Prev: Authen/ACE, Up: Module List A Basic challenge/response authentication scheme. ************************************************* NAME ==== Authen::Challenge::Basic - A Basic challenge/response authentication scheme. SYNOPSIS ======== use Authen::Challenge::Basic; $server = Authen::Challenge->new ('Secret' => 'known2us', 'Timeout' => 30, 'Sync' => 10); $client = Authen::Challenge->new ('Secret' => 'known2us', 'Timeout' => 30, 'Sync' => 10); $challenge = $server->Challenge; $response = $client->Response($challenge); if ($server->Validate($challenge, $response)) { print "Hi master\n"; } else { print "Impostor!\n"; } DESCRIPTION =========== Authen::Challenge::Basic provides a simple MD5-based challenge/response protocol allowing for mutual peer authentication in a session. The protocol includes timing information, so it is possible to introduce time constraints in the session to help prevent attacks that rely on adjusting the clock in one of the peers. This protocol requires a shared secret to be known only to the peers. The compromise of this secret also compromises this protocol, so it should be treated as a trusted password for that matter. Challenge/response sessions are not 'replayable' provided that the attacker ignores the shared secret. The sessions are also associated to the instance that produced the challenge. This means that it can only be Validate()'d by the instance that produced the challenge in the first place. The built-in random number generator from perl is used in this module. Hooks for better random number generators are planned soon to increase the relative strength of this protocol. In any case, the main security dependencies for this module are MD5 itself and the secrecy of the shared secret. The following functions are provided by this class. new() Creates a new instance of a challenge/response endpoint. It has three parameters that influence its behavior. Those can be seen next $server = Authen::Challenge::Basic->new ('Secret' => 'known2us', 'Timeout' => 30, 'Sync' => 10); 'Secret' is used to indicate the shared secret to use in this session. 'Timeout' specifies the lifespan, in seconds, for this transaction. This means that a succesful Validate() must occur within this many seconds to have a chance to be acknowledged. Reducing this value too much can cause problems as a slight ammount of load can make the session fail. 30 seconds is a reasonable default for many uses. If left unspecified, no timeout is enforced. 'Sync' indicates how strict are we with regard to the clock in our peer. The parameter contains the maximum offset in seconds between the clocks of the peers. The more strict we are (ie, the smaller the number), the less tolerant we are. If left unspecified, we'll allow any ammount of drift. It's specified in seconds. Challenge() Issues a new challenge. The object creating this challenge stores information about it that allows for later recognition and validation. The Challenge() is a typical function of the server, though a double Challenge/Response scenario allows mutual authentication such as in the following scheme: Client Server (1) C1 ----------------------> (2) <---------------------- R(C1), C2 (3) R(C2) ----------------------> On stage (2), the Client is authenticated to the server. On stage (3), both are mutually authenticated. This method is usually invoked like $challenge = $server->Challenge; $challenge will contain a printable string that must be passed to the peer in order for a response to be received. Response() This method takes a challenge and generates the required response. This is usually invoked as $response = $client->Response($challenge); Where $challenge contains a Challenge generated by a call to Challenge(). $response will contain a printable string that must be returned to the peer in order for it to be validated. Validate() This method verifies the correctness of the Challenge/Response session by insuring that: (a) The challenge was indeed generated from this instance and is pending validation (b) The time interval for the validation is acceptable (c) The shared secret was used by the peer to create the response Usually this method is invoked like this $r = $server->Validate($challenge, $response); It returns a true value to indicate a correct session where (a), (b) and (c) hold true or false otherwise. CAVEATS ======= Note that this module helps insure that the peers were who they said they where provided that the shared secret is not known to any third parties. If this is not true, then anything could happen. Also, after the initial authentication, a network connection can be stolen or hijacked, rendering all of the tests useless. AUTHOR ====== Luis E. Munoz  File: pm.info, Node: Authen/FAQ, Next: Authen/Krb4, Prev: Authen/Challenge/Basic, Up: Module List Frequently-Asked Questions about Authen::PAM. ********************************************* NAME ==== pam_faq - Frequently-Asked Questions about Authen::PAM. SYNOPSIS ======== perldoc pam_faq VERSION ======= This document is currently at version 0.01, as of *April 21, 2000* DESCRIPTION =========== 1. Can I authenticate a user non interactively? ----------------------------------------------- Yes, you can although not in a very clean way. The PAM library has a mechanism, in a form of a conversation function, to send and receive text data from the user. For details of the format of the conversation function consult the Authen::PAM manual. This function receives a list of code/string pairs. There are two codes (PAM_TEXT_INFO and PAM_ERROR_MSG) for displaying the associated string to the user and two codes (PAM_ECHO_ON and PAM_ECHO_OFF) for getting input from the user. As you can see the codes are rather general and you can not be completely sure when you are asked for a user name and when for a password. However, the common practice is that PAM_ECHO_ON is used for a user name and PAM_ECHO_OFF is used for a password. So, what you can do is to write your own conversation function which ignores the PAM_TEXT_INFO and PAM_ERROR_MSG codes and returns the user name for the code PAM_ECHO_ON and the password for the code PAM_ECHO_OFF. If you pass the user name in the initialization function then usually you will not be asked for it. Here is a simple example how to do this: use Authen::PAM; $service = "passwd"; $username = "foo"; $password = "bar"; sub my_conv_func { my @res; while ( @_ ) { my $code = shift; my $msg = shift; my $ans = ""; $ans = $username if ($code == PAM_PROMPT_ECHO_ON() ); $ans = $password if ($code == PAM_PROMPT_ECHO_OFF() ); push @res, (PAM_SUCCESS(),$ans); } push @res, PAM_SUCCESS(); return @res; } ref($pamh = new Authen::PAM($service, $username, \&my_conv_func)) || die "Error code $pamh during PAM init!"; $pamh->pam_authenticate; The Authen::PAM module comes with a default conversation function which you can find in the file `PAM.pm'. 2. Can I change a password non interactively? --------------------------------------------- All the discussion of the previous question also applies here. There is however one serious complication. When changing a password it is quite possible that the PAM library will send you at lest two PAM_ECHO_OFF prompts - one for the old password and one or two for the new one. Therefore, the first thing you should do is to see what sequence of prompts is produced by your service. Then the conversation function should include some state variable to distinguish the different prompts. Here is an example: use Authen::PAM; $service = "passwd"; $username = "foo"; $oldpassword = "bar_old"; $newpassword = "bar_new"; sub my_conv_func { my @res; while ( @_ ) { my $code = shift; my $msg = shift; my $ans = ""; $ans = $username if ($code == PAM_PROMPT_ECHO_ON() ); if ($code == PAM_PROMPT_ECHO_OFF() ) { $ans = $oldpassword if ($state == 0); $ans = $newpassword if ($state == 1); $ans = $newpassword if ($state == 2); $state++; } push @res, (PAM_SUCCESS(),$ans); } push @res, PAM_SUCCESS(); return @res; } ref($pamh = new Authen::PAM($service, $username, \&my_conv_func)) || die "Error code $pamh during PAM init!"; $state = 0; $pamh->pam_chauthtok; =head2 3. Is there a conversation function which translates the PAM requests to HTML form? So far I am not aware of any. However if you known that there exists or want to write one you can contact me. The idea of implementing such web interface is that when the conversation function is called it constructs a HTML page from the input codes and strings. The major problem with this approach is that the HTTP protocol is stateless. To overcome this difficulty you should write some daemon program which interacts with the PAM library and keeps the current state of the conversation. SEE ALSO ======== Authen-PAM AUTHOR ====== Nikolay Pelov nikip@iname.com COPYRIGHT ========= Copyright (c) 1998-2000 Nikolay Pelov. All rights reserved. This file is part of the Authen::PAM library. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Authen/Krb4, Next: Authen/Krb5, Prev: Authen/FAQ, Up: Module List Perl extension for Kerberos 4 ***************************** NAME ==== Authen::Krb4 - Perl extension for Kerberos 4 SYNOPSIS ======== use Authen::Krb4; DESCRIPTION =========== Authen::Krb4 is an object oriented extension to Perl 5 which implements several user-level Kerberos 4 functions. With this module, you can create Kerberized clients and servers written in Perl. It is compatible with both AFS and MIT Kerberos. VARIABLES & FUNCTIONS --------------------- NOTE: No methods or variables are exported, so each variable and function should be preceded by 'Authen::Krb4::' error Contains the error code of the most recent Kerberos function call. get_phost(alias) Returns the instance name of the host 'alias' get_lrealm(n) Returns the nth realm of the host machine. n is zero by default. realmofhost(host) Returns the realm of the machine 'host'. mk_req(service,instance,realm,checksum) Returns an Authen::Krb4::Ticket object for the specified service, instance, and realm. It will return undef if there was an error. rd_req(ticket,service,instance,fn) Returns an Authen::Krb4::AuthDat object, which contains information obtained from the ticket, or undef upon failure. Ticket is a variable of the class Authen::Krb4::Ticket, which can be obtained from mk_req(). fn is a path to the appropriate srvtab. /etc/srvtab will be used if fn is null. get_cred(service,instance,realm) Search the caller's ticket file for a ticket for the service and instance in the given realm. Returns a Authen::Krb4::Creds object, or undef upon failure. This method can be used to extract a ticket's session key. get_key_sched(session) Returns the key schedule for the session key 'session', which can be obtained from rd_req() or get_cred(). The key schedule is an Authen::Krb4::KeySchedule object. mk_priv(in,schedule,key,sender,receiver) Encrypts the data stored in 'in' and returns the encrypted data. sender and receiver should be in standard internet format, which can be achieved using the inet_aton and sockaddr_in functions in the Socket module. rd_priv(in,schedule,key,sender,receiver) Decrypts the variable 'in' and returns the original data. Other parameters are as described in mk_priv() sendauth(options,fh,service,inst,realm,checksum,laddr,faddr,version) Obtains a ticket for the specified service, instance, and realm, and writes it to the socket 'fh'. Use recvauth to read the ticket on the server. 'laddr' is the packed network address of the client, and 'faddr' is the packed network address of the server. 'options' can be any of the following: Authen::Krb4::KOPT_DONT_MK_REQ Authen::Krb4::KOPT_DO_MUTUAL Authen::Krb4::KOPT_DONT_CANON Use KOPT_DO_MUTUAL if you plan to do any encryption. This function returns a list containing the service ticket, the credentials, and the key schedule. recvauth(options,fh,service,inst,faddr,laddr,fn) Reads a ticket/authenticator pair from the socket 'fh'. 'options' can be set as described above. 'faddr' is the packed network address of the client, and 'laddr' is the packed network address of the server. This function returns a list containing the ticket, an AuthDat object, the key schedule, and the version string. get_pw_in_tkt(user,inst,realm,service,srealm,lifetime,password) Tries to get an initial ticket for 'user' using 'password'. This function is especially useful for verifying a user's password. See the Kerberos documentation for details. get_svc_in_tkt(user,inst,realm,service,srealm,lifetime,srvtab) Tries to get an initial ticket for 'user' using the private key stored in 'srvtab'. read_service_key(user,inst,realm,kvno,srvtab) Extracts the private key from a srvtab and returns it. Use a kvno of 0 to extract the first matching entry. dest_tkt() Destroys the ticket file, much like kdestroy. get_err_txt(n) Returns a string containing a textual description of the kerberos error number n. CLASSES & METHODS ----------------- There are four classes in the Authen::Krb4 module, Ticket, AuthDat, Creds, and KeySchedule. They are all simply abstractions of Kerberos 4 structures. You almost never need to worry about creating new objects-the functions which return these objects create them for you (is this the best thing to do?). The one exception is when you need to construct a Ticket object for rd_req(). See below for details. Ticket Contains a ticket for a specified service, instance, and realm. new(dat) Returns a new Ticket object containing the data in 'dat'. You must create a new Ticket object on the server side for passing to rd_req(). dat The data contained in the ticket. Looks like junk to the naked eye. length The length of the data contained in 'dat'. AuthDat Contains the contents of the AUTH_DAT structure returned by rd_req(). See below for the goodies. pname Returns the principal's name. pinst Returns the principal's instance. prealm Returns the principal's realm. session The session key. Pass this to get_key_sched() to obtain a key schedule for encryption. k_flags Flags from the ticket. checksum The checksum from the ticket. See mk_req(). life Life of the ticket. time_sec The time the ticket was issued. localtime() can convert this to a nicer format. address The address in the ticket. Useful for mutual authentication. reply Reply to send to the client (not implemented yet). Creds Contains information retreived from your ticket file. service The service name. instance The instance realm The realm session Returns the session key. Pass this to get_key_sched() to obtain a key schedule for encryption. lifetime The lifetime of the ticket. kvno The key version number. ticket The ticket itself. issue_date The date the ticket was issued. pname The name of the principal. pinst The instance of the principal. KeySchedule You don't need to fool around with this. AUTHOR ====== Jeff Horwitz SEE ALSO ======== perl(1).  File: pm.info, Node: Authen/Krb5, Next: Authen/Libwrap, Prev: Authen/Krb4, Up: Module List Perl extension for Kerberos 5 ***************************** NAME ==== Authen::Krb5 - Perl extension for Kerberos 5 SYNOPSIS ======== use Authen::Krb5; Authen::Krb5::init_context(); Authen::Krb5::init_ets(); DESCRIPTION =========== Authen::Krb5 is an object oriented interface to the Kerberos 5 API. Both the implementation and documentation are nowhere near complete, and may require previous experience with Kerberos 5 programming. Most of the functions here are documented in detail in the Kerberos 5 API documentation. FUNCTIONS --------- error(n) Returns the error code from the most recent Authen::Krb5 call. If provided with an error code 'n', this function will return a textual description of the error. init_context() Initializes a context for the application. Returns a Authen::Krb5::Context object, or undef if there was an error. Should be called along with init_ets at the beginning of a script. init_ets() Initializes the Kerberos error tables. Should be called along with init_context at the beginning of a script. get_default_realm() Returns the default realm of your host. get_host_realm(host) Returns the realm of the specified host. get_krbhst(realm) Returns a list of the Kerberos servers from the specified realm. build_principal_ext(p) Not like the actual krb5_build_principal_ext. This is legacy code from Malcolm's code, which I'll probably change in future releases. In any case, it creates a 'server' principal for use in getting a TGT. Pass it the principal for which you would like a TGT. parse_name(name) Converts a string representation of a principal to a principal object. You can use this to create a principal from your username. sname_to_principal(hostname,sname,type) Generates a server principal from the given hostname, service, and type. Type can be one of the following: NT_UNKNOWN, NT_PRINCIPAL, NT_SRV_INST, NT_SRV_HST, NT_SRV_XHST, NT_UID. See the Kerberos documentation for details. cc_resolve(name) Returns a credentials cache identifier which corresponds to the given name. 'name' must be in the form TYPE:RESIDUAL. See the Kerberos documentation for more information. cc_default_name() Returns the name of the default credentials cache, which may be equivalent to KRB5CCACHE. cc_default() Returns a Authen::Krb5::Ccache object representing the default credentials cache. kt_resolve(name) Returns a Authen::Krb5::Keytab object representing the specified keytab name. get_in_tkt_with_password(client,server,password,cc) Attempt to get an initial ticket for the client. 'client' is a principal object for which you want an initial ticket. 'server' is a principal object for the service (usually krbtgt/REALM@REALM). 'password' is the password for the client, and 'cc' is a Authen::Krb5::Ccache object representing the current credentials cache. Returns a Kerberos error code. mk_req(auth_context,ap_req_options,service,hostname,in,cc) Obtains a ticket for a specified service and returns a KRB_AP_REQ message suitable for passing to rd_req. 'auth_context' is the Authen::Krb5::AuthContext object you want to use for this connection, 'ap_req_options' is an OR'ed representation of the possible options (see Kerberos docs), 'service' is the name of the service for which you want a ticket (like 'host'), hostname is the hostname of the server, 'in' can be any user-specified data that can be verified at the server end, and 'cc' is your credentials cache object. rd_req(auth_context,in,server,keytab) Parses a KRB_AP_REQ message and returns its contents in a Authen::Krb5::Ticket object. 'auth_context' is the connection's Authen::Krb5::AuthContext object, 'in' is the KRB_AP_REQ message (usually from mk_req), and server is the expected server's name for the ticket. 'keytab' is a Authen::Krb5::Keytab object for the keytab you want to use. Specify 'undef' or leave off to use the default keytab. mk_priv(auth_context,in) Encrypts 'in' using parameters specified in auth_context, and returns the encrypted data. Requires use of a replay cache. rd_priv(auth_context,in) Decrypts 'in' using parameters specified in auth_context, and returns the decrypted data. sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc) Obtains and sends an authenticated ticket from a client program to a server program using the filehandle 'fh'. 'version' is an application-defined version string that recvauth compares to its own version string. 'client' is the client principal, e.g. username@REALM. 'server' is the service principal to which you are authenticating, e.g. service.hostname@REALM. The only useful option right now is AP_OPTS_MUTUAL_REQUIRED, which forces sendauth to perform mutual authentication with the server. 'in' is a string that will be received by recvauth and verified by the server-it's up to the application. 'in_creds' is not yet supported, so just use 'undef' here. 'cc' should be set to the current credentials cache. sendauth returns true on success and undefined on failure. recvauth(auth_context,fh,version,server,keytab) Receives authentication data from a client using the sendauth function through the filehandle 'fh'. 'version' is as described in the sendauth section. 'server' is the server principal to which the client will be authenticating. 'keytab' is a Authen::Krb5::Keytab object specifying the keytab to use for this service. recvauth returns a Authen::Krb5::Ticket object on success or undefined on failure. genaddrs(auth_context,fh,flags) Uses the open socket filehandle 'fh' to generate local and remote addresses for auth_context. Flags should be one of the following, depending on the type of address you want to generate (flags can be OR'ed): KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR gen_portaddr(addr,port) Generates a local port address that can be used to name a replay cache. 'addr' is a Authen::Krb5::Address object, and port is a port number in network byte order. For generateing a replay cache name, you should supply the local address of the client and the socket's local port number. Returns a Authen::Krb5::Address object containing the address. gen_replay_name(addr,string) Generate a unique replay cache name. 'addr' is a Authen::Krb5::Address object created by gen_portaddr. 'string' is used as a unique identifier for the replay cache. Returns the replay cache name. get_server_rcache(name) Returns a Authen::Krb5::Rcache object using the replay cache name 'name.' CLASSES & METHODS ----------------- Authen::Krb5::Principal Kerberos 5 princpal object. o realm Returns the realm of the principal. o type Returns the type of the principal. o data Returns a list containing the components of the principal (everything before the realm). Authen::Krb5::Ccache Kerberos 5 credentials cache object. o initialize(p) Creates/refreshes a credentials cache for the primary principal 'p'. If the cache already exists, its contents are destroyed. o get_name Returns the name of the credentials cache. o get_principal Returns the primary principal of the credentials cache. o destroy Destroys the credentials cache and releases all resources it used. Authen::Krb5::AuthContext Kerberos 5 auth_context object. o new Allocates memory for a new Authen::Krb5::AuthContext object and returns it. o setaddrs(localaddr,remoteaddr) Sets the local and remote addresses for the AuthContext object. 'localaddr' and 'remoteaddr' are Authen::Krb5::Address objects, usually of type ADDRTYPE_INET. o getaddrs() Returns a list containing the local and the remote address of the AuthContext object. o setrcache(rc) Sets the replay cache for auth_context. 'rc' is a Authen::Krb5::Rcache object generated by get_server_rcache. Authen::Krb5::Ticket Kerberos 5 ticket object. o server Returns the server stored in the ticket. o enc_part2 Returns a Authen::Krb5::EncTktPart object representation of the ticket data. See below. Authen::Krb5::EncTktPart Object representation of the krb5_enc_tkt_part structure. o client The client principal contained in the ticket. AUTHOR ====== Jeff Horwitz (jeff@laserlink.net) ACKNOWLEDGEMENTS ================ Based on the original work by Doug MacEachern and Malcolm Beattie. Code contributions from Scott Hutton (shutton@indiana.edu). SEE ALSO ======== perl(1), kerberos(1).  File: pm.info, Node: Authen/Libwrap, Next: Authen/PAM, Prev: Authen/Krb5, Up: Module List access to Wietse Venema's TCP Wrappers library ********************************************** NAME ==== Authen::Libwrap - access to Wietse Venema's TCP Wrappers library SYNOPSIS ======== use Authen::Libwrap qw( hosts_ctl STRING_UNKNOWN ); # we know the remote username (using identd) $rc = hosts_ctl( "programname", "hostname.domain.com", "10.1.1.1", "username" ); ); print "Access is ", $rc ? "granted" : "refused", "\n"; # we don't know the remote username $rc = hosts_ctl( "programname", "hostname.domain.com", "10.1.1.1", STRING_UNKNOWN ); ); print "Access is ", $rc ? "granted" : "refused", "\n"; DESCRIPTION =========== The Authen::Libwrap module allows you to access the hosts_ctl() function from the popular TCP Wrappers security package. This allows validation of network access from perl programs against the system-wide `hosts.allow' file. If any of the parameters to hosts_ctl() are not known (i.e. username due to lack of an identd server), the constant STRING_UNKNOWN should be passed to the function. EXPORTS ======= Nothing unless you ask for it. hosts_ctl( $daemon, $hostname, $ip_address, $username ); CONSTANTS ========= STRING_UNKNOWN BUGS ==== Calls to hosts_ctl() which a line in `hosts.allow' that uses the "twist" option will terminate the running perl program. This is not a bug in Authen::Libwrap per se - libwrap uses exec(3) to replace the running process with the specified program, so there's nothing to return to. Some operating systems ship with a default catch-all rule in `hosts.allow' that uses the twist option. You may have to modify this configuration to use Authen::Libwrap effectively. AUTHOR ====== James FitzGibbon, SEE ALSO ======== perl(1), hosts_access(3), hosts_access(5), hosts_options(5)  File: pm.info, Node: Authen/PAM, Next: Authen/PIN, Prev: Authen/Libwrap, Up: Module List Perl interface to PAM library ***************************** NAME ==== Authen::PAM - Perl interface to PAM library SYNOPSIS ======== use Authen::PAM; $res = pam_start($service_name, $user, $pamh); $res = pam_start($service_name, $user, \my_conv_func, $pamh); $res = pam_end($pamh, $pam_status); $res = pam_authenticate($pamh, $flags); $res = pam_setcred($pamh, $flags); $res = pam_acct_mgmt($pamh, $flags); $res = pam_open_session($pamh, $flags); $res = pam_close_session($pamh, $flags); $res = pam_chauthtok($pamh, $flags); $error_str = pam_strerror($pamh, $errnum); $res = pam_set_item($pamh, $item_type, $item); $res = pam_get_item($pamh, $item_type, $item); if (HAVE_PAM_ENV_FUNCTIONS()) { $res = pam_putenv($pamh, $name_value); $val = pam_getenv($pamh, $name); %env = pam_getenvlist($pamh); } if (HAVE_PAM_FAIL_DELAY()) { $res = pam_fail_delay($pamh, $musec_delay); $res = pam_set_item($pamh, PAM_FAIL_DELAY(), \my_fail_delay_func); } DESCRIPTION =========== The *Authen::PAM* module provides a Perl interface to the *PAM* library. The only difference with the standard PAM interface is that instead of passing a pam_conv struct which has an additional context parameter appdata_ptr, you must only give an address to a conversation function written in Perl (see below). If you use the 3 argument version of pam_start then a default conversation function is used (Authen::PAM::pam_default_conv). The $flags argument is optional for all functions which use it except for pam_setcred. The $pam_status argument is also optional for pam_end function. Both of these arguments will be set to 0 if not given. The names of some constants from the PAM library have changed over the time. You can use any of the known names for a given constant although it is advisable to use the latest one. When this module supports some of the additional features of the PAM library (e.g. pam_fail_delay) then the corresponding HAVE_PAM_XXX constant will have a value 1 otherwise it will return 0. For compatibility with older PAM libraries I have added the constant HAVE_PAM_ENV_FUNCTIONS which is true if your PAM library has the functions for handling environment variables (pam_putenv, pam_getenv, pam_getenvlist). Object Oriented Style --------------------- If you prefer to use an object oriented style for accessing the PAM library here is the interface: use Authen::PAM qw(:constants); $pamh = new Authen::PAM($service_name, $user); $pamh = new Authen::PAM($service_name, $user, \my_conv_func); ref($pamh) || die "Error code $pamh during PAM init!"; $res = $pamh->pam_authenticate($flags); $res = $pamh->pam_setcred($flags); $res = $pamh->pam_acct_mgmt($flags); $res = $pamh->pam_open_session($flags); $res = $pamh->pam_close_session($flags); $res = $pamh->pam_chauthtok($flags); $error_str = $pamh->pam_strerror($errnum); $res = $pamh->pam_set_item($item_type, $item); $res = $pamh->pam_get_item($item_type, $item); $res = $pamh->pam_putenv($name_value); $val = $pamh->pam_getenv($name); %env = $pamh->pam_getenvlist; The constructor new will call the pam_start function and if successfull will return an object reference. Otherwise the $pamh will contain the error number returned by pam_start. The pam_end function will be called automatically when the object is no longer referenced. Examples -------- Here is an example of using PAM for changing the password of the current user: use Authen::PAM; $login_name = getpwuid($<); pam_start("passwd", $login_name, $pamh); pam_chauthtok($pamh); pam_end($pamh); or the same thing but using OO style: $pamh = new Authen::PAM("passwd", $login_name); $pamh->pam_chauthtok; $pamh = 0; # Force perl to call the destructor for the $pamh Conversation function format ---------------------------- When starting the PAM the user must supply a conversation function. It is used for interaction between the PAM modules and the user. The argument of the function is a list of pairs ($msg_type, $msg) and it must return a list with the same number of pairs ($resp_retcode, $resp) with replies to the input messages. For now the $resp_retcode is not used and must be always set to 0. In addition the user must append to the end of the resulting list the return code of the conversation function (usually PAM_SUCCESS). Here is a sample form of the PAM conversation function: sub my_conv_func { my @res; while ( @_ ) { my $msg_type = shift; my $msg = shift; print $msg; # switch ($msg_type) { obtain value for $ans; } push @res, (0,$ans); } push @res, PAM_SUCCESS(); return @res; } COMPATIBILITY ============= This module was tested with the following versions of the Linux-PAM library: 0.50, 0.56, 0.59 and 0.65. The following constant names: PAM_AUTHTOKEN_REQD, PAM_CRED_ESTABLISH, PAM_CRED_DELETE, PAM_CRED_REINITIALIZE, PAM_CRED_REFRESH are used by some older version of the Linux-PAM library and are not exported by default. If you really want them, then load the module with use Authen::PAM qw(:DEFAULT :old); This module still does not support some of the new Linux-PAM functions such as pam_system_log. SEE ALSO ======== PAM Application developer's Manual AUTHOR ====== Nikolay Pelov nikip@iname.com COPYRIGHT ========= Copyright (c) 1998-2000 Nikolay Pelov. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.