1Admin(3) User Contributed Perl Documentation Admin(3)
2
6 Authen::Krb5::Admin - Perl extension for MIT Kerberos 5 admin interface
7
9 use Authen::Krb5::Admin;
10 use Authen::Krb5::Admin qw(:constants);
11
13 The Authen::Krb5::Admin Perl module is an object-oriented interface to
14 the Kerberos 5 admin server. Currently only MIT KDCs are supported,
15 but the author envisions seamless integration with other KDCs.
16 The following classes are provided by this module:
18 Authen::Krb5::Admin handle for performing kadmin operations
20 Authen::Krb5::Admin::Config kadmin configuration parameters
21 Authen::Krb5::Admin::Key key data from principal object
22 Authen::Krb5::Admin::Policy kadmin policies
23 Authen::Krb5::Admin::Principal kadmin principals
24 Configuration Parameters, Policies, and Principals
26 Before performing kadmin operations, the programmer must construct
27 objects to represent the entities to be manipulated. Each of the
28 classes
29 Authen::Krb5::Admin::Config
31 Authen::Krb5::Admin::Key
32 Authen::Krb5::Admin::Policy
33 Authen::Krb5::Admin::Principal
34 has a constructor new which takes no arguments (except for the class
36 name). The new object may be populated using accessor methods, each of
37 which is named for the C struct element it represents. Methods always
38 return the current value of the attribute, except for the policy_clear
39 method, which returns nothing. If a value is provided, the attribute
40 is set to that value, and the new value is returned.
41 All attributes may be modified in each object, but read-only attributes
43 will be ignored when performing kadmin operations. These attributes
44 are indicated in the documentation for their accessor methods.
45 Each of the C functions that manipulate kadm5 principal and policy
47 structures takes a mask argument to indicate which fields should be
48 taken into account. The Perl accessor methods take care of the mask
49 for you, assuming that when you change a value, you will eventually
50 want it changed on the server.
51 Flags for the read-only fields do not get set automatically because
53 they would result in a bad mask error when performing kadmin
54 operations.
55 Some writable attributes are not allowed to have their masks set for
57 certain operations. For example, KADM5_POLICY may not be set during a
58 create_principal operation, but since the Perl module sets that flag
59 automatically when you set the policy attribute of the principal
60 object, a bad mask error would result. Therefore, some kadmin
61 operations automatically clear certain flags first.
62 Though you should never have to, you can manipulate the mask on your
64 own using the mask methods and the flags associated with each attribute
65 (indicated in curly braces ({}s) below). Use the tag :constants to
66 request that the flag constants (and all other constants) be made
67 available (see Exporter(3)).
68 Authen::Krb5::Admin::Config
70 This class is used to configure a kadmin connection. Without
71 this object, Authen::Krb5::Admin constructors will default to
72 the configuration defined in the Kerberos 5 profile
73 (/etc/krb5.conf by default). So this object is usually only
74 needed when selecting alternate realms or contacting a
75 specific, non-default server.
76 The only methods in this class are the constructor (new,
78 described above) and the following accessor methods.
79 * admin_server {KADM5_CONFIG_ADMIN_SERVER}
81 Admin server hostname
82 * kadmind_port {KADM5_CONFIG_KADMIND_PORT}
84 Admin server port number
85 * kpasswd_port {KADM5_CONFIG_KPASSWD_PORT}
87 Kpasswd server port number
88 * mask Mask (described above)
90 * profile {KADM5_CONFIG_PROFILE}
92 Kerberos 5 configuration profile
93 * realm {KADM5_CONFIG_REALM}
95 Kerberos 5 realm name
96 Authen::Krb5::Admin::Key
98 This class represents key data contained in kadmin principal
99 objects. The only methods in this class are the constructor
100 (new, described above) and the following accessor methods.
101 * key_contents
103 Key contents, encrypted with the KDC master key. This data may
104 not be available remotely.
105 * enc_type
107 Kerberos 5 enctype of the key
108 * key_type
110 Alias for enc_type
111 * kvno Key version number
113 * salt_contents
115 Salt contents, if any (ver > 1)
116 * salt_type
118 Salt type, if any (ver > 1)
119 * ver Version number of the underlying krb5_key_data structure
121 Authen::Krb5::Admin::Policy
123 This class represents kadmin policies. The only methods in
124 this class are the constructor (new, described above) and the
125 following accessor methods.
126 * mask Mask (described above)
128 * name {KADM5_POLICY}
130 Policy name
131 * pw_history_num {KADM5_PW_HISTORY_NUM}
133 Number (between 1 and 10, inclusive) of past passwords to be
134 stored for the principal. A principal may not set its password
135 to any of its previous pw_history_num passwords.
136 * pw_max_life {KADM5_PW_MAX_LIFE}
138 Default number of seconds a password lasts before the principal
139 is required to change it
140 * pw_max_fail {KADM5_PW_MAX_FAILURE}
142 The maximum allowed number of attempts before a lockout.
143 * pw_failcnt_interval {KADM5_PW_FAILURE_COUNT_INTERVAL}
145 The period after which the bad preauthentication count will be
146 reset.
147 * pw_lockout_duration {KADM5_PW_LOCKOUT_DURATION}
149 The period in which lockout is enforced; a duration of zero
150 means that the principal must be manually unlocked.
151 * pw_min_classes {KADM5_PW_MIN_CLASSES}
153 Number (between 1 and 5, inclusive) of required character
154 classes represented in a password
155 * pw_min_length {KADM5_PW_MIN_LENGTH}
157 Minimum number of characters in a password
158 * pw_min_life {KADM5_PW_MIN_LIFE}
160 Number of seconds a password must age before the principal may
161 change it
162 * policy_refcnt {KADM5_REF_COUNT}
164 Number of principals referring to this policy (read-only, does
165 not set KADM5_REF_COUNT automatically)
166 Authen::Krb5::Admin::Principal
168 The attributes fail_auth_count, last_failed, and last_success
169 are only meaningful if the KDC is configured to update the
170 database with this type of information.
171 The only methods in this class are the constructor (new,
173 described above), the following accessor methods, and
174 policy_clear, which is used to clear the policy attribute.
175 * attributes {KADM5_ATTRIBUTES}
177 Bitfield representing principal attributes (see kadmin(8))
178 * aux_attributes {KADM5_AUX_ATTRIBUTES}
180 Bitfield used by kadmin. Currently only recognizes the
181 KADM5_POLICY, which indicates that a policy is in effect for
182 this principal. This attribute is read-only, so
183 KADM5_AUX_ATTRIBUTES is not set automatically.
184 * fail_auth_count {KADM5_FAIL_AUTH_COUNT}
186 Number of consecutive failed AS_REQs for this principal. This
187 attribute is read-only, so KADM5_FAIL_AUTH_COUNT is not set
188 automatically.
189 * kvno {KADM5_KVNO}
191 Key version number
192 * last_failed {KADM5_LAST_FAILED}
194 Time (in seconds since the Epoch) of the last failed AS_REQ for
195 this principal. This attribute is read-only, so
196 KADM5_LAST_FAILED is not set automatically.
197 * last_pwd_change {KADM5_LAST_PWD_CHANGE}
199 Time (in seconds since the Epoch) of the last password change
200 for this principal. This attribute is read-only, so
201 KADM5_LAST_PWD_CHANGE is not set automatically.
202 * last_success {KADM5_LAST_SUCCESS}
204 Time (in seconds since the Epoch) of the last successful AS_REQ
205 for this principal. This attribute is read-only, so
206 KADM5_LAST_SUCCESS is not set automatically.
207 * mask Mask (see above)
209 * max_life {KADM5_MAX_LIFE}
211 maximum lifetime in seconds of any Kerberos ticket issued to
212 this principal
213 * max_renewable_life {KADM5_MAX_RLIFE}
215 maximum renewable lifetime in seconds of any Kerberos ticket
216 issued to this principal
217 * mod_date {KADM5_MOD_TIME}
219 Time (in seconds since the Epoch) this principal was last
220 modified. This attribute is read-only, so KADM5_MOD_TIME is
221 not set automatically.
222 * mod_name {KADM5_MOD_NAME}
224 Kerberos principal (Authen::Krb5::Principal, see
225 Authen::Krb5(3)) that last modified this principal. This
226 attribute is read-only, so KADM5_MOD_NAME is not set
227 automatically.
228 * policy {KADM5_POLICY}
230 Name of policy that affects this principal if KADM5_POLICY is
231 set in aux_attributes
232 * policy_clear {KADM5_POLICY_CLR}
234 Not really an attribute--disables the current policy for this
235 principal. This method doesn't return anything.
236 * princ_expire_time {KADM5_PRINC_EXPIRE_TIME}
238 Expire time (in seconds since the Epoch) of the principal
239 * principal {KADM5_PRINCIPAL}
241 Kerberos principal itself (Authen::Krb5::Principal, see
242 Authen::Krb5(3))
243 * pw_expiration {KADM5_PW_EXPIRATION}
245 Expire time (in seconds since the Epoch) of the principal's
246 password
247 * db_args [@ARGS]
249 When called without any @ARGS, returns the list of arguments
250 that will be passed into the underlying database, as with
251 "addprinc -x" in "kadmin". If @ARGS is non-empty, it will
252 replace any database arguments, which will then be returned,
253 like this:
254 my @old = $principal->db_args;
256 # -or-
257 my @old = $principal->db_args(@new);
258 # The RPC call will ignore the tail data unless
260 # you set this flag:
261 $principal->mask($principal->mask | KADM5_TL_DATA);
262 Operations
264 To perform kadmin operations (addprinc, delprinc, etc.), we first
265 construct an object of the class Authen::Krb5::Admin, which contains a
266 server handle. Then we use object methods to perform the operations
267 using that handle.
268 In the following synopses, parameter types are indicated by their names
270 as follows:
271 $error Kerberos 5 error code
273 $kadm5 Authen::Krb5::Admin
274 $kadm5_config Authen::Krb5::Admin::Config
275 $kadm5_pol Authen::Krb5::Admin::Policy
276 $kadm5_princ Authen::Krb5::Admin::Principal
277 $krb5_ccache Authen::Krb5::Ccache
278 $krb5_princ Authen::Krb5::Principal
279 $success TRUE if if the call succeeeded, undef otherwise
280 Everything else is an unblessed scalar value (or an array of them)
282 inferable from context.
283 Parameters surrounded by square brackets ([]s) are each optional.
285 Constructors
287 Each of the following constructors authenticates as $client to
288 the admin server $service, which defaults to
289 KADM5_ADMIN_SERVICE if undef. An undefined value for
290 $kadm5_config will cause the interface to infer the
291 configuration from the Kerberos 5 profile (/etc/krb5.conf by
292 default).
293 * $kadm5 = Authen::Krb5::Admin->init_with_creds($client,
295 $krb5_ccache[, $service, $kadm5_config])
296 Authenticate using the credentials cached in $krb5_ccache.
297 * $kadm5 = Authen::Krb5::Admin->init_with_password($client[, $password,
299 $service, $kadm5_config])
300 Authenticate with $password.
301 * $kadm5 = Authen::Krb5::Admin->init_with_skey($client[, $keytab_file,
303 $service, $kadm5_config])
304 Authenticate using the keytab stored in $keytab_file. If
305 $keytab_file is undef, the default keytab is used.
306 Principal Operations
308 * $success = $kadm5->chpass_principal($krb5_princ, $password)
309 Change the password of $krb5_princ to $password.
310 * $success = $kadm5->create_principal($kadm5_princ[, $password])
312 Insert $kadm5_princ into the database, optionally setting its
313 password to the string in $password. Clears KADM5_POLICY_CLR
314 and KADM5_FAIL_AUTH_COUNT.
315 * $success = $kadm5->delete_principal($krb5_princ)
317 Delete the principal represented by $krb5_princ from the
318 database.
319 * $kadm5_princ = $kadm5->get_principal($krb5_princ[, $mask])
321 Retrieve the Authen::Krb5::Admin::Principal object for the
322 principal $krb5_princ from the database. Use
323 KADM5_PRINCIPAL_NORMAL_MASK to retrieve all of the useful
324 attributes.
325 * @names = $kadm5->get_principals([$expr])
327 Retrieve a list of principal names matching the glob pattern
328 $expr. In the absence of $expr, retrieve the list of all
329 principal names.
330 * $success = $kadm5->modify_principal($kadm5_princ)
332 Modify $kadm5_princ in the database. The principal to modify
333 is determined by "$kadm5_princ->principal", and the rest of the
334 writable parameters will be modified accordingly. Clears
335 KADM5_PRINCIPAL.
336 * @keys = $kadm5->randkey_principal($krb5_princ)
338 Randomize the principal in the database represented by
339 $krb5_princ and return Authen::Krb5::Keyblock objects.
340 * $success = $kadm5->rename_principal($krb5_princ_from, $krb5_princ_to)
342 Change the name of the principal from $krb5_princ_from to
343 $krb5_princ_to.
344 Policy Operations
346 * $success = $kadm5->create_policy($kadm5_pol)
347 Insert $kadm5_pol into the database.
348 * $success = $kadm5->delete_policy($name)
350 Delete the policy named $name from the database.
351 * $kadm5_pol = $kadm5->get_policy([$name])
353 Retrieve the Authen::Krb5::Admin::Policy object for the policy
354 named $name from the database.
355 * @names = $kadm5->get_policies([$expr])
357 Retrieve a list of policy names matching the glob pattern
358 $expr. In the absence of $expr, retrieve the list of all
359 policy names.
360 * $success = $kadm5->modify_policy($kadm5_pol)
362 Modify $kadm5_pol in the database. The policy to modify is
363 determined by "$kadm5_pol-"name>,(and the rest of the writable)
364 parameters will be modified accordingly. Clears KADM5_POLICY.
365 Other Methods
367 * $magic_value = Authen::Krb5::Admin::error [$error]
368 Return value that acts like $! (see perlvar(1)) for the most
369 recent Authen::Krb5::Admin call. With error code $error,
370 return the error message corresponding to that error code.
371 * $error_code = Authen::Krb5::Admin::error_code
373 Returns the value of the error code for the most recent
374 Authen::Krb5::Admin call as a simple integer.
375 * $privs = $kadm5->get_privs
377 Return a bitfield representing the kadmin privileges a
378 principal has, as follows:
379 get KADM5_PRIV_GET
381 add KADM5_PRIV_ADD
382 modify KADM5_PRIV_MODIFY
383 delete KADM5_PRIV_DELETE
384
386 See the unit tests included with this software for examlpes. They can
387 be found in the t/ subdirectory of the distribution.
388
390 krb.conf Kerberos 5 configuration file
391
393 There is no facility for specifying keysalts for methods like
394 create_principal and modify_principal. This facility is provided by
395 the Kerberos 5 API and requires an initialized context. So it probably
396 makes more sense for Authen::Krb5(3) to handle those functions.
397
399 Stephen Quinney <squinney@inf.ed.ac.uk>
400 Author Emeritus: Andrew J. Korty <ajk@iu.edu>
402
404 perl(1), perlvar(1), Authen::Krb5(3), Exporter(3), kadmin(8).
405
407 Hey! The above document had some coding errors, which are explained
408 below:
409 Around line 316:
411 Expected text after =item, not a bullet
412 Around line 320:
414 Expected text after =item, not a bullet
415 Around line 324:
417 Expected text after =item, not a bullet
418 Around line 328:
420 Expected text after =item, not a bullet
421 Around line 332:
423 Expected text after =item, not a bullet
424 Around line 336:
426 Expected text after =item, not a bullet
427 Around line 346:
429 Expected text after =item, not a bullet
430 Around line 351:
432 Expected text after =item, not a bullet
433 Around line 355:
435 Expected text after =item, not a bullet
436 Around line 359:
438 Expected text after =item, not a bullet
439 Around line 363:
441 Expected text after =item, not a bullet
442 Around line 367:
444 Expected text after =item, not a bullet
445 Around line 371:
447 Expected text after =item, not a bullet
448 Around line 381:
450 Expected text after =item, not a bullet
451 Around line 385:
453 Expected text after =item, not a bullet
454 Around line 389:
456 Expected text after =item, not a bullet
457 Around line 395:
459 Expected text after =item, not a bullet
460 Around line 400:
462 Expected text after =item, not a bullet
463 Around line 404:
465 Expected text after =item, not a bullet
466 Around line 408:
468 Expected text after =item, not a bullet
469 Around line 413:
471 Expected text after =item, not a bullet
472 Around line 418:
474 Expected text after =item, not a bullet
475 Around line 422:
477 Expected text after =item, not a bullet
478 Around line 427:
480 Expected text after =item, not a bullet
481 Around line 442:
483 Expected text after =item, not a bullet
484 Around line 446:
486 Expected text after =item, not a bullet
487 Around line 453:
489 Expected text after =item, not a bullet
490 Around line 459:
492 Expected text after =item, not a bullet
493 Around line 463:
495 Expected text after =item, not a bullet
496 Around line 469:
498 Expected text after =item, not a bullet
499 Around line 475:
501 Expected text after =item, not a bullet
502 Around line 481:
504 Expected text after =item, not a bullet
505 Around line 485:
507 Expected text after =item, not a bullet
508 Around line 490:
510 Expected text after =item, not a bullet
511 Around line 495:
513 Expected text after =item, not a bullet
514 Around line 501:
516 Expected text after =item, not a bullet
517 Around line 507:
519 Expected text after =item, not a bullet
520 Around line 512:
522 Expected text after =item, not a bullet
523 Around line 517:
525 Expected text after =item, not a bullet
526 Around line 521:
528 Expected text after =item, not a bullet
529 Around line 526:
531 Expected text after =item, not a bullet
532 Around line 530:
534 Expected text after =item, not a bullet
535 Around line 581:
537 Expected text after =item, not a bullet
538 Around line 585:
540 Expected text after =item, not a bullet
541 Around line 589:
543 Expected text after =item, not a bullet
544 Around line 596:
546 Expected text after =item, not a bullet
547 Around line 600:
549 Expected text after =item, not a bullet
550 Around line 606:
552 Expected text after =item, not a bullet
553 Around line 610:
555 Expected text after =item, not a bullet
556 Around line 616:
558 Expected text after =item, not a bullet
559 Around line 621:
561 Expected text after =item, not a bullet
562 Around line 627:
564 Expected text after =item, not a bullet
565 Around line 632:
567 Expected text after =item, not a bullet
568 Around line 638:
570 Expected text after =item, not a bullet
571 Around line 642:
573 Expected text after =item, not a bullet
574 Around line 646:
576 Expected text after =item, not a bullet
577 Around line 651:
579 Expected text after =item, not a bullet
580 Around line 656:
582 Expected text after =item, not a bullet
583 Around line 664:
585 Expected text after =item, not a bullet
586 Around line 670:
588 Expected text after =item, not a bullet
589 Around line 675:
591 Expected text after =item, not a bullet
592perl v5.38.0 2023-07-20 Admin(3)