Provided by: libauthen-krb5-admin-perl_0.17-1build1_amd64 bug

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

       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)) 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 <squinney@inf.ed.ac.uk>

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

SEE ALSO

       perl(1), perlvar(1), Authen::Krb5(3), Exporter(3), kadmin(8).