1Admin(3) User Contributed Perl Documentation Admin(3)
2
3
4
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
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
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
401 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
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.30.1 2020-01-29 Admin(3)