From: Greg Hudson Date: Wed, 14 Mar 2012 18:30:39 +0000 (+0000) Subject: Consolidate password and ticket management docs X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=445db58f9edef48d58e9fc55500a355b97c3c4a1;p=krb5.git 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. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25763 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/rst_source/krb_users/index.rst b/doc/rst_source/krb_users/index.rst index 22c9c6978..299792c23 100644 --- a/doc/rst_source/krb_users/index.rst +++ b/doc/rst_source/krb_users/index.rst @@ -15,7 +15,7 @@ Contents .. 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 diff --git a/doc/rst_source/krb_users/pwd_mgmt.rst b/doc/rst_source/krb_users/pwd_mgmt.rst new file mode 100644 index 000000000..8645c06dd --- /dev/null +++ b/doc/rst_source/krb_users/pwd_mgmt.rst @@ -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@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@ATHENA.MIT.EDU + david@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 diff --git a/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst b/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst deleted file mode 100644 index dcbe0b014..000000000 --- a/doc/rst_source/krb_users/pwd_mgmt/grant_access.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _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@ATHENA.MIT.EDU - david@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. diff --git a/doc/rst_source/krb_users/pwd_mgmt/index.rst b/doc/rst_source/krb_users/pwd_mgmt/index.rst deleted file mode 100644 index f9e433f08..000000000 --- a/doc/rst_source/krb_users/pwd_mgmt/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -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@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. - -.. toctree:: - :maxdepth: 1 - - pwd_management.rst - grant_access.rst - pwd_quality.rst diff --git a/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst b/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst deleted file mode 100644 index 2f599aa0c..000000000 --- a/doc/rst_source/krb_users/pwd_mgmt/pwd_management.rst +++ /dev/null @@ -1,41 +0,0 @@ -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. diff --git a/doc/rst_source/krb_users/pwd_mgmt/pwd_quality.rst b/doc/rst_source/krb_users/pwd_mgmt/pwd_quality.rst deleted file mode 100644 index 63daaa0bd..000000000 --- a/doc/rst_source/krb_users/pwd_mgmt/pwd_quality.rst +++ /dev/null @@ -1,4 +0,0 @@ -Password quality verification -============================= - -TODO diff --git a/doc/rst_source/krb_users/tkt_mgmt.rst b/doc/rst_source/krb_users/tkt_mgmt.rst new file mode 100644 index 000000000..2c0951d86 --- /dev/null +++ b/doc/rst_source/krb_users/tkt_mgmt.rst @@ -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@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@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@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@EXAMPLE.COM + Password for david@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@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@EXAMPLE.COM`` that would be good for three hours, you would +type:: + + shell% kinit -f -l 3h david@EXAMPLE.COM + Password for david@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@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@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@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@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@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU + 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU + 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU + 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@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@ATHENA.MIT.EDU + + Valid starting Expires Service principal + 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@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@EXAMPLE.COM + + Valid starting Expires Service principal + 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM + Flags: Ff + 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@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% diff --git a/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst b/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst deleted file mode 100644 index e11e1ae0d..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt/destroy_tkt.rst +++ /dev/null @@ -1,20 +0,0 @@ -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% diff --git a/doc/rst_source/krb_users/tkt_mgmt/index.rst b/doc/rst_source/krb_users/tkt_mgmt/index.rst deleted file mode 100644 index a34e6902e..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -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@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. - -.. toctree:: - :maxdepth: 1 - - tkt_management.rst - obtain_kinit.rst - view_klist.rst - destroy_tkt.rst diff --git a/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst b/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst deleted file mode 100644 index b004c1df3..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt/obtain_kinit.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _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@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@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@EXAMPLE.COM - Password for david@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@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@EXAMPLE.COM`` that would be good for three hours, you would -type:: - - shell% kinit -f -l 3h david@EXAMPLE.COM - Password for david@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)`. diff --git a/doc/rst_source/krb_users/tkt_mgmt/tkt_management.rst b/doc/rst_source/krb_users/tkt_mgmt/tkt_management.rst deleted file mode 100644 index da513980f..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt/tkt_management.rst +++ /dev/null @@ -1,76 +0,0 @@ -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. diff --git a/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst b/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst deleted file mode 100644 index 45c5dbd21..000000000 --- a/doc/rst_source/krb_users/tkt_mgmt/view_klist.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. _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@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@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@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@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@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 06/07/04 19:49:21 06/08/04 05:49:19 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - 06/07/04 20:22:30 06/08/04 05:49:19 host/daffodil.mit.edu@ATHENA.MIT.EDU - 06/07/04 20:24:18 06/08/04 05:49:19 krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU - 06/07/04 20:24:18 06/08/04 05:49:19 host/trillium.example.com@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@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 31/07/05 19:06:25 31/07/05 19:16:25 krbtgt/ATHENA.MIT.EDU@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@EXAMPLE.COM - - Valid starting Expires Service principal - 07/31/05 11:52:29 07/31/05 21:11:23 krbtgt/EXAMPLE.COM@EXAMPLE.COM - Flags: Ff - 07/31/05 12:03:48 07/31/05 21:11:23 host/trillium.example.com@EXAMPLE.COM - Flags: Ff - shell%