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

NAME

6       Authen::Krb5::Admin - Perl extension for MIT Kerberos 5 admin interface
7

SYNOPSIS

9         use Authen::Krb5::Admin;
10         use Authen::Krb5::Admin qw(:constants);
11

DESCRIPTION

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
17       The following classes are provided by this module:
18
19        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
25   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
30               Authen::Krb5::Admin::Config
31               Authen::Krb5::Admin::Key
32               Authen::Krb5::Admin::Policy
33               Authen::Krb5::Admin::Principal
34
35       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
42       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
46       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
52       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
56       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
63       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
69       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
77               The only methods in this class are the constructor (new,
78               described above) and the following accessor methods.
79
80       * admin_server {KADM5_CONFIG_ADMIN_SERVER}
81               Admin server hostname
82
83       * kadmind_port {KADM5_CONFIG_KADMIND_PORT}
84               Admin server port number
85
86       * kpasswd_port {KADM5_CONFIG_KPASSWD_PORT}
87               Kpasswd server port number
88
89       * mask  Mask (described above)
90
91       * profile {KADM5_CONFIG_PROFILE}
92               Kerberos 5 configuration profile
93
94       * realm {KADM5_CONFIG_REALM}
95               Kerberos 5 realm name
96
97       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
102       * key_contents
103               Key contents, encrypted with the KDC master key.  This data may
104               not be available remotely.
105
106       * enc_type
107               Kerberos 5 enctype of the key
108
109       * key_type
110               Alias for enc_type
111
112       * kvno  Key version number
113
114       * salt_contents
115               Salt contents, if any (ver > 1)
116
117       * salt_type
118               Salt type, if any (ver > 1)
119
120       * ver   Version number of the underlying krb5_key_data structure
121
122       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
127       * mask  Mask (described above)
128
129       * name {KADM5_POLICY}
130               Policy name
131
132       * 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
137       * 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
141       * pw_max_fail {KADM5_PW_MAX_FAILURE}
142               The maximum allowed number of attempts before a lockout.
143
144       * pw_failcnt_interval {KADM5_PW_FAILURE_COUNT_INTERVAL}
145               The period after which the bad preauthentication count will be
146               reset.
147
148       * 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
152       * pw_min_classes {KADM5_PW_MIN_CLASSES}
153               Number (between 1 and 5, inclusive) of required character
154               classes represented in a password
155
156       * pw_min_length {KADM5_PW_MIN_LENGTH}
157               Minimum number of characters in a password
158
159       * pw_min_life {KADM5_PW_MIN_LIFE}
160               Number of seconds a password must age before the principal may
161               change it
162
163       * policy_refcnt {KADM5_REF_COUNT}
164               Number of principals referring to this policy (read-only, does
165               not set KADM5_REF_COUNT automatically)
166
167       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
172               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
176       * attributes {KADM5_ATTRIBUTES}
177               Bitfield representing principal attributes (see kadmin(8))
178
179       * 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
185       * 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
190       * kvno {KADM5_KVNO}
191               Key version number
192
193       * 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
198       * 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
203       * 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
208       * mask  Mask (see above)
209
210       * max_life {KADM5_MAX_LIFE}
211               maximum lifetime in seconds of any Kerberos ticket issued to
212               this principal
213
214       * max_renewable_life {KADM5_MAX_RLIFE}
215               maximum renewable lifetime in seconds of any Kerberos ticket
216               issued to this principal
217
218       * 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
223       * 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
229       * policy {KADM5_POLICY}
230               Name of policy that affects this principal if KADM5_POLICY is
231               set in aux_attributes
232
233       * 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
237       * princ_expire_time {KADM5_PRINC_EXPIRE_TIME}
238               Expire time (in seconds since the Epoch) of the principal
239
240       * principal {KADM5_PRINCIPAL}
241               Kerberos principal itself (Authen::Krb5::Principal, see
242               Authen::Krb5(3))
243
244       * pw_expiration {KADM5_PW_EXPIRATION}
245               Expire time (in seconds since the Epoch) of the principal's
246               password
247
248       * 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
255                   my @old = $principal->db_args;
256                   # -or-
257                   my @old = $principal->db_args(@new);
258
259                   # The RPC call will ignore the tail data unless
260                   # you set this flag:
261                   $principal->mask($principal->mask | KADM5_TL_DATA);
262
263   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
269       In the following synopses, parameter types are indicated by their names
270       as follows:
271
272               $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
281       Everything else is an unblessed scalar value (or an array of them)
282       inferable from context.
283
284       Parameters surrounded by square brackets ([]s) are each optional.
285
286       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
294       * $kadm5 =  Authen::Krb5::Admin->init_with_creds($client,
295       $krb5_ccache[, $service, $kadm5_config])
296               Authenticate using the credentials cached in $krb5_ccache.
297
298       * $kadm5 = Authen::Krb5::Admin->init_with_password($client[, $password,
299       $service, $kadm5_config])
300               Authenticate with $password.
301
302       * $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
307       Principal Operations
308       * $success = $kadm5->chpass_principal($krb5_princ, $password)
309               Change the password of $krb5_princ to $password.
310
311       * $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
316       * $success = $kadm5->delete_principal($krb5_princ)
317               Delete the principal represented by $krb5_princ from the
318               database.
319
320       * $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
326       * @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
331       * $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
337       * @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
341       * $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
345       Policy Operations
346       * $success = $kadm5->create_policy($kadm5_pol)
347               Insert $kadm5_pol into the database.
348
349       * $success = $kadm5->delete_policy($name)
350               Delete the policy named $name from the database.
351
352       * $kadm5_pol = $kadm5->get_policy([$name])
353               Retrieve the Authen::Krb5::Admin::Policy object for the policy
354               named $name from the database.
355
356       * @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
361       * $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
366       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
372       * $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
376       * $privs = $kadm5->get_privs
377               Return a bitfield representing the kadmin privileges a
378               principal has, as follows:
379
380                       get     KADM5_PRIV_GET
381                       add     KADM5_PRIV_ADD
382                       modify  KADM5_PRIV_MODIFY
383                       delete  KADM5_PRIV_DELETE
384

EXAMPLES

386       See the unit tests included with this software for examlpes.  They can
387       be found in the t/ subdirectory of the distribution.
388

FILES

390        krb.conf               Kerberos 5 configuration file
391

BUGS

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

AUTHOR

399       Stephen Quinney <squinney@inf.ed.ac.uk>
400
401       Author Emeritus: Andrew J. Korty <ajk@iu.edu>
402

SEE ALSO

404       perl(1), perlvar(1), Authen::Krb5(3), Exporter(3), kadmin(8).
405

POD ERRORS

407       Hey! The above document had some coding errors, which are explained
408       below:
409
410       Around line 316:
411           Expected text after =item, not a bullet
412
413       Around line 320:
414           Expected text after =item, not a bullet
415
416       Around line 324:
417           Expected text after =item, not a bullet
418
419       Around line 328:
420           Expected text after =item, not a bullet
421
422       Around line 332:
423           Expected text after =item, not a bullet
424
425       Around line 336:
426           Expected text after =item, not a bullet
427
428       Around line 346:
429           Expected text after =item, not a bullet
430
431       Around line 351:
432           Expected text after =item, not a bullet
433
434       Around line 355:
435           Expected text after =item, not a bullet
436
437       Around line 359:
438           Expected text after =item, not a bullet
439
440       Around line 363:
441           Expected text after =item, not a bullet
442
443       Around line 367:
444           Expected text after =item, not a bullet
445
446       Around line 371:
447           Expected text after =item, not a bullet
448
449       Around line 381:
450           Expected text after =item, not a bullet
451
452       Around line 385:
453           Expected text after =item, not a bullet
454
455       Around line 389:
456           Expected text after =item, not a bullet
457
458       Around line 395:
459           Expected text after =item, not a bullet
460
461       Around line 400:
462           Expected text after =item, not a bullet
463
464       Around line 404:
465           Expected text after =item, not a bullet
466
467       Around line 408:
468           Expected text after =item, not a bullet
469
470       Around line 413:
471           Expected text after =item, not a bullet
472
473       Around line 418:
474           Expected text after =item, not a bullet
475
476       Around line 422:
477           Expected text after =item, not a bullet
478
479       Around line 427:
480           Expected text after =item, not a bullet
481
482       Around line 442:
483           Expected text after =item, not a bullet
484
485       Around line 446:
486           Expected text after =item, not a bullet
487
488       Around line 453:
489           Expected text after =item, not a bullet
490
491       Around line 459:
492           Expected text after =item, not a bullet
493
494       Around line 463:
495           Expected text after =item, not a bullet
496
497       Around line 469:
498           Expected text after =item, not a bullet
499
500       Around line 475:
501           Expected text after =item, not a bullet
502
503       Around line 481:
504           Expected text after =item, not a bullet
505
506       Around line 485:
507           Expected text after =item, not a bullet
508
509       Around line 490:
510           Expected text after =item, not a bullet
511
512       Around line 495:
513           Expected text after =item, not a bullet
514
515       Around line 501:
516           Expected text after =item, not a bullet
517
518       Around line 507:
519           Expected text after =item, not a bullet
520
521       Around line 512:
522           Expected text after =item, not a bullet
523
524       Around line 517:
525           Expected text after =item, not a bullet
526
527       Around line 521:
528           Expected text after =item, not a bullet
529
530       Around line 526:
531           Expected text after =item, not a bullet
532
533       Around line 530:
534           Expected text after =item, not a bullet
535
536       Around line 581:
537           Expected text after =item, not a bullet
538
539       Around line 585:
540           Expected text after =item, not a bullet
541
542       Around line 589:
543           Expected text after =item, not a bullet
544
545       Around line 596:
546           Expected text after =item, not a bullet
547
548       Around line 600:
549           Expected text after =item, not a bullet
550
551       Around line 606:
552           Expected text after =item, not a bullet
553
554       Around line 610:
555           Expected text after =item, not a bullet
556
557       Around line 616:
558           Expected text after =item, not a bullet
559
560       Around line 621:
561           Expected text after =item, not a bullet
562
563       Around line 627:
564           Expected text after =item, not a bullet
565
566       Around line 632:
567           Expected text after =item, not a bullet
568
569       Around line 638:
570           Expected text after =item, not a bullet
571
572       Around line 642:
573           Expected text after =item, not a bullet
574
575       Around line 646:
576           Expected text after =item, not a bullet
577
578       Around line 651:
579           Expected text after =item, not a bullet
580
581       Around line 656:
582           Expected text after =item, not a bullet
583
584       Around line 664:
585           Expected text after =item, not a bullet
586
587       Around line 670:
588           Expected text after =item, not a bullet
589
590       Around line 675:
591           Expected text after =item, not a bullet
592
593
594
595perl v5.34.0                      2022-01-20                          Admin(3)
Impressum