Add documentation of the Active Directory support

Also remove some configuration checks that aren't required, and
unify handling of some configuration options.

4 files changed, 108 insertions, 30 deletions

diff --git a/NEWS b/NEWS
index aa9cf47..9d5b1a6 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,18 @@
 
 wallet 1.3 (unreleased)
 
+    This release adds initial, experimental support for using Active
+    Directory as the KDC for keytab creation.  The interface to Active
+    Directory uses a combination of direct LDAP queries and the msktutil
+    utility.  This version does not support the wallet unchanging flag.
+    Unchanging requires that a keytab be retrieved without changing the
+    password/kvno which is not supported by msktutil.  Active Directory
+    can be selected by setting KEYTAB_KRBTYPE to AD in the wallet
+    configuration.  Multiple other configuration options must also be set;
+    see Wallet::Config for more information and README for the additional
+    Perl modules required.  Thanks to Bill MacAllister for the
+    implementation.
+
     A new ACL type, nested (Wallet::ACL::Nested), is now supported.  The
     identifier of this ACL names another ACL, and access is granted if
     that ACL would grant access.  This lets one combine multiple other
@@ -63,13 +75,6 @@ wallet 1.3 (unreleased)
 
     Displays of ACLs and ACL entries are now sorted correctly.
 
-    Initial support for using Active Directory as the KDC for keytab
-    creation.  The interface to Active Directory uses a combination of
-    direct LDAP queries and the msktutil utility.  This version does
-    not support the wallet unchanging flag.  Unchanging requires that
-    a keytab be retrieved without changing the password/kvno which is
-    not supported by msktutil.
-
 wallet 1.2 (2014-12-08)
 
     The duo object type has been split into several sub-types, each for a
diff --git a/README b/README
index 75b1224..200f0eb 100644
--- a/README
+++ b/README
@@ -91,12 +91,15 @@ REQUIREMENTS
   on CPAN for older versions.
 
   The keytab support in the wallet server supports either Heimdal or MIT
-  Kerberos KDCs.  The Heimdal support requires the Heimdal::Kadm5 Perl
-  module.  The MIT Kerberos support requires the MIT Kerberos kadmin
-  client program be installed.  In either case, wallet also requires that
-  the wallet server have a keytab for a principal with appropriate access
-  to create, modify, and delete principals from the KDC (as configured in
-  kadm5.acl on an MIT Kerberos KDC).
+  Kerberos KDCs and has exeprimental support for Active Directory.  The
+  Heimdal support requires the Heimdal::Kadm5 Perl module.  The MIT
+  Kerberos support requires the MIT Kerberos kadmin client program be
+  installed.  The Active Directory support requires the Net::LDAP,
+  Authen::SASL, and IPC::Run Perl modules and the msktutil client program.
+  In all cases, wallet also requires that the wallet server have a keytab
+  for a principal with appropriate access to create, modify, and delete
+  principals from the KDC (as configured in kadm5.acl on an MIT Kerberos
+  KDC).
 
   To support the unchanging flag on keytab objects with an MIT Kerberos
   KDC, the Net::Remctl Perl module (shipped with remctl) must be installed
@@ -339,8 +342,12 @@ THANKS
   security models.
 
   To Jon Robertson for the refactoring of Wallet::Kadmin, Heimdal support,
-  many of the wallet server-side reports, and the initial wallet-rekey
-  implementation.
+  many of the wallet server-side reports, the initial wallet-rekey
+  implementation, and lots of work on object and ACL types including
+  nested ACLs.
+
+  To Bill MacAllister for Wallet::Kadmin::AD and the implementation of
+  keytab object types backed by Active Directory.
 
 LICENSE
 
diff --git a/perl/lib/Wallet/Config.pm b/perl/lib/Wallet/Config.pm
index e8bc00c..f4ebc0f 100644
--- a/perl/lib/Wallet/Config.pm
+++ b/perl/lib/Wallet/Config.pm
@@ -319,7 +319,8 @@ modify, inspect, and delete any principals that should be managed by the
 wallet.  (In MIT Kerberos F<kadm5.acl> parlance, this is C<admci>
 privileges.)
 
-KEYTAB_FILE must be set to use keytab objects.
+KEYTAB_FILE must be set to use keytab objects with any backend other than
+Active Directory.
 
 =cut
 
@@ -336,16 +337,18 @@ is generally pointless and may interact poorly with the way C<addprinc
 -randkey> works when third-party add-ons for password strength checking
 are used.)
 
+This option is ignored when using Active Directory.
+
 =cut
 
 our $KEYTAB_FLAGS = '-clearpolicy';
 
 =item KEYTAB_HOST
 
-Specifies the host on which the kadmin service is running.  This setting
-overrides the C<admin_server> setting in the [realms] section of
-F<krb5.conf> and any DNS SRV records and allows the wallet to run on a
-system that doesn't have a Kerberos configuration for the wallet's realm.
+Specifies the host on which the kadmin or Active Directory service is running.
+This setting overrides the C<admin_server> setting in the [realms] section of
+F<krb5.conf> and any DNS SRV records and allows the wallet to run on a system
+that doesn't have a Kerberos configuration for the wallet's realm.
 
 =cut
 
@@ -357,13 +360,15 @@ The path to the B<kadmin> command-line client.  The default value is
 C<kadmin>, which will cause the wallet to search for B<kadmin> on its
 default PATH.
 
+This option is ignored when using Active Directory.
+
 =cut
 
 our $KEYTAB_KADMIN = 'kadmin';
 
 =item KEYTAB_KRBTYPE
 
-The Kerberos KDC implementation type, either C<Heimdal> or C<MIT>
+The Kerberos KDC implementation type, chosen from C<AD>, C<Heimdal>, or C<MIT>
 (case-insensitive).  KEYTAB_KRBTYPE must be set to use keytab objects.
 
 =cut
@@ -375,9 +380,9 @@ our $KEYTAB_KRBTYPE;
 The principal whose key is stored in KEYTAB_FILE.  The wallet will
 authenticate as this principal to the kadmin service.
 
-KEYTAB_PRINCIPAL must be set to use keytab objects, at least until
-B<kadmin> is smart enough to use the first principal found in the keytab
-it's using for authentication.
+KEYTAB_PRINCIPAL must be set to use keytab objects unless Active Directory is
+the backend, at least until B<kadmin> is smart enough to use the first
+principal found in the keytab it's using for authentication.
 
 =cut
 
@@ -391,7 +396,7 @@ installation and the keytab object names are stored without realm.
 KEYTAB_REALM is added when talking to the KDC via B<kadmin>.
 
 KEYTAB_REALM must be set to use keytab objects.  C<ktadd> doesn't always
-default to the local realm.
+default to the local realm and the Active Directory integration requires it.
 
 =cut
 
@@ -414,6 +419,69 @@ our $KEYTAB_TMP;
 
 =back
 
+The following parameters are specific to generating keytabs from Active
+Directory (KEYTAB_KRBTYPE is set to C<AD>).
+
+=over 4
+
+=item AD_CACHE
+
+Specifies the ticket cache to use when manipulating Active Directory objects.
+The ticket cache must be for a principal able to bind to Active Directory and
+run B<msktutil>.
+
+AD_CACHE must be set to use Active Directory support.
+
+=cut
+
+our $AD_CACHE;
+
+=item AD_COMPUTER_DN
+
+The LDAP base DN for computer objects inside Active Directory.  All keytabs of
+the form host/<hostname> will be mapped to objects with a C<samAccountName> of
+the <hostname> portion under this DN.
+
+AD_COMPUTER_DN must be set if using Active Directory as the keytab backend.
+
+=cut
+
+our $AD_COMPUTER_DN;
+
+=item AD_DEBUG
+
+If set to true, asks for some additional debugging information, such as the
+B<msktutil> command, to be logged to syslog.  These debugging messages will be
+logged to the C<local3> facility.
+
+=cut
+
+our $AD_DEBUG = 0;
+
+=item AD_MSKTUTIL
+
+The path to the B<msktutil> command-line client.  The default value is
+C<msktutil>, which will cause the wallet to search for B<msktutil> on its
+default PATH.
+
+=cut
+
+our $AD_MSKTUTIL = 'msktutil';
+
+=item AD_USER_DN
+
+The LDAP base DN for user objects inside Active Directory.  All keytabs of the
+form service/<user> will be mapped to objects with a C<servicePrincipalName>
+matching the wallet object name under this DN.
+
+AD_USER_DN must be set if using Active Directory as the keytab backend.
+
+=cut
+
+our $AD_USER_DN;
+
+=back
+
 =head2 Retrieving Existing Keytabs
 
 Heimdal provides the choice, over the network protocol, of either
diff --git a/perl/lib/Wallet/Kadmin/AD.pm b/perl/lib/Wallet/Kadmin/AD.pm
index 4efc643..97bf2bf 100644
--- a/perl/lib/Wallet/Kadmin/AD.pm
+++ b/perl/lib/Wallet/Kadmin/AD.pm
@@ -130,16 +130,14 @@ sub get_ad_keytab {
 # that error output.
 sub msktutil {
     my ($self, $args_ref) = @_;
-    unless (defined($Wallet::Config::KEYTAB_PRINCIPAL)
-        and defined($Wallet::Config::KEYTAB_FILE)
+    unless (defined($Wallet::Config::KEYTAB_HOST)
         and defined($Wallet::Config::KEYTAB_REALM))
     {
         die "keytab object implementation not configured\n";
     }
-    unless (defined($Wallet::Config::AD_SERVER)
+    unless (defined($Wallet::Config::AD_CACHE)
         and defined($Wallet::Config::AD_COMPUTER_DN)
-        and defined($Wallet::Config::AD_USER_DN)
-        and defined($Wallet::Config::AD_KEYTAB_BUCKET))
+        and defined($Wallet::Config::AD_USER_DN))
     {
         die "Active Directory support not configured\n";
     }