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