Admin(3pm)

📦

version 0.17 · 4 versions

0.17 · debian trixie, ubuntu resolute (latest)
0.17 · ubuntu stonking
0.17 · ubuntu jammy
0.17 · debian bookworm

✨ Admin(3pm) — User Contributed Perl Documentation ✨

okay so bestie, this is Admin(3pm), part 1 of 2, and we're gonna get you fluent in the Authen::Krb5::Admin module. 💖

💖 NAME 💖

Authen::Krb5::Admin — Perl extension for MIT Kerberos 5 admin interface ✨

🌸 SYNOPSIS 🌸

         use Authen::Krb5::Admin;
         use Authen::Krb5::Admin qw(:constants);

🦋 DESCRIPTION 🦋

okay so the Authen::Krb5::Admin Perl module is literally an object-oriented interface to the Kerberos 5 admin server. Right now only MIT KDCs are supported, but the author is envisioning seamless integration with other KDCs. periodt.

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 doing any kadmin operations, bestie, the programmer has to construct objects to represent the entities being manipulated. Each of these classes:

        Authen::Krb5::Admin::Config
        Authen::Krb5::Admin::Key
        Authen::Krb5::Admin::Policy
        Authen::Krb5::Admin::Principal

has a constructor new that takes no arguments (except for the class name). The new object can be populated using accessor methods, and each one is named for the C struct element it represents. Methods always return the current value of the attribute, except for policy_clear, which returns nothing. If a value is provided, the attribute gets set to that value, and the new value is returned. slay.

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. no cap.

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. iconic.

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. the way that works is lowkey wild but okay.

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. periodt.

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. iykyk.

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);

🦋 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. 💖

okay so before we go any further — any parameter wrapped up in square brackets ([]) is optional, bestie. Every single one. That's the vibe check for this whole page. 💅

Constructors 🎀

Each of these lil constructors authenticates as $client against the admin server $service, which defaults to KADM5_ADMIN_SERVICE if it's undef. And if $kadm5_config is undefined? The interface just infers the config from the Kerberos 5 profile (/etc/krb5.conf by default). Easy. ✨

$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. And if $keytab_file is undef? You get the default keytab. Slay.

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. This one 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. bye bestie 👋
$kadm5_princ = $kadm5->get_principal($krb5_princ[, $mask]) — Retrieve the Authen::Krb5::Admin::Principal object for the principal $krb5_princ from the database. Pro tip: use KADM5_PRINCIPAL_NORMAL_MASK to grab all of the useful attributes. 🌸
@names = $kadm5->get_principals([$expr]) — Retrieve a list of principal names matching the glob pattern $expr. If there's no $expr, you get 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 get modified accordingly. This one clears KADM5_PRINCIPAL.
@keys = $kadm5->randkey_principal($krb5_princ) — Randomize the principal in the database represented by $krb5_princ, and it hands you back 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. glow-up, fr fr ✨

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. No $expr? You get 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 get modified accordingly. This one clears KADM5_POLICY.

Other Methods 💫

$magic_value = Authen::Krb5::Admin::error [$error] — Returns a value that acts like $! (go peek at perlvar(1) if you don't know her) for the most recent Authen::Krb5::Admin call. Pass an error code $error and it returns 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. no cap 🧮
$privs = $kadm5->get_privs — Returns a bitfield representing the kadmin privileges a principal has, like so:

get     KADM5_PRIV_GET
add     KADM5_PRIV_ADD
modify  KADM5_PRIV_MODIFY
delete  KADM5_PRIV_DELETE

✨ EXAMPLES ✨

Want examples? Go look at the unit tests that ship with this software — they're chillin' in the t/ subdirectory of the distribution. 📁

📂 FILES 📂

krb.conf — Kerberos 5 configuration file

💀 BUGS 💀

Okay so here's the tea: there is no facility for specifying keysalts for methods like create_principal and modify_principal. That facility is provided by the Kerberos 5 API and it needs an initialized context. So honestly it probably makes more sense for Authen::Krb5(3) to handle those functions. not me calling out the API design 😭

👑 AUTHOR 👑

Stephen Quinney <squinney@inf.ed.ac.uk>

Author Emeritus: Andrew J. Korty <ajk@iu.edu>

and that's the whole page, bestie 🫶 this one's from perl v5.40.1, dated 2025-04-11, and it lives at Admin(3pm). go forth and admin responsibly 💖✨🎀

📦 where this page comes from

debian trixie: libauthen-krb5-admin-perl 0.17-5 · BSD-2-Clause
ubuntu resolute: libauthen-krb5-admin-perl 0.17-5 · BSD-2-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms