1Krb5(3)               User Contributed Perl Documentation              Krb5(3)
2
3
4

NAME

6       Authen::Krb5 - Perl extension for Kerberos 5
7

SYNOPSIS

9       use Authen::Krb5;
10
11       Authen::Krb5::init_context();
12

DESCRIPTION

14       Authen::Krb5 is an object oriented interface to the Kerberos 5 API.
15       Both the implementation and documentation are nowhere near complete,
16       and may require previous experience with Kerberos 5 programming.  Most
17       of the functions here are documented in detail in the Kerberos 5 API
18       documentation.
19
20   FUNCTIONS
21       error(n)
22           Returns the error code from the most recent Authen::Krb5 call.  If
23           provided with an error code 'n', this function will return a
24           textual description of the error.
25
26       init_context()
27           Initializes a context for the application.  Returns a
28           Authen::Krb5::Context object, or undef if there was an error.
29
30       init_ets() (DEPRECATED)
31           Initializes the Kerberos error tables.  Should be called along with
32           init_context at the beginning of a script.
33
34       get_default_realm()
35           Returns the default realm of your host.
36
37       get_host_realm(host)
38           Returns the realm of the specified host.
39
40       get_krbhst(realm)
41           Returns a list of the Kerberos servers from the specified realm.
42
43       build_principal_ext(p)
44           Not like the actual krb5_build_principal_ext.  This is legacy code
45           from Malcolm's code, which I'll probably change in future releases.
46           In any case, it creates a 'server' principal for use in getting a
47           TGT.  Pass it the principal for which you would like a TGT.
48
49       parse_name(name)
50           Converts a string representation of a principal to a principal
51           object.  You can use this to create a principal from your username.
52
53       sname_to_principal(hostname,sname,type)
54           Generates a server principal from the given hostname, service, and
55           type.  Type can be one of the following: NT_UNKNOWN, NT_PRINCIPAL,
56           NT_SRV_INST, NT_SRV_HST, NT_SRV_XHST, NT_UID.  See the Kerberos
57           documentation for details.
58
59       cc_resolve(name)
60           Returns a credentials cache identifier which corresponds to the
61           given name.  'name' must be in the form TYPE:RESIDUAL.  See the
62           Kerberos documentation for more information.
63
64       cc_default_name()
65           Returns the name of the default credentials cache, which may be
66           equivalent to KRB5CCACHE.
67
68       cc_default()
69           Returns a Authen::Krb5::Ccache object representing the default
70           credentials cache.
71
72       kt_resolve(name)
73           Returns a Authen::Krb5::Keytab object representing the specified
74           keytab name.
75
76       kt_default_name()
77           Returns a sting containing the default keytab name.
78
79       kt_default()
80           Returns an Authen::Krb5::Keytab object representing the default
81           keytab.
82
83       kt_read_service_key(name, principal[, kvno, enctype])
84           Searches the keytab specified by name (the default keytab if name
85           is undef) for a key matching principal (and optionally kvno and
86           enctype) and returns the key in the form of an
87           Authen::Krb5::Keyblock object.
88
89       get_init_creds_password(client, password[, service])
90           Attempt to get an initial ticket for the client.  'client' is a
91           principal object for which you want an initial ticket.  'password'
92           is the password for the client.  'service', if given, is the string
93           representation (not a principal object) for the ticket to acquire.
94           If not given, it defaults to krbtgt/REALM@REALM for the local
95           realm.  Returns an Authen::Krb5::Creds object or undef on failure.
96
97       get_init_creds_keytab(client, keytab[, service])
98           Attempt to get an inintial ticket for the client using a keytab.
99           'client' is a principal object for which you want an initial
100           ticket.  'keytab' is a keytab object created with kt_resolve.
101           'service', if given, is the string representation (not a principal
102           object) for the ticket to acquire.  If not given, it defaults to
103           krbtgt/REALM@REALM for the local realm.  Returns an
104           Authen::Krb5::Creds object or undef on failure.
105
106       get_in_tkt_with_password(client,server,password,cc)
107           Attempt to get an initial ticket for the client.  'client' is a
108           principal object for which you want an initial ticket.  'server' is
109           a principal object for the service (usually krbtgt/REALM@REALM).
110           'password' is the password for the client, and 'cc' is a
111           Authen::Krb5::Ccache object representing the current credentials
112           cache.  Returns a Kerberos error code.
113
114           Although this interface is deprecated in the Kerberos C libraries,
115           it's supported in the Perl module.  In this module, it's
116           implemented in terms of krb5_get_init_creds_password,
117           krb5_cc_initialize, and krb5_cc_store_cred.
118
119       get_in_tkt_with_keytab(client,server,keytab,cc)
120           Obtain an initial ticket for the client using a keytab.  'client'
121           is a principal object for which you want an initial ticket.
122           'server' is a principal object for the service (usually
123           krbtgt/REALM@REALM).  'keytab' is a keytab object createed with
124           kt_resolve.  'cc' is a Authen::Krb5::Ccache object representing the
125           current credentials cache.  Returns a Kerberos error code.
126
127           Although this interface is deprecated in the Kerberos C libraries,
128           it's supported in the Perl module.  In this module, it's
129           implemented in terms of krb5_get_init_creds_keytab,
130           krb5_cc_initialize, and krb5_cc_store_cred.
131
132       mk_req(auth_context,ap_req_options,service,hostname,in,cc)
133           Obtains a ticket for a specified service and returns a KRB_AP_REQ
134           message suitable for passing to rd_req.  'auth_context' is the
135           Authen::Krb5::AuthContext object you want to use for this
136           connection, 'ap_req_options' is an OR'ed representation of the
137           possible options (see Kerberos docs), 'service' is the name of the
138           service for which you want a ticket (like 'host'), hostname is the
139           hostname of the server, 'in' can be any user-specified data that
140           can be verified at the server end, and 'cc' is your credentials
141           cache object.
142
143       rd_req(auth_context,in,server,keytab)
144           Parses a KRB_AP_REQ message and returns its contents in a
145           Authen::Krb5::Ticket object.  'auth_context' is the connection's
146           Authen::Krb5::AuthContext object, 'in' is the KRB_AP_REQ message
147           (usually from mk_req), and server is the expected server's name for
148           the ticket.  'keytab' is a Authen::Krb5::Keytab object for the
149           keytab you want to use.  Specify 'undef' or leave off to use the
150           default keytab.
151
152       mk_priv(auth_context,in)
153           Encrypts 'in' using parameters specified in auth_context, and
154           returns the encrypted data.  Requires use of a replay cache.
155
156       rd_priv(auth_context,in)
157           Decrypts 'in' using parameters specified in auth_context, and
158           returns the decrypted data.
159
160       sendauth(auth_context,fh,version,client,server,options,in,in_creds,cc)
161           Obtains and sends an authenticated ticket from a client program to
162           a server program using the filehandle 'fh'.  'version' is an
163           application-defined version string that recvauth compares to its
164           own version string.  'client' is the client principal, e.g.
165           username@REALM.  'server' is the service principal to which you are
166           authenticating, e.g. service.hostname@REALM.  The only useful
167           option right now is AP_OPTS_MUTUAL_REQUIRED, which forces sendauth
168           to perform mutual authentication with the server.  'in' is a string
169           that will be received by recvauth and verified by the server--it's
170           up to the application.  'in_creds' is not yet supported, so just
171           use 'undef' here.  'cc' should be set to the current credentials
172           cache.  sendauth returns true on success and undefined on failure.
173
174       recvauth(auth_context,fh,version,server,keytab)
175           Receives authentication data from a client using the sendauth
176           function through the filehandle 'fh'.  'version' is as described in
177           the sendauth section.  'server' is the server principal to which
178           the client will be authenticating.  'keytab' is a
179           Authen::Krb5::Keytab object specifying the keytab to use for this
180           service.  recvauth returns a Authen::Krb5::Ticket object on success
181           or undefined on failure.
182
183       genaddrs(auth_context,fh,flags)
184           Uses the open socket filehandle 'fh' to generate local and remote
185           addresses for auth_context.  Flags should be one of the following,
186           depending on the type of address you want to generate (flags can be
187           OR'ed):
188
189           KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
190           KRB5_AUTH_CONTEXT_GENERATE_LOCAL_FULL_ADDR
191           KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
192           KRB5_AUTH_CONTEXT_GENERATE_REMOTE_FULL_ADDR
193
194       gen_portaddr(addr,port)
195           Generates a local port address that can be used to name a replay
196           cache.  'addr' is a Authen::Krb5::Address object, and port is a
197           port number in network byte order.  For generateing a replay cache
198           name, you should supply the local address of the client and the
199           socket's local port number.  Returns a Authen::Krb5::Address object
200           containing the address.
201
202       gen_replay_name(addr,string)
203           Generate a unique replay cache name.  'addr' is a
204           Authen::Krb5::Address object created by gen_portaddr.  'string' is
205           used as a unique identifier for the replay cache.  Returns the
206           replay cache name.
207
208       get_server_rcache(name)
209           Returns a Authen::Krb5::Rcache object using the replay cache name
210           'name.'
211
212   CLASSES & METHODS
213       Authen::Krb5::Principal
214           Kerberos 5 princpal object.
215
216           o realm
217               Returns the realm of the principal.
218
219           o type
220               Returns the type of the principal.
221
222           o data
223               Returns a list containing the components of the principal
224               (everything before the realm).
225
226       Authen::Krb5::Ccache
227           Kerberos 5 credentials cache object.
228
229           o initialize(p)
230               Creates/refreshes a credentials cache for the primary principal
231               'p'.  If the cache already exists, its contents are destroyed.
232
233           o store_cred(creds)
234               Stores the given credentials, which should be an
235               Authen::Krb5::Creds object as returned from
236               get_init_creds_password() or get_init_creds_keytab(), in the
237               cache.
238
239           o get_name
240               Returns the name of the credentials cache.
241
242           o get_principal
243               Returns the primary principal of the credentials cache.
244
245           o destroy
246               Destroys the credentials cache and releases all resources it
247               used.
248
249           o start_seq_get()
250               Returns a cursor that can be passed to next_cred() to read in
251               turn every credential in the cache.
252
253           o next_cred(cursor)
254               Returns the next credential in the cache as an
255               Authen::Krb5::Creds object.
256
257           o end_seq_get(cursor)
258               Perform cleanup opreations after next_cred() and invalidates
259               cursor.
260
261       Authen::Krb5::KeyBlock
262           Kerberos 5 keyblock object.
263
264           o enctype()
265               Returns the encryption type ID.
266
267           o enctype_string()
268               Returns a text description of the encryption type.
269
270           o length()
271               Returns the length of the session key.
272
273           o contents()
274               Returns the actual contents of the keyblock (the session key).
275
276       Authen::Krb5::AuthContext
277           Kerberos 5 auth_context object.
278
279           o new
280               Allocates memory for a new Authen::Krb5::AuthContext object and
281               returns it.
282
283           o setaddrs(localaddr,remoteaddr)
284               Sets the local and remote addresses for the AuthContext object.
285               'localaddr' and 'remoteaddr' are Authen::Krb5::Address objects,
286               usually of type ADDRTYPE_INET.
287
288           o getaddrs()
289               Returns a list containing the local and the remote address of
290               the AuthContext object.
291
292           o setrcache(rc)
293               Sets the replay cache for auth_context.  'rc' is a
294               Authen::Krb5::Rcache object generated by get_server_rcache.
295
296           o getkey()
297               Retrieves the session key as an Authen::Krb5::KeyBlock object.
298
299       Authen::Krb5::Ticket
300           Kerberos 5 ticket object.
301
302           o server
303               Returns the server stored in the ticket.
304
305           o enc_part2
306               Returns a Authen::Krb5::EncTktPart object representation of the
307               ticket data.  See below.
308
309       Authen::Krb5::EncTktPart
310           Object representation of the krb5_enc_tkt_part structure.
311
312           o client
313               The client principal contained in the ticket.
314
315       Authen::Krb5::Keyblock
316           Object representation of the krb5_keyblock structure.
317
318           o enctype
319               The integral enctype of the key.
320
321           o length
322               Length of the key.
323
324           o contents
325               Contents of the key itself, as a string.
326
327       Authen::Krb5::Keytab
328           o add_entry(entry)
329               Adds entry to the keytab.
330
331           o remove_entry(entry)
332               Removes entry from the keytab.
333
334           o get_name()
335               Returns the name of the keytab.
336
337           o get_entry(principal[, kvno, enctype])
338               Returns an Authen::Krb5::KeytabEntry object representing an
339               entry in the keytab matching principal and optionally kvno and
340               enctype.
341
342           o start_seq_get()
343               Returns a cursor that can be passed to next_entry() to read in
344               turn every key in the keytab.
345
346           o next_entry(cursor)
347               Returns the next entry in the keytab as an
348               Authen::Krb5::KeytabEntry object.
349
350           o end_seq_get(cursor)
351               Perform cleanup opreations after next_entry() and invalidates
352               cursor.
353
354       Authen::Krb5::KeytabEntry
355           o new(principal, kvno, keyblock)
356               Create a new Authen::Krb5::KeytabEntry object from an
357               Authen::Krb5::Principal object, a key version number, and an
358               Authen::Krb5::Keyblock object.
359
360           o principal
361               An Authen::Krb5::Principal object representing the principal
362               contained in the entry.
363
364           o timestamp
365               The timestamp of the entry.
366
367           o kvno
368               The key version number of the key contained in the entry.
369
370           o key
371               An Authen::Krb5::Keyblock object representing a copy of the
372               keyblock contained in the entry.
373
374       Authen::Krb5::Creds
375           Object representing a credential.
376
377           o starttime()
378               Returns the starttime time property of the credential.
379
380           o authtime()
381               Returns the authtime time property of the credential.
382
383           o endtime()
384               Returns the endtime time property of the credential.
385
386           o renew_till()
387               Returns the renew_till time property of the credential.
388
389           o server()
390               Returns the name of the service principal the credential is
391               for.
392
393           o client()
394               Returns the client principal name (will usually be identical
395               for all credentials in a credential cache).
396
397           o ticket()
398               Returns the Authen::Krb5::Ticket for this credential.
399
400           o keyblock()
401               Returns the keyblock of the credential.
402

AUTHOR

404       Jeff Horwitz (jeff@smashing.org)
405

ACKNOWLEDGEMENTS

407       Based on the original work by Doug MacEachern and Malcolm Beattie.
408       Code contributions from Scott Hutton (shutton@indiana.edu).
409

SEE ALSO

411       perl(1), kerberos(1).
412

POD ERRORS

414       Hey! The above document had some coding errors, which are explained
415       below:
416
417       Around line 602:
418           You forgot a '=back' before '=head1'
419
420
421
422perl v5.34.0                      2022-01-20                           Krb5(3)
Impressum