From owner-svn-doc-head@FreeBSD.ORG Thu May 15 02:46:04 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id C044E156; Thu, 15 May 2014 02:46:04 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id AC2B7265F; Thu, 15 May 2014 02:46:04 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s4F2k4u6007734; Thu, 15 May 2014 02:46:04 GMT (envelope-from bjk@svn.freebsd.org) Received: (from bjk@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s4F2k4vm007732; Thu, 15 May 2014 02:46:04 GMT (envelope-from bjk@svn.freebsd.org) Message-Id: <201405150246.s4F2k4vm007732@svn.freebsd.org> From: Benjamin Kaduk Date: Thu, 15 May 2014 02:46:04 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44840 - head/en_US.ISO8859-1/books/handbook/security X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 15 May 2014 02:46:04 -0000 Author: bjk Date: Thu May 15 02:46:04 2014 New Revision: 44840 URL: http://svnweb.freebsd.org/changeset/doc/44840 Log: Technical review of the Kerberos chapter Many of the statements in this chapter were just plain wrong. Apply some major modernization, in particular the current Kerberos RFC is 4120, not 1510. Kerberized telnet, rlogin, ftp and similar are no longer recommended -- use ssh and scp instead. The heimdal in base is no longer crippled so as to be a minimal installation; it is fully functional. The heimdal in ports does offer the option to install some additional features such as KCM and PKINIT. Add a bit more introduction to Kerberos terminology and conventions. Make the sample output closer to the current reality. Don't imply that eight characters is a particularly strong password. security/krb5 does not install ktelnetd, klogind, and friends anymore, so there's no need to mention its README.FreeBSD here (especially since these things are disrecommended anyway). www/mod_auth_kerb uses the HTTP/ principal, not the www/ principal. Kerberized ssh uses GSSAPI these days, so the Kerberos-specific options are not worth mentioning. Kerberos works just fine on multiuser machines; the permissions of credentials cache files are set to 0600. Remove the section on access issues with kerberos and ssh; it is very confused. (It seems to be talking about ssh keys and ssh-agent, but in a very unclear and inaccurate fashion.) There is still more to be done here, but this should get us most of the way. Reviewed by: bcr (partial) Approved by: hrs (mentor) Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/security/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu May 15 00:43:23 2014 (r44839) +++ head/en_US.ISO8859-1/books/handbook/security/chapter.xml Thu May 15 02:46:04 2014 (r44840) @@ -1095,10 +1095,11 @@ sendmail : PARANOID : denyKerberos is a network authentication protocol which was originally created by the Massachusetts Institute of Technology - (MIT) as a solution to network security - problems. The Kerberos protocol uses + (MIT) as a way to securely provide authentication + across a potentially hostile network. + The Kerberos protocol uses strong cryptography so that both a client and server can prove - their identity over an insecure network. + their identity without sending any unencrypted secrets over the network. Kerberos can be described as an identity-verifying proxy system and as a trusted third-party authentication system. After a user authenticates with @@ -1106,29 +1107,36 @@ sendmail : PARANOID : deny The only function of Kerberos is - to provide the secure authentication of users on the network. + to provide the secure authentication of users and servers on the network. It does not provide authorization or auditing functions. It is recommended that Kerberos be used with other security methods which provide authorization and audit services. The current version of the protocol is version 5, described - in RFC 1510. Several free + in RFC 4120. Several free implementations of this protocol are available, covering a wide range of operating systems. MIT continues to develop their Kerberos package. It is commonly used in the US as a cryptography - product, and has historically been affected by + product, and has historically been subject to US export regulations. In &os;, MIT Kerberos is available as the security/krb5 package or - port. Heimdal Kerberos was + port. The Heimdal Kerberos implementation was explicitly developed outside of the US to avoid export regulations. The Heimdal - Kerberos distribution is available as - the security/heimdal package or port, and a - minimal installation is included in the base &os; - install. + Kerberos distribution is included in + the base &os; installation, and another distribution with more + configurable options is available as security/heimdal + in the Ports Collection. + + In Kerberos users and services are + identified as principals which are contained within + an administrative grouping, called a realm. A + typical user principal would be of the form + user@REALM + (realms are traditionally uppercase). This section provides a guide on how to set up Kerberos using the Heimdal @@ -1169,12 +1177,14 @@ sendmail : PARANOID : denyThe Key Distribution Center (KDC) is the centralized authentication service that - Kerberos provides. It is the + Kerberos provides, the trusted + third party of the system. It is the computer that issues Kerberos - tickets. The KDC is considered trusted by + tickets, which are used for clients to authenticate to servers. + Because the KDC is considered trusted by all other computers in the - Kerberos realm, and thus has - heightened security concerns. + Kerberos realm, it has heightened security + concerns. Direct access to the KDC should be limited. While running a KDC requires few computing resources, a dedicated machine acting only as a @@ -1202,20 +1212,23 @@ kadmind5_server_enable="YES"In this example, the KDC will use the fully-qualified hostname kerberos.example.org. Add - a CNAME entry to the DNS - zone file if the KDC has a different - hostname than that specified in - /etc/krb5.conf. - - For large networks with a properly configured - DNS server, the above example could be - trimmed to: + class="fqdomainname">kerberos.example.org. The + hostname of the KDC must be resolvable in the + DNS. + + Kerberos can also use the + DNS to locate KDCs, instead of a + [realms] section in + /etc/krb5.conf. For large organizations that + have their own DNS servers, the above example + could be trimmed to: [libdefaults] - default_realm = EXAMPLE.ORG + default_realm = EXAMPLE.ORG +[domain_realm] + .example.org = EXAMPLE.ORG - With the following lines being appended to the + With the following lines being included in the example.org zone file: @@ -1227,8 +1240,8 @@ _kerberos IN TXT In order for clients to be able to find the - Kerberos services, the - KDC must have either + Kerberos services, they + must have either a fully configured /etc/krb5.conf or a minimally configured /etc/krb5.conf and a properly configured @@ -1239,20 +1252,22 @@ _kerberos IN TXT /var/heimdal/m-key. To create the master - key, run kstash and enter a + /var/heimdal/m-key; it would be reasonable to + use a 45-character random password for this purpose. To create the + master key, run kstash and enter a password: &prompt.root; kstash -Master key: xxxxxxxx -Verifying password - Master key: xxxxxxxx +Master key: xxxxxxxxxxxxxxxxxxxxxxx +Verifying password - Master key: xxxxxxxxxxxxxxxxxxxxxxx - Once the master key has been created, initialize the - database using kadmin -l. This option - instructs kadmin to modify the local - database files directly rather than going through the - &man.kadmind.8; network service. This handles the - chicken-and-egg problem of trying to connect to the database + Once the master key has been created, the database should be + initialized. The Kerberos administrative + tool &man.kadmin.8; can be used on the KDC in a mode that + operates directly on the database, without using the &man.kadmind.8; + network service, as kadmin -l. + This resolves the chicken-and-egg problem of trying to connect to + the database before it is created. At the kadmin prompt, use init to create the realm's initial database: @@ -1280,21 +1295,22 @@ Verifying password - Password: service kadmind start. While there will not be any kerberized daemons running at this point, it is possible to confirm that the KDC is - functioning by obtaining and listing a ticket for the - principal that was just created from the command-line of the - KDC: + functioning by obtaining a ticket for the + principal that was just created: &prompt.user; kinit tillman tillman@EXAMPLE.ORG's Password: - -&prompt.user; klist -Credentials cache: FILE:/tmp/krb5cc_500 + + Confirm that a ticket was successfully obtained using + klist: + &prompt.user; klist +Credentials cache: FILE:/tmp/krb5cc_1001 Principal: tillman@EXAMPLE.ORG - Issued Expires Principal -Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG + Issued Expires Principal +Aug 27 15:37:58 2013 Aug 28 01:37:58 2013 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG - The temporary ticket can be revoked when the test is + The temporary ticket can be destroyed when the test is finished: &prompt.user; kdestroy @@ -1309,87 +1325,98 @@ Aug 27 15:37:58 Aug 28 01:37:58 krbtgt enabling services - To configure a server to use - Kerberos authentication, copy - /etc/krb5.conf from the - KDC to the server in a secure fashion, such - as &man.scp.1;, or physically via removable media. + The first step in configuring a server to use + Kerberos authentication is to + ensure that it has the correct configuration in + /etc/krb5.conf. The version from the + KDC can be used as-is, or it can be + regenerated on the new system. Next, create /etc/krb5.keytab on the - server. This is the major difference between a server - providing Kerberos enabled daemons - and a workstation: the server must have a - keytab. This file contains the server's - host key, which allows it and the KDC to - verify each others identity. It must be transmitted to the + server. This is the main part of Kerberizing a service + — it corresponds to generating a secret shared between the + service and the KDC. The secret is a cryptographic + key, stored in a keytab. The keytab contains + the server's host key, which allows it and the KDC + to verify each others' identity. It must be transmitted to the server in a secure fashion, as the security of the server can be broken if the key is made public. Typically, the - keytab is transferred to the server using - kadmin. This is handy because the host - principal, the KDC end of the - krb5.keytab, is also created using + keytab is generated on an administrator's + trusted machine using kadmin, then securely + transferred to the server, e.g., with &man.scp.1;; it can also + be created directly on the server if that is consistent with + the desired security policy. It is very important that the + keytab is transmitted to the server in a secure fashion: if + the key is known by some other party, that party can impersonate + any user to the server! Using kadmin on the + server directly is convenient, because the entry for the host + principal in the KDC database is also created using kadmin. - A ticket must first be obtained and this ticket must be - allowed to use the kadmin interface in the + Of course, kadmin is a kerberized service; + a Kerberos ticket is needed to authenticate + to the network service, but to ensure that the user running + kadmin is actually present (and their session has + not been hijacked), kadmin will prompt for the + password to get a fresh ticket. The principal authenticating + to the kadmin service must be permitted to use the + kadmin interface, as specified in kadmind.acl. See the section titled Remote administration in info heimdal for details on designing access control lists. Instead of enabling remote kadmin - access, the administrator can securely connect to the + access, the administrator could securely connect to the KDC via the local console or &man.ssh.1;, and perform administration locally using kadmin -l. After installing /etc/krb5.conf, - use add --random-key from the - Kerberos server. This adds the - server's host principal. Then, use ext to - extract the server's host principal to its own keytab: + use add --random-key in kadmin. + This adds the server's host principal to the database, but does not + extract a copy of the host principal key to a keytab. To generate + the keytab, use ext to extract the server's host + principal key to its own keytab: &prompt.root; kadmin kadmin> add --random-key host/myserver.example.org Max ticket life [unlimited]: Max renewable life [unlimited]: +Principal expiration time [never]: +Password expiration time [never]: Attributes []: -kadmin> ext host/myserver.example.org +kadmin> ext_keytab host/myserver.example.org kadmin> exit - Note that ext stores the extracted key - in /etc/krb5.keytab by default. - - If &man.kadmind.8; is not running on the - KDC and there is no access to - &man.kadmin.8; remotely, add the server's host principal - directly on the KDC and then extract it to - a temporary file to avoid overwriting the - /etc/krb5.keytab on the - KDC: + Note that ext_keytab stores the extracted key + in /etc/krb5.keytab by default. This is + good when being run on the server being kerberized, but the + --keytab path/to/file + argument should be used when the keytab is being extracted + elsewhere: &prompt.root; kadmin -kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org +kadmin> ext_keytab --keytab=/tmp/example.keytab host/myserver.example.org kadmin> exit The keytab can then be securely copied to the server using &man.scp.1; or a removable media. Be sure to specify a - non-default keytab name to avoid overwriting the keytab on the - KDC. + non-default keytab name to avoid inserting unneeded keys into the + system's keytab. - At this point, the server can communicate with the - KDC using - krb5.conf and it can prove its own - identity with krb5.keytab. It is now - ready for the Kerberos services to - be enabled. For this example, the &man.telnetd.8; service is - enabled in /etc/inetd.conf and - &man.inetd.8; has been restarted with service inetd - restart: - - telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user - - The critical change is that the - authentication type is set to user. Refer to &man.telnetd.8; - for more details. + At this point, the server can read encrypted messages from the + KDC using its shared key, stored in + krb5.keytab. It is now + ready for the Kerberos-using services to + be enabled. One of the most common such services is &man.sshd.8;, + which supports Kerberos via the + GSS-API. In + /etc/ssh/sshd_config, add the line: + + GSSAPIAuthentication yes + + After making this change, &man.sshd.8; must be restared for + the new configuration to take effect: service sshd + restart. @@ -1401,36 +1428,34 @@ kadmin> exitconfigure clients - To configure a client to use - Kerberos, securely copy - /etc/krb5.conf to the client computer - from the KDC. + As it was for the server, the client requires configuration in + /etc/krb5.conf. Copy the file in place + (securely) or re-enter it as needed. Test the client by using kinit, klist, and kdestroy from - the client to obtain, show, and then delete an existing ticket - for the principal. Kerberos + the client to obtain, show, and then delete a ticket + for an existing principal. Kerberos applications should also be able to connect to Kerberos enabled servers. If that does not work but obtaining a ticket does, the problem is likely with the server and not with the client or the - KDC. + KDC. In the case of kerberized &man.ssh.1;, + GSS-API is disabled by default, so test using + ssh -o GSSAPIAuthentication=yes + hostname. When testing a Kerberized application, try using a packet - sniffer such as tcpdump to confirm that the - password is not sent in the clear. + sniffer such as tcpdump to confirm that no + sensitive information is sent in the clear. Various Kerberos client - applications are available. &os; installs - telnetd as the only - Kerberos enabled service. The - Heimdal package or port installs - Kerberos enabled versions of - ftpd, rshd, - rcp, rlogind, and a few - other less common programs. The MIT port - contains a full suite of Kerberos - client applications. + applications are available. With the advent of a bridge so that + applications using SASL for authentication can + use GSS-API mechanisms as well, large classes + of client applications can use Kerberos + for authentication, from Jabber clients to IMAP + clients. .k5login @@ -1489,20 +1514,8 @@ jdoe@example.org MIT versions if PATH lists the system directories first. - - With the &os; MIT - security/krb5 port, be sure to read - /usr/local/share/doc/krb5/README.FreeBSD - installed by the port to understand why logins via - telnetd and klogind - behave somewhat oddly. Correcting the incorrect - permissions on cache file behavior requires that - the login.krb5 binary be used for - authentication so that it can properly change ownership for - the forwarded credentials. - - - The following edits should also be made to + When using MIT Kerberos as a KDC on &os;, + the following edits should also be made to rc.conf: kerberos5_server="/usr/local/sbin/krb5kdc" @@ -1523,9 +1536,8 @@ kadmind5_server_enable="YES" When using either Heimdal or MIT - Kerberos, ensure that the - PATH lists the - Kerberos versions of the + Kerberos from ports, ensure that the + PATH lists the port's versions of the client applications before the system versions. @@ -1541,7 +1553,7 @@ kadmind5_server_enable="YES"host/ principal must be changed and the keytab updated. This also applies to special keytab entries like the www/ principal used for + class="username">HTTP/ principal used for Apache's www/mod_auth_kerb. @@ -1570,8 +1582,8 @@ kadmind5_server_enable="YES"With MIT Kerberos, to allow a principal to have a ticket life longer than the default - ten hours, use modify_principal at the - &man.kadmin.8; prompt to change the + lifetime of ten hours, use modify_principal + at the &man.kadmin.8; prompt to change the maxlife of both the principal in question and the krbtgt principal. The @@ -1607,17 +1619,6 @@ kadmind5_server_enable="YES" - To use long ticket lifetimes when using - OpenSSH to connect to the - machine where the ticket is stored, make sure that - Kerberos - is set to - no in - /etc/ssh/sshd_config. Otherwise, - tickets will be deleted at log out. - - - Host principals can have a longer ticket lifetime. If the user principal has a lifetime of a week but the host being connected to has a lifetime of nine hours, the user @@ -1658,20 +1659,6 @@ kadmind5_server_enable="YES"POP3 mail server sends passwords in plain text. - Kerberos is intended for - single-user workstations. In a multi-user environment, - Kerberos is less secure as it - stores the tickets in /tmp, which is - readable by all users. If a user is sharing a computer, it is - possible that the user's tickets can be stolen or copied by - another user. - - This can be overcome with kinit -c or, - preferably, the KRB5CCNAME environment - variable. Storing the ticket in the user's home directory and - using file permissions are commonly used to mitigate this - problem. - The KDC is a single point of failure. By design, the KDC must be as secure as its master password database. The KDC should @@ -1706,45 +1693,6 @@ kadmind5_server_enable="YES" - Access Issues with Kerberos and - <command>ssh</command> - - &man.ssh.1; - - Kerberos is an excellent authentication protocol, but - there are bugs in the Kerberized versions of - telnet and rlogin that - make them unsuitable for dealing with binary streams. By - default, Kerberos does not encrypt a session unless - is used, whereas ssh - encrypts everything. - - While ssh works well, it forwards - encryption keys by default. This introduces a security risk - to a user who uses ssh to access an - insecure machine from a secure workstation. The keys - themselves are not exposed, but ssh - installs a forwarding port for the duration of the login. If - an attacker has broken root on the insecure machine, - he can utilize that port to gain access to any other machine - that those keys unlock. - - It is recommended that ssh is used in - combination with Kerberos whenever possible for staff logins - as it can be compiled with Kerberos support. This reduces - reliance on potentially exposed SSH keys - while protecting passwords via Kerberos. Keys should only be - used for automated tasks from secure machines as this is - something that Kerberos is unsuited to. It is recommended to - either turn off key-forwarding in the - SSH configuration, or to make use of - from=IP/DOMAIN in - authorized_keys to make the key only - usable to entities logging in from specific machines. - - - Resources and Further Information @@ -1769,8 +1717,8 @@ kadmind5_server_enable="YES" RFC - 1510, The Kerberos Network + xlink:href="http://www.ietf.org/rfc/rfc4120.txt?number=4120">RFC + 4120, The Kerberos Network Authentication Service (V5)