# Copyright (c) 1999 Jeff Horwitz (jeff@smashing.org). All rights reserved.
# This module is free software; you can redistribute it and/or modify it under
# the same terms as Perl itself.
package Authen::Krb4;
use strict;
use vars qw($VERSION @ISA @EXPORT);
require 5.002;
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.
@EXPORT = qw(
);
$VERSION = '1.1';
sub KOPT_DONT_MK_REQ { 0x00000001; }
sub KOPT_DO_MUTUAL { 0x00000002; }
sub KOPT_DONT_CANON { 0x00000004; }
$Authen::Krb4::error=0;
bootstrap Authen::Krb4 $VERSION;
# Preloaded methods go here.
# Autoload methods go after =cut, and are processed by the autosplit program.
1;
__END__
# Below is the stub of documentation for your module. You better edit it!
=head1 NAME
Authen::Krb4 - Perl extension for Kerberos 4
=head1 SYNOPSIS
use Authen::Krb4;
=head1 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.
=head2 VARIABLES & FUNCTIONS
NOTE: No methods or variables are exported, so each variable and function
should be preceded by 'Authen::Krb4::'
=over 4
=item error
Contains the error code of the most recent Kerberos function call.
=item get_phost(alias)
Returns the instance name of the host 'alias'
=item get_lrealm(n)
Returns the nth realm of the host machine. n is zero by default.
=item realmofhost(host)
Returns the realm of the machine 'host'.
=item 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.
=item 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.
=item 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.
=item 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.
=item 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.
=item rd_priv(in,schedule,key,sender,receiver)
Decrypts the variable 'in' and returns the original data. Other
parameters are as described in mk_priv()
=item 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.
=item 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.
=item 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.
=item 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'.
=item 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.
=item dest_tkt()
Destroys the ticket file, much like kdestroy.
=item get_err_txt(n)
Returns a string containing a textual description of the kerberos error
number n.
=back
=head2 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.
=over 4
=item Ticket
Contains a ticket for a specified service, instance, and realm.
=item * 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().
=item * dat
The data contained in the ticket. Looks like junk to the naked eye.
=item * length
The length of the data contained in 'dat'.
=item AuthDat
Contains the contents of the AUTH_DAT structure returned by rd_req(). See
below for the goodies.
=item * pname
Returns the principal's name.
=item * pinst
Returns the principal's instance.
=item * prealm
Returns the principal's realm.
=item * session
The session key. Pass this to get_key_sched() to obtain a key schedule
for encryption.
=item * k_flags
Flags from the ticket.
=item * checksum
The checksum from the ticket. See mk_req().
=item * life
Life of the ticket.
=item * time_sec
The time the ticket was issued. localtime() can convert this to a nicer
format.
=item * address
The address in the ticket. Useful for mutual authentication.
=item * reply
Reply to send to the client (not implemented yet).
=item Creds
Contains information retreived from your ticket file.
=item * service
The service name.
=item * instance
The instance
=item * realm
The realm
=item * session
Returns the session key. Pass this to get_key_sched() to obtain a key
schedule for encryption.
=item * lifetime
The lifetime of the ticket.
=item * kvno
The key version number.
=item * ticket
The ticket itself.
=item * issue_date
The date the ticket was issued.
=item * pname
The name of the principal.
=item * pinst
The instance of the principal.
=item KeySchedule
You don't need to fool around with this.
=back
=head1 AUTHOR
Jeff Horwitz <jeff@smashing.org>
=head1 SEE ALSO
perl(1).
=cut