| < Wallet::Object::File API | Russ Allbery > Software > wallet | Wallet::Schema API > |
(Keytab object implementation for wallet)
my @name = qw(keytab host/shell.example.com);
my @trace = ($user, $host, time);
my $object = Wallet::Object::Keytab->create (@name, $dbh, @trace);
my $keytab = $object->get (@trace);
$object->destroy (@trace);
Wallet::Object::Keytab is a representation of Kerberos keytab objects in the wallet. It implements the wallet object API and provides the necessary glue to create principals in a Kerberos KDC, create and return keytabs for those principals, and delete them out of Kerberos when the wallet object is destroyed.
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 be created in Kerberos and then a keytab is generated and stored in a file on disk.
This implementation generates a new random key (and hence invalidates all existing keytabs) each time the keytab is retrieved with the get() method.
To use this object, several configuration parameters must be set. See Wallet::Config(3) for details on those configuration parameters and information about how to set wallet configuration.
This object mostly inherits from Wallet::Object::Base. See the documentation for that class for all generic methods. Below are only those methods that are overridden or behave specially for this implementation.
Sets or retrieves a given object attribute. The following attributes are supported:
Restricts the generated keytab to a specific set of encryption types. The
values of this attribute must be enctype strings recognized by Kerberos
(strings like aes256-cts or des-cbc-crc). Encryption types
must also be present in the list of supported enctypes stored in the
database database or the attr() method will reject them. Note that the
salt should not be included; since the salt is irrelevant for keytab keys,
it will always be set to normal by the wallet.
If this attribute is set, the specified enctype list will be passed to ktadd when get() is called for that keytab. If it is not set, the default set in the KDC will be used.
This attribute is ignored if the unchanging flag is set on a
keytab. Keytabs retrieved with unchanging set will contain all
keys present in the KDC for that Kerberos principal and therefore may
contain different enctypes than those requested by this attribute.
Sets the external systems to which the key of a given principal is
synchronized. The only supported value for this attribute is
kaserver, which says to synchronize the key with an AFS Kerberos v4
kaserver.
If this attribute is set on a keytab, whenever get() is called for that
keytab, the new DES key will be extracted from that keytab and set in the
configured AFS kaserver. The Kerberos v4 principal name will be the same
as the Kerberos v5 principal name except that the components are separated
by . instead of /; the second component is truncated after
the first . if the first component is one of host,
ident, imap, pop, or smtp; and the first
component is rcmd if the Kerberos v5 principal component is
host. The principal name must not contain more than two
components.
If this attribute is set, calling destroy() will also destroy the principal from the AFS kaserver, with a principal mapping determined as above.
If no other arguments besides ATTRIBUTE are given, returns the values of that attribute, if any, as a list. On error, returns the empty list. To distinguish between an error and an empty return, call error() afterwards. It is guaranteed to return undef unless there was an error.
If other arguments are given, sets the given ATTRIBUTE values to VALUES, which must be a reference to an array (even if only one value is being set). Pass a reference to an empty array to clear the attribute values. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used.
This is a class method and should be called on the Wallet::Object::Keytab
class. It creates a new object with the given TYPE and NAME (TYPE is
normally keytab and must be for the rest of the wallet system to
use the right class, but this module doesn't check for ease of
subclassing), using DBH as the handle to the wallet metadata database.
PRINCIPAL, HOSTNAME, and DATETIME are stored as history information.
PRINCIPAL should be the user who is creating the object. If DATETIME
isn't given, the current time is used.
When a new keytab object is created, the Kerberos principal designated by
NAME is also created in the Kerberos realm determined from the wallet
configuration. If the principal already exists, create() still succeeds
(so that a previously unmanaged principal can be imported into the
wallet). Otherwise, if the Kerberos principal could not be created,
create() fails. The principal is created with the -randkey option
to randomize its keys. NAME must not contain the realm; instead, the
KEYTAB_REALM configuration variable should be set. See Wallet::Config(3)
for more information.
If create() fails, it throws an exception.
Destroys a keytab object by removing it from the database and deleting the principal out of Kerberos. If deleting the principal fails, destroy() fails, but destroy() succeeds if the principal didn't exist when it was called (so that it can be used to clean up stranded entries). Returns true on success and false on failure. The caller should call error() to get the error message after a failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used.
Retrieves a keytab for this object and returns the keytab data or undef on
error. The caller should call error() to get the error message if get()
returns undef. The keytab is created with ktadd, invalidating any
existing keytabs for that principal, unless the unchanging flag is set on
the object. PRINCIPAL, HOSTNAME, and DATETIME are stored as history
information. PRINCIPAL should be the user who is downloading the keytab.
If DATETIME isn't given, the current time is used.
If the configuration variable $KEYTAB_AFS_DESTROY is set and the
sync attribute is not set to kaserver, calling get() on a
keytab object will cause the corresponding Kerberos v4 principal to be
destroyed. This variable is not set by default.
The keytab is created in this file using ktadd and then read into
memory. KEYTAB_TMP is set in the wallet configuration, and <pid> is the
process ID of the current process. The file is unlinked after being read.
Currently, this implementation only supports MIT Kerberos and needs modifications to support Heimdal. It calls an external kadmin program rather than using a native Perl module and therefore requires kadmin be installed and parses its output. It may miss some error conditions if the output of kadmin ever changes.
Only one Kerberos realm is supported for a given wallet implementation and all keytab objects stored must be in that realm. Keytab names in the wallet database do not have realm information.
kadmin(8), Wallet::Config(3), Wallet::Object::Base(3), wallet-backend(8)
This module is part of the wallet system. The current version is available from <http://www.eyrie.org/~eagle/software/wallet/>.
Russ Allbery <rra@stanford.edu>
| < Wallet::Object::File API | Russ Allbery > Software > wallet | Wallet::Schema API > |