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_min_classes {KADM5_PW_MIN_CLASSES}
142 Number (between 1 and 5, inclusive) of required character
143 classes represented in a password
144 * pw_min_length {KADM5_PW_MIN_LENGTH}
146 Minimum number of characters in a password
147 * pw_min_life {KADM5_PW_MIN_LIFE}
149 Number of seconds a password must age before the principal may
150 change it
151 * policy_refcnt {KADM5_REF_COUNT}
153 Number of principals referring to this policy (read-only, does
154 not set KADM5_REF_COUNT automatically)
155 Authen::Krb5::Admin::Principal
157 The attributes fail_auth_count, last_failed, and last_success
158 are only meaningful if the KDC is configured to update the
159 database with this type of information.
160 The only methods in this class are the constructor (new,
162 described above), the following accessor methods, and
163 policy_clear, which is used to clear the policy attribute.
164 * attributes {KADM5_ATTRIBUTES}
166 Bitfield representing principal attributes (see kadmin(8))
167 * aux_attributes {KADM5_AUX_ATTRIBUTES}
169 Bitfield used by kadmin. Currently only recognizes the
170 KADM5_POLICY, which indicates that a policy is in effect for
171 this principal. This attribute is read-only, so
172 KADM5_AUX_ATTRIBUTES is not set automatically.
173 * fail_auth_count {KADM5_FAIL_AUTH_COUNT}
175 Number of consecutive failed AS_REQs for this principal. This
176 attribute is read-only, so KADM5_FAIL_AUTH_COUNT is not set
177 automatically.
178 * kvno {KADM5_KVNO}
180 Key version number
181 * last_failed {KADM5_LAST_FAILED}
183 Time (in seconds since the Epoch) of the last failed AS_REQ for
184 this principal. This attribute is read-only, so
185 KADM5_LAST_FAILED is not set automatically.
186 * last_pwd_change {KADM5_LAST_PWD_CHANGE}
188 Time (in seconds since the Epoch) of the last password change
189 for this principal. This attribute is read-only, so
190 KADM5_LAST_PWD_CHANGE is not set automatically.
191 * last_success {KADM5_LAST_SUCCESS}
193 Time (in seconds since the Epoch) of the last successful AS_REQ
194 for this principal. This attribute is read-only, so
195 KADM5_LAST_SUCCESS is not set automatically.
196 * mask Mask (see above)
198 * max_life {KADM5_MAX_LIFE}
200 maximum lifetime in seconds of any Kerberos ticket issued to
201 this principal
202 * max_renewable_life {KADM5_MAX_RLIFE}
204 maximum renewable lifetime in seconds of any Kerberos ticket
205 issued to this principal
206 * mod_date {KADM5_MOD_TIME}
208 Time (in seconds since the Epoch) this principal was last
209 modified. This attribute is read-only, so KADM5_MOD_TIME is
210 not set automatically.
211 * mod_name {KADM5_MOD_NAME}
213 Kerberos principal (Authen::Krb5::Principal, see
214 Authen::Krb5(3)) that last modified this principal. This
215 attribute is read-only, so KADM5_MOD_NAME is not set
216 automatically.
217 * policy {KADM5_POLICY}
219 Name of policy that affects this principal if KADM5_POLICY is
220 set in aux_attributes
221 * policy_clear {KADM5_POLICY_CLR}
223 Not really an attribute--disables the current policy for this
224 principal. This method doesn't return anything.
225 * princ_expire_time {KADM5_PRINC_EXPIRE_TIME}
227 Expire time (in seconds since the Epoch) of the principal
228 * principal {KADM5_PRINCIPAL}
230 Kerberos principal itself (Authen::Krb5::Principal, see
231 Authen::Krb5(3))
232 * pw_expiration {KADM5_PW_EXPIRATION}
234 Expire time (in seconds since the Epoch) of the principal's
235 password
236 Operations
238 To perform kadmin operations (addprinc, delprinc, etc.), we first
239 construct an object of the class Authen::Krb5::Admin, which contains a
240 server handle. Then we use object methods to perform the operations
241 using that handle.
242 In the following synopses, parameter types are indicated by their names
244 as follows:
245 $error Kerberos 5 error code
247 $kadm5 Authen::Krb5::Admin
248 $kadm5_config Authen::Krb5::Admin::Config
249 $kadm5_pol Authen::Krb5::Admin::Policy
250 $kadm5_princ Authen::Krb5::Admin::Principal
251 $krb5_ccache Authen::Krb5::Ccache
252 $krb5_princ Authen::Krb5::Principal
253 $success TRUE if if the call succeeeded, undef otherwise
254 Everything else is an unblessed scalar value (or an array of them)
256 inferable from context.
257 Parameters surrounded by square brackets ([]s) are each optional.
259 Constructors
261 Each of the following constructors authenticates as $client to
262 the admin server $service, which defaults to
263 KADM5_ADMIN_SERVICE if undef. An undefined value for
264 $kadm5_config will cause the interface to infer the
265 configuration from the Kerberos 5 profile (/etc/krb5.conf by
266 default).
267 * $kadm5 = Authen::Krb5::Admin->init_with_creds($client,
269 $krb5_ccache[, $service, $kadm5_config])
270 Authenticate using the credentials cached in $krb5_ccache.
271 * $kadm5 = Authen::Krb5::Admin->init_with_password($client[, $password,
273 $service, $kadm5_config])
274 Authenticate with $password.
275 * $kadm5 = Authen::Krb5::Admin->init_with_skey($client[, $keytab_file,
277 $service, $kadm5_config])
278 Authenticate using the keytab stored in $keytab_file. If
279 $keytab_file is undef, the default keytab is used.
280 Principal Operations
282 * $success = $kadm5->chpass_principal($krb5_princ, $password)
283 Change the password of $krb5_princ to $password.
284 * $success = $kadm5->create_principal($kadm5_princ[, $password])
286 Insert $kadm5_princ into the database, optionally setting its
287 password to the string in $password. Clears KADM5_POLICY_CLR
288 and KADM5_FAIL_AUTH_COUNT.
289 * $success = $kadm5->delete_principal($krb5_princ)
291 Delete the principal represented by $krb5_princ from the
292 database.
293 * $kadm5_princ = $kadm5->get_principal($krb5_princ[, $mask])
295 Retrieve the Authen::Krb5::Admin::Principal object for the
296 principal $krb5_princ from the database. Use
297 KADM5_PRINCIPAL_NORMAL_MASK to retrieve all of the useful
298 attributes.
299 * @names = $kadm5->get_principals([$expr])
301 Retrieve a list of principal names matching the glob pattern
302 $expr. In the absence of $expr, retrieve the list of all
303 principal names.
304 * $success = $kadm5->modify_principal($kadm5_princ)
306 Modify $kadm5_princ in the database. The principal to modify
307 is determined by "$kadm5_princ->principal", and the rest of the
308 writable parameters will be modified accordingly. Clears
309 KADM5_PRINCIPAL.
310 * @keys = $kadm5->randkey_principal($krb5_princ)
312 Randomize the principal in the database represented by
313 $krb5_princ and return Authen::Krb5::Keyblock objects.
314 * $success = $kadm5->rename_principal($krb5_princ_from, $krb5_princ_to)
316 Change the name of the principal from $krb5_princ_from to
317 $krb5_princ_to.
318 Policy Operations
320 * $success = $kadm5->create_policy($kadm5_pol)
321 Insert $kadm5_pol into the database.
322 * $success = $kadm5->delete_policy($name)
324 Delete the policy named $name from the database.
325 * $kadm5_pol = $kadm5->get_policy([$name])
327 Retrieve the Authen::Krb5::Admin::Policy object for the policy
328 named $name from the database.
329 * @names = $kadm5->get_policies([$expr])
331 Retrieve a list of policy names matching the glob pattern
332 $expr. In the absence of $expr, retrieve the list of all
333 policy names.
334 * $success = $kadm5->modify_policy($kadm5_pol)
336 Modify $kadm5_pol in the database. The policy to modify is
337 determined by "$kadm5_pol-"name>,(and the rest of the writable)
338 parameters will be modified accordingly. Clears KADM5_POLICY.
339 Other Methods
341 * $magic_value = Authen::Krb5::Admin::error [$error]
342 Return value that acts like $! (see perlvar(1)) for the most
343 recent Authen::Krb5::Admin call. With error code $error,
344 return the error message corresponding to that error code.
345 * $privs = $kadm5->get_privs
347 Return a bitfield representing the kadmin privileges a
348 principal has, as follows:
349 get KADM5_PRIV_GET
351 add KADM5_PRIV_ADD
352 modify KADM5_PRIV_MODIFY
353 delete KADM5_PRIV_DELETE
354
356 See the unit tests included with this software for examlpes. They can
357 be found in the t/ subdirectory of the distribution.
358
360 krb.conf Kerberos 5 configuration file
361
363 There is no facility for specifying keysalts for methods like
364 create_principal and modify_principal. This facility is provided by
365 the Kerberos 5 API and requires an initialized context. So it probably
366 makes more sense for Authen::Krb5(3) to handle those functions.
367
369 Andrew J. Korty <ajk@iu.edu>
370
372 perl(1), perlvar(1), Authen::Krb5(3), Exporter(3), kadmin(8).
373perl v5.12.0 2008-02-25 Admin(3)