.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Krb5 3pm"
.TH Krb5 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Authen::Krb5 \- Perl extension for Kerberos 5
.SH SYNOPSIS
.IX Header "SYNOPSIS"
use Authen::Krb5;
.PP
\&\fBAuthen::Krb5::init_context()\fR;
.SH DESCRIPTION
.IX Header "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.
.SS FUNCTIONS
.IX Subsection "FUNCTIONS"
.IP error(n) 4
.IX Item "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.
.IP \fBinit_context()\fR 4
.IX Item "init_context()"
Initializes a context for the application.  Returns a Authen::Krb5::Context
object, or undef if there was an error.
.IP "\fBinit_ets()\fR (DEPRECATED)" 4
.IX Item "init_ets() (DEPRECATED)"
Initializes the Kerberos error tables.  Should be called along with
init_context at the beginning of a script.
.IP \fBget_default_realm()\fR 4
.IX Item "get_default_realm()"
Returns the default realm of your host.
.IP get_host_realm(host) 4
.IX Item "get_host_realm(host)"
Returns the realm of the specified host.
.IP get_krbhst(realm) 4
.IX Item "get_krbhst(realm)"
Returns a list of the Kerberos servers from the specified realm.
.IP build_principal_ext(p) 4
.IX Item "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.
.IP parse_name(name) 4
.IX Item "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.
.IP sname_to_principal(hostname,sname,type) 4
.IX Item "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.
.IP cc_resolve(name) 4
.IX Item "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.
.IP \fBcc_default_name()\fR 4
.IX Item "cc_default_name()"
Returns the name of the default credentials cache, which may be equivalent
to KRB5CCACHE.
.IP \fBcc_default()\fR 4
.IX Item "cc_default()"
Returns a Authen::Krb5::Ccache object representing the default credentials
cache.
.IP kt_resolve(name) 4
.IX Item "kt_resolve(name)"
Returns a Authen::Krb5::Keytab object representing the specified keytab name.
.IP \fBkt_default_name()\fR 4
.IX Item "kt_default_name()"
Returns a sting containing the default keytab name.
.IP \fBkt_default()\fR 4
.IX Item "kt_default()"
Returns an Authen::Krb5::Keytab object representing the default keytab.
.IP "kt_read_service_key(name, principal[, kvno, enctype])" 4
.IX Item "kt_read_service_key(name, principal[, kvno, enctype])"
Searches the keytab specified by \fIname\fR (the default keytab if
\&\fIname\fR is undef) for a key matching \fIprincipal\fR (and optionally
\&\fIkvno\fR and \fIenctype\fR) and returns the key in the form of an
Authen::Krb5::Keyblock object.
.IP "get_init_creds_password(client, password[, service])" 4
.IX Item "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.
.IP "get_init_creds_keytab(client, keytab[, service])" 4
.IX Item "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.
.IP get_in_tkt_with_password(client,server,password,cc) 4
.IX Item "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.
.Sp
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.
.IP get_in_tkt_with_keytab(client,server,keytab,cc) 4
.IX Item "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.
.Sp
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.
.IP mk_req(auth_context,ap_req_options,service,hostname,in,cc) 4
.IX Item "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.
.IP rd_req(auth_context,in,server,keytab) 4
.IX Item "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.
.IP mk_priv(auth_context,in) 4
.IX Item "mk_priv(auth_context,in)"
Encrypts 'in' using parameters specified in auth_context, and returns the
encrypted data.  Requires use of a replay cache.
.IP rd_priv(auth_context,in) 4
.IX Item "rd_priv(auth_context,in)"
Decrypts 'in' using parameters specified in auth_context, and returns the
decrypted data.
.IP sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc) 4
.IX Item "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.
.IP recvauth(auth_context,fh,version,server,keytab) 4
.IX Item "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.
.IP genaddrs(auth_context,fh,flags) 4
.IX Item "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):
.Sp
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
.IP gen_portaddr(addr,port) 4
.IX Item "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.
.IP gen_replay_name(addr,string) 4
.IX Item "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.
.IP get_server_rcache(name) 4
.IX Item "get_server_rcache(name)"
Returns a Authen::Krb5::Rcache object using the replay cache name 'name.'
.SS "CLASSES & METHODS"
.IX Subsection "CLASSES & METHODS"
.IP Authen::Krb5::Principal 4
.IX Item "Authen::Krb5::Principal"
Kerberos 5 princpal object.
.RS 4
.IP "o realm" 4
.IX Item "o realm"
Returns the realm of the principal.
.IP "o type" 4
.IX Item "o type"
Returns the type of the principal.
.IP "o data" 4
.IX Item "o data"
Returns a list containing the components of the principal (everything before
the realm).
.RE
.RS 4
.RE
.IP Authen::Krb5::Ccache 4
.IX Item "Authen::Krb5::Ccache"
Kerberos 5 credentials cache object.
.RS 4
.IP "o initialize(p)" 4
.IX Item "o initialize(p)"
Creates/refreshes a credentials cache for the primary principal 'p'.  If the
cache already exists, its contents are destroyed.
.IP "o store_cred(creds)" 4
.IX Item "o store_cred(creds)"
Stores the given credentials, which should be an Authen::Krb5::Creds object
as returned from \fBget_init_creds_password()\fR or \fBget_init_creds_keytab()\fR, in
the cache.
.IP "o get_name" 4
.IX Item "o get_name"
Returns the name of the credentials cache.
.IP "o get_principal" 4
.IX Item "o get_principal"
Returns the primary principal of the credentials cache.
.IP "o destroy" 4
.IX Item "o destroy"
Destroys the credentials cache and releases all resources it used.
.IP "o \fBstart_seq_get()\fR" 4
.IX Item "o start_seq_get()"
Returns a cursor that can be passed to \fR\f(BInext_cred()\fR\fI\fR to read in turn
every credential in the cache.
.IP "o next_cred(cursor)" 4
.IX Item "o next_cred(cursor)"
Returns the next credential in the cache as an Authen::Krb5::Creds
object.
.IP "o end_seq_get(cursor)" 4
.IX Item "o end_seq_get(cursor)"
Perform cleanup opreations after \fR\f(BInext_cred()\fR\fI\fR and invalidates
\&\fIcursor\fR.
.RE
.RS 4
.RE
.IP Authen::Krb5::KeyBlock 4
.IX Item "Authen::Krb5::KeyBlock"
Kerberos 5 keyblock object.
.RS 4
.IP "o \fBenctype()\fR" 4
.IX Item "o enctype()"
Returns the encryption type ID.
.IP "o \fBenctype_string()\fR" 4
.IX Item "o enctype_string()"
Returns a text description of the encryption type.
.IP "o \fBlength()\fR" 4
.IX Item "o length()"
Returns the length of the session key.
.IP "o \fBcontents()\fR" 4
.IX Item "o contents()"
Returns the actual contents of the keyblock (the session key).
.RE
.RS 4
.RE
.IP Authen::Krb5::AuthContext 4
.IX Item "Authen::Krb5::AuthContext"
Kerberos 5 auth_context object.
.RS 4
.IP "o new" 4
.IX Item "o new"
Allocates memory for a new Authen::Krb5::AuthContext object and returns it.
.IP "o setaddrs(localaddr,remoteaddr)" 4
.IX Item "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.
.IP "o \fBgetaddrs()\fR" 4
.IX Item "o getaddrs()"
Returns a list containing the local and the remote address of the
AuthContext object.
.IP "o setrcache(rc)" 4
.IX Item "o setrcache(rc)"
Sets the replay cache for auth_context.  'rc' is a Authen::Krb5::Rcache object
generated by get_server_rcache.
.IP "o \fBgetkey()\fR" 4
.IX Item "o getkey()"
Retrieves the session key as an Authen::Krb5::KeyBlock object.
.RE
.RS 4
.RE
.IP Authen::Krb5::Ticket 4
.IX Item "Authen::Krb5::Ticket"
Kerberos 5 ticket object.
.RS 4
.IP "o server" 4
.IX Item "o server"
Returns the server stored in the ticket.
.IP "o enc_part2" 4
.IX Item "o enc_part2"
Returns a Authen::Krb5::EncTktPart object representation of the ticket data.
See below.
.RE
.RS 4
.RE
.IP Authen::Krb5::EncTktPart 4
.IX Item "Authen::Krb5::EncTktPart"
Object representation of the krb5_enc_tkt_part structure.
.RS 4
.IP "o client" 4
.IX Item "o client"
The client principal contained in the ticket.
.RE
.RS 4
.RE
.IP Authen::Krb5::Keyblock 4
.IX Item "Authen::Krb5::Keyblock"
Object representation of the krb5_keyblock structure.
.RS 4
.IP "o enctype" 4
.IX Item "o enctype"
The integral enctype of the key.
.IP "o length" 4
.IX Item "o length"
Length of the key.
.IP "o contents" 4
.IX Item "o contents"
Contents of the key itself, as a string.
.RE
.RS 4
.RE
.IP Authen::Krb5::Keytab 4
.IX Item "Authen::Krb5::Keytab"
.RS 4
.PD 0
.IP "o add_entry(entry)" 4
.IX Item "o add_entry(entry)"
.PD
Adds \fIentry\fR to the keytab.
.IP "o remove_entry(entry)" 4
.IX Item "o remove_entry(entry)"
Removes \fIentry\fR from the keytab.
.IP "o \fBget_name()\fR" 4
.IX Item "o get_name()"
Returns the name of the keytab.
.IP "o get_entry(principal[, kvno, enctype])" 4
.IX Item "o get_entry(principal[, kvno, enctype])"
Returns an Authen::Krb5::KeytabEntry object representing an entry in
the keytab matching \fIprincipal\fR and optionally \fIkvno\fR and
\&\fIenctype\fR.
.IP "o \fBstart_seq_get()\fR" 4
.IX Item "o start_seq_get()"
Returns a cursor that can be passed to \fR\f(BInext_entry()\fR\fI\fR to read in turn
every key in the keytab.
.IP "o next_entry(cursor)" 4
.IX Item "o next_entry(cursor)"
Returns the next entry in the keytab as an Authen::Krb5::KeytabEntry
object.
.IP "o end_seq_get(cursor)" 4
.IX Item "o end_seq_get(cursor)"
Perform cleanup opreations after \fR\f(BInext_entry()\fR\fI\fR and invalidates
\&\fIcursor\fR.
.RE
.RS 4
.RE
.IP Authen::Krb5::KeytabEntry 4
.IX Item "Authen::Krb5::KeytabEntry"
.RS 4
.PD 0
.IP "o new(principal, kvno, keyblock)" 4
.IX Item "o new(principal, kvno, keyblock)"
.PD
Create a new Authen::Krb5::KeytabEntry object from an
Authen::Krb5::Principal object, a key version number, and an
Authen::Krb5::Keyblock object.
.IP "o principal" 4
.IX Item "o principal"
An Authen::Krb5::Principal object representing the principal contained
in the entry.
.IP "o timestamp" 4
.IX Item "o timestamp"
The timestamp of the entry.
.IP "o kvno" 4
.IX Item "o kvno"
The key version number of the key contained in the entry.
.IP "o key" 4
.IX Item "o key"
An Authen::Krb5::Keyblock object representing a copy of the keyblock
contained in the entry.
.RE
.RS 4
.RE
.IP Authen::Krb5::Creds 4
.IX Item "Authen::Krb5::Creds"
Object representing a credential.
.RS 4
.IP "o \fBstarttime()\fR" 4
.IX Item "o starttime()"
Returns the starttime time property of the credential.
.IP "o \fBauthtime()\fR" 4
.IX Item "o authtime()"
Returns the authtime time property of the credential.
.IP "o \fBendtime()\fR" 4
.IX Item "o endtime()"
Returns the endtime time property of the credential.
.IP "o \fBrenew_till()\fR" 4
.IX Item "o renew_till()"
Returns the renew_till time property of the credential.
.IP "o \fBserver()\fR" 4
.IX Item "o server()"
Returns the name of the service principal the credential is for.
.IP "o \fBclient()\fR" 4
.IX Item "o client()"
Returns the client principal name (will usually be identical for all
credentials in a credential cache).
.IP "o \fBticket()\fR" 4
.IX Item "o ticket()"
Returns the Authen::Krb5::Ticket for this credential.
.IP "o \fBkeyblock()\fR" 4
.IX Item "o keyblock()"
Returns the keyblock of the credential.
.RE
.RS 4
.RE
.SH AUTHOR
.IX Header "AUTHOR"
Jeff Horwitz (jeff@smashing.org)
.SH ACKNOWLEDGEMENTS
.IX Header "ACKNOWLEDGEMENTS"
Based on the original work by Doug MacEachern and Malcolm Beattie.  Code
contributions from Scott Hutton (shutton@indiana.edu).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBkerberos\fR\|(1).