NAME

Krb5 - Perl extension for Kerberos 5

SYNOPSIS

use Krb5;

Krb5::init_context(); Krb5::init_ets();

DESCRIPTION

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 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 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 Krb5::Ccache object representing the default credentials cache.

kt_resolve(name)

Returns a 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 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 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 Krb5::Ticket object. 'auth_context' is the connection's 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 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 Krb5::Keytab object specifying the keytab to use for this service. recvauth returns a 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 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 Krb5::Address object containing the address.

gen_replay_name(addr,string)

Generate a unique replay cache name. 'addr' is a 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 Krb5::Rcache object using the replay cache name 'name.'

CLASSES & METHODS

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

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.

Krb5::AuthContext

Kerberos 5 auth_context object.

o new

Allocates memory for a new Krb5::AuthContext object and returns it.

o setaddrs(localaddr,remoteaddr)

Sets the local and remote addresses for the AuthContext object. 'localaddr' and 'remoteaddr' are 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 Krb5::Rcache object generated by get_server_rcache.

Krb5::Ticket

Kerberos 5 ticket object.

o server

Returns the server stored in the ticket.

o enc_part2

Returns a Krb5::EncTktPart object representation of the ticket data. See below.

Krb5::EncTktPart

Object representation of the krb5_enc_tkt_part structure.

o client

The client principal contained in the ticket.

AUTHOR

Jeff Horwitz (jhorwitz@umich.edu)

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