svn rev #25763: trunk/doc/rst_source/krb_users/ pwd_mgmt/ tkt_mgmt/

ghudson@MIT.EDU ghudson at MIT.EDU
Wed Mar 14 14:30:39 EDT 2012


http://src.mit.edu/fisheye/changelog/krb5/?cs=25763
Commit By: ghudson
Log Message:
Consolidate password and ticket management docs

In the RST documentation, combine the pwd_mgmt and tkt_mgmt
subdirectories of krb_users into single files, without changing the
content.


Changed Files:
U   trunk/doc/rst_source/krb_users/index.rst
D   trunk/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst
D   trunk/doc/rst_source/krb_users/pwd_mgmt/index.rst
D   trunk/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst
D   trunk/doc/rst_source/krb_users/pwd_mgmt/pwd_quality.rst
A   trunk/doc/rst_source/krb_users/pwd_mgmt.rst
D   trunk/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst
D   trunk/doc/rst_source/krb_users/tkt_mgmt/index.rst
D   trunk/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst
D   trunk/doc/rst_source/krb_users/tkt_mgmt/tkt_management.rst
D   trunk/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst
A   trunk/doc/rst_source/krb_users/tkt_mgmt.rst
Modified: trunk/doc/rst_source/krb_users/index.rst
===================================================================
--- trunk/doc/rst_source/krb_users/index.rst	2012-03-12 20:24:45 UTC (rev 25762)
+++ trunk/doc/rst_source/krb_users/index.rst	2012-03-14 18:30:39 UTC (rev 25763)
@@ -15,7 +15,7 @@
 .. toctree::
    :maxdepth: 2
 
-   pwd_mgmt/index.rst
-   tkt_mgmt/index.rst
+   pwd_mgmt.rst
+   tkt_mgmt.rst
    user_appl/index.rst
    user_commands/index.rst

Added: trunk/doc/rst_source/krb_users/pwd_mgmt.rst
===================================================================
--- trunk/doc/rst_source/krb_users/pwd_mgmt.rst	                        (rev 0)
+++ trunk/doc/rst_source/krb_users/pwd_mgmt.rst	2012-03-14 18:30:39 UTC (rev 25763)
@@ -0,0 +1,111 @@
+Password management
+===================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+          Guide**.  Currently it is under review.  Please, send your
+          feedback, corrections and additions to krb5-bugs at mit.edu.
+          Your contribution is greatly appreciated.
+
+Your password is the only way Kerberos has of verifying your identity.
+If someone finds out your password, that person can masquerade as
+you--send email that comes from you, read, edit, or delete your files,
+or log into other hosts as you--and no one will be able to tell the
+difference.  For this reason, it is important that you choose a good
+password, and keep it secret.  If you need to give access to your
+account to someone else, you can do so through Kerberos (see
+:ref:`grant_access`).  You should never tell your password to anyone,
+including your system administrator, for any reason.  You should
+change your password frequently, particularly any time you think
+someone may have found out what it is.
+
+
+Changing your password
+----------------------
+
+To change your Kerberos password, use the :ref:`kpasswd(1)` command.
+It will ask you for your old password (to prevent someone else from
+walking up to your computer when you're not there and changing your
+password), and then prompt you for the new one twice.  (The reason you
+have to type it twice is to make sure you have typed it correctly.)
+For example, user ``david`` would do the following::
+
+    shell% kpasswd
+    Password for david:    <- Type your old password.
+    Enter new password:    <- Type your new password.
+    Enter it again:  <- Type the new password again.
+    Password changed.
+    shell%
+
+If ``david`` typed the incorrect old password, he would get the
+following message::
+
+    shell% kpasswd
+    Password for david:  <- Type the incorrect old password.
+    kpasswd: Password incorrect while getting initial ticket
+    shell%
+
+If you make a mistake and don't type the new password the same way
+twice, kpasswd will ask you to try again::
+
+    shell% kpasswd
+    Password for david:  <- Type the old password.
+    Enter new password:  <- Type the new password.
+    Enter it again: <- Type a different new password.
+    kpasswd: Password mismatch while reading password
+    shell%
+
+Once you change your password, it takes some time for the change to
+propagate through the system.  Depending on how your system is set up,
+this might be anywhere from a few minutes to an hour or more.  If you
+need to get new Kerberos tickets shortly after changing your password,
+try the new password.  If the new password doesn't work, try again
+using the old one.
+
+
+.. _grant_access:
+
+Granting access to your account
+-------------------------------
+
+If you need to give someone access to log into your account, you can
+do so through Kerberos, without telling the person your password.
+Simply create a file called :ref:`.k5login(5)` in your home directory.
+This file should contain the Kerberos principal of each person to whom
+you wish to give access.  Each principal must be on a separate line.
+Here is a sample .k5login file::
+
+    jennifer at ATHENA.MIT.EDU
+    david at EXAMPLE.COM
+
+This file would allow the users ``jennifer`` and ``david`` to use your
+user ID, provided that they had Kerberos tickets in their respective
+realms.  If you will be logging into other hosts across a network, you
+will want to include your own Kerberos principal in your .k5login file
+on each of these hosts.
+
+Using a .k5login file is much safer than giving out your password,
+because:
+
+* You can take access away any time simply by removing the principal
+  from your .k5login file.
+
+* Although the user has full access to your account on one particular
+  host (or set of hosts if your .k5login file is shared, e.g., over
+  NFS), that user does not inherit your network privileges.
+
+* Kerberos keeps a log of who obtains tickets, so a system
+  administrator could find out, if necessary, who was capable of using
+  your user ID at a particular time.
+
+One common application is to have a .k5login file in root's home
+directory, giving root access to that machine to the Kerberos
+principals listed.  This allows system administrators to allow users
+to become root locally, or to log in remotely as root, without their
+having to give out the root password, and without anyone having to
+type the root password over the network.
+
+
+Password quality verification
+-----------------------------
+
+TODO

Added: trunk/doc/rst_source/krb_users/tkt_mgmt.rst
===================================================================
--- trunk/doc/rst_source/krb_users/tkt_mgmt.rst	                        (rev 0)
+++ trunk/doc/rst_source/krb_users/tkt_mgmt.rst	2012-03-14 18:30:39 UTC (rev 25763)
@@ -0,0 +1,313 @@
+Ticket management
+=================
+
+.. note:: This document was copied from **Kerberos V5 UNIX User's
+          Guide**.  Currently it is under review.  Please, send your
+          feedback, corrections and additions to krb5-bugs at mit.edu.
+          Your contribution is greatly appreciated.
+
+On many systems, Kerberos is built into the login program, and you get
+tickets automatically when you log in.  Other programs, such as rsh,
+rcp, telnet, and rlogin, can forward copies of your tickets to the
+remote host.  Most of these programs also automatically destroy your
+tickets when they exit.  However, MIT recommends that you explicitly
+destroy your Kerberos tickets when you are through with them, just to
+be sure.  One way to help ensure that this happens is to add the
+:ref:`kdestroy(1)` command to your .logout file.  Additionally, if you
+are going to be away from your machine and are concerned about an
+intruder using your permissions, it is safest to either destroy all
+copies of your tickets, or use a screensaver that locks the screen.
+
+
+Kerberos ticket properties
+--------------------------
+
+There are various properties that Kerberos tickets can have:
+
+If a ticket is **forwardable**, then the KDC can issue a new ticket
+with a different network address based on the forwardable ticket.
+This allows for authentication forwarding without requiring a password
+to be typed in again.  For example, if a user with a forwardable TGT
+logs into a remote system, the KDC could issue a new TGT for that user
+with the netword address of the remote system, allowing authentication
+on that host to work as though the user were logged in locally.
+
+When the KDC creates a new ticket based on a forwardable ticket, it
+sets the **forwarded** flag on that new ticket.  Any tickets that are
+created based on a ticket with the forwarded flag set will also have
+their forwarded flags set.
+
+A **proxiable** ticket is similar to a forwardable ticket in that it
+allows a service to take on the identity of the client.  Unlike a
+forwardable ticket, however, a proxiable ticket is only issued for
+specific services.  In other words, a ticket-granting ticket cannot be
+issued based on a ticket that is proxiable but not forwardable.
+
+A **proxy** ticket is one that was issued based on a proxiable ticket.
+
+A **postdated** ticket is issued with the invalid flag set.  After the
+starting time listed on the ticket, it can be presented to the KDC to
+obtain valid tickets.
+
+Tickets with the **postdateable** flag set can be used to issue
+postdated tickets.
+
+**Renewable** tickets can be used to obtain new session keys without
+the user entering their password again.  A renewable ticket has two
+expiration times.  The first is the time at which this particular
+ticket expires.  The second is the latest possible expiration time for
+any ticket issued based on this renewable ticket.
+
+A ticket with the **initial flag** set was issued based on the
+authentication protocol, and not on a ticket-granting ticket.  Clients
+that wish to ensure that the user's key has been recently presented
+for verification could specify that this flag must be set to accept
+the ticket.
+
+An **invalid** ticket must be rejected by application servers.
+Postdated tickets are usually issued with this flag set, and must be
+validated by the KDC before they can be used.
+
+A **preauthenticated** ticket is one that was only issued after the
+client requesting the ticket had authenticated itself to the KDC.
+
+The **hardware authentication** flag is set on a ticket which required
+the use of hardware for authentication.  The hardware is expected to
+be possessed only by the client which requested the tickets.
+
+If a ticket has the **transit policy** checked flag set, then the KDC
+that issued this ticket implements the transited-realm check policy
+and checked the transited-realms list on the ticket.  The
+transited-realms list contains a list of all intermediate realms
+between the realm of the KDC that issued the first ticket and that of
+the one that issued the current ticket.  If this flag is not set, then
+the application server must check the transited realms itself or else
+reject the ticket.
+
+The okay as **delegate** flag indicates that the server specified in
+the ticket is suitable as a delegate as determined by the policy of
+that realm.  A server that is acting as a delegate has been granted a
+proxy or a forwarded TGT.  This flag is a new addition to the Kerberos
+V5 protocol and is not yet implemented on MIT servers.
+
+An **anonymous** ticket is one in which the named principal is a
+generic principal for that realm; it does not actually specify the
+individual that will be using the ticket.  This ticket is meant only
+to securely distribute a session key.  This is a new addition to the
+Kerberos V5 protocol and is not yet implemented on MIT servers.
+
+
+.. _obtain_tkt:
+
+Obtaining tickets with kinit
+----------------------------
+
+If your site is using the Kerberos V5 login program, you will get
+Kerberos tickets automatically when you log in.  If your site uses a
+different login program, you may need to explicitly obtain your
+Kerberos tickets, using the :ref:`kinit(1)` program.  Similarly, if
+your Kerberos tickets expire, use the kinit program to obtain new
+ones.
+
+To use the kinit program, simply type ``kinit`` and then type your
+password at the prompt. For example, Jennifer (whose username is
+``jennifer``) works for Bleep, Inc. (a fictitious company with the
+domain name mit.edu and the Kerberos realm ATHENA.MIT.EDU).  She would
+type::
+
+    shell% kinit
+    Password for jennifer at ATHENA.MIT.EDU: <-- [Type jennifer's password here.]
+    shell%
+
+If you type your password incorrectly, kinit will give you the
+following error message::
+
+    shell% kinit
+    Password for jennifer at ATHENA.MIT.EDU: <-- [Type the wrong password here.]
+    kinit: Password incorrect
+    shell%
+
+and you won't get Kerberos tickets.
+
+Notice that kinit assumes you want tickets for your own username in
+your default realm.  Suppose Jennifer's friend David is visiting, and
+he wants to borrow a window to check his mail.  David needs to get
+tickets for himself in his own realm, EXAMPLE.COM [1]_. He would
+type::
+
+    shell% kinit david at EXAMPLE.COM
+    Password for david at EXAMPLE.COM: <-- [Type david's password here.]
+    shell%
+
+David would then have tickets which he could use to log onto his own
+machine.  Note that he typed his password locally on Jennifer's
+machine, but it never went over the network.  Kerberos on the local
+host performed the authentication to the KDC in the other realm.
+
+If you want to be able to forward your tickets to another host, you
+need to request forwardable tickets. You do this by specifying the
+**-f** option::
+
+    shell% kinit -f
+    Password for jennifer at ATHENA.MIT.EDU: <-- [Type your password here.]
+    shell%
+
+Note that kinit does not tell you that it obtained forwardable
+tickets; you can verify this using the :ref:`klist(1)` command (see
+:ref:`view_tkt`).
+
+Normally, your tickets are good for your system's default ticket
+lifetime, which is ten hours on many systems.  You can specify a
+different ticket lifetime with the **-l** option.  Add the letter
+**s** to the value for seconds, **m** for minutes, **h** for hours, or
+**d** for days.  For example, to obtain forwardable tickets for
+``david at EXAMPLE.COM`` that would be good for three hours, you would
+type::
+
+    shell% kinit -f -l 3h david at EXAMPLE.COM
+    Password for david at EXAMPLE.COM: <-- [Type david's password here.]
+    shell%
+
+.. note:: You cannot mix units; specifying a lifetime of 3h30m would
+          result in an error.  Note also that most systems specify a
+          maximum ticket lifetime.  If you request a longer ticket
+          lifetime, it will be automatically truncated to the maximum
+          lifetime.
+
+.. [1] Note: the realm EXAMPLE.COM must be listed in your computer's
+       Kerberos configuration file, :ref:`krb5.conf(5)`.
+
+
+.. _view_tkt:
+
+Viewing tickets with klist
+--------------------------
+
+The :ref:`klist(1)` command shows your tickets.  When you first obtain
+tickets, you will have only the ticket-granting ticket.  The listing
+would look like this::
+
+    shell% klist
+    Ticket cache: /tmp/krb5cc_ttypa
+    Default principal: jennifer at ATHENA.MIT.EDU
+
+    Valid starting     Expires            Service principal
+    06/07/04 19:49:21  06/08/04 05:49:19  krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+    shell%
+
+The ticket cache is the location of your ticket file. In the above
+example, this file is named ``/tmp/krb5cc_ttypa``. The default
+principal is your Kerberos principal.
+
+The "valid starting" and "expires" fields describe the period of time
+during which the ticket is valid.  The "service principal" describes
+each ticket.  The ticket-granting ticket has the primary ``krbtgt``,
+and the instance is the realm name.
+
+Now, if ``jennifer`` connected to the machine ``daffodil.mit.edu``,
+and then typed "klist" again, she would have gotten the following
+result::
+
+    shell% klist
+    Ticket cache: /tmp/krb5cc_ttypa
+    Default principal: jennifer at ATHENA.MIT.EDU
+
+    Valid starting     Expires            Service principal
+    06/07/04 19:49:21  06/08/04 05:49:19  krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+    06/07/04 20:22:30  06/08/04 05:49:19  host/daffodil.mit.edu at ATHENA.MIT.EDU
+    shell%
+
+Here's what happened: when ``jennifer`` used telnet to connect to the
+host ``daffodil.mit.edu``, the telnet program presented her
+ticket-granting ticket to the KDC and requested a host ticket for the
+host ``daffodil.mit.edu``.  The KDC sent the host ticket, which telnet
+then presented to the host ``daffodil.mit.edu``, and she was allowed
+to log in without typing her password.
+
+Suppose your Kerberos tickets allow you to log into a host in another
+domain, such as ``trillium.example.com``, which is also in another
+Kerberos realm, ``EXAMPLE.COM``.  If you telnet to this host, you will
+receive a ticket-granting ticket for the realm ``EXAMPLE.COM``, plus
+the new host ticket for ``trillium.example.com``.  klist will now
+show::
+
+    shell% klist
+    Ticket cache: /tmp/krb5cc_ttypa
+    Default principal: jennifer at ATHENA.MIT.EDU
+
+    Valid starting     Expires            Service principal
+    06/07/04 19:49:21  06/08/04 05:49:19  krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+    06/07/04 20:22:30  06/08/04 05:49:19  host/daffodil.mit.edu at ATHENA.MIT.EDU
+    06/07/04 20:24:18  06/08/04 05:49:19  krbtgt/EXAMPLE.COM at ATHENA.MIT.EDU
+    06/07/04 20:24:18  06/08/04 05:49:19  host/trillium.example.com at EXAMPLE.COM
+    shell%
+
+You can use the **-f** option to view the flags that apply to your
+tickets.  The flags are:
+
+===== =========================
+  F   Forwardable
+  f   forwarded
+  P   Proxiable
+  p   proxy
+  D   postDateable
+  d   postdated
+  R   Renewable
+  I   Initial
+  i   invalid
+  H   Hardware authenticated
+  A   preAuthenticated
+  T   Transit policy checked
+  O   Okay as delegate
+  a   anonymous
+===== =========================
+
+Here is a sample listing.  In this example, the user *jennifer*
+obtained her initial tickets (**I**), which are forwardable (**F**)
+and postdated (**d**) but not yet validated (**i**)::
+
+    shell% klist -f
+    Ticket cache: /tmp/krb5cc_320
+    Default principal: jennifer at ATHENA.MIT.EDU
+
+    Valid starting      Expires             Service principal
+    31/07/05 19:06:25  31/07/05 19:16:25  krbtgt/ATHENA.MIT.EDU at ATHENA.MIT.EDU
+            Flags: FdiI
+    shell%
+
+In the following example, the user *david*'s tickets were forwarded
+(**f**) to this host from another host.  The tickets are reforwardable
+(**F**)::
+
+    shell% klist -f
+    Ticket cache: /tmp/krb5cc_p11795
+    Default principal: david at EXAMPLE.COM
+
+    Valid starting     Expires            Service principal
+    07/31/05 11:52:29  07/31/05 21:11:23  krbtgt/EXAMPLE.COM at EXAMPLE.COM
+            Flags: Ff
+    07/31/05 12:03:48  07/31/05 21:11:23  host/trillium.example.com at EXAMPLE.COM
+            Flags: Ff
+    shell%
+
+
+Destroying tickets with kdestroy
+--------------------------------
+
+Your Kerberos tickets are proof that you are indeed yourself, and
+tickets can be stolen.  If this happens, the person who has them can
+masquerade as you until they expire.  For this reason, you should
+destroy your Kerberos tickets when you are away from your computer.
+
+Destroying your tickets is easy.  Simply type kdestroy::
+
+    shell% kdestroy
+    shell%
+
+If :ref:`kdestroy(1)` fails to destroy your tickets, it will beep and
+give an error message.  For example, if kdestroy can't find any
+tickets to destroy, it will give the following message::
+
+    shell% kdestroy
+    kdestroy: No credentials cache file found while destroying cache
+    shell%



More information about the cvs-krb5 mailing list