From 0c8fa354358381b3f1b92598e7f1b46f8cf744cc Mon Sep 17 00:00:00 2001 From: assar Date: Thu, 21 Jun 2001 02:12:07 +0000 Subject: import of heimdal 0.3f --- crypto/heimdal/doc/Makefile.in | 11 +- crypto/heimdal/doc/ack.texi | 4 +- crypto/heimdal/doc/heimdal.texi | 8 +- crypto/heimdal/doc/kerberos4.texi | 4 +- crypto/heimdal/doc/migration.texi | 4 +- crypto/heimdal/doc/misc.texi | 8 +- crypto/heimdal/doc/programming.texi | 287 ++++++++ crypto/heimdal/doc/setup.texi | 4 +- .../draft-ietf-krb-wg-kerberos-referrals-00.txt | 725 +++++++++++++++++++++ crypto/heimdal/doc/win2k.texi | 4 +- 10 files changed, 1041 insertions(+), 18 deletions(-) create mode 100644 crypto/heimdal/doc/programming.texi create mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt (limited to 'crypto/heimdal/doc') 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 + +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 -- cgit v1.1