Provided by: libauthen-krb5-perl_1.9-6ubuntu1_amd64 bug

NAME

       Authen::Krb5 - Perl extension for Kerberos 5

SYNOPSIS

       use Authen::Krb5;

       Authen::Krb5::init_context();

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.

       init_ets() (DEPRECATED)
           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.

       kt_default_name()
           Returns a sting containing the default keytab name.

       kt_default()
           Returns an Authen::Krb5::Keytab object representing the default keytab.

       kt_read_service_key(name, principal[, kvno, enctype])
           Searches the keytab specified by name (the default keytab if name is undef) for a key
           matching principal (and optionally kvno and enctype) and returns the key in the form
           of an Authen::Krb5::Keyblock object.

       get_init_creds_password(client, password[, service])
           Attempt to get an initial ticket for the client.  'client' is a principal object for
           which you want an initial ticket.  'password' is the password for the client.
           'service', if given, is the string representation (not a principal object) for the
           ticket to acquire.  If not given, it defaults to krbtgt/REALM@REALM for the local
           realm.  Returns an Authen::Krb5::Creds object or undef on failure.

       get_init_creds_keytab(client, keytab[, service])
           Attempt to get an inintial ticket for the client using a keytab.  'client' is a
           principal object for which you want an initial ticket.  'keytab' is a keytab object
           created with kt_resolve.  'service', if given, is the string representation (not a
           principal object) for the ticket to acquire.  If not given, it defaults to
           krbtgt/REALM@REALM for the local realm.  Returns an Authen::Krb5::Creds object or
           undef on failure.

       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.

           Although this interface is deprecated in the Kerberos C libraries, it's supported in
           the Perl module.  In this module, it's implemented in terms of
           krb5_get_init_creds_password, krb5_cc_initialize, and krb5_cc_store_cred.

       get_in_tkt_with_keytab(client,server,keytab,cc)
           Obtain an initial ticket for the client using a keytab.  'client' is a principal
           object for which you want an initial ticket.  'server' is a principal object for the
           service (usually krbtgt/REALM@REALM).  'keytab' is a keytab object createed with
           kt_resolve.  'cc' is a Authen::Krb5::Ccache object representing the current
           credentials cache.  Returns a Kerberos error code.

           Although this interface is deprecated in the Kerberos C libraries, it's supported in
           the Perl module.  In this module, it's implemented in terms of
           krb5_get_init_creds_keytab, krb5_cc_initialize, and krb5_cc_store_cred.

       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 store_cred(creds)
               Stores the given credentials, which should be an Authen::Krb5::Creds object as
               returned from get_init_creds_password() or get_init_creds_keytab(), in the cache.

           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.

           o start_seq_get()
               Returns a cursor that can be passed to next_cred() to read in turn every
               credential in the cache.

           o next_cred(cursor)
               Returns the next credential in the cache as an Authen::Krb5::Creds object.

           o end_seq_get(cursor)
               Perform cleanup opreations after next_cred() and invalidates cursor.

       Authen::Krb5::KeyBlock
           Kerberos 5 keyblock object.

           o enctype()
               Returns the encryption type ID.

           o enctype_string()
               Returns a text description of the encryption type.

           o length()
               Returns the length of the session key.

           o contents()
               Returns the actual contents of the keyblock (the session key).

       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.

           o getkey()
               Retrieves the session key as an Authen::Krb5::KeyBlock object.

       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.

       Authen::Krb5::Keyblock
           Object representation of the krb5_keyblock structure.

           o enctype
               The integral enctype of the key.

           o length
               Length of the key.

           o contents
               Contents of the key itself, as a string.

       Authen::Krb5::Keytab
           o add_entry(entry)
               Adds entry to the keytab.

           o remove_entry(entry)
               Removes entry from the keytab.

           o get_name()
               Returns the name of the keytab.

           o get_entry(principal[, kvno, enctype])
               Returns an Authen::Krb5::KeytabEntry object representing an entry in the keytab
               matching principal and optionally kvno and enctype.

           o start_seq_get()
               Returns a cursor that can be passed to next_entry() to read in turn every key in
               the keytab.

           o next_entry(cursor)
               Returns the next entry in the keytab as an Authen::Krb5::KeytabEntry object.

           o end_seq_get(cursor)
               Perform cleanup opreations after next_entry() and invalidates cursor.

       Authen::Krb5::KeytabEntry
           o new(principal, kvno, keyblock)
               Create a new Authen::Krb5::KeytabEntry object from an Authen::Krb5::Principal
               object, a key version number, and an Authen::Krb5::Keyblock object.

           o principal
               An Authen::Krb5::Principal object representing the principal contained in the
               entry.

           o timestamp
               The timestamp of the entry.

           o kvno
               The key version number of the key contained in the entry.

           o key
               An Authen::Krb5::Keyblock object representing a copy of the keyblock contained in
               the entry.

       Authen::Krb5::Creds
           Object representing a credential.

           o starttime()
               Returns the starttime time property of the credential.

           o authtime()
               Returns the authtime time property of the credential.

           o endtime()
               Returns the endtime time property of the credential.

           o renew_till()
               Returns the renew_till time property of the credential.

           o server()
               Returns the name of the service principal the credential is for.

           o client()
               Returns the client principal name (will usually be identical for all credentials
               in a credential cache).

           o ticket()
               Returns the Authen::Krb5::Ticket for this credential.

           o keyblock()
               Returns the keyblock of the credential.

AUTHOR

       Jeff Horwitz (jeff@smashing.org)

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).