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.

2 files changed, 25 insertions, 106 deletions

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/>.