Authen::Krb5::Admin - Perl extension for MIT Kerberos 5 admin interface
use Authen::Krb5::Admin;
use Authen::Krb5::Admin qw(:constants);
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
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_max_fail {KADM5_PW_MAX_FAILURE}
- The maximum allowed number of attempts before a
lockout.
- pw_failcnt_interval {KADM5_PW_FAILURE_COUNT_INTERVAL}
- The period after which the bad preauthentication count will
be reset.
- pw_lockout_duration {KADM5_PW_LOCKOUT_DURATION}
- The period in which lockout is enforced; a duration of zero
means that the principal must be manually unlocked.
- 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
- db_args [@ARGS]
- When called without any @ARGS, returns the list of
arguments that will be passed into the underlying database, as with
"addprinc -x" in "kadmin". If @ARGS is non-empty, it
will replace any database arguments, which will then be returned, like
this:
my @old = $principal->db_args;
# -or-
my @old = $principal->db_args(@new);
# The RPC call will ignore the tail data unless
# you set this flag:
$principal->mask($principal->mask | KADM5_TL_DATA);
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.
- $error_code = Authen::Krb5::Admin::error_code
- Returns the value of the error code for the most recent
Authen::Krb5::Admin call as a simple integer.
- $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
See the unit tests included with this software for examlpes. They can be found
in the
t/ subdirectory of the distribution.
krb.conf Kerberos 5 configuration file
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
Authen::Krb5(3) to handle those
functions.
Stephen Quinney <
[email protected]>
Author Emeritus: Andrew J. Korty <
[email protected]>
perl(1),
perlvar(1),
Authen::Krb5(3),
Exporter(3),
kadmin(8).