summaryrefslogtreecommitdiff
path: root/perl/Wallet/Kadmin.pm
diff options
context:
space:
mode:
Diffstat (limited to 'perl/Wallet/Kadmin.pm')
-rw-r--r--perl/Wallet/Kadmin.pm66
1 files changed, 49 insertions, 17 deletions
diff --git a/perl/Wallet/Kadmin.pm b/perl/Wallet/Kadmin.pm
index 78b72cd..a06e1e2 100644
--- a/perl/Wallet/Kadmin.pm
+++ b/perl/Wallet/Kadmin.pm
@@ -1,4 +1,4 @@
-# Wallet::Kadmin -- Kadmin module wrapper for the wallet.
+# Wallet::Kadmin -- Kerberos administration API for wallet keytab backend.
#
# Written by Jon Robertson <jonrober@stanford.edu>
# Copyright 2009, 2010 Board of Trustees, Leland Stanford Jr. University
@@ -73,15 +73,16 @@ __END__
##############################################################################
=for stopwords
-Kadmin keytabs keytab Heimdal API kadmind kadmin
+backend Kadmin keytabs keytab Heimdal API kadmind kadmin KDC ENCTYPES
+enctypes enctype Allbery
=head1 NAME
-Wallet::Kadmin - Kadmin module wrapper for wallet keytabs
+Wallet::Kadmin - Kerberos administration API for wallet keytab backend
=head1 SYNOPSIS
- my $kadmin = Wallet::Kadmin->new ();
+ my $kadmin = Wallet::Kadmin->new;
$kadmin->addprinc ("host/shell.example.com");
$kadmin->ktadd ("host/shell.example.com", "aes256-cts-hmac-sha1-96");
my $exists = $kadmin->exists ("host/oldshell.example.com");
@@ -89,21 +90,15 @@ Wallet::Kadmin - Kadmin module wrapper for wallet keytabs
=head1 DESCRIPTION
-Wallet::Kadmin is a wrapper to modules that provide an interface for
-keytab integration with wallet. Each module is meant to interface with a
-specific type of Kerberos implementation, such as MIT Kerberos or Heimdal,
-and provide a standard set of API calls used to interact with that
-implementation's kadmin interface.
+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.
-
-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.
-
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.
@@ -122,8 +117,25 @@ implementation is not recognized or set, die with an error message.
=head1 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.
+
=over 4
+=item addprinc(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.
+
+=item delprinc(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.
+
=item error([ERROR ...])
Returns the error of the last failing operation or undef if no operations
@@ -137,6 +149,12 @@ 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.
+=item exists(PRINCIPAL)
+
+Returns true if the given principal exists in the KDC and C<0> if it
+doesn't. If an error is encountered in checking whether the principal
+exists, exists() returns undef.
+
=item fork_callback(CALLBACK)
If the module has to fork an external process for some reason, such as a
@@ -144,6 +162,20 @@ 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.
+=item ktadd(PRINCIPAL, FILE, ENCTYPES)
+
+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.
+
+ktadd() creates a new keytab for the given principal, storing it in the
+given file and limited to the enctypes supplied. The enctype values must
+be enctype strings recognized by the Kerberos implementation (strings like
+C<aes256-cts-hmac-sha1-96> or C<des-cbc-crc>). Returns true on success
+and false on failure.
+
=back
=head1 SEE ALSO
@@ -155,6 +187,6 @@ available from L<http://www.eyrie.org/~eagle/software/wallet/>.
=head1 AUTHORS
-Jon Robertson <jonrober@stanford.edu>
+Jon Robertson <jonrober@stanford.edu> and Russ Allbery <rra@stanford.edu>
=cut