From 4c4859fa83295db5c26f47b96c719060cfd9e2b1 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Fri, 16 Mar 2012 04:31:57 +0000 Subject: [PATCH] Edit RST user man pages for clarity and accuracy git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25771 dc483132-0cff-0310-8789-dd5450dbe970 --- .../krb_users/user_commands/kdestroy.rst | 10 +- .../krb_users/user_commands/kinit.rst | 100 +++++++++--------- .../krb_users/user_commands/klist.rst | 8 +- .../krb_users/user_commands/kpasswd.rst | 27 +---- .../krb_users/user_commands/kswitch.rst | 2 +- .../krb_users/user_commands/kvno.rst | 19 ++-- 6 files changed, 74 insertions(+), 92 deletions(-) diff --git a/doc/rst_source/krb_users/user_commands/kdestroy.rst b/doc/rst_source/krb_users/user_commands/kdestroy.rst index f7469d5f1..f664f302e 100644 --- a/doc/rst_source/krb_users/user_commands/kdestroy.rst +++ b/doc/rst_source/krb_users/user_commands/kdestroy.rst @@ -15,10 +15,10 @@ SYNOPSIS 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 @@ kdestroy uses the following environment variable: **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 diff --git a/doc/rst_source/krb_users/user_commands/kinit.rst b/doc/rst_source/krb_users/user_commands/kinit.rst index 109a5c02a..ea1ee3a90 100644 --- a/doc/rst_source/krb_users/user_commands/kinit.rst +++ b/doc/rst_source/krb_users/user_commands/kinit.rst @@ -42,9 +42,9 @@ OPTIONS 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 @@ OPTIONS **-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 @@ OPTIONS **-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 @@ OPTIONS 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 @@ OPTIONS 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 @@ ENVIRONMENT 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 @@ FILES 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 diff --git a/doc/rst_source/krb_users/user_commands/klist.rst b/doc/rst_source/krb_users/user_commands/klist.rst index 30ae72ef4..594a77142 100644 --- a/doc/rst_source/krb_users/user_commands/klist.rst +++ b/doc/rst_source/krb_users/user_commands/klist.rst @@ -65,7 +65,7 @@ OPTIONS **-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 @@ OPTIONS 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 @@ klist uses the following environment variable: **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 diff --git a/doc/rst_source/krb_users/user_commands/kpasswd.rst b/doc/rst_source/krb_users/user_commands/kpasswd.rst index f7c484064..1b6463265 100644 --- a/doc/rst_source/krb_users/user_commands/kpasswd.rst +++ b/doc/rst_source/krb_users/user_commands/kpasswd.rst @@ -13,11 +13,8 @@ DESCRIPTION ----------- 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 @@ OPTIONS 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. diff --git a/doc/rst_source/krb_users/user_commands/kswitch.rst b/doc/rst_source/krb_users/user_commands/kswitch.rst index 6c83a5c86..62134959b 100644 --- a/doc/rst_source/krb_users/user_commands/kswitch.rst +++ b/doc/rst_source/krb_users/user_commands/kswitch.rst @@ -36,7 +36,7 @@ kswitch 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 + 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 diff --git a/doc/rst_source/krb_users/user_commands/kvno.rst b/doc/rst_source/krb_users/user_commands/kvno.rst index 6db4353b5..4f2e2fd38 100644 --- a/doc/rst_source/krb_users/user_commands/kvno.rst +++ b/doc/rst_source/krb_users/user_commands/kvno.rst @@ -28,8 +28,8 @@ OPTIONS ------- **-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 @@ OPTIONS 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 @@ OPTIONS 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 -- 2.26.2