--- name: "Authen::Krb5::Admin" section: "3pm" platform: "linux" package: "libauthen-krb5-admin-perl" version: "0.17-5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Authen::Krb5::Admin" --- # Authen::Krb5::Admin(3pm) Perl extension for MIT Kerberos 5 admin interface ## 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\_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)](/kadmin/8.md)) - 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. 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)](/perlvar/1.md)) 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 ``` ## 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 **Authen::Krb5(3)** to handle those functions. ## AUTHOR Stephen Quinney \ Author Emeritus: Andrew J. Korty \ ## SEE ALSO [**perl**(1)](/perl/1.md), [**perlvar**(1)](/perlvar/1.md), **Authen::Krb5**(3), **Exporter**(3), [**kadmin**(8)](/kadmin/8.md).