Move Wallet::Kadmin documentation into the parent class

Rather than duplicating the API documentation in both ::Heimdal and
::MIT, move it into Wallet::Kadmin and just reference that from the
subclasses.  Add documentation for exists(), since that's part of the
public API.  Move a few methods around and fix a few other minor
documentation differences.

3 files changed, 74 insertions, 123 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
diff --git a/perl/Wallet/Kadmin/Heimdal.pm b/perl/Wallet/Kadmin/Heimdal.pm
index 2d393e2..d59b33c 100644
--- a/perl/Wallet/Kadmin/Heimdal.pm
+++ b/perl/Wallet/Kadmin/Heimdal.pm
@@ -1,4 +1,4 @@
-# Wallet::Kadmin::Heimdal -- Heimdal Kadmin interactions for the wallet.
+# Wallet::Kadmin::Heimdal -- Wallet Kerberos administration API for Heimdal.
 #
 # Written by Jon Robertson <jonrober@stanford.edu>
 # Copyright 2009, 2010 Board of Trustees, Leland Stanford Jr. University
@@ -204,15 +204,15 @@ __END__
 ##############################################################################
 
 =for stopwords
-keytabs keytab kadmin enctypes API ENCTYPES enctype Allbery Heimdal
+keytabs keytab kadmin KDC API Allbery Heimdal
 
 =head1 NAME
 
-Wallet::Kadmin::Heimdal - Heimdal admin interactions for wallet keytabs
+Wallet::Kadmin::Heimdal - Wallet Kerberos administration API for Heimdal
 
 =head1 SYNOPSIS
 
-    my $kadmin = Wallet::Kadmin::MIT->new ();
+    my $kadmin = Wallet::Kadmin::Heimdal->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");
@@ -220,55 +220,18 @@ Wallet::Kadmin::Heimdal - Heimdal admin interactions for wallet keytabs
 
 =head1 DESCRIPTION
 
-Wallet::Kadmin::Heimdal is an interface for keytab integration with the
-wallet, specifically for using kadmin to create, delete, and add enctypes
-to keytabs.  It implements the wallet kadmin API and provides the
-necessary glue to Heimdal installs for each of these functions, while
-allowing the wallet to keep the details of what type of Kerberos
-installation is being used abstracted.
-
-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.
+Wallet::Kadmin::Heimdal implements the Wallet::Kadmin API for Heimdal,
+providing an interface to create and delete principals and create keytabs.
+It provides the API documented in Wallet::Kadmin(3) for a Heimdal KDC.
 
 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.
 
-=head1 METHODS
-
-=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, or throws an error if there was a failure in adding the
-principal.  If the principal already exists, return true as we are
-bringing our expectations in line with reality.
-
-=item addprinc(PRINCIPAL)
-
-Removes a principal with the given name.  Returns true on success, or
-throws an error if there was a failure in removing the principal.  If the
-principal does not exist, return true as we are bringing our expectations
-in line with reality.
-
-=item ktadd(PRINCIPAL, FILE, ENCTYPES)
-
-Creates a new keytab for the given principal, as the given file, limited
-to the enctypes supplied.  The enctype values must be enctype strings
-recognized by Kerberos (strings like C<aes256-cts-hmac-sha1-96> or
-C<des-cbc-crc>).  An error is thrown on failure or if the creation fails,
-otherwise true is returned.
-
-=back
-
 =head1 SEE ALSO
 
-kadmin(8), Wallet::Config(3), Wallet::Object::Keytab(3), wallet-backend(8)
+kadmin(8), Wallet::Config(3), Wallet::Kadmin(3),
+Wallet::Object::Keytab(3), wallet-backend(8)
 
 This module is part of the wallet system.  The current version is
 available from L<http://www.eyrie.org/~eagle/software/wallet/>.
diff --git a/perl/Wallet/Kadmin/MIT.pm b/perl/Wallet/Kadmin/MIT.pm
index 9dc101e..1ab8b1d 100644
--- a/perl/Wallet/Kadmin/MIT.pm
+++ b/perl/Wallet/Kadmin/MIT.pm
@@ -1,4 +1,4 @@
-# Wallet::Kadmin::MIT -- MIT Kadmin interactions for the wallet.
+# Wallet::Kadmin::MIT -- Wallet Kerberos administration API for MIT.
 #
 # Written by Russ Allbery <rra@stanford.edu>
 # Pulled into a module by Jon Robertson <jonrober@stanford.edu>
@@ -28,16 +28,6 @@ use Wallet::Kadmin ();
 $VERSION = '0.02';
 
 ##############################################################################
-# Utility functions
-##############################################################################
-
-# Set a callback to be called for forked kadmin processes.
-sub fork_callback {
-    my ($self, $callback) = @_;
-    $self->{fork_callback} = $callback;
-}
-
-##############################################################################
 # kadmin Interaction
 ##############################################################################
 
@@ -99,6 +89,12 @@ sub kadmin {
 # Public interfaces
 ##############################################################################
 
+# Set a callback to be called for forked kadmin processes.
+sub fork_callback {
+    my ($self, $callback) = @_;
+    $self->{fork_callback} = $callback;
+}
+
 # Check whether a given principal already exists in Kerberos.  Returns true if
 # so, false otherwise.  Returns undef if kadmin fails, with the error already
 # set by kadmin.
@@ -196,10 +192,6 @@ sub delprinc {
     return 1;
 }
 
-##############################################################################
-# Documentation
-##############################################################################
-
 # Create a new MIT kadmin object.  Very empty for the moment, but later it
 # will probably fill out if we go to using a module rather than calling
 # kadmin directly.
@@ -218,15 +210,15 @@ __END__
 ##############################################################################
 
 =for stopwords
-keytabs keytab kadmin enctype enctypes API ENCTYPES Allbery
+keytabs keytab kadmin KDC API Allbery
 
 =head1 NAME
 
-Wallet::Kadmin::MIT - MIT admin interactions for wallet keytabs
+Wallet::Kadmin::MIT - Wallet Kerberos administration API for MIT
 
 =head1 SYNOPSIS
 
-    my $kadmin = Wallet::Kadmin::MIT->new ();
+    my $kadmin = Wallet::Kadmin::MIT->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");
@@ -234,52 +226,15 @@ Wallet::Kadmin::MIT - MIT admin interactions for wallet keytabs
 
 =head1 DESCRIPTION
 
-Wallet::Kadmin::MIT is an interface for keytab integration with the
-wallet, specifically for using kadmin to create, delete, and add enctypes
-to keytabs.  It implements the wallet kadmin API and provides the
-necessary glue to MIT Kerberos installs for each of these functions, while
-allowing the wallet to keep the details of what type of Kerberos
-installation is being used abstracted.
-
-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.
+Wallet::Kadmin::MIT implements the Wallet::Kadmin API for MIT Kerberos,
+providing an interface to create and delete principals and create keytabs.
+It provides the API documented in Wallet::Kadmin(3) for an MIT Kerberos
+KDC.
 
 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.
 
-=head1 METHODS
-
-=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, or throws an error if there was a failure in adding the
-principal.  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
-throws an error if there was a failure in removing the principal.  If the
-principal does not exist, return true as we are bringing our expectations
-in line with reality.
-
-=item ktadd(PRINCIPAL, FILE, ENCTYPES)
-
-Creates a new keytab for the given principal, as the given file, limited
-to the enctypes supplied.  The enctype values must be enctype strings
-recognized by Kerberos (strings like C<aes256-cts-hmac-sha1-96> or
-C<des-cbc-crc>).  An error is thrown on failure or if the creation fails,
-otherwise true is returned.
-
-=back
-
 =head1 LIMITATIONS
 
 Currently, this implementation calls an external B<kadmin> program rather
@@ -289,7 +244,8 @@ output of B<kadmin> ever changes.
 
 =head1 SEE ALSO
 
-kadmin(8), Wallet::Config(3), Wallet::Object::Keytab(3), wallet-backend(8)
+kadmin(8), Wallet::Config(3), Wallet::Kadmin(3),
+Wallet::Object::Keytab(3), wallet-backend(8)
 
 This module is part of the wallet system.  The current version is
 available from L<http://www.eyrie.org/~eagle/software/wallet/>.