doc/user-guide.texinfo

   1 \input texinfo @c -*-texinfo-*-
   2 @c %**start of header
   3 @c guide
   4 @setfilename krb5-user.info
   5 @settitle Kerberos V5 UNIX User's Guide
   6 @setchapternewpage odd                  @c chapter begins on next odd page
   7 @c @setchapternewpage on                   @c chapter begins on next page
   8 @c @smallbook                              @c Format for 7" X 9.25" paper
   9 @c %**end of header
  10
  11 @paragraphindent 0
  12 @iftex
  13 @parskip 6pt plus 6pt
  14 @end iftex
  15
  16 @include definitions.texinfo
  17 @set EDITION b7-1
  18
  19 @finalout                               @c don't print black warning boxes
  20
  21 @titlepage
  22 @title @value{PRODUCT} UNIX User's Guide
  23 @subtitle Release:  @value{RELEASE}
  24 @subtitle Document Edition:  @value{EDITION}
  25 @subtitle Last updated:  @value{UPDATED}
  26 @author @value{COMPANY}
  27
  28 @page
  29 @vskip 0pt plus 1filll
  30
  31 @include copyright.texinfo
  32 @end titlepage
  33
  34 @comment  node-name,  next,  previous,  up
  35 @node Top, Introduction, (dir), (dir)
  36
  37 @ifinfo
  38 This file describes how to use the @value{PRODUCT} client programs.
  39
  40 @include copyright.texinfo
  41 @end ifinfo
  42
  43 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
  44 @c function.  Don't forget to run M-x texinfo-every-node-update after
  45 @c you add a new section or subsection, or after you've rearranged the
  46 @c comand before each @section or @subsection!  All you need to enter
  47 @c is:
  48 @c
  49 @c @section New Section Name
  50 @c
  51 @c M-x texinfo-every-node-update will take care of calculating the
  52 @c node's forward and back pointers.
  53 @c
  54 @c ---------------------------------------------------------------------
  55
  56 @menu
  57 * Introduction::
  58 * Kerberos V5 Tutorial::
  59 * Kerberos V5 Reference::
  60 * Kerberos Glossary::
  61 @end menu
  62
  63 @node Introduction, Kerberos V5 Tutorial, Top, Top
  64 @chapter Introduction
  65
  66 @value{PRODUCT} is based on the Kerberos V5 authentication system
  67 developed at MIT.  Kerberos is named for the three-headed watchdog from
  68 Greek mythology, who guarded the entrance to the underworld.
  69
  70 Under Kerberos, a client (generally either a user or a service) sends a
  71 request for a ticket to the @i{Key Distribution Center} (KDC).  The KDC
  72 creates a @dfn{ticket-granting ticket} (TGT) for the client, encrypts it
  73 using the client's password as the key, and sends the encrypted TGT back
  74 to the client.  The client then attempts to decrypt the TGT, using its
  75 password.  If the client successfully decrypts the TGT (@i{i.e.}, if the
  76 client gave the correct password), it keeps the decrypted TGT, which
  77 indicates proof of the client's identity.
  78
  79 The TGT, which expires at a specified time, permits the client to obtain
  80 additional tickets, which give permission for specific services.  The
  81 requesting and granting of these additional tickets is user-transparent.
  82
  83 Since Kerberos negotiates authenticated, and optionally encrypted,
  84 communications between two points anywhere on the internet, it provides
  85 a layer of security that is not dependent on which side of a firewall
  86 either client is on.  Since studies have shown that half of the computer
  87 security breaches in industry happen from @i{inside} firewalls,
  88 @value{COMPANY}'s @value{PRODUCT} plays a vital role in maintaining your
  89 nework security.
  90
  91 The @value{PRODUCT} package is designed to be easy to use.  Most of the
  92 commands are nearly identical to UNIX network programs you are already
  93 used to.  @value{PRODUCT} is a @dfn{single-sign-on} system, which means
  94 that you have to type your password only once per session, and Kerberos
  95 does the authenticating and encrypting transparently.
  96
  97 @iftex
  98 @vfil
  99 @end iftex
 100 @need 2000
 101 @menu
 102 * What is a Ticket?::
 103 * What is a Kerberos Principal?::
 104 @end menu
 105
 106 @node What is a Ticket?, What is a Kerberos Principal?, Introduction, Introduction
 107 @section What is a Ticket?
 108
 109 Your Kerberos @dfn{credentials}, or ``@dfn{tickets}'', are a set of
 110 electronic information that can be used to verify your identity.  Your
 111 Kerberos tickets may be stored in a file, or they may exist only in
 112 memory.
 113
 114 The first ticket you obtain is a @dfn{ticket-granting ticket}, which
 115 permits you to obtain additional tickets.  These additional tickets give
 116 you permission for specific services.  The requesting and granting of
 117 these additional tickets happens transparently.
 118
 119 A good analogy for the ticket-granting ticket is a three-day ski pass
 120 that is good at four different resorts.  You show the pass at whichever
 121 resort you decide to go to (until it expires), and you receive a lift
 122 ticket for that resort.  Once you have the lift ticket, you can ski all
 123 you want at that resort.  If you go to another resort the next day, you
 124 once again show your pass, and you get an additional lift ticket for the
 125 new resort.  The difference is that the @value{PRODUCT} programs notice
 126 that you have the weekend ski pass, and get the lift ticket for you, so
 127 you don't have to perform the transactions yourself.
 128
 129 @iftex
 130 @vfil
 131 @end iftex
 132 @need 2000
 133 @node What is a Kerberos Principal?,  , What is a Ticket?, Introduction
 134 @section What is a Kerberos Principal?
 135
 136 A Kerberos @dfn{principal} is a unique identity to which Kerberos can
 137 assign tickets.  By convention, a principal is divided into three parts:
 138 the @dfn{primary}, the @dfn{instance}, and the @dfn{realm}.  The format
 139 of a typical Kerberos V5 principal is @code{primary/instance@@REALM}.
 140
 141 @itemize @bullet
 142 @item The @dfn{primary} is the first part of the principal.  In the case
 143 of a user, it's the same as your username.  For a host, the primary is
 144 the word @code{host}.
 145
 146 @item The @dfn{instance} is an optional string that qualifies the
 147 primary.  The instance is separated from the primary by a slash
 148 (@code{/}).  In the case of a user, the instance is usually null, but a
 149 user might also have an additional principal, with an instance called
 150 @samp{admin}, which he/she uses to administrate a database.  The
 151 principal @code{@value{RANDOMUSER1}@@@value{PRIMARYREALM}} is completely
 152 separate from the principal
 153 @code{@value{RANDOMUSER1}/admin@@@value{PRIMARYREALM}}, with a separate
 154 password, and separate permissions.  In the case of a host, the instance
 155 is the fully qualified hostname, e.g.,
 156 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}.
 157
 158 @item The @dfn{realm} is your Kerberos realm.  In most cases, your
 159 Kerberos realm is your domain name, in upper-case letters.  For example,
 160 the machine @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} would be in
 161 the realm @code{@value{PRIMARYREALM}}.
 162 @end itemize
 163
 164 @node Kerberos V5 Tutorial, Kerberos V5 Reference, Introduction, Top
 165 @chapter @value{PRODUCT} Tutorial
 166
 167 This tutorial is intended to familiarize you with the @value{PRODUCT}
 168 client programs.  We will represent your prompt as ``@code{shell%}''.
 169 So an instruction to type the ``@kbd{ls}'' command would be represented as
 170 follows:
 171
 172 @need 600
 173 @smallexample
 174 @group
 175 @b{shell%} ls
 176 @end group
 177 @end smallexample
 178
 179 In these examples, we will use sample usernames, such as
 180 @code{@value{RANDOMUSER1}} and @code{@value{RANDOMUSER2}}, sample
 181 hostnames, such as @code{@value{RANDOMHOST1}} and
 182 @code{@value{RANDOMHOST2}}, and sample domain names, such as
 183 @code{@value{PRIMARYDOMAIN}} and @code{@value{SECONDDOMAIN}}.  When you
 184 see one of these, substitute your username, hostname, or domain name
 185 accordingly.
 186
 187 @menu
 188 * Setting Up to Use Kerberos V5::
 189 * Ticket Management::
 190 * Password Management::
 191 * Kerberos V5 Applications::
 192 @end menu
 193
 194 @node Setting Up to Use Kerberos V5, Ticket Management, Kerberos V5 Tutorial, Kerberos V5 Tutorial
 195 @section Setting Up to Use @value{PRODUCT}
 196
 197 Your system administrator will have installed the @value{PRODUCT}
 198 programs in whichever directory makes the most sense for your system.
 199 We will use @code{@value{ROOTDIR}} throughout this guide to refer to the
 200 top-level directory @value{PRODUCT} directory.  We will therefor use
 201 @code{@value{BINDIR}} to denote the location of the @value{PRODUCT} user
 202 programs.  In your installation, the directory name may be different,
 203 but whatever the directory name is, you should make sure it is included
 204 in your path.  You will probably want to put it @i{ahead of} the
 205 directories @code{/bin} and @code{/usr/bin} so you will get the
 206 @value{PRODUCT} network programs, rather than the standard UNIX
 207 versions, when you type their command names.
 208
 209 @node Ticket Management, Password Management, Setting Up to Use Kerberos V5, Kerberos V5 Tutorial
 210 @section Ticket Management
 211
 212 On many systems, Kerberos is built into the login program, and you get
 213 tickets automatically when you log in.  Other programs, such as
 214 /@code{rsh}, @code{rcp}, @code{telnet}, and @code{rlogin}, can forward
 215 copies of your tickets to the remote host.  Most of these programs also
 216 automatically destroy your tickets when they exit.  However,
 217 @value{COMPANY} recommends that you explicitly destroy your Kerberos
 218 tickets when you are through with them, just to be sure.  One way to
 219 help ensure that this happens is to add the @code{kdestroy} command to
 220 your @code{.logout} file.  Additionally, if you are going to be away
 221 from your machine and are concerned about an intruder using your
 222 permissions, it is safest to either destroy all copies of your tickets,
 223 or use a screensaver that locks the screen.
 224
 225 @need 2000
 226 @menu
 227 * Obtaining Tickets with kinit::
 228 * Viewing Your Tickets with klist::
 229 * Destroying Your Tickets with kdestroy::
 230 @end menu
 231
 232 @node Obtaining Tickets with kinit, Viewing Your Tickets with klist, Ticket Management, Ticket Management
 233 @subsection Obtaining Tickets with kinit
 234
 235 If your site is using the @value{PRODUCT} login program, you will get
 236 Kerberos tickets automatically when you log in.  If your site uses a
 237 different login program, you may need to explicitly obtain your Kerberos
 238 tickets, using the @code{kinit} program.  Similarly, if your Kerberos
 239 tickets expire, use the @code{kinit} program to obtain new ones.
 240
 241 @need 1500
 242 To use the @code{kinit} program, simply type @kbd{kinit} and then type
 243 your password at the prompt.  For example, Jennifer (whose username is
 244 @code{@value{RANDOMUSER1}}) works for Bleep, Inc. (a fictitious company
 245 with the domain name @code{@value{PRIMARYDOMAIN}} and the Kerberos realm
 246 @code{@value{PRIMARYREALM}}).  She would type:
 247
 248 @smallexample
 249 @group
 250 @b{shell%} kinit
 251 @b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type @value{RANDOMUSER1}'s password here.]}
 252 @b{shell%}
 253 @end group
 254 @end smallexample
 255
 256 @need 1000
 257 If you type your password incorrectly, kinit will give you the following
 258 error message:
 259
 260 @smallexample
 261 @group
 262 @b{shell%} kinit
 263 @b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type the wrong password here.]}
 264 @b{kinit: Password incorrect}
 265 @b{shell%}
 266 @end group
 267 @end smallexample
 268
 269 @noindent and you won't get Kerberos tickets.
 270
 271 @noindent Notice that @code{kinit} assumes you want tickets for your own
 272 username in your default realm.
 273 @need 1500
 274 Suppose Jennifer's friend David is visiting, and he wants to borrow a
 275 window to check his mail.  David needs to get tickets for himself in his
 276 own realm, @value{SECONDREALM}.@footnote{Note:  the realm
 277 @value{SECONDREALM} must be listed in your computer's Kerberos
 278 configuration file, @code{/etc/krb5.conf}.}  He would type:
 279
 280 @smallexample
 281 @group
 282 @b{shell%} kinit @value{RANDOMUSER2}@@@value{SECONDREALM}
 283 @b{Password for @value{RANDOMUSER2}@@@value{SECONDREALM}:} @i{<-- [Type @value{RANDOMUSER2}'s password here.]}
 284 @b{shell%}
 285 @end group
 286 @end smallexample
 287
 288 @noindent David would then have tickets which he could use to log onto
 289 his own machine.  Note that he typed his password locally on Jennifer's
 290 machine, but it never went over the network.  Kerberos on the local host
 291 performed the authentication to the KDC in the other realm.
 292
 293 @need 1000
 294 If you want to be able to forward your tickets to another host, you need
 295 to request @dfn{forwardable} tickets.  You do this by specifying the
 296 @kbd{-f} option:
 297
 298 @smallexample
 299 @group
 300 @b{shell%} kinit -f
 301 @b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type your password here.]}
 302 @b{shell%}
 303 @end group
 304 @end smallexample
 305
 306 @noindent
 307 Note that @code{kinit} does not tell you that it obtained forwardable
 308 tickets; you can verify this using the @code{klist} command
 309 (@pxref{Viewing Your Tickets with klist}).
 310
 311 Normally, your tickets are good for your system's default ticket
 312 lifetime, which is ten hours on many systems.  You can specify a
 313 different ticket lifetime with the @samp{-l} option.  Add the letter
 314 @samp{s} to the value for seconds, @samp{m} for minutes, @samp{h} for
 315 hours, or @samp{d} for days.
 316 @need 1500
 317 For example, to obtain forwardable tickets for
 318 @code{@value{RANDOMUSER2}@@@value{SECONDREALM}} that would be good for
 319 three hours, you would type:
 320
 321 @smallexample
 322 @group
 323 @b{shell%} kinit -f -l 3h @value{RANDOMUSER2}@@@value{SECONDREALM}
 324 @b{Password for @value{RANDOMUSER2}@@@value{SECONDREALM}:} @i{<-- [Type @value{RANDOMUSER2}'s password here.]}
 325 @b{shell%}
 326 @end group
 327 @end smallexample
 328
 329 @noindent
 330 You cannot mix units; specifying a lifetime of @samp{3h30m} would result
 331 in an error.  Note also that most systems specify a maximum ticket
 332 lifetime.  If you request a longer ticket lifetime, it will be
 333 automatically truncated to the maximum lifetime.
 334
 335 @iftex
 336 @vfil
 337 @end iftex
 338 @need 3000
 339 @node Viewing Your Tickets with klist, Destroying Your Tickets with kdestroy, Obtaining Tickets with kinit, Ticket Management
 340 @subsection Viewing Your Tickets with klist
 341
 342 The @code{klist} command shows your tickets.  When you first obtain
 343 tickets, you will have only the ticket-granting ticket.  (@xref{What is
 344 a Ticket?}.)  The listing would look like this:
 345
 346 @smallexample
 347 @group
 348 @b{shell%} klist
 349 Ticket cache: /tmp/krb5cc_ttypa
 350 Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM}
 351
 352 Valid starting     Expires            Service principal
 353 06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
 354 @b{shell%}
 355 @end group
 356 @end smallexample
 357
 358 @noindent
 359 The ticket cache is the location of your ticket file.  In the above
 360 example, this file is named @code{/tmp/krb5cc_ttypa}.  The default
 361 principal is your kerberos @dfn{principal}.  (@pxref{What is a Kerberos
 362 Principal?})
 363
 364 The ``valid starting'' and ``expires'' fields describe the period of
 365 time during which the ticket is valid.  The @dfn{service principal}
 366 describes each ticket.  The ticket-granting ticket has the primary
 367 @code{krbtgt}, and the instance is the realm name.
 368
 369 @need 2000
 370 Now, if @value{RANDOMUSER1} connected to the machine
 371 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, and then typed
 372 @kbd{klist} again, she would have gotten the following result:
 373
 374 @smallexample
 375 @group
 376 @b{shell%} klist
 377 Ticket cache: /tmp/krb5cc_ttypa
 378 Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM}
 379
 380 Valid starting     Expires            Service principal
 381 06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
 382 06/07/96 20:22:30  06/08/96 05:49:19  host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
 383 @b{shell%}
 384 @end group
 385 @end smallexample
 386
 387 @noindent
 388 Here's what happened:  when @value{RANDOMUSER1} used telnet to connect
 389 to the host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, the telnet
 390 program presented her ticket-granting ticket to the KDC and requested a
 391 host ticket for the host
 392 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}.  The KDC sent the host
 393 ticket, which telnet then presented to the host
 394 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, and she was allowed to
 395 log in without typing her password.
 396 @iftex
 397 @vfil
 398 @end iftex
 399
 400 @need 3000
 401 Suppose your Kerberos tickets allow you to log into a host in another
 402 domain, such as @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, which
 403 is also in another Kerberos realm, @code{@value{SECONDREALM}}.  If you
 404 telnet to this host, you will receive a ticket-granting ticket for the
 405 realm @code{@value{SECONDREALM}}, plus the new @code{host} ticket for
 406 @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}.  @kbd{klist} will now
 407 show:
 408
 409 @smallexample
 410 @group
 411 @b{shell%} klist
 412 Ticket cache: /tmp/krb5cc_ttypa
 413 Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM}
 414
 415 Valid starting     Expires            Service principal
 416 06/07/96 19:49:21  06/08/96 05:49:19  krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
 417 06/07/96 20:22:30  06/08/96 05:49:19  host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
 418 06/07/96 20:24:18  06/08/96 05:49:19  krbtgt/@value{SECONDREALM}@@@value{PRIMARYREALM}
 419 06/07/96 20:24:18  06/08/96 05:49:19  host/@value{RANDOMHOST2}.@value{SECONDDOMAIN}@@@value{PRIMARYREALM}
 420 @b{shell%}
 421 @end group
 422 @end smallexample
 423
 424 You can use the @code{-f} option to view the @dfn{flags} that apply to
 425 your tickets.  The flags are:
 426
 427 @table @b
 428 @itemx F
 429 @b{F}orwardable
 430 @itemx f
 431 @b{f}orwarded
 432 @itemx P
 433 @b{P}roxiable
 434 @itemx p
 435 @b{p}roxy
 436 @itemx D
 437 post@b{D}ateable
 438 @itemx d
 439 post@b{d}ated
 440 @itemx R
 441 @b{R}enewable
 442 @itemx I
 443 @b{I}nitial
 444 @itemx i
 445 @b{i}nvalid
 446 @end table
 447
 448 @need 1500
 449 Here is a sample listing.  In this example, the user @value{RANDOMUSER1}
 450 obtained her initial tickets (@samp{I}), which are forwardable
 451 (@samp{F}) and postdated (@samp{d}) but not yet validated (@samp{i}).
 452 (@xref{kinit Reference} for more information about postdated tickets.)
 453
 454 @smallexample
 455 @group
 456 @b{shell%} klist -f
 457 @b{Ticket cache: /tmp/krb5cc_320
 458 Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM}
 459
 460 Valid starting      Expires             Service principal
 461 31 Jul 96 19:06:25  31 Jul 96 19:16:25  krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
 462         Flags: FdiI
 463 shell%}
 464 @end group
 465 @end smallexample
 466
 467 @need 1500
 468 In the following example, the user @value{RANDOMUSER2}'s tickets were
 469 forwarded (@samp{f}) to this host from another host.  The tickets are
 470 reforwardable (@samp{F}).
 471
 472 @smallexample
 473 @group
 474 @b{shell%} klist -f
 475 @b{Ticket cache: /tmp/krb5cc_p11795
 476 Default principal: @value{RANDOMUSER2}@@@value{SECONDREALM}
 477
 478 Valid starting     Expires            Service principal
 479 07/31/96 11:52:29  07/31/96 21:11:23  krbtgt/@value{SECONDREALM}@@@value{SECONDREALM}
 480         Flags: Ff
 481 07/31/96 12:03:48  07/31/96 21:11:23  host/@value{RANDOMHOST2}.@value{SECONDDOMAIN}@@@value{SECONDREALM}
 482         Flags: Ff
 483 shell%}
 484 @end group
 485 @end smallexample
 486
 487 @iftex
 488 @vfil
 489 @end iftex
 490 @need 2000
 491 @node Destroying Your Tickets with kdestroy,  , Viewing Your Tickets with klist, Ticket Management
 492 @subsection Destroying Your Tickets with kdestroy
 493
 494 Your Kerberos tickets are proof that you are indeed yourself, and
 495 tickets can be stolen.  If this happens, the person who has them can
 496 masquerade as you until they expire.  For this reason, you should
 497 destroy your Kerberos tickets when you are away from your computer.
 498
 499 @need 1000
 500 Destroying your tickets is easy.  Simply type @kbd{kdestroy}.
 501
 502 @smallexample
 503 @group
 504 @b{shell%} kdestroy
 505 @b{shell%}
 506 @end group
 507 @end smallexample
 508
 509 @need 1500
 510 If @code{kdestroy} fails to destroy your tickets, it will beep and give
 511 an error message.  For example, if @code{kdestroy} can't find any
 512 tickets to destroy, it will give the following message:
 513
 514 @smallexample
 515 @group
 516 @b{shell%} kdestroy
 517 @b{kdestroy: No credentials cache file found while destroying cache
 518 Ticket cache NOT destroyed!
 519 shell%}
 520 @end group
 521 @end smallexample
 522
 523 @iftex
 524 @vfil
 525 @end iftex
 526 @need 2000
 527 @node Password Management, Kerberos V5 Applications, Ticket Management, Kerberos V5 Tutorial
 528 @section Password Management
 529
 530 Your password is the only way Kerberos has of verifying your identity.
 531 If someone finds out your password, that person can masquerade as
 532 you---send email that comes from you, read, edit, or delete your files,
 533 or log into other hosts as you---and no one will be able to tell the
 534 difference.  For this reason, it is important that you choose a good
 535 password (@pxref{Password Advice}), and keep it secret.  If you need to
 536 give access to your account to someone else, you can do so through
 537 Kerberos.  (@xref{Granting Access to Your Account}.)  You should
 538 @i{never} tell your password to anyone, including your system
 539 administrator, for any reason.  You should change your password
 540 frequently, particularly any time you think someone may have found out
 541 what it is.
 542
 543 @iftex
 544 @vfil
 545 @end iftex
 546 @need 2000
 547 @menu
 548 * Changing Your Password::
 549 * Password Advice::
 550 * Granting Access to Your Account::
 551 @end menu
 552
 553 @node Changing Your Password, Password Advice, Password Management, Password Management
 554 @subsection Changing Your Password
 555
 556 @need 2500
 557 To change your Kerberos password, use the @code{kpasswd} command.  It
 558 will ask you for your old password (to prevent someone else from walking
 559 up to your computer when you're not there and changing your password),
 560 and then prompt you for the new one twice.  (The reason you have to type
 561 it twice is to make sure you have typed it correctly.)  For example,
 562 user @code{@value{RANDOMUSER2}} would do the following:
 563
 564 @smallexample
 565 @group
 566 @b{shell%} kpasswd
 567 @b{Old password for @value{RANDOMUSER2}:}    @i{<- Type your old password.}
 568 @b{New Password for @value{RANDOMUSER2}:}    @i{<- Type your new password.}
 569 @b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:}  @i{<- Type the new password again.}
 570 @b{Password changed.}
 571 @b{shell%}
 572 @end group
 573 @end smallexample
 574
 575 @need 1800
 576 If @value{RANDOMUSER2} typed the incorrect old password, he would get
 577 the following message:
 578
 579 @smallexample
 580 @group
 581 @b{shell%} kpasswd
 582 @b{Old password for @value{RANDOMUSER2}:}  @i{<- Type the incorrect old password.}
 583 @b{Incorrect old password.
 584 shell%}
 585 @end group
 586 @end smallexample
 587
 588 @need 2500
 589 If you make a mistake and don't type the new password the same way
 590 twice, @code{kpasswd} will ask you to try again:
 591
 592 @smallexample
 593 @group
 594 @b{shell%} kpasswd
 595 @b{Old password for @value{RANDOMUSER2}:}  @i{<- Type the old password.}
 596 @b{New Password for @value{RANDOMUSER2}:}  @i{<- Type the new password.}
 597 @b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type a different new password.}
 598 @b{Mismatch - try again
 599 New Password for @value{RANDOMUSER2}:}  @i{<- Type the new password.}
 600 @b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type the same new password.}
 601 @b{Password changed.
 602 shell%}
 603 @end group
 604 @end smallexample
 605
 606 Once you change your password, it takes some time for the change to
 607 propagate through the system.  Depending on how your system is set up,
 608 this might be anywhere from a few minutes to an hour or more.  If you
 609 need to get new Kerberos tickets shortly after changing your password,
 610 try the new password.  If the new password doesn't work, try again using
 611 the old one.
 612 @iftex
 613 @vfil
 614 @end iftex
 615
 616 @need 2000
 617 @node Password Advice, Granting Access to Your Account, Changing Your Password, Password Management
 618 @subsection Password Advice
 619
 620 Your password can include almost any character you can type (except
 621 control keys and the ``enter'' key).  A good password is one you can
 622 remember, but that no one else can easily guess.  Examples of @i{bad}
 623 passwords are words that can be found in a dictionary, any common or
 624 popular name, especially a famous person (or cartoon character), your
 625 name or username in any form (@i{e.g.}, forward, backward, repeated
 626 twice, @i{etc.}), your spouse's, child's, or pet's name, your birth
 627 date, your social security number, and any sample password that appears
 628 in this (or any other) manual.
 629
 630 @need 2200
 631 @value{COMPANY} recommends that your password be at least 6 characters
 632 long, and contain UPPER- and lower-case letters, numbers, and/or
 633 punctuation marks.  Some passwords that would be good if they weren't
 634 listed in this manual include:
 635
 636 @itemize @bullet
 637 @item some initials, like ``GykoR-66.'' for ``Get your kicks on Route
 638 66.''
 639
 640 @item an easy-to-pronounce nonsense word, like ``slaRooBey'' or
 641 ``krang-its''
 642
 643 @item a misspelled phrase, like ``2HotPeetzas!'' or ``ItzAGurl!!!''
 644 @end itemize
 645
 646 @noindent Note:  don't actually use any of the above passwords.  They're
 647 only meant to show you how to make up a good password.  Passwords that
 648 appear in a manual are the first ones intruders will try.
 649 @iftex
 650 @vfil
 651 @end iftex
 652
 653 @need 3800
 654 @value{PRODUCT} allows your system administrators to automatically
 655 reject bad passwords, based on whatever criteria they choose.  For
 656 example, if the user @code{@value{RANDOMUSER1}} chose a bad password,
 657 Kerberos would give an error message like the following:
 658
 659 @smallexample
 660 @group
 661 @b{shell%} kpasswd
 662 @b{Old password for @value{RANDOMUSER1}:}  @i{<- Type your old password here.}
 663 @b{New Password for @value{RANDOMUSER1}:}  @i{<- Type an insecure new password.}
 664 @b{Verifying, please re-enter New Password for @value{RANDOMUSER1}:}  @i{<- Type it again.}
 665
 666 ERROR: Insecure password not accepted.  Please choose another.
 667
 668 kpasswd: Insecure password rejected while attempting to change password.
 669 Please choose another password.
 670
 671 @b{New Password for @value{RANDOMUSER1}:}  @i{<- Type a good password here.}
 672 @b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:}  @i{<- Type it again.}
 673 @b{Password changed.
 674 shell%}
 675 @end group
 676 @end smallexample
 677
 678 @noindent Your system administrators can choose the message that is
 679 displayed if you choose a bad password, so the message you see may be
 680 different from the above example.
 681
 682 @iftex
 683 @vfil
 684 @end iftex
 685 @need 2000
 686 @node Granting Access to Your Account,  , Password Advice, Password Management
 687 @subsection Granting Access to Your Account
 688
 689 @need 1800
 690 If you need to give someone access to log into your account, you can do
 691 so through Kerberos, without telling the person your password.  Simply
 692 create a file called @code{.k5login} in your home directory.  This file
 693 should contain the Kerberos principal (@xref{What is a Kerberos
 694 Principal?}) of each person to whom you wish to give access.  Each
 695 principal must be on a separate line.  Here is a sample @code{.k5login}
 696 file:
 697
 698 @smallexample
 699 @group
 700 @value{RANDOMUSER1}@@@value{PRIMARYREALM}
 701 @value{RANDOMUSER2}@@@value{SECONDREALM}
 702 @end group
 703 @end smallexample
 704
 705 @noindent This file would allow the users @code{@value{RANDOMUSER1}} and
 706 @code{@value{RANDOMUSER2}} to use your user ID, provided that they had
 707 Kerberos tickets in their respective realms.  If you will be logging
 708 into other hosts across a network, you will want to include your own
 709 Kerberos principal in your @code{.k5login} file on each of these hosts.
 710
 711 @need 1000
 712 Using a @code{.k5login} file is much safer than giving out your
 713 password, because:
 714
 715 @itemize @bullet
 716 @item You can take access away any time simply by removing the principal
 717 from your @code{.k5login} file.
 718
 719 @item Although the user has full access to your account on one
 720 particular host (or set of hosts if your @code{.k5login} file is shared,
 721 @i{e.g.}, over NFS), that user does not inherit your network privileges.
 722
 723 @item Kerberos keeps a log of who obtains tickets, so a system
 724 administrator could find out, if necessary, who was capable of using
 725 your user ID at a particular time.
 726 @end itemize
 727
 728 One common application is to have a @code{.k5login} file in
 729 @code{root}'s home directory, giving root access to that machine to the
 730 Kerberos principals listed.  This allows system administrators to allow
 731 users to become root locally, or to log in remotely as @code{root},
 732 without their having to give out the root password, and without anyone
 733 having to type the root password over the network.
 734
 735 @iftex
 736 @vfil
 737 @end iftex
 738 @need 2000
 739
 740 @node Kerberos V5 Applications,  , Password Management, Kerberos V5 Tutorial
 741 @section @value{PRODUCT} Applications
 742
 743 @value{PRODUCT} is a @dfn{single-sign-on} system.  This means that you
 744 only have to type your password once, and the @value{PRODUCT} programs
 745 do the authenticating (and optionally encrypting) for you.  The way this
 746 works is that Kerberos has been built into each of a suite of network
 747 programs.  For example, when you use a @value{PRODUCT} program to
 748 connect to a remote host, the program, the KDC, and the remote host
 749 perform a set of rapid negotiations.  When these negotiations are
 750 completed, your program has proven your identity on your behalf to the
 751 remote host, and the remote host has granted you access, all in the
 752 space of a few seconds.
 753
 754 The @value{PRODUCT} applications are versions of existing UNIX network
 755 programs with the Kerberos features added.
 756
 757 @iftex
 758 @vfil
 759 @end iftex
 760 @need 2000
 761 @menu
 762 * Overview of Additional Features::
 763 * telnet::
 764 * rlogin::
 765 * FTP::
 766 * rsh::
 767 * rcp::
 768 * ksu::
 769 @end menu
 770
 771 @node Overview of Additional Features, telnet, Kerberos V5 Applications, Kerberos V5 Applications
 772 @subsection Overview of Additional Features
 773
 774 The @value{PRODUCT} @dfn{network programs} are those programs that
 775 connect to another host somewhere on the internet.  These programs
 776 include @code{rlogin}, @code{telnet}, @code{ftp}, @code{rsh},
 777 @code{rcp}, and @code{ksu}.  These programs have all of the original
 778 features of the corresponding non-Kerberos @code{rlogin}, @code{telnet},
 779 @code{ftp}, @code{rsh}, @code{rcp}, and @code{su} programs, plus
 780 additional features that transparently use your Kerberos tickets for
 781 negotiating authentication and optional encryption with the remote host.
 782 In most cases, all you'll notice is that you no longer have to type your
 783 password, because Kerberos has already proven your identity.
 784
 785 The @value{PRODUCT} network programs allow you the options of forwarding
 786 your tickets to the remote host (if you obtained forwardable tickets
 787 with the @code{kinit} program; @pxref{Obtaining Tickets with kinit}), and
 788 encrypting data transmitted between you and the remote host.
 789
 790 This section of the tutorial assumes you are familiar with the
 791 non-Kerberos versions of these programs, and highlights the Kerberos
 792 functions added in the @value{PRODUCT} package.
 793
 794 @iftex
 795 @vfil
 796 @end iftex
 797 @need 2000
 798 @node telnet, rlogin, Overview of Additional Features, Kerberos V5 Applications
 799 @subsection telnet
 800
 801 The @value{PRODUCT} @code{telnet} command works exactly like the
 802 standard UNIX telnet program, with the following Kerberos options added:
 803
 804 @table @kbd
 805 @itemx -f, --forward
 806 forwards a copy of your tickets to the remote host.
 807
 808 @itemx --noforward
 809 turns off forwarding of tickets to the remote host.  (This option
 810 overrides any forwarding specified in your machine's configuration
 811 files.)
 812
 813 @itemx -F, --forwardable
 814 forwards a copy of your tickets to the remote host, and marks them
 815 re-forwardable from the remote host.
 816
 817 @itemx --noforwardable
 818 makes any forwarded tickets nonforwardable.  (This option overrides any
 819 forwardability specified in your machine's configuration files.)
 820
 821 @itemx -k @i{realm}
 822 requests tickets for the remote host in the specified realm, instead of
 823 determining the realm itself.
 824
 825 @itemx -K
 826 uses your tickets to authenticate to the remote host, but does not log
 827 you in.
 828
 829 @itemx -a
 830 attempt automatic login using your tickets.  @code{telnet} will assume
 831 the same username unless you explicitly specify another.
 832
 833 @itemx -x, --encrypt
 834 turns on encryption.
 835
 836 @itemx --noencrypt
 837 turns off encryption.
 838 @end table
 839
 840 @iftex
 841 @vfil
 842 @end iftex
 843
 844 @need 4000
 845 For example, if @code{@value{RANDOMUSER2}} wanted to use the standard
 846 UNIX telnet to connect to the machine
 847 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, he would type:
 848
 849 @smallexample
 850 @group
 851 @b{shell%} telnet @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}
 852 @b{Trying 128.0.0.5 ...
 853 Connected to @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}.
 854 Escape character is '^]'.
 855
 856 NetBSD/i386 (@value{RANDOMHOST1}) (ttyp3)
 857
 858 login:} @value{RANDOMUSER2}
 859 @b{Password:}    @i{<- @value{RANDOMUSER2} types his password here}
 860 @b{Last login: Fri Jun 21 17:13:11 from @value{RANDOMHOST2}.@value{SECONDDOMAIN}
 861 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
 862         The Regents of the University of California.   All rights reserved.
 863
 864 NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
 865
 866 Welcome to NetBSD!
 867 shell%}
 868 @end group
 869 @end smallexample
 870
 871 @noindent Note that the machine
 872 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} asked for
 873 @code{@value{RANDOMUSER2}}'s password.  When he typed it, his password
 874 was sent over the network unencrypted.  If an intruder were watching
 875 network traffic at the time, that intruder would know
 876 @code{@value{RANDOMUSER2}}'s password.
 877
 878 @iftex
 879 @vfil
 880 @end iftex
 881 @need 4000
 882 If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use the
 883 @value{PRODUCT} telnet to connect to the machine
 884 @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, she could forward a
 885 copy of her tickets, request an encrypted session, and log on as herself
 886 as follows:
 887
 888 @smallexample
 889 @group
 890 @b{shell%} telnet -a -f -x @value{RANDOMHOST2}.@value{SECONDDOMAIN}
 891 @b{Trying 128.0.0.5...
 892 Connected to @value{RANDOMHOST2}.@value{SECONDDOMAIN}.
 893 Escape character is '^]'.
 894 [ Kerberos V5 accepts you as ``@value{RANDOMUSER1}@@@value{SECONDDOMAIN}'' ]
 895 [ Kerberos V5 accepted forwarded credentials ]
 896 NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
 897
 898 Welcome to NetBSD!
 899 shell%}
 900 @end group
 901 @end smallexample
 902
 903 @noindent Note that @code{@value{RANDOMUSER1}}'s machine used Kerberos
 904 to authenticate her to @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}},
 905 and logged her in automatically as herself.  She had an encrypted
 906 session, a copy of her tickets already waiting for her, and she never
 907 typed her password.
 908
 909 If you forwarded your Kerberos tickets, @code{telnet} automatically
 910 destroys them when it exits.  The full set of options to @value{PRODUCT}
 911 @code{telnet} are discussed in the Reference section of this manual.
 912 (@pxref{telnet Reference})
 913
 914 @iftex
 915 @vfil
 916 @end iftex
 917 @need 2000
 918 @node rlogin, FTP, telnet, Kerberos V5 Applications
 919 @subsection rlogin
 920
 921 @need 1000
 922 The @value{PRODUCT} @code{rlogin} command works exactly like the
 923 standard UNIX rlogin program, with the following Kerberos options added:
 924
 925 @table @kbd
 926 @itemx -f, --forward
 927 forwards a copy of your tickets to the remote host.
 928
 929 @itemx --noforward
 930 turns off forwarding of tickets to the remote host.  (This option
 931 overrides any forwarding specified in your machine's configuration
 932 files.)
 933
 934 @itemx -F, --forwardable
 935 forwards a copy of your tickets to the remote host, and marks them
 936 re-forwardable from the remote host.
 937
 938 @itemx --noforwardable
 939 makes any forwarded tickets nonforwardable.  (This option overrides any
 940 forwardability specified in your machine's configuration files.)
 941
 942 @itemx -k @i{realm}
 943 requests tickets for the remote host in the specified realm, instead of
 944 determining the realm itself.
 945
 946 @itemx -x, --encrypt
 947 turns on encryption.
 948
 949 @itemx --noencrypt
 950 turns off encryption.
 951 @end table
 952
 953 @need 3000
 954 For example, if @code{@value{RANDOMUSER2}} wanted to use the standard
 955 UNIX rlogin to connect to the machine
 956 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, he would type:
 957
 958 @smallexample
 959 @group
 960 @b{shell%} rlogin @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} -l @value{RANDOMUSER2}
 961 @b{Password:}  @i{<- @value{RANDOMUSER2} types his password here}
 962 @b{Last login: Fri Jun 21 10:36:32 from :0.0
 963 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
 964         The Regents of the University of California.   All rights reserved.
 965
 966 NetBSD 1.1: Tue May 21 00:31:42 EDT 1996
 967
 968 Welcome to NetBSD!
 969 shell%}
 970 @end group
 971 @end smallexample
 972
 973 @noindent Note that the machine
 974 @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} asked for
 975 @code{@value{RANDOMUSER2}}'s password.  When he typed it, his password
 976 was sent over the network unencrypted.  If an intruder were watching
 977 network traffic at the time, that intruder would know
 978 @code{@value{RANDOMUSER2}}'s password.
 979
 980 @iftex
 981 @vfil
 982 @end iftex
 983 @need 4000
 984 If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use
 985 @value{PRODUCT} rlogin to connect to the machine
 986 @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, she could forward a
 987 copy of her tickets, mark them as not forwardable from the remote host,
 988 and request an encrypted session as follows:
 989
 990 @smallexample
 991 @group
 992 @b{shell%} rlogin @value{RANDOMHOST2}.@value{SECONDDOMAIN} -f -x
 993 @b{This rlogin session is using DES encryption for all data transmissions.
 994 Last login: Thu Jun 20 16:20:50 from @value{RANDOMHOST1}
 995 SunOS Release 4.1.4 (GENERIC) #2: Tue Nov 14 18:09:31 EST 1995
 996 Not checking quotas. Try quota.real if you need them.
 997 shell%}
 998 @end group
 999 @end smallexample
1000
1001 @noindent Note that @code{@value{RANDOMUSER1}}'s machine used Kerberos
1002 to authenticate her to @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}},
1003 and logged her in automatically as herself.  She had an encrypted
1004 session, a copy of her tickets were waiting for her, and she never typed
1005 her password.
1006
1007 If you forwarded your Kerberos tickets, @code{rlogin} automatically
1008 destroys them when it exits.  The full set of options to @value{PRODUCT}
1009 @code{rlogin} are discussed in the Reference section of this manual.
1010 (@pxref{rlogin Reference})
1011
1012 @iftex
1013 @vfil
1014 @end iftex
1015 @need 2000
1016 @node FTP, rsh, rlogin, Kerberos V5 Applications
1017 @subsection FTP
1018
1019 @need 1000
1020 The @value{PRODUCT} @code{FTP} program works exactly like the standard
1021 UNIX FTP program, with the following Kerberos features added:
1022
1023 @table @kbd
1024 @itemx -k @i{realm}
1025 requests tickets for the remote host in the specified realm, instead of
1026 determining the realm itself.
1027
1028 @itemx -forward
1029 requests that your tickets be forwarded to the remote host.  The
1030 @kbd{-forward} argument must be the last argument on the command line.
1031
1032 @itemx protect @i{level}
1033 (issued at the @code{ftp>} prompt) sets the protection level.  ``Clear''
1034 is no protection; ``safe'' ensures data integrity by verifying the
1035 checksum, and ``private'' encrypts the data.  Encryption also ensures
1036 data integrity.
1037 @end table
1038
1039 @need 5000
1040 For example, suppose @code{@value{RANDOMUSER1}} wants to get her
1041 @code{RMAIL} file from the directory @code{~@value{RANDOMUSER1}/Mail},
1042 on the host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}.  She wants
1043 to encrypt the file transfer.  The exchange would look like the
1044 following:
1045
1046 @smallexample
1047 @group
1048 @b{shell%} ftp @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}
1049 Connected to @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}.
1050 220 @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} FTP server (Version 5.60) ready.
1051 334 Using authentication type GSSAPI; ADAT must follow
1052 GSSAPI accepted as authentication type
1053 GSSAPI authentication succeeded
1054 Name (@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}:@value{RANDOMUSER1}):
1055 232 GSSAPI user @value{RANDOMUSER1}@@@value{PRIMARYREALM} is authorized as @value{RANDOMUSER1}
1056 230 User @value{RANDOMUSER1} logged in.
1057 Remote system type is UNIX.
1058 Using binary mode to transfer files.
1059 ftp> protect private
1060 200 Protection level set to Private.
1061 ftp> cd ~@value{RANDOMUSER1}/MAIL
1062 250 CWD command successful.
1063 ftp> get RMAIL
1064 227 Entering Passive Mode (128,0,0,5,16,49)
1065 150 Opening BINARY mode data connection for RMAIL (361662 bytes).
1066 226 Transfer complete.
1067 361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s)
1068 ftp> quit
1069 @b{shell%}
1070 @end group
1071 @end smallexample
1072
1073 The full set of options to @value{PRODUCT} @code{FTP} are discussed
1074 in the Reference section of this manual.  (@pxref{FTP Reference})
1075
1076 @iftex
1077 @vfil
1078 @end iftex
1079 @need 2000
1080 @node rsh, rcp, FTP, Kerberos V5 Applications
1081 @subsection rsh
1082
1083 @need 1000
1084 The @value{PRODUCT} @code{rsh} program works exactly like the standard
1085 UNIX rlogin program, with the following Kerberos features added:
1086
1087 @table @kbd
1088 @itemx -f, --forward
1089 forwards a copy of your tickets to the remote host.
1090
1091 @itemx --noforward
1092 turns off forwarding of tickets to the remote host.  (This option
1093 overrides any forwarding specified in your machine's configuration
1094 files.)
1095
1096 @itemx -F, --forwardable
1097 forwards a copy of your tickets to the remote host, and marks them
1098 re-forwardable from the remote host.
1099
1100 @itemx --noforwardable
1101 makes any forwarded tickets nonforwardable.  (This option overrides any
1102 forwardability specified in your machine's configuration files.)
1103
1104 @itemx -k @i{realm}
1105 requests tickets for the remote host in the specified realm, instead of
1106 determining the realm itself.
1107
1108 @itemx -x, --encrypt
1109 turns on encryption.
1110
1111 @itemx --noencrypt
1112 turns off encryption.
1113 @end table
1114
1115 @need 1800
1116 For example, if your Kerberos tickets allowed you to run programs on the
1117 host @code{@value{RANDOMHOST2}@@@value{SECONDDOMAIN}} as root, you could
1118 run the @samp{date} program as follows:
1119
1120 @smallexample
1121 @group
1122 @b{shell%} rsh @value{RANDOMHOST2}.@value{SECONDDOMAIN} -l root -x date
1123 @b{This rsh session is using DES encryption for all data transmissions.
1124 Fri Jun 21 17:06:12 EDT 1996
1125 shell%}
1126 @end group
1127 @end smallexample
1128
1129 If you forwarded your Kerberos tickets, @code{rsh} automatically
1130 destroys them when it exits.  The full set of options to @value{PRODUCT}
1131 @code{rsh} are discussed in the Reference section of this manual.
1132 (@pxref{rsh Reference})
1133
1134 @iftex
1135 @vfil
1136 @end iftex
1137 @need 2000
1138 @node rcp, ksu, rsh, Kerberos V5 Applications
1139 @subsection rcp
1140
1141 @need 1000
1142 The @value{PRODUCT} @code{rcp} program works exactly like the standard
1143 UNIX rcp program, with the following Kerberos features added:
1144
1145 @table @kbd
1146 @itemx -k @i{realm}
1147 requests tickets for the remote host in the specified realm, instead of
1148 determining the realm itself.
1149
1150 @itemx -x, --encrypt
1151 turns on encryption.
1152 @end table
1153
1154
1155 @need 1500
1156 For example, if you wanted to copy the file @code{/etc/motd} from the
1157 host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} into the current
1158 directory, via an encrypted connection, you would simply type:
1159
1160 @smallexample
1161 @b{shell%} rcp -x @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}:/etc/motd .
1162 @end smallexample
1163
1164 The @kbd{rcp} program negotiates authentication and encryption
1165 transparently.  The full set of options to @value{PRODUCT} @code{rcp}
1166 are discussed in the Reference section of this manual.  (@pxref{rcp
1167 Reference})
1168
1169 @iftex
1170 @vfil
1171 @end iftex
1172 @need 2000
1173 @node ksu,  , rcp, Kerberos V5 Applications
1174 @subsection ksu
1175
1176 The @value{PRODUCT} @code{ksu} program replaces the standard UNIX su
1177 program.  @code{ksu} first authenticates you to Kerberos.  Depending on
1178 the configuration of your system, @code{ksu} may ask for your Kerberos
1179 password if authentication fails.  @emph{Note that you should never type
1180 your password if you are remotely logged in using an unencrypted
1181 connection.}
1182
1183 Once @code{ksu} has authenticated you, if your Kerberos principal
1184 appears in the target's @code{.k5login} file (@pxref{Granting Access to
1185 Your Account}) or in the target's @code{.k5users} file (see below), it
1186 switches your user ID to the target user ID.
1187
1188 @need 2000
1189 For example, @code{@value{RANDOMUSER2}} has put
1190 @code{@value{RANDOMUSER1}}'s Kerberos principal in his @code{.k5login}
1191 file.  If @code{@value{RANDOMUSER1}} uses @code{ksu} to become
1192 @code{@value{RANDOMUSER2}}, the exchange would look like this.  (To
1193 differentiate between the two shells, @code{@value{RANDOMUSER1}}'s
1194 prompt is represented as @code{@value{RANDOMUSER1}%} and
1195 @code{@value{RANDOMUSER2}}'s prompt is represented as
1196 @code{@value{RANDOMUSER2}%}.)
1197
1198 @smallexample
1199 @group
1200 @b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2}
1201 @b{Account @value{RANDOMUSER2}: authorization for @value{RANDOMUSER1}@@@value{PRIMARYREALM} successful
1202 Changing uid to @value{RANDOMUSER2} (3382)
1203 @value{RANDOMUSER2}%}
1204 @end group
1205 @end smallexample
1206
1207 @noindent
1208 Note that the new shell has a copy of @code{@value{RANDOMUSER1}}'s
1209 tickets.  The ticket filename contains @code{@value{RANDOMUSER2}}'s UID
1210 with @samp{.1} appended to it:
1211
1212 @smallexample
1213 @group
1214 @b{@value{RANDOMUSER2}%} klist
1215 @b{Ticket cache: /tmp/krb5cc_3382.1
1216 Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM}
1217
1218 Valid starting      Expires             Service principal
1219 31 Jul 96 21:53:01  01 Aug 96 07:52:53  krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM}
1220 31 Jul 96 21:53:39  01 Aug 96 07:52:53  host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}
1221 @value{RANDOMUSER2}%}
1222 @end group
1223 @end smallexample
1224
1225 @need 2500
1226 If @code{@value{RANDOMUSER1}} had not appeared in
1227 @code{@value{RANDOMUSER2}}'s @code{.k5login} file (and the system was
1228 configured to ask for a password), the exchange would have looked like
1229 this (assuming @code{@value{RANDOMUSER2}} has taken appropriate
1230 precautions in protecting his password):
1231
1232 @smallexample
1233 @group
1234 @b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2}
1235 @b{WARNING: Your password may be exposed if you enter it here and are logged
1236          in remotely using an unsecure (non-encrypted) channel.
1237 Kerberos password for @value{RANDOMUSER2}@@@value{PRIMARYREALM}:}  @i{<-  @code{@value{RANDOMUSER1}} types the wrong password here.}
1238 @b{ksu: Password incorrect
1239 Authentication failed.
1240 @value{RANDOMUSER1}%}
1241 @end group
1242 @end smallexample
1243
1244 Now, suppose @code{@value{RANDOMUSER2}} did not want to give
1245 @code{@value{RANDOMUSER1}} full access to his account, but wanted to
1246 give her permission to list his files and use the "more" command to view
1247 them.  He could create a @code{.k5users} file giving her permission to
1248 run only those specific commands.
1249
1250 @need 3500
1251 The @code{.k5users} file is like the @code{.k5login} file, except that
1252 each principal is optionally followed by a list of commands.  @code{ksu}
1253 will let those principals execute only the commands listed, using the
1254 @kbd{-e} option.  @code{@value{RANDOMUSER2}}'s @code{.k5users} file
1255 might look like the following:
1256
1257 @smallexample
1258 @group
1259 @value{RANDOMUSER1}@@@value{PRIMARYREALM}       /bin/ls /usr/bin/more
1260 @value{ADMINUSER}@@@value{PRIMARYREALM}         /bin/ls
1261 @value{ADMINUSER}/admin@@@value{PRIMARYREALM}   *
1262 @value{RANDOMUSER2}@@@value{SECONDREALM}
1263 @end group
1264 @end smallexample
1265
1266 @noindent The above @code{.k5users} file would let
1267 @code{@value{RANDOMUSER1}} run only the commands @code{/bin/ls} and
1268 @code{/usr/bin/more}.  It would let @code{@value{ADMINUSER}} run only
1269 the command @code{/bin/ls} if he had regular tickets, but if he had
1270 tickets for his @code{admin} instance,
1271 @code{@value{ADMINUSER}/admin@@@value{PRIMARYREALM}}, he would be able
1272 to execute any command.  The last line gives @code{@value{RANDOMUSER2}}
1273 in the realm @value{SECONDREALM} permission to execute any command.
1274 (@i{I.e.}, having only a Kerberos principal on a line is equivalent to
1275 giving that principal permission to execute @code{*}.)  This is so that
1276 @value{RANDOMUSER2} can allow himself to execute commands when he logs
1277 in, using Kerberos, from a machine in the realm @value{SECONDREALM}.
1278
1279 @need 2500
1280 Then, when @code{@value{RANDOMUSER1}} wanted to list his home directory,
1281 she would type:
1282
1283 @smallexample
1284 @group
1285 @b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2} -e ls ~@value{RANDOMUSER2}
1286 @b{Authenticated @value{RANDOMUSER1}@@@value{PRIMARYREALM}
1287 Account @value{RANDOMUSER2}: authorization for @value{RANDOMUSER1}@@@value{PRIMARYREALM} for execution of
1288                /bin/ls successful
1289 Changing uid to @value{RANDOMUSER2} (3382)
1290 Mail            News            Personal        misc            bin
1291 @value{RANDOMUSER1}%}
1292 @end group
1293 @end smallexample
1294
1295 @noindent If @code{@value{RANDOMUSER1}} had tried to give a different
1296 command to @code{ksu}, it would have prompted for a password as with the
1297 previous example.
1298
1299 Note that unless the @code{.k5users} file gives the target permission to
1300 run any command, the user must use @code{ksu} with the @kbd{-e}
1301 @i{command} option.
1302
1303 @need 1000
1304 The @code{ksu} options you are most likely to use are:
1305
1306 @table @kbd
1307 @itemx -n @i{principal}
1308 specifies which Kerberos principal you want to use for @code{ksu}.
1309 (@i{e.g.}, the user @code{@value{ADMINUSER}} might want to use his
1310 @code{admin} instance.  @xref{What is a Ticket?}.)
1311
1312 @itemx -c
1313 specifies the location of your Kerberos credentials cache (ticket file).
1314
1315 @itemx -C
1316 specifies the location you want the Kerberos credentials cache (ticket
1317 file) to be for the target user ID.
1318
1319 @itemx -k
1320 tells @code{ksu} not to destroy your Kerberos tickets when @code{ksu} is
1321 finished.
1322
1323 @itemx -f
1324 requests forwardable tickets.  (@xref{Obtaining Tickets with kinit}.)  This
1325 is only applicable if @code{ksu} needs to obtain tickets.
1326
1327 @itemx -l @i{lifetime}
1328 sets the ticket lifetime.  (@xref{Obtaining Tickets with kinit}.)  This is
1329 only applicable if @code{ksu} needs to obtain tickets.
1330
1331 @itemx -z
1332 tells @code{ksu} to copy your Kerberos tickets only if the UID you are
1333 switching is the same as the Kerberos primary (either yours or the one
1334 specified by the @kbd{-n} option).
1335
1336 @itemx -Z
1337 tells @code{ksu} not to copy any Kerberos tickets to the new UID.
1338
1339 @itemx -e @i{command}
1340 tells @code{ksu} to execute @i{command} and then exit.  See the
1341 description of the @code{.k5users} file above.
1342
1343 @itemx -a @i{text}
1344 (at the end of the command line) tells @code{ksu} to pass everything
1345 after @samp{-a} to the target shell.
1346 @end table
1347
1348 The full set of options to @value{PRODUCT} @code{ksu} are discussed
1349 in the Reference section of this manual.  (@pxref{ksu Reference})
1350
1351 @node Kerberos V5 Reference, Kerberos Glossary, Kerberos V5 Tutorial, Top
1352 @chapter @value{PRODUCT} Reference
1353
1354 This section will include copies of the manual pages for the
1355 @value{PRODUCT} client programs.  You can read the manual entry for any
1356 command by typing @code{man} @i{command}, where @i{command} is the name
1357 of the command for which you want to read the manual entry.  For
1358 example, to read the @code{kinit} manual entry, you would type:
1359
1360 @smallexample
1361 @b{shell%} man kinit
1362 @end smallexample
1363
1364 Note:  To be able to view the @value{PRODUCT} manual pages on line, you
1365 may need to add the directory @code{@value{ROOTDIR}/man} to your MANPATH
1366 environment variable.  (Remember to replace @code{@value{ROOTDIR}} with
1367 the top-level directory in which @value{PRODUCT} is installed.)  For
1368 example, if you had the the following line in your @code{.login}
1369 file@footnote{The MANPATH variable may be specified in a different
1370 initialization file, depending on your operating system.  Some of the
1371 files in which you might specify environment variables include
1372 @code{.login}, @code{.profile}, or @code{.cshrc}.}:
1373
1374 @smallexample
1375 setenv MANPATH /usr/local/man:/usr/man
1376 @end smallexample
1377
1378 @noindent
1379 and the @value{PRODUCT} man pages were in the directory
1380 @code{/usr/@value{LCPRODUCT}/man}, you would change the line to the following:
1381
1382 @smallexample
1383 setenv MANPATH /usr/@value{LCPRODUCT}/man:/usr/local/man:/usr/man
1384 @end smallexample
1385
1386 @ifinfo
1387 Note to info users:  the manual pages are not available within this info
1388 tree.  You can read them from emacs with the command:
1389
1390 @smallexample
1391 M-x manual-entry @emph{command}
1392 @end smallexample
1393 @end ifinfo
1394
1395 @page
1396
1397 @menu
1398 * kinit Reference::
1399 * klist Reference::
1400 * kdestroy Reference::
1401 * kpasswd Reference::
1402 * telnet Reference::
1403 * rlogin Reference::
1404 * FTP Reference::
1405 * rsh Reference::
1406 * rcp Reference::
1407 * ksu Reference::
1408 @end menu
1409
1410 @node kinit Reference, klist Reference, Kerberos V5 Reference, Kerberos V5 Reference
1411 @section kinit Reference
1412
1413 @iftex
1414 @special{psfile=kinit1.ps voffset=-700 hoffset=-40}
1415 @centerline{Reference Manual for @code{kinit}}
1416 @page
1417
1418 @special{psfile=kinit2.ps voffset=-700 hoffset=-40}
1419 @centerline{Reference Manual for @code{kinit}}
1420 @page
1421 @end iftex
1422 @ifinfo
1423 Type @kbd{M-x manual-entry kinit} to read this manual page.
1424 @end ifinfo
1425
1426 @node klist Reference, kdestroy Reference, kinit Reference, Kerberos V5 Reference
1427 @section klist Reference
1428
1429 @iftex
1430 @special{psfile=klist1.ps voffset=-700 hoffset=-40}
1431 @centerline{Reference Manual for @code{klist}}
1432 @page
1433 @end iftex
1434 @ifinfo
1435 Type @kbd{M-x manual-entry klist} to read this manual page.
1436 @end ifinfo
1437
1438 @node kdestroy Reference, kpasswd Reference, klist Reference, Kerberos V5 Reference
1439 @section kdestroy Reference
1440
1441 @iftex
1442 @special{psfile=kdestroy1.ps voffset=-700 hoffset=-60}
1443 @centerline{Reference Manual for @code{kdestroy}}
1444 @page
1445 @end iftex
1446 @ifinfo
1447 Type @kbd{M-x manual-entry kdestroy} to read this manual page.
1448 @end ifinfo
1449
1450 @node kpasswd Reference, telnet Reference, kdestroy Reference, Kerberos V5 Reference
1451 @section kpasswd Reference
1452
1453 @iftex
1454 @special{psfile=kpasswd1.ps voffset=-700 hoffset=-40}
1455 @centerline{Reference Manual for @code{kpasswd}}
1456 @page
1457 @end iftex
1458 @ifinfo
1459 Type @kbd{M-x manual-entry kpasswd} to read this manual page.
1460 @end ifinfo
1461
1462 @node telnet Reference, rlogin Reference, kpasswd Reference, Kerberos V5 Reference
1463 @section telnet Reference
1464
1465 @iftex
1466 @special{psfile=telnet1.ps voffset=-700 hoffset=-40}
1467 @centerline{Reference Manual for @code{telnet}}
1468 @page
1469
1470 @special{psfile=telnet2.ps voffset=-700 hoffset=-40}
1471 @centerline{Reference Manual for @code{telnet}}
1472 @page
1473
1474 @special{psfile=telnet3.ps voffset=-700 hoffset=-40}
1475 @centerline{Reference Manual for @code{telnet}}
1476 @page
1477
1478 @special{psfile=telnet4.ps voffset=-700 hoffset=-40}
1479 @centerline{Reference Manual for @code{telnet}}
1480 @page
1481
1482 @special{psfile=telnet5.ps voffset=-700 hoffset=-40}
1483 @centerline{Reference Manual for @code{telnet}}
1484 @page
1485
1486 @special{psfile=telnet6.ps voffset=-700 hoffset=-40}
1487 @centerline{Reference Manual for @code{telnet}}
1488 @page
1489
1490 @special{psfile=telnet7.ps voffset=-700 hoffset=-40}
1491 @centerline{Reference Manual for @code{telnet}}
1492 @page
1493
1494 @special{psfile=telnet8.ps voffset=-700 hoffset=-40}
1495 @centerline{Reference Manual for @code{telnet}}
1496 @page
1497
1498 @special{psfile=telnet9.ps voffset=-700 hoffset=-40}
1499 @centerline{Reference Manual for @code{telnet}}
1500 @page
1501
1502 @special{psfile=telnet10.ps voffset=-700 hoffset=-40}
1503 @centerline{Reference Manual for @code{telnet}}
1504 @page
1505 @end iftex
1506 @ifinfo
1507 Type @kbd{M-x manual-entry telnet} to read this manual page.
1508 @end ifinfo
1509
1510 @node rlogin Reference, FTP Reference, telnet Reference, Kerberos V5 Reference
1511 @section rlogin Reference
1512
1513 @iftex
1514 @special{psfile=rlogin1.ps voffset=-700 hoffset=-40}
1515 @centerline{Reference Manual for @code{rlogin}}
1516 @page
1517
1518 @special{psfile=rlogin2.ps voffset=-700 hoffset=-40}
1519 @centerline{Reference Manual for @code{rlogin}}
1520 @page
1521 @end iftex
1522 @ifinfo
1523 Type @kbd{M-x manual-entry rlogin} to read this manual page.
1524 @end ifinfo
1525
1526 @node FTP Reference, rsh Reference, rlogin Reference, Kerberos V5 Reference
1527 @section FTP Reference
1528
1529 @iftex
1530 @special{psfile=ftp1.ps voffset=-700 hoffset=-40}
1531 @centerline{Reference Manual for @code{FTP}}
1532 @page
1533
1534 @special{psfile=ftp2.ps voffset=-700 hoffset=-40}
1535 @centerline{Reference Manual for @code{FTP}}
1536 @page
1537
1538 @special{psfile=ftp3.ps voffset=-700 hoffset=-40}
1539 @centerline{Reference Manual for @code{FTP}}
1540 @page
1541
1542 @special{psfile=ftp4.ps voffset=-700 hoffset=-40}
1543 @centerline{Reference Manual for @code{FTP}}
1544 @page
1545
1546 @special{psfile=ftp5.ps voffset=-700 hoffset=-40}
1547 @centerline{Reference Manual for @code{FTP}}
1548 @page
1549
1550 @special{psfile=ftp6.ps voffset=-700 hoffset=-40}
1551 @centerline{Reference Manual for @code{FTP}}
1552 @page
1553
1554 @special{psfile=ftp7.ps voffset=-700 hoffset=-40}
1555 @centerline{Reference Manual for @code{FTP}}
1556 @page
1557
1558 @special{psfile=ftp8.ps voffset=-700 hoffset=-40}
1559 @centerline{Reference Manual for @code{FTP}}
1560 @page
1561 @end iftex
1562 @ifinfo
1563 Type @kbd{M-x manual-entry FTP} to read this manual page.
1564 @end ifinfo
1565
1566 @node rsh Reference, rcp Reference, FTP Reference, Kerberos V5 Reference
1567 @section rsh Reference
1568
1569 @iftex
1570 @special{psfile=rsh1.ps voffset=-700 hoffset=-40}
1571 @centerline{Reference Manual for @code{rsh}}
1572 @page
1573
1574 @special{psfile=rsh2.ps voffset=-700 hoffset=-40}
1575 @centerline{Reference Manual for @code{rsh}}
1576 @page
1577 @end iftex
1578 @ifinfo
1579 Type @kbd{M-x manual-entry rsh} to read this manual page.
1580 @end ifinfo
1581
1582 @node rcp Reference, ksu Reference, rsh Reference, Kerberos V5 Reference
1583 @section rcp Reference
1584
1585 @iftex
1586 @special{psfile=rcp1.ps voffset=-700 hoffset=-40}
1587 @centerline{Reference Manual for @code{rcp}}
1588 @page
1589
1590 @special{psfile=rcp2.ps voffset=-700 hoffset=-40}
1591 @centerline{Reference Manual for @code{rcp}}
1592 @page
1593 @end iftex
1594 @ifinfo
1595 Type @kbd{M-x manual-entry rcp} to read this manual page.
1596 @end ifinfo
1597
1598 @node ksu Reference,  , rcp Reference, Kerberos V5 Reference
1599 @section ksu Reference
1600
1601 @iftex
1602 @special{psfile=ksu1.ps voffset=-700 hoffset=-40}
1603 @centerline{Reference Manual for @code{ksu}}
1604 @page
1605
1606 @special{psfile=ksu2.ps voffset=-700 hoffset=-40}
1607 @centerline{Reference Manual for @code{ksu}}
1608 @page
1609
1610 @special{psfile=ksu3.ps voffset=-700 hoffset=-40}
1611 @centerline{Reference Manual for @code{ksu}}
1612 @page
1613
1614 @special{psfile=ksu4.ps voffset=-700 hoffset=-40}
1615 @centerline{Reference Manual for @code{ksu}}
1616 @page
1617
1618 @special{psfile=ksu5.ps voffset=-700 hoffset=-40}
1619 @centerline{Reference Manual for @code{ksu}}
1620 @page
1621 @end iftex
1622 @ifinfo
1623 Type @kbd{M-x manual-entry ksu} to read this manual page.
1624 @end ifinfo
1625
1626 @node Kerberos Glossary,  , Kerberos V5 Reference, Top
1627 @appendix Kerberos Glossary
1628
1629 @include glossary.texinfo
1630
1631 @contents
1632 @bye