Updated documentation for ktadd/ktremove commands.

Added usage example to  ktutil document.

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25107 dc483132-0cff-0310-8789-dd5450dbe970

3 files changed, 86 insertions, 67 deletions

diff --git a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
index d3f4d000c..0fd7ea9de 100644
--- a/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
+++ b/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
@@ -201,7 +201,7 @@ add_principal
 
               Aliases::
 
-                        addprinc and ank.  
+                        addprinc ank
 
               The options are:
 
@@ -369,9 +369,9 @@ modify_principal
 
                  .. note:: This command requires the *modify* privilege.  
 
-              Alias::
+              Alias:: 
 
-                     modprinc
+                        modprinc
 
               The options are:
 
@@ -750,21 +750,40 @@ list_policies
 ktadd
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-       **ktadd** [**-k** *keytab*] [**-q**] [**-e** *keysaltlist*] [**-norandkey**] [[*principal* | **-glob** *princ-exp*] [...]
-              Adds a *principal* or all principals matching *princ-exp* to a *keytab*.  
+       **ktadd**  [[*principal* | **-glob** *princ-exp*]
+              Adds a *principal* or all principals matching *princ-exp* to a keytab file.  
               It randomizes each principal's key in the process, to prevent a compromised admin account from reading out all of the keys from the database.  
-              However, *kadmin.local* has the *-norandkey* option, which leaves the keys and their version numbers unchanged, 
-              similar to the Kerberos V4 ext_srvtab command. That allows users to continue to use the passwords they know to login normally, 
-              while simultaneously allowing scripts to login to the same account using a *keytab*.  
-              There is no significant security risk added since *kadmin.local* must be run by root on the KDC anyway.
+              The rules for principal expression are the same as for the *kadmin* :ref:`list_principals` command. 
+
+                 .. note:: Requires the  *inquire* and *changepw* privileges.  
+                           
+                           If you use the *-glob* option, it also requires the *list* administrative privilege. 
+
+              The options are:
+
+              **-k[eytab]**  *keytab*  
+                     Use *keytab* as the keytab file. Otherwise, *ktadd* will use the default keytab file (*/etc/krb5.keytab*).
+
+              **-e** *"enc:salt..."*
+                     Use the specified list of enctype-salttype pairs for setting the key of the principal. 
+                     The enctype-salttype pairs may be delimited with commas or whitespace.
+                     The quotes are necessary for whitespace-delimited list.
+                     If this option is not specified, then *supported_enctypes* from :ref:`krb5.conf` will be used.
+                     This will not function against kadmin daemons earlier than krb5-1.2. 
+                     See :ref:`Supported_Encryption_Types_and_Salts` for all possible values.
+
+              **-q**
+                     Run in quiet mode. This causes *ktadd* to display less verbose information.
 
-                 .. note:: Requires  the  *inquire* and *changepw* privileges.  
+              **-norandkey**
+                     Do not randomize the keys. The keys and their version numbers stay unchanged.
+                     That allows users to continue to use the passwords they know to login normally, 
+                     while simultaneously allowing scripts to login to the same account using a *keytab*.  
+                     There is no significant security risk added since *kadmin.local* must be run by root on the KDC anyway.
+                     This option is only available in *kadmin.local* and cannot be specified in combination with *-e* option.
 
-              An entry for each of the principal's unique encryption types is added, ignoring
-              multiple keys with the same encryption type but different salt types.  If the **-k** argument is not specified, the  default  *keytab*
-              */etc/krb5.keytab* is used.  If the *-q* option is specified, less verbose status information is displayed.
 
-              The **-glob** option requires the *list* privilege.  *princ-exp* follows the same rules described for the *list_principals* command.
+              .. note:: An entry for each of the principal's unique encryption types is added, ignoring multiple keys with the same encryption type but different salt types.
 
 
               EXAMPLE::
@@ -775,26 +794,38 @@ ktadd
                           WRFILE:/tmp/foo-new-keytab
                      kadmin:
 
+.. _ktadd_end:
+
 .. _ktremove:
 
 ktremove
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-       **ktremove** [**-k** *keytab*] [**-q**] *principal* [*kvno* | *all* | *old*]
-              Removes entries for the specified principal from a *keytab*.  Requires no permissions, since this does not require database
-              access.  If the string "all" is specified, all entries for that principal are removed; if the string "old" is specified, all
-              entries for that principal except those with the highest kvno are removed.  Otherwise, the value specified is parsed as an integer, 
-              and all entries whose kvno match that integer are removed.  If the *-k*  argument is not specifeid, the default *keytab*
-              */etc/krb5.keytab* is used. If the *-q* option is specified, less verbose status information is displayed.
+       **ktremove**  *principal* [*kvno* | *all* | *old*]
+              Removes entries for the specified *principal* from a keytab.  Requires no permissions, since this does not require database access. 
+
 
+              If the string "all" is specified, all entries for that principal are removed; 
+              if the string "old" is specified, all entries for that principal except those with the highest kvno are removed.  
+              Otherwise, the value specified is parsed as an integer, and all entries whose *kvno* match that integer are removed.
+
+              The options are:
+
+              **-k[eytab]**  *keytab*  
+                     Use keytab as the keytab file. Otherwise, *ktremove* will use the default keytab file (*/etc/krb5.keytab*).
+
+              **-q**
+                     Run in quiet mode. This causes *ktremove* to display less verbose information.
 
               EXAMPLE::
 
-                     kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
+                     kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin all
                      Entry for principal kadmin/admin with kvno 3 removed
                           from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
                      kadmin:
 
+.. _ktremove_end:
+
 
 FILES
 -----------
diff --git a/doc/rst_source/krb_admins/admin_commands/ktutil.rst b/doc/rst_source/krb_admins/admin_commands/ktutil.rst
index 5324d5e9a..096d5391b 100644
--- a/doc/rst_source/krb_admins/admin_commands/ktutil.rst
+++ b/doc/rst_source/krb_admins/admin_commands/ktutil.rst
@@ -1,3 +1,5 @@
+.. _ktutil(1):
+
 ktutil
 =============
 
@@ -65,6 +67,16 @@ COMMANDS
 
               Aliases: **exit**, **q**
 
+
+EXAMPLE: 
+
+      ktutil:  add_entry -password -p alice@BLEEP.COM -k 1 -e aes128-cts-hmac-sha1-96
+      Password for alice@BLEEP.COM:
+      ktutil:  add_entry -password -p alice@BLEEP.COM -k 1 -e aes256-cts-hmac-sha1-96
+      Password for alice@BLEEP.COM:
+      ktutil:  write_kt keytab
+      ktutil:
+
 SEE ALSO
 -------------
 
diff --git a/doc/rst_source/krb_admins/appl_servers/keytabs.rst b/doc/rst_source/krb_admins/appl_servers/keytabs.rst
index 7719c430a..4206ea60a 100644
--- a/doc/rst_source/krb_admins/appl_servers/keytabs.rst
+++ b/doc/rst_source/krb_admins/appl_servers/keytabs.rst
@@ -1,73 +1,49 @@
 Keytabs
 ==============
 
-A keytab is a host's copy of its own keylist, which is analogous to a user's password. An application server that needs to authenticate itself to the KDC has to have a keytab that contains its own principal and key. Just as it is important for users to protect their passwords, it is equally important for hosts to protect their keytabs. You should always store keytab files on local disk, and make them readable only by root, and you should never send a keytab file over a network in the clear. Ideally, you should run the kadmin command to extract a keytab on the host on which the keytab is to reside. 
+A keytab is a host's copy of its own keylist, which is analogous to a user's password. An application server that needs to authenticate itself to the KDC has to have a keytab that contains its own principal and key. Just as it is important for users to protect their passwords, it is equally important for hosts to protect their keytabs. You should always store keytab files on local disk, and make them readable only by root, and you should never send a keytab file over a network in the clear. Ideally, you should run the *kadmin* command to extract a keytab on the host on which the keytab is to reside. 
 
 
 .. _add_princ_kt:
 
-Adding Principals to Keytabs
+Adding principals to keytabs
 ----------------------------------
 
-To generate a keytab, or to add a principal to an existing keytab, use the **ktadd** command from kadmin, which requires the "inquire" administrative privilege. (If you use the -glob princ_exp option, it also requires the "list" administrative privilege.) The syntax is::
 
-     ktadd [-k[eytab] keytab] [-q] [-e key:salt_list] [principal | -glob princ_exp] [...]
-     
+To generate a keytab, or to add a principal to an existing keytab, use the **ktadd** command from *kadmin*.
 
-The *ktadd* command takes the following switches
+.. include:: ../admin_commands/kadmin_local.rst
+   :start-after:  _ktadd:
+   :end-before: _ktadd_end:
 
-============================================= =================================================================
--k[eytab] *keytab*                                Use keytab as the keytab file. Otherwise, *ktadd* will use the default keytab file (*/etc/krb5.keytab*).
--e *"enc:salt..."*                                Uses the specified list of enctype-salttype pairs for setting the key of the principal. The quotes are necessary if there are multiple enctype-salttype pairs. This will not function against kadmin daemons earlier than krb5-1.2. See :ref:`Supported_Encryption_Types_and_Salts` for all possible values.
--q                                                Run in quiet mode. This causes *ktadd* to display less verbose information.
-principal | -glob *principal expression*          Add principal, or all principals matching principal expression to the keytab. The rules for principal expression are the same as for the kadmin :ref:`list_principals` command. 
-============================================= =================================================================
 
-Here is a sample session, using configuration files that enable only *des-cbc-crc* encryption. (The line beginning with => is a continuation of the previous line.)::
+.. note::  Alternatively, the keytab can be generated using :ref:`ktutil(1)`  *add_entry -password* and  *write_kt* commands.
 
-     kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
-     kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with
-          kvno 2, encryption type DES-CBC-CRC added to keytab
-          WRFILE:/etc/krb5.keytab.
-     kadmin:
-     
 
-     kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab
-     => kadmin/admin kadmin/changepw
-     kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with
-          kvno 3, encryption type DES-CBC-CRC added to keytab
-          WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
-     kadmin:
-     
 
-Removing Principals from Keytabs
----------------------------------
+EXAMPLES:
 
-To remove a principal from an existing keytab, use the kadmin **ktremove** command. The syntax is::
+     Here is a sample session, using configuration files that enable only *des-cbc-crc* encryption::
 
-     ktremove [-k[eytab] keytab] [-q] principal [kvno | all | old]
+        kadmin: ktadd host/daffodil.mit.edu@ATHENA.MIT.EDU
+        kadmin: Entry for principal host/daffodil.mit.edu@ATHENA.MIT.EDU with kvno 2, encryption type DES-CBC-CRC added to keytab WRFILE:/etc/krb5.keytab.
+        kadmin:
      
 
-The *ktremove* command takes the following switches
+        kadmin: ktadd -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin kadmin/changepw
+        kadmin: Entry for principal kadmin/admin@ATHENA.MIT.EDU with kvno 3, encryption type DES-CBC-CRC added to keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
+        kadmin:
+     
 
+Removing principals from keytabs
+---------------------------------
 
-====================== ====================================
--k[eytab] *keytab*      Use keytab as the keytab file. Otherwise, *ktremove* will use the default keytab file (*/etc/krb5.keytab*).
--q                      Run in quiet mode. This causes *ktremove* to display less verbose information.
-*principal*             The principal to remove from the keytab. (Required.)
-*kvno*                       Remove all entries for the specified principal whose Key Version Numbers match *kvno*.
-all                        Remove all entries for the specified principal
-old                      Remove all entries for the specified principal *except those with the highest kvno*. 
-====================== ====================================
+To remove a principal from an existing keytab, use the *kadmin* **ktremove** command. 
 
-For example::
+.. include:: ../admin_commands/kadmin_local.rst
+   :start-after:  _ktremove:
+   :end-before: _ktremove_end:
 
-     kadmin: ktremove -k /usr/local/var/krb5kdc/kadmind.keytab kadmin/admin
-     kadmin: Entry for principal kadmin/admin with kvno 3 removed
-          from keytab WRFILE:/usr/local/var/krb5kdc/kadmind.keytab.
-     kadmin:
-     
-----------------------
 
 Feedback: