From: Greg Hudson Date: Wed, 14 Mar 2012 19:55:44 +0000 (+0000) Subject: Remove user_appl section in RST docs X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=0bb72611892782381e7c73e1a4481d9b2e503f9f;p=krb5.git Remove user_appl section in RST docs The user_appl directory contained documentation for krb5_appl programs which have largely been subsumed by ssh, for ksu (essentially duplicating the ksu man page), and for ssh (a stub). Get rid of the whole thing for now; we can add an ssh section back into the user guide when we have more written about it. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25766 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/rst_source/krb_users/index.rst b/doc/rst_source/krb_users/index.rst index 299792c23..c2baf97da 100644 --- a/doc/rst_source/krb_users/index.rst +++ b/doc/rst_source/krb_users/index.rst @@ -17,5 +17,4 @@ Contents pwd_mgmt.rst tkt_mgmt.rst - user_appl/index.rst user_commands/index.rst diff --git a/doc/rst_source/krb_users/user_appl/ftp.rst b/doc/rst_source/krb_users/user_appl/ftp.rst deleted file mode 100644 index 5fafd3e48..000000000 --- a/doc/rst_source/krb_users/user_appl/ftp.rst +++ /dev/null @@ -1,40 +0,0 @@ -ftp -=== - -The Kerberos V5 FTP program works exactly like the standard UNIX FTP -program, with the following Kerberos features added: - -=========================== =================================================================================================== --k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself. --f requests that your tickets be forwarded to the remote host. The -f argument must be the last argument on the command line. -protect *level* (issued at the ftp> prompt) sets the protection level. **clear** is no protection; **safe** ensures data integrity by verifying the checksum, and **private** encrypts the data. Encryption also ensures data integrity. -=========================== =================================================================================================== - -For example, suppose ``jennifer`` wants to get her RMAIL file from the -directory ``~jennifer/Mail``, on the host ``daffodil.mit.edu``. She -wants to encrypt the file transfer. The exchange would look like the -following:: - - shell% ftp daffodil.mit.edu - Connected to daffodil.mit.edu. - 220 daffodil.mit.edu FTP server (Version 5.60) ready. - 334 Using authentication type GSSAPI; ADAT must follow - GSSAPI accepted as authentication type - GSSAPI authentication succeeded - 200 Data channel protection level set to private. - Name (daffodil.mit.edu:jennifer): - 232 GSSAPI user jennifer@ATHENA.MIT.EDU is authorized as jennifer - 230 User jennifer logged in. - Remote system type is UNIX. - Using binary mode to transfer files. - ftp> protect private - 200 Protection level set to Private. - ftp> cd ~jennifer/MAIL - 250 CWD command successful. - ftp> get RMAIL - 227 Entering Passive Mode (128,0,0,5,16,49) - 150 Opening BINARY mode data connection for RMAIL (361662 bytes). - 226 Transfer complete. - 361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s) - ftp> quit - shell% diff --git a/doc/rst_source/krb_users/user_appl/index.rst b/doc/rst_source/krb_users/user_appl/index.rst deleted file mode 100644 index d984e29d8..000000000 --- a/doc/rst_source/krb_users/user_appl/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -Kerberized LINUX/UNIX applications -================================== - -.. 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. - -Kerberos V5 is a single-sign-on system. This means that you only have -to type your password once, and the Kerberos V5 programs do the -authenticating (and optionally encrypting) for you. The way this -works is that Kerberos has been built into each of a suite of network -programs. For example, when you use a Kerberos V5 program to connect -to a remote host, the program, the KDC, and the remote host perform a -set of rapid negotiations. When these negotiations are completed, -your program has proven your identity on your behalf to the remote -host, and the remote host has granted you access, all in the space of -a few seconds. - -The Kerberos V5 network programs are those programs that connect to -another host somewhere on the internet. These programs include -rlogin, telnet, ftp, rsh, rcp, and ksu. These programs have all of -the original features of the corresponding non-Kerberos rlogin, -telnet, ftp, rsh, rcp, and su programs, plus additional features that -transparently use your Kerberos tickets for negotiating authentication -and optional encryption with the remote host. In most cases, all -you'll notice is that you no longer have to type your password, -because Kerberos has already proven your identity. - -The Kerberos V5 network programs allow you the options of forwarding -your tickets to the remote host (if you obtained forwardable tickets -with the :ref:`kinit(1)` program; see :ref:`obtain_tkt`), and -encrypting data transmitted between you and the remote host. - -The Kerberos V5 applications are versions of existing UNIX network -programs with the Kerberos features added. - -.. toctree:: - :maxdepth: 1 - - telnet.rst - ftp.rst - rcp.rst - rlogin.rst - rsh.rst - ksu.rst - ssh.rst diff --git a/doc/rst_source/krb_users/user_appl/ksu.rst b/doc/rst_source/krb_users/user_appl/ksu.rst deleted file mode 100644 index fc04b5a85..000000000 --- a/doc/rst_source/krb_users/user_appl/ksu.rst +++ /dev/null @@ -1,145 +0,0 @@ -ksu -=== - -The Kerberos V5 :ref:`ksu(1)` program replaces the standard UNIX su -program (See ksu_vs_su_). ksu first authenticates you to Kerberos. -Depending on the configuration of your system, ksu may ask for your -Kerberos password if authentication fails. Note that you should never -type your password if you are remotely logged in using an unencrypted -connection. - -Once ksu has authenticated you, if your Kerberos principal appears in -the target's :ref:`.k5login(5)` file (see Granting Access to Your -Account) or in the target's .k5users file (see below), it switches -your user ID to the target user ID. - -For example, ``david`` has put ``jennifer``'s Kerberos principal in -his .k5login file. If ``jennifer`` uses ksu to become ``david``, the -exchange would look like this. (To differentiate between the two -shells, ``jennifer``'s prompt is represented as ``jennifer`` and -``david``'s prompt is represented as ``david``.):: - - jennifer% ksu david - Account david: authorization for jennifer@ATHENA.MIT.EDU successful - Changing uid to david (3382) - david% - -Note that the new shell has a copy of ``jennifer``'s tickets. The -ticket filename contains ``david``'s UID with .1 appended to it:: - - david% klist - Ticket cache: /tmp/krb5cc_3382.1 - Default principal: jennifer@ATHENA.MIT.EDU - - Valid starting Expires Service principal - 07/31/04 21:53:01 08/01/04 07:52:53 krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU - 07/31/04 21:53:39 08/01/04 07:52:53 host/daffodil.mit.edu@ATHENA.MIT.EDU - david% - -If ``jennifer`` had not appeared in ``david``'s .k5login file (and the -system was configured to ask for a password), the exchange would have -looked like this (assuming ``david`` has taken appropriate precautions -in protecting his password):: - - jennifer% ksu david - WARNING: Your password may be exposed if you enter it here and are logged in remotely using an unsecure (non-encrypted) channel. - Kerberos password for david@ATHENA.MIT.EDU: <- jennifer types the wrong password here. - ksu: Password incorrect - Authentication failed. - jennifer% - -Now, suppose ``david`` did not want to give ``jennifer`` full access -to his account, but wanted to give her permission to list his files -and use the "more" command to view them. He could create a .k5users -file giving her permission to run only those specific commands. - -The .k5users file is like the .k5login file, except that each -principal is optionally followed by a list of commands. ksu will let -those principals execute only the commands listed, using the -e -option. ``david``'s .k5users file might look like the following:: - - jennifer@ATHENA.MIT.EDU /bin/ls /usr/bin/more - joeadmin@ATHENA.MIT.EDU /bin/ls - joeadmin/admin@ATHENA.MIT.EDU * - david@EXAMPLE.COM - -The above .k5users file would let ``jennifer`` run only the commands -``/bin/ls`` and ``/usr/bin/more``. It would let ``joeadmin`` run only -the command ``/bin/ls`` if he had regular tickets, but if he had -tickets for his admin instance, ``joeadmin/admini@ATHENA.MIT.EDU``, he -would be able to execute any command. The last line gives ``david`` -in the realm ``EXAMPLE.COM`` permission to execute any command. -(I.e., having only a Kerberos principal on a line is equivalent to -giving that principal permission to execute ``*``.) This is so that -``david`` can allow himself to execute commands when he logs in, using -Kerberos, from a machine in the realm EXAMPLE.COM. - -Then, when ``jennifer`` wanted to list his home directory, she would type:: - - jennifer% ksu david -e ls ~david - Authenticated jennifer@ATHENA.MIT.EDU - Account david: authorization for jennifer@ATHENA.MIT.EDU for execution of /bin/ls successful - Changing uid to david (3382) - Mail News Personal misc bin - jennifer% - -If ``jennifer`` had tried to give a different command to ksu, it would -have prompted for a password as with the previous example. - -Note that unless the .k5users file gives the target permission to run -any command, the user must use ksu with the -e command option. - -The ksu options you are most likely to use are: - -=================== ==================================== --n *principal* specifies which Kerberos principal you want to use for ksu. - (e.g., the user *joeadmin* might want to use his admin instance.) --c specifies the location of your Kerberos credentials cache (ticket file). --k tells ksu not to destroy your Kerberos tickets when ksu is finished. --f requests forwardable tickets. (See :ref:`obtain_tkt`.) - This is only applicable if ksu needs to obtain tickets. --l *lifetime* sets the ticket lifetime. (See :ref:`obtain_tkt`.) - This is only applicable if ksu needs to obtain tickets. --z tells ksu to copy your Kerberos tickets only if the UID you are switching - is the same as the Kerberos primary - (either yours or the one specified by the **-n** option). --Z tells ksu not to copy any Kerberos tickets to the new UID. --e *command* tells ksu to execute command and then exit. - See the description of the .k5users file above. --a *text* (at the end of the command line) tells ksu to pass everything - after **-a** to the target shell. -=================== ==================================== - ----------------------------------- - -.. _ksu_vs_su: - -ksu vs su ---------- - -From from the discussion at -[http://mailman.mit.edu/pipermail/kerberos/2011-January/016886.html]: - -The main reason why we use ksu instead of su is because every person -who can su to root has their own separate ``/root`` principal with a -separate password and we want them to use those passwords instead. In -many cases, the set of people who know the actual root password is -more limited than the people who can ksu (perhaps because the formula -for it is shared with other systems those people should not be root -on, for instance). - -You can do this with su and an appropriate PAM configuration, or with -sudo and an appropriate PAM configuration, but it's fiddly and -annoying and it's often easier to just use ksu. Plus, you'd probably -have to use my pam-krb5 module rather than whatever came with your -system, since it would be extremely difficult to set this up without -the aid of the **alt_auth_map** configuration option. - -Don't need to leak my root password to client users - -Client users shall use ksu under local machine, not remote machines: -Ideally in Kerberos you never enter your password into any remote -system, but always authenticate locally and then use Kerberos to -authenticate to remote systems. We're moving in that way (by allowing -root logins only via GSSAPI), but the tradeoff is that you have to -allow remote direct root logins, which makes some a bit uncomfortable. diff --git a/doc/rst_source/krb_users/user_appl/rcp.rst b/doc/rst_source/krb_users/user_appl/rcp.rst deleted file mode 100644 index 99e6598ce..000000000 --- a/doc/rst_source/krb_users/user_appl/rcp.rst +++ /dev/null @@ -1,18 +0,0 @@ -rcp -=== - -The Kerberos V5 rcp program works exactly like the standard UNIX rcp -program, with the following Kerberos features added: - -============= ================ --k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself. --x turns on encryption. -============= ================ - -For example, if you wanted to copy the file ``/etc/motd`` from the -host ``daffodil.mit.edu`` into the current directory, via an encrypted -connection, you would simply type:: - - shell% rcp -x daffodil.mit.edu:/etc/motd . - -The rcp program negotiates authentication and encryption transparently. diff --git a/doc/rst_source/krb_users/user_appl/rlogin.rst b/doc/rst_source/krb_users/user_appl/rlogin.rst deleted file mode 100644 index 99539f851..000000000 --- a/doc/rst_source/krb_users/user_appl/rlogin.rst +++ /dev/null @@ -1,50 +0,0 @@ -rlogin -====== - -The Kerberos V5 *rlogin* command works exactly like the standard UNIX -*rlogin* program, with the following Kerberos options added: - -============= ================================================================================================================ --f forwards a copy of your tickets to the remote host. --F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host. --k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself. --x encrypts the input and output data streams (the username is sent unencrypted) -============= ================================================================================================================ - -For example, if ``david`` wanted to use the standard UNIX ``rlogin`` -to connect to the machine daffodil.example.com, he would type:: - - shell% rlogin daffodil.example.com -l david - Password: <- david types his password here - Last login: Fri Jun 21 10:36:32 from :0.0 - Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. - - NetBSD 1.1: Tue May 21 00:31:42 EDT 1996 - - Welcome to NetBSD! - shell% - -Note that the machine ``daffodil.example.com`` asked for *david*'s -password. When he typed it, his password was sent over the network -unencrypted. If an intruder were watching network traffic at the -time, that intruder would know ``david``'s password. - -If, on the other hand, ``jennifer`` wanted to use Kerberos V5 rlogin -to connect to the machine ``trillium.mit.edu``, she could forward a -copy of her tickets, mark them as not forwardable from the remote -host, and request an encrypted session as follows:: - - shell% rlogin trillium.mit.edu -f -x - This rlogin session is using DES encryption for all data transmissions. - Last login: Thu Jun 20 16:20:50 from daffodil - Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002 - shell% - -Note that ``jennifer``'s machine used Kerberos to authenticate her to -``trillium.mit.edu``, and logged her in automatically as herself. She -had an encrypted session, a copy of her tickets were waiting for her, -and she never typed her password. - -If you forwarded your Kerberos tickets, rlogin automatically destroys -them when it exits. diff --git a/doc/rst_source/krb_users/user_appl/rsh.rst b/doc/rst_source/krb_users/user_appl/rsh.rst deleted file mode 100644 index 81486ff36..000000000 --- a/doc/rst_source/krb_users/user_appl/rsh.rst +++ /dev/null @@ -1,24 +0,0 @@ -rsh -=== - -The Kerberos V5 rsh program works exactly like the standard UNIX -rlogin program, with the following Kerberos features added: - -========== ====================== --f forwards a copy of your tickets to the remote host. --F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host. --k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself. --x encrypts the input and output data streams (the command line is not encrypted) -========== ====================== - -For example, if your Kerberos tickets allowed you to run programs on -the host ``trillium@example.com`` as root, you could run the date -program as follows:: - - shell% rsh trillium.example.com -l root -x date - This rsh session is using DES encryption for all data transmissions. - Tue Jul 30 19:34:21 EDT 2002 - shell% - -If you forwarded your Kerberos tickets, rsh automatically destroys -them when it exits. diff --git a/doc/rst_source/krb_users/user_appl/ssh.rst b/doc/rst_source/krb_users/user_appl/ssh.rst deleted file mode 100644 index 54ceb81ca..000000000 --- a/doc/rst_source/krb_users/user_appl/ssh.rst +++ /dev/null @@ -1,12 +0,0 @@ -ssh -=== - -TODO - -#. Configuration - -#. Cross realm and *ssh* - -#. - -.. seealso:: man pages ssh_config and sshd_config diff --git a/doc/rst_source/krb_users/user_appl/telnet.rst b/doc/rst_source/krb_users/user_appl/telnet.rst deleted file mode 100644 index 1745cd703..000000000 --- a/doc/rst_source/krb_users/user_appl/telnet.rst +++ /dev/null @@ -1,65 +0,0 @@ -telnet -====== - -The Kerberos V5 telnet command works exactly like the standard UNIX -telnet program, with the following Kerberos options added: - -============== ========================================================================================================================== --f forwards a copy of your tickets to the remote host. --F forwards a copy of your tickets to the remote host, and marks them re-forwardable from the remote host. --k *realm* requests tickets for the remote host in the specified realm, instead of determining the realm itself. --K uses your tickets to authenticate to the remote host, but does not log you in. --a attempt automatic login using your tickets. telnet will assume the same username unless you explicitly specify another. --x turns on encryption. -============== ========================================================================================================================== - -For example, if david wanted to use the standard UNIX telnet to -connect to the machine daffodil.mit.edu, he would type:: - - shell% telnet daffodil.example.com - Trying 128.0.0.5 ... - Connected to daffodil.example.com. - Escape character is '^]'. - - NetBSD/i386 (daffodil) (ttyp3) - - login: david - Password: <- david types his password here - Last login: Fri Jun 21 17:13:11 from trillium.mit.edu - Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 - The Regents of the University of California. All rights reserved. - - NetBSD 1.1: Tue May 21 00:31:42 EDT 1996 - - Welcome to NetBSD! - shell% - -Note that the machine ``daffodil.example.com`` asked for *david*'s -password. When he typed it, his password was sent over the network -unencrypted. If an intruder were watching network traffic at the -time, that intruder would know david's password. - -If, on the other hand, ``jennifer`` wanted to use the Kerberos V5 -telnet to connect to the machine ``trillium.mit.edu``, she could -forward a copy of her tickets, request an encrypted session, and log -on as herself as follows:: - - shell% telnet -a -f -x trillium.mit.edu - Trying 128.0.0.5... - Connected to trillium.mit.edu. - Escape character is '^]'. - [ Kerberos V5 accepts you as ``jennifer@mit.edu'' ] - [ Kerberos V5 accepted forwarded credentials ] - What you type is protected by encryption. - Last login: Tue Jul 30 18:47:44 from daffodil.example.com - Athena Server (sun4) Version 9.1.11 Tue Jul 30 14:40:08 EDT 2002 - - shell% - -Note that ``jennifer``'s machine used Kerberos to authenticate her to -``trillium.mit.edu``, and logged her in automatically as herself. She -had an encrypted session, a copy of her tickets already waiting for -her, and she never typed her password. - -If you forwarded your Kerberos tickets, telnet automatically destroys -them when it exits.