Admin(3pm)
NAME
Authen::Krb5::Admin - Perl extension for MIT Kerberos 5 admin interface
SYNOPSIS
use Authen::Krb5::Admin; use Authen::Krb5::Admin qw(:constants);
DESCRIPTION
The Authen::Krb5::Admin Perl module is an object-oriented interface to
the Kerberos 5 admin server. Currently only MIT KDCs are supported,
but the author envisions seamless integration with other KDCs.
- The following classes are provided by this module:
- Authen::Krb5::Admin handle for performing kadmin operations
Authen::Krb5::Admin::Config kadmin configuration parameters
Authen::Krb5::Admin::Key key data from principal object
Authen::Krb5::Admin::Policy kadmin policies
Authen::Krb5::Admin::Principal kadmin principals - Configuration Parameters, Policies, and Principals
- Before performing kadmin operations, the programmer must construct
objects to represent the entities to be manipulated. Each of the
classes
Authen::Krb5::Admin::Config
Authen::Krb5::Admin::Key
Authen::Krb5::Admin::Policy
Authen::Krb5::Admin::Principal - has a constructor new which takes no arguments (except for the class
name). The new object may be populated using accessor methods, each of
which is named for the C struct element it represents. Methods always
return the current value of the attribute, except for the policy_clear
method, which returns nothing. If a value is provided, the attribute
is set to that value, and the new value is returned. - All attributes may be modified in each object, but read-only attributes
will be ignored when performing kadmin operations. These attributes
are indicated in the documentation for their accessor methods. - Each of the C functions that manipulate kadm5 principal and policy
structures takes a mask argument to indicate which fields should be
taken into account. The Perl accessor methods take care of the mask
for you, assuming that when you change a value, you will eventually
want it changed on the server. - Flags for the read-only fields do not get set automatically because
they would result in a bad mask error when performing kadmin
operations. - Some writable attributes are not allowed to have their masks set for
certain operations. For example, KADM5_POLICY may not be set during a create_principal operation, but since the Perl module sets that flag automatically when you set the policy attribute of the principal object, a bad mask error would result. Therefore, some kadmin
operations automatically clear certain flags first. - Though you should never have to, you can manipulate the mask on your
own using the mask methods and the flags associated with each attribute (indicated in curly braces ({}s) below). Use the tag :constants to request that the flag constants (and all other constants) be made
available (see Exporter(3)). - Authen::Krb5::Admin::Config
- This class is used to configure a kadmin connection. Without
this object, Authen::Krb5::Admin constructors will default to the configuration defined in the Kerberos 5 profile
(/etc/krb5.conf by default). So this object is usually only needed when selecting alternate realms or contacting a
specific, non-default server. - The only methods in this class are the constructor (new, described above) and the following accessor methods.
- * admin_server {KADM5_CONFIG_ADMIN_SERVER}
- Admin server hostname
- * kadmind_port {KADM5_CONFIG_KADMIND_PORT}
- Admin server port number
- * kpasswd_port {KADM5_CONFIG_KPASSWD_PORT}
- Kpasswd server port number
- * mask Mask (described above)
- * profile {KADM5_CONFIG_PROFILE}
- Kerberos 5 configuration profile
- * realm {KADM5_CONFIG_REALM}
- Kerberos 5 realm name
- Authen::Krb5::Admin::Key
- This class represents key data contained in kadmin principal
objects. The only methods in this class are the constructor
(new, described above) and the following accessor methods. - * key_contents
- Key contents, encrypted with the KDC master key. This data may not be available remotely.
- * enc_type
- Kerberos 5 enctype of the key
- * key_type
- Alias for enc_type
- * kvno Key version number
- * salt_contents
- Salt contents, if any (ver > 1)
- * salt_type
- Salt type, if any (ver > 1)
- * ver Version number of the underlying krb5_key_data structure
- Authen::Krb5::Admin::Policy
- This class represents kadmin policies. The only methods in
this class are the constructor (new, described above) and the following accessor methods. - * mask Mask (described above)
- * name {KADM5_POLICY}
- Policy name
- * pw_history_num {KADM5_PW_HISTORY_NUM}
- Number (between 1 and 10, inclusive) of past passwords to be
stored for the principal. A principal may not set its password to any of its previous pw_history_num passwords. - * pw_max_life {KADM5_PW_MAX_LIFE}
- Default number of seconds a password lasts before the principal is required to change it
- * pw_min_classes {KADM5_PW_MIN_CLASSES}
- Number (between 1 and 5, inclusive) of required character
classes represented in a password - * pw_min_length {KADM5_PW_MIN_LENGTH}
- Minimum number of characters in a password
- * pw_min_life {KADM5_PW_MIN_LIFE}
- Number of seconds a password must age before the principal may change it
- * policy_refcnt {KADM5_REF_COUNT}
- Number of principals referring to this policy (read-only, does not set KADM5_REF_COUNT automatically)
- Authen::Krb5::Admin::Principal
- The attributes fail_auth_count, last_failed, and last_success
are only meaningful if the KDC is configured to update the
database with this type of information. - The only methods in this class are the constructor (new,
described above), the following accessor methods, and
policy_clear, which is used to clear the policy attribute. - * attributes {KADM5_ATTRIBUTES}
- Bitfield representing principal attributes (see kadmin(8))
- * aux_attributes {KADM5_AUX_ATTRIBUTES}
- Bitfield used by kadmin. Currently only recognizes the
KADM5_POLICY, which indicates that a policy is in effect for
this principal. This attribute is read-only, so
KADM5_AUX_ATTRIBUTES is not set automatically. - * fail_auth_count {KADM5_FAIL_AUTH_COUNT}
- Number of consecutive failed AS_REQs for this principal. This
attribute is read-only, so KADM5_FAIL_AUTH_COUNT is not set
automatically. - * kvno {KADM5_KVNO}
- Key version number
- * last_failed {KADM5_LAST_FAILED}
- Time (in seconds since the Epoch) of the last failed AS_REQ for
this principal. This attribute is read-only, so
KADM5_LAST_FAILED is not set automatically. - * last_pwd_change {KADM5_LAST_PWD_CHANGE}
- Time (in seconds since the Epoch) of the last password change
for this principal. This attribute is read-only, so
KADM5_LAST_PWD_CHANGE is not set automatically. - * last_success {KADM5_LAST_SUCCESS}
- Time (in seconds since the Epoch) of the last successful AS_REQ
for this principal. This attribute is read-only, so
KADM5_LAST_SUCCESS is not set automatically. - * mask Mask (see above)
- * max_life {KADM5_MAX_LIFE}
- maximum lifetime in seconds of any Kerberos ticket issued to
this principal - * max_renewable_life {KADM5_MAX_RLIFE}
- maximum renewable lifetime in seconds of any Kerberos ticket
issued to this principal - * mod_date {KADM5_MOD_TIME}
- Time (in seconds since the Epoch) this principal was last
modified. This attribute is read-only, so KADM5_MOD_TIME is
not set automatically. - * mod_name {KADM5_MOD_NAME}
- Kerberos principal (Authen::Krb5::Principal, see
Authen::Krb5(3)) that last modified this principal. This
attribute is read-only, so KADM5_MOD_NAME is not set
automatically. - * policy {KADM5_POLICY}
- Name of policy that affects this principal if KADM5_POLICY is
set in aux_attributes - * policy_clear {KADM5_POLICY_CLR}
- Not really an attribute--disables the current policy for this
principal. This method doesn't return anything. - * princ_expire_time {KADM5_PRINC_EXPIRE_TIME}
- Expire time (in seconds since the Epoch) of the principal
- * principal {KADM5_PRINCIPAL}
- Kerberos principal itself (Authen::Krb5::Principal, see Authen::Krb5(3))
- * pw_expiration {KADM5_PW_EXPIRATION}
- Expire time (in seconds since the Epoch) of the principal's
password - Operations
- To perform kadmin operations (addprinc, delprinc, etc.), we first
construct an object of the class Authen::Krb5::Admin, which contains a server handle. Then we use object methods to perform the operations
using that handle. - In the following synopses, parameter types are indicated by their names
as follows:
$error Kerberos 5 error code
$kadm5 Authen::Krb5::Admin
$kadm5_config Authen::Krb5::Admin::Config
$kadm5_pol Authen::Krb5::Admin::Policy
$kadm5_princ Authen::Krb5::Admin::Principal
$krb5_ccache Authen::Krb5::Ccache
$krb5_princ Authen::Krb5::Principal
$success TRUE if if the call succeeeded, undef otherwise - Everything else is an unblessed scalar value (or an array of them)
inferable from context. - Parameters surrounded by square brackets ([]s) are each optional.
- Constructors
- Each of the following constructors authenticates as $client to
the admin server $service, which defaults to
KADM5_ADMIN_SERVICE if undef. An undefined value for
$kadm5_config will cause the interface to infer the
configuration from the Kerberos 5 profile (/etc/krb5.conf by default). - * $kadm5 = Authen::Krb5::Admin->init_with_creds($client,
$krb5_ccache[, $service, $kadm5_config]) - Authenticate using the credentials cached in $krb5_ccache.
- * $kadm5 = Authen::Krb5::Admin->init_with_password($client[, $password, $service, $kadm5_config])
- Authenticate with $password.
- * $kadm5 = Authen::Krb5::Admin->init_with_skey($client[, $keytab_file, $service, $kadm5_config])
- Authenticate using the keytab stored in $keytab_file. If
$keytab_file is undef, the default keytab is used. - Principal Operations
* $success = $kadm5->chpass_principal($krb5_princ, $password) - Change the password of $krb5_princ to $password.
- * $success = $kadm5->create_principal($kadm5_princ[, $password])
- Insert $kadm5_princ into the database, optionally setting its
password to the string in $password. Clears KADM5_POLICY_CLR
and KADM5_FAIL_AUTH_COUNT. - * $success = $kadm5->delete_principal($krb5_princ)
- Delete the principal represented by $krb5_princ from the
database. - * $kadm5_princ = $kadm5->get_principal($krb5_princ[, $mask])
- Retrieve the Authen::Krb5::Admin::Principal object for the
principal $krb5_princ from the database. Use
KADM5_PRINCIPAL_NORMAL_MASK to retrieve all of the useful
attributes. - * @names = $kadm5->get_principals([$expr])
- Retrieve a list of principal names matching the glob pattern
$expr. In the absence of $expr, retrieve the list of all
principal names. - * $success = $kadm5->modify_principal($kadm5_princ)
- Modify $kadm5_princ in the database. The principal to modify
is determined by "$kadm5_princ->principal", and the rest of the writable parameters will be modified accordingly. Clears
KADM5_PRINCIPAL. - * @keys = $kadm5->randkey_principal($krb5_princ)
- Randomize the principal in the database represented by
$krb5_princ and return Authen::Krb5::Keyblock objects. - * $success = $kadm5->rename_principal($krb5_princ_from, $krb5_princ_to)
- Change the name of the principal from $krb5_princ_from to
$krb5_princ_to. - Policy Operations
* $success = $kadm5->create_policy($kadm5_pol) - Insert $kadm5_pol into the database.
- * $success = $kadm5->delete_policy($name)
- Delete the policy named $name from the database.
- * $kadm5_pol = $kadm5->get_policy([$name])
- Retrieve the Authen::Krb5::Admin::Policy object for the policy named $name from the database.
- * @names = $kadm5->get_policies([$expr])
- Retrieve a list of policy names matching the glob pattern
$expr. In the absence of $expr, retrieve the list of all
policy names. - * $success = $kadm5->modify_policy($kadm5_pol)
- Modify $kadm5_pol in the database. The policy to modify is
determined by "$kadm5_pol-"name>,(and the rest of the writable) parameters will be modified accordingly. Clears KADM5_POLICY. - Other Methods
* $magic_value = Authen::Krb5::Admin::error [$error] - Return value that acts like $! (see perlvar(1)) for the most
recent Authen::Krb5::Admin call. With error code $error,
return the error message corresponding to that error code. - * $privs = $kadm5->get_privs
- Return a bitfield representing the kadmin privileges a
principal has, as follows:
get KADM5_PRIV_GET
add KADM5_PRIV_ADD
modify KADM5_PRIV_MODIFY
delete KADM5_PRIV_DELETE
EXAMPLES
See the unit tests included with this software for examlpes. They can
be found in the t/ subdirectory of the distribution.
FILES
krb.conf Kerberos 5 configuration file
BUGS
There is no facility for specifying keysalts for methods like
create_principal and modify_principal. This facility is provided by
the Kerberos 5 API and requires an initialized context. So it probably
makes more sense for AAuutthheenn::::KKrrbb55(3) to handle those functions.
AUTHOR
Andrew J. Korty <ajk@iu.edu>