1Krb5(3) User Contributed Perl Documentation Krb5(3)
2
6 Authen::Krb5 - Perl extension for Kerberos 5
7
9 use Authen::Krb5;
10 Authen::Krb5::init_context();
12
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 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 init_context()
27 Initializes a context for the application. Returns a
28 Authen::Krb5::Context object, or undef if there was an error.
29 init_ets() (DEPRECATED)
31 Initializes the Kerberos error tables. Should be called along with
32 init_context at the beginning of a script.
33 get_default_realm()
35 Returns the default realm of your host.
36 get_host_realm(host)
38 Returns the realm of the specified host.
39 get_krbhst(realm)
41 Returns a list of the Kerberos servers from the specified realm.
42 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 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 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 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 cc_default_name()
65 Returns the name of the default credentials cache, which may be
66 equivalent to KRB5CCACHE.
67 cc_default()
69 Returns a Authen::Krb5::Ccache object representing the default
70 credentials cache.
71 kt_resolve(name)
73 Returns a Authen::Krb5::Keytab object representing the specified
74 keytab name.
75 kt_default_name()
77 Returns a sting containing the default keytab name.
78 kt_default()
80 Returns an Authen::Krb5::Keytab object representing the default
81 keytab.
82 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 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 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 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 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 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 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 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 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 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 rd_priv(auth_context,in)
157 Decrypts 'in' using parameters specified in auth_context, and
158 returns the decrypted data.
159 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 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 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 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 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 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 get_server_rcache(name)
209 Returns a Authen::Krb5::Rcache object using the replay cache name
210 'name.'
211 CLASSES & METHODS
213 Authen::Krb5::Principal
214 Kerberos 5 princpal object.
215 o realm
217 Returns the realm of the principal.
218 o type
220 Returns the type of the principal.
221 o data
223 Returns a list containing the components of the principal
224 (everything before the realm).
225 Authen::Krb5::Ccache
227 Kerberos 5 credentials cache object.
228 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 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 o get_name
240 Returns the name of the credentials cache.
241 o get_principal
243 Returns the primary principal of the credentials cache.
244 o destroy
246 Destroys the credentials cache and releases all resources it
247 used.
248 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 o next_cred(cursor)
254 Returns the next credential in the cache as an
255 Authen::Krb5::Creds object.
256 o end_seq_get(cursor)
258 Perform cleanup opreations after next_cred() and invalidates
259 cursor.
260 Authen::Krb5::KeyBlock
262 Kerberos 5 keyblock object.
263 o enctype()
265 Returns the encryption type ID.
266 o enctype_string()
268 Returns a text description of the encryption type.
269 o length()
271 Returns the length of the session key.
272 o contents()
274 Returns the actual contents of the keyblock (the session key).
275 Authen::Krb5::AuthContext
277 Kerberos 5 auth_context object.
278 o new
280 Allocates memory for a new Authen::Krb5::AuthContext object and
281 returns it.
282 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 o getaddrs()
289 Returns a list containing the local and the remote address of
290 the AuthContext object.
291 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 o getkey()
297 Retrieves the session key as an Authen::Krb5::KeyBlock object.
298 Authen::Krb5::Ticket
300 Kerberos 5 ticket object.
301 o server
303 Returns the server stored in the ticket.
304 o enc_part2
306 Returns a Authen::Krb5::EncTktPart object representation of the
307 ticket data. See below.
308 Authen::Krb5::EncTktPart
310 Object representation of the krb5_enc_tkt_part structure.
311 o client
313 The client principal contained in the ticket.
314 Authen::Krb5::Keyblock
316 Object representation of the krb5_keyblock structure.
317 o enctype
319 The integral enctype of the key.
320 o length
322 Length of the key.
323 o contents
325 Contents of the key itself, as a string.
326 Authen::Krb5::Keytab
328 o add_entry(entry)
329 Adds entry to the keytab.
330 o remove_entry(entry)
332 Removes entry from the keytab.
333 o get_name()
335 Returns the name of the keytab.
336 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 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 o next_entry(cursor)
347 Returns the next entry in the keytab as an
348 Authen::Krb5::KeytabEntry object.
349 o end_seq_get(cursor)
351 Perform cleanup opreations after next_entry() and invalidates
352 cursor.
353 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 o principal
361 An Authen::Krb5::Principal object representing the principal
362 contained in the entry.
363 o timestamp
365 The timestamp of the entry.
366 o kvno
368 The key version number of the key contained in the entry.
369 o key
371 An Authen::Krb5::Keyblock object representing a copy of the
372 keyblock contained in the entry.
373 Authen::Krb5::Creds
375 Object representing a credential.
376 o starttime()
378 Returns the starttime time property of the credential.
379 o authtime()
381 Returns the authtime time property of the credential.
382 o endtime()
384 Returns the endtime time property of the credential.
385 o renew_till()
387 Returns the renew_till time property of the credential.
388 o server()
390 Returns the name of the service principal the credential is
391 for.
392 o client()
394 Returns the client principal name (will usually be identical
395 for all credentials in a credential cache).
396 o ticket()
398 Returns the Authen::Krb5::Ticket for this credential.
399 o keyblock()
401 Returns the keyblock of the credential.
402
404 Jeff Horwitz (jeff@smashing.org)
405
407 Based on the original work by Doug MacEachern and Malcolm Beattie.
408 Code contributions from Scott Hutton (shutton@indiana.edu).
409
411 perl(1), kerberos(1).
412
414 Hey! The above document had some coding errors, which are explained
415 below:
416 Around line 602:
418 You forgot a '=back' before '=head1'
419perl v5.32.0 2020-07-28 Krb5(3)