import of heimdal 0.3f

10 files changed, 1041 insertions, 18 deletions

diff --git a/crypto/heimdal/doc/Makefile.in b/crypto/heimdal/doc/Makefile.in
index 2638ef1..ffc5d89 100644
--- a/crypto/heimdal/doc/Makefile.in
+++ b/crypto/heimdal/doc/Makefile.in
@@ -1,6 +1,7 @@
-# Makefile.in generated automatically by automake 1.4a from Makefile.am
+# Makefile.in generated automatically by automake 1.4b from Makefile.am
 
-# Copyright (C) 1994, 1995-9, 2000 Free Software Foundation, Inc.
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000
+# Free Software Foundation, Inc.
 # This Makefile.in is free software; the Free Software Foundation
 # gives unlimited permission to copy and/or distribute it,
 # with or without modifications, as long as this notice is preserved.
@@ -119,7 +120,7 @@ install_sh = @install_sh@
 # $Id: Makefile.am.common,v 1.3 1999/04/01 14:58:43 joda Exp $
 
 
-# $Id: Makefile.am.common,v 1.23 2000/12/05 09:11:09 joda Exp $
+# $Id: Makefile.am.common,v 1.26 2001/05/21 13:27:48 joda Exp $
 
 
 AUTOMAKE_OPTIONS = foreign no-dependencies no-texinfo.tex
@@ -185,6 +186,8 @@ NROFF_MAN = groff -mandoc -Tascii
 @KRB5_TRUE@	$(top_builddir)/lib/asn1/libasn1.la
 @KRB5_TRUE@LIB_gssapi = @KRB5_TRUE@$(top_builddir)/lib/gssapi/libgssapi.la
 
+@DCE_TRUE@LIB_kdfs = @DCE_TRUE@$(top_builddir)/lib/kdfs/libkdfs.la
+
 CHECK_LOCAL = $(PROGRAMS)
 
 info_TEXINFOS = heimdal.texi
@@ -212,7 +215,7 @@ DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
 GZIP_ENV = --best
 all: all-redirect
 .SUFFIXES:
-.SUFFIXES: .1 .3 .5 .8 .cat1 .cat3 .cat5 .cat8 .dvi .et .h .info .ps .texi .texinfo .txi .x
+.SUFFIXES: .et .h .1 .3 .5 .8 .cat1 .cat3 .cat5 .cat8 .x .dvi .info .ps .texi .texinfo .txi
 $(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.in $(ACLOCAL_M4) $(top_srcdir)/Makefile.am.common $(top_srcdir)/cf/Makefile.am.common
 	cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile
 
diff --git a/crypto/heimdal/doc/ack.texi b/crypto/heimdal/doc/ack.texi
index eedbc53..fe0113e 100644
--- a/crypto/heimdal/doc/ack.texi
+++ b/crypto/heimdal/doc/ack.texi
@@ -1,6 +1,6 @@
-@c $Id: ack.texi,v 1.13 2001/01/30 01:57:31 assar Exp $
+@c $Id: ack.texi,v 1.14 2001/02/24 05:09:23 assar Exp $
 
-@node  Acknowledgments, , Windows 2000 compatability, Top
+@node  Acknowledgments, , Migration, Top
 @comment  node-name,  next,  previous,  up
 @appendix Acknowledgments
 
diff --git a/crypto/heimdal/doc/heimdal.texi b/crypto/heimdal/doc/heimdal.texi
index 3d9d4cd..6bc92a9 100644
--- a/crypto/heimdal/doc/heimdal.texi
+++ b/crypto/heimdal/doc/heimdal.texi
@@ -1,6 +1,6 @@
 \input texinfo @c -*- texinfo -*-
 @c %**start of header
-@c $Id: heimdal.texi,v 1.16 2000/07/28 15:43:36 assar Exp $
+@c $Id: heimdal.texi,v 1.17 2001/02/24 05:09:24 assar Exp $
 @setfilename heimdal.info
 @settitle HEIMDAL
 @iftex
@@ -15,7 +15,7 @@
 @c %**end of header
 
 @c not yet @include version.texi
-@set UPDATED $Date: 2000/07/28 15:43:36 $
+@set UPDATED $Date: 2001/02/24 05:09:24 $
 @set EDITION 0.1
 @set VERSION 0.3a
 
@@ -227,6 +227,7 @@ to the following restrictions:
 * Things in search for a better place::  
 * Kerberos 4 issues::           
 * Windows 2000 compatability::
+* Programming with Kerberos::
 * Migration::
 * Acknowledgments::             
 
@@ -238,8 +239,9 @@ to the following restrictions:
 @include setup.texi
 @include misc.texi
 @include kerberos4.texi
-@include migration.texi
 @include win2k.texi
+@include programming.texi
+@include migration.texi
 @include ack.texi
 
 @c @shortcontents
diff --git a/crypto/heimdal/doc/kerberos4.texi b/crypto/heimdal/doc/kerberos4.texi
index 92614c8..613e352 100644
--- a/crypto/heimdal/doc/kerberos4.texi
+++ b/crypto/heimdal/doc/kerberos4.texi
@@ -1,6 +1,6 @@
-@c $Id: kerberos4.texi,v 1.12 2001/01/30 17:07:03 assar Exp $
+@c $Id: kerberos4.texi,v 1.13 2001/02/24 05:09:24 assar Exp $
 
-@node Kerberos 4 issues, Migration, Things in search for a better place, Top
+@node Kerberos 4 issues, Windows 2000 compatability, Things in search for a better place, Top
 @comment  node-name,  next,  previous,  up
 @chapter Kerberos 4 issues
 
diff --git a/crypto/heimdal/doc/migration.texi b/crypto/heimdal/doc/migration.texi
index 90deed7..67b843a 100644
--- a/crypto/heimdal/doc/migration.texi
+++ b/crypto/heimdal/doc/migration.texi
@@ -1,6 +1,6 @@
-@c $Id: migration.texi,v 1.2 2001/01/28 22:03:36 assar Exp $
+@c $Id: migration.texi,v 1.3 2001/02/24 05:09:24 assar Exp $
 
-@node Migration, Windows 2000 compatability, Kerberos 4 issues, Top
+@node Migration, Acknowledgments, Programming with Kerberos, Top
 @chapter Migration
 
 @section General issues
diff --git a/crypto/heimdal/doc/misc.texi b/crypto/heimdal/doc/misc.texi
index 994f6f2..8b3f980 100644
--- a/crypto/heimdal/doc/misc.texi
+++ b/crypto/heimdal/doc/misc.texi
@@ -1,4 +1,4 @@
-@c $Id: misc.texi,v 1.5 2001/01/28 22:11:23 assar Exp $
+@c $Id: misc.texi,v 1.6 2001/02/24 05:09:24 assar Exp $
 
 @node Things in search for a better place, Kerberos 4 issues, Setting up a realm, Top
 @chapter Things in search for a better place
@@ -56,3 +56,9 @@ protocol.
 A working solution would be to hook up a machine with a real operating
 system to the console of the Cisco and then use it as a backwards
 terminal server.
+
+@section Making things work on Transarc AFS
+
+@subsection How to get a KeyFile
+
+@file{ktutil -k AFSKEYFILE:KeyFile get afs@@MY.REALM}
diff --git a/crypto/heimdal/doc/programming.texi b/crypto/heimdal/doc/programming.texi
new file mode 100644
index 0000000..ffcac21
--- /dev/null
+++ b/crypto/heimdal/doc/programming.texi
@@ -0,0 +1,287 @@
+@c $Id: programming.texi,v 1.2 2001/05/16 22:11:00 assar Exp $
+
+@node Programming with Kerberos
+@chapter Programming with Kerberos
+
+First you need to know how the Kerberos model works, go read the
+introduction text (@pxref{What is Kerberos?}).
+
+@macro manpage{man, section}
+@cite{\man\(\section\)}
+@end macro
+
+@menu
+* Kerberos 5 API Overview::     
+* Walkthru a sample Kerberos 5 client::  
+* Validating a password in a server application::  
+@end menu
+
+@node Kerberos 5 API Overview, Walkthru a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos
+@section Kerberos 5 API Overview
+
+Most functions are documenteded in manual pages.  This overview only
+tries to point to where to look for a specific function.
+
+@subsection Kerberos context
+
+A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that
+are context specific are stored in this struture, including default
+encryption types, credential-cache (ticket file), and default realms.
+
+See the manual pages for @manpage{krb5_context,3} and
+@manpage{krb5_init_context,3}.
+
+@subsection Kerberos authenication context
+
+Kerberos authentication context (@code{krb5_auth_context}) holds all
+context related to an authenticated connection, in a similar way to the
+kerberos context that holds the context for the thread or process.
+
+The @code{krb5_auth_context} is used by various functions that are
+directly related to authentication between the server/client. Example of
+data that this structure contains are various flags, addresses of client
+and server, port numbers, keyblocks (and subkeys), sequence numbers,
+replay cache, and checksum types.
+
+See the manual page for @manpage{krb5_auth_context,3}.
+
+@subsection Keytab managment
+
+A keytab is a storage for locally stored keys. Heimdal includes keytab
+support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's,
+and for storing keys in memory.
+
+See also manual page for @manpage{krb5_keytab,3}
+
+@node Walkthru a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos
+@section Walkthru a sample Kerberos 5 client
+
+This example contains parts of a sample TCP Kerberos 5 clients, if you
+want a real working client, please look in @file{appl/test} directory in
+the Heimdal distribution.
+
+All Kerberos error-codes that are returned from kerberos functions in
+this program are passed to @code{krb5_err}, that will print a
+descriptive text of the error code and exit. Graphical programs can
+convert error-code to a humal readable error-string with the
+@manpage{krb5_get_err_text,3} function.
+
+Note that you should not use any Kerberos function before
+@code{krb5_init_context()} have completed successfully. That is the
+reson @code{err()} is used when @code{krb5_init_context()} fails.
+
+First the client needs to call @code{krb5_init_context} to initialize
+the Kerberos 5 library. This is only needed once per thread
+in the program. If the function returns a non-zero value it indicates
+that either the Kerberos implemtation is failing or its disabled on
+this host.
+
+@example
+#include <krb5.h>
+
+int
+main(int argc, char **argv)
+@{
+        krb5_context context;
+
+        if (krb5_context(&context))
+                errx (1, "krb5_context");
+@end example
+
+Now the client wants to connect to the host at the other end. The
+preferred way of doing this is using @manpage{getaddrinfo,3} (for
+operating system that have this function implemented), since getaddrinfo
+is neutral to the address type and can use any protocol that is available.
+
+@example
+        struct addrinfo *ai, *a;
+        struct addrinfo hints;
+        int error;
+
+        memset (&hints, 0, sizeof(hints));
+        hints.ai_socktype = SOCK_STREAM;
+        hints.ai_protocol = IPPROTO_TCP;
+
+        error = getaddrinfo (hostname, "pop3", &hints, &ai);
+        if (error)
+                errx (1, "%s: %s", hostname, gai_strerror(error));
+
+        for (a = ai; a != NULL; a = a->ai_next) @{
+                int s;
+
+                s = socket (a->ai_family, a->ai_socktype, a->ai_protocol);
+                if (s < 0)
+                        continue;
+                if (connect (s, a->ai_addr, a->ai_addrlen) < 0) @{
+                        warn ("connect(%s)", hostname);
+                            close (s);
+                            continue;
+                @}
+                freeaddrinfo (ai);
+                ai = NULL;
+        @}
+        if (ai) @{
+                    freeaddrinfo (ai);
+                    errx ("failed to contact %s", hostname);
+        @}
+@end example
+
+Before authenticating, an authentication context needs to be
+created. This context keeps all information for one (to be) authenticated
+connection (see @manpage{krb5_auth_context,3}).
+
+@example
+        status = krb5_auth_con_init (context, &auth_context);
+        if (status)
+                krb5_err (context, 1, status, "krb5_auth_con_init");
+@end example
+
+For setting the address in the authentication there is a help function
+@code{krb5_auth_con_setaddrs_from_fd} that does everthing that is needed
+when given a connected file descriptor to the socket.
+
+@example
+        status = krb5_auth_con_setaddrs_from_fd (context,
+                                                 auth_context,
+                                                 &sock);
+        if (status)
+                krb5_err (context, 1, status, 
+                          "krb5_auth_con_setaddrs_from_fd");
+@end example
+
+The next step is to build a server principal for the service we want
+to connect to. (See also @manpage{krb5_sname_to_principal,3}.)
+
+@example
+        status = krb5_sname_to_principal (context,
+                                          hostname,
+                                          service,
+                                          KRB5_NT_SRV_HST,
+                                          &server);
+        if (status)
+                krb5_err (context, 1, status, "krb5_sname_to_principal");
+@end example
+
+The client principal is not passed to @manpage{krb5_sendauth,3}
+function, this causes the @code{krb5_sendauth} function to try to figure it
+out itself.
+
+The server program is using the function @manpage{krb5_recvauth,3} to
+receive the Kerberos 5 authenticator.
+
+In this case, mutual authenication will be tried. That means that the server
+will authenticate to the client. Using mutual authenication
+is good since it enables the user to verify that they are talking to the
+right server (a server that knows the key).
+
+If you are using a non-blocking socket you will need to do all work of
+@code{krb5_sendauth} yourself. Basically you need to send over the
+authenticator from @manpage{krb5_mk_req,3} and, in case of mutual
+authentication, verifying the result from the server with
+@manpage{krb5_rd_rep,3}.
+
+@example
+        status = krb5_sendauth (context,
+                                &auth_context,
+                                &sock,
+                                VERSION,
+                                NULL,
+                                server,
+                                AP_OPTS_MUTUAL_REQUIRED,
+                                NULL,
+                                NULL,
+                                NULL,
+                                NULL,
+                                NULL,
+                                NULL);
+        if (status)
+                krb5_err (context, 1, status, "krb5_sendauth");
+@end example
+
+Once authentication has been performed, it is time to send some
+data. First we create a krb5_data structure, then we sign it with
+@manpage{krb5_mk_safe,3} using the @code{auth_context} that contains the
+session-key that was exchanged in the
+@manpage{krb5_sendauth,3}/@manpage{krb5_recvauth,3} authentication
+sequence.
+
+@example
+        data.data   = "hej";
+        data.length = 3;
+
+        krb5_data_zero (&packet);
+
+        status = krb5_mk_safe (context,
+                               auth_context,
+                               &data,
+                               &packet,
+                               NULL);
+        if (status)
+                krb5_err (context, 1, status, "krb5_mk_safe");
+@end example
+
+And send it over the network.
+
+@example
+        len = packet.length;
+        net_len = htonl(len);
+
+        if (krb5_net_write (context, &sock, &net_len, 4) != 4)
+                err (1, "krb5_net_write");
+        if (krb5_net_write (context, &sock, packet.data, len) != len)
+                err (1, "krb5_net_write");
+@end example
+
+To send encrypted (and signed) data @manpage{krb5_mk_priv,3} should be
+used instead. @manpage{krb5_mk_priv,3} works the same way as
+@manpage{krb5_mk_safe,3}, with the exception that it encrypts the data
+in addition to signing it.
+
+@example
+        data.data   = "hemligt";
+        data.length = 7;
+
+        krb5_data_free (&packet);
+
+        status = krb5_mk_priv (context,
+                               auth_context,
+                               &data,
+                               &packet,
+                               NULL);
+        if (status)
+                krb5_err (context, 1, status, "krb5_mk_priv");
+@end example
+
+And send it over the network.
+
+@example
+        len = packet.length;
+        net_len = htonl(len);
+
+        if (krb5_net_write (context, &sock, &net_len, 4) != 4)
+                err (1, "krb5_net_write");
+        if (krb5_net_write (context, &sock, packet.data, len) != len)
+                err (1, "krb5_net_write");
+
+@end example
+
+The server is using @manpage{krb5_rd_safe,3} and
+@manpage{krb5_rd_priv,3} to verify the signature and decrypt the packet.
+
+@node Validating a password in a server application,  , Walkthru a sample Kerberos 5 client, Programming with Kerberos
+@section Validating a password in an application
+
+See the manual page for @manpage{krb5_verify_user,3}.
+
+@c @node Why you should use GSS-API for new applications, Walkthru a sample GSS-API client, Validating a password in a server application, Programming with Kerberos
+@c @section Why you should use GSS-API for new applications
+@c 
+@c SSPI, bah, bah, microsoft, bah, bah, almost GSS-API.
+@c 
+@c It would also be possible for other mechanisms then Kerberos, but that
+@c doesn't exist any other GSS-API implementations today.
+@c 
+@c @node Walkthru a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos
+@c @section Walkthru a sample GSS-API client
+@c 
+@c Write about how gssapi_clent.c works.
diff --git a/crypto/heimdal/doc/setup.texi b/crypto/heimdal/doc/setup.texi
index ed14306..8a1a31b 100644
--- a/crypto/heimdal/doc/setup.texi
+++ b/crypto/heimdal/doc/setup.texi
@@ -1,4 +1,4 @@
-@c $Id: setup.texi,v 1.21 2001/01/29 04:39:46 assar Exp $
+@c $Id: setup.texi,v 1.22 2001/02/11 17:10:34 assar Exp $
 
 @node Setting up a realm, Things in search for a better place, Building and Installing, Top
 
@@ -417,7 +417,7 @@ is the same thing as no salt at all).
 
 Common types of salting includes
 
-@itemize
+@itemize @bullet
 @item @code{v4} (or @code{des:pw-salt:})
 
 The Kerberos 4 salting is using no salt att all. Reson there is colon
diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt
new file mode 100644
index 0000000..5845995
--- /dev/null
+++ b/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt
@@ -0,0 +1,725 @@
+
+
+Kerberos Working Group                                         M. Swift 
+Internet Draft                                         University of WA 
+Document: draft-ietf-krb-wg-kerberos-referrals-00.txt         J. Brezak 
+Category: Standards Track                                     Microsoft 
+                                                             J. Trostle 
+                                                          Cisco Systems 
+                                                             K. Raeburn 
+                                                                    MIT 
+                                                          February 2001 
+
+ 
+           Generating KDC Referrals to locate Kerberos realms 
+ 
+ 
+Status of this Memo 
+ 
+   This document is an Internet-Draft and is in full conformance with 
+   all provisions of Section 10 of RFC2026 [1].  
+    
+   Internet-Drafts are working documents of the Internet Engineering 
+   Task Force (IETF), its areas, and its working groups. Note that 
+   other groups may also distribute working documents as Internet-
+   Drafts. Internet-Drafts are draft documents valid for a maximum of 
+   six months and may be updated, replaced, or obsoleted by other 
+   documents at any time. It is inappropriate to use Internet- Drafts 
+   as reference material or to cite them other than as "work in 
+   progress."  
+    
+   The list of current Internet-Drafts can be accessed at 
+   http://www.ietf.org/ietf/1id-abstracts.txt  
+   The list of Internet-Draft Shadow Directories can be accessed at 
+   http://www.ietf.org/shadow.html. 
+    
+1. Abstract 
+    
+   The draft documents a new method for a Kerberos Key Distribution 
+   Center (KDC) to respond to client requests for kerberos tickets when 
+   the client does not have detailed configuration information on the 
+   realms of users or services. The KDC will handle requests for 
+   principals in other realms by returning either a referral error or a 
+   cross-realm TGT to another realm on the referral path. The clients 
+   will use this referral information to reach the realm of the target 
+   principal and then receive the ticket. 
+    
+2. Conventions used in this document 
+    
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
+   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in 
+   this document are to be interpreted as described in RFC-2119 [2]. 
+    
+3. Introduction 
+    
+
+
+  
+Swift                 Category - Standards Track                     1 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   Current implementations of the Kerberos AS and TGS protocols, as 
+   defined in RFC 1510 [3], use principal names constructed from a 
+   known user or service name and realm. A service name is typically 
+   constructed from a name of the service and the DNS host name of the 
+   computer that is providing the service. Many existing deployments of 
+   Kerberos use a single Kerberos realm where all users and services 
+   would be using the same realm. However in an environment where there 
+   are multiple trusted Kerberos realms, the client needs to be able to 
+   determine what realm a particular user or service is in before 
+   making an AS or TGS request. Traditionally this requires client 
+   configuration to make this possible. 
+    
+   When having to deal with multiple trusted realms, users are forced 
+   to know what realm they are in before they can obtain a ticket 
+   granting ticket (TGT) with an AS request. However, in many cases the 
+   user would like to use a more familiar name that is not directly 
+   related to the realm of their Kerberos principal name. A good 
+   example of this is an RFC-822 style email name. This document 
+   describes a mechanism that would allow a user to specify a user 
+   principal name that is an alias for the user's Kerberos principal 
+   name. In practice this would be the name that the user specifies to 
+   obtain a TGT from a Kerberos KDC. The user principal name no longer 
+   has a direct relationship with the Kerberos principal or realm. Thus 
+   the administrator is able to move the user's principal to other 
+   realms without the user having to know that it happened. 
+    
+   Once a user has a TGT, they would like to be able to access services 
+   in any trusted Kerberos realm. To do this requires that the client 
+   be able to determine what realm the target service's host is in 
+   before making the TGS request. Current implementations of Kerberos 
+   typically have a table that maps DNS host names to corresponding 
+   Kerberos realms. In order for this to work on the client, each 
+   application canonicalizes the host name of the service by doing a 
+   DNS lookup followed by a reverse lookup using the returned IP 
+   address. The returned primary host name is then used in the 
+   construction of the principal name for the target service. In order 
+   for the correct realm to be added for the target host, the mapping 
+   table [domain_to_realm] is consulted for the realm corresponding to 
+   the DNS host name. The corresponding realm is then used to complete 
+   the target service principal name. 
+    
+   This traditional mechanism requires that each client have very 
+   detailed configuration information about the hosts that are 
+   providing services and their corresponding realms. Having client 
+   side configuration information can be very costly from an 
+   administration point of view - especially if there are many realms 
+   and computers in the environment. 
+    
+   Current implementations of Kerberos also have difficulty with 
+   services on hosts that can have multiple host names (multi-homed 
+   hosts). Traditionally, each host name would need to have a distinct 
+   principal and a corresponding key. An extreme example of this would 
+   be a Web server with multiple host names for each domain that it is 
+  
+Swift                 Category - Standards Track                     2 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   supporting. Principal aliases allow multi-homed hosts to have a 
+   single Kerberos principal (with a single key) that can have 
+   identities for each distinct host name. This mechanism allows the 
+   Kerberos client to request a service ticket for the distinct 
+   hostname and allows the KDC to return a ticket for the single 
+   principal that the host is using. This canonical principal name 
+   allows the host to only have to manage a single key for all of the 
+   identities that it supports. In addition, the client only needs to 
+   know the realm of the canonical service name, not all of the 
+   identities. 
+    
+   This draft proposes a solution for these problems and simplifies 
+   administration by minimizing the configuration information needed on 
+   each computer using Kerberos. Specifically it describes a mechanism 
+   to allow the KDC to handle Canonicalization of names, provide for 
+   principal aliases for users and services and provide a mechanism for 
+   the KDC to determine the trusted realm authentication path by being 
+   able to generate referrals to other realms in order to locate 
+   principals. 
+    
+   To rectify these problems, this draft introduces three new kinds of   
+   KDC referrals: 
+        
+   1. AS ticket referrals, in which the client doesn't know which realm 
+      contains a user account.  
+   2. TGS ticket referrals, in which the client doesn't know which 
+      realm contains a server account.  
+   3. Cross realm shortcut referrals, in which the KDC chooses the next 
+      path on a referral chain 
+    
+4. Realm Organization Model 
+    
+   This draft assumes that the world of principals is arranged on 
+   multiple levels: the realm, the enterprise, and the world. A KDC may 
+   issue tickets for any principal in its realm or cross-realm tickets 
+   for realms with which it has a direct trust relationship. The KDC 
+   also has access to a trusted name service that can resolve any name 
+   from within its enterprise into a realm. This trusted name service 
+   removes the need to use an untrusted DNS lookup for name resolution. 
+    
+   For example, consider the following configuration, where lines 
+   indicate trust relationships: 
+    
+                  MS.COM  
+                /        \ 
+               /          \ 
+        OFFICE.MS.COM    NT.MS.COM 
+    
+   In this configuration, all users in the MS.COM enterprise could have 
+   a principal name such as alice@MS.COM, with the same realm portion. 
+   In addition, servers at MS.COM should be able to have DNS host names 
+   from any DNS domain independent of what Kerberos realm their 
+   principal resides in. 
+  
+Swift                 Category - Standards Track                     3 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+    
+5. Principal Names 
+    
+5.1 Service Principal Names 
+    
+   The standard Kerberos model in RFC 1510 [3] gives each Kerberos 
+   principal a single name. However, if a service is reachable by 
+   several addresses, it is useful for a principal to have multiple 
+   names. Consider a service running on a multi-homed machine. Rather 
+   than requiring a separate principal and password for each name it 
+   exports, a single account with multiple names could be used. 
+    
+   Multiple names are also useful for services in that clients need not 
+   perform DNS lookups to resolve a host name into a full DNS address. 
+   Instead, the service may have a name for each of its supported host 
+   names, including its IP address. Nonetheless, it is still convenient 
+   for the service to not have to be aware of all these names. Thus a 
+   new name may be added to DNS for a service by updating DNS and the 
+   KDC database without having to notify the service. In addition, it 
+   implies that these aliases are globally unique: they do not include 
+   a specifier dictating what realm contains the principal. Thus, an 
+   alias for a server is of the form "class/instance/name" and may be 
+   transmitted as any name type. 
+    
+5.2 Client Principal Names 
+    
+   Similarly, a client account may also have multiple principal names. 
+   More useful, though, is a globally unique name that allows 
+   unification of email and security principal names. For example, all 
+   users at MS may have a client principal name of the form 
+   "joe@MS.COM" even though the principals are contained in multiple 
+   realms. This global name is again an alias for the true client 
+   principal name, which is indicates what realm contains the 
+   principal. Thus, accounts "alice" in the realm ntdev.MS.COM and 
+   "bob" in office.MS.COM may logon as "alice@MS.COM" and "bob@MS.COM". 
+   This requires a new client principal name type, as the AS-REQ 
+   message only contains a single realm field, and the realm portion of 
+   this name doesn't correspond to any Kerberos realm. Thus, the entire 
+   name "alice@MS.COM" is transmitted in the client name field of the 
+   AS-REQ message, with a name type of KRB-NT-ENTERPRISE-PRINCIPAL. 
+    
+        KRB-NT-ENTERPRISE-PRINCIPAL     10 
+    
+5.3 Name Canonicalization 
+    
+   In order to support name aliases, the Kerberos client must 
+   explicitly request the name-canonicalization KDC option (bit 15) in 
+   the ticket flags for the TGS-REQ. This flag indicates to the KDC 
+   that the client is prepared to receive a reply with a different 
+   client or server principal name than the request. Thus, the 
+   KDCOptions types is redefined as: 
+    
+        KDCOptions ::=   BIT STRING { 
+  
+Swift                 Category - Standards Track                     4 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+                          reserved(0), 
+                          forwardable(1), 
+                          forwarded(2), 
+                          proxiable(3), 
+                          proxy(4), 
+                          allow-postdate(5), 
+                          postdated(6), 
+                          unused7(7), 
+                          renewable(8), 
+                          unused9(9), 
+                          unused10(10), 
+                          unused11(11), 
+                          name-canonicalize(15), 
+                          renewable-ok(27), 
+                          enc-tkt-in-skey(28), 
+                          renew(30), 
+                          validate(31) 
+         } 
+    
+6. Client Referrals 
+    
+   The simplest form of ticket referral is for a user requesting a 
+   ticket using an AS-REQ. In this case, the client machine will send 
+   the AS request to a convenient trusted realm, either the realm of 
+   the client machine or the realm of the client name. In the case of 
+   the name Alice@MS.COM, the client may optimistically choose to send 
+   the request to MS.COM. 
+    
+   The client will send the string "alice@MS.COM" in the client 
+   principal name field using the KRB-NT-ENTERPRISE-PRINCIPAL name type 
+   with the crealm set to MS.COM. The KDC will try to lookup the name 
+   in its local account database. If the account is present in the 
+   crealm of the request, it MUST return a KDC reply structure with the 
+   appropriate ticket. If the account is not present in the crealm 
+   specified in the request and the name-canonicalize flag in the 
+   KDCoptions is set, the KDC will try to lookup the entire name, 
+   Alice@MS.COM, using a name service. If this lookup is unsuccessful, 
+   it MUST return the error KDC_ERR_C_PRINCIPAL_UNKNOWN. If the lookup 
+   is successful, it MUST return an error KDC_ERR_WRONG_REALM (0x44) 
+   and in the error message the cname and crealm field MUST contain the 
+   client name and the true realm of the client. If the KDC contains 
+   the account locally, it MUST return a normal ticket. The client name 
+   and realm portions of the ticket and KDC reply message MUST be the 
+   client's true name in the realm, not the globally unique name. 
+    
+   If the client receives a KDC_ERR_WRONG_REALM error, it will issue a 
+   new AS request with the same client principal name used to generate 
+   the first referral to the realm specified by the crealm field of the 
+   kerberos error message from the first request. This request MUST 
+   produce a valid AS response with a ticket for the canonical user 
+   name. The ticket MUST also include the ticket extension containing 
+   the TE-REFERRAL-DATA with the referred-names set to the name from 
+
+  
+Swift                 Category - Standards Track                     5 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   the AS request. Any other error or referral will terminate the 
+   request and result in a failed AS request. 
+    
+7. Server Referrals 
+    
+   The server referral mechanism is a bit more complex than the client 
+   referral mechanism. The primary problem is that the KDC must return 
+   a referral ticket rather than an error message, so it will include 
+   in the TGS response information about what realm contains the 
+   service. This is done by returning information about the server name 
+   in the pre-auth data field of the KDC reply. 
+    
+   If the KDC resolves the server principal name into a principal in 
+   its realm, it may return a normal ticket. If the name-canonicalize 
+   flag in the KDCoptions is not set, then the KDC MUST only look up 
+   the name as a normal principal name. Otherwise, it MUST search all 
+   aliases as well. The server principal name in both the ticket and 
+   the KDC reply MUST be the true server principal name instead of one 
+   of the aliases. This frees the application server from needing to 
+   know about all its aliases. 
+    
+   If the name-canonicalize flag in the KDCoptions is set and the KDC 
+   doesn't find the principal locally, the KDC can return a cross-realm 
+   ticket granting ticket to the next hop on the trust path towards a 
+   realm that may be able to resolve the principal name. 
+    
+   If the KDC can determine the service principal's realm, it can 
+   return the server realm as ticket extension data. The ticket 
+   extension MUST be encrypted using the session key from the ticket, 
+   and the same etype as is used to protect the TGS reply body. 
+    
+   The data itself is an ASN.1 encoded structure containing the 
+   server's realm, and if known, canonical principal name and alias 
+   names. The first name in the sequence is the canonical principal 
+   name. 
+    
+                TE-REFERRAL-INFO        20 
+                 
+                TE-REFERRAL-DATA ::= SEQUENCE { 
+                        referred-server-realm[0]  KERB-REALM 
+                        referred-names[1]         SEQUENCE OF 
+                        PrincipalNames OPTIONAL 
+                } 
+    
+    
+   The client can use this information to request a chain of cross-
+   realm ticket granting tickets until it reaches the realm of the 
+   server, and can then expect to receive a valid service ticket. 
+    
+   In order to facilitate cross-realm interoperability, a client SHOULD 
+   NOT send short names in TGS requests to the KDC. A short name is 
+   defined as a Kerberos name that includes a DNS name that is not 
+   fully qualified. The client MAY use forward DNS lookups to obtain 
+  
+Swift                 Category - Standards Track                     6 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   the long name that corresponds to the user entered short name (the 
+   short name will be a prefix of the corresponding long name). 
+    
+   The client may use the referred-names field to tell if it already 
+   has a ticket to the server in its ticket cache. 
+    
+   The client can use this information to request a chain of cross-
+   realm ticket granting tickets until it reaches the realm of the 
+   server, and can then expect to receive a valid service ticket. 
+   However an implementation should limit the number of referrals that 
+   it processes to avoid infinite referral loops. A suggested limit is 
+   5 referrals before giving up. 
+    
+8. Cross Realm Routing 
+    
+   The current Kerberos protocol requires the client to explicitly 
+   request a cross-realm TGT for each pair of realms on a referral 
+   chain. As a result, the client machines need to be aware of the 
+   trust hierarchy and of any short-cut trusts (those that aren't 
+   parent-child trusts). This requires more configurations on the 
+   client. Instead, the client should be able to request a TGT to the 
+   target realm from each realm on the route. The KDC will determine 
+   the best path for the client and return a cross-realm TGT. The 
+   client has to be aware that a request for a cross-realm TGT may 
+   return a TGT for a realm different from the one requested. 
+    
+9. Security Considerations 
+ 
+   The original Kerberos specification stated that the server principal 
+   name in the KDC reply was the same as the server name in the 
+   request. These protocol changes break that assumption, so the client 
+   may be vulnerable to a denial of service attack by an attacker that 
+   replays replies from previous requests. It can verify that the 
+   request was one of its own by checking the client-address field or 
+   authtime field, though, so the damage is limited and detectable. 
+    
+   For the AS exchange case, it is important that the logon mechanism 
+   not trust a name that has not been used to authenticate the user. 
+   For example, the name that the user enters as part of a logon 
+   exchange may not be the name that the user authenticates as, given 
+   that the KDC_ERR_WRONG_REALM error may have been returned. The 
+   relevant Kerberos naming information for logon (if any), is the 
+   client name and client realm in the service ticket targeted at the 
+   workstation that was obtained using the user's initial TGT. 
+    
+   How the client name and client realm is mapped into a local account 
+   for logon is a local matter, but the client logon mechanism MUST use 
+   additional information such as the client realm and/or authorization 
+   attributes from the service ticket presented to the workstation by 
+   the user, when mapping the logon credentials to a local account on 
+   the workstation. 
+    
+10. Discussion 
+  
+Swift                 Category - Standards Track                     7 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+ 
+   This section contains issues and suggestions that need to be 
+   incorporated into this draft. From Ken Raeburn [raeburn@mit.edu]: 
+    
+   1) No means to do name canonicalization if you're not 
+      authenticating. Is it okay to require credentials in order to do 
+      canonicalization? If so, how about this: Send a TGS_REQ for the 
+      service name you have.  If you get back a TGS_REP for a service, 
+      great; pull out the name and throw out the credentials.  If you 
+      get back a TGS_REP for a TGT service, ask again in the specified 
+      realm.  If you get back a KRB_ERROR because policy prohibits you 
+      from authenticating to that service, we can add to the 
+      specification that the {realm,sname} in the KRB_ERROR must be the 
+      canonical name, and the checksum must be used.  As long as the 
+      checksum is present, it's still a secure exchange with the KDC.  
+       
+      If we have to be able to do name canonicalization without any 
+      sort of credentials, either client-side (tickets) or server-side 
+      (tickets automatically acquired via service key), I think we just 
+      lose. But maybe GSSAPI should be changed if that's the case. 
+    
+   2) Can't refer to another realm and specify a different service name 
+      to give to that realm's KDC.  The local KDC can tell you a 
+      different service name or a different realm name, but not both. 
+      This comes up in the "gnuftp.raeburn.org CNAME ftp.gnu.org" type 
+      of case I've mentioned. 
+       
+      Except ... the KDC-REP structure includes padata and ticket 
+      extensions fields that are extensible.  We could add a required 
+      value to one of them -- perhaps only in the case where you return 
+      a TGT when not asked -- that contains signed information about 
+      the principal name to ask for in the other realm.  (It would have 
+      to be required, otherwise a man-in-the-middle could make it go 
+      away.) Signing would be done using the session key for the TGS. 
+    
+   3) Secure canonicalization of service name in AS_REQ. If the 
+      response is an AS_REP, we need a way to tell that the altered 
+      server name wasn't a result of a MITM attack on the AS_REQ 
+      message.  Again, the KDC-REP extensible fields could have a new 
+      required value added when name canonicalization happens, 
+      indicating what the original principal name (in the AS_REQ 
+      message) was, and signed using the same key as protects the 
+      AS_REP.  If it doesn't match what the client requested, the 
+      messages were altered in transit. 
+    
+   4) Client name needs referral to another realm, and server name 
+      needs canonicalization of some sort. The above fixes wouldn't 
+      work for this case, and I'm not even sure which KDC should be 
+      doing the canonicalization anyways. 
+    
+    
+   The other-principal-name datum would probably look something like: 
+    
+  
+Swift                 Category - Standards Track                     8 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+       PrincipalAndNonce ::= SEQUENCE { 
+                    name[0]     PrincipalName, 
+                    nonce[1]    INTEGER         -- copied from KDC_REQ 
+       } 
+       SignedPrincipal ::= SEQUENCE { 
+                    name-and-nonce[0]   PrincipalAndNonce, 
+                    cksum[1]    Checksum 
+       } 
+       {PA,TE}-ORIGINAL-SERVER-PRINCIPAL ::= SignedPrincipal 
+       {PA,TE}-REMOTE-SERVER-PRINCIPAL ::= SignedPrincipal 
+    
+   with the checksum computed over the encoding of the 'name-and-nonce' 
+   field, and appropriate PA- or TE- numbers assigned.  I don't have a 
+   strong opinion on whether it'd be a pa-data or ticket extension; 
+   conceptually it seems like an abuse of either, but, well, I think 
+   I'd rather abuse them than leave the facility both in and 
+   inadequate. 
+    
+   The nonce is needed because multiple exchanges may be made with the 
+   same key, and these extension fields aren't packed in with the other 
+   encrypted data in the same response, so a MITM could pick apart 
+   multiple messages and mix-and-match components.  (In a TGS_REQ 
+   exchange, a subsession key would help, but it's not required.) 
+    
+   The extension field would be required to prevent a MITM from 
+   discarding the field from a response; a flag bit in a protected part 
+   of the message (probably in 'flags' in EncKDCRepPart) could also let 
+   us know of a cases where the information can be omitted, namely, 
+   when no name change is done.  Perhaps the bit should be set to 
+   indicate that a name change *was* done, and clear if it wasn't, 
+   making the no-change case more directly compatible with RFC1510. 
+ 
+11. References 
+    
+ 
+   1  Bradner, S., "The Internet Standards Process -- Revision 3", BCP 
+      9, RFC 2026, October 1996. 
+    
+   2  Bradner, S., "Key words for use in RFCs to Indicate Requirement 
+      Levels", BCP 14, RFC 2119, March 1997 
+    
+   3  Kohl, J., Neuman, C., "The Kerberos Network Authentication 
+      Service (V5)", RFC 1510, September 1993 
+    
+    
+12. Author's Addresses 
+    
+   Michael Swift 
+   University of Washington 
+   Seattle, Washington 
+   Email: mikesw@cs.washington.edu 
+    
+   John Brezak 
+  
+Swift                 Category - Standards Track                     9 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   Microsoft 
+   One Microsoft Way 
+   Redmond, Washington 
+   Email: jbrezak@Microsoft.com 
+    
+   Jonathan Trostle 
+   Cisco Systems 
+   170 W. Tasman Dr. 
+   San Jose, CA 95134 
+   Email: jtrostle@cisco.com 
+    
+   Kenneth Raeburn 
+   Massachusetts Institute of Technology 77 
+   Massachusetts Avenue 
+   Cambridge, Massachusetts 02139 
+   Email: raeburn@mit.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+Swift                 Category - Standards Track                    10 
+
+
+
+
+
+
+
+
+                            KDC Referrals               February 2001 
+ 
+ 
+   Full Copyright Statement 
+
+   Copyright (C) The Internet Society (1999).  All Rights Reserved. 
+    
+   This document and translations of it may be copied and furnished to 
+   others, and derivative works that comment on or otherwise explain it 
+   or assist in its implementation may be prepared, copied, published 
+   and distributed, in whole or in part, without restriction of any 
+   kind, provided that the above copyright notice and this paragraph 
+   are included on all such copies and derivative works.  However, this   
+   document itself may not be modified in any way, such as by removing   
+   the copyright notice or references to the Internet Society or other   
+   Internet organizations, except as needed for the purpose of 
+   developing Internet standards in which case the procedures for 
+   copyrights defined in the Internet Standards process must be 
+   followed, or as required to translate it into languages other than 
+   English. 
+    
+   The limited permissions granted above are perpetual and will not be 
+   revoked by the Internet Society or its successors or assigns. 
+    
+   This document and the information contained herein is provided on an 
+   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 
+   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 
+   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 
+   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 
+    
+    
+    
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+  
+Swift                 Category - Standards Track                    11 
+
+
+
+
+
+
+
diff --git a/crypto/heimdal/doc/win2k.texi b/crypto/heimdal/doc/win2k.texi
index baa1b47..1d48677 100644
--- a/crypto/heimdal/doc/win2k.texi
+++ b/crypto/heimdal/doc/win2k.texi
@@ -1,6 +1,6 @@
-@c $Id: win2k.texi,v 1.12 2001/01/28 22:10:35 assar Exp $
+@c $Id: win2k.texi,v 1.13 2001/02/24 05:09:24 assar Exp $
 
-@node Windows 2000 compatability, Acknowledgments, Migration, Top
+@node Windows 2000 compatability, Programming with Kerberos, Kerberos 4 issues, Top
 @comment  node-name,  next,  previous,  up
 @chapter Windows 2000 compatability