svn rev #25771: trunk/doc/rst_source/krb_users/user_commands/

ghudson@MIT.EDU ghudson at MIT.EDU
Fri Mar 16 00:31:57 EDT 2012


http://src.mit.edu/fisheye/changelog/krb5/?cs=25771
Commit By: ghudson
Log Message:
Edit RST user man pages for clarity and accuracy


Changed Files:
U   trunk/doc/rst_source/krb_users/user_commands/kdestroy.rst
U   trunk/doc/rst_source/krb_users/user_commands/kinit.rst
U   trunk/doc/rst_source/krb_users/user_commands/klist.rst
U   trunk/doc/rst_source/krb_users/user_commands/kpasswd.rst
U   trunk/doc/rst_source/krb_users/user_commands/kswitch.rst
U   trunk/doc/rst_source/krb_users/user_commands/kvno.rst
Modified: trunk/doc/rst_source/krb_users/user_commands/kdestroy.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kdestroy.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/kdestroy.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -15,10 +15,10 @@
 DESCRIPTION
 -----------
 
-The kdestroy utility destroys the user's active Kerberos
-authorization tickets by writing zeros to the specified
-credentials cache that contains them. If the credentials
-cache is not specified, the default credentials cache is destroyed.
+The kdestroy utility destroys the user's active Kerberos authorization
+tickets by overwriting and deleting the credentials cache that
+contains them.  If the credentials cache is not specified, the default
+credentials cache is destroyed.
 
 
 OPTIONS
@@ -57,7 +57,7 @@
 
 **KRB5CCNAME**
     Location of the default Kerberos 5 credentials (ticket) cache, in
-    the form *type*:*residual*.  If no type prefix is present, the
+    the form *type*:*residual*.  If no *type* prefix is present, the
     **FILE** type is assumed.  The type of the default cache may
     determine the availability of a cache collection; for instance, a
     default cache of type **DIR** causes caches within the directory

Modified: trunk/doc/rst_source/krb_users/user_commands/kinit.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kinit.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/kinit.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -42,9 +42,9 @@
     display verbose output.
 
 **-l** *lifetime*
-    requests a ticket  with  the  lifetime  lifetime.   The
-    value  for lifetime must be followed immediately by one
-    of the following delimiters:
+    requests a ticket with the lifetime *lifetime*.  The integer value
+    for *lifetime* must be followed immediately by one of the
+    following delimiters:
 
      ::
 
@@ -64,7 +64,7 @@
 **-s** *start_time*
     requests a postdated ticket, valid starting at *start_time*.
     Postdated tickets are issued with the **invalid** flag set, and
-    need to be fed back to the kdc before use.
+    need to be resubmitted to the KDC for validation before use.
 
 **-r** *renewable_life*
     requests renewable tickets, with a total lifetime of
@@ -72,31 +72,34 @@
     **-l** option, with the same delimiters.
 
 **-f**
-    request forwardable tickets.
+    requests forwardable tickets.
 
 **-F**
-    do not request forwardable tickets.
+    requests non-forwardable tickets.
 
 **-p**
-    request proxiable tickets.
+    requests proxiable tickets.
 
 **-P**
-    do not request proxiable tickets.
+    requests non-proxiable tickets.
 
 **-a**
-    request tickets with the local address[es].
+    requests tickets restricted to the host's local address[es].
 
 **-A**
-    request address-less tickets.
+    requests tickets not restricted by address.
 
 **-C**
-    requests canonicalization of the principal name.
+    requests canonicalization of the principal name, and allows the
+    KDC to reply with a different client principal from the one
+    requested.
 
 **-E**
-    treats the principal name as an enterprise name.
+    treats the principal name as an enterprise name (implies the
+    **-C** option).
 
 **-v**
-    requests that the ticket granting ticket in the cache (with the
+    requests that the ticket-granting ticket in the cache (with the
     **invalid** flag set) be passed to the KDC for validation.  If the
     ticket is within its requested time range, the cache is replaced
     with the validated ticket.
@@ -107,15 +110,15 @@
     within its renewable life.
 
 **-k** [**-t** *keytab_file*]
-    requests a ticket, obtained from a key in the local host's keytab
-    file.  The name and location of the key tab file may be specified
-    with the **-t** *keytab_file* option; otherwise the default name
-    and location will be used.  By default a host ticket is requested
-    but any principal may be specified.  On a KDC, the special keytab
-    location ``KDB:`` can be used to indicate that kinit should open
-    the KDC database and look up the key directly.  This permits an
+    requests a ticket, obtained from a key in the local host's keytab.
+    The location of the keytab may be specified with the **-t**
+    *keytab_file* option; otherwise the default keytab will be used.
+    By default, a host ticket for the local host is requested, but any
+    principal may be specified.  On a KDC, the special keytab location
+    ``KDB:`` can be used to indicate that kinit should open the KDC
+    database and look up the key directly.  This permits an
     administrator to obtain tickets as any principal that supports
-    password-based authentication.
+    authentication based on the key.
 
 **-n**
     Requests anonymous processing.  Two types of anonymous principals
@@ -138,40 +141,39 @@
     anonymous operation.
 
 **-T** *armor_ccache*
-    Specifies the name of a credential cache that already contains a
-    ticket.  If supported by the KDC, this ccache will be used to
-    armor the request so that an attacker would have to know both the
-    key of the armor ticket and the key of the principal used for
-    authentication in order to attack the request.  Armoring also
+    Specifies the name of a credentials cache that already contains a
+    ticket.  If supported by the KDC, this cache will be used to armor
+    the request, preventing offline dictionary attacks and allowing
+    the use of additional preauthentication mechanisms.  Armoring also
     makes sure that the response from the KDC is not modified in
     transit.
 
 **-c** *cache_name*
-    use *cache_name* as the Kerberos 5 credentials (ticket) cache name
-    and location; if this option is not used, the default cache name
-    and location are used.
+    use *cache_name* as the Kerberos 5 credentials (ticket) cache
+    location.  If this option is not used, the default cache location
+    is used.
 
-    The default credentials cache may vary between systems.  If the
+    The default cache location may vary between systems.  If the
     **KRB5CCNAME** environment variable is set, its value is used to
-    name the default ticket cache.  If a principal name is specified
-    and the type of the default credentials cache supports a
-    collection (such as the DIR type), an existing cache containing
-    credentials for the principal is selected or a new one is created
-    and becomes the new primary cache.  Otherwise, any existing
-    contents of the default cache are destroyed by kinit.
+    locate the default cache.  If a principal name is specified and
+    the type of the default cache supports a collection (such as the
+    DIR type), an existing cache containing credentials for the
+    principal is selected or a new one is created and becomes the new
+    primary cache.  Otherwise, any existing contents of the default
+    cache are destroyed by kinit.
 
 **-S** *service_name*
     specify an alternate service name to use when getting initial
     tickets.
 
 **-X** *attribute*\ [=\ *value*]
-    specify a pre-authentication *attribute* and *value* to be passed
-    to pre-authentication plugins.  The acceptable attribute and value
-    values vary from pre-authentication plugin to plugin.  This option
-    may be specified multiple times to specify multiple attributes.
-    If no value is specified, it is assumed to be "yes".
+    specify a pre-authentication *attribute* and *value* to be
+    interpreted by pre-authentication modules.  The acceptable
+    attribute and value values vary from module to module.  This
+    option may be specified multiple times to specify multiple
+    attributes.  If no value is specified, it is assumed to be "yes".
 
-    The following attributes are recognized by the OpenSSL pkinit
+    The following attributes are recognized by the PKINIT
     pre-authentication mechanism:
 
     **X509_user_identity**\ =\ *value*
@@ -191,12 +193,12 @@
 kinit uses the following environment variables:
 
 **KRB5CCNAME**
-    Location of the default Kerberos 5 credentials (ticket) cache, in
-    the form *type*:*residual*.  If no type prefix is present, the
-    **FILE** type is assumed.  The type of the default cache may
-    determine the availability of a cache collection; for instance, a
-    default cache of type **DIR** causes caches within the directory
-    to be present in the collection.
+    Location of the default Kerberos 5 credentials cache, in the form
+    *type*:*residual*.  If no *type* prefix is present, the **FILE**
+    type is assumed.  The type of the default cache may determine the
+    availability of a cache collection; for instance, a default cache
+    of type **DIR** causes caches within the directory to be present
+    in the collection.
 
 
 FILES
@@ -207,7 +209,7 @@
     decimal UID of the user).
 
 ``/etc/krb5.keytab``
-    default location for the local host's keytab file.
+    default location for the local host's keytab.
 
 
 SEE ALSO

Modified: trunk/doc/rst_source/krb_users/user_commands/klist.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/klist.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/klist.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -65,7 +65,7 @@
 **-s**
     Causes klist to run silently (produce no output), but to still set
     the exit status according to whether it finds the credentials
-    cache. The exit status is '0' if klist finds a credentials cache,
+    cache.  The exit status is '0' if klist finds a credentials cache,
     and '1' if it does not or if the tickets are expired.
 
 **-a**
@@ -90,8 +90,8 @@
 
 If *cache_name* or *keytab_name* is not specified, klist will display
 the credentials in the default credentials cache or keytab file as
-appropriate. If the **KRB5CCNAME** environment variable is set, its
-value is used to name the default ticket cache.
+appropriate.  If the **KRB5CCNAME** environment variable is set, its
+value is used to locate the default ticket cache.
 
 
 ENVIRONMENT
@@ -101,7 +101,7 @@
 
 **KRB5CCNAME**
     Location of the default Kerberos 5 credentials (ticket) cache, in
-    the form *type*:*residual*.  If no type prefix is present, the
+    the form *type*:*residual*.  If no *type* prefix is present, the
     **FILE** type is assumed.  The type of the default cache may
     determine the availability of a cache collection; for instance, a
     default cache of type **DIR** causes caches within the directory

Modified: trunk/doc/rst_source/krb_users/user_commands/kpasswd.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kpasswd.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/kpasswd.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -13,11 +13,8 @@
 -----------
 
 The kpasswd command is used to change a Kerberos principal's password.
-kpasswd prompts for the current Kerberos password, which is used to
-obtain a ``changepw`` ticket from the KDC for the user's Kerberos
-realm.  If kpasswd successfully obtains the ``changepw`` ticket, the
-user is prompted twice for the new password, and the password is
-changed.
+kpasswd first prompts for the current Kerberos password, then prompts
+the user twice for the new password, and the password is changed.
 
 If the principal is governed by a policy that specifies the length
 and/or number of character classes required in the new password, the
@@ -36,27 +33,7 @@
     identity of the user invoking the kpasswd command.
 
 
-PORTS
------
-
-kpasswd looks first for
- ::
-
-    kpasswd_server = host:port
-
-in the [realms] section of the :ref:`krb5.conf(5)` file under the
-current realm.  If that is missing, kpasswd looks for the
-**admin_server** entry, but substitutes 464 for the port.
-
-
 SEE ALSO
 --------
 
 :ref:`kadmin(1)`, :ref:`kadmind(8)`
-
-
-BUGS
-----
-
-kpasswd may not work with multi-homed hosts running on the Solaris
-platform.

Modified: trunk/doc/rst_source/krb_users/user_commands/kswitch.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kswitch.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/kswitch.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -36,7 +36,7 @@
 
 **KRB5CCNAME**
     Location of the default Kerberos 5 credentials (ticket) cache, in
-    the form *type*:*residual*.  If no type prefix is present, the
+    the form *type*:*residual*.  If no *type* prefix is present, the
     **FILE** type is assumed.  The type of the default cache may
     determine the availability of a cache collection; for instance, a
     default cache of type **DIR** causes caches within the directory

Modified: trunk/doc/rst_source/krb_users/user_commands/kvno.rst
===================================================================
--- trunk/doc/rst_source/krb_users/user_commands/kvno.rst	2012-03-15 22:52:45 UTC (rev 25770)
+++ trunk/doc/rst_source/krb_users/user_commands/kvno.rst	2012-03-16 04:31:57 UTC (rev 25771)
@@ -28,8 +28,8 @@
 -------
 
 **-c** *ccache*
-   Specifies the name of a credentials cache to use (if not the
-   default)
+    Specifies the name of a credentials cache to use (if not the
+    default)
 
 **-e** *etype*
     Specifies the enctype which will be requested for the session key
@@ -37,10 +37,12 @@
     certain backward compatibility situations.
 
 **-q**
-   Suppress printing
+    Suppress printing output when successful.  If a service ticket
+    cannot be obtained, an error message will still be printed and
+    kvno will exit with nonzero status.
 
 **-h**
-   Prints a usage statement and exits
+    Prints a usage statement and exits.
 
 **-P**
     Specifies that the *service1 service2* ...  arguments are to be
@@ -49,10 +51,11 @@
     conjunction with protocol transition.
 
 **-S** *sname*
-    Specifies that *krb5_sname_to_principal()* will be used to build
-    principal names.  If this flag is specified, the *service1
-    service2* ...  arguments are interpreted as hostnames (rather than
-    principal names), and *sname* is interpreted as the service name.
+    Specifies that the *service1 service2* ... arguments are
+    interpreted as hostnames, and the service principals are to be
+    constructed from those hostnames and the service name *sname*.
+    The service hostnames will be canonicalized according to the usual
+    rules for constructing service principals.
 
 **-U** *for_user*
     Specifies that protocol transition (S4U2Self) is to be used to



More information about the cvs-krb5 mailing list