oracular (3) Wallet::Kadmin.3pm.gz

NAME

       Wallet::Kadmin - Kerberos administration API for wallet keytab backend

SYNOPSIS

           my $kadmin = Wallet::Kadmin->new;
           $kadmin->create ('host/foo.example.com');
           my $data = $kadmin->keytab_rekey ('host/foo.example.com',
                                             'aes256-cts-hmac-sha1-96');
           $data = $kadmin->keytab ('host/foo.example.com');
           my $exists = $kadmin->exists ('host/oldshell.example.com');
           $kadmin->destroy ('host/oldshell.example.com') if $exists;

DESCRIPTION

       Wallet::Kadmin is a wrapper and base class for modules that provide an interface for wallet to do
       Kerberos administration, specifically create and delete principals and create keytabs for a principal.
       Each subclass administers a specific type of Kerberos implementation, such as MIT Kerberos or Heimdal,
       providing a standard set of API calls used to interact with that implementation's kadmin interface.

       The class uses Wallet::Config to find which type of kadmin interface is in use and then returns an object
       to use for interacting with that interface.  See "KEYTAB OBJECT CONFIGURATION" in Wallet::Config for
       details on how to configure this module.

CLASS METHODS

       new()
           Finds the proper Kerberos implementation and calls the new() constructor for that implementation's
           module, returning the resulting object.  If the implementation is not recognized or set, die with an
           error message.

INSTANCE METHODS

       These methods are provided by any object returned by new(), regardless of the underlying kadmin
       interface.  They are implemented by the child class appropriate for the configured Kerberos
       implementation.

       create(PRINCIPAL)
           Adds a new principal with a given name.  The principal is created with a random password, and any
           other flags set by Wallet::Config.  Returns true on success and false on failure.  If the principal
           already exists, return true as we are bringing our expectations in line with reality.

       destroy(PRINCIPAL)
           Removes a principal with the given name.  Returns true on success or false on failure.  If the
           principal does not exist, return true as we are bringing our expectations in line with reality.

       error([ERROR ...])
           Returns the error of the last failing operation or undef if no operations have failed.  Callers
           should call this function to get the error message after an undef return from any other instance
           method.

           For the convenience of child classes, this method can also be called with one or more error strings.
           If so, those strings are concatenated together, trailing newlines are removed, any text of the form
           " at \S+ line \d+\.?" at the end of the message is stripped off, and the result is stored as the
           error.  Only child classes should call this method with an error string.

       exists(PRINCIPAL)
           Returns true if the given principal exists in the KDC and 0 if it doesn't.  If an error is
           encountered in checking whether the principal exists, exists() returns undef.

       fork_callback(CALLBACK)
           If the module has to fork an external process for some reason, such as a kadmin command-line client,
           the sub CALLBACK will be called in the child process before running the program.  This can be used
           to, for example, properly clean up shared database handles.

       keytab(PRINCIPAL)
           keytab() creates a keytab for the given principal, storing it in the given file.  A keytab is an on-
           disk store for the key or keys for a Kerberos principal.  Keytabs are used by services to verify
           incoming authentication from clients or by automated processes that need to authenticate to Kerberos.
           To create a keytab, the principal has to have previously been created in the Kerberos KDC.  Returns
           the keytab as binary data on success and undef on failure.

       keytab_rekey(PRINCIPAL [, ENCTYPE ...])
           Like keytab(), but randomizes the key for the principal before generating the keytab and writes it to
           the given file.  This will invalidate any existing keytabs for that principal.  This method can also
           limit the encryption types of the keys for that principal via the optional ENCTYPE arguments.  The
           enctype values must be enctype strings recognized by the Kerberos implementation (strings like
           "aes256-cts-hmac-sha1-96" or "des-cbc-crc").  If none are given, the KDC defaults will be used.
           Returns the keytab as binary data on success and undef on failure.

       The following methods are utility methods to aid with child class implementation and should only be
       called by child classes.

       read_keytab(FILE)
           Reads the contents of the keytab stored in FILE into memory and returns it as binary data.  On
           failure, returns undef and sets the object error.

SEE ALSO

       kadmin(8), Wallet::Config(3), Wallet::Object::Keytab(3), wallet-backend(8)

       This module is part of the wallet system.  The current version is available from
       <https://www.eyrie.org/~eagle/software/wallet/>.

AUTHORS

       Jon Robertson <jonrober@stanford.edu> and Russ Allbery <eagle@eyrie.org>