diff options
| author | markm <markm@FreeBSD.org> | 2000-01-09 20:58:00 +0000 |
|---|---|---|
| committer | markm <markm@FreeBSD.org> | 2000-01-09 20:58:00 +0000 |
| commit | 4ecbd6db44d79348bc815f31096e53104f50838b (patch) | |
| tree | 36fa73706fa0587a390c45a3fbf17c9523cb0e35 /crypto/heimdal/doc | |
| download | FreeBSD-src-4ecbd6db44d79348bc815f31096e53104f50838b.zip FreeBSD-src-4ecbd6db44d79348bc815f31096e53104f50838b.tar.gz | |
Import KTH Heimdal, which will be the core of our Kerberos5.
Userland to follow.
Diffstat (limited to 'crypto/heimdal/doc')
46 files changed, 68850 insertions, 0 deletions
diff --git a/crypto/heimdal/doc/Makefile.am b/crypto/heimdal/doc/Makefile.am new file mode 100644 index 0000000..734bf62 --- /dev/null +++ b/crypto/heimdal/doc/Makefile.am @@ -0,0 +1,8 @@ +# $Id: Makefile.am,v 1.6 1999/03/20 13:58:16 joda Exp $ + +include $(top_srcdir)/Makefile.am.common + +AUTOMAKE_OPTIONS += no-texinfo.tex + +info_TEXINFOS = heimdal.texi +heimdal_TEXINFOS = intro.texi install.texi setup.texi kerberos4.texi diff --git a/crypto/heimdal/doc/Makefile.in b/crypto/heimdal/doc/Makefile.in new file mode 100644 index 0000000..710abb8 --- /dev/null +++ b/crypto/heimdal/doc/Makefile.in @@ -0,0 +1,620 @@ +# Makefile.in generated automatically by automake 1.4 from Makefile.am + +# Copyright (C) 1994, 1995-8, 1999 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. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +# $Id: Makefile.am,v 1.6 1999/03/20 13:58:16 joda Exp $ + + +# $Id: Makefile.am.common,v 1.3 1999/04/01 14:58:43 joda Exp $ + + +# $Id: Makefile.am.common,v 1.13 1999/11/01 03:19:58 assar Exp $ + + +SHELL = @SHELL@ + +srcdir = @srcdir@ +top_srcdir = @top_srcdir@ +VPATH = @srcdir@ +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +bindir = @bindir@ +sbindir = @sbindir@ +libexecdir = @libexecdir@ +datadir = @datadir@ +sysconfdir = @sysconfdir@ +sharedstatedir = @sharedstatedir@ +localstatedir = @localstatedir@ +libdir = @libdir@ +infodir = @infodir@ +mandir = @mandir@ +includedir = @includedir@ +oldincludedir = /usr/include + +DESTDIR = + +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ + +top_builddir = .. + +ACLOCAL = @ACLOCAL@ +AUTOCONF = @AUTOCONF@ +AUTOMAKE = @AUTOMAKE@ +AUTOHEADER = @AUTOHEADER@ + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ $(AM_INSTALL_PROGRAM_FLAGS) +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +transform = @program_transform_name@ + +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +host_alias = @host_alias@ +host_triplet = @host@ +AFS_EXTRA_LD = @AFS_EXTRA_LD@ +AIX_EXTRA_KAFS = @AIX_EXTRA_KAFS@ +AWK = @AWK@ +CANONICAL_HOST = @CANONICAL_HOST@ +CATMAN = @CATMAN@ +CATMANEXT = @CATMANEXT@ +CC = @CC@ +DBLIB = @DBLIB@ +EXEEXT = @EXEEXT@ +EXTRA_LIB45 = @EXTRA_LIB45@ +GROFF = @GROFF@ +INCLUDE_ = @INCLUDE_@ +LD = @LD@ +LEX = @LEX@ +LIBOBJS = @LIBOBJS@ +LIBTOOL = @LIBTOOL@ +LIB_ = @LIB_@ +LIB_AUTH_SUBDIRS = @LIB_AUTH_SUBDIRS@ +LIB_kdb = @LIB_kdb@ +LIB_otp = @LIB_otp@ +LIB_roken = @LIB_roken@ +LIB_security = @LIB_security@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MAKE_X_PROGS_BIN_PROGS = @MAKE_X_PROGS_BIN_PROGS@ +MAKE_X_PROGS_BIN_SCRPTS = @MAKE_X_PROGS_BIN_SCRPTS@ +MAKE_X_PROGS_LIBEXEC_PROGS = @MAKE_X_PROGS_LIBEXEC_PROGS@ +NEED_WRITEAUTH_FALSE = @NEED_WRITEAUTH_FALSE@ +NEED_WRITEAUTH_TRUE = @NEED_WRITEAUTH_TRUE@ +NM = @NM@ +NROFF = @NROFF@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +RANLIB = @RANLIB@ +VERSION = @VERSION@ +VOID_RETSIGTYPE = @VOID_RETSIGTYPE@ +WFLAGS = @WFLAGS@ +WFLAGS_NOIMPLICITINT = @WFLAGS_NOIMPLICITINT@ +WFLAGS_NOUNUSED = @WFLAGS_NOUNUSED@ +YACC = @YACC@ + +AUTOMAKE_OPTIONS = foreign no-dependencies no-texinfo.tex + +SUFFIXES = .et .h .1 .3 .5 .8 .cat1 .cat3 .cat5 .cat8 .x + +INCLUDES = -I$(top_builddir)/include + +AM_CFLAGS = $(WFLAGS) + +COMPILE_ET = $(top_builddir)/lib/com_err/compile_et + +buildinclude = $(top_builddir)/include + +LIB_XauReadAuth = @LIB_XauReadAuth@ +LIB_crypt = @LIB_crypt@ +LIB_dbm_firstkey = @LIB_dbm_firstkey@ +LIB_dbopen = @LIB_dbopen@ +LIB_dlopen = @LIB_dlopen@ +LIB_dn_expand = @LIB_dn_expand@ +LIB_el_init = @LIB_el_init@ +LIB_getattr = @LIB_getattr@ +LIB_gethostbyname = @LIB_gethostbyname@ +LIB_getpwent_r = @LIB_getpwent_r@ +LIB_getpwnam_r = @LIB_getpwnam_r@ +LIB_getsockopt = @LIB_getsockopt@ +LIB_logout = @LIB_logout@ +LIB_logwtmp = @LIB_logwtmp@ +LIB_odm_initialize = @LIB_odm_initialize@ +LIB_readline = @LIB_readline@ +LIB_res_search = @LIB_res_search@ +LIB_setpcred = @LIB_setpcred@ +LIB_setsockopt = @LIB_setsockopt@ +LIB_socket = @LIB_socket@ +LIB_syslog = @LIB_syslog@ +LIB_tgetent = @LIB_tgetent@ + +HESIODLIB = @HESIODLIB@ +HESIODINCLUDE = @HESIODINCLUDE@ +INCLUDE_hesiod = @INCLUDE_hesiod@ +LIB_hesiod = @LIB_hesiod@ + +INCLUDE_krb4 = @INCLUDE_krb4@ +LIB_krb4 = @LIB_krb4@ + +INCLUDE_readline = @INCLUDE_readline@ + +LEXLIB = @LEXLIB@ + +cat1dir = $(mandir)/cat1 +cat3dir = $(mandir)/cat3 +cat5dir = $(mandir)/cat5 +cat8dir = $(mandir)/cat8 + +MANRX = \(.*\)\.\([0-9]\) +CATSUFFIX = @CATSUFFIX@ + +NROFF_MAN = groff -mandoc -Tascii + +@KRB4_TRUE@LIB_kafs = $(top_builddir)/lib/kafs/libkafs.la $(AIX_EXTRA_KAFS) + +@KRB5_TRUE@LIB_krb5 = $(top_builddir)/lib/krb5/libkrb5.la $(top_builddir)/lib/asn1/libasn1.la +@KRB5_TRUE@LIB_gssapi = $(top_builddir)/lib/gssapi/libgssapi.la + +CHECK_LOCAL = $(PROGRAMS) + +info_TEXINFOS = heimdal.texi +heimdal_TEXINFOS = intro.texi install.texi setup.texi kerberos4.texi +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = ../include/config.h +CONFIG_CLEAN_FILES = +CFLAGS = @CFLAGS@ +COMPILE = $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +LTCOMPILE = $(LIBTOOL) --mode=compile $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +CCLD = $(CC) +LINK = $(LIBTOOL) --mode=link $(CCLD) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ +TEXI2DVI = texi2dvi +INFO_DEPS = heimdal.info +DVIS = heimdal.dvi +TEXINFOS = heimdal.texi +DIST_COMMON = $(heimdal_TEXINFOS) Makefile.am Makefile.in mdate-sh + + +DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST) + +TAR = tar +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 +$(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 + +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + cd $(top_builddir) \ + && CONFIG_FILES=$(subdir)/$@ CONFIG_HEADERS= $(SHELL) ./config.status + + +heimdal.info: heimdal.texi $(heimdal_TEXINFOS) +heimdal.dvi: heimdal.texi $(heimdal_TEXINFOS) + + +DVIPS = dvips + +.texi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texi.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.texi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.texinfo.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi.info: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` + +.txi.dvi: + TEXINPUTS=.:$$TEXINPUTS \ + MAKEINFO='$(MAKEINFO) -I $(srcdir)' $(TEXI2DVI) $< + +.txi: + @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9] + cd $(srcdir) \ + && $(MAKEINFO) `echo $< | sed 's,.*/,,'` +.dvi.ps: + $(DVIPS) $< -o $@ + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + $(mkinstalldirs) $(DESTDIR)$(infodir) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + d=$(srcdir); \ + for ifile in `cd $$d && echo $$file $$file-[0-9] $$file-[0-9][0-9]`; do \ + if test -f $$d/$$ifile; then \ + echo " $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile"; \ + $(INSTALL_DATA) $$d/$$ifile $(DESTDIR)$(infodir)/$$ifile; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\ + install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\ + done; \ + else : ; fi + +uninstall-info: + $(PRE_UNINSTALL) + @if $(SHELL) -c 'install-info --version | sed 1q | fgrep -s -v -i debian' >/dev/null 2>&1; then \ + ii=yes; \ + else ii=; fi; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + test -z "$ii" \ + || install-info --info-dir=$(DESTDIR)$(infodir) --remove $$file; \ + done + @$(NORMAL_UNINSTALL) + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + (cd $(DESTDIR)$(infodir) && rm -f $$file $$file-[0-9] $$file-[0-9][0-9]); \ + done + +dist-info: $(INFO_DEPS) + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + d=$(srcdir); \ + for file in `cd $$d && eval echo $$base*`; do \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file; \ + done; \ + done + +mostlyclean-aminfo: + -rm -f heimdal.aux heimdal.cp heimdal.cps heimdal.dvi heimdal.fn \ + heimdal.fns heimdal.ky heimdal.kys heimdal.ps heimdal.log \ + heimdal.pg heimdal.toc heimdal.tp heimdal.tps heimdal.vr \ + heimdal.vrs heimdal.op heimdal.tr heimdal.cv heimdal.cn + +clean-aminfo: + +distclean-aminfo: + +maintainer-clean-aminfo: + cd $(srcdir) && for i in $(INFO_DEPS); do \ + rm -f $$i; \ + if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \ + rm -f $$i-[0-9]*; \ + fi; \ + done +tags: TAGS +TAGS: + + +distdir = $(top_builddir)/$(PACKAGE)-$(VERSION)/$(subdir) + +subdir = doc + +distdir: $(DISTFILES) + @for file in $(DISTFILES); do \ + d=$(srcdir); \ + if test -d $$d/$$file; then \ + cp -pr $$/$$file $(distdir)/$$file; \ + else \ + test -f $(distdir)/$$file \ + || ln $$d/$$file $(distdir)/$$file 2> /dev/null \ + || cp -p $$d/$$file $(distdir)/$$file || :; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-info + $(MAKE) $(AM_MAKEFLAGS) top_distdir="$(top_distdir)" distdir="$(distdir)" dist-hook +info-am: $(INFO_DEPS) +info: info-am +dvi-am: $(DVIS) +dvi: dvi-am +check-am: all-am + $(MAKE) $(AM_MAKEFLAGS) check-local +check: check-am +installcheck-am: +installcheck: installcheck-am +install-exec-am: + @$(NORMAL_INSTALL) + $(MAKE) $(AM_MAKEFLAGS) install-exec-hook +install-exec: install-exec-am + +install-data-am: install-info-am install-data-local +install-data: install-data-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am +install: install-am +uninstall-am: uninstall-info +uninstall: uninstall-am +all-am: Makefile $(INFO_DEPS) all-local +all-redirect: all-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) AM_INSTALL_PROGRAM_FLAGS=-s install +installdirs: + $(mkinstalldirs) $(DESTDIR)$(infodir) + + +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -rm -f Makefile $(CONFIG_CLEAN_FILES) + -rm -f config.cache config.log stamp-h stamp-h[0-9]* + +maintainer-clean-generic: +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic + +mostlyclean: mostlyclean-am + +clean-am: clean-aminfo clean-generic mostlyclean-am + +clean: clean-am + +distclean-am: distclean-aminfo distclean-generic clean-am + -rm -f libtool + +distclean: distclean-am + +maintainer-clean-am: maintainer-clean-aminfo maintainer-clean-generic \ + distclean-am + @echo "This command is intended for maintainers to use;" + @echo "it deletes files that may require special tools to rebuild." + +maintainer-clean: maintainer-clean-am + +.PHONY: install-info-am uninstall-info mostlyclean-aminfo \ +distclean-aminfo clean-aminfo maintainer-clean-aminfo tags distdir \ +info-am info dvi-am dvi check-local check check-am installcheck-am \ +installcheck install-exec-am install-exec install-data-local \ +install-data-am install-data install-am install uninstall-am uninstall \ +all-local all-redirect all-am all installdirs mostlyclean-generic \ +distclean-generic clean-generic maintainer-clean-generic clean \ +mostlyclean distclean maintainer-clean + + +install-suid-programs: + @foo='$(bin_SUIDS)'; \ + for file in $$foo; do \ + x=$(DESTDIR)$(bindir)/$$file; \ + if chown 0:0 $$x && chmod u+s $$x; then :; else \ + chmod 0 $$x; fi; done + +install-exec-hook: install-suid-programs + +install-build-headers:: $(include_HEADERS) $(build_HEADERZ) + @foo='$(include_HEADERS) $(build_HEADERZ)'; \ + for f in $$foo; do \ + f=`basename $$f`; \ + if test -f "$(srcdir)/$$f"; then file="$(srcdir)/$$f"; \ + else file="$$f"; fi; \ + if cmp -s $$file $(buildinclude)/$$f 2> /dev/null ; then \ + : ; else \ + echo " cp $$file $(buildinclude)/$$f"; \ + cp $$file $(buildinclude)/$$f; \ + fi ; \ + done + +all-local: install-build-headers +#NROFF_MAN = nroff -man +.1.cat1: + $(NROFF_MAN) $< > $@ +.3.cat3: + $(NROFF_MAN) $< > $@ +.5.cat5: + $(NROFF_MAN) $< > $@ +.8.cat8: + $(NROFF_MAN) $< > $@ + +dist-cat1-mans: + @foo='$(man1_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.1) foo="$$foo $$i";; \ + esac; done ;\ + for i in $$foo; do \ + x=`echo $$i | sed 's/\.[^.]*$$/.cat1/'`; \ + echo "$(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x"; \ + $(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x; \ + done + +dist-cat3-mans: + @foo='$(man3_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.3) foo="$$foo $$i";; \ + esac; done ;\ + for i in $$foo; do \ + x=`echo $$i | sed 's/\.[^.]*$$/.cat3/'`; \ + echo "$(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x"; \ + $(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x; \ + done + +dist-cat5-mans: + @foo='$(man5_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.5) foo="$$foo $$i";; \ + esac; done ;\ + for i in $$foo; do \ + x=`echo $$i | sed 's/\.[^.]*$$/.cat5/'`; \ + echo "$(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x"; \ + $(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x; \ + done + +dist-cat8-mans: + @foo='$(man8_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.8) foo="$$foo $$i";; \ + esac; done ;\ + for i in $$foo; do \ + x=`echo $$i | sed 's/\.[^.]*$$/.cat8/'`; \ + echo "$(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x"; \ + $(NROFF_MAN) $(srcdir)/$$i > $(distdir)/$$x; \ + done + +dist-hook: dist-cat1-mans dist-cat3-mans dist-cat5-mans dist-cat8-mans + +install-cat1-mans: + @ext=1;\ + foo='$(man1_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.1) foo="$$foo $$i";; \ + esac; done; \ + if test "$$foo"; then \ + $(mkinstalldirs) $(DESTDIR)$(cat1dir); \ + for x in $$foo; do \ + f=`echo $$x | sed 's/\.[^.]*$$/.cat1/'`; \ + if test -f "$(srcdir)/$$f"; then \ + b=`echo $$x | sed 's!$(MANRX)!\1!'`; \ + echo "$(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(cat1dir)/$$b.$(CATSUFFIX)";\ + $(INSTALL_DATA) $(srcdir)/$$g $(DESTDIR)$(cat1dir)/$$b.$(CATSUFFIX);\ + fi; \ + done ;\ + fi + +install-cat3-mans: + @ext=3;\ + foo='$(man3_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.3) foo="$$foo $$i";; \ + esac; done; \ + if test "$$foo"; then \ + $(mkinstalldirs) $(DESTDIR)$(cat3dir); \ + for x in $$foo; do \ + f=`echo $$x | sed 's/\.[^.]*$$/.cat3/'`; \ + if test -f "$(srcdir)/$$f"; then \ + b=`echo $$x | sed 's!$(MANRX)!\1!'`; \ + echo "$(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(cat3dir)/$$b.$(CATSUFFIX)";\ + $(INSTALL_DATA) $(srcdir)/$$g $(DESTDIR)$(cat3dir)/$$b.$(CATSUFFIX);\ + fi; \ + done ;\ + fi + +install-cat5-mans: + @ext=5;\ + foo='$(man5_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.5) foo="$$foo $$i";; \ + esac; done; \ + if test "$$foo"; then \ + $(mkinstalldirs) $(DESTDIR)$(cat5dir); \ + for x in $$foo; do \ + f=`echo $$x | sed 's/\.[^.]*$$/.cat5/'`; \ + if test -f "$(srcdir)/$$f"; then \ + b=`echo $$x | sed 's!$(MANRX)!\1!'`; \ + echo "$(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(cat5dir)/$$b.$(CATSUFFIX)";\ + $(INSTALL_DATA) $(srcdir)/$$g $(DESTDIR)$(cat5dir)/$$b.$(CATSUFFIX);\ + fi; \ + done ;\ + fi + +install-cat8-mans: + @ext=8;\ + foo='$(man8_MANS)'; \ + bar='$(man_MANS)'; \ + for i in $$bar; do \ + case $$i in \ + *.8) foo="$$foo $$i";; \ + esac; done; \ + if test "$$foo"; then \ + $(mkinstalldirs) $(DESTDIR)$(cat8dir); \ + for x in $$foo; do \ + f=`echo $$x | sed 's/\.[^.]*$$/.cat8/'`; \ + if test -f "$(srcdir)/$$f"; then \ + b=`echo $$x | sed 's!$(MANRX)!\1!'`; \ + echo "$(INSTALL_DATA) $(srcdir)/$$f $(DESTDIR)$(cat8dir)/$$b.$(CATSUFFIX)";\ + $(INSTALL_DATA) $(srcdir)/$$g $(DESTDIR)$(cat8dir)/$$b.$(CATSUFFIX);\ + fi; \ + done ;\ + fi + +install-cat-mans: install-cat1-mans install-cat3-mans install-cat5-mans install-cat8-mans + +install-data-local: install-cat-mans + +.et.h: + $(COMPILE_ET) $< +.et.c: + $(COMPILE_ET) $< + +.x.c: + @cmp -s $< $@ 2> /dev/null || cp $< $@ + +check-local:: + @foo='$(CHECK_LOCAL)'; \ + if test "$$foo"; then \ + failed=0; all=0; \ + for i in $$foo; do \ + all=`expr $$all + 1`; \ + if ./$$i --version > /dev/null 2>&1; then \ + echo "PASS: $$i"; \ + else \ + echo "FAIL: $$i"; \ + failed=`expr $$failed + 1`; \ + fi; \ + done; \ + if test "$$failed" -eq 0; then \ + banner="All $$all tests passed"; \ + else \ + banner="$$failed of $$all tests failed"; \ + fi; \ + dashes=`echo "$$banner" | sed s/./=/g`; \ + echo "$$dashes"; \ + echo "$$banner"; \ + echo "$$dashes"; \ + test "$$failed" -eq 0; \ + fi + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/crypto/heimdal/doc/ack.texi b/crypto/heimdal/doc/ack.texi new file mode 100644 index 0000000..bfb03b8 --- /dev/null +++ b/crypto/heimdal/doc/ack.texi @@ -0,0 +1,55 @@ +@node Acknowledgments, , Windows 2000 compatability, Top +@comment node-name, next, previous, up +@appendix Acknowledgments + +Eric Young wrote ``libdes''. + +The University of California at Berkeley initially wrote @code{telnet}, +and @code{telnetd}. The authentication and encryption code of +@code{telnet} and @code{telnetd} was added by David Borman (then of Cray +Research, Inc). The encryption code was removed when this was exported +and then added back by Juha Eskelinen, @email{esc@@magic.fi}. + +The @code{popper} was also a Berkeley program initially. + +Some of the functions in @file{libroken} also come from Berkeley by way +of NetBSD/FreeBSD. + +@code{editline} was written by Simmule Turner and Rich Salz. + +Bugfixes, documentation, encouragement, and code has been contributed by: +@table @asis +@item Derrick J Brashear +@email{shadow@@dementia.org} +@item Ken Hornstein +@email{kenh@@cmf.nrl.navy.mil} +@item Johan Ihrén +@email{johani@@pdc.kth.se} +@item Love Hörnquist-Åstrand +@email{e96_lho@@e.kth.se} +@item Magnus Ahltorp +@email{map@@stacken.kth.se} +@item Mark Eichin +@email{eichin@@cygnus.com} +@item Marc Horowitz +@email{marc@@cygnus.com} +@item Luke Howard +@email{lukeh@@xedoc.com.au} +@item Brandon S. Allbery KF8NH +@email{allbery@@kf8nh.apk.net} +@item Jun-ichiro itojun Hagino +@email{itojun@@kame.net} +@item Daniel Kouril +@email{kouril@@informatics.muni.cz} +@item Åke Sandgren +@email{ake@@cs.umu.se} +@item Michal Vocu +@email{michal@@karlin.mff.cuni.cz} +@item Miroslav Ruda +@email{ruda@@ics.muni.cz} +@item Brian A May +@email{bmay@@snoopy.apana.org.au} +@item and we hope that those not mentioned here will forgive us. +@end table + +All bugs were introduced by ourselves. diff --git a/crypto/heimdal/doc/heimdal.texi b/crypto/heimdal/doc/heimdal.texi new file mode 100644 index 0000000..4cf1b3f --- /dev/null +++ b/crypto/heimdal/doc/heimdal.texi @@ -0,0 +1,246 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@c $Id: heimdal.texi,v 1.14 2000/01/02 04:09:00 assar Exp $ +@setfilename heimdal.info +@settitle HEIMDAL +@iftex +@afourpaper +@end iftex +@c some sensible characters, please? +@tex +\input latin1.tex +@end tex +@setchapternewpage on +@syncodeindex pg cp +@c %**end of header + +@c not yet @include version.texi +@set UPDATED $Date: 2000/01/02 04:09:00 $ +@set EDITION 0.0 +@set VERSION 0.2k + +@ifinfo +@dircategory Heimdal +@direntry +* Heimdal: (heimdal). The Kerberos 5 distribution from KTH +@end direntry +@end ifinfo + +@c title page +@titlepage +@title Heimdal +@subtitle Kerberos 5 from KTH +@subtitle Edition @value{EDITION}, for version @value{VERSION} +@subtitle 1999 +@author Johan Danielsson +@author Assar Westerlund +@author last updated @value{UPDATED} + +@def@copynext{@vskip 20pt plus 1fil@penalty-1000} +@def@copyrightstart{} +@def@copyrightend{} +@page +@copyrightstart +Copyright (c) 1997-2000 Kungliga Tekniska Högskolan +(Royal Institute of Technology, Stockholm, Sweden). +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. Neither the name of the Institute nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@copynext + +Copyright (C) 1995-1997 Eric Young (eay@@mincom.oz.au) +All rights reserved. + +This package is an DES implementation written by Eric Young (eay@@mincom.oz.au). +The implementation was written so as to conform with MIT's libdes. + +This library is free for commercial and non-commercial use as long as +the following conditions are aheared to. The following conditions +apply to all code found in this distribution. + +Copyright remains Eric Young's, and as such any Copyright notices in +the code are not to be removed. +If this package is used in a product, Eric Young should be given attribution +as the author of that the SSL library. This can be in the form of a textual +message at program startup or in documentation (online or textual) provided +with the package. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: + This product includes software developed by Eric Young (eay@@mincom.oz.au) + +THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@copynext + +Copyright (C) 1990 by the Massachusetts Institute of Technology + +Export of this software from the United States of America may +require a specific license from the United States Government. +It is the responsibility of any person or organization contemplating +export to obtain such a license before exporting. + +WITHIN THAT CONSTRAINT, permission to use, copy, modify, and +distribute this software and its documentation for any purpose and +without fee is hereby granted, provided that the above copyright +notice appear in all copies and that both that copyright notice and +this permission notice appear in supporting documentation, and that +the name of M.I.T. not be used in advertising or publicity pertaining +to distribution of the software without specific, written prior +permission. M.I.T. makes no representations about the suitability of +this software for any purpose. It is provided "as is" without express +or implied warranty. + +@copynext + +Copyright (c) 1988, 1990, 1993 + The Regents of the University of California. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +3. All advertising materials mentioning features or use of this software + must display the following acknowledgement: + This product includes software developed by the University of + California, Berkeley and its contributors. + +4. Neither the name of the University nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@copynext + +Copyright 1992 Simmule Turner and Rich Salz. All rights reserved. + +This software is not subject to any license of the American Telephone +and Telegraph Company or of the Regents of the University of California. + +Permission is granted to anyone to use this software for any purpose on +any computer system, and to alter it and redistribute it freely, subject +to the following restrictions: + +1. The authors are not responsible for the consequences of use of this + software, no matter how awful, even if they arise from flaws in it. + +2. The origin of this software must not be misrepresented, either by + explicit claim or by omission. Since few users ever read sources, + credits must appear in the documentation. + +3. Altered versions must be plainly marked as such, and must not be + misrepresented as being the original software. Since few users + ever read sources, credits must appear in the documentation. + +4. This notice may not be removed or altered. + +@copyrightend +@end titlepage + +@c Less filling! Tastes great! +@iftex +@parindent=0pt +@global@parskip 6pt plus 1pt +@global@chapheadingskip = 15pt plus 4pt minus 2pt +@global@secheadingskip = 12pt plus 3pt minus 2pt +@global@subsecheadingskip = 9pt plus 2pt minus 2pt +@end iftex +@ifinfo +@paragraphindent 0 +@end ifinfo + +@ifinfo +@node Top, Introduction, (dir), (dir) +@top Heimdal +@end ifinfo + +@menu +* Introduction:: +* What is Kerberos?:: +* Building and Installing:: +* Setting up a realm:: +* Things in search for a better place:: +* Kerberos 4 issues:: +* Windows 2000 compatability:: +* Acknowledgments:: + +@end menu + +@include intro.texi +@include whatis.texi +@include install.texi +@include setup.texi +@include misc.texi +@include kerberos4.texi +@include win2k.texi +@include ack.texi + +@c @shortcontents +@contents + +@bye diff --git a/crypto/heimdal/doc/init-creds b/crypto/heimdal/doc/init-creds new file mode 100644 index 0000000..13667e0 --- /dev/null +++ b/crypto/heimdal/doc/init-creds @@ -0,0 +1,374 @@ +Currently, getting an initial ticket for a user involves many function +calls, especially when a full set of features including password +expiration and challenge preauthentication is desired. In order to +solve this problem, a new api is proposed. + +typedef struct _krb5_prompt { + char *prompt; + int hidden; + krb5_data *reply; +} krb5_prompt; + +typedef int (*krb5_prompter_fct)(krb5_context context, + void *data, + const char *banner, + int num_prompts, + krb5_prompt prompts[]); + +typedef struct _krb5_get_init_creds_opt { + krb5_flags flags; + krb5_deltat tkt_life; + krb5_deltat renew_life; + int forwardable; + int proxiable; + krb5_enctype *etype_list; + int etype_list_length; + krb5_address **address_list; + /* XXX the next three should not be used, as they may be + removed later */ + krb5_preauthtype *preauth_list; + int preauth_list_length; + krb5_data *salt; +} krb5_get_init_creds_opt; + +#define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE 0x0001 +#define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE 0x0002 +#define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE 0x0004 +#define KRB5_GET_INIT_CREDS_OPT_PROXIABLE 0x0008 +#define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST 0x0010 +#define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST 0x0020 +#define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST 0x0040 +#define KRB5_GET_INIT_CREDS_OPT_SALT 0x0080 + +void krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt); + +void krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt, + krb5_deltat tkt_life); +void krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt, + krb5_deltat renew_life); +void krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt, + int forwardable); +void krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt, + int proxiable); +void krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt, + krb5_enctype *etype_list, + int etype_list_length); +void krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt, + krb5_address **addresses); +void krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt, + krb5_preauthtype *preauth_list, + int preauth_list_length); +void krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt, + krb5_data *salt); + +krb5_error_code +krb5_get_init_creds_password(krb5_context context, + krb5_creds *creds, + krb5_principal client, + char *password, + krb5_prompter_fct prompter, + void *data, + krb5_deltat start_time, + char *in_tkt_service, + krb5_get_init_creds_opt *options); + +This function will attempt to acquire an initial ticket. The function +will perform whatever tasks are necessary to do so. This may include +changing an expired password, preauthentication. + +The arguments divide into two types. Some arguments are basically +invariant and arbitrary across all initial tickets, and if not +specified are determined by configuration or library defaults. Some +arguments are different for each execution or application, and if not +specified can be determined correctly from system configuration or +environment. The former arguments are contained in a structure whose +pointer is passed to the function. A bitmask specifies which elements +of the structure should be used. In most cases, a NULL pointer can be +used. The latter arguments are specified as individual arguments to +the function. + +If a pointer to a credential is specified, the initial credential is +filled in. If the caller only wishes to do a simple password check +and will not be doing any other kerberos functions, then a NULL +pointer may be specified, and the credential will be destroyed. + +If the client name is non-NULL, the initial ticket requested will be +for that principal. Otherwise, the principal will be the the username +specified by the USER environment variable, or if the USER environment +variable is not set, the username corresponding to the real user id of +the caller. + +If the password is non-NULL, then this string is used as the password. +Otherwise, the prompter function will be used to prompt the user for +the password. + +If a prompter function is non-NULL, it will be used if additional user +input is required, such as if the user's password has expired and +needs to be changed, or if input preauthentication is necessary. If +no function is specified and input is required, then the login will +fail. + + The context argument is the same as that passed to krb5_login. + The data argument is passed unmodified to the prompter + function and is intended to be used to pass application data + (such as a display handle) to the prompter function. + + The banner argument, if non-NULL, will indicate what sort of + input is expected from the user (for example, "Password has + expired and must be changed" or "Enter Activcard response for + challenge 012345678"), and should be displayed accordingly. + + The num_prompts argument indicates the number of values which + should be prompted for. If num_prompts == 0, then the banner + contains an informational message which should be displayed to + the user. + + The prompts argument contains an array describing the values + for which the user should be prompted. The prompt member + indicates the prompt for each value ("Enter new + password"/"Enter it again", or "Challenge response"). The + hidden member is nonzero if the response should not be + displayed back to the user. The reply member is a pointer to + krb5_data structure which has already been allocated. The + prompter should fill in the structure with the NUL-terminated + response from the user. + + If the response data does not fit, or if any other error + occurs, then the prompter function should return a non-zero + value which will be returned by the krb5_get_init_creds + function. Otherwise, zero should be returned. + + The library function krb5_prompter_posix() implements + a prompter using a posix terminal for user in. This function + does not use the data argument. + +If the start_time is zero, then the requested ticket will be valid +beginning immediately. Otherwise, the start_time indicates how far in +the future the ticket should be postdated. + +If the in_tkt_service name is non-NULL, that principal name will be +used as the server name for the initial ticket request. The realm of +the name specified will be ignored and will be set to the realm of the +client name. If no in_tkt_service name is specified, +krbtgt/CLIENT-REALM@CLIENT-REALM will be used. + +For the rest of arguments, a configuration or library default will be +used if no value is specified in the options structure. + +If a tkt_life is specified, that will be the lifetime of the ticket. +The library default is 10 hours; there is no configuration variable +(there should be, but it's not there now). + +If a renew_life is specified and non-zero, then the RENEWABLE option +on the ticket will be set, and the value of the argument will be the +the renewable lifetime. The configuration variable [libdefaults] +"renew_lifetime" is the renewable lifetime if none is passed in. The +library default is not to set the RENEWABLE option. + +If forwardable is specified, the FORWARDABLE option on the ticket will +be set if and only if forwardable is non-zero. The configuration +variable [libdefaults] "forwardable" is used if no value is passed in. +The option will be set if and only if the variable is "y", "yes", +"true", "t", "1", or "on", case insensitive. The library default is +not to set the FORWARDABLE option. + +If proxiable is specified, the PROXIABLE option on the ticket will be +set if and only if proxiable is non-zero. The configuration variable +[libdefaults] "proxiable" is used if no value is passed in. The +option will be set if and only if the variable is "y", "yes", "true", +"t", "1", or "on", case insensitive. The library default is not to +set the PROXIABLE option. + +If etype_list is specified, it will be used as the list of desired +encryption algorithms in the request. The configuration variable +[libdefaults] "default_tkt_enctypes" is used if no value is passed in. +The library default is "des-cbc-md5 des-cbc-crc". + +If address_list is specified, it will be used as the list of addresses +for which the ticket will be valid. The library default is to use all +local non-loopback addresses. There is no configuration variable. + +If preauth_list is specified, it names preauth data types which will +be included in the request. The library default is to interact with +the kdc to determine the required preauth types. There is no +configuration variable. + +If salt is specified, it specifies the salt which will be used when +converting the password to a key. The library default is to interact +with the kdc to determine the correct salt. There is no configuration +variable. + +================================================================ + +typedef struct _krb5_verify_init_creds_opt { + krb5_flags flags; + int ap_req_nofail; +} krb5_verify_init_creds_opt; + +#define KRB5_VERIFY_INIT_CREDS_OPT_AP_REQ_NOFAIL 0x0001 + +void krb5_verify_init_creds_opt_init(krb5_init_creds_opt *options); +void krb5_verify_init_creds_opt_set_ap_req_nofail(krb5_init_creds_opt *options, + int ap_req_nofail); + +krb5_error_code +krb5_verify_init_creds(krb5_context context, + krb5_creds *creds, + krb5_principal ap_req_server, + krb5_keytab ap_req_keytab, + krb5_ccache *ccache, + krb5_verify_init_creds_opt *options); + +This function will use the initial ticket in creds to make an AP_REQ +and verify it to insure that the AS_REP has not been spoofed. + +If the ap_req_server name is non-NULL, then this service name will be +used for the AP_REQ; otherwise, the default host key +(host/hostname.domain@LOCAL-REALM) will be used. + +If ap_req_keytab is non-NULL, the service key for the verification +will be read from that keytab; otherwise, the service key will be read +from the default keytab. + +If the service of the ticket in creds is the same as the service name +for the AP_REQ, then this ticket will be used directly. If the ticket +is a tgt, then it will be used to obtain credentials for the service. +Otherwise, the verification will fail, and return an error. + +Other failures of the AP_REQ verification may or may not be considered +errors, as described below. + +If a pointer to a credential cache handle is specified, and the handle +is NULL, a credential cache handle referring to all credentials +obtained in the course of verifying the user will be returned. In +order to avoid potential setuid race conditions and other problems +related to file system access, this handle will refer to a memory +credential cache. If the handle is non-NULL, then the credentials +will be added to the existing ccache. If the caller only wishes to +verify the password and will not be doing any other kerberos +functions, then a NULL pointer may be specified, and the credentials +will be deleted before the function returns. + +If ap_req_nofail is specified, then failures of the AP_REQ +verification are considered errors if and only if ap_req_nofail is +non-zero. + +Whether or not AP_REQ validation is performed and what failures mean +depends on these inputs: + + A) The appropriate keytab exists and contains the named key. + + B) An AP_REQ request to the kdc succeeds, and the resulting AP_REQ +can be decrypted and verified. + + C) The administrator has specified in a configuration file that +AP_REQ validation must succeed. This is basically a paranoid bit, and +can be overridden by the application based on a command line flag or +other application-specific info. This flag is especially useful if +the admin is concerned that DNS might be spoofed while determining the +host/FQDN name. The configuration variable [libdefaults] +"verify_ap_req_nofail" is used if no value is passed in. The library +default is not to set this option. + +Initial ticket verification will succeed if and only if: + + - A && B or + - !A && !C + +================================================================ + +For illustrative purposes, here's the invocations I expect some +programs will use. Of course, error checking needs to be added. + +kinit: + + /* Fill in client from the command line || existing ccache, and, + start_time, and options.{tkt_life,renew_life,forwardable,proxiable} + from the command line. Some or all may remain unset. */ + + krb5_get_init_creds(context, &creds, client, + krb5_initial_prompter_posix, NULL, + start_time, NULL, &options); + krb5_cc_store_cred(context, ccache, &creds); + krb5_free_cred_contents(context, &creds); + +login: + + krb5_get_init_creds(context, &creds, client, + krb5_initial_prompter_posix, NULL, + 0, NULL, NULL); + krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); + /* setuid */ + krb5_cc_store_cred(context, ccache, &creds); + krb5_cc_copy(context, vcc, ccache); + krb5_free_cred_contents(context, &creds); + krb5_cc_destroy(context, vcc); + +xdm: + + krb5_get_initial_creds(context, &creds, client, + krb5_initial_prompter_xt, (void *) &xtstuff, + 0, NULL, NULL); + krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); + /* setuid */ + krb5_cc_store_cred(context, ccache, &creds); + krb5_free_cred_contents(context, &creds); + krb5_cc_copy(context, vcc, ccache); + krb5_cc_destroy(context, vcc); + +passwd: + + krb5_init_creds_opt_init(&options); + krb5_init_creds_opt_set_tkt_life = 300; + krb5_get_initial_creds(context, &creds, client, + krb5_initial_prompter_posix, NULL, + 0, "kadmin/changepw", &options); + /* change password */ + krb5_free_cred_contents(context, &creds); + +pop3d (simple password validator when no user interation possible): + + krb5_get_initial_creds(context, &creds, client, + NULL, NULL, 0, NULL, NULL); + krb5_verify_init_creds(context, &creds, NULL, NULL, &vcc, NULL); + krb5_cc_destroy(context, vcc); + +================================================================ + +password expiration has a subtlety. When a password expires and is +changed, there is a delay between when the master gets the new key +(immediately), and the slaves (propogation interval). So, when +getting an in_tkt, if the password is expired, the request should be +reissued to the master (this kind of sucks if you have SAM, oh well). +If this says expired, too, then the password should be changed, and +then the initial ticket request should be issued to the master again. +If the master times out, then a message that the password has expired +and cannot be changed due to the master being unreachable should be +displayed. + +================================================================ + +get_init_creds reads config stuff from: + +[libdefaults] + varname1 = defvalue + REALM = { + varname1 = value + varname2 = value + } + +typedef struct _krb5_get_init_creds_opt { + krb5_flags flags; + krb5_deltat tkt_life; /* varname = "ticket_lifetime" */ + krb5_deltat renew_life; /* varname = "renew_lifetime" */ + int forwardable; /* varname = "forwardable" */ + int proxiable; /* varname = "proxiable" */ + krb5_enctype *etype_list; /* varname = "default_tkt_enctypes" */ + int etype_list_length; + krb5_address **address_list; /* no varname */ + krb5_preauthtype *preauth_list; /* no varname */ + int preauth_list_length; + krb5_data *salt; +} krb5_get_init_creds_opt; + + diff --git a/crypto/heimdal/doc/install.texi b/crypto/heimdal/doc/install.texi new file mode 100644 index 0000000..5d195a6 --- /dev/null +++ b/crypto/heimdal/doc/install.texi @@ -0,0 +1,86 @@ +@node Building and Installing, Setting up a realm, What is Kerberos?, Top +@comment node-name, next, previous, up +@chapter Building and Installing + +Heimdal uses GNU Autoconf to configure for specific hosts, and GNU +Automake to manage makefiles. If this is new to you, the short +instruction is to run the @code{configure} script in the top level +directory, and when that finishes @code{make}. + +If you want to build the distribution in a different directory from the +source directory, you will need a make that implements VPATH correctly, +such as GNU make. + +You will need to build the distribution: + +@itemize @bullet +@item +A compiler that supports a ``loose'' ANSI C mode, such as @code{gcc}. +@item +lex or flex +@item +awk +@item +yacc or bison +@item +a socket library +@item +NDBM or Berkeley DB for building the server side. +@end itemize + +When everything is built, you can install by doing @kbd{make +install}. The default location for installation is @file{/usr/heimdal}, +but this can be changed by running @code{configure} with +@samp{--prefix=/some/other/place}. + +If you need to change the default behavior, configure understands the +following options: + +@table @asis +@item @kbd{--without-berkeley-db} +DB is preferred before NDBM, but if you for some reason want to use NDBM +instead, you can use this option. + +@item @kbd{--with-krb4=@file{dir}} +Gives the location of Kerberos 4 libraries and headers. This enables +Kerberos 4 support in the applications (telnet, rsh, popper, etc) and +the KDC. It is automatically check for in @file{/usr/athena}. If you +keep libraries and headers in different places, you can instead give the +path to each with the @kbd{--with-krb4-lib=@file{dir}}, and +@kbd{--with-krb4-include=@file{dir}} options. + +You will need a fairly recent version of our Kerberos 4 distribution for +@code{rshd} and @code{popper} to support version 4 clients. + +@item @kbd{--enable-kaserver} +Enables experimental kaserver support in the KDC. This is the protocol +used by the ``KDC'' in AFS. Requires Kerberos 4 support. + +@item @kbd{--enable-kaserver-db} +Enables experimental support for reading kaserver databases in hprop. +This is useful when migrating from a kaserver to a Heimdal KDC. + +@item @kbd{--disable-otp} +By default some of the application programs will build with support for +one-time passwords (OTP). Use this option to disable that support. + +@item @kbd{--enable-osfc2} +Enable some C2 support for OSF/Digital Unix/Tru64. Use this option if +you are running your OSF operating system in C2 mode. + +@item @kbd{--with-readline=@file{dir}} +Gives the path for the GNU Readline library, which will be used in some +programs. If no readline library is found, the (simpler) editline +library will be used instead. + +@item @kbd{--with-hesiod=@file{dir}} +Enables hesiod support in push. + +@item @kbd{--enable-netinfo} +Add support for using netinfo to lookup configuration information. +Probably only useful (and working) on NextStep/Mac OS X. + +@item @kbd{--without-ipv6} +Disable the IPv6 support. + +@end table diff --git a/crypto/heimdal/doc/intro.texi b/crypto/heimdal/doc/intro.texi new file mode 100644 index 0000000..518aada --- /dev/null +++ b/crypto/heimdal/doc/intro.texi @@ -0,0 +1,93 @@ +@node Introduction, What is Kerberos?, Top, Top +@c @node Introduction, What is Kerberos?, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +@heading What is Heimdal? + +Heimdal is a free implementation of Kerberos 5. The goals are to: + +@itemize @bullet +@item +have an implementation that can be freely used by anyone +@item +be protocol compatible with existing implementations and, if not in +conflict, with RFC 1510 (and any future updated RFC) +@item +be reasonably compatible with the M.I.T Kerberos V5 API +@item +have support for Kerberos V5 over GSS-API (RFC1964) +@item +include the most important and useful application programs (rsh, telnet, +popper, etc.) +@item +include enough backwards compatibility with Kerberos V4 +@end itemize + +@heading Status + +Heimdal has the following features (this does not mean any of this +works): + +@itemize @bullet +@item +a stub generator and a library to encode/decode/whatever ASN.1/DER +stuff +@item +a @code{libkrb5} library that should be possible to get to work with +simple applications +@item +a GSS-API library that should have all the important functions for +building applications +@item +Eric Young's @file{libdes} +@item +@file{kinit}, @file{klist}, @file{kdestroy} +@item +@file{telnet}, @file{telnetd} +@item +@file{rsh}, @file{rshd} +@item +@file{popper}, @file{push} (a movemail equivalent) +@item +@file{ftp}, and @file{ftpd} +@item +a library @file{libkafs} for authenticating to AFS and a program +@file{afslog} that uses it +@item +some simple test programs +@item +a KDC that supports most things; optionally, it may also support +Kerberos V4 and kaserver, +@item +simple programs for distributing databases between a KDC master and +slaves +@item +a password changing daemon @file{kpasswdd}, library functions for +changing passwords and a simple client +@item +some kind of administration system +@item +Kerberos V4 support in many of the applications. +@end itemize + +@heading Bug reports + +If you find bugs in this software, make sure it is a genuine bug and not +just a part of the code that isn't implemented. + +Bug reports should be sent to @email{heimdal-bugs@@pdc.kth.se}. Please +include information on what machine and operating system (including +version) you are running, what you are trying to do, what happens, what +you think should have happened, an example for us to repeat, the output +you get when trying the example, and a patch for the problem if you have +one. Please make any patches with @code{diff -u} or @code{diff -c}. + +Suggestions, comments and other non bug reports are also welcome. + +@heading Mailing list + +There are two mailing lists with talk about +Heimdal. @email{heimdal-announce@@sics.se} is a low-volume announcement +list, while @email{heimdal-discuss@@sics.se} is for general discussion. +Send a message to @email{majordomo@@sics.se} to subscribe. diff --git a/crypto/heimdal/doc/kerberos4.texi b/crypto/heimdal/doc/kerberos4.texi new file mode 100644 index 0000000..93671f9 --- /dev/null +++ b/crypto/heimdal/doc/kerberos4.texi @@ -0,0 +1,183 @@ +@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 + +If compiled with version 4 support, the KDC can serve requests from a +Kerberos 4 client. There are a few things you must do for this to work. + +@menu +* Principal conversion issues:: +* Converting a version 4 database:: +@end menu + +@node Principal conversion issues, Converting a version 4 database, Kerberos 4 issues, Kerberos 4 issues +@section Principal conversion issues + +First, Kerberos 4 and Kerberos 5 principals are different. A version 4 +principal consists of a name, an instance, and a realm. A version 5 +principal has one or more components, and a realm (the terms ``name'' +and ``instance'' are still used, for the first and second component, +respectively). Also, in some cases the name of a version 4 principal +differs from the first component of the corresponding version 5 +principal. One notable example is the ``host'' type principals, where +the version 4 name is @samp{rcmd} (for ``remote command''), and the +version 5 name is @samp{host}. For the class of principals that has a +hostname as instance, there is an other major difference, Kerberos 4 +uses only the first component of the hostname, whereas Kerberos 5 uses +the fully qualified hostname. + +Because of this it can be hard or impossible to correctly convert a +version 4 principal to a version 5 principal @footnote{the other way is +not always trivial either, but usually easier}. The biggest problem is +to know if the conversion resulted in a valid principal. To give an +example, suppose you want to convert the principal @samp{rcmd.foo}. + +The @samp{rcmd} name suggests that the instance is a hostname (even if +there are exceptions to this rule). To correctly convert the instance +@samp{foo} to a hostname, you have to know which host it is referring +to. You can to this by either guessing (from the realm) which domain +name to append, or you have to have a list of possible hostnames. In the +simplest cases you can cover most principals with the first rule. If you +have several domains sharing a single realm this will not usually +work. If the exceptions are few you can probably come by with a lookup +table for the exceptions. + +In a complex scenario you will need some kind of host lookup mechanism. +Using DNS for this is tempting, but DNS is error prone, slow and unsafe +@footnote{at least until secure DNS is commonly available}. + +Fortunately, the KDC has a trump on hand: it can easily tell if a +principal exists in the database. The KDC will use +@code{krb5_425_conv_principal_ext} to convert principals when handling +to version 4 requests. + +@node Converting a version 4 database, , Principal conversion issues, Kerberos 4 issues +@section Converting a version 4 database + +If you want to convert an existing version 4 database, the principal +conversion issue arises too. + +If you decide to convert your database once and for all, you will only +have to do this conversion once. It is also possible to run a version 5 +KDC as a slave to a version 4 KDC. In this case this conversion will +happen every time the database is propagated. When doing this +conversion, there are a few things to look out for. If you have stale +entries in the database, these entries will not be converted. This might +be because these principals are not used anymore, or it might be just +because the principal couldn't be converted. + +You might also see problems with a many-to-one mapping of +principals. For instance, if you are using DNS lookups and you have two +principals @samp{rcmd.foo} and @samp{rcmd.bar}, where `foo' is a CNAME +for `bar', the resulting principals will be the same. Since the +conversion function can't tell which is correct, these conflicts will +have to be resolved manually. + +@subsection Conversion example + +Given the following set of hosts and services: + +@example +foo.se rcmd +mail.foo.se rcmd, pop +ftp.bar.se rcmd, ftp +@end example + +you have a database that consists of the following principals: + +@samp{rcmd.foo}, @samp{rcmd.mail}, @samp{pop.mail}, @samp{rcmd.ftp}, and +@samp{ftp.ftp}. + +lets say you also got these extra principals: @samp{rcmd.gone}, +@samp{rcmd.old-mail}, where @samp{gone.foo.se} was a machine that has +now passed away, and @samp{old-mail.foo.se} was an old mail machine that +is now a CNAME for @samp{mail.foo.se}. + +When you convert this database you want the following conversions to be +done: +@example +rcmd.foo host/foo.se +rcmd.mail host/mail.foo.se +pop.mail pop/mail.foo.se +rcmd.ftp host/ftp.bar.se +ftp.ftp ftp/ftp.bar.se +rcmd.gone @i{removed} +rcmd.old-mail @i{removed} +@end example + +A @file{krb5.conf} that does this looks like: + +@example +[realms] + FOO.SE = @{ + v4_name_convert = @{ + host = @{ + ftp = ftp + pop = pop + rcmd = host + @} + @} + v4_instance_convert = @{ + foo = foo.se + ftp = ftp.bar.se + @} + default_domain = foo.se + @} +@end example + +The @samp{v4_name_convert} section says which names should be considered +having an instance consisting of a hostname, and it also says how the +names should be converted (for instance @samp{rcmd} should be converted +to @samp{host}). The @samp{v4_instance_convert} section says how a +hostname should be qualified (this is just a hosts-file in +disguise). Host-instances that aren't covered by +@samp{v4_instance_convert} are qualified by appending the contents of +the @samp{default_domain}. + +Actually, this example doesn't work. Or rather, it works to well. Since +it has no way of knowing which hostnames are valid and which are not, it +will happily convert @samp{rcmd.gone} to @samp{host/gone.foo.se}. This +isn't a big problem, but if you have run your kerberos realm for a few +years, chances are big that you have quite a few `junk' principals. + +If you don't want this you can remove the @samp{default_domain} +statement, but then you will have to add entries for @emph{all} your hosts +in the @samp{v4_instance_convert} section. + +Instead of doing this you can use DNS to convert instances. This is not +a solution without problems, but it is probably easier than adding lots +of static host entries. + +To enable DNS lookup you should turn on @samp{v4_instance_resolve} in +the @samp{[libdefaults]} section. + +@subsection Converting a database + +The database conversion is done with @samp{hprop}. Assuming that you +have the @samp{kadmin/hprop} key in the keytab @file{hprop.keytab}, you +can run this command to propagate the database to the machine called +@samp{slave-server} (which should be running a @samp{hpropd}). + +@example +hprop -4 -E -k hprop.keytab slave-server +@end example + +@section Version 4 Kadmin + +@samp{kadmind} can act as a version 4 kadmind, and you can do most +operations, but with some restrictions (since the version 4 kadmin +protocol is, lets say, very ad hoc.) One example is that it only passes +des keys when creating principals and changing passwords (modern kpasswd +clients do send the password, so it's possible to to password quality +checks). Because of this you can only create principals with des keys, +and you can't set any flags or do any other fancy stuff. + +To get this to work, you have to create a @samp{changepw/kerberos} +principal (if you are converting a version 4 data you should have this +principal), and add it to the keytab the @samp{kadmind} is using. You +then have to add another entry to inetd (since version 4 uses port 751, +not 749). + +@emph{And then there are a many more things you can do; more on this in +a later version of this manual. Until then, UTSL.} + diff --git a/crypto/heimdal/doc/latin1.tex b/crypto/heimdal/doc/latin1.tex new file mode 100644 index 0000000..e683dd2 --- /dev/null +++ b/crypto/heimdal/doc/latin1.tex @@ -0,0 +1,95 @@ +% ISO Latin 1 (ISO 8859/1) encoding for Computer Modern fonts. +% Jan Michael Rynning <jmr@nada.kth.se> 1990-10-12 +\def\inmathmode#1{\relax\ifmmode#1\else$#1$\fi} +\global\catcode`\^^a0=\active \global\let^^a0=~ % no-break space +\global\catcode`\^^a1=\active \global\def^^a1{!`} % inverted exclamation mark +\global\catcode`\^^a2=\active \global\def^^a2{{\rm\rlap/c}} % cent sign +\global\catcode`\^^a3=\active \global\def^^a3{{\it\$}} % pound sign +% currency sign, yen sign, broken bar +\global\catcode`\^^a7=\active \global\let^^a7=\S % section sign +\global\catcode`\^^a8=\active \global\def^^a8{\"{}} % diaeresis +\global\catcode`\^^a9=\active \global\let^^a9=\copyright % copyright sign +% feminine ordinal indicator, left angle quotation mark +\global\catcode`\^^ac=\active \global\def^^ac{\inmathmode\neg}% not sign +\global\catcode`\^^ad=\active \global\let^^ad=\- % soft hyphen +% registered trade mark sign +\global\catcode`\^^af=\active \global\def^^af{\={}} % macron +% ... +\global\catcode`\^^b1=\active \global\def^^b1{\inmathmode\pm} % plus minus +\global\catcode`\^^b2=\active \global\def^^b2{\inmathmode{{^2}}} +\global\catcode`\^^b3=\active \global\def^^b3{\inmathmode{{^3}}} +\global\catcode`\^^b4=\active \global\def^^b4{\'{}} % acute accent +\global\catcode`\^^b5=\active \global\def^^b5{\inmathmode\mu} % mu +\global\catcode`\^^b6=\active \global\let^^b6=\P % pilcroy +\global\catcode`\^^b7=\active \global\def^^b7{\inmathmode{{\cdot}}} +\global\catcode`\^^b8=\active \global\def^^b8{\c{}} % cedilla +\global\catcode`\^^b9=\active \global\def^^b9{\inmathmode{{^1}}} +% ... +\global\catcode`\^^bc=\active \global\def^^bc{\inmathmode{{1\over4}}} +\global\catcode`\^^bd=\active \global\def^^bd{\inmathmode{{1\over2}}} +\global\catcode`\^^be=\active \global\def^^be{\inmathmode{{3\over4}}} +\global\catcode`\^^bf=\active \global\def^^bf{?`} % inverted question mark +\global\catcode`\^^c0=\active \global\def^^c0{\`A} +\global\catcode`\^^c1=\active \global\def^^c1{\'A} +\global\catcode`\^^c2=\active \global\def^^c2{\^A} +\global\catcode`\^^c3=\active \global\def^^c3{\~A} +\global\catcode`\^^c4=\active \global\def^^c4{\"A} % capital a with diaeresis +\global\catcode`\^^c5=\active \global\let^^c5=\AA % capital a with ring above +\global\catcode`\^^c6=\active \global\let^^c6=\AE +\global\catcode`\^^c7=\active \global\def^^c7{\c C} +\global\catcode`\^^c8=\active \global\def^^c8{\`E} +\global\catcode`\^^c9=\active \global\def^^c9{\'E} +\global\catcode`\^^ca=\active \global\def^^ca{\^E} +\global\catcode`\^^cb=\active \global\def^^cb{\"E} +\global\catcode`\^^cc=\active \global\def^^cc{\`I} +\global\catcode`\^^cd=\active \global\def^^cd{\'I} +\global\catcode`\^^ce=\active \global\def^^ce{\^I} +\global\catcode`\^^cf=\active \global\def^^cf{\"I} +% capital eth +\global\catcode`\^^d1=\active \global\def^^d1{\~N} +\global\catcode`\^^d2=\active \global\def^^d2{\`O} +\global\catcode`\^^d3=\active \global\def^^d3{\'O} +\global\catcode`\^^d4=\active \global\def^^d4{\^O} +\global\catcode`\^^d5=\active \global\def^^d5{\~O} +\global\catcode`\^^d6=\active \global\def^^d6{\"O} % capital o with diaeresis +\global\catcode`\^^d7=\active \global\def^^d7{\inmathmode\times}% multiplication sign +\global\catcode`\^^d8=\active \global\let^^d8=\O +\global\catcode`\^^d9=\active \global\def^^d9{\`U} +\global\catcode`\^^da=\active \global\def^^da{\'U} +\global\catcode`\^^db=\active \global\def^^db{\^U} +\global\catcode`\^^dc=\active \global\def^^dc{\"U} +\global\catcode`\^^dd=\active \global\def^^dd{\'Y} +% capital thorn +\global\catcode`\^^df=\active \global\def^^df{\ss} +\global\catcode`\^^e0=\active \global\def^^e0{\`a} +\global\catcode`\^^e1=\active \global\def^^e1{\'a} +\global\catcode`\^^e2=\active \global\def^^e2{\^a} +\global\catcode`\^^e3=\active \global\def^^e3{\~a} +\global\catcode`\^^e4=\active \global\def^^e4{\"a} % small a with diaeresis +\global\catcode`\^^e5=\active \global\let^^e5=\aa % small a with ring above +\global\catcode`\^^e6=\active \global\let^^e6=\ae +\global\catcode`\^^e7=\active \global\def^^e7{\c c} +\global\catcode`\^^e8=\active \global\def^^e8{\`e} +\global\catcode`\^^e9=\active \global\def^^e9{\'e} +\global\catcode`\^^ea=\active \global\def^^ea{\^e} +\global\catcode`\^^eb=\active \global\def^^eb{\"e} +\global\catcode`\^^ec=\active \global\def^^ec{\`\i} +\global\catcode`\^^ed=\active \global\def^^ed{\'\i} +\global\catcode`\^^ee=\active \global\def^^ee{\^\i} +\global\catcode`\^^ef=\active \global\def^^ef{\"\i} +% small eth +\global\catcode`\^^f1=\active \global\def^^f1{\~n} +\global\catcode`\^^f2=\active \global\def^^f2{\`o} +\global\catcode`\^^f3=\active \global\def^^f3{\'o} +\global\catcode`\^^f4=\active \global\def^^f4{\^o} +\global\catcode`\^^f5=\active \global\def^^f5{\~o} +\global\catcode`\^^f6=\active \global\def^^f6{\"o} % small o with diaeresis +\global\catcode`\^^f7=\active \global\def^^f7{\inmathmode\div}% division sign +\global\catcode`\^^f8=\active \global\let^^f8=\o +\global\catcode`\^^f9=\active \global\def^^f9{\`u} +\global\catcode`\^^fa=\active \global\def^^fa{\'u} +\global\catcode`\^^fb=\active \global\def^^fb{\^u} +\global\catcode`\^^fc=\active \global\def^^fc{\"u} +\global\catcode`\^^fd=\active \global\def^^fd{\'y} +% capital thorn +\global\catcode`\^^ff=\active \global\def^^ff{\"y} diff --git a/crypto/heimdal/doc/layman.asc b/crypto/heimdal/doc/layman.asc new file mode 100644 index 0000000..d4fbe64 --- /dev/null +++ b/crypto/heimdal/doc/layman.asc @@ -0,0 +1,1855 @@ +A Layman's Guide to a Subset of ASN.1, BER, and DER + +An RSA Laboratories Technical Note +Burton S. Kaliski Jr. +Revised November 1, 1993 + + +Supersedes June 3, 1991 version, which was also published as +NIST/OSI Implementors' Workshop document SEC-SIG-91-17. +PKCS documents are available by electronic mail to +<pkcs@rsa.com>. + +Copyright (C) 1991-1993 RSA Laboratories, a division of RSA +Data Security, Inc. License to copy this document is granted +provided that it is identified as "RSA Data Security, Inc. +Public-Key Cryptography Standards (PKCS)" in all material +mentioning or referencing this document. +003-903015-110-000-000 + + +Abstract. This note gives a layman's introduction to a +subset of OSI's Abstract Syntax Notation One (ASN.1), Basic +Encoding Rules (BER), and Distinguished Encoding Rules +(DER). The particular purpose of this note is to provide +background material sufficient for understanding and +implementing the PKCS family of standards. + + +1. Introduction + +It is a generally accepted design principle that abstraction +is a key to managing software development. With abstraction, +a designer can specify a part of a system without concern +for how the part is actually implemented or represented. +Such a practice leaves the implementation open; it +simplifies the specification; and it makes it possible to +state "axioms" about the part that can be proved when the +part is implemented, and assumed when the part is employed +in another, higher-level part. Abstraction is the hallmark +of most modern software specifications. + +One of the most complex systems today, and one that also +involves a great deal of abstraction, is Open Systems +Interconnection (OSI, described in X.200). OSI is an +internationally standardized architecture that governs the +interconnection of computers from the physical layer up to +the user application layer. Objects at higher layers are +defined abstractly and intended to be implemented with +objects at lower layers. For instance, a service at one +layer may require transfer of certain abstract objects +between computers; a lower layer may provide transfer +services for strings of ones and zeroes, using encoding +rules to transform the abstract objects into such strings. +OSI is called an open system because it supports many +different implementations of the services at each layer. + +OSI's method of specifying abstract objects is called ASN.1 +(Abstract Syntax Notation One, defined in X.208), and one +set of rules for representing such objects as strings of +ones and zeros is called the BER (Basic Encoding Rules, +defined in X.209). ASN.1 is a flexible notation that allows +one to define a variety data types, from simple types such +as integers and bit strings to structured types such as sets +and sequences, as well as complex types defined in terms of +others. BER describes how to represent or encode values of +each ASN.1 type as a string of eight-bit octets. There is +generally more than one way to BER-encode a given value. +Another set of rules, called the Distinguished Encoding +Rules (DER), which is a subset of BER, gives a unique +encoding to each ASN.1 value. + +The purpose of this note is to describe a subset of ASN.1, +BER and DER sufficient to understand and implement one OSI- +based application, RSA Data Security, Inc.'s Public-Key +Cryptography Standards. The features described include an +overview of ASN.1, BER, and DER and an abridged list of +ASN.1 types and their BER and DER encodings. Sections 2-4 +give an overview of ASN.1, BER, and DER, in that order. +Section 5 lists some ASN.1 types, giving their notation, +specific encoding rules, examples, and comments about their +application to PKCS. Section 6 concludes with an example, +X.500 distinguished names. + +Advanced features of ASN.1, such as macros, are not +described in this note, as they are not needed to implement +PKCS. For information on the other features, and for more +detail generally, the reader is referred to CCITT +Recommendations X.208 and X.209, which define ASN.1 and BER. + +Terminology and notation. In this note, an octet is an eight- +bit unsigned integer. Bit 8 of the octet is the most +significant and bit 1 is the least significant. + +The following meta-syntax is used for in describing ASN.1 +notation: + + BIT monospace denotes literal characters in the type + and value notation; in examples, it generally + denotes an octet value in hexadecimal + + n1 bold italics denotes a variable + + [] bold square brackets indicate that a term is + optional + + {} bold braces group related terms + + | bold vertical bar delimits alternatives with a + group + + ... bold ellipsis indicates repeated occurrences + + = bold equals sign expresses terms as subterms + + +2. Abstract Syntax Notation One + +Abstract Syntax Notation One, abbreviated ASN.1, is a +notation for describing abstract types and values. + +In ASN.1, a type is a set of values. For some types, there +are a finite number of values, and for other types there are +an infinite number. A value of a given ASN.1 type is an +element of the type's set. ASN.1 has four kinds of type: +simple types, which are "atomic" and have no components; +structured types, which have components; tagged types, which +are derived from other types; and other types, which include +the CHOICE type and the ANY type. Types and values can be +given names with the ASN.1 assignment operator (::=) , and +those names can be used in defining other types and values. + +Every ASN.1 type other than CHOICE and ANY has a tag, which +consists of a class and a nonnegative tag number. ASN.1 +types are abstractly the same if and only if their tag +numbers are the same. In other words, the name of an ASN.1 +type does not affect its abstract meaning, only the tag +does. There are four classes of tag: + + Universal, for types whose meaning is the same in all + applications; these types are only defined in + X.208. + + Application, for types whose meaning is specific to an + application, such as X.500 directory services; + types in two different applications may have the + same application-specific tag and different + meanings. + + Private, for types whose meaning is specific to a given + enterprise. + + Context-specific, for types whose meaning is specific + to a given structured type; context-specific tags + are used to distinguish between component types + with the same underlying tag within the context of + a given structured type, and component types in + two different structured types may have the same + tag and different meanings. + +The types with universal tags are defined in X.208, which +also gives the types' universal tag numbers. Types with +other tags are defined in many places, and are always +obtained by implicit or explicit tagging (see Section 2.3). +Table 1 lists some ASN.1 types and their universal-class +tags. + + Type Tag number Tag number + (decimal) (hexadecimal) + INTEGER 2 02 + BIT STRING 3 03 + OCTET STRING 4 04 + NULL 5 05 + OBJECT IDENTIFIER 6 06 + SEQUENCE and SEQUENCE OF 16 10 + SET and SET OF 17 11 + PrintableString 19 13 + T61String 20 14 + IA5String 22 16 + UTCTime 23 17 + + Table 1. Some types and their universal-class tags. + +ASN.1 types and values are expressed in a flexible, +programming-language-like notation, with the following +special rules: + + o Layout is not significant; multiple spaces and + line breaks can be considered as a single space. + + o Comments are delimited by pairs of hyphens (--), + or a pair of hyphens and a line break. + + o Identifiers (names of values and fields) and type + references (names of types) consist of upper- and + lower-case letters, digits, hyphens, and spaces; + identifiers begin with lower-case letters; type + references begin with upper-case letters. + +The following four subsections give an overview of simple +types, structured types, implicitly and explicitly tagged +types, and other types. Section 5 describes specific types +in more detail. + + +2.1 Simple types + +Simple types are those not consisting of components; they +are the "atomic" types. ASN.1 defines several; the types +that are relevant to the PKCS standards are the following: + + BIT STRING, an arbitrary string of bits (ones and + zeroes). + + IA5String, an arbitrary string of IA5 (ASCII) + characters. + + INTEGER, an arbitrary integer. + + NULL, a null value. + + OBJECT IDENTIFIER, an object identifier, which is a + sequence of integer components that identify an + object such as an algorithm or attribute type. + + OCTET STRING, an arbitrary string of octets (eight-bit + values). + + PrintableString, an arbitrary string of printable + characters. + + T61String, an arbitrary string of T.61 (eight-bit) + characters. + + UTCTime, a "coordinated universal time" or Greenwich + Mean Time (GMT) value. + +Simple types fall into two categories: string types and non- +string types. BIT STRING, IA5String, OCTET STRING, +PrintableString, T61String, and UTCTime are string types. + +String types can be viewed, for the purposes of encoding, as +consisting of components, where the components are +substrings. This view allows one to encode a value whose +length is not known in advance (e.g., an octet string value +input from a file stream) with a constructed, indefinite- +length encoding (see Section 3). + +The string types can be given size constraints limiting the +length of values. + + +2.2 Structured types + +Structured types are those consisting of components. ASN.1 +defines four, all of which are relevant to the PKCS +standards: + + SEQUENCE, an ordered collection of one or more types. + + SEQUENCE OF, an ordered collection of zero or more + occurrences of a given type. + + SET, an unordered collection of one or more types. + + SET OF, an unordered collection of zero or more + occurrences of a given type. + +The structured types can have optional components, possibly +with default values. + + +2.3 Implicitly and explicitly tagged types + +Tagging is useful to distinguish types within an +application; it is also commonly used to distinguish +component types within a structured type. For instance, +optional components of a SET or SEQUENCE type are typically +given distinct context-specific tags to avoid ambiguity. + +There are two ways to tag a type: implicitly and explicitly. + +Implicitly tagged types are derived from other types by +changing the tag of the underlying type. Implicit tagging is +denoted by the ASN.1 keywords [class number] IMPLICIT (see +Section 5.1). + +Explicitly tagged types are derived from other types by +adding an outer tag to the underlying type. In effect, +explicitly tagged types are structured types consisting of +one component, the underlying type. Explicit tagging is +denoted by the ASN.1 keywords [class number] EXPLICIT (see +Section 5.2). + +The keyword [class number] alone is the same as explicit +tagging, except when the "module" in which the ASN.1 type is +defined has implicit tagging by default. ("Modules" are +among the advanced features not described in this note.) + +For purposes of encoding, an implicitly tagged type is +considered the same as the underlying type, except that the +tag is different. An explicitly tagged type is considered +like a structured type with one component, the underlying +type. Implicit tags result in shorter encodings, but +explicit tags may be necessary to avoid ambiguity if the tag +of the underlying type is indeterminate (e.g., the +underlying type is CHOICE or ANY). + + +2.4 Other types + +Other types in ASN.1 include the CHOICE and ANY types. The +CHOICE type denotes a union of one or more alternatives; the +ANY type denotes an arbitrary value of an arbitrary type, +where the arbitrary type is possibly defined in the +registration of an object identifier or integer value. + + +3. Basic Encoding Rules + +The Basic Encoding Rules for ASN.1, abbreviated BER, give +one or more ways to represent any ASN.1 value as an octet +string. (There are certainly other ways to represent ASN.1 +values, but BER is the standard for interchanging such +values in OSI.) + +There are three methods to encode an ASN.1 value under BER, +the choice of which depends on the type of value and whether +the length of the value is known. The three methods are +primitive, definite-length encoding; constructed, definite- +length encoding; and constructed, indefinite-length +encoding. Simple non-string types employ the primitive, +definite-length method; structured types employ either of +the constructed methods; and simple string types employ any +of the methods, depending on whether the length of the value +is known. Types derived by implicit tagging employ the +method of the underlying type and types derived by explicit +tagging employ the constructed methods. + +In each method, the BER encoding has three or four parts: + + Identifier octets. These identify the class and tag + number of the ASN.1 value, and indicate whether + the method is primitive or constructed. + + Length octets. For the definite-length methods, these + give the number of contents octets. For the + constructed, indefinite-length method, these + indicate that the length is indefinite. + + Contents octets. For the primitive, definite-length + method, these give a concrete representation of + the value. For the constructed methods, these + give the concatenation of the BER encodings of the + components of the value. + + End-of-contents octets. For the constructed, indefinite- + length method, these denote the end of the + contents. For the other methods, these are absent. + +The three methods of encoding are described in the following +sections. + + +3.1 Primitive, definite-length method + +This method applies to simple types and types derived from +simple types by implicit tagging. It requires that the +length of the value be known in advance. The parts of the +BER encoding are as follows: + +Identifier octets. There are two forms: low tag number (for +tag numbers between 0 and 30) and high tag number (for tag +numbers 31 and greater). + + Low-tag-number form. One octet. Bits 8 and 7 specify + the class (see Table 2), bit 6 has value "0," + indicating that the encoding is primitive, and + bits 5-1 give the tag number. + + Class Bit Bit + 8 7 + universal 0 0 + application 0 1 + context-specific 1 0 + private 1 1 + + Table 2. Class encoding in identifier octets. + + High-tag-number form. Two or more octets. First octet + is as in low-tag-number form, except that bits 5-1 + all have value "1." Second and following octets + give the tag number, base 128, most significant + digit first, with as few digits as possible, and + with the bit 8 of each octet except the last set + to "1." + +Length octets. There are two forms: short (for lengths +between 0 and 127), and long definite (for lengths between 0 +and 21008-1). + + Short form. One octet. Bit 8 has value "0" and bits 7-1 + give the length. + + Long form. Two to 127 octets. Bit 8 of first octet has + value "1" and bits 7-1 give the number of + additional length octets. Second and following + octets give the length, base 256, most significant + digit first. + +Contents octets. These give a concrete representation of the +value (or the value of the underlying type, if the type is +derived by implicit tagging). Details for particular types +are given in Section 5. + + +3.2 Constructed, definite-length method + +This method applies to simple string types, structured +types, types derived simple string types and structured +types by implicit tagging, and types derived from anything +by explicit tagging. It requires that the length of the +value be known in advance. The parts of the BER encoding are +as follows: + +Identifier octets. As described in Section 3.1, except that +bit 6 has value "1," indicating that the encoding is +constructed. + +Length octets. As described in Section 3.1. + +Contents octets. The concatenation of the BER encodings of +the components of the value: + + o For simple string types and types derived from + them by implicit tagging, the concatenation of the + BER encodings of consecutive substrings of the + value (underlying value for implicit tagging). + + o For structured types and types derived from them + by implicit tagging, the concatenation of the BER + encodings of components of the value (underlying + value for implicit tagging). + + o For types derived from anything by explicit + tagging, the BER encoding of the underlying value. + +Details for particular types are given in Section 5. + + +3.3 Constructed, indefinite-length method + +This method applies to simple string types, structured +types, types derived simple string types and structured +types by implicit tagging, and types derived from anything +by explicit tagging. It does not require that the length of +the value be known in advance. The parts of the BER encoding +are as follows: + +Identifier octets. As described in Section 3.2. + +Length octets. One octet, 80. + +Contents octets. As described in Section 3.2. + +End-of-contents octets. Two octets, 00 00. + +Since the end-of-contents octets appear where an ordinary +BER encoding might be expected (e.g., in the contents octets +of a sequence value), the 00 and 00 appear as identifier and +length octets, respectively. Thus the end-of-contents octets +is really the primitive, definite-length encoding of a value +with universal class, tag number 0, and length 0. + + +4. Distinguished Encoding Rules + +The Distinguished Encoding Rules for ASN.1, abbreviated DER, +are a subset of BER, and give exactly one way to represent +any ASN.1 value as an octet string. DER is intended for +applications in which a unique octet string encoding is +needed, as is the case when a digital signature is computed +on an ASN.1 value. DER is defined in Section 8.7 of X.509. + +DER adds the following restrictions to the rules given in +Section 3: + + 1. When the length is between 0 and 127, the short + form of length must be used + + 2. When the length is 128 or greater, the long form + of length must be used, and the length must be + encoded in the minimum number of octets. + + 3. For simple string types and implicitly tagged + types derived from simple string types, the + primitive, definite-length method must be + employed. + + 4. For structured types, implicitly tagged types + derived from structured types, and explicitly + tagged types derived from anything, the + constructed, definite-length method must be + employed. + +Other restrictions are defined for particular types (such as +BIT STRING, SEQUENCE, SET, and SET OF), and can be found in +Section 5. + + +5. Notation and encodings for some types + +This section gives the notation for some ASN.1 types and +describes how to encode values of those types under both BER +and DER. + +The types described are those presented in Section 2. They +are listed alphabetically here. + +Each description includes ASN.1 notation, BER encoding, and +DER encoding. The focus of the encodings is primarily on the +contents octets; the tag and length octets follow Sections 3 +and 4. The descriptions also explain where each type is used +in PKCS and related standards. ASN.1 notation is generally +only for types, although for the type OBJECT IDENTIFIER, +value notation is given as well. + + +5.1 Implicitly tagged types + +An implicitly tagged type is a type derived from another +type by changing the tag of the underlying type. + +Implicit tagging is used for optional SEQUENCE components +with underlying type other than ANY throughout PKCS, and for +the extendedCertificate alternative of PKCS #7's +ExtendedCertificateOrCertificate type. + +ASN.1 notation: + +[[class] number] IMPLICIT Type + +class = UNIVERSAL | APPLICATION | PRIVATE + +where Type is a type, class is an optional class name, and +number is the tag number within the class, a nonnegative +integer. + +In ASN.1 "modules" whose default tagging method is implicit +tagging, the notation [[class] number] Type is also +acceptable, and the keyword IMPLICIT is implied. (See +Section 2.3.) For definitions stated outside a module, the +explicit inclusion of the keyword IMPLICIT is preferable to +prevent ambiguity. + +If the class name is absent, then the tag is context- +specific. Context-specific tags can only appear in a +component of a structured or CHOICE type. + +Example: PKCS #8's PrivateKeyInfo type has an optional +attributes component with an implicit, context-specific tag: + +PrivateKeyInfo ::= SEQUENCE { + version Version, + privateKeyAlgorithm PrivateKeyAlgorithmIdentifier, + privateKey PrivateKey, + attributes [0] IMPLICIT Attributes OPTIONAL } + +Here the underlying type is Attributes, the class is absent +(i.e., context-specific), and the tag number within the +class is 0. + +BER encoding. Primitive or constructed, depending on the +underlying type. Contents octets are as for the BER encoding +of the underlying value. + +Example: The BER encoding of the attributes component of a +PrivateKeyInfo value is as follows: + + o the identifier octets are 80 if the underlying + Attributes value has a primitive BER encoding and + a0 if the underlying Attributes value has a + constructed BER encoding + + o the length and contents octets are the same as the + length and contents octets of the BER encoding of + the underlying Attributes value + +DER encoding. Primitive or constructed, depending on the +underlying type. Contents octets are as for the DER encoding +of the underlying value. + + +5.2 Explicitly tagged types + +Explicit tagging denotes a type derived from another type by +adding an outer tag to the underlying type. + +Explicit tagging is used for optional SEQUENCE components +with underlying type ANY throughout PKCS, and for the +version component of X.509's Certificate type. + +ASN.1 notation: + +[[class] number] EXPLICIT Type + +class = UNIVERSAL | APPLICATION | PRIVATE + +where Type is a type, class is an optional class name, and +number is the tag number within the class, a nonnegative +integer. + +If the class name is absent, then the tag is context- +specific. Context-specific tags can only appear in a +component of a SEQUENCE, SET or CHOICE type. + +In ASN.1 "modules" whose default tagging method is explicit +tagging, the notation [[class] number] Type is also +acceptable, and the keyword EXPLICIT is implied. (See +Section 2.3.) For definitions stated outside a module, the +explicit inclusion of the keyword EXPLICIT is preferable to +prevent ambiguity. + +Example 1: PKCS #7's ContentInfo type has an optional +content component with an explicit, context-specific tag: + +ContentInfo ::= SEQUENCE { + contentType ContentType, + content + [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL } + +Here the underlying type is ANY DEFINED BY contentType, the +class is absent (i.e., context-specific), and the tag number +within the class is 0. + +Example 2: X.509's Certificate type has a version component +with an explicit, context-specific tag, where the EXPLICIT +keyword is omitted: + +Certificate ::= ... + version [0] Version DEFAULT v1988, +... + +The tag is explicit because the default tagging method for +the ASN.1 "module" in X.509 that defines the Certificate +type is explicit tagging. + +BER encoding. Constructed. Contents octets are the BER +encoding of the underlying value. + +Example: the BER encoding of the content component of a +ContentInfo value is as follows: + + o identifier octets are a0 + + o length octets represent the length of the BER + encoding of the underlying ANY DEFINED BY + contentType value + + o contents octets are the BER encoding of the + underlying ANY DEFINED BY contentType value + +DER encoding. Constructed. Contents octets are the DER +encoding of the underlying value. + + +5.3 ANY + +The ANY type denotes an arbitrary value of an arbitrary +type, where the arbitrary type is possibly defined in the +registration of an object identifier or associated with an +integer index. + +The ANY type is used for content of a particular content +type in PKCS #7's ContentInfo type, for parameters of a +particular algorithm in X.509's AlgorithmIdentifier type, +and for attribute values in X.501's Attribute and +AttributeValueAssertion types. The Attribute type is used by +PKCS #6, #7, #8, #9 and #10, and the AttributeValueAssertion +type is used in X.501 distinguished names. + +ASN.1 notation: + +ANY [DEFINED BY identifier] + +where identifier is an optional identifier. + +In the ANY form, the actual type is indeterminate. + +The ANY DEFINED BY identifier form can only appear in a +component of a SEQUENCE or SET type for which identifier +identifies some other component, and that other component +has type INTEGER or OBJECT IDENTIFIER (or a type derived +from either of those by tagging). In that form, the actual +type is determined by the value of the other component, +either in the registration of the object identifier value, +or in a table of integer values. + +Example: X.509's AlgorithmIdentifier type has a component of +type ANY: + +AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL } + +Here the actual type of the parameter component depends on +the value of the algorithm component. The actual type would +be defined in the registration of object identifier values +for the algorithm component. + +BER encoding. Same as the BER encoding of the actual value. + +Example: The BER encoding of the value of the parameter +component is the BER encoding of the value of the actual +type as defined in the registration of object identifier +values for the algorithm component. + +DER encoding. Same as the DER encoding of the actual value. + + +5.4 BIT STRING + +The BIT STRING type denotes an arbitrary string of bits +(ones and zeroes). A BIT STRING value can have any length, +including zero. This type is a string type. + +The BIT STRING type is used for digital signatures on +extended certificates in PKCS #6's ExtendedCertificate type, +for digital signatures on certificates in X.509's +Certificate type, and for public keys in certificates in +X.509's SubjectPublicKeyInfo type. + +ASN.1 notation: + +BIT STRING + +Example: X.509's SubjectPublicKeyInfo type has a component +of type BIT STRING: + +SubjectPublicKeyInfo ::= SEQUENCE { + algorithm AlgorithmIdentifier, + publicKey BIT STRING } + +BER encoding. Primitive or constructed. In a primitive +encoding, the first contents octet gives the number of bits +by which the length of the bit string is less than the next +multiple of eight (this is called the "number of unused +bits"). The second and following contents octets give the +value of the bit string, converted to an octet string. The +conversion process is as follows: + + 1. The bit string is padded after the last bit with + zero to seven bits of any value to make the length + of the bit string a multiple of eight. If the + length of the bit string is a multiple of eight + already, no padding is done. + + 2. The padded bit string is divided into octets. The + first eight bits of the padded bit string become + the first octet, bit 8 to bit 1, and so on through + the last eight bits of the padded bit string. + +In a constructed encoding, the contents octets give the +concatenation of the BER encodings of consecutive substrings +of the bit string, where each substring except the last has +a length that is a multiple of eight bits. + +Example: The BER encoding of the BIT STRING value +"011011100101110111" can be any of the following, among +others, depending on the choice of padding bits, the form of +length octets, and whether the encoding is primitive or +constructed: + +03 04 06 6e 5d c0 DER encoding + +03 04 06 6e 5d e0 padded with "100000" + +03 81 04 06 6e 5d c0 long form of length octets + +23 09 constructed encoding: "0110111001011101" + "11" + 03 03 00 6e 5d + 03 02 06 c0 + +DER encoding. Primitive. The contents octects are as for a +primitive BER encoding, except that the bit string is padded +with zero-valued bits. + +Example: The DER encoding of the BIT STRING value +"011011100101110111" is + +03 04 06 6e 5d c0 + + +5.5 CHOICE + +The CHOICE type denotes a union of one or more alternatives. + +The CHOICE type is used to represent the union of an +extended certificate and an X.509 certificate in PKCS #7's +ExtendedCertificateOrCertificate type. + +ASN.1 notation: + +CHOICE { + [identifier1] Type1, + ..., + [identifiern] Typen } + +where identifier1 , ..., identifiern are optional, distinct +identifiers for the alternatives, and Type1, ..., Typen are +the types of the alternatives. The identifiers are primarily +for documentation; they do not affect values of the type or +their encodings in any way. + +The types must have distinct tags. This requirement is +typically satisfied with explicit or implicit tagging on +some of the alternatives. + +Example: PKCS #7's ExtendedCertificateOrCertificate type is +a CHOICE type: + +ExtendedCertificateOrCertificate ::= CHOICE { + certificate Certificate, -- X.509 + extendedCertificate [0] IMPLICIT ExtendedCertificate +} + +Here the identifiers for the alternatives are certificate +and extendedCertificate, and the types of the alternatives +are Certificate and [0] IMPLICIT ExtendedCertificate. + +BER encoding. Same as the BER encoding of the chosen +alternative. The fact that the alternatives have distinct +tags makes it possible to distinguish between their BER +encodings. + +Example: The identifier octets for the BER encoding are 30 +if the chosen alternative is certificate, and a0 if the +chosen alternative is extendedCertificate. + +DER encoding. Same as the DER encoding of the chosen +alternative. + + +5.6 IA5String + +The IA5String type denotes an arbtrary string of IA5 +characters. IA5 stands for International Alphabet 5, which +is the same as ASCII. The character set includes non- +printing control characters. An IA5String value can have any +length, including zero. This type is a string type. + +The IA5String type is used in PKCS #9's electronic-mail +address, unstructured-name, and unstructured-address +attributes. + +ASN.1 notation: + +IA5String + +BER encoding. Primitive or constructed. In a primitive +encoding, the contents octets give the characters in the IA5 +string, encoded in ASCII. In a constructed encoding, the +contents octets give the concatenation of the BER encodings +of consecutive substrings of the IA5 string. + +Example: The BER encoding of the IA5String value +"test1@rsa.com" can be any of the following, among others, +depending on the form of length octets and whether the +encoding is primitive or constructed: + +16 0d 74 65 73 74 31 40 72 73 61 2e 63 6f 6d DER encoding + +16 81 0d long form of length octets + 74 65 73 74 31 40 72 73 61 2e 63 6f 6d + +36 13 constructed encoding: "test1" + "@" + "rsa.com" + 16 05 74 65 73 74 31 + 16 01 40 + 16 07 72 73 61 2e 63 6f 6d + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + +Example: The DER encoding of the IA5String value +"test1@rsa.com" is + +16 0d 74 65 73 74 31 40 72 73 61 2e 63 6f 6d + + +5.7 INTEGER + +The INTEGER type denotes an arbitrary integer. INTEGER +values can be positive, negative, or zero, and can have any +magnitude. + +The INTEGER type is used for version numbers throughout +PKCS, cryptographic values such as modulus, exponent, and +primes in PKCS #1's RSAPublicKey and RSAPrivateKey types and +PKCS #3's DHParameter type, a message-digest iteration count +in PKCS #5's PBEParameter type, and version numbers and +serial numbers in X.509's Certificate type. + +ASN.1 notation: + +INTEGER [{ identifier1(value1) ... identifiern(valuen) }] + +where identifier1, ..., identifiern are optional distinct +identifiers and value1, ..., valuen are optional integer +values. The identifiers, when present, are associated with +values of the type. + +Example: X.509's Version type is an INTEGER type with +identified values: + +Version ::= INTEGER { v1988(0) } + +The identifier v1988 is associated with the value 0. X.509's +Certificate type uses the identifier v1988 to give a default +value of 0 for the version component: + +Certificate ::= ... + version Version DEFAULT v1988, +... + +BER encoding. Primitive. Contents octets give the value of +the integer, base 256, in two's complement form, most +significant digit first, with the minimum number of octets. +The value 0 is encoded as a single 00 octet. + +Some example BER encodings (which also happen to be DER +encodings) are given in Table 3. + + Integer BER encoding + value + 0 02 01 00 + 127 02 01 7F + 128 02 02 00 80 + 256 02 02 01 00 + -128 02 01 80 + -129 02 02 FF 7F + + Table 3. Example BER encodings of INTEGER values. + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + + +5.8 NULL + +The NULL type denotes a null value. + +The NULL type is used for algorithm parameters in several +places in PKCS. + +ASN.1 notation: + +NULL + +BER encoding. Primitive. Contents octets are empty. + +Example: The BER encoding of a NULL value can be either of +the following, as well as others, depending on the form of +the length octets: + +05 00 + +05 81 00 + +DER encoding. Primitive. Contents octets are empty; the DER +encoding of a NULL value is always 05 00. + + +5.9 OBJECT IDENTIFIER + +The OBJECT IDENTIFIER type denotes an object identifier, a +sequence of integer components that identifies an object +such as an algorithm, an attribute type, or perhaps a +registration authority that defines other object +identifiers. An OBJECT IDENTIFIER value can have any number +of components, and components can generally have any +nonnegative value. This type is a non-string type. + +OBJECT IDENTIFIER values are given meanings by registration +authorities. Each registration authority is responsible for +all sequences of components beginning with a given sequence. +A registration authority typically delegates responsibility +for subsets of the sequences in its domain to other +registration authorities, or for particular types of object. +There are always at least two components. + +The OBJECT IDENTIFIER type is used to identify content in +PKCS #7's ContentInfo type, to identify algorithms in +X.509's AlgorithmIdentifier type, and to identify attributes +in X.501's Attribute and AttributeValueAssertion types. The +Attribute type is used by PKCS #6, #7, #8, #9, and #10, and +the AttributeValueAssertion type is used in X.501 +distinguished names. OBJECT IDENTIFIER values are defined +throughout PKCS. + +ASN.1 notation: + +OBJECT IDENTIFIER + +The ASN.1 notation for values of the OBJECT IDENTIFIER type +is + +{ [identifier] component1 ... componentn } + +componenti = identifieri | identifieri (valuei) | valuei + +where identifier, identifier1, ..., identifiern are +identifiers, and value1, ..., valuen are optional integer +values. + +The form without identifier is the "complete" value with all +its components; the form with identifier abbreviates the +beginning components with another object identifier value. +The identifiers identifier1, ..., identifiern are intended +primarily for documentation, but they must correspond to the +integer value when both are present. These identifiers can +appear without integer values only if they are among a small +set of identifiers defined in X.208. + +Example: The following values both refer to the object +identifier assigned to RSA Data Security, Inc.: + +{ iso(1) member-body(2) 840 113549 } +{ 1 2 840 113549 } + +(In this example, which gives ASN.1 value notation, the +object identifier values are decimal, not hexadecimal.) +Table 4 gives some other object identifier values and their +meanings. + + Object identifier value Meaning + { 1 2 } ISO member bodies + { 1 2 840 } US (ANSI) + { 1 2 840 113549 } RSA Data Security, Inc. + { 1 2 840 113549 1 } RSA Data Security, Inc. PKCS + { 2 5 } directory services (X.500) + { 2 5 8 } directory services-algorithms + + Table 4. Some object identifier values and their meanings. + +BER encoding. Primitive. Contents octets are as follows, +where value1, ..., valuen denote the integer values of the +components in the complete object identifier: + + 1. The first octet has value 40 * value1 + value2. + (This is unambiguous, since value1 is limited to + values 0, 1, and 2; value2 is limited to the range + 0 to 39 when value1 is 0 or 1; and, according to + X.208, n is always at least 2.) + + 2. The following octets, if any, encode value3, ..., + valuen. Each value is encoded base 128, most + significant digit first, with as few digits as + possible, and the most significant bit of each + octet except the last in the value's encoding set + to "1." + +Example: The first octet of the BER encoding of RSA Data +Security, Inc.'s object identifier is 40 * 1 + 2 = 42 = +2a16. The encoding of 840 = 6 * 128 + 4816 is 86 48 and the +encoding of 113549 = 6 * 1282 + 7716 * 128 + d16 is 86 f7 +0d. This leads to the following BER encoding: + +06 06 2a 86 48 86 f7 0d + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + + +5.10 OCTET STRING + +The OCTET STRING type denotes an arbitrary string of octets +(eight-bit values). An OCTET STRING value can have any +length, including zero. This type is a string type. + +The OCTET STRING type is used for salt values in PKCS #5's +PBEParameter type, for message digests, encrypted message +digests, and encrypted content in PKCS #7, and for private +keys and encrypted private keys in PKCS #8. + +ASN.1 notation: + +OCTET STRING [SIZE ({size | size1..size2})] + +where size, size1, and size2 are optional size constraints. +In the OCTET STRING SIZE (size) form, the octet string must +have size octets. In the OCTET STRING SIZE (size1..size2) +form, the octet string must have between size1 and size2 +octets. In the OCTET STRING form, the octet string can have +any size. + +Example: PKCS #5's PBEParameter type has a component of type +OCTET STRING: + +PBEParameter ::= SEQUENCE { + salt OCTET STRING SIZE(8), + iterationCount INTEGER } + +Here the size of the salt component is always eight octets. + +BER encoding. Primitive or constructed. In a primitive +encoding, the contents octets give the value of the octet +string, first octet to last octet. In a constructed +encoding, the contents octets give the concatenation of the +BER encodings of substrings of the OCTET STRING value. + +Example: The BER encoding of the OCTET STRING value 01 23 45 +67 89 ab cd ef can be any of the following, among others, +depending on the form of length octets and whether the +encoding is primitive or constructed: + +04 08 01 23 45 67 89 ab cd ef DER encoding + +04 81 08 01 23 45 67 89 ab cd ef long form of length octets + +24 0c constructed encoding: 01 ... 67 + 89 ... ef + 04 04 01 23 45 67 + 04 04 89 ab cd ef + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + +Example: The BER encoding of the OCTET STRING value 01 23 45 +67 89 ab cd ef is + +04 08 01 23 45 67 89 ab cd ef + + +5.11 PrintableString + +The PrintableString type denotes an arbitrary string of +printable characters from the following character set: + + A, B, ..., Z + a, b, ..., z + 0, 1, ..., 9 + (space) ' ( ) + , - . / : = ? + +This type is a string type. + +The PrintableString type is used in PKCS #9's challenge- +password and unstructuerd-address attributes, and in several +X.521 distinguished names attributes. + +ASN.1 notation: + +PrintableString + +BER encoding. Primitive or constructed. In a primitive +encoding, the contents octets give the characters in the +printable string, encoded in ASCII. In a constructed +encoding, the contents octets give the concatenation of the +BER encodings of consecutive substrings of the string. + +Example: The BER encoding of the PrintableString value "Test +User 1" can be any of the following, among others, depending +on the form of length octets and whether the encoding is +primitive or constructed: + +13 0b 54 65 73 74 20 55 73 65 72 20 31 DER encoding + +13 81 0b long form of length octets + 54 65 73 74 20 55 73 65 72 20 31 + +33 0f constructed encoding: "Test " + "User 1" + 13 05 54 65 73 74 20 + 13 06 55 73 65 72 20 31 + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + +Example: The DER encoding of the PrintableString value "Test +User 1" is + +13 0b 54 65 73 74 20 55 73 65 72 20 31 + + +5.12 SEQUENCE + +The SEQUENCE type denotes an ordered collection of one or +more types. + +The SEQUENCE type is used throughout PKCS and related +standards. + +ASN.1 notation: + +SEQUENCE { + [identifier1] Type1 [{OPTIONAL | DEFAULT value1}], + ..., + [identifiern] Typen [{OPTIONAL | DEFAULT valuen}]} + +where identifier1 , ..., identifiern are optional, distinct +identifiers for the components, Type1, ..., Typen are the +types of the components, and value1, ..., valuen are optional +default values for the components. The identifiers are +primarily for documentation; they do not affect values of +the type or their encodings in any way. + +The OPTIONAL qualifier indicates that the value of a +component is optional and need not be present in the +sequence. The DEFAULT qualifier also indicates that the +value of a component is optional, and assigns a default +value to the component when the component is absent. + +The types of any consecutive series of components with the +OPTIONAL or DEFAULT qualifier, as well as of any component +immediately following that series, must have distinct tags. +This requirement is typically satisfied with explicit or +implicit tagging on some of the components. + +Example: X.509's Validity type is a SEQUENCE type with two +components: + +Validity ::= SEQUENCE { + start UTCTime, + end UTCTime } + +Here the identifiers for the components are start and end, +and the types of the components are both UTCTime. + +BER encoding. Constructed. Contents octets are the +concatenation of the BER encodings of the values of the +components of the sequence, in order of definition, with the +following rules for components with the OPTIONAL and DEFAULT +qualifiers: + + o if the value of a component with the OPTIONAL or + DEFAULT qualifier is absent from the sequence, + then the encoding of that component is not + included in the contents octets + + o if the value of a component with the DEFAULT + qualifier is the default value, then the encoding + of that component may or may not be included in + the contents octets + +DER encoding. Constructed. Contents octets are the same as +the BER encoding, except that if the value of a component +with the DEFAULT qualifier is the default value, the +encoding of that component is not included in the contents +octets. + + +5.13 SEQUENCE OF + +The SEQUENCE OF type denotes an ordered collection of zero +or more occurrences of a given type. + +The SEQUENCE OF type is used in X.501 distinguished names. + +ASN.1 notation: + +SEQUENCE OF Type + +where Type is a type. + +Example: X.501's RDNSequence type consists of zero or more +occurences of the RelativeDistinguishedName type, most +significant occurrence first: + +RDNSequence ::= SEQUENCE OF RelativeDistinguishedName + +BER encoding. Constructed. Contents octets are the +concatenation of the BER encodings of the values of the +occurrences in the collection, in order of occurence. + +DER encoding. Constructed. Contents octets are the +concatenation of the DER encodings of the values of the +occurrences in the collection, in order of occurence. + + +5.14 SET + +The SET type denotes an unordered collection of one or more +types. + +The SET type is not used in PKCS. + +ASN.1 notation: + +SET { + [identifier1] Type1 [{OPTIONAL | DEFAULT value1}], + ..., + [identifiern] Typen [{OPTIONAL | DEFAULT valuen}]} + +where identifier1, ..., identifiern are optional, distinct +identifiers for the components, Type1, ..., Typen are the +types of the components, and value1, ..., valuen are +optional default values for the components. The identifiers +are primarily for documentation; they do not affect values +of the type or their encodings in any way. + +The OPTIONAL qualifier indicates that the value of a +component is optional and need not be present in the set. +The DEFAULT qualifier also indicates that the value of a +component is optional, and assigns a default value to the +component when the component is absent. + +The types must have distinct tags. This requirement is +typically satisfied with explicit or implicit tagging on +some of the components. + +BER encoding. Constructed. Contents octets are the +concatenation of the BER encodings of the values of the +components of the set, in any order, with the following +rules for components with the OPTIONAL and DEFAULT +qualifiers: + + o if the value of a component with the OPTIONAL or + DEFAULT qualifier is absent from the set, then the + encoding of that component is not included in the + contents octets + + o if the value of a component with the DEFAULT + qualifier is the default value, then the encoding + of that component may or may not be included in + the contents octets + +DER encoding. Constructed. Contents octets are the same as +for the BER encoding, except that: + + 1. If the value of a component with the DEFAULT + qualifier is the default value, the encoding of + that component is not included. + + 2. There is an order to the components, namely + ascending order by tag. + + +5.15 SET OF + +The SET OF type denotes an unordered collection of zero or +more occurrences of a given type. + +The SET OF type is used for sets of attributes in PKCS #6, +#7, #8, #9 and #10, for sets of message-digest algorithm +identifiers, signer information, and recipient information +in PKCS #7, and in X.501 distinguished names. + +ASN.1 notation: + +SET OF Type + +where Type is a type. + +Example: X.501's RelativeDistinguishedName type consists of +zero or more occurrences of the AttributeValueAssertion +type, where the order is unimportant: + +RelativeDistinguishedName ::= + SET OF AttributeValueAssertion + +BER encoding. Constructed. Contents octets are the +concatenation of the BER encodings of the values of the +occurrences in the collection, in any order. + +DER encoding. Constructed. Contents octets are the same as +for the BER encoding, except that there is an order, namely +ascending lexicographic order of BER encoding. Lexicographic +comparison of two different BER encodings is done as +follows: Logically pad the shorter BER encoding after the +last octet with dummy octets that are smaller in value than +any normal octet. Scan the BER encodings from left to right +until a difference is found. The smaller-valued BER encoding +is the one with the smaller-valued octet at the point of +difference. + + +5.16 T61String + +The T61String type denotes an arbtrary string of T.61 +characters. T.61 is an eight-bit extension to the ASCII +character set. Special "escape" sequences specify the +interpretation of subsequent character values as, for +example, Japanese; the initial interpretation is Latin. The +character set includes non-printing control characters. The +T61String type allows only the Latin and Japanese character +interepretations, and implementors' agreements for directory +names exclude control characters [NIST92]. A T61String value +can have any length, including zero. This type is a string +type. + +The T61String type is used in PKCS #9's unstructured-address +and challenge-password attributes, and in several X.521 +attributes. + +ASN.1 notation: + +T61String + +BER encoding. Primitive or constructed. In a primitive +encoding, the contents octets give the characters in the +T.61 string, encoded in ASCII. In a constructed encoding, +the contents octets give the concatenation of the BER +encodings of consecutive substrings of the T.61 string. + +Example: The BER encoding of the T61String value "cl'es +publiques" (French for "public keys") can be any of the +following, among others, depending on the form of length +octets and whether the encoding is primitive or constructed: + +14 0f DER encoding + 63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73 + +14 81 0f long form of length octets + 63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73 + +34 15 constructed encoding: "cl'es" + " " + "publiques" + 14 05 63 6c c2 65 73 + 14 01 20 + 14 09 70 75 62 6c 69 71 75 65 73 + +The eight-bit character c2 is a T.61 prefix that adds an +acute accent (') to the next character. + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + +Example: The DER encoding of the T61String value "cl'es +publiques" is + +14 0f 63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73 + + +5.17 UTCTime + +The UTCTime type denotes a "coordinated universal time" or +Greenwich Mean Time (GMT) value. A UTCTime value includes +the local time precise to either minutes or seconds, and an +offset from GMT in hours and minutes. It takes any of the +following forms: + +YYMMDDhhmmZ +YYMMDDhhmm+hh'mm' +YYMMDDhhmm-hh'mm' +YYMMDDhhmmssZ +YYMMDDhhmmss+hh'mm' +YYMMDDhhmmss-hh'mm' + +where: + + YY is the least significant two digits of the year + + MM is the month (01 to 12) + + DD is the day (01 to 31) + + hh is the hour (00 to 23) + + mm are the minutes (00 to 59) + + ss are the seconds (00 to 59) + + Z indicates that local time is GMT, + indicates that + local time is later than GMT, and - indicates that + local time is earlier than GMT + + hh' is the absolute value of the offset from GMT in + hours + + mm' is the absolute value of the offset from GMT in + minutes + +This type is a string type. + +The UTCTime type is used for signing times in PKCS #9's +signing-time attribute and for certificate validity periods +in X.509's Validity type. + +ASN.1 notation: + +UTCTime + +BER encoding. Primitive or constructed. In a primitive +encoding, the contents octets give the characters in the +string, encoded in ASCII. In a constructed encoding, the +contents octets give the concatenation of the BER encodings +of consecutive substrings of the string. (The constructed +encoding is not particularly interesting, since UTCTime +values are so short, but the constructed encoding is +permitted.) + +Example: The time this sentence was originally written was +4:45:40 p.m. Pacific Daylight Time on May 6, 1991, which can +be represented with either of the following UTCTime values, +among others: + +"910506164540-0700" + +"910506234540Z" + +These values have the following BER encodings, among others: + +17 0d 39 31 30 35 30 36 32 33 34 35 34 30 5a + +17 11 39 31 30 35 30 36 31 36 34 35 34 30 2D 30 37 30 + 30 + +DER encoding. Primitive. Contents octets are as for a +primitive BER encoding. + + +6. An example + +This section gives an example of ASN.1 notation and DER +encoding: the X.501 type Name. + + +6.1 Abstract notation + +This section gives the ASN.1 notation for the X.501 type +Name. + +Name ::= CHOICE { + RDNSequence } + +RDNSequence ::= SEQUENCE OF RelativeDistinguishedName + +RelativeDistinguishedName ::= + SET OF AttributeValueAssertion + +AttributeValueAssertion ::= SEQUENCE { + AttributeType, + AttributeValue } + +AttributeType ::= OBJECT IDENTIFIER + +AttributeValue ::= ANY + +The Name type identifies an object in an X.500 directory. +Name is a CHOICE type consisting of one alternative: +RDNSequence. (Future revisions of X.500 may have other +alternatives.) + +The RDNSequence type gives a path through an X.500 directory +tree starting at the root. RDNSequence is a SEQUENCE OF type +consisting of zero or more occurences of +RelativeDistinguishedName. + +The RelativeDistinguishedName type gives a unique name to an +object relative to the object superior to it in the +directory tree. RelativeDistinguishedName is a SET OF type +consisting of zero or more occurrences of +AttributeValueAssertion. + +The AttributeValueAssertion type assigns a value to some +attribute of a relative distinguished name, such as country +name or common name. AttributeValueAssertion is a SEQUENCE +type consisting of two components, an AttributeType type and +an AttributeValue type. + +The AttributeType type identifies an attribute by object +identifier. The AttributeValue type gives an arbitrary +attribute value. The actual type of the attribute value is +determined by the attribute type. + + +6.2 DER encoding + +This section gives an example of a DER encoding of a value +of type Name, working from the bottom up. + +The name is that of the Test User 1 from the PKCS examples +[Kal93]. The name is represented by the following path: + + (root) + | + countryName = "US" + | + organizationName = "Example Organization" + | + commonName = "Test User 1" + +Each level corresponds to one RelativeDistinguishedName +value, each of which happens for this name to consist of one +AttributeValueAssertion value. The AttributeType value is +before the equals sign, and the AttributeValue value (a +printable string for the given attribute types) is after the +equals sign. + +The countryName, organizationName, and commonUnitName are +attribute types defined in X.520 as: + +attributeType OBJECT IDENTIFIER ::= + { joint-iso-ccitt(2) ds(5) 4 } + +countryName OBJECT IDENTIFIER ::= { attributeType 6 } +organizationName OBJECT IDENTIFIER ::= + { attributeType 10 } +commonUnitName OBJECT IDENTIFIER ::= + { attributeType 3 } + + +6.2.1 AttributeType + +The three AttributeType values are OCTET STRING values, so +their DER encoding follows the primitive, definite-length +method: + +06 03 55 04 06 countryName + +06 03 55 04 0a organizationName + +06 03 55 04 03 commonName + +The identifier octets follow the low-tag form, since the tag +is 6 for OBJECT IDENTIFIER. Bits 8 and 7 have value "0," +indicating universal class, and bit 6 has value "0," +indicating that the encoding is primitive. The length octets +follow the short form. The contents octets are the +concatenation of three octet strings derived from +subidentifiers (in decimal): 40 * 2 + 5 = 85 = 5516; 4; and +6, 10, or 3. + + +6.2.2 AttributeValue + +The three AttributeValue values are PrintableString values, +so their encodings follow the primitive, definite-length +method: + +13 02 55 53 "US" + +13 14 "Example Organization" + 45 78 61 6d 70 6c 65 20 4f 72 67 61 6e 69 7a 61 + 74 69 6f 6e + +13 0b "Test User 1" + 54 65 73 74 20 55 73 65 72 20 31 + +The identifier octets follow the low-tag-number form, since +the tag for PrintableString, 19 (decimal), is between 0 and +30. Bits 8 and 7 have value "0" since PrintableString is in +the universal class. Bit 6 has value "0" since the encoding +is primitive. The length octets follow the short form, and +the contents octets are the ASCII representation of the +attribute value. + + +6.2.3 AttributeValueAssertion + +The three AttributeValueAssertion values are SEQUENCE +values, so their DER encodings follow the constructed, +definite-length method: + +30 09 countryName = "US" + 06 03 55 04 06 + 13 02 55 53 + +30 1b organizationName = "Example Organizaiton" + 06 03 55 04 0a + 13 14 ... 6f 6e + +30 12 commonName = "Test User 1" + 06 03 55 04 0b + 13 0b ... 20 31 + +The identifier octets follow the low-tag-number form, since +the tag for SEQUENCE, 16 (decimal), is between 0 and 30. +Bits 8 and 7 have value "0" since SEQUENCE is in the +universal class. Bit 6 has value "1" since the encoding is +constructed. The length octets follow the short form, and +the contents octets are the concatenation of the DER +encodings of the attributeType and attributeValue +components. + + +6.2.4 RelativeDistinguishedName + +The three RelativeDistinguishedName values are SET OF +values, so their DER encodings follow the constructed, +definite-length method: + +31 0b + 30 09 ... 55 53 + +31 1d + 30 1b ... 6f 6e + +31 14 + 30 12 ... 20 31 + +The identifier octets follow the low-tag-number form, since +the tag for SET OF, 17 (decimal), is between 0 and 30. Bits +8 and 7 have value "0" since SET OF is in the universal +class Bit 6 has value "1" since the encoding is constructed. +The lengths octets follow the short form, and the contents +octets are the DER encodings of the respective +AttributeValueAssertion values, since there is only one +value in each set. + + +6.2.5 RDNSequence + +The RDNSequence value is a SEQUENCE OF value, so its DER +encoding follows the constructed, definite-length method: + +30 42 + 31 0b ... 55 53 + 31 1d ... 6f 6e + 31 14 ... 20 31 + +The identifier octets follow the low-tag-number form, since +the tag for SEQUENCE OF, 16 (decimal), is between 0 and 30. +Bits 8 and 7 have value "0" since SEQUENCE OF is in the +universal class. Bit 6 has value "1" since the encoding is +constructed. The lengths octets follow the short form, and +the contents octets are the concatenation of the DER +encodings of the three RelativeDistinguishedName values, in +order of occurrence. + + +6.2.6 Name + +The Name value is a CHOICE value, so its DER encoding is the +same as that of the RDNSequence value: + +30 42 + 31 0b + 30 09 + 06 03 55 04 06 attributeType = countryName + 13 02 55 53 attributeValue = "US" + 31 1d + 30 1b + 06 03 55 04 0a attributeType = organizationName + 13 14 attributeValue = "Example Organization" + 45 78 61 6d 70 6c 65 20 4f 72 67 61 6e 69 7a 61 + 74 69 6f 6e + + 31 14 + 30 12 + 06 03 55 04 03 attributeType = commonName + 13 0b attributeValue = "Test User 1" + 54 65 73 74 20 55 73 65 72 20 31 + + +References + +PKCS #1 RSA Laboratories. PKCS #1: RSA Encryption + Standard. Version 1.5, November 1993. + +PKCS #3 RSA Laboratories. PKCS #3: Diffie-Hellman Key- + Agreement Standard. Version 1.4, November 1993. + +PKCS #5 RSA Laboratories. PKCS #5: Password-Based + Encryption Standard. Version 1.5, November 1993. + +PKCS #6 RSA Laboratories. PKCS #6: Extended-Certificate + Syntax Standard. Version 1.5, November 1993. + +PKCS #7 RSA Laboratories. PKCS #7: Cryptographic Message + Syntax Standard. Version 1.5, November 1993. + +PKCS #8 RSA Laboratories. PKCS #8: Private-Key Information + Syntax Standard. Version 1.2, November 1993. + +PKCS #9 RSA Laboratories. PKCS #9: Selected Attribute + Types. Version 1.1, November 1993. + +PKCS #10 RSA Laboratories. PKCS #10: Certification Request + Syntax Standard. Version 1.0, November 1993. + +X.200 CCITT. Recommendation X.200: Reference Model of + Open Systems Interconnection for CCITT + Applications. 1984. + +X.208 CCITT. Recommendation X.208: Specification of + Abstract Syntax Notation One (ASN.1). 1988. + +X.209 CCITT. Recommendation X.209: Specification of + Basic Encoding Rules for Abstract Syntax Notation + One (ASN.1). 1988. + +X.500 CCITT. Recommendation X.500: The + Directory--Overview of Concepts, Models and + Services. 1988. + +X.501 CCITT. Recommendation X.501: The Directory-- + Models. 1988. + +X.509 CCITT. Recommendation X.509: The Directory-- + Authentication Framework. 1988. + +X.520 CCITT. Recommendation X.520: The Directory-- + Selected Attribute Types. 1988. + +[Kal93] Burton S. Kaliski Jr. Some Examples of the PKCS + Standards. RSA Laboratories, November 1993. + +[NIST92] NIST. Special Publication 500-202: Stable + Implementation Agreements for Open Systems + Interconnection Protocols. Part 11 (Directory + Services Protocols). December 1992. + + +Revision history + + +June 3, 1991 version + +The June 3, 1991 version is part of the initial public +release of PKCS. It was published as NIST/OSI Implementors' +Workshop document SEC-SIG-91-17. + + +November 1, 1993 version + +The November 1, 1993 version incorporates several editorial +changes, including the addition of a revision history. It is +updated to be consistent with the following versions of the +PKCS documents: + + PKCS #1: RSA Encryption Standard. Version 1.5, November + 1993. + + PKCS #3: Diffie-Hellman Key-Agreement Standard. Version + 1.4, November 1993. + + PKCS #5: Password-Based Encryption Standard. Version + 1.5, November 1993. + + PKCS #6: Extended-Certificate Syntax Standard. Version + 1.5, November 1993. + + PKCS #7: Cryptographic Message Syntax Standard. Version + 1.5, November 1993. + + PKCS #8: Private-Key Information Syntax Standard. + Version 1.2, November 1993. + + PKCS #9: Selected Attribute Types. Version 1.1, + November 1993. + + PKCS #10: Certification Request Syntax Standard. + Version 1.0, November 1993. + +The following substantive changes were made: + + Section 5: Description of T61String type is added. + + Section 6: Names are changed, consistent with other + PKCS examples. + + +Author's address + +Burton S. Kaliski Jr., Ph.D. +Chief Scientist +RSA Laboratories (415) 595-7703 +100 Marine Parkway (415) 595-4126 (fax) +Redwood City, CA 94065 USA burt@rsa.com diff --git a/crypto/heimdal/doc/mdate-sh b/crypto/heimdal/doc/mdate-sh new file mode 100755 index 0000000..37171f2 --- /dev/null +++ b/crypto/heimdal/doc/mdate-sh @@ -0,0 +1,92 @@ +#!/bin/sh +# Get modification time of a file or directory and pretty-print it. +# Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc. +# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995 +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation, +# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# Prevent date giving response in another language. +LANG=C +export LANG +LC_ALL=C +export LC_ALL +LC_TIME=C +export LC_TIME + +# Get the extended ls output of the file or directory. +# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below. +if ls -L /dev/null 1>/dev/null 2>&1; then + set - x`ls -L -l -d $1` +else + set - x`ls -l -d $1` +fi +# The month is at least the fourth argument +# (3 shifts here, the next inside the loop). +shift +shift +shift + +# Find the month. Next argument is day, followed by the year or time. +month= +until test $month +do + shift + case $1 in + Jan) month=January; nummonth=1;; + Feb) month=February; nummonth=2;; + Mar) month=March; nummonth=3;; + Apr) month=April; nummonth=4;; + May) month=May; nummonth=5;; + Jun) month=June; nummonth=6;; + Jul) month=July; nummonth=7;; + Aug) month=August; nummonth=8;; + Sep) month=September; nummonth=9;; + Oct) month=October; nummonth=10;; + Nov) month=November; nummonth=11;; + Dec) month=December; nummonth=12;; + esac +done + +day=$2 + +# Here we have to deal with the problem that the ls output gives either +# the time of day or the year. +case $3 in + *:*) set `date`; eval year=\$$# + case $2 in + Jan) nummonthtod=1;; + Feb) nummonthtod=2;; + Mar) nummonthtod=3;; + Apr) nummonthtod=4;; + May) nummonthtod=5;; + Jun) nummonthtod=6;; + Jul) nummonthtod=7;; + Aug) nummonthtod=8;; + Sep) nummonthtod=9;; + Oct) nummonthtod=10;; + Nov) nummonthtod=11;; + Dec) nummonthtod=12;; + esac + # For the first six month of the year the time notation can also + # be used for files modified in the last year. + if (expr $nummonth \> $nummonthtod) > /dev/null; + then + year=`expr $year - 1` + fi;; + *) year=$3;; +esac + +# The result. +echo $day $month $year diff --git a/crypto/heimdal/doc/misc.texi b/crypto/heimdal/doc/misc.texi new file mode 100644 index 0000000..e926536 --- /dev/null +++ b/crypto/heimdal/doc/misc.texi @@ -0,0 +1,62 @@ +@node Things in search for a better place, Kerberos 4 issues, Setting up a realm, Top +@chapter Things in search for a better place + +@section Making things work on Ciscos + +Modern versions of Cisco IOS has some support for authenticating via +Kerberos 5. This can be used both to verify passwords via a ticket +exchange Kerberos 5 (boring), and to use Kerberos authenticated telnet +to access your router (less boring). The following has been tested on +IOS 11.2(12), things might be different with other versions. Old +versions are known to have bugs. + +To make this work, you will first have to configure your router to use +Kerberos (this is explained in the documentation). A sample +configuration looks like the following: + +@example +aaa new-model +aaa authentication login default krb5-telnet krb5 enable +aaa authorization exec krb5-instance +kerberos local-realm FOO.SE +kerberos srvtab entry host/router.foo.se 0 891725446 4 1 8 012345678901234567 +kerberos server FOO.SE 10.0.0.1 +kerberos instance map admin 15 +@end example + +This tells you (among other things) that the when logging in, the router +should try to authenticate with kerberized telnet, and if that fails try +to verify a plain text password via a Kerberos ticket exchange (as +opposed to a local database or RADIUS or something similar), and if that +fails try the local enable password. If you're not careful when you +specify the `login default' authentication mechanism, you might not be +able to login. The `instance map' and `authorization exec' lines says +that people with `admin' instances should be given `enabled' shells when +logging in. + +To make the Heimdal KDC produce tickets that the Cisco can decode you +might have to turn on the @samp{encode_as_rep_as_tgs_rep} flag in the +KDC. You will also have to specify that the router can't handle anything +but @samp{des-cbc-crc}. There currently isn't an easy way to do +this. The best you can do is to dump your database (with @samp{kadmin -l +dump}), remove all entries for keys other than @samp{des-cbc-crc}, and +then reloading the database (@samp{kadmin -l load}). An example should +clarify this. You should have something like (again, truncated): +@example +host/router.foo.se@@FOO.SE 4:0:1:...:-:... - - - - - - - 126 +@end example +Change this to: +@example +host/router.foo.se@@FOO.SE 4:0:1:...:- - - - - - - - 126 +@end example + +This all fine and so, but unless you have an IOS version with encryption +(available only in the U.S) it doesn't really solve any problems. Sure +you don't have to send your password over the wire, but since the telnet +connection isn't protected it's still possible for someone to steal your +session. This won't be fixed until someone adds integrity to the telnet +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. diff --git a/crypto/heimdal/doc/setup.texi b/crypto/heimdal/doc/setup.texi new file mode 100644 index 0000000..a43eb7e --- /dev/null +++ b/crypto/heimdal/doc/setup.texi @@ -0,0 +1,247 @@ +@node Setting up a realm, Things in search for a better place, Building and Installing, Top +@chapter Setting up a realm + +A +@cindex realm +realm is an administrative domain. The name of a Kerberos realm is +usually the Internet domain name in uppercase. Call your realm the same +as your Internet domain name if you do not have strong reasons for not +doing so. It will make life easier for you and everyone else. + +@section Configuration file + +To setup a realm you will first have to create a configuration file: +@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many +configuration options, some of which are described here. + +There is a sample @file{krb5.conf} supplied with the distribution. + +The configuration file is a hierarchical structure consisting of +sections, each containing a list of bindings (either variable +assignments or subsections). A section starts with +@samp{[section-name]}. A binding consists of a left hand side, an equal +(@samp{=}) and a right hand side (the left hand side tag must be +separated from the equal with some whitespace.) Subsections has a +@samp{@{} as the first non-whitespace character after the equal. All +other bindings are treated as variable assignments. The value of a +variable extends to the end of the line. + +@example +[section1] + a-subsection = @{ + var = value1 + other-var = value with @{@} + sub-sub-section = @{ + var = 123 + @} + @} + var = some other value +[section2] + var = yet another value +@end example + +In this manual, names of sections and bindings will be given as strings +separated by slashes (@samp{/}). The @samp{other-var} variable will thus +be @samp{section1/a-subsection/other-var}. + +For in-depth information about the contents of the config file, refer to +the @file{krb5.conf} manual page. Some of the more important sections +are briefly described here. + +The @samp{libdefaults} section contains a list of library configuration +parameters, such as the default realm and the timeout for kdc +responses. The @samp{realms} section contains information about specific +realms, such as where they hide their KDC. This section serves the same +purpose as the Kerberos 4 @file{krb.conf} file, but can contain more +information. Finally the @samp{domain_realm} section contains a list of +mappings from domains to realms, equivalent to the Kerberos 4 +@file{krb.realms} file. + +To continue with the realm setup, you will have to create a config file, +with contents similar to the following. + +@example +[libdefaults] + default_realm = MY.REALM +[realms] + MY.REALM = @{ + kdc = my.kdc + @} +[domain_realm] + .my.domain = MY.REALM + +@end example + +If you use a realm name equal to your domain name, you can omit the +@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a +SRV-record for your realm, or your kerberos server has CNAME called +@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. + +@section Creating the database + +The database library will look for the database in @file{/var/heimdal}, +so you should probably create that directory. + +The keys of all the principals are stored in the database. If you +choose to, these can be encrypted with a master key. You do not have to +remember this key (or password), but just to enter it once and it will +be stored in a file (@file{/var/heimdal/m-key}). If you want to have a +master key, run @samp{kstash} to create this master key: + +@example +# kstash +Master key: +Verifying password - Master key: +@end example + +To initialise the database use the @code{kadmin} program, with the +@samp{-l} option (to enable local database mode). First issue a +@kbd{init MY.REALM} command. This will create the database and insert +default principals for that realm. You can have more than one realm in +one database, so @samp{init} does not destroy any old database. + +Before creating the database, @samp{init} will ask you some questions +about max ticket lifetimes. + +After creating the database you should probably add yourself to it. You +do this with the @samp{add} command. It takes as argument the name of a +principal. The principal should contain a realm, so if you haven't setup +a default realm, you will need to explicitly include the realm. + +@example +# kadmin -l +kadmin> init MY.REALM +Realm max ticket life [unlimited]: +Realm max renewable ticket life [unlimited]: +kadmin> add me +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +Password: +Verifying password - Password: +@end example + +Now start the KDC and try getting a ticket. + +@example +# kdc & +# kinit me +me@@MY.REALMS's Password: +# klist +Credentials cache: /tmp/krb5cc_0 + Principal: me@@MY.REALM + + Issued Expires Principal +Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM +@end example + +If you are curious you can use the @samp{dump} command to list all the +entries in the database. It should look something similar to the +following example (note that the entries here are truncated for +typographical reasons): + +@smallexample +kadmin> dump +me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... +kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... +krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... +kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... +@end smallexample + +@section keytabs + +To extract a service ticket from the database and put it in a keytab you +need to first create the principal in the database with @samp{ank} +(using the @kbd{--random} flag to get a random password) and then +extract it with @samp{ext_keytab}. + +@example +kadmin> add --random host/my.host.name +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin> ext host/my.host.name +# ktutil list +Version Type Principal + 1 des-cbc-md5 host/my.host.name@@MY.REALM + 1 des-cbc-md4 host/my.host.name@@MY.REALM + 1 des-cbc-crc host/my.host.name@@MY.REALM + 1 des3-cbc-sha1 host/my.host.name@@MY.REALM +@end example + +@section Remote administration + +The administration server, @samp{kadmind}, is started by @samp{inetd} +and you should add a line similar to the one below to your +@file{/etc/inetd.conf}. + +@example +kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind +@end example + +You might need to add @samp{kerberos-adm} to your @file{/etc/services} +as 749/tcp. + +Access to the admin server is controlled by an acl-file, (default +@file{/var/heimdal/kadmind.acl}.) The lines in the access file, has the +following syntax: +@smallexample +principal [priv1,priv2,...] +@end smallexample + +The privileges you can assign to a principal are: @samp{add}, +@samp{change-password} (or @samp{cpw} for short), @samp{delete}, +@samp{get}, @samp{list}, and @samp{modify}, or the special privilege +@samp{all}. All of these roughly corresponds to the different commands +in @samp{kadmin}. + +@section Password changing + +To allow users to change their passwords, you should run @samp{kpasswdd}. +It is not run from @samp{inetd}. + +You might need to add @samp{kpasswd} to your @file{/etc/services} as +464/udp. + +@subsection Password quality assurance + +It is important that users have good passwords, both to make it harder +to guess them and to avoid off-line attacks (pre-authentication provides +some defense against off-line attacks). To ensure that the users choose +good passwords, you can enable password quality controls in +@samp{kpasswdd}. The controls themselves are done in a shared library +that is used by @samp{kpasswdd}. To configure in these controls, add +lines similar to the following to your @file{/etc/krb5.conf}: + +@example +[password_quality] + check_library = @var{library} + check_function = @var{function} +@end example + +The function @var{function} in the shared library @var{library} will be +called for proposed new passwords. The function should be declared as: + +@example +const char * +function(krb5_context context, krb5_principal principal, krb5_data *pwd); +@end example + +The function should verify that @var{pwd} is a good password for +@var{principal} and if so return @code{NULL}. If it is deemed to be of +low quality, it should return a string explaining why that password +should not be used. + +Code for a password quality checking function that uses the cracklib +library can be found in @file{kpasswd/sample_password_check.c} in the +source code distribution. It requires the cracklib library built with +the patch available at +@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. + +If no password quality checking function is configured, it is only +verified that it is at least six characters of length. + +@section Testing clients and servers + +Now you should be able to run all the clients and servers. Refer to the +appropriate man pages for information on how to use them. diff --git a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt b/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt new file mode 100644 index 0000000..a97ef9d --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt @@ -0,0 +1,412 @@ +CAT working group M. Swift +Internet Draft J. Brezak +Document: draft-brezak-win2k-krb-rc4-hmac-01.txt Microsoft +Category: Informational October 1999 + + + The Windows 2000 RC4-HMAC Kerberos encryption type + + +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 Windows 2000 implementation of Kerberos introduces a new + encryption type based on the RC4 encryption algorithm and using an + MD5 HMAC for checksum. This is offered as an alternative to using + the existing DES based encryption types. + + The RC4-HMAC encryption types are used to ease upgrade of existing + Windows NT environments, provide strong crypto (128-bit key + lengths), and provide exportable (meet United States government + export restriction requirements) encryption. + + The Windows 2000 implementation of Kerberos contains new encryption + and checksum types for two reasons: for export reasons early in the + development process, 56 bit DES encryption could not be exported, + and because upon upgrade from Windows NT 4.0 to Windows 2000, + accounts will not have the appropriate DES keying material to do the + standard DES encryption. Furthermore, 3DES is not available for + export, and there was a desire to use a single flavor of encryption + in the product for both US and international products. + + As a result, there are two new encryption types and one new checksum + type introduced in Windows 2000. + + +2. Conventions used in this document + + + +Swift Category - Informational 1 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + 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. Key Generation + + On upgrade from existing Windows NT domains, the user accounts would + not have a DES based key available to enable the use of DES base + encryption types specified in RFC 1510. The key used for RC4-HMAC is + the same as the existing Windows NT key (NT Password Hash) for + compatibility reasons. Once the account password is changed, the DES + based keys are created and maintained. Once the DES keys are + available DES based encryption types can be used with Kerberos. + + The RC4-HMAC String to key function is defined as follow: + + String2Key(password) + + K = MD4(UNICODE(password)) + + The RC4-HMAC keys are generated by using the Windows UNICODE version + of the password. Each Windows UNICODE character is encoded in + little-endian format of 2 octets each. Then performing an MD4 [6] + hash operation on just the UNICODE characters of the password (not + including the terminating zero octets). + +4. Basic Operations + + The MD5 HMAC function is defined in [3]. It is used in this + encryption type for checksum operations. Refer to [3] for details on + its operation. In this document this function is referred to as + HMAC(Key, Data) returning the checksum using the specified key on + the data. + + The basic MD5 hash operation is used in this encryption type and + defined in [7]. In this document this function is referred to as + MD5(Data) returning the checksum of the data. + + The basic RC4 encryption operation is used in this encryption type + and defined in [8]. In this document the function is referred to as + RC4(Key, Data) returning the encrypted data using the specified key + on the data. + + These encryption types use key derivation as defined in [9] (RFC- + 1510BIS) in Section titled "Key Derivation". With each message, the + message type (T) is used as a component of the keying material. + + All strings in this document are ASCII unless otherwise specified. + The lengths of ASCII encoded character strings include the trailing + terminator character (0). + + The concat(a,b,c,...) function will return the logical concatenation + (left to right) of the values of the arguments. + +Swift Category - Informational 2 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + + The nonce(n) function returns a pseudo-random number of "n" octets. + +5. Checksum Types + + There is one checksum type used in this encryption type. The + Kerberos constant for this type is: + #define KERB_CHECKSUM_HMAC_MD5 (-138) + + The function is defined as follows: + + K - is the Key + T - the message type, encoded as a little-endian four byte integer + + CHKSUM(K, T, data) + + Ksign = HMAC(K, "signature key") //includes zero octet at end + tmp = MD5(concat(T, data)) + CHKSUM = HMAC(Ksign, tmp) + + +6. Encryption Types + + There are two encryption types used in these encryption types. The + Kerberos constants for these types are: + #define KERB_ETYPE_RC4_HMAC 23 + #define KERB_ETYPE_RC4_HMAC_EXP 24 + + The basic encryption function is defined as follow: + + T = the message type, encoded as a little-endian four byte integer. + + ENCRYPT(K, T, data) + if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) + L = concat("fortybits", T) //includes zero octet at + //end of string constant + Else + L = T + Ksign = HMAC(K,L) + Confounder = nonce(8) // get an 8 octet nonce for a confounder + Checksum = HMAC(Ksign, concat(Confounder, data)) + Ke = Ksign + if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) + memset(&Ke[7], 0x0ab, 9) + Ke2 = HMAC(Ke, Checksum) + data = RC4(Ke2, data) + + The header field on the encrypted data in KDC messages is: + + typedef struct _RC4_MDx_HEADER { + UCHAR Checksum[16]; + UCHAR Confounder[8]; + } RC4_MDx_HEADER, *PRC4_MDx_HEADER; + +Swift Category - Informational 3 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + + The character constant "fortybits" evolved from the time when a 40- + bit key length was all that was exportable from the United States. + It is now used to recognize that the key length is of "exportable" + length. In this description, the key size is actually 56-bits. + +7. Key Strength Negotiation + + A Kerberos client and server can negotiate over key length if they + are using mutual authentication. If the client is unable to perform + full strength encryption, it may propose a key in the "subkey" field + of the authenticator, using a weaker encryption type. The server + must then either return the same key or suggest its own key in the + subkey field of the AP reply message. The key used to encrypt data + is derived from the key returned by the server. If the client is + able to perform strong encryption but the server is not, it may + propose a subkey in the AP reply without first being sent a subkey + in the authenticator. + +8. GSSAPI Kerberos V5 Mechanism Type + +8.1 Mechanism Specific Changes + + The GSSAPI per-message tokens also require new checksum and + encryption types. The GSS-API per-message tokens must be changed to + support these new encryption types (See [5] Section 1.2.2). The + sealing algorithm identifier (SEAL_ALG) for an RC4 based encryption + is: + Byte 4..5 SEAL_ALG 0x10 0x00 - RC4 + + The signing algorithm identifier (SGN_ALG) for MD5 HMAC is: + Byte 2..3 SGN ALG 0x11 0x00 - HMAC + + The only support quality of protection is: + #define GSS_KRB5_INTEG_C_QOP_DEFAULT 0x0 + + In addition, when using an RC4 based encryption type, the sequence + number is sent in big-endian rather than little-endian order. + +8.2 GSSAPI Checksum Type + + The GSSAPI checksum type and algorithm is defined in Section 5. Only + the first 8 octets of the checksum are used. The resulting checksum + is stored in the SGN_CKSUM field (See [5] Section 1.2) for + GSS_GetMIC() and GSS_Wrap(conf_flag=FALSE). + +8.3 GSSAPI Encryption Types + + There are two encryption types for GSSAPI message tokens, one that + is 128 bits in strength, and one that is 56 bits in strength as + defined in Section 6. + + + +Swift Category - Informational 4 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + All padding is rounded up to 1 byte. One byte is needed to say that + there is 1 byte of padding. The DES based mechanism type uses 8 byte + padding. See [5] Section 1.2.2.3. + + The encryption mechanism used for GSS based messages is as follow: + + T = the message type, encoded as a little-endian four byte integer. + + GSS-ENCRYPT(K, T, data) + IV = SND_SEQ + K = XOR(K, 0xf0f0f0f0f0f0f0f0f0f0f0f0f0f0f0) + if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) + L = concat("fortybits", T) //includes zero octet at end + else + L = T + Ksign = HMAC(K, L) + Ke = Ksign + if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) + memset(&Ke[7], 0x0ab, 9) + Ke2 = HMAC(Ke, IV) + Data = RC4(Ke2, data) + SND_SEQ = RC4(Ke, seq#) + + The sequence number (SND_SEQ) and IV are used as defined in [5] + Section 1.2.2. + + The character constant "fortybits" evolved from the time when a 40- + bit key length was all that was exportable from the United States. + It is now used to recognize that the key length is of "exportable" + length. In this description, the key size is actually 56-bits. + +8. Security Considerations + + Care must be taken in implementing this encryption type because it + uses a stream cipher. If a different IV isnÆt used in each direction + when using a session key, the encryption is weak. By using the + sequence number as an IV, this is avoided. + +9. 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 Krawczyk, H., Bellare, M., Canetti, R.,"HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997 + + 4 Kohl, J., Neuman, C., "The Kerberos Network Authentication + Service (V5)", RFC 1510, September 1993 + + + +Swift Category - Informational 5 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + + 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, + June 1996 + + 6 R. Rivest, "The MD4 Message-Digest Algorithm", RFC-1320, April + 1992 + + 7 R. Rivest, "The MD5 Message-Digest Algorithm", RFC-1321, April + 1992 + + 8 RC4 is a proprietary encryption algorithm available under license + from RSA Data Security Inc. For licensing information, + contact: + RSA Data Security, Inc. + 100 Marine Parkway + Redwood City, CA 94065-1031 + + 9 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network + Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- + 04.txt, June 25, 1999 + + +10. Author's Addresses + + Mike Swift + Microsoft + One Microsoft Way + Redmond, Washington + Email: mikesw@microsoft.com + + John Brezak + Microsoft + One Microsoft Way + Redmond, Washington + Email: jbrezak@microsoft.com + + + + + + + + + + + + + + + + + + + +Swift Category - Informational 6 + + Windows 2000 RC4-HMAC Kerberos E-Type October 1999 + + + +11. 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 - Informational 7 +
\ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/draft-foo b/crypto/heimdal/doc/standardisation/draft-foo new file mode 100644 index 0000000..8174d46 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo @@ -0,0 +1,171 @@ + + + + + + +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-ipv6.txt> SICS +Internet-Draft October, 1997 +Expire in six months + + Kerberos over IPv6 + +Status of this Memo + + This document is an Internet-Draft. 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." + + To view the entire list of current Internet-Drafts, please check the + "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow + Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), + munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or + ftp.isi.edu (US West Coast). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + + This document specifies the address types and transport types + necessary for using Kerberos [RFC1510] over IPv6 [RFC1883]. + +Specification + + IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB + order. The type of IPv6 addresses is twenty-four (24). + + The following addresses (see [RFC1884]) MUST not appear in any + Kerberos packet: + + the Unspecified Address + the Loopback Address + Link-Local addresses + + IPv4-mapped IPv6 addresses MUST be represented as addresses of type + 2. + + + + +Westerlund [Page 1] + +Internet Draft Kerberos over IPv6 October, 1997 + + + Communication with the KDC over IPv6 MUST be done as in section 8.2.1 + of [RFC1510]. + +Discussion + + [RFC1510] suggests using the address family constants in + <sys/socket.h> from BSD. This cannot be done for IPv6 as these + numbers have diverged and are different on different BSD-derived + systems. [RFC2133] does not either specify a value for AF_INET6. + Thus a value has to be decided and the implementations have to + convert between the value used in Kerberos HostAddress and the local + AF_INET6. + + There are a few different address types in IPv6, see [RFC1884]. Some + of these are used for quite special purposes and it makes no sense to + include them in Kerberos packets. + + It is necessary to represent IPv4-mapped addresses as Internet + addresses (type 2) to be compatible with Kerberos implementations + that only support IPv4. + +Security considerations + + This memo does not introduce any known security considerations in + addition to those mentioned in [RFC1510]. + +References + + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + [RFC1883] Deering, S., Hinden, R., "Internet Protocol, Version 6 + (IPv6) Specification", RFC 1883, December 1995. + + [RFC1884] Hinden, R., Deering, S., "IP Version 6 Addressing + Architecture", RFC 1884, December 1995. + + [RFC2133] Gilligan, R., Thomson, S., Bound, J., Stevens, W., "Basic + Socket Interface Extensions for IPv6", RFC2133, April 1997. + +Author's Address + + Assar Westerlund + Swedish Institute of Computer Science + Box 1263 + S-164 29 KISTA + Sweden + + + + +Westerlund [Page 2] + +Internet Draft Kerberos over IPv6 October, 1997 + + + Phone: +46-8-7521526 + Fax: +46-8-7517230 + EMail: assar@sics.se + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Westerlund [Page 3] + diff --git a/crypto/heimdal/doc/standardisation/draft-foo.ms b/crypto/heimdal/doc/standardisation/draft-foo.ms new file mode 100644 index 0000000..62b109a --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo.ms @@ -0,0 +1,136 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Westerlund +.ds RF [Page %] +.ds CF +.ds LH Internet Draft +.ds RH October, 1997 +.ds CH Kerberos over IPv6 +.hy 0 +.ad l +.in 0 +.ta \n(.luR +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-ipv6.txt> SICS +Internet-Draft October, 1997 +Expire in six months + +.ce +Kerberos over IPv6 + +.ti 0 +Status of this Memo + +.in 3 +This document is an Internet-Draft. 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." + +To view the entire list of current Internet-Drafts, please check +the "1id-abstracts.txt" listing contained in the Internet-Drafts +Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net +(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East +Coast), or ftp.isi.edu (US West Coast). + +Distribution of this memo is unlimited. Please send comments to the +<cat-ietf@mit.edu> mailing list. + +.ti 0 +Abstract + +.in 3 +This document specifies the address types and transport types +necessary for using Kerberos [RFC1510] over IPv6 [RFC1883]. + +.ti 0 +Specification + +.in 3 +IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB +order. The type of IPv6 addresses is twenty-four (24). + +The following addresses (see [RFC1884]) MUST not appear in any +Kerberos packet: + +the Unspecified Address +.br +the Loopback Address +.br +Link-Local addresses + +IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. + +Communication with the KDC over IPv6 MUST be done as in section +8.2.1 of [RFC1510]. + +.ti 0 +Discussion + +.in 3 +[RFC1510] suggests using the address family constants in +<sys/socket.h> from BSD. This cannot be done for IPv6 as these +numbers have diverged and are different on different BSD-derived +systems. [RFC2133] does not either specify a value for AF_INET6. +Thus a value has to be decided and the implementations have to convert +between the value used in Kerberos HostAddress and the local AF_INET6. + +There are a few different address types in IPv6, see [RFC1884]. Some +of these are used for quite special purposes and it makes no sense to +include them in Kerberos packets. + +It is necessary to represent IPv4-mapped addresses as Internet +addresses (type 2) to be compatible with Kerberos implementations that +only support IPv4. + +.ti 0 +Security considerations + +.in 3 +This memo does not introduce any known security considerations in +addition to those mentioned in [RFC1510]. + +.ti 0 +References + +.in 3 +[RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network +Authentication Service (V5)", RFC 1510, September 1993. + +[RFC1883] Deering, S., Hinden, R., "Internet Protocol, Version 6 +(IPv6) Specification", RFC 1883, December 1995. + +[RFC1884] Hinden, R., Deering, S., "IP Version 6 Addressing +Architecture", RFC 1884, December 1995. + +[RFC2133] Gilligan, R., Thomson, S., Bound, J., Stevens, W., "Basic +Socket Interface Extensions for IPv6", RFC2133, April 1997. + +.ti 0 +Author's Address + +Assar Westerlund +.br +Swedish Institute of Computer Science +.br +Box 1263 +.br +S-164 29 KISTA +.br +Sweden + +Phone: +46-8-7521526 +.br +Fax: +46-8-7517230 +.br +EMail: assar@sics.se diff --git a/crypto/heimdal/doc/standardisation/draft-foo2 b/crypto/heimdal/doc/standardisation/draft-foo2 new file mode 100644 index 0000000..0fa695f --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo2 @@ -0,0 +1,171 @@ + + + + + + +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-tcp.txt> SICS +Internet-Draft Johan Danielsson +November, 1997 PDC, KTH +Expire in six months + + Kerberos over TCP + +Status of this Memo + + This document is an Internet-Draft. 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." + + To view the entire list of current Internet-Drafts, please check the + "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow + Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), + munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or + ftp.isi.edu (US West Coast). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + + This document specifies how the communication should be done between + a client and a KDC using Kerberos [RFC1510] with TCP as the transport + protocol. + +Specification + + This draft specifies an extension to section 8.2.1 of RFC1510. + + A Kerberos server MAY accept requests on TCP port 88 (decimal). + + The data sent from the client to the KDC should consist of 4 bytes + containing the length, in network byte order, of the Kerberos + request, followed by the request (AS-REQ or TGS-REQ) itself. The + reply from the KDC should consist of the length of the reply packet + (4 bytes, network byte order) followed by the packet itself (AS-REP, + TGS-REP, or KRB-ERROR). + + + + +Westerlund, Danielsson [Page 1] + +Internet Draft Kerberos over TCP November, 1997 + + + C->S: Open connection to TCP port 88 at the server + C->S: length of request + C->S: AS-REQ or TGS-REQ + S->C: length of reply + S->C: AS-REP, TGS-REP, or KRB-ERROR + +Discussion + + Even though the preferred way of sending kerberos packets is over UDP + there are several occasions when it's more practical to use TCP. + + Mainly, it's usually much less cumbersome to get TCP through + firewalls than UDP. + + In theory, there's no reason for having explicit length fields, that + information is already encoded in the ASN1 encoding of the Kerberos + packets. But having explicit lengths makes it unnecessary to have to + decode the ASN.1 encoding just to know how much data has to be read. + + Another way of signaling the end of the request of the reply would be + to do a half-close after the request and a full-close after the + reply. This does not work well with all kinds of firewalls. + +Security considerations + + This memo does not introduce any known security considerations in + addition to those mentioned in [RFC1510]. + +References + + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + +Authors' Addresses + + Assar Westerlund + Swedish Institute of Computer Science + Box 1263 + S-164 29 KISTA + Sweden + + Phone: +46-8-7521526 + Fax: +46-8-7517230 + EMail: assar@sics.se + + Johan Danielsson + PDC, KTH + S-100 44 STOCKHOLM + + + +Westerlund, Danielsson [Page 2] + +Internet Draft Kerberos over TCP November, 1997 + + + Sweden + + Phone: +46-8-7907885 + Fax: +46-8-247784 + EMail: joda@pdc.kth.se + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Westerlund, Danielsson [Page 3] + diff --git a/crypto/heimdal/doc/standardisation/draft-foo2.ms b/crypto/heimdal/doc/standardisation/draft-foo2.ms new file mode 100644 index 0000000..7e0fa0a --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo2.ms @@ -0,0 +1,145 @@ +.pl 10.0i +.po 0 +.ll 7.2i +.lt 7.2i +.nr LL 7.2i +.nr LT 7.2i +.ds LF Westerlund, Danielsson +.ds RF [Page %] +.ds CF +.ds LH Internet Draft +.ds RH November, 1997 +.ds CH Kerberos over TCP +.hy 0 +.ad l +.in 0 +.ta \n(.luR +.nf +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-tcp.txt> SICS +Internet-Draft Johan Danielsson +November, 1997 PDC, KTH +Expire in six months +.fi + +.ce +Kerberos over TCP + +.ti 0 +Status of this Memo + +.in 3 +This document is an Internet-Draft. 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." + +To view the entire list of current Internet-Drafts, please check +the "1id-abstracts.txt" listing contained in the Internet-Drafts +Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net +(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East +Coast), or ftp.isi.edu (US West Coast). + +Distribution of this memo is unlimited. Please send comments to the +<cat-ietf@mit.edu> mailing list. + +.ti 0 +Abstract + +.in 3 +This document specifies how the communication should be done between a +client and a KDC using Kerberos [RFC1510] with TCP as the transport +protocol. + +.ti 0 +Specification + +This draft specifies an extension to section 8.2.1 of RFC1510. + +A Kerberos server MAY accept requests on TCP port 88 (decimal). + +The data sent from the client to the KDC should consist of 4 bytes +containing the length, in network byte order, of the Kerberos request, +followed by the request (AS-REQ or TGS-REQ) itself. The reply from +the KDC should consist of the length of the reply packet (4 bytes, +network byte order) followed by the packet itself (AS-REP, TGS-REP, or +KRB-ERROR). + +.nf +C->S: Open connection to TCP port 88 at the server +C->S: length of request +C->S: AS-REQ or TGS-REQ +S->C: length of reply +S->C: AS-REP, TGS-REP, or KRB-ERROR +.fi + +.ti 0 +Discussion + +Even though the preferred way of sending kerberos packets is over UDP +there are several occasions when it's more practical to use TCP. + +Mainly, it's usually much less cumbersome to get TCP through firewalls +than UDP. + +In theory, there's no reason for having explicit length fields, that +information is already encoded in the ASN1 encoding of the Kerberos +packets. But having explicit lengths makes it unnecessary to have to +decode the ASN.1 encoding just to know how much data has to be read. + +Another way of signaling the end of the request of the reply would be +to do a half-close after the request and a full-close after the reply. +This does not work well with all kinds of firewalls. + +.ti 0 +Security considerations + +.in 3 +This memo does not introduce any known security considerations in +addition to those mentioned in [RFC1510]. + +.ti 0 +References + +.in 3 +[RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network +Authentication Service (V5)", RFC 1510, September 1993. + +.ti 0 +Authors' Addresses + +Assar Westerlund +.br +Swedish Institute of Computer Science +.br +Box 1263 +.br +S-164 29 KISTA +.br +Sweden + +Phone: +46-8-7521526 +.br +Fax: +46-8-7517230 +.br +EMail: assar@sics.se + +Johan Danielsson +.br +PDC, KTH +.br +S-100 44 STOCKHOLM +.br +Sweden + +Phone: +46-8-7907885 +.br +Fax: +46-8-247784 +.br +EMail: joda@pdc.kth.se diff --git a/crypto/heimdal/doc/standardisation/draft-foo3 b/crypto/heimdal/doc/standardisation/draft-foo3 new file mode 100644 index 0000000..2b8b7bb --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo3 @@ -0,0 +1,227 @@ + + + + + + +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-firewalls.txt> SICS +Internet-Draft Johan Danielsson +November, 1997 PDC, KTH +Expire in six months + + Kerberos vs firewalls + +Status of this Memo + + This document is an Internet-Draft. 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." + + To view the entire list of current Internet-Drafts, please check the + "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow + Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), + munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or + ftp.isi.edu (US West Coast). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + +Introduction + + Kerberos[RFC1510] is a protocol for authenticating parties + communicating over insecure networks. + + Firewalling is a technique for achieving an illusion of security by + putting restrictions on what kinds of packets and how these are sent + between the internal (so called "secure") network and the global (or + "insecure") Internet. + +Definitions + + client: the user, process, and host acquiring tickets from the KDC + and authenticating itself to the kerberised server. + + KDC: the Kerberos Key Distribution Center + + + + +Westerlund, Danielsson [Page 1] + +Internet Draft Kerberos vs firewalls November, 1997 + + + Kerberised server: the server using Kerberos to authenticate the + client, for example telnetd. + +Firewalls + + A firewall is usually placed between the "inside" and the "outside" + networks, and is supposed to protect the inside from the evils on the + outside. There are different kinds of firewalls. The main + differences are in the way they forward packets. + + o+ The most straight forward type is the one that just imposes + restrictions on incoming packets. Such a firewall could be + described as a router that filters packets that match some + criteria. + + o+ They may also "hide" some or all addresses on the inside of the + firewall, replacing the addresses in the outgoing packets with the + address of the firewall (aka network address translation, or NAT). + NAT can also be used without any packet filtering, for instance + when you have more than one host sharing a single address (for + example, with a dialed-in PPP connection). + + There are also firewalls that does NAT both on the inside and the + outside (a server on the inside will see this as a connection from + the firewall). + + o+ A third type is the proxy type firewall, that parses the contents + of the packets, basically acting as a server to the client, and as + a client to the server (man-in-the-middle). If Kerberos is to be + used with this kind of firewall, a protocol module that handles + KDC requests has to be written. + + This type of firewall might also cause extra trouble when used with + kerberised versions of protocols that the proxy understands, in + addition to the ones mentioned below. This is the case with the FTP + Security Extensions [RFC2228], that adds a new set of commands to the + FTP protocol [RFC959], for integrity, confidentiality, and privacy + protecting commands. When transferring data, the FTP protocol uses a + separate data channel, and an FTP proxy will have to look out for + commands that start a data transfer. If all commands are encrypted, + this is impossible. A protocol that doesn't suffer from this is the + Telnet Authentication Option [RFC1416] that does all authentication + and encryption in-bound. + +Scenarios + + Here the different scenarios we have considered are described, the + problems they introduce and the proposed ways of solving them. + + + +Westerlund, Danielsson [Page 2] + +Internet Draft Kerberos vs firewalls November, 1997 + + + Combinations of these can also occur. + + Client behind firewall + + This is the most typical and common scenario. First of all the + client needs some way of communicating with the KDC. This can be + done with whatever means and is usually much simpler when the KDC is + able to communicate over TCP. + + Apart from that, the client needs to be sure that the ticket it will + acquire from the KDC can be used to authenticate to a server outside + its firewall. For this, it needs to add the address(es) of potential + firewalls between itself and the KDC/server, to the list of its own + addresses when requesting the ticket. We are not aware of any + protocol for determining this set of addresses, thus this will have + to be manually configured in the client. + + The client could also request a ticket with no addresses, but some + KDCs and servers might not accept such a ticket. + + With the ticket in possession, communication with the kerberised + server will not need to be any different from communicating between a + non-kerberised client and server. + + Kerberised server behind firewall + + The kerberised server does not talk to the KDC at all so nothing + beyond normal firewall-traversal techniques for reaching the server + itself needs to be applied. + + The kerberised server needs to be able to retrieve the original + address (before its firewall) that the request was sent for. If this + is done via some out-of-band mechanism or it's directly able to see + it doesn't matter. + + KDC behind firewall + + The same restrictions applies for a KDC as for any other server. + +Specification + +Security considerations + + This memo does not introduce any known security considerations in + addition to those mentioned in [RFC1510]. + +References + + + + +Westerlund, Danielsson [Page 3] + +Internet Draft Kerberos vs firewalls November, 1997 + + + [RFC959] Postel, J. and Reynolds, J., "File Transfer Protocol (FTP)", + RFC 969, October 1985 + + [RFC1416] Borman, D., "Telnet Authentication Option", RFC 1416, + February 1993. + + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + [RFC2228] Horowitz, M. and Lunt, S., "FTP Security Extensions", + RFC2228, October 1997. + +Authors' Addresses + + Assar Westerlund + Swedish Institute of Computer Science + Box 1263 + S-164 29 KISTA + Sweden + + Phone: +46-8-7521526 + Fax: +46-8-7517230 + EMail: assar@sics.se + + Johan Danielsson + PDC, KTH + S-100 44 STOCKHOLM + Sweden + + Phone: +46-8-7907885 + Fax: +46-8-247784 + EMail: joda@pdc.kth.se + + + + + + + + + + + + + + + + + + + +Westerlund, Danielsson [Page 4] + diff --git a/crypto/heimdal/doc/standardisation/draft-foo3.ms b/crypto/heimdal/doc/standardisation/draft-foo3.ms new file mode 100644 index 0000000..c024ca3 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-foo3.ms @@ -0,0 +1,260 @@ +.\" even if this file is called .ms, it's using the me macros. +.\" to format try something like `nroff -me' +.\" level 2 heading +.de HH +.$p "\\$2" "" "\\$1" +.$0 "\\$2" +.. +.\" make sure footnotes produce the right thing with nroff +.ie t \ +\{\ +.ds { \v'-0.4m'\x'\\n(0x=0*-0.2m'\s-3 +.ds } \s0\v'0.4m' +.\} +.el \ +\{\ +.ds { [ +.ds } ] +.\} +.ds * \\*{\\n($f\\*}\k* +.\" page footer +.fo 'Westerlund, Danielsson''[Page %]' +.\" date +.ds RH \*(mo, 19\n(yr +.\" left margin +.nr lm 6 +.\" heading indent per level +.nr si 3n +.\" footnote indent +.nr fi 0 +.\" paragraph indent +.nr po 0 +.\" don't hyphenate +.hy 0 +.\" left adjustment +.ad l +.\" indent 0 +.in 0 +.\" line length 16cm and page length 25cm (~10 inches) +.ll 16c +.pl 25c +.ta \n(.luR +.nf +Network Working Group Assar Westerlund +<draft-ietf-cat-krb5-firewalls.txt> SICS +Internet-Draft Johan Danielsson +\*(RH PDC, KTH +Expire in six months +.fi + +.\" page header, has to be set here so it won't appear on page 1 +.he 'Internet Draft'Kerberos vs firewalls'\*(RH' +.ce +.b "Kerberos vs firewalls" + +.HH 1 "Status of this Memo" +.lp +This document is an Internet-Draft. 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. +.lp +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 \*(lqwork in progress.\*(rq +.lp +To view the entire list of current Internet-Drafts, please check the +\*(lq1id-abstracts.txt\*(rq listing contained in the Internet-Drafts +Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), +munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or +ftp.isi.edu (US West Coast). +.lp +Distribution of this memo is unlimited. Please send comments to the +<cat-ietf@mit.edu> mailing list. +.HH 1 "Abstract" +.lp +Kerberos and firewalls both deal with security, but doesn't get along +very well. This memo discusses ways to use Kerberos in a firewalled +environment. +.HH 1 "Introduction" +.lp +Kerberos[RFC1510] +.(d +[RFC1510] +Kohl, J. and Neuman, C., \*(lqThe Kerberos Network Authentication +Service (V5)\*(rq, RFC 1510, September 1993. +.)d +is a protocol for authenticating parties communicating over insecure +networks. Firewalling is a technique for achieving an illusion of +security by putting restrictions on what kinds of packets and how +these are sent between the internal (so called \*(lqsecure\*(rq) +network and the global (or \*(lqinsecure\*(rq) Internet. The problems +with firewalls are many, but to name a few: +.np +Firewalls usually doesn't allow people to use UDP. The reason for this +is that UDP is (by firewall advocates) considered insecure. This +belief is probably based on the fact that many \*(lqinsecure\*(rq +protocols (like NFS) use UDP. UDP packets are also considered easy to +fake. +.np +Firewalls usually doesn't allow people to connect to arbitrary ports, +such as the ports used when talking to the KDC. +.np +In many non-computer organisations, the computer staff isn't what +you'd call \*(lqwizards\*(rq; a typical case is an academic +institution, where someone is taking care of the computers part time, +and is doing research the rest of the time. Adding a complex device +like a firewall to an environment like this, often leads to poorly run +systems that is more a hindrance for the legitimate users than to +possible crackers. +.lp +The easiest way to deal with firewalls is to ignore them, however in +some cases this just isn't possible. You might have users that are +stuck behind a firewall, but also has to access your system, or you +might find yourself behind a firewall, for instance when out +travelling. +.lp +To make it possible for people to use Kerberos from behind a firewall, +there are several things to consider. +.(q +.i +Add things to do when stuck behind a firewall, like talking about the +problem with local staff, making them open some port in the firewall, +using some other port, or proxy. +.r +.)q +.HH 1 "Firewalls" +.lp +A firewall is usually placed between the \*(lqinside\*(rq and the +\*(lqoutside\*(rq networks, and is supposed to protect the inside from the +evils on the outside. There are different kinds of firewalls. The +main differences are in the way they forward (or doesn't) packets. +.ip \(bu +The most straight forward type is the one that just imposes +restrictions on incoming packets. Such a firewall could be described +as a router that filters packets that match some criteria. +.ip \(bu +They may also \*(lqhide\*(rq some or all addresses on the inside of the +firewall, replacing the addresses in the outgoing packets with the +address of the firewall (aka network address translation, or NAT). NAT +can also be used without any packet filtering, for instance when you +have more than one host sharing a single address (e.g with a dialed-in +PPP connection). +.ip +There are also firewalls that does NAT both on the inside and the +outside (a server on the inside will see this as a connection from the +firewall). +.ip \(bu +A third type is the proxy type firewall, that parses the contents of +the packets, basically acting as a server to the client, and as a +client to the server (man-in-the-middle). If Kerberos is to be used +with this kind of firewall, a protocol module that handles KDC +requests has to be written\**. +.(f +\**Instead of writing a new module for Kerberos, it can be possible to +hitch a ride on some other protocol, that's already beeing handled by +the proxy. +.)f +.lp +The last type of firewall might also cause extra trouble when used +with kerberised versions of protocols that the proxy understands, in +addition to the ones mentioned below. This is the case with the FTP +Security Extensions [RFC2228], +.(d +[RFC2228] +Horowitz, M. and Lunt, S., \*(lqFTP Security Extensions\*(rq, RFC2228, +October 1997. +.)d +that adds a new set of commands to the FTP protocol [RFC959], +.(d +[RFC959] Postel, J. and Reynolds, J., \*(lqFile Transfer Protocol +(FTP)\*(rq, RFC 969, October 1985 +.)d +for integrity, confidentiality, and privacy protecting commands, and +data. When transferring data, the FTP protocol uses a separate data +channel, and an FTP proxy will have to look out for commands that +start a data transfer. If all commands are encrypted, this is +impossible. A protocol that doesn't suffer from this is the Telnet +Authentication Option [RFC1416] +.(d +[RFC1416] +Borman, D., \*(lqTelnet Authentication Option\*(rq, RFC 1416, February +1993. +.)d +that does all +authentication and encryption in-bound. +.HH 1 "Scenarios" +.lp +Here the different scenarios we have considered are described, the +problems they introduce and the proposed ways of solving them. +Combinations of these can also occur. +.HH 2 "Client behind firewall" +.lp +This is the most typical and common scenario. First of all the client +needs some way of communicating with the KDC. This can be done with +whatever means and is usually much simpler when the KDC is able to +communicate over TCP. +.lp +Apart from that, the client needs to be sure that the ticket it will +acquire from the KDC can be used to authenticate to a server outside +its firewall. For this, it needs to add the address(es) of potential +firewalls between itself and the KDC/server, to the list of its own +addresses when requesting the ticket. We are not aware of any +protocol for determining this set of addresses, thus this will have to +be manually configured in the client. +.lp +The client could also request a ticket with no addresses. This is not +a recommended way to solve this problem. The address was put into the +ticket to make it harder to use a stolen ticket. A ticket without +addresses will therefore be less \*(lqsecure.\*(rq RFC1510 also says that +the KDC may refuse to issue, and the server may refuse to accept an +address-less ticket. +.lp +With the ticket in possession, communication with the kerberised +server will not need to be any different from communicating between a +non-kerberised client and server. +.HH 2 "Kerberised server behind firewall" +.lp +The kerberised server does not talk to the KDC at all, so nothing +beyond normal firewall-traversal techniques for reaching the server +itself needs to be applied. +.lp +If the firewall rewrites the clients address, the server will have to +use some other (possibly firewall specific) protocol to retrieve the +original address. If this is not possible, the address field will have +to be ignored. This has the same effect as if there were no addresses +in the ticket (see the discussion above). +.HH 2 "KDC behind firewall" +.lp +The KDC is in this respect basically just like any other server. +.\" .uh "Specification" +.HH 1 "Security considerations" +.lp +Since the whole network behind a NAT-type firewall looks like one +computer from the outside, any security added by the addresses in the +ticket will be lost. +.HH 1 "References" +.lp +.pd +.HH 1 "Authors' Addresses" +.lp +.nf +Assar Westerlund +Swedish Institute of Computer Science +Box 1263 +S-164 29 KISTA +.sp +Phone: +46-8-7521526 +Fax: +46-8-7517230 +EMail: assar@sics.se +.sp 2 +Johan Danielsson +Center for Parallel Computers +KTH +S-100 44 STOCKHOLM +.sp +Phone: +46-8-7906356 +Fax: +46-8-247784 +EMail: joda@pdc.kth.se +.fi
\ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt b/crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt new file mode 100644 index 0000000..4dcff48 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt @@ -0,0 +1,244 @@ +Network Working Group M. Horowitz +<draft-horowitz-key-derivation-01.txt> Cygnus Solutions +Internet-Draft March, 1997 + + + Key Derivation for Authentication, Integrity, and Privacy + +Status of this Memo + + This document is an Internet-Draft. 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.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + author. + +Abstract + + Recent advances in cryptography have made it desirable to use longer + cryptographic keys, and to make more careful use of these keys. In + particular, it is considered unwise by some cryptographers to use the + same key for multiple purposes. Since most cryptographic-based + systems perform a range of functions, such as authentication, key + exchange, integrity, and encryption, it is desirable to use different + cryptographic keys for these purposes. + + This RFC does not define a particular protocol, but defines a set of + cryptographic transformations for use with arbitrary network + protocols and block cryptographic algorithm. + + +Deriving Keys + + In order to use multiple keys for different functions, there are two + possibilities: + + - Each protocol ``key'' contains multiple cryptographic keys. The + implementation would know how to break up the protocol ``key'' for + use by the underlying cryptographic routines. + + - The protocol ``key'' is used to derive the cryptographic keys. + The implementation would perform this derivation before calling + + + +Horowitz [Page 1] + +Internet Draft Key Derivation March, 1997 + + + the underlying cryptographic routines. + + In the first solution, the system has the opportunity to provide + separate keys for different functions. This has the advantage that + if one of these keys is broken, the others remain secret. However, + this comes at the cost of larger ``keys'' at the protocol layer. In + addition, since these ``keys'' may be encrypted, compromising the + cryptographic key which is used to encrypt them compromises all the + component keys. Also, the not all ``keys'' are used for all possible + functions. Some ``keys'', especially those derived from passwords, + are generated from limited amounts of entropy. Wasting some of this + entropy on cryptographic keys which are never used is unwise. + + The second solution uses keys derived from a base key to perform + cryptographic operations. By carefully specifying how this key is + used, all of the advantages of the first solution can be kept, while + eliminating some disadvantages. In particular, the base key must be + used only for generating the derived keys, and this derivation must + be non-invertible and entropy-preserving. Given these restrictions, + compromise of one derived keys does not compromise the other subkeys. + Attack of the base key is limited, since it is only used for + derivation, and is not exposed to any user data. + + Since the derived key has as much entropy as the base keys (if the + cryptosystem is good), password-derived keys have the full benefit of + all the entropy in the password. + + To generate a derived key from a base key: + + Derived Key = DK(Base Key, Well-Known Constant) + + where + + DK(Key, Constant) = n-truncate(E(Key, Constant)) + + In this construction, E(Key, Plaintext) is a block cipher, Constant + is a well-known constant defined by the protocol, and n-truncate + truncates its argument by taking the first n bits; here, n is the key + size of E. + + If the output of E is is shorter than n bits, then some entropy in + the key will be lost. If the Constant is smaller than the block size + of E, then it must be padded so it may be encrypted. If the Constant + is larger than the block size, then it must be folded down to the + block size to avoid chaining, which affects the distribution of + entropy. + + In any of these situations, a variation of the above construction is + used, where the folded Constant is encrypted, and the resulting + output is fed back into the encryption as necessary (the | indicates + concatentation): + + K1 = E(Key, n-fold(Constant)) + K2 = E(Key, K1) + + + +Horowitz [Page 2] + +Internet Draft Key Derivation March, 1997 + + + K3 = E(Key, K2) + K4 = ... + + DK(Key, Constant) = n-truncate(K1 | K2 | K3 | K4 ...) + + n-fold is an algorithm which takes m input bits and ``stretches'' + them to form n output bits with no loss of entropy, as described in + [Blumenthal96]. In this document, n-fold is always used to produce n + bits of output, where n is the key size of E. + + If the size of the Constant is not equal to the block size of E, then + the Constant must be n-folded to the block size of E. This number is + used as input to E. If the block size of E is less than the key + size, then the output from E is taken as input to a second invocation + of E. This process is repeated until the number of bits accumulated + is greater than or equal to the key size of E. When enough bits have + been computed, the first n are taken as the derived key. + + Since the derived key is the result of one or more encryptions in the + base key, deriving the base key from the derived key is equivalent to + determining the key from a very small number of plaintext/ciphertext + pairs. Thus, this construction is as strong as the cryptosystem + itself. + + +Deriving Keys from Passwords + + When protecting information with a password or other user data, it is + necessary to convert an arbitrary bit string into an encryption key. + In addition, it is sometimes desirable that the transformation from + password to key be difficult to reverse. A simple variation on the + construction in the prior section can be used: + + Key = DK(n-fold(Password), Well-Known Constant) + + The n-fold algorithm is reversible, so recovery of the n-fold output + is equivalent to recovery of Password. However, recovering the n- + fold output is difficult for the same reason recovering the base key + from a derived key is difficult. + + + + Traditionally, the transformation from plaintext to ciphertext, or + vice versa, is determined by the cryptographic algorithm and the key. + A simple way to think of derived keys is that the transformation is + determined by the cryptographic algorithm, the constant, and the key. + + For interoperability, the constants used to derive keys for different + purposes must be specified in the protocol specification. The + constants must not be specified on the wire, or else an attacker who + determined one derived key could provide the associated constant and + spoof data using that derived key, rather than the one the protocol + designer intended. + + + + +Horowitz [Page 3] + +Internet Draft Key Derivation March, 1997 + + + Determining which parts of a protocol require their own constants is + an issue for the designer of protocol using derived keys. + + +Security Considerations + + This entire document deals with security considerations relating to + the use of cryptography in network protocols. + + +Acknowledgements + + I would like to thank Uri Blumenthal, Hugo Krawczyk, and Bill + Sommerfeld for their contributions to this document. + + +References + + [Blumenthal96] Blumenthal, U., "A Better Key Schedule for DES-Like + Ciphers", Proceedings of PRAGOCRYPT '96, 1996. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz [Page 4] diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt new file mode 100644 index 0000000..ccba35e --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt @@ -0,0 +1,62 @@ + + +A new Request for Comments is now available in online RFC libraries. + + + RFC 2078 + + Title: Generic Security Service Application Program + Interface, Version 2 + Author: J. Linn + Date: January 1997 + Mailbox: John.Linn@ov.com + Pages: 85 + Characters: 185990 + Obsoletes: 1508 + + URL: ftp://ds.internic.net/rfc/rfc2078.txt + + +This memo revises RFC-1508, making specific, incremental changes in +response to implementation experience and liaison requests. It is +intended, therefore, that this memo or a successor version thereto +will become the basis for subsequent progression of the GSS-API +specification on the standards track. This document is a product of +the Common Authentication Technology Working Group. + +This is now a Proposed Standard Protocol. + +This document specifies an Internet standards track protocol for the +Internet community, and requests discussion and suggestions for +improvements. Please refer to the current edition of the "Internet +Official Protocol Standards" (STD 1) for the standardization state and +status of this protocol. Distribution of this memo is unlimited. + +This announcement is sent to the IETF list and the RFC-DIST list. +Requests to be added to or deleted from the IETF distribution list +should be sent to IETF-REQUEST@CNRI.RESTON.VA.US. Requests to be +added to or deleted from the RFC-DIST distribution list should +be sent to RFC-DIST-REQUEST@ISI.EDU. + +Details on obtaining RFCs via FTP or EMAIL may be obtained by sending +an EMAIL message to rfc-info@ISI.EDU with the message body +help: ways_to_get_rfcs. For example: + + To: rfc-info@ISI.EDU + Subject: getting rfcs + + help: ways_to_get_rfcs + +Requests for special distribution should be addressed to either the +author of the RFC in question, or to admin@DS.INTERNIC.NET. Unless +specifically noted otherwise on the RFC itself, all RFCs are for +unlimited distribution. + +Submissions for Requests for Comments should be sent to +RFC-EDITOR@ISI.EDU. Please consult RFC 1543, Instructions to RFC +Authors, for further information. + + +Joyce K. Reynolds and Mary Kennedy +USC/Information Sciences Institute + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt new file mode 100644 index 0000000..518f4c6 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt @@ -0,0 +1,6188 @@ + + Internet draft J.Wray + IETF Common Authentication Technology WG Digital Equipment Corporation + <draft-ietf-cat-gssv2-cbind-04.txt> March 1997 + + + + Generic Security Service API Version 2 : C-bindings + + + 1. STATUS OF THIS MEMO + + This document is an Internet Draft. 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. Internet Drafts may be updated, replaced, + or obsoleted by other documents at any time. It is not appropriate to + use Internet Drafts as reference material or to cite them other than as + a "working draft" or "work in progress." Please check the I-D abstract + listing contained in each Internet Draft directory to learn the current + status of this or any other Internet Draft. + + Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF + Common Authentication Technology WG discussion list. + + + 2. ABSTRACT + + This draft document specifies C language bindings for Version 2 of the + Generic Security Service Application Program Interface (GSSAPI), which + is described at a language-independent conceptual level in other drafts + [GSSAPI]. It revises RFC-1509, making specific incremental changes in + response to implementation experience and liaison requests. It is + intended, therefore, that this draft or a successor version thereof will + become the basis for subsequent progression of the GSS-API specification + on the standards track. + + The Generic Security Service Application Programming Interface provides + security services to its callers, and is intended for implementation + atop a variety of underlying cryptographic mechanisms. Typically, + GSSAPI callers will be application protocols into which security + enhancements are integrated through invocation of services provided by + the GSSAPI. The GSSAPI allows a caller application to authenticate a + principal identity associated with a peer application, to delegate + rights to a peer, and to apply security services such as confidentiality + and integrity on a per-message basis. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 1] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 3. INTRODUCTION + + The Generic Security Service Application Programming Interface [GSSAPI] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and to + apply security services such as confidentiality and integrity on a per- + message basis. + + There are four stages to using the GSSAPI: + + (a) The application acquires a set of credentials with which it may + prove its identity to other processes. The application's + credentials vouch for its global identity, which may or may not be + related to any local username under which it may be running. + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a pair + of GSSAPI data structures that contain shared state information, + which is required in order that per-message security services may + be provided. Examples of state that might be shared between + applications as part of a security context are cryptographic keys, + and message sequence numbers. As part of the establishment of a + security context, the context initiator is authenticated to the + responder, and may require that the responder is authenticated in + turn. The initiator may optionally give the responder the right + to initiate further security contexts, acting as an agent or + delegate of the initiator. This transfer of rights is termed + delegation, and is achieved by creating a set of credentials, + similar to those used by the initiating application, but which may + be used by the responder. + + To establish and maintain the shared information that makes up the + security context, certain GSSAPI calls will return a token data + structure, which is a cryptographically protected opaque data + type. The caller of such a GSSAPI routine is responsible for + transferring the token to the peer application, encapsulated if + necessary in an application-application protocol. On receipt of + such a token, the peer application should pass it to a + corresponding GSSAPI routine which will decode the token and + extract the information, updating the security context state + information accordingly. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + + to application data, which are treated by GSSAPI as arbitrary + octet-strings. An application transmitting a message that it + + + + Wray Document Expiration: 1 September 1997 [Page 2] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + wishes to protect will call the appropriate GSSAPI routine + (gss_get_mic or gss_wrap) to apply protection, specifying the + appropriate security context, and send the resulting token to the + receiving application. The receiver will pass the received token + (and, in the case of data protected by gss_get_mic, the + accompanying message-data) to the corresponding decoding routine + (gss_verify_mic or gss_unwrap) to remove the protection and + validate the data. + + (d) At the completion of a communications session (which may extend + across several transport connections), each application calls a + GSSAPI routine to delete the security context. Multiple contexts + may also be used (either successively or simultaneously) within a + single communications association, at the option of the + applications. + + + 4. GSSAPI ROUTINES + + This section lists the routines that make up the GSSAPI, and offers a + brief description of the purpose of each routine. Detailed descriptions + of each routine are listed in alphabetical order in section 7. + + Table 4-1 GSSAPI Credential-management Routines + + ROUTINE SECTION FUNCTION + + gss_acquire_cred 7.2 Assume a global identity; + Obtain a GSSAPI credential + handle for pre-existing + credentials. + + gss_add_cred 7.3 Construct credentials + incrementally + + gss_inquire_cred 7.21 Obtain information about + a credential. + + gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information + about a credential. + + gss_release_cred 7.27 Discard a credential handle. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 3] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Table 4-2 GSSAPI Context-level Routines + + ROUTINE SECTION FUNCTION + + gss_init_sec_context 7.19 Initiate a security context + with a peer application + + + gss_accept_sec_context 7.1 Accept a security context + initiated by a peer + application + + gss_delete_sec_context 7.9 Discard a security context + + gss_process_context_token 7.25 Process a token on a security + context from a peer + application + + gss_context_time 7.7 Determine for how long a + context will remain valid + + gss_inquire_context 7.20 Obtain information about a + security context + + gss_wrap_size_limit 7.33 Determine token-size limit for + gss_wrap on a context + + gss_export_sec_context 7.14 Transfer a security context to + another process + + gss_import_sec_context 7.17 Import a transferred context + + + + + Table 4-3 GSSAPI Per-message Routines + + ROUTINE SECTION FUNCTION + + gss_get_mic 7.15 Calculate a cryptographic + Message Integrity Code (MIC) + for a message; integrity service + + gss_verify_mic 7.32 Check a MIC against a message; + verify integrity of a received + message + + gss_wrap 7.36 Attach a MIC to a message, and + optionally encrypt the message + content; confidentiality service + + + + + Wray Document Expiration: 1 September 1997 [Page 4] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_unwrap 7.31 Verify a message with attached + MIC, and decrypt message + content if necessary. + + + + + Table 4-4 GSSAPI Name manipulation Routines + + ROUTINE SECTION FUNCTION + + gss_import_name 7.16 Convert a contiguous string name + to internal-form + + gss_display_name 7.10 Convert internal-form name + to text + + gss_compare_name 7.6 Compare two internal-form names + + gss_release_name 7.28 Discard an internal-form name + + gss_inquire_names_for_mech 7.24 List the name-types supported + by a specified mechanism + + gss_inquire_mechs_for_name 7.23 List mechanisms that support + a given nametype + + gss_canonicalize_name 7.5 Convert an internal name to + an MN. + + gss_export_name 7.13 Convert an MN to export form + + gss_duplicate_name 7.12 Create a copy of an internal name + + + + + Table 4-5 GSSAPI Miscellaneous Routines + + ROUTINE SECTION FUNCTION + + gss_display_status 7.11 Convert a GSSAPI status code + to text + + gss_indicate_mechs 7.18 Determine available underlying + authentication mechanisms + + gss_release_buffer 7.26 Discard a buffer + + gss_release_oid_set 7.29 Discard a set of object + identifiers + + + + Wray Document Expiration: 1 September 1997 [Page 5] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_create_empty_oid_set 7.8 Create a set containing no + object identifiers + + gss_add_oid_set_member 7.4 Add an object identifier to + a set + + gss_test_oid_set_member 7.30 Determines whether an object + identifier is a member of a set + + + + + + Individual GSSAPI implementations may augment these routines by + providing additional mechanism-specific routines if required + functionality is not available from the generic forms. Applications are + encouraged to use the generic routines wherever possible on portability + grounds. + + + 5. DATA TYPES AND CALLING CONVENTIONS + + The following conventions are used by the GSSAPI C-language bindings: + + 5.1. Integer types + + GSSAPI uses the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data type + is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map this + type onto a built-in data type. If the platform supports the X/Open + xom.h header file, the OM_uint32 definition contained therein should be + used; the GSSAPI header file in Appendix A contains logic that will + detect the prior inclusion of xom.h, and will not attempt to re-declare + OM_uint32. If the X/Open header file is not available on the platform, + the GSSAPI implementation should use the smallest natural unsigned + integer type that provides at least 32 bits of precision. + + 5.2. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous octet-strings. All such data is passed between the + GSSAPI and the caller using the gss_buffer_t data type. This data type + is a pointer to a buffer descriptor, which consists of a length field + that contains the total number of bytes in the datum, and a value field + which contains a pointer to the actual datum: + + + + + + Wray Document Expiration: 1 September 1997 [Page 6] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data returned to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; unused gss_buffer_desc objects may + be initialized to the value GSS_C_EMPTY_BUFFER. + + 5.2.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at the + GSSAPI, because their internal structure has no significance either to + the GSSAPI or to the caller. Examples of such opaque data types are the + input_token parameter to gss_init_sec_context (which is opaque to the + caller), and the input_message parameter to gss_wrap (which is opaque to + the GSSAPI). Opaque data is passed between the GSSAPI and the + application using the gss_buffer_t datatype. + + 5.2.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO Latin-1 + character strings. Examples are the printable strings passed to + gss_import_name via the input_name_buffer parameter. Some GSSAPI + routines also return character strings. All such character strings are + passed between the application and the GSSAPI implementation using the + gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object. + + When a gss_buffer_desc object describes a printable string, the length + field of the gss_buffer_desc should only count printable characters + within the string. In particular, a trailing NUL character should NOT + be included in the length count, nor should either the GSSAPI + implementation or the application assume the presence of an uncounted + trailing NUL. + + 5.3. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or Object + identifier. This is a type containing ISO-defined tree-structured + values, and is used by the GSSAPI caller to select an underlying + security mechanism and to specify namespaces. A value of type gss_OID + has the following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + + Wray Document Expiration: 1 September 1997 [Page 7] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value portion of + the normal BER TLV encoding of the gss_OID. The length field contains + the number of bytes in this value. For example, the gss_OID value + corresponding to {iso(1) identified-organization(3) icd-ecma(12) + member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the + DASS X.509 authentication mechanism, has a length field of 7 and an + elements field pointing to seven octets containing the following octal + values: 53,14,2,207,163,7,5. GSSAPI implementations should provide + constant gss_OID values to allow applications to request any supported + mechanism, although applications are encouraged on portability grounds + to accept the default mechanism. gss_OID values should also be provided + to allow applications to specify particular name types (see section + 5.10). Applications should treat gss_OID_desc values returned by GSSAPI + routines as read-only. In particular, the application should not + attempt to deallocate them with free(). The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype[XOM]. + + 5.4. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. This + type represents one or more object identifiers (section 5.3). A + gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each of + which describes a single OID. gss_OID_set values are used to name the + available mechanisms supported by the GSSAPI, to request the use of + specific mechanisms, and to indicate which mechanisms a given credential + supports. + + All OID sets returned to the application by GSSAPI are dynamic objects + (the gss_OID_set_desc, the "elements" array of the set, and the + "elements" array of each member OID are all dynamically allocated), and + this storage must be deallocated by the application using the + gss_release_oid_set() routine. + + + 5.5. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which should be implemented as a pointer or + arithmetic type. If a pointer implementation is chosen, care must be + taken to ensure that two gss_cred_id_t values may be compared with the + == operator. + + + + Wray Document Expiration: 1 September 1997 [Page 8] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSSAPI credentials can contain mechanism-specific principal + authentication data for multiple mechanisms. A GSSAPI credential is + composed of a set of credential-elements, each of which is applicable to + a single mechanism. A credential may contain at most one credential- + element for each supported mechanism. A credential-element identifies + the data needed by a single mechanism to authenticate a single + principal, and conceptually contains two credential-references that + describing the actual mechanism-specific authentication data, one to be + used by GSSAPI for initiating contexts, and one to be used for + accepting contexts. For mechanisms that do not distinguish between + acceptor and initiator credentials, both references would point to the + same underlying mechanism-specific authentication data. + + Credentials describe a set of mechanism-specific principals, and give + their holder the ability to act as any of those principals. All + principal identities asserted by a single GSSAPI credential should + belong to the same entity, although enforcement of this property is an + implementation-specific matter. The GSSAPI does not make the actual + credentials available to applications; instead a credential handle is + used to identify a particular credential, held internally by GSSAPI. + The combination of GSSAPI credential handle and mechanism identifies the + principal whose identity will be asserted by the credential when used + with that mechanism. + + The gss_init_sec_context and gss_accept_sec_context routines allow the + value GSS_C_NO_CREDENTIAL to be specified as their credential handle + parameter. This special credential-handle indicates a desire by the + application to act as a default principal. While individual GSSAPI + implementations are free to determine such default behavior as + appropriate to the mechanism, the following default behavior by these + routines is recommended for portability: + + (a) gss_init_sec_context + + (i) If there is only a single principal capable of initiating + security contexts for the chosen mechanism that the + application is authorized to act on behalf of, then that + principal shall be used, otherwise + + (ii) If the platform maintains a concept of a default network- + identity for the chosen mechanism, and if the application is + authorized to act on behalf of that identity for the purpose + of initiating security contexts, then the principal + corresponding to that identity shall be used, otherwise + + (iii) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities for the chosen mechanism, and if the + application is authorized to act on behalf of the network- + identity image of the default local identity for the purpose + of initiating security contexts using the chosen mechanism, + + + + Wray Document Expiration: 1 September 1997 [Page 9] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + then the principal corresponding to that identity shall be + used, otherwise + + (iv) A user-configurable default identity should be used. + + (b) gss_accept_sec_context + + (i) If there is only a single authorized principal identity + capable of accepting security contexts for the chosen + mechanism, then that principal shall be used, otherwise + + (ii) If the mechanism can determine the identity of the target + principal by examining the context-establishment token, and + if the accepting application is authorized to act as that + principal for the purpose of accepting security contexts + using the chosen mechanism, then that principal identity + shall be used, otherwise + + (iii) If the mechanism supports context acceptance by any + principal, and if mutual authentication was not requested, + any principal that the application is authorized to accept + security contexts under using the chosen mechanism may be + used, otherwise + + (iv) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + wherever possible. Applications requesting default behavior are likely + to be more portable across mechanisms and platforms than ones that use + gss_acquire_cred to request a specific identity. + + 5.6. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It should be + implemented as a pointer or arithmetic type. If a pointer type is + chosen, care should be taken to ensure that two gss_ctx_id_t values may + be compared with the == operator. + + The security context holds state information about each end of a peer + communication, including cryptographic state information. + + 5.7. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + octet-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other end. + Encapsulation (if required) and transfer of the token are the + + + + Wray Document Expiration: 1 September 1997 [Page 10] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + responsibility of the peer applications. A token is passed between the + GSSAPI and the application using the gss_buffer_t conventions. + + 5.8. Interprocess tokens + + Certain GSSAPI routines are intended to transfer data between processes + in multi-process programs. These routines use a caller-opaque octet- + string, generated by the GSSAPI in one process for use by the GSSAPI in + another process. The calling application is responsible for + transferring such tokens between processes in an OS-specific manner. + Note that, while GSSAPI implementors are encouraged to avoid placing + sensitive information within interprocess tokens, or to + cryptographically protect them, many implementations will be unable to + avoid placing key material or other sensitive data within them. It is + the application's responsibility to ensure that interprocess tokens are + protected in transit, and transferred only to processes that are + trustworthy. An interprocess token is passed between the GSSAPI and the + application using the gss_buffer_t conventions. + + 5.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + 5.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism(s) used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSS-API + specification) or calling errors (errors that are specific to these + language bindings). + + A GSS status code can indicate a single fatal generic API error from the + routine and a single calling error. In addition, supplementary status + information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + + Hence if a GSS-API routine returns a GSS status code whose upper 16 bits + contain a non-zero value, the call failed. If the calling error field + + + + Wray Document Expiration: 1 September 1997 [Page 11] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper 16 + bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info field + of the status code. The meaning of individual bits is listed below in + table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + GSS_S_BAD_SIG 6 A token had an invalid + GSS_S_BAD_MIC MIC + GSS_S_NO_CRED 7 No credentials were supplied, + or the credentials were + unavailable or inaccessible. + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + + + + + Wray Document Expiration: 1 September 1997 [Page 12] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + GSS_S_BAD_QOP 14 The quality-of-protection + requested could not be + provide + GSS_S_UNAUTHORIZED 15 The operation is forbidden by + local security policy + GSS_S_UNAVAILABLE 16 The operation or option is not + available + GSS_S_DUPLICATE_ELEMENT 17 The requested credential element + already exists + GSS_S_NAME_NOT_MN 18 The provided name was not a + mechanism name. + + + + + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + GSS_S_GAP_TOKEN 4 An expected per-message token + was not received + + + The routine documentation also uses the name GSS_S_COMPLETE, which is a + zero value, to indicate an absence of any API errors or supplementary + information bits. + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather + than to bitfield values. For example, the actual value of the symbol + GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status + code and removes all but the relevant field. For example, the value + obtained by applying GSS_ROUTINE_ERROR to a status code removes the + calling errors and supplementary info fields, leaving only the routine + errors field. The values delivered by these macros may be directly + compared with a GSS_S_xxx symbol of the appropriate type. The macro + + + + Wray Document Expiration: 1 September 1997 [Page 13] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_ERROR() is also provided, which when applied to a GSS status code + returns a non-zero value if the status code indicated a calling or + routine error, and a zero value otherwise. All macros defined by GSS- + API evaluate their argument(s) exactly once. + + A GSS-API implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + + 5.9.2. Mechanism-specific status codes + + GSS-API routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, indicated + by a OM_uint32 value. + + The minor_status parameter will always be set by a GSS-API routine, even + if it returns a calling error or one of the generic API errors indicated + above as fatal, although most other output parameters may remain unset + in such cases. However, output parameters that are expected to return + pointers to storage allocated by a routine must always be set by the + routine, even in the event of an error, although in such cases the GSS- + API routine may elect to set the returned parameter value to NULL to + indicate that no storage was actually allocated. Any length field + associated with such pointers (as in a gss_buffer_desc structure) should + also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS status + code is defined. The mechanism status code will provide more details + about the error. + + 5.10. Names + + A name is used to identify a person or entity. GSS-API authenticates + the relationship between a name and the entity claiming the name. + + Since different authentication mechanisms may employ different + namespaces for identifying their principals, GSSAPI's naming support is + necessarily complex in multi-mechanism environments (or even in some + single-mechanism environments where the underlying mechanism supports + multiple namespaces). + + Two distinct representations are defined for names: + + (a) An internal form. This is the GSSAPI "native" format for names, + represented by the implementation-specific gss_name_t type. It is + opaque to GSSAPI callers. A single gss_name_t object may contain + multiple names from different namespaces, but all names should + refer to the same entity. An example of such an internal name + + + + Wray Document Expiration: 1 September 1997 [Page 14] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + would be the name returned from a call to the gss_inquire_cred + routine, when applied to a credential containing credential + elements for multiple authentication mechanisms employing + different namespaces. This gss_name_t object will contain a + distinct name for the entity for each authentication mechanism. + + For GSSAPI implementations supporting multiple namespaces, objects + of type gss_name_t must contain sufficient information to + determine the namespace to which each primitive name belongs. + + (b) Mechanism-specific contiguous octet-string forms. A format + capable of containing a single name (from a single namespace). + Contiguous string names are always accompanied by an object + identifier specifying the namespace to which the name belongs, and + their format is dependent on the authentication mechanism that + employs the name. Many, but not all, contiguous string names will + be printable, and may therefore be used by GSSAPI applications for + communication with their users. + + Routines (gss_import_name and gss_display_name) are provided to convert + names between contiguous string representations and the internal + gss_name_t type. gss_import_name may support multiple syntaxes for each + supported namespace, allowing users the freedom to choose a preferred + name representation. gss_display_name should use an implementation- + chosen printable syntax for each supported name-type. + + If an application calls gss_display_name(), passing the internal name + resulting from a call to gss_import_name(), there is no guarantee the + the resulting contiguous string name will be the same as the original + imported string name. Nor do name-space identifiers necessarily survive + unchanged after a journey through the internal name-form. An example of + this might be a mechanism that authenticates X.500 names, but provides + an algorithmic mapping of Internet DNS names into X.500. That + mechanism's implementation of gss_import_name() might, when presented + with a DNS name, generate an internal name that contained both the + original DNS name and the equivalent X.500 name. Alternatively, it might + only store the X.500 name. In the latter case, gss_display_name() would + most likely generate a printable X.500 name, rather than the original + DNS name. + + The process of authentication delivers to the context acceptor an + internal name. Since this name has been authenticated by a single + mechanism, it contains only a single name (even if the internal name + presented by the context initiator to gss_init_sec_context had multiple + components). Such names are termed internal mechanism names, or "MN"s + and the names emitted by gss_accept_sec_context() are always of this + type. Since some applications may require MNs without wanting to incur + the overhead of an authentication operation, a second function, + gss_canonicalize_name(), is provided to convert a general internal name + into an MN. + + + + + Wray Document Expiration: 1 September 1997 [Page 15] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Comparison of internal-form names may be accomplished via the + gss_compare_name() routine, which returns true if the two names being + compared refer to the same entity. This removes the need for the + application program to understand the syntaxes of the various printable + names that a given GSS-API implementation may support. Since GSSAPI + assumes that all primitive names contained within a given internal name + refer to the same entity, gss_compare_name() can return true if the two + names have at least one primitive name in common. If the implementation + embodies knowledge of equivalence relationships between names taken from + different namespaces, this knowledge may also allow successful + comparison of internal names containing no overlapping primitive + elements. + + When used in large access control lists, the overhead of invoking + gss_import_name() and gss_compare_name() on each name from the ACL may + be prohibitive. As an alternative way of supporting this case, GSSAPI + defines a special form of the contiguous string name which may be + compared directly (e.g. with memcmp()). Contigous names suitable for + comparison are generated by the gss_export_name() routine, which + requires an MN as input. Exported names may be re-imported by the + gss_import_name() routine, and the resulting internal name will also be + an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the + "export name" type, and the value of this constant is given in Appendix + A. Structurally, an exported name object consists of a header + containing an OID identifying the mechanism that authenticated the name, + and a trailer containing the name itself, where the syntax of the + trailer is defined by the individual mechanism specification. The + precise format of an export name is defined in the language-independent + GSSAPI specification [GSSAPI]. + + Note that the results obtained by using gss_compare_name() will in + general be different from those obtained by invoking + gss_canonicalize_name() and gss_export_name(), and then comparing the + exported names. The first series of operation determines whether two + (unauthenticated) names identify the same principal; the second whether + a particular mechanism would authenticate them as the same principal. + These two operations will in general give the same results only for MNs. + + The gss_name_t datatype should be implemented as a pointer type. To + allow the compiler to aid the application programmer by performing + type-checking, the use of (void *) is discouraged. A pointer to an + implementation-defined type is the preferred choice. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated with + an internal-form name. + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 16] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.11. Channel Bindings + + GSS-API supports the use of user-specified tags to identify a given + context to the peer application. These tags are intended to be used to + identify the particular communications channel that carries the context. + Channel bindings are communicated to the GSS-API using the following + structure: + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type of + addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET Internet address type (e.g. IP) + GSS_C_AF_IMPLINK ARPAnet IMP address type + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these symbols name address families rather than specific + addressing formats. For address families that contain several + alternative address forms, the initiator_address and acceptor_address + fields must contain sufficient information to determine which address + form is used. When not otherwise specified, addresses should be + specified in network byte-order (that is, native byte-ordering for the + address family). + + + + + Wray Document Expiration: 1 September 1997 [Page 17] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Conceptually, the GSS-API concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism calculates a + MIC over this octet string, and binds the MIC to the context + establishment token emitted by gss_init_sec_context. The same bindings + are presented by the context acceptor to gss_accept_sec_context, and a + MIC is calculated in the same way. The calculated MIC is compared with + that found in the token, and if the MICs differ, gss_accept_sec_context + will return a GSS_S_BAD_BINDINGS error, and the context will not be + established. Some mechanisms may include the actual channel binding + data in the token (rather than just a MIC); applications should + therefore not use confidential data as channel-binding components. + Individual mechanisms may impose additional constraints on addresses and + address types that may appear in channel bindings. For example, a + mechanism may verify that the initiator_address field of the channel + bindings presented to gss_init_sec_context contains the correct network + address of the host system. Portable applications should therefore + ensure that they either provide correct information for the address + fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as + the address-types. + + 5.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + + 5.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned via + the parameter is not required by the application. + + 5.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to indicate + default actions. + + 5.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + + 5.12.4. Pointer types + + Specify NULL as the value. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 18] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 5.12.5. Object IDs + + Specify GSS_C_NO_OID as the value. + + 5.12.6. Object ID Sets + + Specify GSS_C_NO_OID_SET as the value. + + 5.12.7. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are + not to be used. + + + 6. ADDITIONAL CONTROLS + + This section discusses the optional services that a context initiator + may request of the GSS-API at context establishment. Each of these + services is requested by setting a flag in the req_flags input parameter + to gss_init_sec_context. + + The optional services currently defined are: + + Delegation - The (usually temporary) transfer of rights from initiator + to acceptor, enabling the acceptor to authenticate itself as an + agent of the initiator. + + Mutual Authentication - In addition to the initiator authenticating its + identity to the context acceptor, the context acceptor should also + authenticate itself to the initiator. + + Replay detection - In addition to providing message integrity services, + gss_get_mic and gss_wrap should include message numbering + information to enable gss_verify_mic and gss_unwrap to detect if a + message has been duplicated. + + Out-of-sequence detection - In addition to providing message integrity + services, gss_get_mic and gss_wrap should include message + sequencing information to enable gss_verify_mic and gss_unwrap to + detect if a message has been received out of sequence. + + Anonymous authentication - The establishment of the security context + should not reveal the initiator's identity to the context + acceptor. + + Any currently undefined bits within such flag arguments should be + ignored by GSS-API implementations when presented by an application, and + should be set to zero when returned to the application by the GSS-API + implementation. + + + + + + Wray Document Expiration: 1 September 1997 [Page 19] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Some mechanisms may not support all optional services, and some + mechanisms may only support some services in conjunction with others. + Both gss_init_sec_context and gss_accept_sec_context inform the + applications which services will be available from the context when the + establishment phase is complete, via the ret_flags output parameter. In + general, if the security mechanism is capable of providing a requested + service, it should do so, even if additional services must be enabled in + order to provide the requested service. If the mechanism is incapable + of providing a requested service, it should proceed without the service, + leaving the application to abort the context establishment process if it + considers the requested service to be mandatory. + + Some mechanisms may specify that support for some services is optional, + and that implementors of the mechanism need not provide it. This is + most commonly true of the confidentiality service, often because of + legal restrictions on the use of data-encryption, but may apply to any + of the services. Such mechanisms are required to send at least one + token from acceptor to initiator during context establishment when the + initiator indicates a desire to use such a service, so that the + initiating GSSAPI can correctly indicate whether the service is + supported by the acceptor's GSSAPI. + + 6.1. Delegation + + The GSS-API allows delegation to be controlled by the initiating + application via a boolean parameter to gss_init_sec_context(), the + routine that establishes a security context. Some mechanisms do not + support delegation, and for such mechanisms attempts by an application + to enable delegation are ignored. + + The acceptor of a security context for which the initiator enabled + delegation will receive (via the delegated_cred_handle parameter of + gss_accept_sec_context) a credential handle that contains the delegated + identity, and this credential handle may be used to initiate subsequent + GSSAPI security contexts as an agent or delegate of the initiator. If + the original initiator's identity is "A" and the delegate's identity is + "B", then, depending on the underlying mechanism, the identity embodied + by the delegated credential may be either "A" or "B acting for A". + + For many mechanisms that support delegation, a simple boolean does not + provide enough control. Examples of additional aspects of delegation + control that a mechanism might provide to an application are duration of + delegation, network addresses from which delegation is valid, and + constraints on the tasks that may be performed by a delegate. Such + controls are presently outside the scope of the GSS-API. GSS-API + implementations supporting mechanisms offering additional controls + should provide extension routines that allow these controls to be + exercised (perhaps by modifying the initiator's GSS-API credential prior + to its use in establishing a context). However, the simple delegation + control provided by GSS-API should always be able to over-ride other + mechanism-specific delegation controls - If the application instructs + + + + Wray Document Expiration: 1 September 1997 [Page 20] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_init_sec_context() that delegation is not desired, then the + implementation must not permit delegation to occur. This is an + exception to the general rule that a mechanism may enable services even + if they are not requested - delegation may only be provide at the + explicit request of the application. + + 6.2. Mutual authentication + + Usually, a context acceptor will require that a context initiator + authenticate itself so that the acceptor may make an access-control + decision prior to performing a service for the initiator. In some + cases, the initiator may also request that the acceptor authenticate + itself. GSS-API allows the initiating application to request this + mutual authentication service by setting a flag when calling + gss_init_sec_context. + + The initiating application is informed as to whether or not mutual + authentication is being requested of the context acceptor. Note that + some mechanisms may not support mutual authentication, and other + mechanisms may always perform mutual authentication, whether or not the + initiating application requests it. In particular, mutual + authentication my be required by some mechanisms in order to support + replay or out-of-sequence message detection, and for such mechanisms a + request for either of these services will automatically enable mutual + authentication. + + 6.3. Replay and out-of-sequence detection + + The GSS-API may provide detection of mis-ordered message once a security + context has been established. Protection may be applied to messages by + either application, by calling either gss_get_mic or gss_wrap, and + verified by the peer application by calling gss_verify_mic or + gss_unwrap. + + gss_get_mic calculates a cryptographic checksum of an application + message, and returns that checksum in a token. The application should + pass both the token and the message to the peer application, which + presents them to gss_verify_mic. + + gss_wrap calculates a cryptographic checksum of an application message, + and places both the checksum and the message inside a single token. The + application should pass the token to the peer application, which + presents it to gss_unwrap to extract the message and verify the + checksum. + + Either pair of routines may be capable of detecting out-of-sequence + message delivery, or duplication of messages. Details of such mis- + ordered messages are indicated through supplementary status bits in the + major status code returned by gss_verify_mic or gss_unwrap. The + relevant supplementary bits are: + + + + + Wray Document Expiration: 1 September 1997 [Page 21] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already + been received and processed. Contexts that do not claim to + provide replay detection may still set this bit if the duplicate + message is processed immediately after the original, with no + intervening messages. + + GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is + a duplicate. Contexts supporting out-of-sequence detection but + not replay detection should always set this bit if + GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection + should only set this bit if the token is so old that it cannot be + checked for duplication. + + GSS_S_UNSEQ_TOKEN - A later token has already been processed. + + GSS_S_GAP_TOKEN - An earlier token has not yet been received. + + A mechanism need not maintain a list of all tokens that have been + processed in order to support these status codes. A typical mechanism + might retain information about only the most recent "N" tokens + processed, allowing it to distinguish duplicates and missing tokens + within the most recent "N" messages; the receipt of a token older than + the most recent "N" would result in a GSS_S_OLD_TOKEN status. + + 6.4. Anonymous Authentication + + In certain situations, an application may wish to initiate the + authentication process to authenticate a peer, without revealing its own + identity. As an example, consider an application providing access to a + database containing medical information, and offering unrestricted + access to the service. A client of such a service might wish to + authenticate the service (in order to establish trust in any information + retrieved from it), but might not wish the service to be able to obtain + the client's identity (perhaps due to privacy concerns about the + specific inquiries, or perhaps simply to avoid being placed on mailing- + lists). + + In normal use of the GSS-API, the initiator's identity is made available + to the acceptor as a result of the context establishment process. + However, context initiators may request that their identity not be + revealed to the context acceptor. Many mechanisms do not support + anonymous authentication, and for such mechanisms the request will not + be honored. An authentication token will be still be generated, but the + application is always informed if a requested service is unavailable, + and has the option to abort context establishment if anonymity is valued + above the other security services that would require a context to be + established. + + In addition to informing the application that a context is established + anonymously (via the ret_flags outputs from gss_init_sec_context and + gss_accept_sec_context), the optional src_name output from + + + + Wray Document Expiration: 1 September 1997 [Page 22] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context and gss_inquire_context will, for such contexts, + return a reserved internal-form name, defined by the implementation. + When presented to gss_display_name, this reserved internal-form name + will result in a printable name that is syntactically distinguishable + from any valid principal name supported by the implementation, + associated with a name-type object identifier with the value + GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable + form of an anonymous name should be chosen such that it implies + anonymity, since this name may appear in, for example, audit logs. For + example, the string "<anonymous>" might be a good choice, if no valid + printable names supported by the implementation can begin with "<" and + end with ">". + + 6.5. Confidentiality + + If a context supports the confidentiality service, gss_wrap may be used + to encrypt application messages. Messages are selectively encrypted, + under the control of the conf_req_flag input parameter to gss_wrap. + + 6.6. Inter-process context transfer + + GSSAPI V2 provides routines (gss_export_sec_context and + gss_import_sec_context) which allow a security context to be transferred + between processes on a single machine. The most common use for such a + feature is a client-server design where the server is implemented as a + single process that accepts incoming security contexts, which then + launches child processes to deal with the data on these contexts. In + such a design, the child processes must have access to the security + context data structure created within the parent by its call to + gss_accept_sec_context so that they can use per-message protection + services and delete the security context when the communication session + ends. + + Since the security context data structure is expected to contain + sequencing information, it is impractical in general to share a context + between processes. Thus GSSAPI provides a call (gss_export_sec_context) + that the process which currently owns the context can call to declare + that it has no intention to use the context subsequently, and to create + an inter-process token containing information needed by the adopting + process to successfully import the context. After successful completion + of this call, the original security context is made inaccessible to the + calling process by GSSAPI, and any context handles referring to this + context are no longer valid. The originating process transfers the + inter-process token to the adopting process, which passes it to + gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it + is functionally identical to the original context. + + The inter-process token may contain sensitive data from the original + security context (including cryptographic keys). Applications using + inter-process tokens to transfer security contexts must take appropriate + steps to protect these tokens in transit. + + + + Wray Document Expiration: 1 September 1997 [Page 23] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Implementations are not required to support the inter-process transfer + of security contexts. The ability to transfer a security context is + indicated when the context is created, by gss_init_sec_context or + gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their + ret_flags parameter. + + + 6.7. The use of incomplete contexts + + Some mechanisms may allow the per-message services to be used before the + context establishment process is complete. For example, a mechanism may + include sufficient information in its initial context-level token for + the context acceptor to immediately decode messages protected with + gss_wrap or gss_get_mic. For such a mechanism, the initiating + application need not wait until subsequent context-level tokens have + been sent and received before invoking the per-message protection + services. + + The ability of a context to provide per-message services in advance of + complete context establishment is indicated by the setting of the + GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from + gss_init_sec_context and gss_accept_sec_context. Applications wishing + to use per-message protection services on partially-established contexts + should check this flag before attempting to invoke gss_wrap or + gss_get_mic. + + + + 7. GSS-API routine descriptions + + In addition to the explicit major status codes documented here, the code + GSS_S_FAILURE may be returned by any routine, indicating an + implementation-specific or mechanism-specific error condition, further + details of which are reported via the minor_status parameter. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 24] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.1. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + const gss_cred_id_t acceptor_cred_handle, + const gss_buffer_t input_token_buffer, + const gss_channel_bindings_t + input_chan_bindings, + const gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application and + a remote peer to be established. The routine may return a output_token + which should be transferred to the peer application, where the peer + application will present it to gss_init_sec_context. If no token need + be sent, gss_accept_sec_context will indicate this by setting the length + field of the output_token argument to zero. To complete the context + establishment, one or more reply tokens may be required from the peer + application; if so, gss_accept_sec_context will return a status flag of + GSS_S_CONTINUE_NEEDED, in which case it should be called again when the + reply token is received from the peer application, passing the token to + gss_accept_sec_context via the input_token parameters. + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_accept_sec_context within a loop: + + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + + do { + receive_token_from_peer(input_token); + maj_stat = gss_accept_sec_context(&min_stat, + &context_hdl, + cred_hdl, + input_token, + input_bindings, + &client_name, + &mech_type, + output_token, + &ret_flags, + &time_rec, + &deleg_cred); + + + + Wray Document Expiration: 1 September 1997 [Page 25] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + } while (maj_stat & GSS_S_CONTINUE_NEEDED); + + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the mech_type parameter may be undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_accept_sec_context returns, whether or not the context is + fully established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + + + + Wray Document Expiration: 1 September 1997 [Page 26] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + All other bits within the ret_flags argument should be set to + zero. + + + While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via + the ret_flags argument indicate the services that the implementation + expects to be available from the established context. + + If the initial call of gss_accept_sec_context() fails, the + implementation should not create a context object, and should leave the + value of the context_handle parameter set to GSS_C_NO_CONTEXT to + indicate this. In the event of a failure on a subsequent call, the + implementation is permitted to delete the "half-built" security context + (in which case it should set the context_handle parameter to + GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security + context (and the context_handle parameter) untouched for the application + to delete (using gss_delete_sec_context). + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. Once + gss_accept_sec_context() has returned a value + via this parameter, resources have been assigned + to the corresponding context, and must be + freed by the application after use with a call + to gss_delete_sec_context(). + + + acceptor_cred_handle gss_cred_id_t, read + Credential handle claimed by context acceptor. + Specify GSS_C_NO_CREDENTIAL to accept the + context as a default principal. If + GSS_C_NO_CREDENTIAL is specified, but no + default acceptor principal is defined, + GSS_S_NO_CRED will be returned. + + input_token_buffer buffer, opaque, read + token obtained from remote application. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. If channel bindings are not + used, specify GSS_C_NO_CHANNEL_BINDINGS. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 27] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + After use, this name should be deallocated by + passing it to gss_release_name(). If not + required, specify NULL. + + mech_type Object ID, modify, optional + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller (in particular, it does not + need to be freed). If not required, specify + NULL. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. If a non-zero length field is + returned, the associated storage must be freed + after use by the application with a call to + gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports a + specific service option. If not needed, + specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + + + + Wray Document Expiration: 1 September 1997 [Page 28] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling the gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator does not wish to + be authenticated; the src_name + parameter (if requested) contains + an anonymous internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + if the accompanying major status return + value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + delegated_cred_handle + gss_cred_id_t, modify, optional + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true, in which case an explicit + + + + Wray Document Expiration: 1 September 1997 [Page 29] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credential handle (i.e. not GSS_C_NO_CREDENTIAL) + will be returned; if deleg_flag is false, + gss_accept_context() will set this parameter to + GSS_C_NO_CREDENTIAL. If a credential handle is + returned, the associated resources must be released + by the application after use with a call to + gss_release_cred(). Specify NULL if not required. + + + minor_status Integer, modify + Mechanism specific status code. + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_accept_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + acceptance, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid MIC. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + + + + + Wray Document Expiration: 1 September 1997 [Page 30] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH The received token specified a mechanism that is not + supported by the implementation or the provided + credential. + + + + + + + + 7.2. gss_acquire_cred + + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + const gss_name_t desired_name, + OM_uint32 time_req, + const gss_OID_set desired_mechs, + gss_cred_usage_t cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * time_rec) + + Purpose: + + Allows an application to acquire a handle for a pre-existing credential + by name. GSS-API implementations must impose a local access-control + policy on callers of this routine to prevent unauthorized callers from + acquiring credentials to which they are not entitled. This routine is + not intended to provide a ``login to the network'' function, as such a + function would involve the creation of new credentials rather than + merely acquiring a handle to existing credentials. Such functions, if + required, should be defined in implementation-specific extensions to the + API. + + If desired_name is GSS_C_NO_NAME, the call is interpreted as a request + for a credential handle that will invoke default behavior when passed to + gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) + or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or + GSS_C_BOTH). + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any + name other than an empty name. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + + + + Wray Document Expiration: 1 September 1997 [Page 31] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + time_req Integer, read, optional + number of seconds that credentials + should remain valid. Specify GSS_C_INDEFINITE + to request that the credentials have the maximum + permitted lifetime. + + desired_mechs Set of Object IDs, read, optional + set of underlying security mechanisms that + may be used. GSS_C_NO_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. Resources + associated with this credential handle must + be released by the application after use + with a call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Storage associated + with the returned OID-set must be released by + the application after use with a call to + gss_release_oid_set(). Specify NULL if not + required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + + + + Wray Document Expiration: 1 September 1997 [Page 32] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because + they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.3. gss_add_cred + + + OM_uint32 gss_add_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t input_cred_handle, + const gss_name_t desired_name, + const gss_OID desired_mech, + gss_cred_usage_t cred_usage, + OM_uint32 initiator_time_req, + OM_uint32 acceptor_time_req, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_uint32 * initiator_time_rec, + OM_uint32 * acceptor_time_rec) + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 33] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Adds a credential-element to a credential. The credential-element is + identified by the name of the principal to which it refers. GSSAPI + implementations must impose a local access-control policy on callers of + this routine to prevent unauthorized callers from acquiring credential- + elements to which they are not entitled. This routine is not intended to + provide a ``login to the network'' function, as such a function would + involve the creation of new mechanism-specific authentication data, + rather than merely acquiring a GSSAPI handle to existing data. Such + functions, if required, should be defined in implementation-specific + extensions to the API. + + This routine is expected to be used primarily by context acceptors, + since implementations are likely to provide mechanism-specific ways of + obtaining GSS-API initiator credentials from the system login process. + Some implementations may therefore not support the acquisition of + GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g. by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call of + gss_inquire_cred immediately following the call of gss_acquire_cred must + return valid credential data, and may therefore incur the overhead of a + deferred credential acquisition. + + This routine can be used to either create a new credential containing + all credential-elements of the original in addition to the newly-acquire + credential-element, or to add the new credential-element to an existing + credential. If NULL is specified for the output_cred_handle parameter + argument, the new credential-element will be added to the credential + identified by input_cred_handle; if a valid pointer is specified for the + output_cred_handle parameter, a new credential and handle will be + created. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the + gss_add_cred will create its output_cred_handle based on default + behavior. That is, the call will have the same effect as if the + application had first made a call to gss_acquire_cred(), specifying the + same usage and passing GSS_C_NO_NAME as the desired_name parameter to + obtain an explicit credential handle embodying default behavior, passed + this credential handle to gss_add_cred(), and finally called + gss_release_cred() on the first credential handle. + + If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter, + a non-NULL output_cred_handle must be supplied. + + Parameters: + + + + + Wray Document Expiration: 1 September 1997 [Page 34] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + minor_status Integer, modify + Mechanism specific status code. + + input_cred_handle gss_cred_id_t, read, optional + The credential to which a credential-element + will be added. If GSS_C_NO_CREDENTIAL is + specified, the routine will create the new + credential based on default behavior (see + description above). Note that, while the + credential-handle is not modified by + gss_add_cred(), the underlying credential + will be modified if output_credential_handle + is NULL. + + desired_name gss_name_t, read. + Name of principal whose credential + should be acquired. + + desired_mech Object ID, read + Underlying security mechanism with which the + credential may be used. + + cred_usage gss_cred_usage_t, read + GSS_C_BOTH - Credential may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credential will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credential will only be used to + accept security contexts. + + initiator_time_req Integer, read, optional + number of seconds that the credential + should remain valid for initiating security + contexts. This argument is ignored if the + created credentials are of type GSS_C_ACCEPT. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + acceptor_time_req Integer, read, optional + number of seconds that the credential + should remain valid for accepting security + contexts. This argument is ignored if the + created credentials are of type GSS_C_INITIATE. + Specify GSS_C_INDEFINITE to request that the + credentials have the maximum permitted initiator + lifetime. + + + + + Wray Document Expiration: 1 September 1997 [Page 35] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + output_cred_handle gss_cred_id_t, modify, optional + The returned credential handle, containing + the new credential-element and all the + credential-elements from input_cred_handle. + If a valid pointer to a gss_cred_id_t is + supplied for this parameter, gss_add_cred + creates a new credential handle containing all + credential-elements from the input_cred_handle + and the newly acquired credential-element; if + NULL is specified for this parameter, the newly + acquired credential-element will be added + to the credential identified by input_cred_handle. + The resources associated with any credential + handle returned via this parameter must be + released by the application after use with a + call to gss_release_cred(). + + actual_mechs Set of Object IDs, modify, optional + The complete set of mechanisms for which + the new credential is valid. Storage for + the returned OID-set must be freed by the + application after use with a call to + gss_release_oid_set(). Specify NULL if + not required. + + initiator_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + initiating contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + acceptor_time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid for + accepting security contexts using the specified + mechanism. If the implementation or mechanism + does not support expiration of credentials, the + value GSS_C_INDEFINITE will be returned. Specify + NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not + supported + + + + + Wray Document Expiration: 1 September 1997 [Page 36] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- + formed. + + GSS_S_DUPLICATE_ELEMENT The credential already contains an element for + the requested mechanism with overlapping usage and + validity period. + + GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added + because they have expired. + + GSS_S_NO_CRED No credentials were found for the specified name. + + + + + + + + 7.4. gss_add_oid_set_member + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member_oid, + gss_OID_set * oid_set) + + Purpose: + + Add an Object Identifier to an Object Identifier set. This routine is + intended for use in conjunction with gss_create_empty_oid_set when + constructing a set of mechanism OIDs for input to gss_acquire_cred. + + The oid_set parameter must refer to an OID-set that was created by + GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI + creates a copy of the member_oid and inserts this copy into the set, + expanding the storage allocated to the OID-set's elements array if + necessary. The routine may add the new member OID anywhere within the + elements array, and implementations should verify that the new + member_oid is not already contained within the elements array. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member_oid Object ID, read + The object identifier to copied into + the set. + + oid_set Set of Object ID, modify + The set in which the object identifier + should be inserted. + + + + Wray Document Expiration: 1 September 1997 [Page 37] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.5. gss_canonicalize_name + + OM_uint32 gss_canonicalize_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + const gss_OID mech_type, + gss_name_t * output_name) + + Purpose: + + Generate a canonical mechanism name (MN) from an arbitrary internal + name. The mechanism name is the name that would be returned to a + context acceptor on successful authentication of a context where the + initiator used the input_name in a successful call to gss_acquire_cred, + specifying an OID set containing <mech_type> as its only member, + followed by a call to gss_init_sec_context, specifying <mech_type> as + the authentication mechanism. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The name for which a canonical form is + desired + + mech_type Object ID, read + The authentication mechanism for which the + canonical form of the name is desired. The + desired mechanism must be specified explicitly; + no default is provided. + + output_name gss_name_t, modify + The resultant canonical name. Storage + associated with this name must be freed by + the application after use with a call to + gss_release_name(). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 38] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion. + + GSS_S_BAD_MECH The identified mechanism is not supported. + + GSS_S_BAD_NAMETYPE The provided internal name contains no elements that + could be processed by the sepcified mechanism. + + GSS_S_BAD_NAME The provided internal name was ill-formed. + + + + + + + + 7.6. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + const gss_name_t name1, + const gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + If either name presented to gss_compare_name denotes an anonymous + principal, the routines should indicate that the two names do not refer + to the same identity. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + non-zero - names refer to same entity + zero - names refer to different entities + (strictly, the names are not known + to refer to the same identity). + + Function value: GSS status code + + + + + Wray Document Expiration: 1 September 1997 [Page 39] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The two names were of incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + + + + 7.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec Integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 40] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.8. gss_create_empty_oid_set + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * oid_set) + + Purpose: + + Create an object-identifier set containing no object identifiers, to + which members may be subsequently added using the + gss_add_oid_set_member() routine. These routines are intended to be + used to construct sets of mechanism object identifiers, for input to + gss_acquire_cred. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + oid_set Set of Object IDs, modify + The empty object identifier set. + The routine will allocate the + gss_OID_set_desc object, which the + application must free after use with + a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.9. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the local + data structures associated with the specified security context, and may + generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. If no token + is required by the mechanism, the GSS-API should set the length field of + the output_token (if provided) to zero. No further security services + + + + Wray Document Expiration: 1 September 1997 [Page 41] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + may be obtained using the context specified by context_handle. + + In addition to deleting established security contexts, + gss_delete_sec_context must also be able to delete "half-built" security + contexts resulting from an incomplete sequence of + gss_init_sec_context()/gss_accept_sec_context() calls. + + The output_token parameter is retained for compatibility with version 1 + of the GSS-API. It is recommended that both peer applications invoke + gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the + output_token parameter, indicating that no token is required, and that + gss_delete_sec_context should simply delete local context data + structures. If the application does pass a valid buffer to + gss_delete_sec_context, mechanisms are encouraged to return a zero- + length token, indicating that no peer action is necessary, and that no + token should be transferred by the application. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + After deleting the context, the GSSAPI will set + this context handle to GSS_C_NO_CONTEXT. + + output_token buffer, opaque, modify, optional + token to be sent to remote application to + instruct it to also delete the context. It + is recommended that applications specify + GSS_C_NO_BUFFER for this parameter, requesting + local deletion only. If a buffer parameter is + provided by the application, the mechanism may + return a token in it; mechanisms that implement + only local deletion should set the length field of + this token to zero to indicate to the application + that no token is to be sent to the peer. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT No valid context was supplied + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 42] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.10. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSS-API implementation. + + If input_name denotes an anonymous principal, the implementation should + return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and + a textual name that is syntactically distinct from all valid supported + printable names in output_name_buffer. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string. + The application must free storage associated + with this name after use with a call to + gss_release_buffer(). + + output_name_type Object ID, modify, optional + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + (in particular, it does not need to be freed). + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME input_name was ill-formed + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 43] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.11. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + OM_uint32 status_value, + int status_type, + const gss_OID mech_type, + OM_uint32 * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSS-API + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple conditions, applications may + need to call gss_display_status multiple times, each call generating a + single text string. The message_context parameter is used by + gss_acquire_cred to store state information about which error messages + have already been extracted from a given status_value; message_context + must be initialized to 0 by the application prior to the first call, and + gss_display_status will return a non-zero value in this parameter if + there are further messages to extract. The message_context parameter + contains all state information required by gss_display_status in order + to extract further messages from the status_value; even when a non-zero + value is returned in this parameter, the application is not required to + call gss_display_status again unless subsequent messages are desired. + The following code extracts all messages from a given status code and + prints them to stderr: + + + OM_uint32 message_context; + OM_uint32 status_code; + OM_uint32 maj_status; + OM_uint32 min_status; + gss_buffer_desc status_string; + + ... + + message_context = 0; + + do { + + maj_status = gss_display_status (&min_status, + status_code, + GSS_C_GSS_CODE, + GSS_C_NO_OID, + &message_context, + &status_string) + + fprintf(stderr, + "%.*s\n", + + + + Wray Document Expiration: 1 September 1997 [Page 44] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + status_string.length, + status_string.value); + + gss_release_buffer(&min_status, + &status_string); + + } while (message_context != 0); + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + status_value Integer, read + Status value to be converted + + status_type Integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NO_OID to + obtain the system default. + + message_context Integer, read/modify + Should be initialized to zero by the + application prior to the first call. + On return from gss_display_status(), + a non-zero status_value parameter indicates + that additional messages may be extracted + from the status code via subsequent calls + to gss_display_status(), passing the same + status_value, status_type, mech_type, and + message_context parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value. + Storage associated with this parameter must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + Wray Document Expiration: 1 September 1997 [Page 45] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_BAD_MECH Indicates that translation in accordance with an + unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the status + type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE. + + + + + + + + 7.12. gss_duplicate_name + + OM_uint32 gss_duplicate_name ( + OM_uint32 * minor_status, + const gss_name_t src_name, + gss_name_t * dest_name) + + Purpose: + + Create an exact duplicate of the existing internal name src_name. The + new dest_name will be independent of src_name (i.e. src_name and + dest_name must both be released, and the release of one shall not affect + the validity of the other). + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + src_name gss_name_t, read + internal name to be duplicated. + + dest_name gss_name_t, modify + The resultant copy of <src_name>. + Storage associated with this name must + be freed by the application after use + with a call to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The src_name parameter was ill-formed. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 46] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.13. gss_export_name + + OM_uint32 gss_export_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_buffer_t exported_name) + + Purpose: + + To produce a canonical contiguous string representation of a mechanism + name (MN), suitable for direct comparison (e.g. with memcmp) for use in + authorization functions (e.g. matching entries in an access-control + list). + + The <input_name> parameter must specify a valid MN (i.e. an internal + name generated by gss_accept_sec_context or by gss_canonicalize_name). + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name gss_name_t, read + The MN to be exported + + exported_name gss_buffer_t, octet-string, modify + The canonical contiguous string form of + <input_name>. Storage associated with + this string must freed by the application + after use with gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name. + + GSS_S_BAD_NAME The provide internal name was ill-formed. + + GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the + GSSAPI implementation. + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 47] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.14. gss_export_sec_context + + OM_uint32 gss_export_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t interprocess_token) + + Purpose: + + Provided to support the sharing of work between multiple processes. + This routine will typically be used by the context-acceptor, in an + application where a single process receives incoming connection requests + and accepts security contexts over them, then passes the established + context to one or more other processes for message exchange. + gss_export_sec_context() deactivates the security context for the + calling process and creates an interprocess token which, when passed to + gss_import_sec_context in another process, will re-activate the context + in the second process. Only a single instantiation of a given context + may be active at any one time; a subsequent attempt by a context + exporter to access the exported security context will fail. + + The implementation may constrain the set of processes by which the + interprocess token may be imported, either as a function of local + security policy, or as a result of implementation decisions. For + example, some implementations may constrain contexts to be passed only + between processes that run under the same account, or which are part of + the same process group. + + The interprocess token may contain security-sensitive information (for + example cryptographic keys). While mechanisms are encouraged to either + avoid placing such sensitive information within interprocess tokens, or + to encrypt the token before returning it to the application, in a + typical object-library GSSAPI implementation this may not be possible. + Thus the application must take care to protect the interprocess token, + and ensure that any process to which the token is transferred is + trustworthy. + + If creation of the interprocess token is succesful, the implementation + shall deallocate all process-wide resources associated with the security + context, and set the context_handle to GSS_C_NO_CONTEXT. In the event + of an error that makes it impossible to complete the export of the + security context, the implementation must not return an interprocess + token, and should strive to leave the security context referenced by the + context_handle parameter untouched. If this is impossible, it is + permissible for the implementation to delete the security context, + providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + + + Wray Document Expiration: 1 September 1997 [Page 48] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + context_handle gss_ctx_id_t, modify + context handle identifying the context to transfer. + + interprocess_token buffer, opaque, modify + token to be transferred to target process. + Storage associated with this token must be + freed by the application after use with a + call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has expired + + GSS_S_NO_CONTEXT The context was invalid + + GSS_S_UNAVAILABLE The operation is not supported. + + + + + + + + 7.15. gss_get_mic + + OM_uint32 gss_get_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_qop_t qop_req, + const gss_buffer_t message_buffer, + gss_buffer_t msg_token) + + Purpose: + + Generates a cryptographic MIC for the supplied message, and places the + MIC in a token for transfer to the peer application. The qop_req + parameter allows a choice between several cryptographic algorithms, if + supported by the chosen mechanism. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + + + + Wray Document Expiration: 1 September 1997 [Page 49] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_req gss_qop_t, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_get_mic will return a + major_status of GSS_S_BAD_QOP. + + message_buffer buffer, opaque, read + message to be protected + + msg_token buffer, opaque, modify + buffer to receive token. The application must + free storage associated with this buffer after + use with a call to gss_release_buffer(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + const gss_buffer_t input_name_buffer, + const gss_OID input_name_type, + gss_name_t * output_name) + + Purpose: + + Convert a contiguous string name to internal form. In general, the + internal name returned (via the <output_name> parameter) will not be an + MN; the exception to this is if the <input_name_type> indicates that the + contiguous string provided via the <input_name_buffer> parameter is of + type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will + be an MN for the mechanism that exported the name. + + + + + Wray Document Expiration: 1 September 1997 [Page 50] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + input_name_buffer buffer, octet-string, read + buffer containing contiguous string name to convert + + input_name_type Object ID, read, optional + Object ID specifying type of printable + name. Applications may specify either + GSS_C_NO_OID to use a mechanism-specific + default printable syntax, or an OID registered + by the GSS-API implementation to name a + specific namespace. + + output_name gss_name_t, modify + returned name in internal form. Storage + associated with this name must be freed + by the application after use with a call + to gss_release_name(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be interpreted as a + name of the specified type + + + + + + + + + 7.17. gss_import_sec_context + + OM_uint32 gss_import_sec_context ( + OM_uint32 * minor_status, + const gss_buffer_t interprocess_token, + gss_ctx_id_t * context_handle) + + Purpose: + + Allows a process to import a security context established by another + process. A given interprocess token may be imported only once. See + gss_export_sec_context. + + + + + Wray Document Expiration: 1 September 1997 [Page 51] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + interprocess_token buffer, opaque, modify + token received from exporting process + + context_handle gss_ctx_id_t, modify + context handle of newly reactivated context. + Resources associated with this context handle + must be released by the application after use + with a call to gss_delete_sec_context(). + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion. + + GSS_S_NO_CONTEXT The token did not contain a valid context reference. + + GSS_S_DEFECTIVE_TOKEN The token was invalid. + + GSS_S_UNAVAILABLE The operation is unavailable. + + GSS_S_UNAUTHORIZED Local policy prevents the import of this context by + the current process.. + + + + + + + + 7.18. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security mechanisms + are available. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + + + + Wray Document Expiration: 1 September 1997 [Page 52] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + dynamically-allocated OID set, that should + be released by the caller after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.19. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + const gss_cred_id_t initiator_cred_handle, + gss_ctx_id_t * context_handle, + const gss_name_t target_name, + const gss_OID mech_type, + OM_uint32 req_flags, + OM_uint32 time_req, + const gss_channel_bindings_t + input_chan_bindings, + const gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + OM_uint32 * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified either as GSS_C_NO_BUFFER, or as a pointer to a + gss_buffer_desc object whose length field contains the value zero. The + routine may return a output_token which should be transferred to the + peer application, where the peer application will present it to + gss_accept_sec_context. If no token need be sent, gss_init_sec_context + will indicate this by setting the length field of the output_token + argument to zero. To complete the context establishment, one or more + reply tokens may be required from the peer application; if so, + gss_init_sec_context will return a status containing the supplementary + information bit GSS_S_CONTINUE_NEEDED. In this case, + gss_init_sec_context should be called again when the reply token is + received from the peer application, passing the reply token to + gss_init_sec_context via the input_token parameters. + + + + Wray Document Expiration: 1 September 1997 [Page 53] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Portable applications should be constructed to use the token length and + return status to determine whether a token needs to be sent or waited + for. Thus a typical portable caller should always invoke + gss_init_sec_context within a loop: + + int context_established = 0; + gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; + ... + input_token->length = 0; + + while (!context_established) { + maj_stat = gss_init_sec_context(&min_stat, + cred_hdl, + &context_hdl, + target_name, + desired_mech, + desired_services, + desired_time, + input_bindings, + input_token, + &actual_mech, + output_token, + &actual_services, + &actual_time); + if (GSS_ERROR(maj_stat)) { + report_error(maj_stat, min_stat); + }; + if (output_token->length != 0) { + send_token_to_peer(output_token); + gss_release_buffer(&min_stat, + output_token) + }; + if (GSS_ERROR(maj_stat)) { + if (context_hdl != GSS_C_NO_CONTEXT) + gss_delete_sec_context(&min_stat, + &context_hdl, + GSS_C_NO_BUFFER); + break; + }; + if (maj_stat & GSS_S_CONTINUE_NEEDED) { + receive_token_from_peer(input_token); + } else { + context_established = 1; + }; + }; + + Whenever the routine returns a major status that includes the value + GSS_S_CONTINUE_NEEDED, the context is not fully established and the + following restrictions apply to the output parameters: + + + + + + Wray Document Expiration: 1 September 1997 [Page 54] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + (a) The value returned via the time_rec parameter is undefined + + (b) Unless the accompanying ret_flags parameter contains the bit + GSS_C_PROT_READY_FLAG, indicating that per-message services may be + applied in advance of a successful completion status, the value + returned via the actual_mech_type parameter is undefined until the + routine returns a major status value of GSS_S_COMPLETE. + + (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, + GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the + ret_flags parameter should contain the values that the + implementation expects would be valid if context establishment + were to succeed. In particular, if the application has requested + a service such as delegation or anonymous authentication via the + req_flags argument, and such a service is unavailable from the + underlying mechanism, gss_init_sec_context should generate a token + that will not provide the service, and indicate via the ret_flags + argument that the service will not be supported. The application + may choose to abort the context establishment by calling + gss_delete_sec_context (if it cannot continue in the absence of + the service), or it may choose to transmit the token and continue + context establishment (if the service was merely desired but not + mandatory). + + The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits + within ret_flags should indicate the actual state at the time + gss_init_sec_context returns, whether or not the context is fully + established. + + Although this requires that GSSAPI implementations set the + GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller + (i.e. when accompanied by a GSS_S_COMPLETE status code), + applications should not rely on this behavior as the flag was not + defined in Version 1 of the GSSAPI. Instead, applications should + be prepared to use per-message services after a successful context + establishment, according to the GSS_C_INTEG_FLAG and + GSS_C_CONF_FLAG values. + + All other bits within the ret_flags argument should be set to + zero. + + If the initial call of gss_init_sec_context() fails, the implementation + should not create a context object, and should leave the value of the + context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In + the event of a failure on a subsequent call, the implementation is + permitted to delete the "half-built" security context (in which case it + should set the context_handle parameter to GSS_C_NO_CONTEXT), but the + preferred behavior is to leave the security context untouched for the + application to delete (using gss_delete_sec_context). + + + + + Wray Document Expiration: 1 September 1997 [Page 55] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + initiator_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to act as a default + initiator principal. If no default + initiator is defined, the function will + return GSS_S_NO_CRED. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + Resources associated with this context-handle + must be released by the application after use + with a call to gee_delete_sec_context(). + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NO_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains various independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for + messages protected with gss_wrap + or gss_get_mic + False - Don't attempt to detect + replayed messages + + + Wray Document Expiration: 1 September 1997 [Page 56] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + protected messages + False - Don't attempt to detect + out-of-sequence messages + GSS_C_ANON_FLAG + True - Do not reveal the initiator's + identity to the acceptor. + False - Authenticate normally. + + time_req Integer, read, optional + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read, optional + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. Specify GSS_C_NO_CHANNEL_BINDINGS + if channel bindings are not used. + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER, or a pointer to + a buffer containing the value GSS_C_EMPTY_BUFFER + on initial call. + + actual_mech_type OID, modify, optional + Actual mechanism used. The OID returned via + this parameter will be a pointer to static + storage that should be treated as read-only; + In particular the application should not attempt + to free it. Specify NULL if not required. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. Storage associated with this + buffer must be freed by the application + after use with a call to gss_release_buffer(). + + ret_flags bit-mask, modify, optional + Contains various independent flags, each of which + indicates that the context supports a specific + service option. Specify NULL if not + required. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + + + + Wray Document Expiration: 1 September 1997 [Page 57] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will + not be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity has not been + revealed, and will not be revealed if + any emitted token is passed to the + acceptor. + False - The initiator's identity has been or + will be authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available for + use if the accompanying major status + return value is either GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED. + + + + Wray Document Expiration: 1 September 1997 [Page 58] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the accompanying major status + return value is GSS_S_COMPLETE. + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + All other bits should be set to zero. + + time_rec Integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application + is required to complete the context, and that + gss_init_sec_context must be called again with that + token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed + on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not reference + any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel bindings + to those specified via the input_chan_bindings + parameter + + GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that + could not be verified + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + + + + Wray Document Expiration: 1 September 1997 [Page 59] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a + token already processed. This is a fatal error during + context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_BAD_MECH The specified mechanism is not supported by the + provided credential, or is unrecognized by the + implementation. + + + + + + + + 7.20. gss_inquire_context + + OM_uint32 gss_inquire_context ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + gss_name_t * src_name, + gss_name_t * targ_name, + OM_uint32 * lifetime_rec, + gss_OID * mech_type, + OM_uint32 * ctx_flags, + int * locally_initiated, + int * open ) + + Purpose: + + Obtains information about a security context. The caller must already + have obtained a handle that refers to the context, although the context + need not be fully established. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security context. + + src_name gss_name_t, modify, optional + The name of the context initiator. + + + + Wray Document Expiration: 1 September 1997 [Page 60] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + If the context was established using anonymous + authentication, and if the application invoking + gss_inquire_context is the context acceptor, + an anonymous name will be returned. Storage + associated with this name must be freed by the + application after use with a call to + gss_release_name(). Specify NULL if not + required. + + targ_name gss_name_t, modify, optional + The name of the context acceptor. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + Specify NULL if not required. + + lifetime_rec Integer, modify, optional + The number of seconds for which the context + will remain valid. If the context has + expired, this parameter will be set to zero. + If the implementation does not support + context expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + mech_type gss_OID, modify, optional + The security mechanism providing the + context. The returned OID will be a + pointer to static storage that should + be treated as read-only by the application; + in particular the application should not + attempt to free it. Specify NULL if not + required. + + ctx_flags bit-mask, modify, optional + Contains various independent flags, each of + which indicates that the context supports + (or is expected to support, if ctx_open is + false) a specific service option. If not + needed, specify NULL. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated from + the initiator to the acceptor. + False - No credentials were delegated + + + + Wray Document Expiration: 1 September 1997 [Page 61] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + GSS_C_MUTUAL_FLAG + True - The acceptor was authenticated + to the initiator + False - The acceptor did not authenticate + itself. + GSS_C_REPLAY_FLAG + True - replay of protected messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence protected + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be invoked + by calling gss_wrap routine + False - No confidentiality service (via + gss_wrap) available. gss_wrap will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_get_mic or gss_wrap + routines. + False - Per-message integrity service + unavailable. + GSS_C_ANON_FLAG + True - The initiator's identity will not + be revealed to the acceptor. + The src_name parameter (if + requested) contains an anonymous + internal name. + False - The initiator has been + authenticated normally. + GSS_C_PROT_READY_FLAG + True - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + for use. + False - Protection services (as specified + by the states of the GSS_C_CONF_FLAG + and GSS_C_INTEG_FLAG) are available + only if the context is fully + established (i.e. if the open parameter + is non-zero). + GSS_C_TRANS_FLAG + True - The resultant security context may + be transferred to other processes via + a call to gss_export_sec_context(). + False - The security context is not + transferrable. + + Wray Document Expiration: 1 September 1997 [Page 62] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + + locally_initiated Boolean, modify + Non-zero if the invoking application is the + context initiator. + Specify NULL if not required. + + open Boolean, modify + Non-zero if the context is fully established; + Zero if a context-establishment token + is expected from the peer application. + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. If the lifetime_rec + parameter was requested, it will be set to 0. + + + + + + + + 7.21. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + gss_cred_usage_t * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + + Wray Document Expiration: 1 September 1997 [Page 63] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name should be freed + by the application after use with a call to + gss_release_name(). Specify NULL if not required. + + lifetime Integer, modify, optional + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify, optional + Set of mechanisms supported by the credential. + Storage associated with this OID set must be + freed by the application after use with a call + to gss_release_oid_set(). Specify NULL if not + required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 64] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.22. gss_inquire_cred_by_mech + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 * minor_status, + const gss_cred_id_t cred_handle, + const gss_OID mech_type, + gss_name_t * name, + OM_uint32 * initiator_lifetime, + OM_uint32 * acceptor_lifetime, + gss_cred_usage_t * cred_usage ) + + Purpose: + + Obtains per-mechanism information about a credential. The caller must + already have obtained a handle that refers to the credential. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default initiator principal. + + mech_type gss_OID, read + The mechanism for which information should be + returned. + + name gss_name_t, modify, optional + The name whose identity the credential asserts. + Storage associated with this name must be + freed by the application after use with a call + to gss_release_name(). Specify NULL if not + required. + + initiator_lifetime Integer, modify, optional + The number of seconds for which the credential + will remain capable of initiating security contexts + under the specified mechanism. If the credential + can no longer be used to initiate contexts, or if + the credential usage for this mechanism is + GSS_C_ACCEPT, + this parameter will be set to zero. If the + implementation does not support expiration of + initiator credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + acceptor_lifetime Integer, modify, optional + The number of seconds for which the credential + + + + Wray Document Expiration: 1 September 1997 [Page 65] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + will remain capable of accepting security contexts + under the specified mechanism. If the credential + can no longer be used to accept contexts, or if + the credential usage for this mechanism is + GSS_C_INITIATE, this parameter will be set to zero. + If the implementation does not support expiration + of acceptor credentials, the value GSS_C_INDEFINITE + will be returned. Specify NULL if not required. + + cred_usage gss_cred_usage_t, modify, optional + How the credential may be used with the specified + mechanism. One of the following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If + the lifetime parameter was not passed as NULL, it will + be set to 0. + + + + + + + + 7.23. gss_inquire_mechs_for_name + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 * minor_status, + const gss_name_t input_name, + gss_OID_set * mech_types ) + + Purpose: + + Returns the set of mechanisms supported by the GSSAPI implementation + that may be able to process the specified name. + + Each mechanism returned will recognize at least one element within the + name. It is permissible for this routine to be implemented within a + mechanism-independent GSSAPI layer, using the type information contained + within the presented name, and based on registration information + + + + Wray Document Expiration: 1 September 1997 [Page 66] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + provided by individual mechanism implementations. This means that the + returned mech_types set may indicate that a particular mechanism will + understand the name when in fact it would refuse to accept the name as + input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred + or gss_add_cred (due to some property of the specific name, as opposed + to the name type). Thus this routine should be used only as a pre- + filter for a call to a subsequent mechanism-specific routine. + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + input_name gss_name_t, read + The name to which the inquiry relates. + + mech_types gss_OID_set, modify + Set of mechanisms that may support the + specified name. The returned OID set + must be freed by the caller after use + with a call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The input_name parameter was ill-formed. + + GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or + unsupported type of name + + + + + + + 7.24. gss_inquire_names_for_mech + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 * minor_status, + const gss_OID mechanism, + gss_OID_set * name_types) + + Purpose: + + Returns the set of nametypes supported by the specified mechanism. + + + + + + + Wray Document Expiration: 1 September 1997 [Page 67] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + mechanism gss_OID, read + The mechanism to be interrogated. + + name_types gss_OID_set, modify + Set of name-types supported by the specified + mechanism. The returned OID set must be + freed by the application after use with a + call to gss_release_oid_set(). + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.25. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Used with + tokens emitted by gss_delete_sec_context. Note that mechanisms are + encouraged to perform local deletion, and not emit tokens from + gss_delete_sec_context. This routine, therefore, is primarily for + backwards compatibility with V1 applications. + + Parameters: + + minor_status Integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + token to process + + + + + Wray Document Expiration: 1 September 1997 [Page 68] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the + token failed + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid context + + + + + + + + 7.26. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer. The storage must have been + allocated by a GSS-API routine. In addition to freeing the associated + storage, the routine will zero the length field in the descriptor to + which the buffer parameter refers. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 69] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.27. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSS-API that the specified credential handle is no longer + required by the application, and frees associated resources. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + Opaque handle identifying credential + to be released. If GSS_C_NO_CREDENTIAL + is supplied, the routine will complete + successfully, but will do nothing. + + minor_status Integer, modify + Mechanism specific status code. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + 7.28. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage by associated with an internal-form name. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + name gss_name_t, modify + The name to be deleted + + + + Wray Document Expiration: 1 September 1997 [Page 70] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + + + + + + + + 7.29. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + Free storage associated with a GSSAPI-generated gss_OID_set object. The + set parameter must refer to an OID-set that was returned from a GSSAPI + routine. gss_release_oid_set() will free the storage associated with + each individual member OID, the OID set's elements array, and the + gss_OID_set_desc. + + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 71] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + 7.30. gss_test_oid_set_member + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 * minor_status, + const gss_OID member, + const gss_OID_set set, + int * present) + + Purpose: + + Interrogate an Object Identifier set to determine whether a specified + Object Identifier is a member. This routine is intended to be used with + OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and + gss_inquire_cred(), but will also work with user-generated sets. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + member Object ID, read + The object identifier whose presence + is to be tested. + + set Set of Object ID, read + The Object Identifier set. + + present Boolean, modify + non-zero if the specified OID is a member + of the set, zero if not. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + + + + + + + 7.31. gss_unwrap + + OM_uint32 gss_unwrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + gss_qop_t * qop_state) + + + + + Wray Document Expiration: 1 September 1997 [Page 72] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Converts a message previously protected by gss_wrap back to a usable + form, verifying the embedded MIC. The conf_state parameter indicates + whether the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality and + integrity services. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + protected message + + output_message_buffer buffer, opaque, modify + Buffer to receive unwrapped message. + Storage associated with this buffer must + be freed by the application after use use + with a call to gss_release_buffer(). + + conf_state boolean, modify, optional + Non-zero - Confidentiality and integrity protection + were used + Zero - Integrity service only was used + Specify NULL if not required + + qop_state gss_qop_t, modify, optional + Quality of protection gained from MIC. + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + + + + Wray Document Expiration: 1 September 1997 [Page 73] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.32. gss_verify_mic + + OM_uint32 gss_verify_mic ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + const gss_buffer_t message_buffer, + const gss_buffer_t token_buffer, + gss_qop_t * qop_state) + + Purpose: + + Verifies that a cryptographic MIC, contained in the token parameter, + fits the supplied message. The qop_state parameter allows a message + recipient to determine the strength of protection that was applied to + the message. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + Message to be verified + + token_buffer buffer, opaque, read + Token associated with message + + + + + Wray Document Expiration: 1 September 1997 [Page 74] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + qop_state gss_qop_t, modify, optional + quality of protection gained from MIC + Specify NULL if not required + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The MIC was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC + for the message, but it had already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for + the message, but it is too old to check for + duplication. + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; a + later token has already been received. + + GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for + the message, but has been verified out of sequence; + an earlier expected token has not yet been received. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + + + + + + + 7.33. gss_wrap + + OM_uint32 gss_wrap ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req + const gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer ) + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 75] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + Purpose: + + Attaches a cryptographic MIC and optionally encrypts the specified + input_message. The output_message contains both the MIC and the + message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Since some application-level protocols may wish to use tokens emitted by + gss_wrap() to provide "secure framing", implementations should support + the wrapping of zero-length messages. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context on which the message + will be sent + + conf_req_flag boolean, read + Non-zero - Both confidentiality and integrity + services are requested + Zero - Only integrity service is requested + + qop_req gss_qop_t, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_wrap will return a major_status of + GSS_S_BAD_QOP. + + input_message_buffer buffer, opaque, read + Message to be protected + + conf_state boolean, modify, optional + Non-zero - Confidentiality, data origin + authentication and integrity + services have been applied + Zero - Integrity and data origin services only + has been applied. + Specify NULL if not required + + output_message_buffer buffer, opaque, modify + Buffer to receive protected message. + Storage associated with this message must + be freed by the application after use with + a call to gss_release_buffer(). + + Function value: GSS status code + + + + Wray Document Expiration: 1 September 1997 [Page 76] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid + context + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + 7.34. gss_wrap_size_limit + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 * minor_status, + const gss_ctx_id_t context_handle, + int conf_req_flag, + gss_qop_t qop_req, + OM_uint32 req_output_size, + OM_uint32 * max_input_size) + + Purpose: + + Allows an application to determine the maximum message size that, if + presented to gss_wrap with the same conf_req_flag and qop_req + parameters, will result in an output token containing no more than + req_output_size bytes. + + This call is intended for use by applications that communicate over + protocols that impose a maximum message size. It enables the + application to fragment messages prior to applying protection. + + Successful completion of this call does not guarantee that gss_wrap will + be able to protect a message of length max_input_size bytes, since this + ability may depend on the availability of system resources at the time + that gss_wrap is called. However, if the implementation itself imposes + an upper limit on the length of messages that may be processed by + gss_wrap, the implementation should not return a value via + max_input_bytes that is greater than this length. + + Parameters: + + minor_status Integer, modify + Mechanism specific status code + + context_handle gss_ctx_id_t, read + A handle that refers to the security over + + + + Wray Document Expiration: 1 September 1997 [Page 77] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + which the messages will be sent. + + conf_req_flag Boolean, read + Indicates whether gss_wrap will be asked + to apply confidentiality protection in + addition to integrity protection. See + the routine description for gss_wrap + for more details. + + qop_req gss_qop_t, read + Indicates the level of protection that + gss_wrap will be asked to provide. See + the routine description for gss_wrap for + more details. + + req_output_size Integer, read + The desired maximum size for tokens emitted + by gss_wrap. + + max_input_size Integer, modify + The maximum input message size that may + be presented to gss_wrap in order to + guarantee that the emitted token shall + be no larger than req_output_size bytes. + + Function value: GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CONTEXT The referenced context could not be accessed. + + GSS_S_CONTEXT_EXPIRED The context has expired. + + GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. + + + + + + + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 78] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX A. GSS-API C header file gssapi.h + + C-language GSS-API implementations should include a copy of the + following header-file. + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + + + /* + * First, include stddef.h to get size_t defined. + */ + #include <stddef.h> + + /* + * If the platform supports the xom.h header file, it should be + * included here. + */ + #include <xom.h> + + + + /* + * Now define the three implementation-dependent types. + */ + typedef <platform-specific> gss_ctx_id_t; + typedef <platform-specific> gss_cred_id_t; + typedef <platform-specific> gss_name_t; + + /* + * The following type must be defined as the smallest natural + * unsigned integer supported by the platform that has at least + * 32 bits of precision. + */ + typedef <platform-specific> gss_uint32; + + + #ifdef OM_STRING + /* + * We have included the xom.h header file. Verify that OM_uint32 + * is defined correctly. + */ + + #if sizeof(gss_uint32) != sizeof(OM_uint32) + #error Incompatible definition of OM_uint32 from xom.h + #endif + + typedef OM_object_identifier gss_OID_desc, *gss_OID; + + #else + + + + Wray Document Expiration: 1 September 1997 [Page 79] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * We can't use X/Open definitions, so roll our own. + */ + + typedef gss_uint32 OM_uint32; + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + #endif + + typedef struct gss_OID_set_desc_struct { + size_t count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * For now, define a QOP-type as an OM_uint32 + */ + typedef OM_uint32 gss_qop_t; + + typedef int gss_cred_usage_t; + + /* + * Flag bits for context-level services. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + #define GSS_C_ANON_FLAG 64 + #define GSS_C_PROT_READY_FLAG 128 + #define GSS_C_TRANS_FLAG 256 + + + + Wray Document Expiration: 1 September 1997 [Page 80] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0 + #define GSS_C_AF_LOCAL 1 + #define GSS_C_AF_INET 2 + #define GSS_C_AF_IMPLINK 3 + #define GSS_C_AF_PUP 4 + #define GSS_C_AF_CHAOS 5 + #define GSS_C_AF_NS 6 + #define GSS_C_AF_NBS 7 + #define GSS_C_AF_ECMA 8 + #define GSS_C_AF_DATAKIT 9 + #define GSS_C_AF_CCITT 10 + #define GSS_C_AF_SNA 11 + #define GSS_C_AF_DECnet 12 + #define GSS_C_AF_DLI 13 + #define GSS_C_AF_LAT 14 + #define GSS_C_AF_HYLINK 15 + #define GSS_C_AF_APPLETALK 16 + #define GSS_C_AF_BSC 17 + #define GSS_C_AF_DSS 18 + #define GSS_C_AF_OSI 19 + #define GSS_C_AF_X25 21 + + #define GSS_C_AF_NULLADDR 255 + + /* + * Various Null values + */ + #define GSS_C_NO_NAME ((gss_name_t) 0) + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NO_OID ((gss_OID) 0) + #define GSS_C_NO_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + + + Wray Document Expiration: 1 September 1997 [Page 81] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* + * Some alternate names for a couple of the above + * values. These are defined for V1 compatibility. + */ + #define GSS_C_NULL_OID GSS_C_NO_OID + #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero + * (as done here) to mean "default protection", or to a specific + * explicit QOP value. However, a value of 0 should always be + * interpreted by a GSSAPI implementation as a request for the + * default protection level. + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x01"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant + * GSS_C_NT_USER_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_USER_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x02"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. + * The constant GSS_C_NT_MACHINE_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_MACHINE_UID_NAME; + + /* + + + + Wray Document Expiration: 1 September 1997 [Page 82] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" + * "\x01\x02\x01\x03"}, + * corresponding to an object-identifier value of + * {iso(1) member-body(2) United States(840) mit(113554) + * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. + * The constant GSS_C_NT_STRING_UID_NAME should be + * initialized to point to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_STRING_UID_NAME; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 2(gss-host-based-services)}. The constant + * GSS_C_NT_HOSTBASED_SERVICE should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, + * corresponding to an object identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 3(gss-anonymous-name)}. The constant + * and GSS_C_NT_ANONYMOUS should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_ANONYMOUS; + + + + /* + * The implementation must reserve static storage for a + * gss_OID_desc object containing the value + * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, + * corresponding to an object-identifier value of + * {1(iso), 3(org), 6(dod), 1(internet), 5(security), + * 6(nametypes), 4(gss-api-exported-name)}. The constant + * GSS_C_NT_EXPORT_NAME should be initialized to point + * to that gss_OID_desc. + */ + extern gss_OID GSS_C_NT_EXPORT_NAME; + + + + + + Wray Document Expiration: 1 September 1997 [Page 83] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions. + * Note that the GSS_ERROR() macro has changed slightly from + * the V1 GSSAPI so that it now evaluates its argument + * only once. + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ + (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + + + + Wray Document Expiration: 1 September 1997 [Page 84] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_MIC GSS_S_BAD_SIG + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAUTHORIZED (15ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_UNAVAILABLE (16ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DUPLICATE_ELEMENT (17ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NAME_NOT_MN (18ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + #define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) + + + /* + * Finally, function prototypes for the GSS-API routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + const gss_OID_set, /* desired_mechs */ + gss_cred_usage_t, /* cred_usage */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_release_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t * /* cred_handle */ + ); + + OM_uint32 gss_init_sec_context + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* initiator_cred_handle */ + gss_ctx_id_t *, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 85] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* target_name */ + const gss_OID, /* mech_type */ + OM_uint32, /* req_flags */ + OM_uint32, /* time_req */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + const gss_buffer_t, /* input_token */ + gss_OID *, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + const gss_cred_id_t, /* acceptor_cred_handle */ + const gss_buffer_t, /* input_token_buffer */ + const gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t *, /* src_name */ + gss_OID *, /* mech_type */ + gss_buffer_t, /* output_token */ + OM_uint32 *, /* ret_flags */ + OM_uint32 *, /* time_rec */ + gss_cred_id_t * /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + OM_uint32 gss_context_time + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + OM_uint32 * /* time_rec */ + ); + + OM_uint32 gss_get_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* message_buffer */ + + + + Wray Document Expiration: 1 September 1997 [Page 86] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify_mic + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* message_buffer */ + const gss_buffer_t, /* token_buffer */ + gss_qop_t * /* qop_state */ + ); + + OM_uint32 gss_wrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + const gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unwrap + (OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + const gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + gss_qop_t * /* qop_state */ + ); + + + + OM_uint32 gss_display_status + (OM_uint32 *, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + const gss_OID, /* mech_type */ + OM_uint32 *, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* name1 */ + + + + Wray Document Expiration: 1 September 1997 [Page 87] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + const gss_name_t, /* name2 */ + int * /* name_equal */ + ); + + OM_uint32 gss_display_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID * /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* input_name_buffer */ + const gss_OID, /* input_name_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_export_name + (OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_buffer_t /* exported_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32 *, /* minor_status */ + gss_name_t * /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32 *, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32 *, /* minor_status */ + gss_OID_set * /* set */ + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + gss_cred_usage_t *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + OM_uint32 gss_inquire_context ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + + + + Wray Document Expiration: 1 September 1997 [Page 88] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + gss_name_t *, /* src_name */ + gss_name_t *, /* targ_name */ + OM_uint32 *, /* lifetime_rec */ + gss_OID *, /* mech_type */ + OM_uint32 *, /* ctx_flags */ + int *, /* locally_initiated */ + int * /* open */ + ); + + OM_uint32 gss_wrap_size_limit ( + OM_uint32 *, /* minor_status */ + const gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + gss_qop_t, /* qop_req */ + OM_uint32, /* req_output_size */ + OM_uint32 * /* max_input_size */ + ); + + + OM_uint32 gss_add_cred ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* input_cred_handle */ + const gss_name_t, /* desired_name */ + const gss_OID, /* desired_mech */ + gss_cred_usage_t, /* cred_usage */ + OM_uint32, /* initiator_time_req */ + OM_uint32, /* acceptor_time_req */ + gss_cred_id_t *, /* output_cred_handle */ + gss_OID_set *, /* actual_mechs */ + OM_uint32 *, /* initiator_time_rec */ + OM_uint32 * /* acceptor_time_rec */ + ); + + + OM_uint32 gss_inquire_cred_by_mech ( + OM_uint32 *, /* minor_status */ + const gss_cred_id_t, /* cred_handle */ + const gss_OID, /* mech_type */ + gss_name_t *, /* name */ + OM_uint32 *, /* initiator_lifetime */ + OM_uint32 *, /* acceptor_lifetime */ + gss_cred_usage_t * /* cred_usage */ + ); + + OM_uint32 gss_export_sec_context ( + OM_uint32 *, /* minor_status */ + gss_ctx_id_t *, /* context_handle */ + gss_buffer_t /* interprocess_token */ + ); + + OM_uint32 gss_import_sec_context ( + + + + Wray Document Expiration: 1 September 1997 [Page 89] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + OM_uint32 *, /* minor_status */ + const gss_buffer_t, /* interprocess_token */ + gss_ctx_id_t * /* context_handle */ + ); + + OM_uint32 gss_create_empty_oid_set ( + OM_uint32 *, /* minor_status */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_add_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member_oid */ + gss_OID_set * /* oid_set */ + ); + + OM_uint32 gss_test_oid_set_member ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* member */ + const gss_OID_set, /* set */ + int * /* present */ + ); + + OM_uint32 gss_inquire_names_for_mech ( + OM_uint32 *, /* minor_status */ + const gss_OID, /* mechanism */ + gss_OID_set * /* name_types */ + ); + + OM_uint32 gss_inquire_mechs_for_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + gss_OID_set * /* mech_types */ + ); + + OM_uint32 gss_canonicalize_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* input_name */ + const gss_OID, /* mech_type */ + gss_name_t * /* output_name */ + ); + + OM_uint32 gss_duplicate_name ( + OM_uint32 *, /* minor_status */ + const gss_name_t, /* src_name */ + gss_name_t * /* dest_name */ + ); + + /* + * The following routines are obsolete variants of gss_get_mic, + * gss_verify_mic, gss_wrap and gss_unwrap. They should be + + + + Wray Document Expiration: 1 September 1997 [Page 90] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + * provided by GSSAPI V2 implementations for backwards + * compatibility with V1 applications. Distinct entrypoints + * (as opposed to #defines) should be provided, both to allow + * GSSAPI V1 applications to link against GSSAPI V2 implementations, + * and to retain the slight parameter type differences between the + * obsolete versions of these routines and their current forms. + */ + + OM_uint32 gss_sign + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + + OM_uint32 gss_verify + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int * /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int *, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + + OM_uint32 gss_unseal + (OM_uint32 *, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int *, /* conf_state */ + int * /* qop_state */ + ); + + + + + #endif /* GSSAPI_H_ */ + + + + + + Wray Document Expiration: 1 September 1997 [Page 91] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + APPENDIX B. Additional constraints for application binary portability + + The purpose of this C-bindings document is to encourage source-level + portability of applications across GSS-API implementations on different + platforms and atop different mechanisms. Additional goals that have not + been explicitly addressed by this document are link-time and run-time + portability. + + Link-time portability provides the ability to compile an application + against one implementation of GSS-API, and then link it against a + different implementation on the same platform. It is a stricter + requirement than source-level portability. + + Run-time portability differs from link-time portability only on those + platforms that implement dynamically loadable GSS-API implementations, + but do not offer load-time symbol resolution. On such platforms, run- + time portability is a stricter requirement than link-time portability, + and will typically include the precise placement of the various GSS-API + routines within library entrypoint vectors. + + Individual platforms will impose their own rules that must be followed + to achieve link-time (and run-time, if different) portability. In order + to ensure either form of binary portability, an ABI specification must + be written for GSS-API implementations on that platform. However, it is + recognized that there are some issues that are likely to be common to + all such ABI specifications. This appendix is intended to be a + repository for such common issues, and contains some suggestions that + individual ABI specifications may choose to reference. Since machine + architectures vary greatly, it may not be possible or desirable to + follow these suggestions on all platforms. + + B.1. Pointers + + While ANSI-C provides a single pointer type for each declared type, plus + a single (void *) type, some platforms (notably those using segmented + memory architectures) augment this with various modified pointer types + (e.g. far pointers, near pointers). These language bindings assume + ANSI-C, and thus do not address such non-standard implementations. + GSS-API implementations for such platforms must choose an appropriate + memory model, and should use it consistently throughout. For example, + if a memory model is chosen that requires the use of far pointers when + passing routine parameters, then far pointers should also be used within + the structures defined by GSS-API. + + B.2. Internal structure alignment + + GSS-API defines several data-structures containing differently-sized + fields. An ABI specification should include a detailed description of + how the fields of such structures are aligned, and if there is any + internal padding in these data structures. The use of compiler defaults + for the platform is recommended. + + + + Wray Document Expiration: 1 September 1997 [Page 92] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + B.3. Handle types + + The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types + should be implemented as either pointer or arithmetic types, and that if + pointer types are used, care should be taken to ensure that two handles + may be compared with the == operator. Note that ANSI-C does not + guarantee that two pointer values may be compared with the == operator + unless either the two pointers point to members of a single array, or at + least one of the pointers contains a NULL value. + + For binary portability, additional constraints are required. The + following is an attempt at defining platform-independent constraints. + + (a) The size of the handle type must be the same as sizeof(void *), + using the appropriate memory model. + + (b) The == operator for the chosen type must be a simple bit-wise + comparison. That is, for two in-memory handle objects h1 and h2, + the boolean value of the expression + + (h1 == h2) + + should always be the same as the boolean value of the expression + + (memcmp(&h1, &h2, sizeof(h1)) == 0) + + (c) The actual use of the type (void *) for handle types is + discouraged, not for binary portability reasons, but since it + effectively disables much of the compile-time type-checking that + the compiler can otherwise perform, and is therefore not + "programmer-friendly". If a pointer implementation is desired, + and if the platform's implementation of pointers permits, the + handles should be implemented as pointers to distinct + implementation-defined types. + + B.4. The gss_name_t type + + The gss_name_t type, representing the internal name object, should be + implemented as a pointer type. The use of the (void *) type is + discouraged as it does not allow the compiler to perform strong type- + checking. However, the pointer type chosen should be of the same size + as the (void *) type. Provided this rule is obeyed, ABI specifications + need not further constrain the implementation of gss_name_t objects. + + B.5. The int and size_t types + + Some platforms may support differently sized implementations of the + "int" and "size_t" types, perhaps chosen through compiler switches, and + perhaps dependent on memory model. An ABI specification for such a + platform should include required implementations for these types. It is + recommended that the default implementation (for the chosen memory + + + + Wray Document Expiration: 1 September 1997 [Page 93] + + + + + + + + INTERNET-DRAFT GSS-API V2 - C bindings March 1997 + + + + model, if appropriate) is chosen. + + B.6. Procedure-calling conventions + + Some platforms support a variety of different binary conventions for + calling procedures. Such conventions cover things like the format of + the stack frame, the order in which the routine parameters are pushed + onto the stack, whether or not a parameter count is pushed onto the + stack, whether some argument(s) or return values are to be passed in + registers, and whether the called routine or the caller is responsible + for removing the stack frame on return. For such platforms, an ABI + specification should specify which calling convention is to be used for + GSSAPI implementations. + + + REFERENCES + + [GSSAPI] J. Linn, "Generic Security Service Application Program + Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2- + 08, 26 August 1996. (This Internet-Draft, like all other + Internet-Drafts, is not an archival document and is subject + to change or deletion. It is available at the time of this + writing by anonymous ftp from ds.internic.net, directory + internet-drafts. Would-be readers should check for successor + Internet-Draft versions or Internet RFCs before relying on + this document.) + + [XOM] OSI Object Management API Specification, Version 2.0 t", + X.400 API Association & X/Open Company Limited, August 24, + 1990. Specification of datatypes and routines for + manipulating information objects. + + + AUTHOR'S ADDRESS + + John Wray Internet email: Wray@tuxedo.enet.dec.com + Digital Equipment Corporation Telephone: +1-508-486-5210 + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + USA + + + + + + + + + + + + + + + Wray Document Expiration: 1 September 1997 [Page 94] + + + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt new file mode 100644 index 0000000..e235bec --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt @@ -0,0 +1,311 @@ + + + + +Network Working Group M. Horowitz +<draft-ietf-cat-kerb-chg-password-02.txt> Stonecast, Inc. +Internet-Draft August, 1998 + + Kerberos Change Password Protocol + +Status of this Memo + + This document is an Internet-Draft. 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.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ftp.ietf.org (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + + The Kerberos V5 protocol [RFC1510] does not describe any mechanism + for users to change their own passwords. In order to promote + interoperability between workstations, personal computers, terminal + servers, routers, and KDC's from multiple vendors, a common password + changing protocol is required. + + + +Overview + + When a user wishes to change his own password, or is required to by + local policy, a simple request of a password changing service is + necessary. This service must be implemented on at least one host for + each Kerberos realm, probably on one of the kdc's for that realm. + The service must accept requests on UDP port 464 (kpasswd), and may + accept requests on TCP port 464 as well. + + The protocol itself consists of a single request message followed by + a single reply message. For UDP transport, each message must be + fully contained in a single UDP packet. + + + + + + + + +Horowitz [Page 1] + +Internet Draft Kerberos Change Password Protocol August, 1998 + + +Request Message + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message length | protocol version number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AP_REQ length | AP-REQ data / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + / KRB-PRIV message / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + message length (16 bits) + Contains the length of the message, including this field, in bytes + (big-endian integer) + protocol version number (16 bits) + Contains the hex constant 0x0001 (big-endian integer) + AP-REQ length (16 bits) + length (big-endian integer) of AP-REQ data, in bytes. + AP-REQ data, as described in RFC1510 (variable length) + This AP-REQ must be for the service principal + kadmin/changepw@REALM, where REALM is the REALM of the user who + wishes to change his password. The Ticket in the AP-REQ must be + derived from an AS request (thus having the INITIAL flag set), and + must include a subkey in the Authenticator. + KRB-PRIV message, as described in RFC1510 (variable length) + This KRB-PRIV message must be generated using the subkey in the + Authenticator in the AP-REQ data. The user-data component of the + message must consist of the user's new password. + + The server must verify the AP-REQ message, decrypt the new password, + perform any local policy checks (such as password quality, history, + authorization, etc.) required, then set the password to the new value + specified. + + The principal whose password is to be changed is the principal which + authenticated to the password changing service. This protocol does + not address administrators who want to change passwords of principal + besides their own. + + +Reply Message + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message length | protocol version number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | AP_REP length | AP-REP data / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + / KRB-PRIV or KRB-ERROR message / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + message length (16 bits) + + + +Horowitz [Page 2] + +Internet Draft Kerberos Change Password Protocol August, 1998 + + + Contains the length of the message, including this field, in bytes + (big-endian integer), + protocol version number (16 bits) + Contains the hex constant 0x0001 (big-endian integer) + AP-REP length (16 bits) + length of AP-REP data, in bytes. If the the length is zero, then + the last field will contain a KRB-ERROR message instead of a KRB- + PRIV message. + AP-REP data, as described in RFC1510 (variable length) + The AP-REP corresponding to the AP-REQ in the request packet. + KRB-PRIV or KRB-ERROR message, as described in RFC1510 (variable + length) + If the AP-REP length is zero, then this field contains a KRB-ERROR + message. Otherwise, it contains a KRB-PRIV message. This KRB- + PRIV message must be generated using the subkey in the + Authenticator in the AP-REQ data. + + The user-data component of the KRB-PRIV message, or e-data + component of the KRB-ERROR message, must consist of the following + data: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | result code | result string / + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + result code (16 bits) + The result code must have one of the following values (big- + endian integer): + 0x0000 if the request succeeds. (This value is not permitted + in a KRB-ERROR message.) + 0x0001 if the request fails due to being malformed + 0x0002 if the request fails due to a "hard" error processing + the request (for example, there is a resource or other + problem causing the request to fail) + 0x0003 if the request fails due to an error in authentication + processing + 0x0004 if the request fails due to a "soft" error processing + the request (for example, some policy or other similar + consideration is causing the request to be rejected). + 0xFFFF if the request fails for some other reason. + Although only a few non-zero result codes are specified here, + the client should accept any non-zero result code as indicating + failure. + result string (variable length) + This field should contain information which the server thinks + might be useful to the user, such as feedback about policy + failures. The string must be encoded in UTF-8. It may be + omitted if the server does not wish to include it. If it is + present, the client should display the string to the user. + This field is analogous to the string which follows the numeric + code in SMTP, FTP, and similar protocols. + + + + +Horowitz [Page 3] + +Internet Draft Kerberos Change Password Protocol August, 1998 + + +Dropped and Modified Messages + + An attacker (or simply a lossy network) could cause either the + request or reply to be dropped, or modified by substituting a KRB- + ERROR message in the reply. + + If a request is dropped, no modification of the password/key database + will take place. If a reply is dropped, the server will (assuming a + valid request) make the password change. However, the client cannot + distinguish between these two cases. + + In this situation, the client should construct a new authenticator, + re-encrypt the request, and retransmit. If the original request was + lost, the server will treat this as a valid request, and the password + will be changed normally. If the reply was lost, then the server + should take care to notice that the request was a duplicate of the + prior request, because the "new" password is the current password, + and the password change time is within some implementation-defined + replay time window. The server should then return a success reply + (an AP-REP message with result code == 0x0000) without actually + changing the password or any other information (such as modification + timestamps). + + If a success reply was replaced with an error reply, then the + application performing the request would return an error to the user. + In this state, the user's password has been changed, but the user + believes that it has not. If the user attempts to change the + password again, this will probably fail, because the user cannot + successfully provide the old password to get an INITIAL ticket to + make the request. This situation requires administrative + intervention as if a password was lost. This situation is, + unfortunately, impossible to prevent. + + +Security Considerations + + This document deals with changing passwords for Kerberos. Because + Kerberos is used for authentication and key distribution, it is + important that this protocol use the highest level of security + services available to a particular installation. Mutual + authentication is performed, so that the server knows the request is + valid, and the client knows that the request has been received and + processed by the server. + + There are also security issues relating to dropped or modified + messages which are addressed explicitly. + + +References + + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + + + + +Horowitz [Page 4] + +Internet Draft Kerberos Change Password Protocol August, 1998 + + +Author's Address + + Marc Horowitz + Stonecast, Inc. + 108 Stow Road + Harvard, MA 01451 + + Phone: +1 978 456 9103 + Email: marc@stonecast.net + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz [Page 5] + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt new file mode 100644 index 0000000..2583a84 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt @@ -0,0 +1,127 @@ + + + + + + +Network Working Group M. Horowitz +<draft-ietf-cat-kerb-des3-hmac-sha1-00.txt> Cygnus Solutions +Internet-Draft November, 1996 + + + Triple DES with HMAC-SHA1 Kerberos Encryption Type + +Status of this Memo + + This document is an Internet-Draft. 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.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + + This document defines a new encryption type and a new checksum type + for use with Kerberos V5 [RFC1510]. This encryption type is based on + the Triple DES cryptosystem and the HMAC-SHA1 [Krawczyk96] message + authentication algorithm. + + The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. + The hmac-sha1-des3 checksum type has been assigned the value 12. + + +Encryption Type des3-cbc-hmac-sha1 + + EncryptedData using this type must be generated as described in + [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC + mode. The keyed hash algorithm is HMAC-SHA1. Unless otherwise + specified, a zero IV must be used. If the length of the input data + is not a multiple of the block size, zero octets must be used to pad + the plaintext to the next eight-octet boundary. The counfounder must + be eight random octets (one block). + + +Checksum Type hmac-sha1-des3 + + Checksums using this type must be generated as described in + [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. + + + +Horowitz [Page 1] + +Internet Draft Kerberos Triple DES with HMAC-SHA1 November, 1996 + + +Common Requirements + + Where the Triple DES key is represented as an EncryptionKey, it shall + be represented as three DES keys, with parity bits, concatenated + together. The key shall be represented with the most significant bit + first. + + When keys are generated by the derivation function, a key length of + 168 bits shall be used. The output bit string will be converted to a + valid Triple DES key by inserting DES parity bits after every seventh + bit. + + Any implementation which implements either of the encryption or + checksum types in this document must support both. + + +Security Considerations + + This entire document defines encryption and checksum types for use + with Kerberos V5. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Kerberos V5", draft- + horowitz-kerb-key-derivation-00.txt, November 1996. + [Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: + Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- + md5-01.txt, August, 1996. + [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + +Horowitz [Page 2] + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt new file mode 100644 index 0000000..46a4158 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt @@ -0,0 +1,250 @@ + + + + + +Network Working Group M. Horowitz +<draft-ietf-cat-kerb-key-derivation-00.txt> Cygnus Solutions +Internet-Draft November, 1996 + + + Key Derivation for Kerberos V5 + +Status of this Memo + + This document is an Internet-Draft. 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.'' + + To learn the current status of any Internet-Draft, please check the + ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow + Directories on ds.internic.net (US East Coast), nic.nordu.net + (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific + Rim). + + Distribution of this memo is unlimited. Please send comments to the + <cat-ietf@mit.edu> mailing list. + +Abstract + + In the Kerberos protocol [RFC1510], cryptographic keys are used in a + number of places. In order to minimize the effect of compromising a + key, it is desirable to use a different key for each of these places. + Key derivation [Horowitz96] can be used to construct different keys + for each operation from the keys transported on the network. For + this to be possible, a small change to the specification is + necessary. + + +Overview + + Under RFC1510 as stated, key derivation could be specified as a set + of encryption types which share the same key type. The constant for + each derivation would be a function of the encryption type. However, + it is generally accepted that, for interoperability, key types and + encryption types must map one-to-one onto each other. (RFC 1510 is + being revised to address this issue.) Therefore, to use key + derivcation with Kerberos V5 requires a small change to the + specification. + + For each place where a key is used in Kerberos, a ``key usage'' must + be specified for that purpose. The key, key usage, and + encryption/checksum type together describe the transformation from + plaintext to ciphertext, or plaintext to checksum. For backward + + + +Horowitz [Page 1] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + compatibility, old encryption types would be defined independently of + the key usage. + + +Key Usage Values + + This is a complete list of places keys are used in the kerberos + protocol, with key usage values and RFC 1510 section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) + + 10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) + 11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) + 12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) + + 13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) + 14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) + 15. KRB-SAVE cksum, keyed with a key chosen by the application + (section 5.8.1) + + 16. Data which is defined in some specification outside of + Kerberos to be encrypted using an RFC1510 encryption type. + 17. Data which is defined in some specification outside of + Kerberos to be checksummed using an RFC1510 checksum type. + + A few of these key usages need a little clarification. A service + which receives an AP-REQ has no way to know if the enclosed Ticket + was part of an AS-REP or TGS-REP. Therefore, key usage 2 must always + + + +Horowitz [Page 2] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + + be used for generating a Ticket, whether it is in response to an AS- + REQ or TGS-REQ. + + There might exist other documents which define protocols in terms of + the RFC1510 encryption types or checksum types. Such documents would + not know about key usages. In order that these documents continue to + be meaningful until they are updated, key usages 16 and 17 must be + used to derive keys for encryption and checksums, respectively. New + protocols defined in terms of the Kerberos encryption and checksum + types should use their own key usages. Key usages may be registered + with IANA to avoid conflicts. Key usages shall be unsigned 32 bit + integers. Zero is not permitted. + + +Defining Cryptosystems Using Key Derivation + + Kerberos requires that the ciphertext component of EncryptedData be + tamper-resistant as well as confidential. This implies encryption + and integrity functions, which must each use their own separate keys. + So, for each key usage, two keys must be generated, one for + encryption (Ke), and one for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + + where the key usage is represented as a 32 bit integer in network + byte order. The ciphertest must be generated from the plaintext as + follows: + + ciphertext = E(Ke, confounder | length | plaintext | padding) | + H(Ki, confounder | length | plaintext | padding) + + The confounder and padding are specific to the encryption algorithm + E. + + When generating a checksum only, there is no need for a confounder or + padding. Again, a new key (Kc) must be used. Checksums must be + generated from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + + MAC = H(Kc, length | plaintext) + + Note that each enctype is described by an encryption algorithm E and + a keyed hash algorithm H, and each checksum type is described by a + keyed hash algorithm H. HMAC, with an appropriate hash, is + recommended for use as H. + + +Security Considerations + + This entire document addresses shortcomings in the use of + cryptographic keys in Kerberos V5. + + + + +Horowitz [Page 3] + +Internet Draft Key Derivation for Kerberos V5 November, 1996 + + +Acknowledgements + + I would like to thank Uri Blumenthal, Sam Hartman, and Bill + Sommerfeld for their contributions to this document. + + +References + + [Horowitz96] Horowitz, M., "Key Derivation for Authentication, + Integrity, and Privacy", draft-horowitz-key-derivation-00.txt, + November 1996. [RFC1510] Kohl, J. and Neuman, C., "The Kerberos + Network Authentication Service (V5)", RFC 1510, September 1993. + + +Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + Email: marc@cygnus.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz [Page 4] + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt new file mode 100644 index 0000000..c5e4d05 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt @@ -0,0 +1,252 @@ + +INTERNET-DRAFT Ari Medvinsky +draft-ietf-cat-kerberos-err-msg-00.txt Matt Hur +Updates: RFC 1510 Dominique Brezinski +expires September 30, 1997 CyberSafe Corporation + Gene Tsudik + Brian Tung + ISI + +Integrity Protection for the Kerberos Error Message + +0. Status Of this Memo + + This document is an Internet-Draft. 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." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires June xx, 1997. + Please send comments to the authors. + +1. Abstract + + The Kerberos error message, as defined in RFC 1510, is transmitted + to the client without any integrity assurance. Therefore, the + client has no means to distinguish between a valid error message + sent from the KDC and one sent by an attacker. This draft describes + a method for assuring the integrity of Kerberos error messages, and + proposes a consistent format for the e-data field in the KRB_ERROR + message. This e-data format enables the storage of cryptographic + checksums by providing an extensible mechanism for specifying e-data + types. + + +2. Motivation + + In the Kerberos protocol [1], if an error occurs for AS_REQ, + TGS_REQ, or AP_REQ, a clear text error message is returned to the + client. An attacker may exploit this vulnerability by sending a + false error message as a reply to any of the above requests. For + example, an attacker may send the KDC_ERR_KEY_EXPIRED error message + in order to force a user to change their password in hope that the + new key will not be as strong as the current key, and thus, easier + to break. + + Since false error messages may be utilized by an attacker, a + Kerberos client should have a means for determining how much trust + to place in a given error message. The rest of this draft + describes a method for assuring the integrity of Kerberos error + messages. + + +3. Approach + + We propose taking a cryptographic checksum over the entire KRB-ERROR + message. This checksum would be returned as part of the error + message and would enable the client to verify the integrity of the + error message. For interoperability reasons, no new fields are + added to the KRB-ERROR message. Instead, the e-data field (see + figure 1) is utilized to carry the cryptographic checksum. + + +3.1 Cryptographic checksums in error messages for AS_REQ, + TGS_REQ & AP_REQ + + If an error occurs for the AS request, the only key that is + available to the KDC is the shared secret (the key derived from the + clients password) registered in the KDCs database. The KDC will + use this key to sign the error message, if and only if, the client + already proved knowledge of the shared secret in the AS request + (e.g. via PA-ENC-TIMESTAMP in preauth data). This policy is needed + to prevent an attacker from getting the KDC to send a signed error + message and then launching an off-line attack in order to obtain a + key of a given principal. + + If an error occurs for a TGS or an AP request, the server will use + the session key sealed in the clients ticket granting ticket to + compute the checksum over the error message. If the checksum could + not be computed (e.g. error while decrypting the ticket) the error + message is returned to the client without the checksum. The client + then has the option to treat unprotected error messages differently. + + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno [0] integer, + msg-type [1] integer, + ctime [2] KerberosTime OPTIONAL, + cusec [3] INTEGER OPTIONAL, + stime [4] KerberosTime, + susec [5] INTEGER, + error-code [6] INTEGER, + crealm [7] Realm OPTIONAL, + cname [8] PrincipalName OPTIONAL, + realm [9] Realm, --Correct realm + sname [10] PrincipalName, --Correct name + e-text [11] GeneralString OPTIONAL, + e-data [12] OCTET STRING OPTIONAL + } + Figure 1 + + +3.2 Format of the e-data field + + We propose to place the cryptographic checksum in the e-data field. + First, we review the format of the e-data field, as specified in + RFC 1510. The format of e-data is specified only in two cases [2]. + "If the error code is KDC_ERR_PREAUTH_REQUIRED, then the e-data + field will contain an encoding of a sequence of padata fields": + + METHOD-DATA ::= SEQUENCE of PA-DATA + PA-DATA ::= SEQUENCE { + padata-type [1] INTEGER, + padata-value [2] OCTET STRING + } + + The second case deals with the KRB_AP_ERR_METHOD error code. The + e-data field will contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type [0] INTEGER, + method-data [1] OCTET STRING OPTIONAL + } + + method-type indicates the required alternate authentication method. + + It should be noted that, in the case of KRB_AP_ERR_METHOD, a signed + checksum is not returned as part of the error message, since the + error code indicates that the Kerberos credentials provided in the + AP_REQ message are unacceptable. + + We propose that the e-data field have the following format for all + error-codes (except KRB_AP_ERR_METHOD): + + E-DATA ::= SEQUENCE { + data-type [1] INTEGER, + data-value [2] OCTET STRING, + } + + The data-type field specifies the type of information that is + carried in the data-value field. Thus, to send a cryptographic + checksum back to the client, the data-type is set to CHECKSUM, the + data-value is set to the ASN.1 encoding of the following sequence: + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } + + +3.3 Computing the checksum + + After the error message is filled out, the error structure is + converted into ASN.1 representation. A cryptographic checksum is + then taken over the encoded error message; the result is placed in + the error message structure, as the last item in the e-data field. + To send the error message, ASN.1 encoding is again performed over + the error message, which now includes the cryptographic checksum. + + +3.4 Verifying the integrity of the error message + + In addition to verifying the cryptographic checksum for the error + message, the client must verify that the error message is bound to + its request. This is done by comparing the ctime field in the + error message to its counterpart in the request message. + + +4. E-DATA types + + Since the e-data types must not conflict with preauthentication data + types, we propose that the preauthentication data types in the range + of 2048 and above be reserved for use as e-data types. + + We define the following e-data type in support of integrity checking + for the Kerberos error message: + + CHECKSUM = 2048 -- the keyed checksum described above + + +5. Discussion + + +5.1 e-data types + + The extension for Kerberos error messages, as outlined above, is + extensible to allow for definition of other error data types. + We propose that the following e-data types be reserved: + + KDCTIME = 2049 + The error data would consist of the KDCs time in KerberosTime. + This data would be used by the client to adjust for clock skew. + + REDIRECT = 2050 + The error data would consist of a hostname. The hostname would + indicate the authoritative KDC from which to obtain a TGT. + + +5.2 e-data types vs. error code specific data formats + + Since RFC 1510 does not define an error data type, the data format + must be explicitly specified for each error code. This draft has + proposed an extension to RFC 1510 that would introduce the concept + of error data types. This would allow for a manageable set of data + types to be used for any error message. The authors assume that + the introduction of this e-data structure will not break any + existing Kerberos implementations. + + +6. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + [2] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 p.67 + + +7. Authors + + Ari Medvinsky <ari.medvinsky@cybersafe.com> + Matthew Hur <matt.hur@cybersafe.com> + Dominique Brezinski <dominique.brezinski@cybersafe.com> + + CyberSafe Corporation + 1605 NW Sammamish Road + Suite 310 + Issaquah, WA 98027-5378 + Phone: (206) 391-6000 + Fax: (206) 391-0508 + http:/www.cybersafe.com + + + Brian Tung <brian@isi.edu> + Gene Tsudik <gts@isi.edu> + + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: (310) 822-1511 + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt new file mode 100644 index 0000000..4b193c5 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt @@ -0,0 +1,282 @@ +INTERNET-DRAFT Brian Tung +draft-ietf-cat-kerberos-pk-cross-01.txt Tatyana Ryutov +Updates: RFC 1510 Clifford Neuman +expires September 30, 1997 Gene Tsudik + ISI + Bill Sommerfeld + Hewlett-Packard + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + + + Public Key Cryptography for Cross-Realm Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. 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.'' + + To learn the current status of any Internet-Draft, please check + the ``1id-abstracts.txt'' listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-cross-01.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions to the Kerberos protocol + specification (RFC 1510, "The Kerberos Network Authentication + Service (V5)", September 1993) to provide a method for using + public key cryptography during cross-realm authentication. The + methods defined here specify the way in which message exchanges + are to be used to transport cross-realm secret keys protected by + encryption under public keys certified as belonging to KDCs. + + +2. Motivation + + The advantages provided by public key cryptography--ease of + recoverability in the event of a compromise, the possibility of + an autonomous authentication infrastructure, to name a few--have + produced a demand for use by Kerberos authentication protocol. A + draft describing the use of public key cryptography in the initial + authentication exchange in Kerberos has already been submitted. + This draft describes its use in cross-realm authentication. + + The principal advantage provided by public key cryptography in + cross-realm authentication lies in the ability to leverage the + existing public key infrastructure. It frees the Kerberos realm + administrator from having to maintain separate keys for each other + realm with which it wishes to exchange authentication information, + or to utilize a hierarchical arrangement, which may pose problems + of trust. + + Even with the multi-hop cross-realm authentication, there must be + some way to locate the path by which separate realms are to be + transited. The current method, which makes use of the DNS-like + realm names typical to Kerberos, requires trust of the intermediate + KDCs. + + The methods described in this draft allow a realm to specify, at + the time of authentication, which certification paths it will + trust. A shared key for cross-realm authentication can be + established, for a period of time. Furthermore, these methods are + transparent to the client, so that only the KDC's need to be + modified to use them. + + It is not necessary to implement the changes described in the + "Public Key Cryptography for Initial Authentication" draft to make + use of the changes in this draft. We solicit comments about the + interaction between the two protocol changes, but as of this + writing, the authors do not perceive any obstacles to using both. + + +3. Protocol Amendments + + We assume that the user has already obtained a TGT. To perform + cross-realm authentication, the user sends a request to the local + KDC as per RFC 1510. If the two realms share a secret key, then + cross-realm authentication proceeds as usual. Otherwise, the + local KDC may attempt to establish a shared key with the remote + KDC using public key cryptography, and exchange this key through + the cross-realm ticket granting ticket. + + We will consider the specific channel on which the message + exchanges take place in Section 5 below. + + +3.1. Changes to the Cross-Realm Ticket Granting Ticket + + In order to avoid the need for changes to the "installed base" of + Kerberos application clients and servers, the only protocol change + is to the way in which cross-realm ticket granting tickets (TGTs) + are encrypted; as these tickets are opaque to clients and servers, + the only change visible to them will be the increased size of the + tickets. + + Cross-realm TGTs are granted by a local KDC to authenticate a user + to a remote KDC's ticket granting service. In standard Kerberos, + they are encrypted using a shared secret key manually configured + into each KDC. + + In order to incorporate public key cryptography, we define a new + encryption type, "ENCTYPE_PK_CROSS". Operationally, this encryption + type transforms an OCTET STRING of plaintext (normally an EncTktPart) + into the following SEQUENCE: + + PKCrossOutput ::= SEQUENCE { + certificate [0] OCTET STRING OPTIONAL, + -- public key certificate + -- of local KDC + encSharedKey [1] EncryptedData, + -- of type EncryptionKey + -- containing random symmetric key + -- encrypted using public key + -- of remote KDC + sigSharedKey [2] Signature, + -- of encSharedKey + -- using signature key + -- of local KDC + pkEncData [3] EncryptedData, + -- (normally) of type EncTktPart + -- encrypted using encryption key + -- found in encSharedKey + } + + PKCROSS operates as follows: when a client submits a request for + cross-realm authentication, the local KDC checks to see if it has + a long-term shared key established for that realm. If so, it uses + this key as per RFC 1510. + + If not, it sends a request for information to the remote KDC. The + content of this message is immaterial, as it does not need to be + processed by the remote KDC; for the sake of consistency, we define + it as follows: + + RemoteRequest ::= [APPLICATION 41] SEQUENCE { + nonce [0] INTEGER + } + + The remote KDC replies with a list of all trusted certifiers and + all its (the remote KDC's) certificates. We note that this response + is universal and does not depend on which KDC makes the request: + + RemoteReply ::= [APPLICATION 42] SEQUENCE { + trustedCertifiers [0] SEQUENCE OF PrincipalName, + certificates[1] SEQUENCE OF Certificate, + encTypeToUse [1] SEQUENCE OF INTEGER + -- encryption types usable + -- for encrypting pkEncData + } + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } -- from pk-init draft + + Upon receiving this reply, the local KDC determines whether it has + a certificate the remote KDC trusts, and whether the remote KDC has + a certificate the local KDC trusts. If so, it issues a ticket + encrypted using the ENCTYPE_PK_CROSS encryption type defined above. + + +3.2. Profile Caches + + We observe that using PKCROSS as specified above requires two + private key operations: a signature generation by the local KDC and + a decryption by the remote KDC. This cost can be reduced in the + long term by judicious caching of the encSharedKey and the + sigSharedKey. + + Let us define a "profile" as the encSharedKey and sigSharedKey, in + conjunction with the associated remote realm name and decrypted + shared key (the key encrypted in the encSharedKey). + + To optimize these interactions, each KDC maintains two caches, one + for outbound profiles and one for inbound profiles. When generating + an outbound TGT for another realm, the local KDC first checks to see + if the corresponding entry exists in the outbound profile cache; if + so, it uses its contents to form the first three fields of the + PKCrossOutput; the shared key is used to encrypt the data for the + fourth field. If not, the components are generated fresh and stored + in the outbound profile cache. + + Upon receipt of the TGT, the remote realm checks its inbound profile + cache for the corresponding entry. If it exists, then it uses the + contents of the entry to decrypt the data encrypted in the pkEncData. + If not, then it goes through the full process of verifying and + extracting the shared key; if this is successful, then a new entry + is created in the inbound profile cache. + + The inbound profile cache should support multiple entries per realm, + in the event that the initiating realm is replicated. + + +4. Finding Realms Supporting PKCROSS + + If either the local realm or the destination realm does not support + PKCROSS, or both do not, the mechanism specified in Section 3 can + still be used in obtaining the desired remote TGT. + + In the reference Kerberos implementations, the default behavior is + to traverse a path up and down the realm name hierarchy, if the + two realms do not share a key. There is, however, the possibility + of using cross links--i.e., keys shared between two realms that + are non-contiguous in the realm name hierarchy--to shorten the + path, both to minimize delay and the number of intermediate realms + that need to be trusted. + + PKCROSS can be used as a way to provide cross-links even in the + absence of shared keys. If the client is aware that one or two + intermediate realms support PKCROSS, then a combination of + PKCROSS and conventional cross-realm authentication can be used + to reach the final destination realm. + + We solicit discussion on the best methods for clients and KDCs to + determine or advertise support for PKCROSS. + + +5. Message Ports + + We have not specified the port on which KDCs supporting PKCROSS + should listen to receive the request for information messages noted + above. We solicit discussion on which port should be used. We + propose to use the standard Kerberos ports (well-known 88 or 750), + but another possibility is to use a completely different port. + + We also solicit discussion on what other approaches can be taken to + obtain the information in the RemoteReply (e.g., secure DNS or some + other repository). + + +6. Expiration Date + + This Internet-Draft will expire on September 30, 1997. + + +7. Authors' Addresses + + Brian Tung + Tatyana Ryutov + Clifford Neuman + Gene Tsudik + USC/Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey, CA 90292-6695 + Phone: +1 310 822 1511 + E-Mail: {brian, tryutov, bcn, gts}@isi.edu + + Bill Sommerfeld + Hewlett Packard + 300 Apollo Drive + Chelmsford MA 01824 + Phone: +1 508 436 4352 + E-Mail: sommerfeld@apollo.hp.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt new file mode 100644 index 0000000..d91c087 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt @@ -0,0 +1,589 @@ + +INTERNET-DRAFT Clifford Neuman +draft-ietf-cat-kerberos-pk-init-03.txt Brian Tung +Updates: RFC 1510 ISI +expires September 30, 1997 John Wray + Digital Equipment Corporation + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + Jonathan Trostle + Novell + + + Public Key Cryptography for Initial Authentication in Kerberos + + +0. Status Of this Memo + + This document is an Internet-Draft. 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." + + To learn the current status of any Internet-Draft, please check + the "1id-abstracts.txt" listing contained in the Internet-Drafts + Shadow Directories on ds.internic.net (US East Coast), + nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or + munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is filed as + draft-ietf-cat-kerberos-pk-init-03.txt, and expires September 30, + 1997. Please send comments to the authors. + + +1. Abstract + + This document defines extensions (PKINIT) to the Kerberos protocol + specification (RFC 1510 [1]) to provide a method for using public + key cryptography during initial authentication. The methods + defined specify the ways in which preauthentication data fields and + error data fields in Kerberos messages are to be used to transport + public key data. + + +2. Introduction + + The popularity of public key cryptography has produced a desire for + its support in Kerberos [2]. The advantages provided by public key + cryptography include simplified key management (from the Kerberos + perspective) and the ability to leverage existing and developing + public key certification infrastructures. + + Public key cryptography can be integrated into Kerberos in a number + of ways. One is to to associate a key pair with each realm, which + can then be used to facilitate cross-realm authentication; this is + the topic of another draft proposal. Another way is to allow users + with public key certificates to use them in initial authentication. + This is the concern of the current document. + + One of the guiding principles in the design of PKINIT is that + changes should be as minimal as possible. As a result, the basic + mechanism of PKINIT is as follows: The user sends a request to the + KDC as before, except that if that user is to use public key + cryptography in the initial authentication step, his certificate + accompanies the initial request, in the preauthentication fields. + + Upon receipt of this request, the KDC verifies the certificate and + issues a ticket granting ticket (TGT) as before, except that instead + of being encrypted in the user's long-term key (which is derived + from a password), it is encrypted in a randomly-generated key. This + random key is in turn encrypted using the public key certificate + that came with the request and signed using the KDC's signature key, + and accompanies the reply, in the preauthentication fields. + + PKINIT also allows for users with only digital signature keys to + authenticate using those keys, and for users to store and retrieve + private keys on the KDC. + + The PKINIT specification may also be used for direct peer to peer + authentication without contacting a central KDC. This application + of PKINIT is described in PKTAPP [4] and is based on concepts + introduced in [5, 6]. For direct client-to-server authentication, + the client uses PKINIT to authenticate to the end server (instead + of a central KDC), which then issues a ticket for itself. This + approach has an advantage over SSL [7] in that the server does not + need to save state (cache session keys). Furthermore, an + additional benefit is that Kerberos tickets can facilitate + delegation (see [8]). + + +3. Proposed Extensions + + This section describes extensions to RFC 1510 for supporting the + use of public key cryptography in the initial request for a ticket + granting ticket (TGT). + + In summary, the following changes to RFC 1510 are proposed: + + --> Users may authenticate using either a public key pair or a + conventional (symmetric) key. If public key cryptography is + used, public key data is transported in preauthentication + data fields to help establish identity. + --> Users may store private keys on the KDC for retrieval during + Kerberos initial authentication. + + This proposal addresses two ways that users may use public key + cryptography for initial authentication. Users may present public + key certificates, or they may generate their own session key, + signed by their digital signature key. In either case, the end + result is that the user obtains an ordinary TGT that may be used for + subsequent authentication, with such authentication using only + conventional cryptography. + + Section 3.1 provides definitions to help specify message formats. + Section 3.2 and 3.3 describe the extensions for the two initial + authentication methods. Section 3.3 describes a way for the user to + store and retrieve his private key on the KDC. + + +3.1. Definitions + + Hash and encryption types will be specified using ENCTYPE tags; we + propose the addition of the following types: + + #define ENCTYPE_SIGN_DSA_GENERATE 0x0011 + #define ENCTYPE_SIGN_DSA_VERIFY 0x0012 + #define ENCTYPE_ENCRYPT_RSA_PRIV 0x0021 + #define ENCTYPE_ENCRYPT_RSA_PUB 0x0022 + + allowing further signature types to be defined in the range 0x0011 + through 0x001f, and further encryption types to be defined in the + range 0x0021 through 0x002f. + + The extensions involve new preauthentication fields. The + preauthentication data types are in the range 17 through 21. + These values are also specified along with their corresponding + ASN.1 definition. + + #define PA-PK-AS-REQ 17 + #define PA-PK-AS-REP 18 + #define PA-PK-AS-SIGN 19 + #define PA-PK-KEY-REQ 20 + #define PA-PK-KEY-REP 21 + + The extensions also involve new error types. The new error types + are in the range 227 through 229. They are: + + #define KDC_ERROR_CLIENT_NOT_TRUSTED 227 + #define KDC_ERROR_KDC_NOT_TRUSTED 228 + #define KDC_ERROR_INVALID_SIG 229 + + In the exposition below, we use the following terms: encryption key, + decryption key, signature key, verification key. It should be + understood that encryption and verification keys are essentially + public keys, and decryption and signature keys are essentially + private keys. The fact that they are logically distinct does + not preclude the assignment of bitwise identical keys. + + +3.2. Standard Public Key Authentication + + Implementation of the changes in this section is REQUIRED for + compliance with pk-init. + + It is assumed that all public keys are signed by some certification + authority (CA). The initial authentication request is sent as per + RFC 1510, except that a preauthentication field containing data + signed by the user's signature key accompanies the request: + + PA-PK-AS-REQ ::- SEQUENCE { + -- PA TYPE 17 + signedPKAuth [0] SignedPKAuthenticator, + userCert [1] SEQUENCE OF Certificate OPTIONAL, + -- the user's certificate + -- optionally followed by that + -- certificate's certifier chain + trustedCertifiers [2] SEQUENCE OF PrincipalName OPTIONAL + -- CAs that the client trusts + } + + SignedPKAuthenticator ::= SEQUENCE { + pkAuth [0] PKAuthenticator, + pkAuthSig [1] Signature, + -- of pkAuth + -- using user's signature key + } + + PKAuthenticator ::= SEQUENCE { + cusec [0] INTEGER, + -- for replay prevention + ctime [1] KerberosTime, + -- for replay prevention + nonce [2] INTEGER, + -- binds response to this request + kdcName [3] PrincipalName, + clientPubValue [4] SubjectPublicKeyInfo OPTIONAL, + -- for Diffie-Hellman algorithm + } + + Signature ::= SEQUENCE { + signedHash [0] EncryptedData + -- of type Checksum + -- encrypted under signature key + } + + Checksum ::= SEQUENCE { + cksumtype [0] INTEGER, + checksum [1] OCTET STRING + } -- as specified by RFC 1510 + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm [0] algorithmIdentifier, + subjectPublicKey [1] BIT STRING + } -- as specified by the X.509 recommendation [9] + + Certificate ::= SEQUENCE { + CertType [0] INTEGER, + -- type of certificate + -- 1 = X.509v3 (DER encoding) + -- 2 = PGP (per PGP draft) + CertData [1] OCTET STRING + -- actual certificate + -- type determined by CertType + } + + Note: If the signature uses RSA keys, then it is to be performed + as per PKCS #1. + + The PKAuthenticator carries information to foil replay attacks, + to bind the request and response, and to optionally pass the + client's Diffie-Hellman public value (i.e. for using DSA in + combination with Diffie-Hellman). The PKAuthenticator is signed + with the private key corresponding to the public key in the + certificate found in userCert (or cached by the KDC). + + In the PKAuthenticator, the client may specify the KDC name in one + of two ways: 1) a Kerberos principal name, or 2) the name in the + KDC's certificate (e.g., an X.500 name, or a PGP name). Note that + case #1 requires that the certificate name and the Kerberos principal + name be bound together (e.g., via an X.509v3 extension). + + The userCert field is a sequence of certificates, the first of which + must be the user's public key certificate. Any subsequent + certificates will be certificates of the certifiers of the user's + certificate. These cerificates may be used by the KDC to verify the + user's public key. This field is empty if the KDC already has the + user's certifcate. + + The trustedCertifiers field contains a list of certification + authorities trusted by the client, in the case that the client does + not possess the KDC's public key certificate. + + Upon receipt of the AS_REQ with PA-PK-AS-REQ pre-authentication + type, the KDC attempts to verify the user's certificate chain + (userCert), if one is provided in the request. This is done by + verifying the certification path against the KDC's policy of + legitimate certifiers. This may be based on a certification + hierarchy, or it may be simply a list of recognized certifiers in a + system like PGP. If the certification path does not match one of + the KDC's trusted certifiers, the KDC sends back an error message of + type KDC_ERROR_CLIENT_NOT_TRUSTED, and it includes in the error data + field a list of its own trusted certifiers, upon which the client + resends the request. + + If trustedCertifiers is provided in the PA-PK-AS-REQ, the KDC + verifies that it has a certificate issued by one of the certifiers + trusted by the client. If it does not have a suitable certificate, + the KDC returns an error message of type KDC_ERROR_KDC_NOT_TRUSTED + to the client. + + If a trust relationship exists, the KDC then verifies the client's + signature on PKAuthenticator. If that fails, the KDC returns an + error message of type KDC_ERROR_INVALID_SIG. Otherwise, the KDC + uses the timestamp in the PKAuthenticator to assure that the request + is not a replay. The KDC also verifies that its name is specified + in PKAuthenticator. + + Assuming no errors, the KDC replies as per RFC 1510, except that it + encrypts the reply not with the user's key, but with a random key + generated only for this particular response. This random key + is sealed in the preauthentication field: + + PA-PK-AS-REP ::= SEQUENCE { + -- PA TYPE 18 + kdcCert [0] SEQUENCE OF Certificate OPTIONAL, + -- the KDC's certificate + -- optionally followed by that + -- certificate's certifier chain + encPaReply [1] EncryptedData, + -- of type PaReply + -- using either the client public + -- key or the Diffie-Hellman key + -- specified by SignedDHPublicValue + signedDHPublicValue [2] SignedDHPublicValue OPTIONAL + } + + + PaReply ::= SEQUENCE { + replyEncKeyPack [0] ReplyEncKeyPack, + replyEncKeyPackSig [1] Signature, + -- of replyEncKeyPack + -- using KDC's signature key + } + + ReplyEncKeyPack ::= SEQUENCE { + replyEncKey [0] EncryptionKey, + -- used to encrypt main reply + nonce [1] INTEGER + -- binds response to the request + -- passed in the PKAuthenticator + } + + SignedDHPublicValue ::= SEQUENCE { + dhPublicValue [0] SubjectPublicKeyInfo, + dhPublicValueSig [1] Signature + -- of dhPublicValue + -- using KDC's signature key + } + + The kdcCert field is a sequence of certificates, the first of which + must have as its root certifier one of the certifiers sent to the + KDC in the PA-PK-AS-REQ. Any subsequent certificates will be + certificates of the certifiers of the KDC's certificate. These + cerificates may be used by the client to verify the KDC's public + key. This field is empty if the client did not send to the KDC a + list of trusted certifiers (the trustedCertifiers field was empty). + + Since each certifier in the certification path of a user's + certificate is essentially a separate realm, the name of each + certifier shall be added to the transited field of the ticket. The + format of these realm names shall follow the naming constraints set + forth in RFC 1510 (sections 7.1 and 3.3.3.1). Note that this will + require new nametypes to be defined for PGP certifiers and other + types of realms as they arise. + + The KDC's certificate must bind the public key to a name derivable + from the name of the realm for that KDC. The client then extracts + the random key used to encrypt the main reply. This random key (in + encPaReply) is encrypted with either the client's public key or + with a key derived from the DH values exchanged between the client + and the KDC. + + +3.3. Digital Signature + + Implementation of the changes in this section are OPTIONAL for + compliance with pk-init. + + We offer this option with the warning that it requires the client to + generate a random key; the client may not be able to guarantee the + same level of randomness as the KDC. + + If the user registered a digital signature key with the KDC instead + of an encryption key, then a separate exchange must be used. The + client sends a request for a TGT as usual, except that it (rather + than the KDC) generates the random key that will be used to encrypt + the KDC response. This key is sent to the KDC along with the + request in a preauthentication field: + + PA-PK-AS-SIGN ::= SEQUENCE { + -- PA TYPE 19 + encSignedKeyPack [0] EncryptedData + -- of SignedKeyPack + -- using the KDC's public key + } + + SignedKeyPack ::= SEQUENCE { + signedKey [0] KeyPack, + signedKeyAuth [1] PKAuthenticator, + signedKeySig [2] Signature + -- of signedKey.signedKeyAuth + -- using user's signature key + } + + KeyPack ::= SEQUENCE { + randomKey [0] EncryptionKey, + -- will be used to encrypt reply + nonce [1] INTEGER + } + + where the nonce is copied from the request. + + Upon receipt of the PA-PK-AS-SIGN, the KDC decrypts then verifies + the randomKey. It then replies as per RFC 1510, except that the + reply is encrypted not with a password-derived user key, but with + the randomKey sent in the request. Since the client already knows + this key, there is no need to accompany the reply with an extra + preauthentication field. The transited field of the ticket should + specify the certification path as described in Section 3.2. + + +3.4. Retrieving the Private Key From the KDC + + Implementation of the changes in this section is RECOMMENDED for + compliance with pk-init. + + When the user's private key is not stored local to the user, he may + choose to store the private key (normally encrypted using a + password-derived key) on the KDC. We provide this option to present + the user with an alternative to storing the private key on local + disk at each machine where he expects to authenticate himself using + pk-init. It should be noted that it replaces the added risk of + long-term storage of the private key on possibly many workstations + with the added risk of storing the private key on the KDC in a + form vulnerable to brute-force attack. + + In order to obtain a private key, the client includes a + preauthentication field with the AS-REQ message: + + PA-PK-KEY-REQ ::= SEQUENCE { + -- PA TYPE 20 + patimestamp [0] KerberosTime OPTIONAL, + -- used to address replay attacks. + pausec [1] INTEGER OPTIONAL, + -- used to address replay attacks. + nonce [2] INTEGER, + -- binds the reply to this request + privkeyID [3] SEQUENCE OF KeyID OPTIONAL + -- constructed as a hash of + -- public key corresponding to + -- desired private key + } + + KeyID ::= SEQUENCE { + KeyIdentifier [0] OCTET STRING + } + + The client may request a specific private key by sending the + corresponding ID. If this field is left empty, then all + private keys are returned. + + If all checks out, the KDC responds as described in the above + sections, except that an additional preauthentication field, + containing the user's private key, accompanies the reply: + + PA-PK-KEY-REP ::= SEQUENCE { + -- PA TYPE 21 + nonce [0] INTEGER, + -- binds the reply to the request + KeyData [1] SEQUENCE OF KeyPair + } + + KeyPair ::= SEQUENCE { + privKeyID [0] OCTET STRING, + -- corresponding to encPrivKey + encPrivKey [1] OCTET STRING + } + + +3.4.1. Additional Protection of Retrieved Private Keys + + We solicit discussion on the following proposal: that the client may + optionally include in its request additional data to encrypt the + private key, which is currently only protected by the user's + password. One possibility is that the client might generate a + random string of bits, encrypt it with the public key of the KDC (as + in the SignedKeyPack, but with an ordinary OCTET STRING in place of + an EncryptionKey), and include this with the request. The KDC then + XORs each returned key with this random bit string. (If the bit + string is too short, the KDC could either return an error, or XOR + the returned key with a repetition of the bit string.) + + In order to make this work, additional means of preauthentication + need to be devised in order to prevent attackers from simply + inserting their own bit string. One way to do this is to store + a hash of the password-derived key (the one used to encrypt the + private key). This hash is then used in turn to derive a second + key (called the hash-key); the hash-key is used to encrypt an ASN.1 + structure containing the generated bit string and a nonce value + that binds it to the request. + + Since the KDC possesses the hash, it can generate the hash-key and + verify this (weaker) preauthentication, and yet cannot reproduce + the private key itself, since the hash is a one-way function. + + +4. Logistics and Policy Issues + + We solicit discussion on how clients and KDCs should be configured + in order to determine which of the options described above (if any) + should be used. One possibility is to set the user's database + record to indicate that authentication is to use public key + cryptography; this will not work, however, in the event that the + client needs to know before making the initial request. + +5. Compatibility with One-Time Passcodes + + We solicit discussion on how the protocol changes proposed in this + draft will interact with the proposed use of one-time passcodes + discussed in draft-ietf-cat-kerberos-passwords-00.txt. + + +6. Strength of Cryptographic Schemes + + In light of recent findings on the strength of MD5 and DES, + we solicit discussion on which encryption types to incorporate + into the protocol changes. + + +7. Bibliography + + [1] J. Kohl, C. Neuman. The Kerberos Network Authentication + Service (V5). Request for Comments: 1510 + + [2] B.C. Neuman, Theodore Ts'o. Kerberos: An Authentication Service + for Computer Networks, IEEE Communications, 32(9):33-38. + September 1994. + + [3] A. Medvinsky, M. Hur. Addition of Kerberos Cipher Suites to + Transport Layer Security (TLS). + draft-ietf-tls-kerb-cipher-suites-00.txt + + [4] A. Medvinsky, M. Hur, B. Clifford Neuman. Public Key Utilizing + Tickets for Application Servers (PKTAPP). + draft-ietf-cat-pktapp-00.txt + + [5] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos Using + Public Key Cryptography. Symposium On Network and Distributed System + Security, 1997. + + [6] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction + Protocol. In Proceedings of the USENIX Workshop on Electronic Commerce, + July 1995. + + [7] Alan O. Freier, Philip Karlton and Paul C. Kocher. + The SSL Protocol, Version 3.0 - IETF Draft. + + [8] B.C. Neuman, Proxy-Based Authorization and Accounting for + Distributed Systems. In Proceedings of the 13th International + Conference on Distributed Computing Systems, May 1993 + + [9] ITU-T (formerly CCITT) + Information technology - Open Systems Interconnection - + The Directory: Authentication Framework Recommendation X.509 + ISO/IEC 9594-8 + + +8. Acknowledgements + + Some of the ideas on which this proposal is based arose during + discussions over several years between members of the SAAG, the IETF + CAT working group, and the PSRG, regarding integration of Kerberos + and SPX. Some ideas have also been drawn from the DASS system. + These changes are by no means endorsed by these groups. This is an + attempt to revive some of the goals of those groups, and this + proposal approaches those goals primarily from the Kerberos + perspective. Lastly, comments from groups working on similar ideas + in DCE have been invaluable. + + +9. Expiration Date + + This draft expires September 30, 1997. + + +10. Authors + + Clifford Neuman + Brian Tung + USC Information Sciences Institute + 4676 Admiralty Way Suite 1001 + Marina del Rey CA 90292-6695 + Phone: +1 310 822 1511 + E-mail: {bcn, brian}@isi.edu + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/Z7 + Littleton, MA 01460 + Phone: +1 508 486 5210 + E-mail: wray@tuxedo.enet.dec.com + + Ari Medvinsky + Matthew Hur + CyberSafe Corporation + 1605 NW Sammamish Road Suite 310 + Issaquah WA 98027-5378 + Phone: +1 206 391 6000 + E-mail: {ari.medvinsky, matt.hur}@cybersafe.com + + Jonathan Trostle + Novell + E-mail: jonathan.trostle@novell.com diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt new file mode 100644 index 0000000..2284c3c --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt @@ -0,0 +1,8277 @@ + +INTERNET-DRAFT Clifford Neuman + John Kohl + Theodore Ts'o + 11 July 1997 + + + + The Kerberos Network Authentication Service (V5) + + +STATUS OF THIS MEMO + + This document is an Internet-Draft. 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." + + To learn the current status of any Internet-Draft, +please check the "1id-abstracts.txt" listing contained in +the Internet-Drafts Shadow Directories on ds.internic.net +(US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US +West Coast), or munnari.oz.au (Pacific Rim). + + The distribution of this memo is unlimited. It is +filed as draft-ietf-cat-kerberos-revisions-00.txt, and expires +11 January 1998. Please send comments to: + + krb-protocol@MIT.EDU + +ABSTRACT + + + This document provides an overview and specification of +Version 5 of the Kerberos protocol, and updates RFC1510 to +clarify aspects of the protocol and its intended use that +require more detailed or clearer explanation than was pro- +vided in RFC1510. This document is intended to provide a +detailed description of the protocol, suitable for implemen- +tation, together with descriptions of the appropriate use of +protocol messages and fields within those messages. + + This document is not intended to describe Kerberos to +__________________________ +Project Athena, Athena, and Kerberos are trademarks of +the Massachusetts Institute of Technology (MIT). No +commercial use of these trademarks may be made without +prior written permission of MIT. + + + +Overview - 1 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +the end user, system administrator, or application +developer. Higher level papers describing Version 5 of the +Kerberos system [1] and documenting version 4 [23], are +available elsewhere. + +OVERVIEW + + This INTERNET-DRAFT describes the concepts and model +upon which the Kerberos network authentication system is +based. It also specifies Version 5 of the Kerberos proto- +col. + + The motivations, goals, assumptions, and rationale +behind most design decisions are treated cursorily; they are +more fully described in a paper available in IEEE communica- +tions [1] and earlier in the Kerberos portion of the Athena +Technical Plan [2]. The protocols have been a proposed +standard and are being considered for advancement for draft +standard through the IETF standard process. Comments are +encouraged on the presentation, but only minor refinements +to the protocol as implemented or extensions that fit within +current protocol framework will be considered at this time. + + Requests for addition to an electronic mailing list for +discussion of Kerberos, kerberos@MIT.EDU, may be addressed +to kerberos-request@MIT.EDU. This mailing list is gatewayed +onto the Usenet as the group comp.protocols.kerberos. +Requests for further information, including documents and +code availability, may be sent to info-kerberos@MIT.EDU. + +BACKGROUND + + The Kerberos model is based in part on Needham and +Schroeder's trusted third-party authentication protocol [4] +and on modifications suggested by Denning and Sacco [5]. +The original design and implementation of Kerberos Versions +1 through 4 was the work of two former Project Athena staff +members, Steve Miller of Digital Equipment Corporation and +Clifford Neuman (now at the Information Sciences Institute +of the University of Southern California), along with Jerome +Saltzer, Technical Director of Project Athena, and Jeffrey +Schiller, MIT Campus Network Manager. Many other members of +Project Athena have also contributed to the work on Ker- +beros. + + Version 5 of the Kerberos protocol (described in this +document) has evolved from Version 4 based on new require- +ments and desires for features not available in Version 4. +The design of Version 5 of the Kerberos protocol was led by +Clifford Neuman and John Kohl with much input from the com- +munity. The development of the MIT reference implementation +was led at MIT by John Kohl and Theodore T'so, with help and +contributed code from many others. Reference implementa- +tions of both version 4 and version 5 of Kerberos are pub- +licly available and commercial implementations have been + +Overview - 2 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +developed and are widely used. + + Details on the differences between Kerberos Versions 4 +and 5 can be found in [6]. + +1. Introduction + + Kerberos provides a means of verifying the identities +of principals, (e.g. a workstation user or a network server) +on an open (unprotected) network. This is accomplished +without relying on assertions by the host operating system, +without basing trust on host addresses, without requiring +physical security of all the hosts on the network, and under +the assumption that packets traveling along the network can +be read, modified, and inserted at will[1]. Kerberos per- +forms authentication under these conditions as a trusted +third-party authentication service by using conventional +(shared secret key[2]) cryptography. Kerberos extensions +have been proposed and implemented that provide for the use +of public key cryptography during certain phases of the +authentication protocol. These extensions provide for +authentication of users registered with public key certifi- +cation authorities, and allow the system to provide certain +benefits of public key cryptography in situations where they +are needed. + + The basic Kerberos authentication process proceeds as +follows: A client sends a request to the authentication +server (AS) requesting "credentials" for a given server. +The AS responds with these credentials, encrypted in the +client's key. The credentials consist of 1) a "ticket" for +the server and 2) a temporary encryption key (often called a +"session key"). The client transmits the ticket (which con- +tains the client's identity and a copy of the session key, +all encrypted in the server's key) to the server. The ses- +sion key (now shared by the client and server) is used to +authenticate the client, and may optionally be used to +__________________________ +[1] Note, however, that many applications use Kerberos' +functions only upon the initiation of a stream-based +network connection. Unless an application subsequently +provides integrity protection for the data stream, the +identity verification applies only to the initiation of +the connection, and does not guarantee that subsequent +messages on the connection originate from the same +principal. +[2] Secret and private are often used interchangeably +in the literature. In our usage, it takes two (or +more) to share a secret, thus a shared DES key is a +secret key. Something is only private when no one but +its owner knows it. Thus, in public key cryptosystems, +one has a public and a private key. + + + +Section 1. - 3 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +authenticate the server. It may also be used to encrypt +further communication between the two parties or to exchange +a separate sub-session key to be used to encrypt further +communication. + + Implementation of the basic protocol consists of one or +more authentication servers running on physically secure +hosts. The authentication servers maintain a database of +principals (i.e., users and servers) and their secret keys. +Code libraries provide encryption and implement the Kerberos +protocol. In order to add authentication to its transac- +tions, a typical network application adds one or two calls +to the Kerberos library directly or through the Generic +Security Services Application Programming Interface, GSSAPI, +described in separate document. These calls result in the +transmission of the necessary messages to achieve authenti- +cation. + + The Kerberos protocol consists of several sub-protocols +(or exchanges). There are two basic methods by which a +client can ask a Kerberos server for credentials. In the +first approach, the client sends a cleartext request for a +ticket for the desired server to the AS. The reply is sent +encrypted in the client's secret key. Usually this request +is for a ticket-granting ticket (TGT) which can later be +used with the ticket-granting server (TGS). In the second +method, the client sends a request to the TGS. The client +uses the TGT to authenticate itself to the TGS in the same +manner as if it were contacting any other application server +that requires Kerberos authentication. The reply is +encrypted in the session key from the TGT. Though the pro- +tocol specification describes the AS and the TGS as separate +servers, they are implemented in practice as different pro- +tocol entry points within a single Kerberos server. + + Once obtained, credentials may be used to verify the +identity of the principals in a transaction, to ensure the +integrity of messages exchanged between them, or to preserve +privacy of the messages. The application is free to choose +whatever protection may be necessary. + + To verify the identities of the principals in a tran- +saction, the client transmits the ticket to the application +server. Since the ticket is sent "in the clear" (parts of +it are encrypted, but this encryption doesn't thwart replay) +and might be intercepted and reused by an attacker, addi- +tional information is sent to prove that the message ori- +ginated with the principal to whom the ticket was issued. +This information (called the authenticator) is encrypted in +the session key, and includes a timestamp. The timestamp +proves that the message was recently generated and is not a +replay. Encrypting the authenticator in the session key +proves that it was generated by a party possessing the ses- +sion key. Since no one except the requesting principal and + + +Section 1. - 4 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +the server know the session key (it is never sent over the +network in the clear) this guarantees the identity of the +client. + + The integrity of the messages exchanged between princi- +pals can also be guaranteed using the session key (passed in +the ticket and contained in the credentials). This approach +provides detection of both replay attacks and message stream +modification attacks. It is accomplished by generating and +transmitting a collision-proof checksum (elsewhere called a +hash or digest function) of the client's message, keyed with +the session key. Privacy and integrity of the messages +exchanged between principals can be secured by encrypting +the data to be passed using the session key contained in the +ticket or the subsession key found in the authenticator. + + The authentication exchanges mentioned above require +read-only access to the Kerberos database. Sometimes, how- +ever, the entries in the database must be modified, such as +when adding new principals or changing a principal's key. +This is done using a protocol between a client and a third +Kerberos server, the Kerberos Administration Server (KADM). +There is also a protocol for maintaining multiple copies of +the Kerberos database. Neither of these protocols are +described in this document. + +1.1. Cross-Realm Operation + + The Kerberos protocol is designed to operate across +organizational boundaries. A client in one organization can +be authenticated to a server in another. Each organization +wishing to run a Kerberos server establishes its own +"realm". The name of the realm in which a client is +registered is part of the client's name, and can be used by +the end-service to decide whether to honor a request. + + By establishing "inter-realm" keys, the administrators +of two realms can allow a client authenticated in the local +realm to prove its identity to servers in other realms[3]. +The exchange of inter-realm keys (a separate key may be used +for each direction) registers the ticket-granting service of +each realm as a principal in the other realm. A client is +then able to obtain a ticket-granting ticket for the remote +realm's ticket-granting service from its local realm. When +that ticket-granting ticket is used, the remote ticket- +granting service uses the inter-realm key (which usually +__________________________ +[3] Of course, with appropriate permission the client +could arrange registration of a separately-named prin- +cipal in a remote realm, and engage in normal exchanges +with that realm's services. However, for even small +numbers of clients this becomes cumbersome, and more +automatic methods as described here are necessary. + + +Section 1.1. - 5 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +differs from its own normal TGS key) to decrypt the ticket- +granting ticket, and is thus certain that it was issued by +the client's own TGS. Tickets issued by the remote ticket- +granting service will indicate to the end-service that the +client was authenticated from another realm. + + A realm is said to communicate with another realm if +the two realms share an inter-realm key, or if the local +realm shares an inter-realm key with an intermediate realm +that communicates with the remote realm. An authentication +path is the sequence of intermediate realms that are tran- +sited in communicating from one realm to another. + + Realms are typically organized hierarchically. Each +realm shares a key with its parent and a different key with +each child. If an inter-realm key is not directly shared by +two realms, the hierarchical organization allows an authen- +tication path to be easily constructed. If a hierarchical +organization is not used, it may be necessary to consult a +database in order to construct an authentication path +between realms. + + Although realms are typically hierarchical, intermedi- +ate realms may be bypassed to achieve cross-realm authenti- +cation through alternate authentication paths (these might +be established to make communication between two realms more +efficient). It is important for the end-service to know +which realms were transited when deciding how much faith to +place in the authentication process. To facilitate this +decision, a field in each ticket contains the names of the +realms that were involved in authenticating the client. + +1.2. Authorization + +As an authentication service, Kerberos provides a means of +verifying the identity of principals on a network. Authen- +tication is usually useful primarily as a first step in the +process of authorization, determining whether a client may +use a service, which objects the client is allowed to +access, and the type of access allowed for each. Kerberos +does not, by itself, provide authorization. Possession of a +client ticket for a service provides only for authentication +of the client to that service, and in the absence of a +separate authorization procedure, it should not be con- +sidered by an application as authorizing the use of that +service. + + Such separate authorization methods may be implemented +as application specific access control functions and may be +based on files such as the application server, or on +separately issued authorization credentials such as those +based on proxies [7] , or on other authorization services. + + Applications should not be modified to accept the +issuance of a service ticket by the Kerberos server (even by + +Section 1.2. - 6 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +an modified Kerberos server) as granting authority to use +the service, since such applications may become vulnerable +to the bypass of this authorization check in an environment +where they interoperate with other KDCs or where other +options for application authentication (e.g. the PKTAPP pro- +posal) are provided. + +1.3. Environmental assumptions + +Kerberos imposes a few assumptions on the environment in +which it can properly function: + ++ "Denial of service" attacks are not solved with Ker- + beros. There are places in these protocols where an + intruder can prevent an application from participating + in the proper authentication steps. Detection and + solution of such attacks (some of which can appear to + be not-uncommon "normal" failure modes for the system) + is usually best left to the human administrators and + users. + ++ Principals must keep their secret keys secret. If an + intruder somehow steals a principal's key, it will be + able to masquerade as that principal or impersonate any + server to the legitimate principal. + ++ "Password guessing" attacks are not solved by Kerberos. + If a user chooses a poor password, it is possible for + an attacker to successfully mount an offline dictionary + attack by repeatedly attempting to decrypt, with suc- + cessive entries from a dictionary, messages obtained + which are encrypted under a key derived from the user's + password. + ++ Each host on the network must have a clock which is + "loosely synchronized" to the time of the other hosts; + this synchronization is used to reduce the bookkeeping + needs of application servers when they do replay detec- + tion. The degree of "looseness" can be configured on a + per-server basis, but is typically on the order of 5 + minutes. If the clocks are synchronized over the net- + work, the clock synchronization protocol must itself be + secured from network attackers. + ++ Principal identifiers are not recycled on a short-term + basis. A typical mode of access control will use + access control lists (ACLs) to grant permissions to + particular principals. If a stale ACL entry remains + for a deleted principal and the principal identifier is + reused, the new principal will inherit rights specified + in the stale ACL entry. By not re-using principal + identifiers, the danger of inadvertent access is + removed. + + + +Section 1.3. - 7 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +1.4. Glossary of terms + +Below is a list of terms used throughout this document. + + +Authentication Verifying the claimed identity of a + principal. + + +Authentication headerA record containing a Ticket and an + Authenticator to be presented to a + server as part of the authentication + process. + + +Authentication path A sequence of intermediate realms tran- + sited in the authentication process when + communicating from one realm to another. + + +Authenticator A record containing information that can + be shown to have been recently generated + using the session key known only by the + client and server. + + +Authorization The process of determining whether a + client may use a service, which objects + the client is allowed to access, and the + type of access allowed for each. + + +Capability A token that grants the bearer permis- + sion to access an object or service. In + Kerberos, this might be a ticket whose + use is restricted by the contents of the + authorization data field, but which + lists no network addresses, together + with the session key necessary to use + the ticket. + + +Ciphertext The output of an encryption function. + Encryption transforms plaintext into + ciphertext. + + +Client A process that makes use of a network + service on behalf of a user. Note that + in some cases a Server may itself be a + client of some other server (e.g. a + print server may be a client of a file + server). + + + +Section 1.4. - 8 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +Credentials A ticket plus the secret session key + necessary to successfully use that + ticket in an authentication exchange. + + +KDC Key Distribution Center, a network ser- + vice that supplies tickets and temporary + session keys; or an instance of that + service or the host on which it runs. + The KDC services both initial ticket and + ticket-granting ticket requests. The + initial ticket portion is sometimes + referred to as the Authentication Server + (or service). The ticket-granting + ticket portion is sometimes referred to + as the ticket-granting server (or ser- + vice). + + +Kerberos Aside from the 3-headed dog guarding + Hades, the name given to Project + Athena's authentication service, the + protocol used by that service, or the + code used to implement the authentica- + tion service. + + +Plaintext The input to an encryption function or + the output of a decryption function. + Decryption transforms ciphertext into + plaintext. + + +Principal A uniquely named client or server + instance that participates in a network + communication. + + +Principal identifierThe name used to uniquely identify each + different principal. + + +Seal To encipher a record containing several + fields in such a way that the fields + cannot be individually replaced without + either knowledge of the encryption key + or leaving evidence of tampering. + + +Secret key An encryption key shared by a principal + and the KDC, distributed outside the + bounds of the system, with a long life- + time. In the case of a human user's + principal, the secret key is derived + + +Section 1.4. - 9 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + from a password. + + +Server A particular Principal which provides a + resource to network clients. The server + is sometimes refered to as the Applica- + tion Server. + + +Service A resource provided to network clients; + often provided by more than one server + (for example, remote file service). + + +Session key A temporary encryption key used between + two principals, with a lifetime limited + to the duration of a single login "ses- + sion". + + +Sub-session key A temporary encryption key used between + two principals, selected and exchanged + by the principals using the session key, + and with a lifetime limited to the dura- + tion of a single association. + + +Ticket A record that helps a client authenti- + cate itself to a server; it contains the + client's identity, a session key, a + timestamp, and other information, all + sealed using the server's secret key. + It only serves to authenticate a client + when presented along with a fresh + Authenticator. + +2. Ticket flag uses and requests + +Each Kerberos ticket contains a set of flags which are used +to indicate various attributes of that ticket. Most flags +may be requested by a client when the ticket is obtained; +some are automatically turned on and off by a Kerberos +server as required. The following sections explain what the +various flags mean, and gives examples of reasons to use +such a flag. + +2.1. Initial and pre-authenticated tickets + + The INITIAL flag indicates that a ticket was issued +using the AS protocol and not issued based on a ticket- +granting ticket. Application servers that want to require +the demonstrated knowledge of a client's secret key (e.g. a +password-changing program) can insist that this flag be set +in any tickets they accept, and thus be assured that the + + +Section 2.1. - 10 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +client's key was recently presented to the application +client. + + The PRE-AUTHENT and HW-AUTHENT flags provide addition +information about the initial authentication, regardless of +whether the current ticket was issued directly (in which +case INITIAL will also be set) or issued on the basis of a +ticket-granting ticket (in which case the INITIAL flag is +clear, but the PRE-AUTHENT and HW-AUTHENT flags are carried +forward from the ticket-granting ticket). + +2.2. Invalid tickets + + The INVALID flag indicates that a ticket is invalid. +Application servers must reject tickets which have this flag +set. A postdated ticket will usually be issued in this +form. Invalid tickets must be validated by the KDC before +use, by presenting them to the KDC in a TGS request with the +VALIDATE option specified. The KDC will only validate tick- +ets after their starttime has passed. The validation is +required so that postdated tickets which have been stolen +before their starttime can be rendered permanently invalid +(through a hot-list mechanism) (see section 3.3.3.1). + +2.3. Renewable tickets + + Applications may desire to hold tickets which can be +valid for long periods of time. However, this can expose +their credentials to potential theft for equally long +periods, and those stolen credentials would be valid until +the expiration time of the ticket(s). Simply using short- +lived tickets and obtaining new ones periodically would +require the client to have long-term access to its secret +key, an even greater risk. Renewable tickets can be used to +mitigate the consequences of theft. Renewable tickets have +two "expiration times": the first is when the current +instance of the ticket expires, and the second is the latest +permissible value for an individual expiration time. An +application client must periodically (i.e. before it +expires) present a renewable ticket to the KDC, with the +RENEW option set in the KDC request. The KDC will issue a +new ticket with a new session key and a later expiration +time. All other fields of the ticket are left unmodified by +the renewal process. When the latest permissible expiration +time arrives, the ticket expires permanently. At each +renewal, the KDC may consult a hot-list to determine if the +ticket had been reported stolen since its last renewal; it +will refuse to renew such stolen tickets, and thus the +usable lifetime of stolen tickets is reduced. + + The RENEWABLE flag in a ticket is normally only inter- +preted by the ticket-granting service (discussed below in +section 3.3). It can usually be ignored by application +servers. However, some particularly careful application + + +Section 2.3. - 11 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +servers may wish to disallow renewable tickets. + + If a renewable ticket is not renewed by its expiration +time, the KDC will not renew the ticket. The RENEWABLE flag +is reset by default, but a client may request it be set by +setting the RENEWABLE option in the KRB_AS_REQ message. If +it is set, then the renew-till field in the ticket contains +the time after which the ticket may not be renewed. + +2.4. Postdated tickets + + Applications may occasionally need to obtain tickets +for use much later, e.g. a batch submission system would +need tickets to be valid at the time the batch job is ser- +viced. However, it is dangerous to hold valid tickets in a +batch queue, since they will be on-line longer and more +prone to theft. Postdated tickets provide a way to obtain +these tickets from the KDC at job submission time, but to +leave them "dormant" until they are activated and validated +by a further request of the KDC. If a ticket theft were +reported in the interim, the KDC would refuse to validate +the ticket, and the thief would be foiled. + + The MAY-POSTDATE flag in a ticket is normally only +interpreted by the ticket-granting service. It can be +ignored by application servers. This flag must be set in a +ticket-granting ticket in order to issue a postdated ticket +based on the presented ticket. It is reset by default; it +may be requested by a client by setting the ALLOW-POSTDATE +option in the KRB_AS_REQ message. This flag does not allow +a client to obtain a postdated ticket-granting ticket; post- +dated ticket-granting tickets can only by obtained by +requesting the postdating in the KRB_AS_REQ message. The +life (endtime-starttime) of a postdated ticket will be the +remaining life of the ticket-granting ticket at the time of +the request, unless the RENEWABLE option is also set, in +which case it can be the full life (endtime-starttime) of +the ticket-granting ticket. The KDC may limit how far in +the future a ticket may be postdated. + + The POSTDATED flag indicates that a ticket has been +postdated. The application server can check the authtime +field in the ticket to see when the original authentication +occurred. Some services may choose to reject postdated +tickets, or they may only accept them within a certain +period after the original authentication. When the KDC +issues a POSTDATED ticket, it will also be marked as +INVALID, so that the application client must present the +ticket to the KDC to be validated before use. + +2.5. Proxiable and proxy tickets + + At times it may be necessary for a principal to allow a +service to perform an operation on its behalf. The service + + +Section 2.5. - 12 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +must be able to take on the identity of the client, but only +for a particular purpose. A principal can allow a service +to take on the principal's identity for a particular purpose +by granting it a proxy. + + The process of granting a proxy using the proxy and +proxiable flags is used to provide credentials for use with +specific services. Though conceptually also a proxy, user's +wishing to delegate their identity for ANY purpose must use +the ticket forwarding mechanism described in the next sec- +tion to forward a ticket granting ticket. + + The PROXIABLE flag in a ticket is normally only inter- +preted by the ticket-granting service. It can be ignored by +application servers. When set, this flag tells the ticket- +granting server that it is OK to issue a new ticket (but not +a ticket-granting ticket) with a different network address +based on this ticket. This flag is set if requested by the +client on initial authentication. By default, the client +will request that it be set when requesting a ticket grant- +ing ticket, and reset when requesting any other ticket. + + This flag allows a client to pass a proxy to a server +to perform a remote request on its behalf, e.g. a print ser- +vice client can give the print server a proxy to access the +client's files on a particular file server in order to +satisfy a print request. + + In order to complicate the use of stolen credentials, +Kerberos tickets are usually valid from only those network +addresses specifically included in the ticket[4]. When +granting a proxy, the client must specify the new network +address from which the proxy is to be used, or indicate that +the proxy is to be issued for use from any address. + + The PROXY flag is set in a ticket by the TGS when it +issues a proxy ticket. Application servers may check this +flag and at their option they may require additional authen- +tication from the agent presenting the proxy in order to +provide an audit trail. + +2.6. Forwardable tickets + + Authentication forwarding is an instance of a proxy +where the service is granted complete use of the client's +identity. An example where it might be used is when a user +logs in to a remote system and wants authentication to work +from that system as if the login were local. + + The FORWARDABLE flag in a ticket is normally only +__________________________ +[4] Though it is permissible to request or issue tick- +ets with no network addresses specified. + + +Section 2.6. - 13 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +interpreted by the ticket-granting service. It can be +ignored by application servers. The FORWARDABLE flag has an +interpretation similar to that of the PROXIABLE flag, except +ticket-granting tickets may also be issued with different +network addresses. This flag is reset by default, but users +may request that it be set by setting the FORWARDABLE option +in the AS request when they request their initial ticket- +granting ticket. + + This flag allows for authentication forwarding without +requiring the user to enter a password again. If the flag +is not set, then authentication forwarding is not permitted, +but the same result can still be achieved if the user +engages in the AS exchange specifying the requested network +addresses and supplies a password. + + The FORWARDED flag is set by the TGS when a client +presents a ticket with the FORWARDABLE flag set and requests +a forwarded ticket by specifying the FORWARDED KDC option +and supplying a set of addresses for the new ticket. It is +also set in all tickets issued based on tickets with the +FORWARDED flag set. Application servers may choose to pro- +cess FORWARDED tickets differently than non-FORWARDED tick- +ets. + +2.7. Other KDC options + + There are two additional options which may be set in a +client's request of the KDC. The RENEWABLE-OK option indi- +cates that the client will accept a renewable ticket if a +ticket with the requested life cannot otherwise be provided. +If a ticket with the requested life cannot be provided, then +the KDC may issue a renewable ticket with a renew-till equal +to the the requested endtime. The value of the renew-till +field may still be adjusted by site-determined limits or +limits imposed by the individual principal or server. + + The ENC-TKT-IN-SKEY option is honored only by the +ticket-granting service. It indicates that the ticket to be +issued for the end server is to be encrypted in the session +key from the a additional second ticket-granting ticket pro- +vided with the request. See section 3.3.3 for specific +details. + +__________________________ +[5] The password-changing request must not be honored +unless the requester can provide the old password (the +user's current secret key). Otherwise, it would be +possible for someone to walk up to an unattended ses- +sion and change another user's password. +[6] To authenticate a user logging on to a local sys- +tem, the credentials obtained in the AS exchange may +first be used in a TGS exchange to obtain credentials + + +Section 3.1. - 14 - Expires 11 January 1998 + + + + + + + Version 5 - Specification Revision 6 + + + +3. Message Exchanges + +The following sections describe the interactions between +network clients and servers and the messages involved in +those exchanges. + +3.1. The Authentication Service Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_AS_REQ 5.4.1 + 2. Kerberos to client KRB_AS_REP or 5.4.2 + KRB_ERROR 5.9.1 + + + The Authentication Service (AS) Exchange between the +client and the Kerberos Authentication Server is initiated +by a client when it wishes to obtain authentication creden- +tials for a given server but currently holds no credentials. +In its basic form, the client's secret key is used for en- +cryption and decryption. This exchange is typically used at +the initiation of a login session to obtain credentials for +a Ticket-Granting Server which will subsequently be used to +obtain credentials for other servers (see section 3.3) +without requiring further use of the client's secret key. +This exchange is also used to request credentials for ser- +vices which must not be mediated through the Ticket-Granting +Service, but rather require a principal's secret key, such +as the password-changing service[5]. This exchange does not +by itself provide any assurance of the the identity of the +user[6]. + + The exchange consists of two messages: KRB_AS_REQ from +the client to Kerberos, and KRB_AS_REP or KRB_ERROR in +reply. The formats for these messages are described in sec- +tions 5.4.1, 5.4.2, and 5.9.1. + + In the request, the client sends (in cleartext) its own +identity and the identity of the server for which it is +requesting credentials. The response, KRB_AS_REP, contains +a ticket for the client to present to the server, and a ses- +sion key that will be shared by the client and the server. +The session key and additional information are encrypted in +the client's secret key. The KRB_AS_REP message contains +information which can be used to detect replays, and to +associate it with the message to which it replies. Various +errors can occur; these are indicated by an error response +(KRB_ERROR) instead of the KRB_AS_REP response. The error +__________________________ +for a local server. Those credentials must then be +verified by a local server through successful comple- +tion of the Client/Server exchange. + + + +Section 3.1. - 15 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +message is not encrypted. The KRB_ERROR message contains +information which can be used to associate it with the mes- +sage to which it replies. The lack of encryption in the +KRB_ERROR message precludes the ability to detect replays, +fabrications, or modifications of such messages. + + Without preautentication, the authentication server +does not know whether the client is actually the principal +named in the request. It simply sends a reply without know- +ing or caring whether they are the same. This is acceptable +because nobody but the principal whose identity was given in +the request will be able to use the reply. Its critical +information is encrypted in that principal's key. The ini- +tial request supports an optional field that can be used to +pass additional information that might be needed for the +initial exchange. This field may be used for pre- +authentication as described in section <<sec preauth>>. + +3.1.1. Generation of KRB_AS_REQ message + + The client may specify a number of options in the ini- +tial request. Among these options are whether pre- +authentication is to be performed; whether the requested +ticket is to be renewable, proxiable, or forwardable; +whether it should be postdated or allow postdating of +derivative tickets; and whether a renewable ticket will be +accepted in lieu of a non-renewable ticket if the requested +ticket expiration date cannot be satisfied by a non- +renewable ticket (due to configuration constraints; see sec- +tion 4). See section A.1 for pseudocode. + + The client prepares the KRB_AS_REQ message and sends it +to the KDC. + +3.1.2. Receipt of KRB_AS_REQ message + + If all goes well, processing the KRB_AS_REQ message +will result in the creation of a ticket for the client to +present to the server. The format for the ticket is +described in section 5.3.1. The contents of the ticket are +determined as follows. + +3.1.3. Generation of KRB_AS_REP message + + The authentication server looks up the client and +server principals named in the KRB_AS_REQ in its database, +extracting their respective keys. If required, the server +pre-authenticates the request, and if the pre-authentication +check fails, an error message with the code +KDC_ERR_PREAUTH_FAILED is returned. If the server cannot +accommodate the requested encryption type, an error message +with code KDC_ERR_ETYPE_NOSUPP is returned. Otherwise it +generates a "random" session key[7]. +__________________________ + + +Section 3.1.3. - 16 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + If there are multiple encryption keys registered for a +client in the Kerberos database (or if the key registered +supports multiple encryption types; e.g. DES-CBC-CRC and +DES-CBC-MD5), then the etype field from the AS request is +used by the KDC to select the encryption method to be used +for encrypting the response to the client. If there is more +than one supported, strong encryption type in the etype +list, the first valid etype for which an encryption key is +available is used. The encryption method used to respond to +a TGS request is taken from the keytype of the session key +found in the ticket granting ticket. + + When the etype field is present in a KDC request, +whether an AS or TGS request, the KDC will attempt to assign +the type of the random session key from the list of methods +in the etype field. The KDC will select the appropriate +type using the list of methods provided together with infor- +mation from the Kerberos database indicating acceptable +encryption methods for the application server. The KDC will +not issue tickets with a weak session key encryption type. + + If the requested start time is absent, indicates a time +in the past, or is within the window of acceptable clock +skew for the KDC and the POSTDATE option has not been speci- +fied, then the start time of the ticket is set to the +authentication server's current time. If it indicates a +time in the future beyond the acceptable clock skew, but the +POSTDATED option has not been specified then the error +KDC_ERR_CANNOT_POSTDATE is returned. Otherwise the +requested start time is checked against the policy of the +local realm (the administrator might decide to prohibit cer- +tain types or ranges of postdated tickets), and if accept- +able, the ticket's start time is set as requested and the +INVALID flag is set in the new ticket. The postdated ticket +must be validated before use by presenting it to the KDC +after the start time has been reached. + + + + + + + + + +__________________________ +[7] "Random" means that, among other things, it should +be impossible to guess the next session key based on +knowledge of past session keys. This can only be +achieved in a pseudo-random number generator if it is +based on cryptographic principles. It is more desir- +able to use a truly random number generator, such as +one based on measurements of random physical phenomena. + + + +Section 3.1.3. - 17 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +The expiration time of the ticket will be set to the minimum +of the following: + ++The expiration time (endtime) requested in the KRB_AS_REQ + message. + ++The ticket's start time plus the maximum allowable lifetime + associated with the client principal (the authentication + server's database includes a maximum ticket lifetime field + in each principal's record; see section 4). + ++The ticket's start time plus the maximum allowable lifetime + associated with the server principal. + ++The ticket's start time plus the maximum lifetime set by + the policy of the local realm. + + If the requested expiration time minus the start time +(as determined above) is less than a site-determined minimum +lifetime, an error message with code KDC_ERR_NEVER_VALID is +returned. If the requested expiration time for the ticket +exceeds what was determined as above, and if the +"RENEWABLE-OK" option was requested, then the "RENEWABLE" +flag is set in the new ticket, and the renew-till value is +set as if the "RENEWABLE" option were requested (the field +and option names are described fully in section 5.4.1). + +If the RENEWABLE option has been requested or if the +RENEWABLE-OK option has been set and a renewable ticket is +to be issued, then the renew-till field is set to the +minimum of: + ++Its requested value. + ++The start time of the ticket plus the minimum of the two + maximum renewable lifetimes associated with the principals' + database entries. + ++The start time of the ticket plus the maximum renewable + lifetime set by the policy of the local realm. + + The flags field of the new ticket will have the follow- +ing options set if they have been requested and if the pol- +icy of the local realm allows: FORWARDABLE, MAY-POSTDATE, +POSTDATED, PROXIABLE, RENEWABLE. If the new ticket is post- +dated (the start time is in the future), its INVALID flag +will also be set. + + If all of the above succeed, the server formats a +KRB_AS_REP message (see section 5.4.2), copying the +addresses in the request into the caddr of the response, +placing any required pre-authentication data into the padata +of the response, and encrypts the ciphertext part in the +client's key using the requested encryption method, and + + +Section 3.1.3. - 18 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +sends it to the client. See section A.2 for pseudocode. + +3.1.4. Generation of KRB_ERROR message + + Several errors can occur, and the Authentication Server +responds by returning an error message, KRB_ERROR, to the +client, with the error-code and e-text fields set to +appropriate values. The error message contents and details +are described in Section 5.9.1. + +3.1.5. Receipt of KRB_AS_REP message + + If the reply message type is KRB_AS_REP, then the +client verifies that the cname and crealm fields in the +cleartext portion of the reply match what it requested. If +any padata fields are present, they may be used to derive +the proper secret key to decrypt the message. The client +decrypts the encrypted part of the response using its secret +key, verifies that the nonce in the encrypted part matches +the nonce it supplied in its request (to detect replays). +It also verifies that the sname and srealm in the response +match those in the request (or are otherwise expected +values), and that the host address field is also correct. +It then stores the ticket, session key, start and expiration +times, and other information for later use. The key- +expiration field from the encrypted part of the response may +be checked to notify the user of impending key expiration +(the client program could then suggest remedial action, such +as a password change). See section A.3 for pseudocode. + + Proper decryption of the KRB_AS_REP message is not suf- +ficient to verify the identity of the user; the user and an +attacker could cooperate to generate a KRB_AS_REP format +message which decrypts properly but is not from the proper +KDC. If the host wishes to verify the identity of the user, +it must require the user to present application credentials +which can be verified using a securely-stored secret key for +the host. If those credentials can be verified, then the +identity of the user can be assured. + +3.1.6. Receipt of KRB_ERROR message + + If the reply message type is KRB_ERROR, then the client +interprets it as an error and performs whatever +application-specific tasks are necessary to recover. + +3.2. The Client/Server Authentication Exchange + + Summary +Message direction Message type Section +Client to Application server KRB_AP_REQ 5.5.1 +[optional] Application server to client KRB_AP_REP or 5.5.2 + KRB_ERROR 5.9.1 + + + +Section 3.2. - 19 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + The client/server authentication (CS) exchange is used +by network applications to authenticate the client to the +server and vice versa. The client must have already +acquired credentials for the server using the AS or TGS +exchange. + +3.2.1. The KRB_AP_REQ message + + The KRB_AP_REQ contains authentication information +which should be part of the first message in an authenti- +cated transaction. It contains a ticket, an authenticator, +and some additional bookkeeping information (see section +5.5.1 for the exact format). The ticket by itself is insuf- +ficient to authenticate a client, since tickets are passed +across the network in cleartext[8], so the authenticator is +used to prevent invalid replay of tickets by proving to the +server that the client knows the session key of the ticket +and thus is entitled to use the ticket. The KRB_AP_REQ mes- +sage is referred to elsewhere as the "authentication +header." + +3.2.2. Generation of a KRB_AP_REQ message + + When a client wishes to initiate authentication to a +server, it obtains (either through a credentials cache, the +AS exchange, or the TGS exchange) a ticket and session key +for the desired service. The client may re-use any tickets +it holds until they expire. To use a ticket the client con- +structs a new Authenticator from the the system time, its +name, and optionally an application specific checksum, an +initial sequence number to be used in KRB_SAFE or KRB_PRIV +messages, and/or a session subkey to be used in negotiations +for a session key unique to this particular session. +Authenticators may not be re-used and will be rejected if +replayed to a server[9]. If a sequence number is to be +included, it should be randomly chosen so that even after +many messages have been exchanged it is not likely to col- +lide with other sequence numbers in use. + + The client may indicate a requirement of mutual +__________________________ +[8] Tickets contain both an encrypted and unencrypted +portion, so cleartext here refers to the entire unit, +which can be copied from one message and replayed in +another without any cryptographic skill. +[9] Note that this can make applications based on un- +reliable transports difficult to code correctly. If the +transport might deliver duplicated messages, either a +new authenticator must be generated for each retry, or +the application server must match requests and replies +and replay the first reply in response to a detected +duplicate. + + + +Section 3.2.2. - 20 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +authentication or the use of a session-key based ticket by +setting the appropriate flag(s) in the ap-options field of +the message. + + The Authenticator is encrypted in the session key and +combined with the ticket to form the KRB_AP_REQ message +which is then sent to the end server along with any addi- +tional application-specific information. See section A.9 +for pseudocode. + +3.2.3. Receipt of KRB_AP_REQ message + + Authentication is based on the server's current time of +day (clocks must be loosely synchronized), the authentica- +tor, and the ticket. Several errors are possible. If an +error occurs, the server is expected to reply to the client +with a KRB_ERROR message. This message may be encapsulated +in the application protocol if its "raw" form is not accept- +able to the protocol. The format of error messages is +described in section 5.9.1. + + The algorithm for verifying authentication information +is as follows. If the message type is not KRB_AP_REQ, the +server returns the KRB_AP_ERR_MSG_TYPE error. If the key +version indicated by the Ticket in the KRB_AP_REQ is not one +the server can use (e.g., it indicates an old key, and the +server no longer possesses a copy of the old key), the +KRB_AP_ERR_BADKEYVER error is returned. If the USE- +SESSION-KEY flag is set in the ap-options field, it indi- +cates to the server that the ticket is encrypted in the ses- +sion key from the server's ticket-granting ticket rather +than its secret key[10]. Since it is possible for the +server to be registered in multiple realms, with different +keys in each, the srealm field in the unencrypted portion of +the ticket in the KRB_AP_REQ is used to specify which secret +key the server should use to decrypt that ticket. The +KRB_AP_ERR_NOKEY error code is returned if the server +doesn't have the proper key to decipher the ticket. + + The ticket is decrypted using the version of the +server's key specified by the ticket. If the decryption +routines detect a modification of the ticket (each encryp- +tion system must provide safeguards to detect modified +ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY +error is returned (chances are good that different keys were +used to encrypt and decrypt). + + The authenticator is decrypted using the session key +extracted from the decrypted ticket. If decryption shows it +to have been modified, the KRB_AP_ERR_BAD_INTEGRITY error is +__________________________ +[10] This is used for user-to-user authentication as +described in [8]. + + +Section 3.2.3. - 21 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +returned. The name and realm of the client from the ticket +are compared against the same fields in the authenticator. +If they don't match, the KRB_AP_ERR_BADMATCH error is +returned (they might not match, for example, if the wrong +session key was used to encrypt the authenticator). The +addresses in the ticket (if any) are then searched for an +address matching the operating-system reported address of +the client. If no match is found or the server insists on +ticket addresses but none are present in the ticket, the +KRB_AP_ERR_BADADDR error is returned. + + If the local (server) time and the client time in the +authenticator differ by more than the allowable clock skew +(e.g., 5 minutes), the KRB_AP_ERR_SKEW error is returned. +If the server name, along with the client name, time and +microsecond fields from the Authenticator match any +recently-seen such tuples, the KRB_AP_ERR_REPEAT error is +returned[11]. The server must remember any authenticator +presented within the allowable clock skew, so that a replay +attempt is guaranteed to fail. If a server loses track of +any authenticator presented within the allowable clock skew, +it must reject all requests until the clock skew interval +has passed. This assures that any lost or re-played authen- +ticators will fall outside the allowable clock skew and can +no longer be successfully replayed (If this is not done, an +attacker could conceivably record the ticket and authentica- +tor sent over the network to a server, then disable the +client's host, pose as the disabled host, and replay the +ticket and authenticator to subvert the authentication.). +If a sequence number is provided in the authenticator, the +server saves it for later use in processing KRB_SAFE and/or +KRB_PRIV messages. If a subkey is present, the server +either saves it for later use or uses it to help generate +its own choice for a subkey to be returned in a KRB_AP_REP +message. + + The server computes the age of the ticket: local +(server) time minus the start time inside the Ticket. If +the start time is later than the current time by more than +the allowable clock skew or if the INVALID flag is set in +the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Oth- +erwise, if the current time is later than end time by more +than the allowable clock skew, the KRB_AP_ERR_TKT_EXPIRED +error is returned. + + If all these checks succeed without an error, the +__________________________ +[11] Note that the rejection here is restricted to au- +thenticators from the same principal to the same +server. Other client principals communicating with the +same server principal should not be have their authen- +ticators rejected if the time and microsecond fields +happen to match some other client's authenticator. + + +Section 3.2.3. - 22 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +server is assured that the client possesses the credentials +of the principal named in the ticket and thus, the client +has been authenticated to the server. See section A.10 for +pseudocode. + + Passing these checks provides only authentication of +the named principal; it does not imply authorization to use +the named service. Applications must make a separate +authorization decisions based upon the authenticated name of +the user, the requested operation, local acces control +information such as that contained in a .k5login or .k5users +file, and possibly a separate distributed authorization ser- +vice. + +3.2.4. Generation of a KRB_AP_REP message + + Typically, a client's request will include both the +authentication information and its initial request in the +same message, and the server need not explicitly reply to +the KRB_AP_REQ. However, if mutual authentication (not only +authenticating the client to the server, but also the server +to the client) is being performed, the KRB_AP_REQ message +will have MUTUAL-REQUIRED set in its ap-options field, and a +KRB_AP_REP message is required in response. As with the +error message, this message may be encapsulated in the +application protocol if its "raw" form is not acceptable to +the application's protocol. The timestamp and microsecond +field used in the reply must be the client's timestamp and +microsecond field (as provided in the authenticator)[12]. +If a sequence number is to be included, it should be ran- +domly chosen as described above for the authenticator. A +subkey may be included if the server desires to negotiate a +different subkey. The KRB_AP_REP message is encrypted in +the session key extracted from the ticket. See section A.11 +for pseudocode. + +3.2.5. Receipt of KRB_AP_REP message + + + If a KRB_AP_REP message is returned, the client uses +the session key from the credentials obtained for the +server[13] to decrypt the message, and verifies that the +__________________________ +[12] In the Kerberos version 4 protocol, the timestamp +in the reply was the client's timestamp plus one. This +is not necessary in version 5 because version 5 mes- +sages are formatted in such a way that it is not possi- +ble to create the reply by judicious message surgery +(even in encrypted form) without knowledge of the ap- +propriate encryption keys. +[13] Note that for encrypting the KRB_AP_REP message, +the sub-session key is not used, even if present in the +Authenticator. + + +Section 3.2.5. - 23 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +timestamp and microsecond fields match those in the Authen- +ticator it sent to the server. If they match, then the +client is assured that the server is genuine. The sequence +number and subkey (if present) are retained for later use. +See section A.12 for pseudocode. + + +3.2.6. Using the encryption key + + After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, +the client and server share an encryption key which can be +used by the application. The "true session key" to be used +for KRB_PRIV, KRB_SAFE, or other application-specific uses +may be chosen by the application based on the subkeys in the +KRB_AP_REP message and the authenticator[14]. In some +cases, the use of this session key will be implicit in the +protocol; in others the method of use must be chosen from +several alternatives. We leave the protocol negotiations of +how to use the key (e.g. selecting an encryption or check- +sum type) to the application programmer; the Kerberos proto- +col does not constrain the implementation options, but an +example of how this might be done follows. + + One way that an application may choose to negotiate a +key to be used for subequent integrity and privacy protec- +tion is for the client to propose a key in the subkey field +of the authenticator. The server can then choose a key +using the proposed key from the client as input, returning +the new subkey in the subkey field of the application reply. +This key could then be used for subsequent communication. +To make this example more concrete, if the encryption method +in use required a 56 bit key, and for whatever reason, one +of the parties was prevented from using a key with more than +40 unknown bits, this method would allow the the party which +is prevented from using more than 40 bits to either propose +(if the client) an initial key with a known quantity for 16 +of those bits, or to mask 16 of the bits (if the server) +with the known quantity. The application implementor is +warned, however, that this is only an example, and that an +analysis of the particular crytosystem to be used, and the +reasons for limiting the key length, must be made before +deciding whether it is acceptable to mask bits of the key. + + With both the one-way and mutual authentication +exchanges, the peers should take care not to send sensitive +information to each other without proper assurances. In +particular, applications that require privacy or integrity +should use the KRB_AP_REP response from the server to client +__________________________ +[14] Implementations of the protocol may wish to pro- +vide routines to choose subkeys based on session keys +and random numbers and to generate a negotiated key to +be returned in the KRB_AP_REP message. + + +Section 3.2.6. - 24 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +to assure both client and server of their peer's identity. +If an application protocol requires privacy of its messages, +it can use the KRB_PRIV message (section 3.5). The KRB_SAFE +message (section 3.4) can be used to assure integrity. + + +3.3. The Ticket-Granting Service (TGS) Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_TGS_REQ 5.4.1 + 2. Kerberos to client KRB_TGS_REP or 5.4.2 + KRB_ERROR 5.9.1 + + + The TGS exchange between a client and the Kerberos +Ticket-Granting Server is initiated by a client when it +wishes to obtain authentication credentials for a given +server (which might be registered in a remote realm), when +it wishes to renew or validate an existing ticket, or when +it wishes to obtain a proxy ticket. In the first case, the +client must already have acquired a ticket for the Ticket- +Granting Service using the AS exchange (the ticket-granting +ticket is usually obtained when a client initially authenti- +cates to the system, such as when a user logs in). The mes- +sage format for the TGS exchange is almost identical to that +for the AS exchange. The primary difference is that encryp- +tion and decryption in the TGS exchange does not take place +under the client's key. Instead, the session key from the +ticket-granting ticket or renewable ticket, or sub-session +key from an Authenticator is used. As is the case for all +application servers, expired tickets are not accepted by the +TGS, so once a renewable or ticket-granting ticket expires, +the client must use a separate exchange to obtain valid +tickets. + + The TGS exchange consists of two messages: A request +(KRB_TGS_REQ) from the client to the Kerberos Ticket- +Granting Server, and a reply (KRB_TGS_REP or KRB_ERROR). +The KRB_TGS_REQ message includes information authenticating +the client plus a request for credentials. The authentica- +tion information consists of the authentication header +(KRB_AP_REQ) which includes the client's previously obtained +ticket-granting, renewable, or invalid ticket. In the +ticket-granting ticket and proxy cases, the request may +include one or more of: a list of network addresses, a col- +lection of typed authorization data to be sealed in the +ticket for authorization use by the application server, or +additional tickets (the use of which are described later). +The TGS reply (KRB_TGS_REP) contains the requested creden- +tials, encrypted in the session key from the ticket-granting +ticket or renewable ticket, or if present, in the sub- +session key from the Authenticator (part of the authentica- +tion header). The KRB_ERROR message contains an error code + + +Section 3.3. - 25 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +and text explaining what went wrong. The KRB_ERROR message +is not encrypted. The KRB_TGS_REP message contains informa- +tion which can be used to detect replays, and to associate +it with the message to which it replies. The KRB_ERROR mes- +sage also contains information which can be used to associ- +ate it with the message to which it replies, but the lack of +encryption in the KRB_ERROR message precludes the ability to +detect replays or fabrications of such messages. + +3.3.1. Generation of KRB_TGS_REQ message + + Before sending a request to the ticket-granting ser- +vice, the client must determine in which realm the applica- +tion server is registered[15]. If the client does not +already possess a ticket-granting ticket for the appropriate +realm, then one must be obtained. This is first attempted +by requesting a ticket-granting ticket for the destination +realm from a Kerberos server for which the client does +posess a ticket-granting ticket (using the KRB_TGS_REQ mes- +sage recursively). The Kerberos server may return a TGT for +the desired realm in which case one can proceed. Alterna- +tively, the Kerberos server may return a TGT for a realm +which is "closer" to the desired realm (further along the +standard hierarchical path), in which case this step must be +repeated with a Kerberos server in the realm specified in +the returned TGT. If neither are returned, then the request +must be retried with a Kerberos server for a realm higher in +the hierarchy. This request will itself require a ticket- +granting ticket for the higher realm which must be obtained +by recursively applying these directions. + + + Once the client obtains a ticket-granting ticket for +the appropriate realm, it determines which Kerberos servers +serve that realm, and contacts one. The list might be +obtained through a configuration file or network service or +it may be generated from the name of the realm; as long as +the secret keys exchanged by realms are kept secret, only +denial of service results from using a false Kerberos +server. +__________________________ +[15] This can be accomplished in several ways. It +might be known beforehand (since the realm is part of +the principal identifier), it might be stored in a +nameserver, or it might be obtained from a configura- +tion file. If the realm to be used is obtained from a +nameserver, there is a danger of being spoofed if the +nameservice providing the realm name is not authenti- +cated. This might result in the use of a realm which +has been compromised, and would result in an attacker's +ability to compromise the authentication of the appli- +cation server to the client. + + + +Section 3.3.1. - 26 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + As in the AS exchange, the client may specify a number +of options in the KRB_TGS_REQ message. The client prepares +the KRB_TGS_REQ message, providing an authentication header +as an element of the padata field, and including the same +fields as used in the KRB_AS_REQ message along with several +optional fields: the enc-authorization-data field for appli- +cation server use and additional tickets required by some +options. + + In preparing the authentication header, the client can +select a sub-session key under which the response from the +Kerberos server will be encrypted[16]. If the sub-session +key is not specified, the session key from the ticket- +granting ticket will be used. If the enc-authorization-data +is present, it must be encrypted in the sub-session key, if +present, from the authenticator portion of the authentica- +tion header, or if not present, using the session key from +the ticket-granting ticket. + + Once prepared, the message is sent to a Kerberos server +for the destination realm. See section A.5 for pseudocode. + +3.3.2. Receipt of KRB_TGS_REQ message + + The KRB_TGS_REQ message is processed in a manner simi- +lar to the KRB_AS_REQ message, but there are many additional +checks to be performed. First, the Kerberos server must +determine which server the accompanying ticket is for and it +must select the appropriate key to decrypt it. For a normal +KRB_TGS_REQ message, it will be for the ticket granting ser- +vice, and the TGS's key will be used. If the TGT was issued +by another realm, then the appropriate inter-realm key must +be used. If the accompanying ticket is not a ticket grant- +ing ticket for the current realm, but is for an application +server in the current realm, the RENEW, VALIDATE, or PROXY +options are specified in the request, and the server for +which a ticket is requested is the server named in the +accompanying ticket, then the KDC will decrypt the ticket in +the authentication header using the key of the server for +which it was issued. If no ticket can be found in the +padata field, the KDC_ERR_PADATA_TYPE_NOSUPP error is +returned. + + Once the accompanying ticket has been decrypted, the +user-supplied checksum in the Authenticator must be verified +against the contents of the request, and the message +rejected if the checksums do not match (with an error code +__________________________ +[16] If the client selects a sub-session key, care must +be taken to ensure the randomness of the selected sub- +session key. One approach would be to generate a ran- +dom number and XOR it with the session key from the +ticket-granting ticket. + + +Section 3.3.2. - 27 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or +not collision-proof (with an error code of +KRB_AP_ERR_INAPP_CKSUM). If the checksum type is not sup- +ported, the KDC_ERR_SUMTYPE_NOSUPP error is returned. If +the authorization-data are present, they are decrypted using +the sub-session key from the Authenticator. + + If any of the decryptions indicate failed integrity +checks, the KRB_AP_ERR_BAD_INTEGRITY error is returned. + +3.3.3. Generation of KRB_TGS_REP message + + The KRB_TGS_REP message shares its format with the +KRB_AS_REP (KRB_KDC_REP), but with its type field set to +KRB_TGS_REP. The detailed specification is in section +5.4.2. + + The response will include a ticket for the requested +server. The Kerberos database is queried to retrieve the +record for the requested server (including the key with +which the ticket will be encrypted). If the request is for +a ticket granting ticket for a remote realm, and if no key +is shared with the requested realm, then the Kerberos server +will select the realm "closest" to the requested realm with +which it does share a key, and use that realm instead. This +is the only case where the response from the KDC will be for +a different server than that requested by the client. + + By default, the address field, the client's name and +realm, the list of transited realms, the time of initial +authentication, the expiration time, and the authorization +data of the newly-issued ticket will be copied from the +ticket-granting ticket (TGT) or renewable ticket. If the +transited field needs to be updated, but the transited type +is not supported, the KDC_ERR_TRTYPE_NOSUPP error is +returned. + + If the request specifies an endtime, then the endtime +of the new ticket is set to the minimum of (a) that request, +(b) the endtime from the TGT, and (c) the starttime of the +TGT plus the minimum of the maximum life for the application +server and the maximum life for the local realm (the maximum +life for the requesting principal was already applied when +the TGT was issued). If the new ticket is to be a renewal, +then the endtime above is replaced by the minimum of (a) the +value of the renew_till field of the ticket and (b) the +starttime for the new ticket plus the life (endtime- +starttime) of the old ticket. + + If the FORWARDED option has been requested, then the +resulting ticket will contain the addresses specified by the +client. This option will only be honored if the FORWARDABLE +flag is set in the TGT. The PROXY option is similar; the +resulting ticket will contain the addresses specified by the + + +Section 3.3.3. - 28 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +client. It will be honored only if the PROXIABLE flag in +the TGT is set. The PROXY option will not be honored on +requests for additional ticket-granting tickets. + + If the requested start time is absent, indicates a time +in the past, or is within the window of acceptable clock +skew for the KDC and the POSTDATE option has not been speci- +fied, then the start time of the ticket is set to the +authentication server's current time. If it indicates a +time in the future beyond the acceptable clock skew, but the +POSTDATED option has not been specified or the MAY-POSTDATE +flag is not set in the TGT, then the error +KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the +ticket-granting ticket has the MAY-POSTDATE flag set, then +the resulting ticket will be postdated and the requested +starttime is checked against the policy of the local realm. +If acceptable, the ticket's start time is set as requested, +and the INVALID flag is set. The postdated ticket must be +validated before use by presenting it to the KDC after the +starttime has been reached. However, in no case may the +starttime, endtime, or renew-till time of a newly-issued +postdated ticket extend beyond the renew-till time of the +ticket-granting ticket. + + If the ENC-TKT-IN-SKEY option has been specified and an +additional ticket has been included in the request, the KDC +will decrypt the additional ticket using the key for the +server to which the additional ticket was issued and verify +that it is a ticket-granting ticket. If the name of the +requested server is missing from the request, the name of +the client in the additional ticket will be used. Otherwise +the name of the requested server will be compared to the +name of the client in the additional ticket and if dif- +ferent, the request will be rejected. If the request +succeeds, the session key from the additional ticket will be +used to encrypt the new ticket that is issued instead of +using the key of the server for which the new ticket will be +used[17]. + + If the name of the server in the ticket that is +presented to the KDC as part of the authentication header is +not that of the ticket-granting server itself, the server is +registered in the realm of the KDC, and the RENEW option is +requested, then the KDC will verify that the RENEWABLE flag +is set in the ticket, that the INVALID flag is not set in +the ticket, and that the renew_till time is still in the +future. If the VALIDATE option is rqeuested, the KDC will +__________________________ +[17] This allows easy implementation of user-to-user +authentication [8], which uses ticket-granting ticket +session keys in lieu of secret server keys in situa- +tions where such secret keys could be easily comprom- +ised. + + +Section 3.3.3. - 29 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +check that the starttime has passed and the INVALID flag is +set. If the PROXY option is requested, then the KDC will +check that the PROXIABLE flag is set in the ticket. If the +tests succeed, and the ticket passes the hotlist check +described in the next paragraph, the KDC will issue the +appropriate new ticket. + + +3.3.3.1. Checking for revoked tickets + + Whenever a request is made to the ticket-granting +server, the presented ticket(s) is(are) checked against a +hot-list of tickets which have been canceled. This hot-list +might be implemented by storing a range of issue timestamps +for "suspect tickets"; if a presented ticket had an authtime +in that range, it would be rejected. In this way, a stolen +ticket-granting ticket or renewable ticket cannot be used to +gain additional tickets (renewals or otherwise) once the +theft has been reported. Any normal ticket obtained before +it was reported stolen will still be valid (because they +require no interaction with the KDC), but only until their +normal expiration time. + + The ciphertext part of the response in the KRB_TGS_REP +message is encrypted in the sub-session key from the Authen- +ticator, if present, or the session key key from the +ticket-granting ticket. It is not encrypted using the +client's secret key. Furthermore, the client's key's +expiration date and the key version number fields are left +out since these values are stored along with the client's +database record, and that record is not needed to satisfy a +request based on a ticket-granting ticket. See section A.6 +for pseudocode. + +3.3.3.2. Encoding the transited field + + If the identity of the server in the TGT that is +presented to the KDC as part of the authentication header is +that of the ticket-granting service, but the TGT was issued +from another realm, the KDC will look up the inter-realm key +shared with that realm and use that key to decrypt the +ticket. If the ticket is valid, then the KDC will honor the +request, subject to the constraints outlined above in the +section describing the AS exchange. The realm part of the +client's identity will be taken from the ticket-granting +ticket. The name of the realm that issued the ticket- +granting ticket will be added to the transited field of the +ticket to be issued. This is accomplished by reading the +transited field from the ticket-granting ticket (which is +treated as an unordered set of realm names), adding the new +realm to the set, then constructing and writing out its +encoded (shorthand) form (this may involve a rearrangement +of the existing encoding). + + + +Section 3.3.3.2. - 30 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + Note that the ticket-granting service does not add the +name of its own realm. Instead, its responsibility is to +add the name of the previous realm. This prevents a mali- +cious Kerberos server from intentionally leaving out its own +name (it could, however, omit other realms' names). + + The names of neither the local realm nor the +principal's realm are to be included in the transited field. +They appear elsewhere in the ticket and both are known to +have taken part in authenticating the principal. Since the +endpoints are not included, both local and single-hop +inter-realm authentication result in a transited field that +is empty. + + Because the name of each realm transited is added to +this field, it might potentially be very long. To decrease +the length of this field, its contents are encoded. The +initially supported encoding is optimized for the normal +case of inter-realm communication: a hierarchical arrange- +ment of realms using either domain or X.500 style realm +names. This encoding (called DOMAIN-X500-COMPRESS) is now +described. + + Realm names in the transited field are separated by a +",". The ",", "\", trailing "."s, and leading spaces (" ") +are special characters, and if they are part of a realm +name, they must be quoted in the transited field by preced- +ing them with a "\". + + A realm name ending with a "." is interpreted as being +prepended to the previous realm. For example, we can encode +traversal of EDU, MIT.EDU, ATHENA.MIT.EDU, WASHINGTON.EDU, +and CS.WASHINGTON.EDU as: + + "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". + +Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end- +points, that they would not be included in this field, and +we would have: + + "EDU,MIT.,WASHINGTON.EDU" + +A realm name beginning with a "/" is interpreted as being +appended to the previous realm[18]. If it is to stand by +itself, then it should be preceded by a space (" "). For +example, we can encode traversal of /COM/HP/APOLLO, /COM/HP, +/COM, and /COM/DEC as: + + "/COM,/HP,/APOLLO, /COM/DEC". +__________________________ +[18] For the purpose of appending, the realm preceding +the first listed realm is considered to be the null +realm (""). + + +Section 3.3.3.2. - 31 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +Like the example above, if /COM/HP/APOLLO and /COM/DEC are +endpoints, they they would not be included in this field, +and we would have: + + "/COM,/HP" + + + A null subfield preceding or following a "," indicates +that all realms between the previous realm and the next +realm have been traversed[19]. Thus, "," means that all +realms along the path between the client and the server have +been traversed. ",EDU, /COM," means that that all realms +from the client's realm up to EDU (in a domain style hierar- +chy) have been traversed, and that everything from /COM down +to the server's realm in an X.500 style has also been +traversed. This could occur if the EDU realm in one hierar- +chy shares an inter-realm key directly with the /COM realm +in another hierarchy. + +3.3.4. Receipt of KRB_TGS_REP message + +When the KRB_TGS_REP is received by the client, it is pro- +cessed in the same manner as the KRB_AS_REP processing +described above. The primary difference is that the cipher- +text part of the response must be decrypted using the ses- +sion key from the ticket-granting ticket rather than the +client's secret key. See section A.7 for pseudocode. + + +3.4. The KRB_SAFE Exchange + + The KRB_SAFE message may be used by clients requiring +the ability to detect modifications of messages they +exchange. It achieves this by including a keyed collision- +proof checksum of the user data and some control informa- +tion. The checksum is keyed with an encryption key (usually +the last key negotiated via subkeys, or the session key if +no negotiation has occured). + +3.4.1. Generation of a KRB_SAFE message + +When an application wishes to send a KRB_SAFE message, it +collects its data and the appropriate control information +and computes a checksum over them. The checksum algorithm +should be a keyed one-way hash function (such as the RSA- +MD5-DES checksum algorithm specified in section 6.4.5, or +the DES MAC), generated using the sub-session key if +present, or the session key. Different algorithms may be +__________________________ +[19] For the purpose of interpreting null subfields, +the client's realm is considered to precede those in +the transited field, and the server's realm is con- +sidered to follow them. + + +Section 3.4.1. - 32 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +selected by changing the checksum type in the message. +Unkeyed or non-collision-proof checksums are not suitable +for this use. + + The control information for the KRB_SAFE message +includes both a timestamp and a sequence number. The +designer of an application using the KRB_SAFE message must +choose at least one of the two mechanisms. This choice +should be based on the needs of the application protocol. + + Sequence numbers are useful when all messages sent will +be received by one's peer. Connection state is presently +required to maintain the session key, so maintaining the +next sequence number should not present an additional prob- +lem. + + If the application protocol is expected to tolerate +lost messages without them being resent, the use of the +timestamp is the appropriate replay detection mechanism. +Using timestamps is also the appropriate mechanism for +multi-cast protocols where all of one's peers share a common +sub-session key, but some messages will be sent to a subset +of one's peers. + + After computing the checksum, the client then transmits +the information and checksum to the recipient in the message +format specified in section 5.6.1. + +3.4.2. Receipt of KRB_SAFE message + +When an application receives a KRB_SAFE message, it verifies +it as follows. If any error occurs, an error code is +reported for use by the application. + + The message is first checked by verifying that the pro- +tocol version and type fields match the current version and +KRB_SAFE, respectively. A mismatch generates a +KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application verifies that the checksum used is a collision- +proof keyed checksum, and if it is not, a +KRB_AP_ERR_INAPP_CKSUM error is generated. The recipient +verifies that the operating system's report of the sender's +address matches the sender's address in the message, and (if +a recipient address is specified or the recipient requires +an address) that one of the recipient's addresses appears as +the recipient's address in the message. A failed match for +either case generates a KRB_AP_ERR_BADADDR error. Then the +timestamp and usec and/or the sequence number fields are +checked. If timestamp and usec are expected and not +present, or they are present but not current, the +KRB_AP_ERR_SKEW error is generated. If the server name, +along with the client name, time and microsecond fields from +the Authenticator match any recently-seen (sent or +received[20] ) such tuples, the KRB_AP_ERR_REPEAT error is +__________________________ +[20] This means that a client and server running on the + + + + + + + Version 5 - Specification Revision 6 + + +generated. If an incorrect sequence number is included, or +a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time- +stamp and usec or a sequence number is present, a +KRB_AP_ERR_MODIFIED error is generated. Finally, the check- +sum is computed over the data and control information, and +if it doesn't match the received checksum, a +KRB_AP_ERR_MODIFIED error is generated. + + If all the checks succeed, the application is assured +that the message was generated by its peer and was not modi- +fied in transit. + +3.5. The KRB_PRIV Exchange + + The KRB_PRIV message may be used by clients requiring +confidentiality and the ability to detect modifications of +exchanged messages. It achieves this by encrypting the mes- +sages and adding control information. + +3.5.1. Generation of a KRB_PRIV message + +When an application wishes to send a KRB_PRIV message, it +collects its data and the appropriate control information +(specified in section 5.7.1) and encrypts them under an +encryption key (usually the last key negotiated via subkeys, +or the session key if no negotiation has occured). As part +of the control information, the client must choose to use +either a timestamp or a sequence number (or both); see the +discussion in section 3.4.1 for guidelines on which to use. +After the user data and control information are encrypted, +the client transmits the ciphertext and some "envelope" +information to the recipient. + +3.5.2. Receipt of KRB_PRIV message + +When an application receives a KRB_PRIV message, it verifies +it as follows. If any error occurs, an error code is +reported for use by the application. + + The message is first checked by verifying that the pro- +tocol version and type fields match the current version and +KRB_PRIV, respectively. A mismatch generates a +KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application then decrypts the ciphertext and processes the +resultant plaintext. If decryption shows the data to have +been modified, a KRB_AP_ERR_BAD_INTEGRITY error is gen- +erated. The recipient verifies that the operating system's +report of the sender's address matches the sender's address +__________________________ +same host and communicating with one another using the +KRB_SAFE messages should not share a common replay +cache to detect KRB_SAFE replays. + + + +Section 3.5.2. - 34 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +in the message, and (if a recipient address is specified or +the recipient requires an address) that one of the +recipient's addresses appears as the recipient's address in +the message. A failed match for either case generates a +KRB_AP_ERR_BADADDR error. Then the timestamp and usec +and/or the sequence number fields are checked. If timestamp +and usec are expected and not present, or they are present +but not current, the KRB_AP_ERR_SKEW error is generated. If +the server name, along with the client name, time and +microsecond fields from the Authenticator match any +recently-seen such tuples, the KRB_AP_ERR_REPEAT error is +generated. If an incorrect sequence number is included, or +a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time- +stamp and usec or a sequence number is present, a +KRB_AP_ERR_MODIFIED error is generated. + + If all the checks succeed, the application can assume +the message was generated by its peer, and was securely +transmitted (without intruders able to see the unencrypted +contents). + +3.6. The KRB_CRED Exchange + + The KRB_CRED message may be used by clients requiring +the ability to send Kerberos credentials from one host to +another. It achieves this by sending the tickets together +with encrypted data containing the session keys and other +information associated with the tickets. + +3.6.1. Generation of a KRB_CRED message + +When an application wishes to send a KRB_CRED message it +first (using the KRB_TGS exchange) obtains credentials to be +sent to the remote host. It then constructs a KRB_CRED mes- +sage using the ticket or tickets so obtained, placing the +session key needed to use each ticket in the key field of +the corresponding KrbCredInfo sequence of the encrypted part +of the the KRB_CRED message. + + Other information associated with each ticket and +obtained during the KRB_TGS exchange is also placed in the +corresponding KrbCredInfo sequence in the encrypted part of +the KRB_CRED message. The current time and, if specifically +required by the application the nonce, s-address, and r- +address fields, are placed in the encrypted part of the +KRB_CRED message which is then encrypted under an encryption +key previosuly exchanged in the KRB_AP exchange (usually the +last key negotiated via subkeys, or the session key if no +negotiation has occured). + +3.6.2. Receipt of KRB_CRED message + +When an application receives a KRB_CRED message, it verifies + + +Section 3.6.2. - 35 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +it. If any error occurs, an error code is reported for use +by the application. The message is verified by checking +that the protocol version and type fields match the current +version and KRB_CRED, respectively. A mismatch generates a +KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application then decrypts the ciphertext and processes the +resultant plaintext. If decryption shows the data to have +been modified, a KRB_AP_ERR_BAD_INTEGRITY error is gen- +erated. + + If present or required, the recipient verifies that the +operating system's report of the sender's address matches +the sender's address in the message, and that one of the +recipient's addresses appears as the recipient's address in +the message. A failed match for either case generates a +KRB_AP_ERR_BADADDR error. The timestamp and usec fields +(and the nonce field if required) are checked next. If the +timestamp and usec are not present, or they are present but +not current, the KRB_AP_ERR_SKEW error is generated. + + If all the checks succeed, the application stores each +of the new tickets in its ticket cache together with the +session key and other information in the corresponding +KrbCredInfo sequence from the encrypted part of the KRB_CRED +message. + +4. The Kerberos Database + +The Kerberos server must have access to a database contain- +ing the principal identifiers and secret keys of principals +to be authenticated[21]. + +4.1. Database contents + +A database entry should contain at least the following +fields: + +Field Value + +name Principal's identif- +ier +key Principal's secret key +p_kvno Principal's key version +max_life Maximum lifetime for Tickets +__________________________ +[21] The implementation of the Kerberos server need not +combine the database and the server on the same +machine; it is feasible to store the principal database +in, say, a network name service, as long as the entries +stored therein are protected from disclosure to and +modification by unauthorized parties. However, we +recommend against such strategies, as they can make +system management and threat analysis quite complex. + + +Section 4.1. - 36 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +max_renewable_life Maximum total lifetime for renewable Tickets + +The name field is an encoding of the principal's identifier. +The key field contains an encryption key. This key is the +principal's secret key. (The key can be encrypted before +storage under a Kerberos "master key" to protect it in case +the database is compromised but the master key is not. In +that case, an extra field must be added to indicate the mas- +ter key version used, see below.) The p_kvno field is the +key version number of the principal's secret key. The +max_life field contains the maximum allowable lifetime (end- +time - starttime) for any Ticket issued for this principal. +The max_renewable_life field contains the maximum allowable +total lifetime for any renewable Ticket issued for this +principal. (See section 3.1 for a description of how these +lifetimes are used in determining the lifetime of a given +Ticket.) + + A server may provide KDC service to several realms, as +long as the database representation provides a mechanism to +distinguish between principal records with identifiers which +differ only in the realm name. + + When an application server's key changes, if the change +is routine (i.e. not the result of disclosure of the old +key), the old key should be retained by the server until all +tickets that had been issued using that key have expired. +Because of this, it is possible for several keys to be +active for a single principal. Ciphertext encrypted in a +principal's key is always tagged with the version of the key +that was used for encryption, to help the recipient find the +proper key for decryption. + + When more than one key is active for a particular prin- +cipal, the principal will have more than one record in the +Kerberos database. The keys and key version numbers will +differ between the records (the rest of the fields may or +may not be the same). Whenever Kerberos issues a ticket, or +responds to a request for initial authentication, the most +recent key (known by the Kerberos server) will be used for +encryption. This is the key with the highest key version +number. + +4.2. Additional fields + +Project Athena's KDC implementation uses additional fields +in its database: + +Field Value + +K_kvno Kerberos' key version +expiration Expiration date for entry +attributes Bit field of attributes +mod_date Timestamp of last modification + + +Section 4.2. - 37 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +mod_name Modifying principal's identifier + + +The K_kvno field indicates the key version of the Kerberos +master key under which the principal's secret key is +encrypted. + + After an entry's expiration date has passed, the KDC +will return an error to any client attempting to gain tick- +ets as or for the principal. (A database may want to main- +tain two expiration dates: one for the principal, and one +for the principal's current key. This allows password aging +to work independently of the principal's expiration date. +However, due to the limited space in the responses, the KDC +must combine the key expiration and principal expiration +date into a single value called "key_exp", which is used as +a hint to the user to take administrative action.) + + The attributes field is a bitfield used to govern the +operations involving the principal. This field might be +useful in conjunction with user registration procedures, for +site-specific policy implementations (Project Athena +currently uses it for their user registration process con- +trolled by the system-wide database service, Moira [9]), to +identify whether a principal can play the role of a client +or server or both, to note whether a server is appropriate +trusted to recieve credentials delegated by a client, or to +identify the "string to key" conversion algorithm used for a +principal's key[22]. Other bits are used to indicate that +certain ticket options should not be allowed in tickets +encrypted under a principal's key (one bit each): Disallow +issuing postdated tickets, disallow issuing forwardable +tickets, disallow issuing tickets based on TGT authentica- +tion, disallow issuing renewable tickets, disallow issuing +proxiable tickets, and disallow issuing tickets for which +the principal is the server. + + The mod_date field contains the time of last modifica- +tion of the entry, and the mod_name field contains the name +of the principal which last modified the entry. + +4.3. Frequently Changing Fields + + Some KDC implementations may wish to maintain the last +time that a request was made by a particular principal. +Information that might be maintained includes the time of +the last request, the time of the last request for a +ticket-granting ticket, the time of the last use of a +ticket-granting ticket, or other times. This information +can then be returned to the user in the last-req field (see +__________________________ +[22] See the discussion of the padata field in section +5.4.2 for details on why this can be useful. + + +Section 4.3. - 38 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +section 5.2). + + Other frequently changing information that can be main- +tained is the latest expiration time for any tickets that +have been issued using each key. This field would be used +to indicate how long old keys must remain valid to allow the +continued use of outstanding tickets. + +4.4. Site Constants + + The KDC implementation should have the following confi- +gurable constants or options, to allow an administrator to +make and enforce policy decisions: + ++ The minimum supported lifetime (used to determine whether + the KDC_ERR_NEVER_VALID error should be returned). This + constant should reflect reasonable expectations of + round-trip time to the KDC, encryption/decryption time, + and processing time by the client and target server, and + it should allow for a minimum "useful" lifetime. + ++ The maximum allowable total (renewable) lifetime of a + ticket (renew_till - starttime). + ++ The maximum allowable lifetime of a ticket (endtime - + starttime). + ++ Whether to allow the issue of tickets with empty address + fields (including the ability to specify that such tick- + ets may only be issued if the request specifies some + authorization_data). + ++ Whether proxiable, forwardable, renewable or post-datable + tickets are to be issued. + + +5. Message Specifications + + The following sections describe the exact contents and +encoding of protocol messages and objects. The ASN.1 base +definitions are presented in the first subsection. The +remaining subsections specify the protocol objects (tickets +and authenticators) and messages. Specification of encryp- +tion and checksum techniques, and the fields related to +them, appear in section 6. + +5.1. ASN.1 Distinguished Encoding Representation + + All uses of ASN.1 in Kerberos shall use the Dis- +tinguished Encoding Representation of the data elements as +described in the X.509 specification, section 8.7 [10]. + + + + + +Section 5.1. - 39 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +5.2. ASN.1 Base Definitions + + The following ASN.1 base definitions are used in the +rest of this section. Note that since the underscore char- +acter (_) is not permitted in ASN.1 names, the hyphen (-) is +used in its place for the purposes of ASN.1 names. + +Realm ::= GeneralString +PrincipalName ::= SEQUENCE { + name-type[0] INTEGER, + name-string[1] SEQUENCE OF GeneralString +} + + +Kerberos realms are encoded as GeneralStrings. Realms shall +not contain a character with the code 0 (the ASCII NUL). +Most realms will usually consist of several components +separated by periods (.), in the style of Internet Domain +Names, or separated by slashes (/) in the style of X.500 +names. Acceptable forms for realm names are specified in +section 7. A PrincipalName is a typed sequence of com- +ponents consisting of the following sub-fields: + +name-type This field specifies the type of name that fol- + lows. Pre-defined values for this field are + specified in section 7.2. The name-type should be + treated as a hint. Ignoring the name type, no two + names can be the same (i.e. at least one of the + components, or the realm, must be different). + This constraint may be eliminated in the future. + +name-stringThis field encodes a sequence of components that + form a name, each component encoded as a General- + String. Taken together, a PrincipalName and a + Realm form a principal identifier. Most Princi- + palNames will have only a few components (typi- + cally one or two). + + + + KerberosTime ::= GeneralizedTime + -- Specifying UTC time zone (Z) + + + The timestamps used in Kerberos are encoded as General- +izedTimes. An encoding shall specify the UTC time zone (Z) +and shall not include any fractional portions of the +seconds. It further shall not include any separators. +Example: The only valid format for UTC time 6 minutes, 27 +seconds after 9 pm on 6 November 1985 is 19851106210627Z. + + HostAddress ::= SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING + + +Section 5.2. - 40 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + } + + HostAddresses ::= SEQUENCE OF SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING + } + + + The host adddress encodings consists of two fields: + +addr-type This field specifies the type of address that + follows. Pre-defined values for this field are + specified in section 8.1. + + +address This field encodes a single address of type addr- + type. + +The two forms differ slightly. HostAddress contains exactly +one address; HostAddresses contains a sequence of possibly +many addresses. + +AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type[0] INTEGER, + ad-data[1] OCTET STRING +} + + +ad-data This field contains authorization data to be + interpreted according to the value of the + corresponding ad-type field. + +ad-type This field specifies the format for the ad-data + subfield. All negative values are reserved for + local use. Non-negative values are reserved for + registered use. + + APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) + } + + + TicketFlags ::= BIT STRING { + reserved(0), + forwardable(1), + forwarded(2), + proxiable(3), + proxy(4), + may-postdate(5), + postdated(6), + invalid(7), + renewable(8), + initial(9), + + +Section 5.2. - 41 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + pre-authent(10), + hw-authent(11), + transited-policy-checked(12), + ok-as-delegate(13) + } + + + KDCOptions ::= BIT STRING { + 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), + unused12(12), + unused13(13), + disable-transited-check(26), + renewable-ok(27), + enc-tkt-in-skey(28), + renew(30), + validate(31) + } + + ASN.1 Bit strings have a length and a value. When + used in Kerberos for the APOptions, TicketFlags, + and KDCOptions, the length of the bit string on + generated values should be the smallest multiple + of 32 bits needed to include the highest order bit + that is set (1), but in no case less than 32 bits. + Implementations should accept values of bit + strings of any length and treat the value of flags + cooresponding to bits beyond the end of the bit + string as if the bit were reset (0). Comparisonof + bit strings of different length should treat the + smaller string as if it were padded with zeros + beyond the high order bits to the length of the + longer string[23]. + +__________________________ +[23] Warning for implementations that unpack and repack +data structures during the generation and verification +of embedded checksums: Because any checksums applied to +data structures must be checked against the original +data the length of bit strings must be preserved within +a data structure between the time that a checksum is +generated through transmission to the time that the +checksum is verified. + + + +Section 5.2. - 42 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + LastReq ::= SEQUENCE OF SEQUENCE { + lr-type[0] INTEGER, + lr-value[1] KerberosTime + } + + +lr-type This field indicates how the following lr-value + field is to be interpreted. Negative values indi- + cate that the information pertains only to the + responding server. Non-negative values pertain to + all servers for the realm. + + If the lr-type field is zero (0), then no informa- + tion is conveyed by the lr-value subfield. If the + absolute value of the lr-type field is one (1), + then the lr-value subfield is the time of last + initial request for a TGT. If it is two (2), then + the lr-value subfield is the time of last initial + request. If it is three (3), then the lr-value + subfield is the time of issue for the newest + ticket-granting ticket used. If it is four (4), + then the lr-value subfield is the time of the last + renewal. If it is five (5), then the lr-value + subfield is the time of last request (of any + type). + + +lr-value This field contains the time of the last request. + The time must be interpreted according to the con- + tents of the accompanying lr-type subfield. + + See section 6 for the definitions of Checksum, Check- +sumType, EncryptedData, EncryptionKey, EncryptionType, and +KeyType. + + +5.3. Tickets and Authenticators + + This section describes the format and encryption param- +eters for tickets and authenticators. When a ticket or +authenticator is included in a protocol message it is +treated as an opaque object. + +5.3.1. Tickets + + A ticket is a record that helps a client authenticate +to a service. A Ticket contains the following information: + +Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno[0] INTEGER, + realm[1] Realm, + sname[2] PrincipalName, + enc-part[3] EncryptedData +} + + +Section 5.3.1. - 43 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +-- Encrypted part of ticket +EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL +} +-- encoded Transited field +TransitedEncoding ::= SEQUENCE { + tr-type[0] INTEGER, -- must be registered + contents[1] OCTET STRING +} + +The encoding of EncTicketPart is encrypted in the key shared +by Kerberos and the end server (the server's secret key). +See section 6 for the format of the ciphertext. + +tkt-vno This field specifies the version number for the + ticket format. This document describes version + number 5. + + +realm This field specifies the realm that issued a + ticket. It also serves to identify the realm part + of the server's principal identifier. Since a + Kerberos server can only issue tickets for servers + within its realm, the two will always be identi- + cal. + + +sname This field specifies the name part of the server's + identity. + + +enc-part This field holds the encrypted encoding of the + EncTicketPart sequence. + + +flags This field indicates which of various options were + used or requested when the ticket was issued. It + is a bit-field, where the selected options are + indicated by the bit being set (1), and the + unselected options and reserved fields being reset + (0). Bit 0 is the most significant bit. The + encoding of the bits is specified in section 5.2. + The flags are described in more detail above in + section 2. The meanings of the flags are: + + +Section 5.3.1. - 44 - Expires 11 January 1998 + + + + + + Version 5 - Specification Revision 6 + + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. When set, this + flag tells the ticket-granting server + that it is OK to issue a new ticket- + granting ticket with a different network + address based on the presented ticket. + + 2 FORWARDED + When set, this flag indicates that the + ticket has either been forwarded or was + issued based on authentication involving + a forwarded ticket-granting ticket. + + 3 PROXIABLE + The PROXIABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. The PROXIABLE + flag has an interpretation identical to + that of the FORWARDABLE flag, except + that the PROXIABLE flag tells the + ticket-granting server that only non- + ticket-granting tickets may be issued + with different network addresses. + + 4 PROXY + When set, this flag indicates that a + ticket is a proxy. + + 5 MAY-POSTDATE + The MAY-POSTDATE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. This flag tells + the ticket-granting server that a post- + dated ticket may be issued based on this + ticket-granting ticket. + + 6 POSTDATED + This flag indicates that this ticket has + been postdated. The end-service can + check the authtime field to see when the + original authentication occurred. + + 7 INVALID + This flag indicates that a ticket is + invalid, and it must be validated by the + KDC before use. Application servers + must reject tickets which have this flag + set. + + + + + + + + +Section 5.3.1. - 45 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 8 RENEWABLE + The RENEWABLE flag is normally only + interpreted by the TGS, and can usually + be ignored by end servers (some particu- + larly careful servers may wish to disal- + low renewable tickets). A renewable + ticket can be used to obtain a replace- + ment ticket that expires at a later + date. + + 9 INITIAL + This flag indicates that this ticket was + issued using the AS protocol, and not + issued based on a ticket-granting + ticket. + + 10 PRE-AUTHENT + This flag indicates that during initial + authentication, the client was authenti- + cated by the KDC before a ticket was + issued. The strength of the pre- + authentication method is not indicated, + but is acceptable to the KDC. + + 11 HW-AUTHENT + This flag indicates that the protocol + employed for initial authentication + required the use of hardware expected to + be possessed solely by the named client. + The hardware authentication method is + selected by the KDC and the strength of + the method is not indicated. + + + + +Section 5.3.1. - 46 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 12 TRANSITED This flag indicates that the KDC for the + POLICY-CHECKED realm has checked the transited field + against a realm defined policy for + trusted certifiers. If this flag is + reset (0), then the application server + must check the transited field itself, + and if unable to do so it must reject + the authentication. If the flag is set + (1) then the application server may skip + its own validation of the transited + field, relying on the validation + performed by the KDC. At its option the + application server may still apply its + own validation based on a separate + policy for acceptance. + +Section 5.3.1. - 47 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 13 OK-AS-DELEGATE This flag indicates that the server (not + the client) specified in the ticket has + been determined by policy of the realm + to be a suitable recipient of + delegation. A client can use the + presence of this flag to help it make a + decision whether to delegate credentials + (either grant a proxy or a forwarded + ticket granting ticket) to this server. + The client is free to ignore the value + of this flag. When setting this flag, + an administrator should consider the + security and placement of the server on + which the service will run, as well as + whether the service requires the use of + delegated credentials. + + + + +Section 5.3.1. - 48 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 14 ANONYMOUS + This flag indicates that the principal + named in the ticket is a generic princi- + pal for the realm and does not identify + the individual using the ticket. The + purpose of the ticket is only to + securely distribute a session key, and + not to identify the user. Subsequent + requests using the same ticket and ses- + sion may be considered as originating + from the same user, but requests with + the same username but a different ticket + are likely to originate from different + users. + + 15-31 RESERVED + Reserved for future use. + + + +key This field exists in the ticket and the KDC + response and is used to pass the session key from + Kerberos to the application server and the client. + The field's encoding is described in section 6.2. + +crealm This field contains the name of the realm in which + the client is registered and in which initial + authentication took place. + + +cname This field contains the name part of the client's + principal identifier. + + +transited This field lists the names of the Kerberos realms + that took part in authenticating the user to whom + this ticket was issued. It does not specify the + order in which the realms were transited. See + section 3.3.3.2 for details on how this field + encodes the traversed realms. + + +authtime This field indicates the time of initial authenti- + cation for the named principal. It is the time of + issue for the original ticket on which this ticket + is based. It is included in the ticket to provide + additional information to the end service, and to + provide the necessary information for implementa- + tion of a `hot list' service at the KDC. An end + service that is particularly paranoid could refuse + to accept tickets for which the initial authenti- + cation occurred "too far" in the past. + + This field is also returned as part of the + response from the KDC. When returned as part of + the response to initial authentication + + +Section 5.3.1. - 49 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + (KRB_AS_REP), this is the current time on the Ker- + beros server[24]. + + +starttime This field in the ticket specifies the time after + which the ticket is valid. Together with endtime, + this field specifies the life of the ticket. If + it is absent from the ticket, its value should be + treated as that of the authtime field. + + +endtime This field contains the time after which the + ticket will not be honored (its expiration time). + Note that individual services may place their own + limits on the life of a ticket and may reject + tickets which have not yet expired. As such, this + is really an upper bound on the expiration time + for the ticket. + + +renew-tillThis field is only present in tickets that have + the RENEWABLE flag set in the flags field. It + indicates the maximum endtime that may be included + in a renewal. It can be thought of as the abso- + lute expiration time for the ticket, including all + renewals. + + +caddr This field in a ticket contains zero (if omitted) + or more (if present) host addresses. These are + the addresses from which the ticket can be used. + If there are no addresses, the ticket can be used + from any location. The decision by the KDC to + issue or by the end server to accept zero-address + tickets is a policy decision and is left to the + Kerberos and end-service administrators; they may + refuse to issue or accept such tickets. The sug- + gested and default policy, however, is that such + tickets will only be issued or accepted when addi- + tional information that can be used to restrict + the use of the ticket is included in the + authorization_data field. Such a ticket is a + capability. + + Network addresses are included in the ticket to + make it harder for an attacker to use stolen + credentials. Because the session key is not sent + over the network in cleartext, credentials can't +__________________________ +[24] It is NOT recommended that this time value be used +to adjust the workstation's clock since the workstation +cannot reliably determine that such a KRB_AS_REP actu- +ally came from the proper KDC in a timely manner. + + +Section 5.3.1. - 50 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + be stolen simply by listening to the network; an + attacker has to gain access to the session key + (perhaps through operating system security + breaches or a careless user's unattended session) + to make use of stolen tickets. + + It is important to note that the network address + from which a connection is received cannot be + reliably determined. Even if it could be, an + attacker who has compromised the client's worksta- + tion could use the credentials from there. + Including the network addresses only makes it more + difficult, not impossible, for an attacker to walk + off with stolen credentials and then use them from + a "safe" location. + + +authorization-data + The authorization-data field is used to pass + authorization data from the principal on whose + behalf a ticket was issued to the application ser- + vice. If no authorization data is included, this + field will be left out. Experience has shown that + the name of this field is confusing, and that a + better name for this field would be restrictions. + Unfortunately, it is not possible to change the + name of this field at this time. + + This field contains restrictions on any authority + obtained on the bases of authentication using the + ticket. It is possible for any principal in + posession of credentials to add entries to the + authorization data field since these entries + further restrict what can be done with the ticket. + Such additions can be made by specifying the addi- + tional entries when a new ticket is obtained dur- + ing the TGS exchange, or they may be added during + chained delegation using the authorization data + field of the authenticator. + + Because entries may be added to this field by the + holder of credentials, it is not allowable for the + presence of an entry in the authorization data + field of a ticket to amplify the priveleges one + would obtain from using a ticket. + + The data in this field may be specific to the end + service; the field will contain the names of ser- + vice specific objects, and the rights to those + objects. The format for this field is described + in section 5.2. Although Kerberos is not con- + cerned with the format of the contents of the sub- + fields, it does carry type information (ad-type). + + + +Section 5.3.1. - 51 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + By using the authorization_data field, a principal + is able to issue a proxy that is valid for a + specific purpose. For example, a client wishing + to print a file can obtain a file server proxy to + be passed to the print server. By specifying the + name of the file in the authorization_data field, + the file server knows that the print server can + only use the client's rights when accessing the + particular file to be printed. + + A separate service providing providing authoriza- + tion or certifying group membership may be built + using the authorization-data field. In this case, + the entity granting authorization (not the author- + ized entity), obtains a ticket in its own name + (e.g. the ticket is issued in the name of a + privelege server), and this entity adds restric- + tions on its own authority and delegates the res- + tricted authority through a proxy to the client. + The client would then present this authorization + credential to the application server separately + from the authentication exchange. + + Similarly, if one specifies the authorization-data + field of a proxy and leaves the host addresses + blank, the resulting ticket and session key can be + treated as a capability. See [7] for some sug- + gested uses of this field. + + The authorization-data field is optional and does + not have to be included in a ticket. + + +5.3.2. Authenticators + + An authenticator is a record sent with a ticket to a +server to certify the client's knowledge of the encryption +key in the ticket, to help the server detect replays, and to +help choose a "true session key" to use with the particular +session. The encoding is encrypted in the ticket's session +key shared by the client and the server: + +-- Unencrypted authenticator +Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL +} + + + +Section 5.3.2. - 52 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +authenticator-vno + This field specifies the version number for the + format of the authenticator. This document speci- + fies version 5. + + +crealm and cname + These fields are the same as those described for + the ticket in section 5.3.1. + + +cksum This field contains a checksum of the the applica- + tion data that accompanies the KRB_AP_REQ. + + +cusec This field contains the microsecond part of the + client's timestamp. Its value (before encryption) + ranges from 0 to 999999. It often appears along + with ctime. The two fields are used together to + specify a reasonably accurate timestamp. + + +ctime This field contains the current time on the + client's host. + + +subkey This field contains the client's choice for an + encryption key which is to be used to protect this + specific application session. Unless an applica- + tion specifies otherwise, if this field is left + out the session key from the ticket will be used. + +seq-numberThis optional field includes the initial sequence + number to be used by the KRB_PRIV or KRB_SAFE mes- + sages when sequence numbers are used to detect + replays (It may also be used by application + specific messages). When included in the authen- + ticator this field specifies the initial sequence + number for messages from the client to the server. + When included in the AP-REP message, the initial + sequence number is that for messages from the + server to the client. When used in KRB_PRIV or + KRB_SAFE messages, it is incremented by one after + each message is sent. + + For sequence numbers to adequately support the + detection of replays they should be non-repeating, + even across connection boundaries. The initial + sequence number should be random and uniformly + distributed across the full space of possible + sequence numbers, so that it cannot be guessed by + an attacker and so that it and the successive + sequence numbers do not repeat other sequences. + + + +Section 5.3.2. - 53 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +authorization-data + This field is the same as described for the ticket + in section 5.3.1. It is optional and will only + appear when additional restrictions are to be + placed on the use of a ticket, beyond those car- + ried in the ticket itself. + +5.4. Specifications for the AS and TGS exchanges + + This section specifies the format of the messages used +in the exchange between the client and the Kerberos server. +The format of possible error messages appears in section +5.9.1. + +5.4.1. KRB_KDC_REQ definition + + The KRB_KDC_REQ message has no type of its own. +Instead, its type is one of KRB_AS_REQ or KRB_TGS_REQ +depending on whether the request is for an initial ticket or +an additional ticket. In either case, the message is sent +from the client to the Authentication Server to request +credentials for a service. + + The message fields are: + +AS-REQ ::= [APPLICATION 10] KDC-REQ +TGS-REQ ::= [APPLICATION 12] KDC-REQ + +KDC-REQ ::= SEQUENCE { + pvno[1] INTEGER, + msg-type[2] INTEGER, + padata[3] SEQUENCE OF PA-DATA OPTIONAL, + req-body[4] KDC-REQ-BODY +} + +PA-DATA ::= SEQUENCE { + padata-type[1] INTEGER, + padata-value[2] OCTET STRING, + -- might be encoded AP-REQ +} + +KDC-REQ-BODY ::= SEQUENCE { + kdc-options[0] KDCOptions, + cname[1] PrincipalName OPTIONAL, + -- Used only in AS-REQ + realm[2] Realm, -- Server's realm + -- Also client's in AS-REQ + sname[3] PrincipalName OPTIONAL, + from[4] KerberosTime OPTIONAL, + till[5] KerberosTime OPTIONAL, + rtime[6] KerberosTime OPTIONAL, + nonce[7] INTEGER, + etype[8] SEQUENCE OF INTEGER, + -- EncryptionType, + -- in preference order + + +Section 5.4.1. - 54 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + addresses[9] HostAddresses OPTIONAL, + enc-authorization-data[10] EncryptedData OPTIONAL, + -- Encrypted AuthorizationData + -- encoding + additional-tickets[11] SEQUENCE OF Ticket OPTIONAL +} + +The fields in this message are: + + +pvno This field is included in each message, and speci- + fies the protocol version number. This document + specifies protocol version 5. + + +msg-type This field indicates the type of a protocol mes- + sage. It will almost always be the same as the + application identifier associated with a message. + It is included to make the identifier more readily + accessible to the application. For the KDC-REQ + message, this type will be KRB_AS_REQ or + KRB_TGS_REQ. + + +padata The padata (pre-authentication data) field con- + tains a sequence of authentication information + which may be needed before credentials can be + issued or decrypted. In the case of requests for + additional tickets (KRB_TGS_REQ), this field will + include an element with padata-type of PA-TGS-REQ + and data of an authentication header (ticket- + granting ticket and authenticator). The checksum + in the authenticator (which must be collision- + proof) is to be computed over the KDC-REQ-BODY + encoding. In most requests for initial authenti- + cation (KRB_AS_REQ) and most replies (KDC-REP), + the padata field will be left out. + + This field may also contain information needed by + certain extensions to the Kerberos protocol. For + example, it might be used to initially verify the + identity of a client before any response is + returned. This is accomplished with a padata + field with padata-type equal to PA-ENC-TIMESTAMP + and padata-value defined as follows: + +padata-type ::= PA-ENC-TIMESTAMP +padata-value ::= EncryptedData -- PA-ENC-TS-ENC + +PA-ENC-TS-ENC ::= SEQUENCE { + patimestamp[0] KerberosTime, -- client's time + pausec[1] INTEGER OPTIONAL +} + + with patimestamp containing the client's time and + + +Section 5.4.1. - 55 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + pausec containing the microseconds which may be + omitted if a client will not generate more than + one request per second. The ciphertext (padata- + value) consists of the PA-ENC-TS-ENC sequence, + encrypted using the client's secret key. + + The padata field can also contain information + needed to help the KDC or the client select the + key needed for generating or decrypting the + response. This form of the padata is useful for + supporting the use of certain token cards with + Kerberos. The details of such extensions are + specified in separate documents. See [11] for + additional uses of this field. + +padata-type + The padata-type element of the padata field indi- + cates the way that the padata-value element is to + be interpreted. Negative values of padata-type + are reserved for unregistered use; non-negative + values are used for a registered interpretation of + the element type. + + +req-body This field is a placeholder delimiting the extent + of the remaining fields. If a checksum is to be + calculated over the request, it is calculated over + an encoding of the KDC-REQ-BODY sequence which is + enclosed within the req-body field. + + +kdc-options + This field appears in the KRB_AS_REQ and + KRB_TGS_REQ requests to the KDC and indicates the + flags that the client wants set on the tickets as + well as other information that is to modify the + behavior of the KDC. Where appropriate, the name + of an option may be the same as the flag that is + set by that option. Although in most case, the + bit in the options field will be the same as that + in the flags field, this is not guaranteed, so it + is not acceptable to simply copy the options field + to the flags field. There are various checks that + must be made before honoring an option anyway. + + The kdc_options field is a bit-field, where the + selected options are indicated by the bit being + set (1), and the unselected options and reserved + fields being reset (0). The encoding of the bits + is specified in section 5.2. The options are + described in more detail above in section 2. The + meanings of the options are: + + + + +Section 5.4.1. - 56 - Expires 11 January 1998 + + + + + Version 5 - Specification Revision 6 + + + Bit(s) Name Description + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE option indicates that + the ticket to be issued is to have its + forwardable flag set. It may only be + set on the initial request, or in a sub- + sequent request if the ticket-granting + ticket on which it is based is also for- + wardable. + + 2 FORWARDED + The FORWARDED option is only specified + in a request to the ticket-granting + server and will only be honored if the + ticket-granting ticket in the request + has its FORWARDABLE bit set. This + option indicates that this is a request + for forwarding. The address(es) of the + host from which the resulting ticket is + to be valid are included in the + addresses field of the request. + + 3 PROXIABLE + The PROXIABLE option indicates that the + ticket to be issued is to have its prox- + iable flag set. It may only be set on + the initial request, or in a subsequent + request if the ticket-granting ticket on + which it is based is also proxiable. + + 4 PROXY + The PROXY option indicates that this is + a request for a proxy. This option will + only be honored if the ticket-granting + ticket in the request has its PROXIABLE + bit set. The address(es) of the host + from which the resulting ticket is to be + valid are included in the addresses + field of the request. + + 5 ALLOW-POSTDATE + The ALLOW-POSTDATE option indicates that + the ticket to be issued is to have its + MAY-POSTDATE flag set. It may only be + set on the initial request, or in a sub- + sequent request if the ticket-granting + ticket on which it is based also has its + MAY-POSTDATE flag set. + + + + + + + +Section 5.4.1. - 57 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 6 POSTDATED + The POSTDATED option indicates that this + is a request for a postdated ticket. + This option will only be honored if the + ticket-granting ticket on which it is + based has its MAY-POSTDATE flag set. + The resulting ticket will also have its + INVALID flag set, and that flag may be + reset by a subsequent request to the KDC + after the starttime in the ticket has + been reached. + + 7 UNUSED + This option is presently unused. + + 8 RENEWABLE + The RENEWABLE option indicates that the + ticket to be issued is to have its + RENEWABLE flag set. It may only be set + on the initial request, or when the + ticket-granting ticket on which the + request is based is also renewable. If + this option is requested, then the rtime + field in the request contains the + desired absolute expiration time for the + ticket. + + 9-13 UNUSED + These options are presently unused. + + 14 REQUEST-ANONYMOUS + The REQUEST-ANONYMOUS option indicates + that the ticket to be issued is not to + identify the user to which it was + issued. Instead, the principal identif- + ier is to be generic, as specified by + the policy of the realm (e.g. usually + anonymous@realm). The purpose of the + ticket is only to securely distribute a + session key, and not to identify the + user. The ANONYMOUS flag on the ticket + to be returned should be set. If the + local realms policy does not permit + anonymous credentials, the request is to + be rejected. + + 15-25 RESERVED + Reserved for future use. + + 26 DISABLE-TRANSITED-CHECK + By default the KDC will check the + transited field of a ticket-granting- + ticket against the policy of the local + realm before it will issue derivative + tickets based on the ticket granting + ticket. If this flag is set in the + request, checking of the transited field + is disabled. Tickets issued without the + performance of this check will be noted + by the reset (0) value of the + TRANSITED-POLICY-CHECKED flag, + indicating to the application server + that the tranisted field must be checked + locally. KDC's are encouraged but not + required to honor the + DISABLE-TRANSITED-CHECK option. + + + +Section 5.4.1. - 58 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + 27 RENEWABLE-OK + The RENEWABLE-OK option indicates that a + renewable ticket will be acceptable if a + ticket with the requested life cannot + otherwise be provided. If a ticket with + the requested life cannot be provided, + then a renewable ticket may be issued + with a renew-till equal to the the + requested endtime. The value of the + renew-till field may still be limited by + local limits, or limits selected by the + individual principal or server. + + 28 ENC-TKT-IN-SKEY + This option is used only by the ticket- + granting service. The ENC-TKT-IN-SKEY + option indicates that the ticket for the + end server is to be encrypted in the + session key from the additional ticket- + granting ticket provided. + + 29 RESERVED + Reserved for future use. + + 30 RENEW + This option is used only by the ticket- + granting service. The RENEW option + indicates that the present request is + for a renewal. The ticket provided is + encrypted in the secret key for the + server on which it is valid. This + option will only be honored if the + ticket to be renewed has its RENEWABLE + flag set and if the time in its renew- + till field has not passed. The ticket + to be renewed is passed in the padata + field as part of the authentication + header. + + 31 VALIDATE + This option is used only by the ticket- + granting service. The VALIDATE option + indicates that the request is to vali- + date a postdated ticket. It will only + be honored if the ticket presented is + postdated, presently has its INVALID + flag set, and would be otherwise usable + at this time. A ticket cannot be vali- + dated before its starttime. The ticket + presented for validation is encrypted in + the key of the server for which it is + valid and is passed in the padata field + as part of the authentication header. + +cname and sname + These fields are the same as those described for + the ticket in section 5.3.1. sname may only be + + +Section 5.4.1. - 59 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + absent when the ENC-TKT-IN-SKEY option is speci- + fied. If absent, the name of the server is taken + from the name of the client in the ticket passed + as additional-tickets. + + +enc-authorization-data + The enc-authorization-data, if present (and it can + only be present in the TGS_REQ form), is an encod- + ing of the desired authorization-data encrypted + under the sub-session key if present in the + Authenticator, or alternatively from the session + key in the ticket-granting ticket, both from the + padata field in the KRB_AP_REQ. + + +realm This field specifies the realm part of the + server's principal identifier. In the AS + exchange, this is also the realm part of the + client's principal identifier. + + +from This field is included in the KRB_AS_REQ and + KRB_TGS_REQ ticket requests when the requested + ticket is to be postdated. It specifies the + desired start time for the requested ticket. + + + +till This field contains the expiration date requested + by the client in a ticket request. It is option + and if omitted the requested ticket is to have the + maximum endtime permitted according to KDC policy + for the parties to the authentication exchange as + limited by expiration date of the ticket granting + ticket or other preauthentication credentials. + + +rtime This field is the requested renew-till time sent + from a client to the KDC in a ticket request. It + is optional. + + +nonce This field is part of the KDC request and + response. It it intended to hold a random number + generated by the client. If the same number is + included in the encrypted response from the KDC, + it provides evidence that the response is fresh + and has not been replayed by an attacker. Nonces + must never be re-used. Ideally, it should be gen- + erated randomly, but if the correct time is known, + it may suffice[25]. +__________________________ +[25] Note, however, that if the time is used as the + +Section 5.4.1. - 60 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +etype This field specifies the desired encryption algo- + rithm to be used in the response. + + +addresses This field is included in the initial request for + tickets, and optionally included in requests for + additional tickets from the ticket-granting + server. It specifies the addresses from which the + requested ticket is to be valid. Normally it + includes the addresses for the client's host. If + a proxy is requested, this field will contain + other addresses. The contents of this field are + usually copied by the KDC into the caddr field of + the resulting ticket. + + +additional-tickets + Additional tickets may be optionally included in a + request to the ticket-granting server. If the + ENC-TKT-IN-SKEY option has been specified, then + the session key from the additional ticket will be + used in place of the server's key to encrypt the + new ticket. If more than one option which + requires additional tickets has been specified, + then the additional tickets are used in the order + specified by the ordering of the options bits (see + kdc-options, above). + + + The application code will be either ten (10) or twelve +(12) depending on whether the request is for an initial +ticket (AS-REQ) or for an additional ticket (TGS-REQ). + + The optional fields (addresses, authorization-data and +additional-tickets) are only included if necessary to per- +form the operation specified in the kdc-options field. + + It should be noted that in KRB_TGS_REQ, the protocol +version number appears twice and two different message types +appear: the KRB_TGS_REQ message contains these fields as +does the authentication header (KRB_AP_REQ) that is passed +in the padata field. + +5.4.2. KRB_KDC_REP definition + + The KRB_KDC_REP message format is used for the reply +from the KDC for either an initial (AS) request or a subse- +quent (TGS) request. There is no message type for +__________________________ +nonce, one must make sure that the workstation time is +monotonically increasing. If the time is ever reset +backwards, there is a small, but finite, probability +that a nonce will be reused. + + + +Section 5.4.2. - 61 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or +KRB_TGS_REP. The key used to encrypt the ciphertext part of +the reply depends on the message type. For KRB_AS_REP, the +ciphertext is encrypted in the client's secret key, and the +client's key version number is included in the key version +number for the encrypted data. For KRB_TGS_REP, the cipher- +text is encrypted in the sub-session key from the Authenti- +cator, or if absent, the session key from the ticket- +granting ticket used in the request. In that case, no ver- +sion number will be present in the EncryptedData sequence. + + The KRB_KDC_REP message contains the following fields: + +AS-REP ::= [APPLICATION 11] KDC-REP +TGS-REP ::= [APPLICATION 13] KDC-REP + +KDC-REP ::= SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + padata[2] SEQUENCE OF PA-DATA OPTIONAL, + crealm[3] Realm, + cname[4] PrincipalName, + ticket[5] Ticket, + enc-part[6] EncryptedData +} + + +EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart +EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart + + + +EncKDCRepPart ::= SEQUENCE { + key[0] EncryptionKey, + last-req[1] LastReq, + nonce[2] INTEGER, + key-expiration[3] KerberosTime OPTIONAL, + flags[4] TicketFlags, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + srealm[9] Realm, + sname[10] PrincipalName, + caddr[11] HostAddresses OPTIONAL +} + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is either KRB_AS_REP or KRB_TGS_REP. +__________________________ +[27] An application code in the encrypted part of a +message provides an additional check that the message +was decrypted properly. + + +Section 5.4.2. - 62 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +padata This field is described in detail in section + 5.4.1. One possible use for this field is to + encode an alternate "mix-in" string to be used + with a string-to-key algorithm (such as is + described in section 6.3.2). This ability is use- + ful to ease transitions if a realm name needs to + change (e.g. when a company is acquired); in such + a case all existing password-derived entries in + the KDC database would be flagged as needing a + special mix-in string until the next password + change. + + +crealm, cname, srealm and sname + These fields are the same as those described for + the ticket in section 5.3.1. + + +ticket The newly-issued ticket, from section 5.3.1. + + +enc-part This field is a place holder for the ciphertext + and related information that forms the encrypted + part of a message. The description of the + encrypted part of the message follows each appear- + ance of this field. The encrypted part is encoded + as described in section 6.1. + + +key This field is the same as described for the ticket + in section 5.3.1. + + +last-req This field is returned by the KDC and specifies + the time(s) of the last request by a principal. + Depending on what information is available, this + might be the last time that a request for a + ticket-granting ticket was made, or the last time + that a request based on a ticket-granting ticket + was successful. It also might cover all servers + for a realm, or just the particular server. Some + implementations may display this information to + the user to aid in discovering unauthorized use of + one's identity. It is similar in spirit to the + last login time displayed when logging into + timesharing systems. + + +nonce This field is described above in section 5.4.1. + + +key-expiration + The key-expiration field is part of the response + from the KDC and specifies the time that the + + +Section 5.4.2. - 63 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + client's secret key is due to expire. The expira- + tion might be the result of password aging or an + account expiration. This field will usually be + left out of the TGS reply since the response to + the TGS request is encrypted in a session key and + no client information need be retrieved from the + KDC database. It is up to the application client + (usually the login program) to take appropriate + action (such as notifying the user) if the expira- + tion time is imminent. + + +flags, authtime, starttime, endtime, renew-till and caddr + These fields are duplicates of those found in the + encrypted portion of the attached ticket (see sec- + tion 5.3.1), provided so the client may verify + they match the intended request and to assist in + proper ticket caching. If the message is of type + KRB_TGS_REP, the caddr field will only be filled + in if the request was for a proxy or forwarded + ticket, or if the user is substituting a subset of + the addresses from the ticket granting ticket. If + the client-requested addresses are not present or + not used, then the addresses contained in the + ticket will be the same as those included in the + ticket-granting ticket. + + +5.5. Client/Server (CS) message specifications + + This section specifies the format of the messages used +for the authentication of the client to the application +server. + +5.5.1. KRB_AP_REQ definition + + The KRB_AP_REQ message contains the Kerberos protocol +version number, the message type KRB_AP_REQ, an options +field to indicate any options in use, and the ticket and +authenticator themselves. The KRB_AP_REQ message is often +referred to as the "authentication header". + +AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData +} + +APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) + + +Section 5.5.1. - 64 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +} + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_AP_REQ. + + +ap-optionsThis field appears in the application request + (KRB_AP_REQ) and affects the way the request is + processed. It is a bit-field, where the selected + options are indicated by the bit being set (1), + and the unselected options and reserved fields + being reset (0). The encoding of the bits is + specified in section 5.2. The meanings of the + options are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 USE-SESSION-KEY + The USE-SESSION-KEY option indicates + that the ticket the client is presenting + to a server is encrypted in the session + key from the server's ticket-granting + ticket. When this option is not speci- + fied, the ticket is encrypted in the + server's secret key. + + 2 MUTUAL-REQUIRED + The MUTUAL-REQUIRED option tells the + server that the client requires mutual + authentication, and that it must respond + with a KRB_AP_REP message. + + 3-31 RESERVED + Reserved for future use. + + + +ticket This field is a ticket authenticating the client + to the server. + + +authenticator + This contains the authenticator, which includes + the client's choice of a subkey. Its encoding is + described in section 5.3.2. + +5.5.2. KRB_AP_REP definition + + The KRB_AP_REP message contains the Kerberos protocol +version number, the message type, and an encrypted time- +stamp. The message is sent in in response to an application +request (KRB_AP_REQ) where the mutual authentication option + + +Section 5.5.2. - 65 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +has been selected in the ap-options field. + +AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[2] EncryptedData +} + +EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { + ctime[0] KerberosTime, + cusec[1] INTEGER, + subkey[2] EncryptionKey OPTIONAL, + seq-number[3] INTEGER OPTIONAL +} + +The encoded EncAPRepPart is encrypted in the shared session +key of the ticket. The optional subkey field can be used in +an application-arranged negotiation to choose a per associa- +tion session key. + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_AP_REP. + + +enc-part This field is described above in section 5.4.2. + + +ctime This field contains the current time on the + client's host. + + +cusec This field contains the microsecond part of the + client's timestamp. + + +subkey This field contains an encryption key which is to + be used to protect this specific application ses- + sion. See section 3.2.6 for specifics on how this + field is used to negotiate a key. Unless an + application specifies otherwise, if this field is + left out, the sub-session key from the authentica- + tor, or if also left out, the session key from the + ticket will be used. + + + +__________________________ +[29] An application code in the encrypted part of a +message provides an additional check that the message +was decrypted properly. + + + +Section 5.5.2. - 66 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +5.5.3. Error message reply + + If an error occurs while processing the application +request, the KRB_ERROR message will be sent in response. +See section 5.9.1 for the format of the error message. The +cname and crealm fields may be left out if the server cannot +determine their appropriate values from the corresponding +KRB_AP_REQ message. If the authenticator was decipherable, +the ctime and cusec fields will contain the values from it. + +5.6. KRB_SAFE message specification + + This section specifies the format of a message that can +be used by either side (client or server) of an application +to send a tamper-proof message to its peer. It presumes +that a session key has previously been exchanged (for exam- +ple, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.6.1. KRB_SAFE definition + + The KRB_SAFE message contains user data along with a +collision-proof checksum keyed with the last encryption key +negotiated via subkeys, or the session key if no negotiation +has occured. The message fields are: + +KRB-SAFE ::= [APPLICATION 20] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + safe-body[2] KRB-SAFE-BODY, + cksum[3] Checksum +} + +KRB-SAFE-BODY ::= SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + + + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_SAFE. + + +safe-body This field is a placeholder for the body of the + KRB-SAFE message. It is to be encoded separately + and then have the checksum computed over it, for + use in the cksum field. + + + +Section 5.6.1. - 67 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +cksum This field contains the checksum of the applica- + tion data. Checksum details are described in sec- + tion 6.4. The checksum is computed over the + encoding of the KRB-SAFE-BODY sequence. + + +user-data This field is part of the KRB_SAFE and KRB_PRIV + messages and contain the application specific data + that is being passed from the sender to the reci- + pient. + + +timestamp This field is part of the KRB_SAFE and KRB_PRIV + messages. Its contents are the current time as + known by the sender of the message. By checking + the timestamp, the recipient of the message is + able to make sure that it was recently generated, + and is not a replay. + + +usec This field is part of the KRB_SAFE and KRB_PRIV + headers. It contains the microsecond part of the + timestamp. + + +seq-number + This field is described above in section 5.3.2. + + +s-address This field specifies the address in use by the + sender of the message. + + +r-address This field specifies the address in use by the + recipient of the message. It may be omitted for + some uses (such as broadcast protocols), but the + recipient may arbitrarily reject such messages. + This field along with s-address can be used to + help detect messages which have been incorrectly + or maliciously delivered to the wrong recipient. + +5.7. KRB_PRIV message specification + + This section specifies the format of a message that can +be used by either side (client or server) of an application +to securely and privately send a message to its peer. It +presumes that a session key has previously been exchanged +(for example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.7.1. KRB_PRIV definition + + The KRB_PRIV message contains user data encrypted in +the Session Key. The message fields are: + +__________________________ +[31] An application code in the encrypted part of a + + + + + + + Version 5 - Specification Revision 6 + + + +KRB-PRIV ::= [APPLICATION 21] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[3] EncryptedData +} + +EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, -- sender's addr + r-address[5] HostAddress OPTIONAL -- recip's addr +} + + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_PRIV. + + +enc-part This field holds an encoding of the EncKrbPrivPart + sequence encrypted under the session key[32]. + This encrypted encoding is used for the enc-part + field of the KRB-PRIV message. See section 6 for + the format of the ciphertext. + + +user-data, timestamp, usec, s-address and r-address + These fields are described above in section 5.6.1. + + +seq-number + This field is described above in section 5.3.2. + +5.8. KRB_CRED message specification + + This section specifies the format of a message that can +be used to send Kerberos credentials from one principal to +__________________________ +message provides an additional check that the message +was decrypted properly. +[32] If supported by the encryption method in use, an +initialization vector may be passed to the encryption +procedure, in order to achieve proper cipher chaining. +The initialization vector might come from the last +block of the ciphertext from the previous KRB_PRIV mes- +sage, but it is the application's choice whether or not +to use such an initialization vector. If left out, the +default initialization vector for the encryption algo- +rithm will be used. + + +Section 5.8. - 69 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +another. It is presented here to encourage a common mechan- +ism to be used by applications when forwarding tickets or +providing proxies to subordinate servers. It presumes that +a session key has already been exchanged perhaps by using +the KRB_AP_REQ/KRB_AP_REP messages. + +5.8.1. KRB_CRED definition + + The KRB_CRED message contains a sequence of tickets to +be sent and information needed to use the tickets, including +the session key from each. The information needed to use +the tickets is encrypted under an encryption key previously +exchanged or transferred alongside the KRB_CRED message. +The message fields are: + +KRB-CRED ::= [APPLICATION 22] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, -- KRB_CRED + tickets[2] SEQUENCE OF Ticket, + enc-part[3] EncryptedData +} + +EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { + ticket-info[0] SEQUENCE OF KrbCredInfo, + nonce[1] INTEGER OPTIONAL, + timestamp[2] KerberosTime OPTIONAL, + usec[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +KrbCredInfo ::= SEQUENCE { + key[0] EncryptionKey, + prealm[1] Realm OPTIONAL, + pname[2] PrincipalName OPTIONAL, + flags[3] TicketFlags OPTIONAL, + authtime[4] KerberosTime OPTIONAL, + starttime[5] KerberosTime OPTIONAL, + endtime[6] KerberosTime OPTIONAL + renew-till[7] KerberosTime OPTIONAL, + srealm[8] Realm OPTIONAL, + sname[9] PrincipalName OPTIONAL, + caddr[10] HostAddresses OPTIONAL +} + + + + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_CRED. + + + + +Section 5.8.1. - 70 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +tickets + These are the tickets obtained from the KDC + specifically for use by the intended recipient. + Successive tickets are paired with the correspond- + ing KrbCredInfo sequence from the enc-part of the + KRB-CRED message. + + +enc-part This field holds an encoding of the EncKrbCredPart + sequence encrypted under the session key shared + between the sender and the intended recipient. + This encrypted encoding is used for the enc-part + field of the KRB-CRED message. See section 6 for + the format of the ciphertext. + + +nonce If practical, an application may require the + inclusion of a nonce generated by the recipient of + the message. If the same value is included as the + nonce in the message, it provides evidence that + the message is fresh and has not been replayed by + an attacker. A nonce must never be re-used; it + should be generated randomly by the recipient of + the message and provided to the sender of the mes- + sage in an application specific manner. + + +timestamp and usec + + These fields specify the time that the KRB-CRED + message was generated. The time is used to pro- + vide assurance that the message is fresh. + + +s-address and r-address + These fields are described above in section 5.6.1. + They are used optionally to provide additional + assurance of the integrity of the KRB-CRED mes- + sage. + + +key This field exists in the corresponding ticket + passed by the KRB-CRED message and is used to pass + the session key from the sender to the intended + recipient. The field's encoding is described in + section 6.2. + + The following fields are optional. If present, they +can be associated with the credentials in the remote ticket +file. If left out, then it is assumed that the recipient of +the credentials already knows their value. + + +prealm and pname + + +Section 5.8.1. - 71 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + The name and realm of the delegated principal + identity. + + +flags, authtime, starttime, endtime, renew-till, srealm, + sname, and caddr + These fields contain the values of the correspond- + ing fields from the ticket found in the ticket + field. Descriptions of the fields are identical + to the descriptions in the KDC-REP message. + +5.9. Error message specification + + This section specifies the format for the KRB_ERROR +message. The fields included in the message are intended to +return as much information as possible about an error. It +is not expected that all the information required by the +fields will be available for all types of errors. If the +appropriate information is not available when the message is +composed, the corresponding field will be left out of the +message. + + Note that since the KRB_ERROR message is not protected +by any encryption, it is quite possible for an intruder to +synthesize or modify such a message. In particular, this +means that the client should not use any fields in this mes- +sage for security-critical purposes, such as setting a sys- +tem clock or generating a fresh authenticator. The message +can be useful, however, for advising a user on the reason +for some failure. + +5.9.1. KRB_ERROR definition + + The KRB_ERROR message consists of the following fields: + +KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL, + e-cksum[13] Checksum OPTIONAL +} + + + + + +Section 5.9.1. - 72 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +pvno and msg-type + These fields are described above in section 5.4.1. + msg-type is KRB_ERROR. + + +ctime This field is described above in section 5.4.1. + + + +cusec This field is described above in section 5.5.2. + + +stime This field contains the current time on the + server. It is of type KerberosTime. + + +susec This field contains the microsecond part of the + server's timestamp. Its value ranges from 0 to + 999999. It appears along with stime. The two + fields are used in conjunction to specify a rea- + sonably accurate timestamp. + + +error-codeThis field contains the error code returned by + Kerberos or the server when a request fails. To + interpret the value of this field see the list of + error codes in section 8. Implementations are + encouraged to provide for national language sup- + port in the display of error messages. + + +crealm, cname, srealm and sname + These fields are described above in section 5.3.1. + + +e-text This field contains additional text to help + explain the error code associated with the failed + request (for example, it might include a principal + name which was unknown). + + +e-data This field contains additional data about the + error for use by the application to help it + recover from or handle the error. If the error- + code is KDC_ERR_PREAUTH_REQUIRED, then the e-data + field will contain an encoding of a sequence of + padata fields, each corresponding to an acceptable + pre-authentication method and optionally contain- + ing data for the method: + + +e-cksum This field contains an optional checksum for the + KRB-ERROR message. The checksum is calculated + over the Kerberos ASN.1 encoding of the KRB-ERROR + + +Section 5.9.1. - 73 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + message with the checksum absent. The checksum is + then added to the KRB-ERROR structure and the mes- + sage is re-encoded. The Checksum should be calcu- + lated using the session key from the ticket grant- + ing ticket or service ticket, where available. If + the error is in response to a TGS or AP request, + the checksum should be calculated uing the the + session key from the client's ticket. If the + error is in response to an AS request, then the + checksum should be calulated using the client's + secret key ONLY if there has been suitable preau- + thentication to prove knowledge of the secret key + by the client[33]. If a checksum can not be com- + puted because the key to be used is not available, + no checksum will be included. + + METHOD-DATA ::= SEQUENCE of PA-DATA + + + If the error-code is KRB_AP_ERR_METHOD, then the + e-data field will contain an encoding of the fol- + lowing sequence: + + METHOD-DATA ::= SEQUENCE { + method-type[0] INTEGER, + method-data[1] OCTET STRING OPTIONAL + } + + method-type will indicate the required alternate + method; method-data will contain any required + additional information. + + + +6. Encryption and Checksum Specifications + +The Kerberos protocols described in this document are +designed to use stream encryption ciphers, which can be +simulated using commonly available block encryption ciphers, +such as the Data Encryption Standard, [12] in conjunction +with block chaining and checksum methods [13]. Encryption +is used to prove the identities of the network entities par- +ticipating in message exchanges. The Key Distribution +Center for each realm is trusted by all principals +registered in that realm to store a secret key in confi- +dence. Proof of knowledge of this secret key is used to +verify the authenticity of a principal. + + The KDC uses the principal's secret key (in the AS +__________________________ +[33] This prevents an attacker who generates an in- +correct AS request from obtaining verifiable plaintext +for use in an off-line password guessing attack. + + +Section 6. - 74 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +exchange) or a shared session key (in the TGS exchange) to +encrypt responses to ticket requests; the ability to obtain +the secret key or session key implies the knowledge of the +appropriate keys and the identity of the KDC. The ability +of a principal to decrypt the KDC response and present a +Ticket and a properly formed Authenticator (generated with +the session key from the KDC response) to a service verifies +the identity of the principal; likewise the ability of the +service to extract the session key from the Ticket and prove +its knowledge thereof in a response verifies the identity of +the service. + + The Kerberos protocols generally assume that the +encryption used is secure from cryptanalysis; however, in +some cases, the order of fields in the encrypted portions of +messages are arranged to minimize the effects of poorly +chosen keys. It is still important to choose good keys. If +keys are derived from user-typed passwords, those passwords +need to be well chosen to make brute force attacks more dif- +ficult. Poorly chosen keys still make easy targets for +intruders. + + The following sections specify the encryption and +checksum mechanisms currently defined for Kerberos. The +encodings, chaining, and padding requirements for each are +described. For encryption methods, it is often desirable to +place random information (often referred to as a confounder) +at the start of the message. The requirements for a con- +founder are specified with each encryption mechanism. + + Some encryption systems use a block-chaining method to +improve the the security characteristics of the ciphertext. +However, these chaining methods often don't provide an +integrity check upon decryption. Such systems (such as DES +in CBC mode) must be augmented with a checksum of the plain- +text which can be verified at decryption and used to detect +any tampering or damage. Such checksums should be good at +detecting burst errors in the input. If any damage is +detected, the decryption routine is expected to return an +error indicating the failure of an integrity check. Each +encryption type is expected to provide and verify an +appropriate checksum. The specification of each encryption +method sets out its checksum requirements. + + Finally, where a key is to be derived from a user's +password, an algorithm for converting the password to a key +of the appropriate type is included. It is desirable for +the string to key function to be one-way, and for the map- +ping to be different in different realms. This is important +because users who are registered in more than one realm will +often use the same password in each, and it is desirable +that an attacker compromising the Kerberos server in one +realm not obtain or derive the user's key in another. + + + +Section 6. - 75 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + For an discussion of the integrity characteristics of +the candidate encryption and checksum methods considered for +Kerberos, the the reader is referred to [14]. + +6.1. Encryption Specifications + + The following ASN.1 definition describes all encrypted +messages. The enc-part field which appears in the unen- +crypted part of messages in section 5 is a sequence consist- +ing of an encryption type, an optional key version number, +and the ciphertext. + + +EncryptedData ::= SEQUENCE { + etype[0] INTEGER, -- EncryptionType + kvno[1] INTEGER OPTIONAL, + cipher[2] OCTET STRING -- ciphertext +} + + +etype This field identifies which encryption algorithm + was used to encipher the cipher. Detailed specif- + ications for selected encryption types appear + later in this section. + + +kvno This field contains the version number of the key + under which data is encrypted. It is only present + in messages encrypted under long lasting keys, + such as principals' secret keys. + + +cipher This field contains the enciphered text, encoded + as an OCTET STRING. + + + The cipher field is generated by applying the specified +encryption algorithm to data composed of the message and +algorithm-specific inputs. Encryption mechanisms defined +for use with Kerberos must take sufficient measures to +guarantee the integrity of the plaintext, and we recommend +they also take measures to protect against precomputed dic- +tionary attacks. If the encryption algorithm is not itself +capable of doing so, the protections can often be enhanced +by adding a checksum and a confounder. + + The suggested format for the data to be encrypted +includes a confounder, a checksum, the encoded plaintext, +and any necessary padding. The msg-seq field contains the +part of the protocol message described in section 5 which is +to be encrypted. The confounder, checksum, and padding are +all untagged and untyped, and their length is exactly suffi- +cient to hold the appropriate item. The type and length is +implicit and specified by the particular encryption type + + +Section 6.1. - 76 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +being used (etype). The format for the data to be encrypted +is described in the following diagram: + + +-----------+----------+-------------+-----+ + |confounder | check | msg-seq | pad | + +-----------+----------+-------------+-----+ + +The format cannot be described in ASN.1, but for those who +prefer an ASN.1-like notation: + +CipherText ::= ENCRYPTED SEQUENCE { + confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, + check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, + msg-seq[2] MsgSequence, + pad UNTAGGED OCTET STRING(pad_length) OPTIONAL +} + + + One generates a random confounder of the appropriate +length, placing it in confounder; zeroes out check; calcu- +lates the appropriate checksum over confounder, check, and +msg-seq, placing the result in check; adds the necessary +padding; then encrypts using the specified encryption type +and the appropriate key. + + Unless otherwise specified, a definition of an encryp- +tion algorithm that specifies a checksum, a length for the +confounder field, or an octet boundary for padding uses this +ciphertext format[36]. Those fields which are not specified +will be omitted. + + In the interest of allowing all implementations using a +__________________________ +[35] In the above specification, UNTAGGED OCTET +STRING(length) is the notation for an octet string with +its tag and length removed. It is not a valid ASN.1 +type. The tag bits and length must be removed from the +confounder since the purpose of the confounder is so +that the message starts with random data, but the tag +and its length are fixed. For other fields, the length +and tag would be redundant if they were included be- +cause they are specified by the encryption type. +[36] The ordering of the fields in the CipherText is +important. Additionally, messages encoded in this for- +mat must include a length as part of the msg-seq field. +This allows the recipient to verify that the message +has not been truncated. Without a length, an attacker +could use a chosen plaintext attack to generate a mes- +sage which could be truncated, while leaving the check- +sum intact. Note that if the msg-seq is an encoding of +an ASN.1 SEQUENCE or OCTET STRING, then the length is +part of that encoding. + + + +Section 6.1. - 77 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +particular encryption type to communicate with all others +using that type, the specification of an encryption type +defines any checksum that is needed as part of the encryp- +tion process. If an alternative checksum is to be used, a +new encryption type must be defined. + + Some cryptosystems require additional information +beyond the key and the data to be encrypted. For example, +DES, when used in cipher-block-chaining mode, requires an +initialization vector. If required, the description for +each encryption type must specify the source of such addi- +tional information. + +6.2. Encryption Keys + + The sequence below shows the encoding of an encryption +key: + + EncryptionKey ::= SEQUENCE { + keytype[0] INTEGER, + keyvalue[1] OCTET STRING + } + + +keytype This field specifies the type of encryption key + that follows in the keyvalue field. It will + almost always correspond to the encryption algo- + rithm used to generate the EncryptedData, though + more than one algorithm may use the same type of + key (the mapping is many to one). This might hap- + pen, for example, if the encryption algorithm uses + an alternate checksum algorithm for an integrity + check, or a different chaining mechanism. + + +keyvalue This field contains the key itself, encoded as an + octet string. + + All negative values for the encryption key type are +reserved for local use. All non-negative values are +reserved for officially assigned type fields and interpreta- +tions. + +6.3. Encryption Systems + +6.3.1. The NULL Encryption System (null) + + If no encryption is in use, the encryption system is +said to be the NULL encryption system. In the NULL encryp- +tion system there is no checksum, confounder or padding. +The ciphertext is simply the plaintext. The NULL Key is +used by the null encryption system and is zero octets in +length, with keytype zero (0). + + + +Section 6.3.1. - 78 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) + + The des-cbc-crc encryption mode encrypts information +under the Data Encryption Standard [12] using the cipher +block chaining mode [13]. A CRC-32 checksum (described in +ISO 3309 [15]) is applied to the confounder and message +sequence (msg-seq) and placed in the cksum field. DES +blocks are 8 bytes. As a result, the data to be encrypted +(the concatenation of confounder, checksum, and message) +must be padded to an 8 byte boundary before encryption. The +details of the encryption of this data are identical to +those for the des-cbc-md5 encryption mode. + + Note that, since the CRC-32 checksum is not collision- +proof, an attacker could use a probabilistic chosen- +plaintext attack to generate a valid message even if a con- +founder is used [14]. The use of collision-proof checksums +is recommended for environments where such attacks represent +a significant threat. The use of the CRC-32 as the checksum +for ticket or authenticator is no longer mandated as an +interoperability requirement for Kerberos Version 5 Specifi- +cation 1 (See section 9.1 for specific details). + + +6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) + + The des-cbc-md4 encryption mode encrypts information +under the Data Encryption Standard [12] using the cipher +block chaining mode [13]. An MD4 checksum (described in +[16]) is applied to the confounder and message sequence +(msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concate- +nation of confounder, checksum, and message) must be padded +to an 8 byte boundary before encryption. The details of the +encryption of this data are identical to those for the des- +cbc-md5 encryption mode. + + +6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) + + The des-cbc-md5 encryption mode encrypts information +under the Data Encryption Standard [12] using the cipher +block chaining mode [13]. An MD5 checksum (described in +[17].) is applied to the confounder and message sequence +(msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concate- +nation of confounder, checksum, and message) must be padded +to an 8 byte boundary before encryption. + + Plaintext and DES ciphtertext are encoded as 8-octet +blocks which are concatenated to make the 64-bit inputs for +the DES algorithms. The first octet supplies the 8 most +significant bits (with the octet's MSbit used as the DES +input block's MSbit, etc.), the second octet the next 8 + + +Section 6.3.4. - 79 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +bits, ..., and the eighth octet supplies the 8 least signi- +ficant bits. + + Encryption under DES using cipher block chaining +requires an additional input in the form of an initializa- +tion vector. Unless otherwise specified, zero should be +used as the initialization vector. Kerberos' use of DES +requires an 8-octet confounder. + + The DES specifications identify some "weak" and "semi- +weak" keys; those keys shall not be used for encrypting mes- +sages for use in Kerberos. Additionally, because of the way +that keys are derived for the encryption of checksums, keys +shall not be used that yield "weak" or "semi-weak" keys when +eXclusive-ORed with the constant F0F0F0F0F0F0F0F0. + + A DES key is 8 octets of data, with keytype one (1). +This consists of 56 bits of key, and 8 parity bits (one per +octet). The key is encoded as a series of 8 octets written +in MSB-first order. The bits within the key are also +encoded in MSB order. For example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) +where B1,B2,...,B56 are the key bits in MSB order, and +P1,P2,...,P8 are the parity bits, the first octet of the key +would be B1,B2,...,B7,P1 (with B1 as the MSbit). [See the +FIPS 81 introduction for reference.] + + To generate a DES key from a text string (password), +the text string normally must have the realm and each com- +ponent of the principal's name appended[37], then padded +with ASCII nulls to an 8 byte boundary. This string is then +fan-folded and eXclusive-ORed with itself to form an 8 byte +DES key. The parity is corrected on the key, and it is used +to generate a DES CBC checksum on the initial string (with +the realm and name appended). Next, parity is corrected on +the CBC checksum. If the result matches a "weak" or "semi- +weak" key as described in the DES specification, it is +eXclusive-ORed with the constant 00000000000000F0. Finally, +the result is returned as the key. Pseudocode follows: + + string_to_key(string,realm,name) { + odd = 1; + s = string + realm; + for(each component in name) { + s = s + component; + } + tempkey = NULL; + pad(s); /* with nulls to 8 byte boundary */ + for(8byteblock in s) { +__________________________ +[37] In some cases, it may be necessary to use a dif- +ferent "mix-in" string for compatibility reasons; see +the discussion of padata in section 5.4.2. + + +Section 6.3.4. - 80 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + if(odd == 0) { + odd = 1; + reverse(8byteblock) + } + else odd = 0; + tempkey = tempkey XOR 8byteblock; + } + fixparity(tempkey); + key = DES-CBC-check(s,tempkey); + fixparity(key); + if(is_weak_key_key(key)) + key = key XOR 0xF0; + return(key); + } + +6.3.5. Triple DES EDE in outer CBC mode with an SHA1 check- +sum (des3-cbc-sha1) + + The des3-cbc-sha1 encryption encodes information using +three Data Encryption Standard transformations with three +DES keys. The first key is used to perform a DES ECB +encryption on an eight-octet data block using the first DES +key, followed by a DES ECB decryption of the result using +the second DES key, and a DES ECB encryption of the result +using the third DES key. Because DES blocks are 8 bytes, +the data to be encrypted (the concatenation of confounder, +checksum, and message) must first be padded to an 8 byte +boundary before encryption. To support the outer CBC mode, +the input is padded an eight-octet boundary. The first 8 +octets of the data to be encrypted (the confounder) is +exclusive-ored with an initialization vector of zero and +then ECB encrypted using triple DES as described above. +Subsequent blocks of 8 octets are exclusive-ored with the +ciphertext produced by the encryption on the previous block +before ECB encryption. + + An HMAC-SHA1 checksum (described in [18].) is applied +to the confounder and message sequence (msg-seq) and placed +in the cksum field. + + Plaintext are encoded as 8-octet blocks which are con- +catenated to make the 64-bit inputs for the DES algorithms. +The first octet supplies the 8 most significant bits (with +the octet's MSbit used as the DES input block's MSbit, +etc.), the second octet the next 8 bits, ..., and the eighth +octet supplies the 8 least significant bits. + + Encryption under Triple DES using cipher block chaining +requires an additional input in the form of an initializa- +tion vector. Unless otherwise specified, zero should be +used as the initialization vector. Kerberos' use of DES +requires an 8-octet confounder. + + The DES specifications identify some "weak" and "semi- + + +Section 6.3.5. - 81 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +weak" keys; those keys shall not be used for encrypting mes- +sages for use in Kerberos. Additionally, because of the way +that keys are derived for the encryption of checksums, keys +shall not be used that yield "weak" or "semi-weak" keys when +eXclusive-ORed with the constant F0F0F0F0F0F0F0F0. + + A Triple DES key is 24 octets of data, with keytype +seven (7). This consists of 168 bits of key, and 24 parity +bits (one per octet). The key is encoded as a series of 24 +octets written in MSB-first order, with the first 8 octets +treated as the first DES key, the second 8 octets as the +second key, and the third 8 octets the third DES key. The +bits within each key are also encoded in MSB order. For +example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) +where B1,B2,...,B56 are the key bits in MSB order, and +P1,P2,...,P8 are the parity bits, the first octet of the key +would be B1,B2,...,B7,P1 (with B1 as the MSbit). [See the +FIPS 81 introduction for reference.] + + To generate a DES key from a text string (password), +the text string normally must have the realm and each com- +ponent of the principal's name appended[38], + + The input string (with any salt data appended to it) is +n-folded into a 24 octet (192 bit) string. To n-fold a +number X, replicate the input value to a length that is the +least common multiple of n and the length of X. Before each +repetition, the input X is rotated to the right by 13 bit +positions. The successive n-bit chunks are added together +using 1's-complement addition (addition with end-around +carry) to yield a n-bit result. (This transformation was +proposed by Richard Basch) + + Each successive set of 8 octets is taken as a DES key, +and its parity is adjusted in the same manner as previously +described. If any of the three sets of 8 octets match a +"weak" or "semi-weak" key as described in the DES specifica- +tion, that chunk is eXclusive-ORed with the constant +00000000000000F0. The resulting DES keys are then used in +sequence to perform a Triple-DES CBC encryption of the n- +folded input string (appended with any salt data), using a +zero initial vector. Parity, weak, and semi-weak keys are +once again corrected and the result is returned as the 24 +octet key. + + Pseudocode follows: + + string_to_key(string,realm,name) { +__________________________ +[38] In some cases, it may be necessary to use a dif- +ferent "mix-in" string for compatibility reasons; see +the discussion of padata in section 5.4.2. + + +Section 6.3.5. - 82 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + s = string + realm; + for(each component in name) { + s = s + component; + } + tkey[24] = fold(s); + fixparity(tkey); + if(isweak(tkey[0-7])) tkey[0-7] = tkey[0-7] XOR 0xF0; + if(isweak(tkey[8-15])) tkey[8-15] = tkey[8-15] XOR 0xF0; + if(is_weak(tkey[16-23])) tkey[16-23] = tkey[16-23] XOR 0xF0; + key[24] = 3DES-CBC(data=fold(s),key=tkey,iv=0); + fixparity(key); + if(is_weak(key[0-7])) key[0-7] = key[0-7] XOR 0xF0; + if(is_weak(key[8-15])) key[8-15] = key[8-15] XOR 0xF0; + if(is_weak(key[16-23])) key[16-23] = key[16-23] XOR 0xF0; + return(key); + } + +6.4. Checksums + + The following is the ASN.1 definition used for a check- +sum: + + Checksum ::= SEQUENCE { + cksumtype[0] INTEGER, + checksum[1] OCTET STRING + } + + +cksumtype This field indicates the algorithm used to gen- + erate the accompanying checksum. + +checksum This field contains the checksum itself, encoded + as an octet string. + + Detailed specification of selected checksum types +appear later in this section. Negative values for the +checksum type are reserved for local use. All non-negative +values are reserved for officially assigned type fields and +interpretations. + + Checksums used by Kerberos can be classified by two +properties: whether they are collision-proof, and whether +they are keyed. It is infeasible to find two plaintexts +which generate the same checksum value for a collision-proof +checksum. A key is required to perturb or initialize the +algorithm in a keyed checksum. To prevent message-stream +modification by an active attacker, unkeyed checksums should +only be used when the checksum and message will be subse- +quently encrypted (e.g. the checksums defined as part of the +encryption algorithms covered earlier in this section). + + Collision-proof checksums can be made tamper-proof if +the checksum value is encrypted before inclusion in a mes- +sage. In such cases, the composition of the checksum and + + +Section 6.4. - 83 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +the encryption algorithm must be considered a separate +checksum algorithm (e.g. RSA-MD5 encrypted using DES is a +new checksum algorithm of type RSA-MD5-DES). For most keyed +checksums, as well as for the encrypted forms of unkeyed +collision-proof checksums, Kerberos prepends a confounder +before the checksum is calculated. + +6.4.1. The CRC-32 Checksum (crc32) + + The CRC-32 checksum calculates a checksum based on a +cyclic redundancy check as described in ISO 3309 [15]. The +resulting checksum is four (4) octets in length. The CRC-32 +is neither keyed nor collision-proof. The use of this +checksum is not recommended. An attacker using a proba- +bilistic chosen-plaintext attack as described in [14] might +be able to generate an alternative message that satisfies +the checksum. The use of collision-proof checksums is +recommended for environments where such attacks represent a +significant threat. + +6.4.2. The RSA MD4 Checksum (rsa-md4) + + The RSA-MD4 checksum calculates a checksum using the +RSA MD4 algorithm [16]. The algorithm takes as input an +input message of arbitrary length and produces as output a +128-bit (16 octet) checksum. RSA-MD4 is believed to be +collision-proof. + +6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4- +des) + + The RSA-MD4-DES checksum calculates a keyed collision- +proof checksum by prepending an 8 octet confounder before +the text, applying the RSA MD4 checksum algorithm, and +encrypting the confounder and the checksum using DES in +cipher-block-chaining (CBC) mode using a variant of the key, +where the variant is computed by eXclusive-ORing the key +with the constant F0F0F0F0F0F0F0F0[39]. The initialization +vector should be zero. The resulting checksum is 24 octets +long (8 octets of which are redundant). This checksum is +tamper-proof and believed to be collision-proof. + + The DES specifications identify some "weak keys" and +__________________________ +[39] A variant of the key is used to limit the use of a +key to a particular function, separating the functions +of generating a checksum from other encryption per- +formed using the session key. The constant +F0F0F0F0F0F0F0F0 was chosen because it maintains key +parity. The properties of DES precluded the use of the +complement. The same constant is used for similar pur- +pose in the Message Integrity Check in the Privacy +Enhanced Mail standard. + + +Section 6.4.3. - 84 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +"semi-weak keys"; those keys shall not be used for generat- +ing RSA-MD4 checksums for use in Kerberos. + + The format for the checksum is described in the follow- +ing diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who +prefer an ASN.1-like notation: + +rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + + + +6.4.4. The RSA MD5 Checksum (rsa-md5) + + The RSA-MD5 checksum calculates a checksum using the +RSA MD5 algorithm. [17]. The algorithm takes as input an +input message of arbitrary length and produces as output a +128-bit (16 octet) checksum. RSA-MD5 is believed to be +collision-proof. + +6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5- +des) + + The RSA-MD5-DES checksum calculates a keyed collision- +proof checksum by prepending an 8 octet confounder before +the text, applying the RSA MD5 checksum algorithm, and +encrypting the confounder and the checksum using DES in +cipher-block-chaining (CBC) mode using a variant of the key, +where the variant is computed by eXclusive-ORing the key +with the constant F0F0F0F0F0F0F0F0. The initialization vec- +tor should be zero. The resulting checksum is 24 octets +long (8 octets of which are redundant). This checksum is +tamper-proof and believed to be collision-proof. + + The DES specifications identify some "weak keys" and +"semi-weak keys"; those keys shall not be used for encrypt- +ing RSA-MD5 checksums for use in Kerberos. + + The format for the checksum is described in the follow- +ing diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who + + +Section 6.4.5. - 85 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +prefer an ASN.1-like notation: + +rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + + +6.4.6. DES cipher-block chained checksum (des-mac) + + The DES-MAC checksum is computed by prepending an 8 +octet confounder to the plaintext, performing a DES CBC-mode +encryption on the result using the key and an initialization +vector of zero, taking the last block of the ciphertext, +prepending the same confounder and encrypting the pair using +DES in cipher-block-chaining (CBC) mode using a a variant of +the key, where the variant is computed by eXclusive-ORing +the key with the constant F0F0F0F0F0F0F0F0. The initializa- +tion vector should be zero. The resulting checksum is 128 +bits (16 octets) long, 64 bits of which are redundant. This +checksum is tamper-proof and collision-proof. + + The format for the checksum is described in the follow- +ing diagram: + ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ +| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ + +The format cannot be described in ASN.1, but for those who +prefer an ASN.1-like notation: + +des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(8) +} + + + The DES specifications identify some "weak" and "semi- +weak" keys; those keys shall not be used for generating +DES-MAC checksums for use in Kerberos, nor shall a key be +used whose variant is "weak" or "semi-weak". + +6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative +(rsa-md4-des-k) + + The RSA-MD4-DES-K checksum calculates a keyed +collision-proof checksum by applying the RSA MD4 checksum +algorithm and encrypting the results using DES in cipher- +block-chaining (CBC) mode using a DES key as both key and +initialization vector. The resulting checksum is 16 octets +long. This checksum is tamper-proof and believed to be +collision-proof. Note that this checksum type is the old +method for encoding the RSA-MD4-DES checksum and it is no + + +Section 6.4.7. - 86 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +longer recommended. + +6.4.8. DES cipher-block chained checksum alternative (des- +mac-k) + + The DES-MAC-K checksum is computed by performing a DES +CBC-mode encryption of the plaintext, and using the last +block of the ciphertext as the checksum value. It is keyed +with an encryption key and an initialization vector; any +uses which do not specify an additional initialization vec- +tor will use the key as both key and initialization vector. +The resulting checksum is 64 bits (8 octets) long. This +checksum is tamper-proof and collision-proof. Note that +this checksum type is the old method for encoding the DES- +MAC checksum and it is no longer recommended. + + The DES specifications identify some "weak keys" and +"semi-weak keys"; those keys shall not be used for generat- +ing DES-MAC checksums for use in Kerberos. + +7. Naming Constraints + + +7.1. Realm Names + + Although realm names are encoded as GeneralStrings and +although a realm can technically select any name it chooses, +interoperability across realm boundaries requires agreement +on how realm names are to be assigned, and what information +they imply. + + To enforce these conventions, each realm must conform +to the conventions itself, and it must require that any +realms with which inter-realm keys are shared also conform +to the conventions and require the same from its neighbors. + + Kerberos realm names are case sensitive. Realm names +that differ only in the case of the characters are not +equivalent. There are presently four styles of realm names: +domain, X500, other, and reserved. Examples of each style +follow: + + domain: ATHENA.MIT.EDU (example) + X500: C=US/O=OSF (example) + other: NAMETYPE:rest/of.name=without-restrictions (example) + reserved: reserved, but will not conflict with above + + +Domain names must look like domain names: they consist of +components separated by periods (.) and they contain neither +colons (:) nor slashes (/). Domain names must be converted +to upper case when used as realm names. + + X.500 names contain an equal (=) and cannot contain a + + +Section 7.1. - 87 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +colon (:) before the equal. The realm names for X.500 names +will be string representations of the names with components +separated by slashes. Leading and trailing slashes will not +be included. + + Names that fall into the other category must begin with +a prefix that contains no equal (=) or period (.) and the +prefix must be followed by a colon (:) and the rest of the +name. All prefixes must be assigned before they may be +used. Presently none are assigned. + + The reserved category includes strings which do not +fall into the first three categories. All names in this +category are reserved. It is unlikely that names will be +assigned to this category unless there is a very strong +argument for not using the "other" category. + + These rules guarantee that there will be no conflicts +between the various name styles. The following additional +constraints apply to the assignment of realm names in the +domain and X.500 categories: the name of a realm for the +domain or X.500 formats must either be used by the organiza- +tion owning (to whom it was assigned) an Internet domain +name or X.500 name, or in the case that no such names are +registered, authority to use a realm name may be derived +from the authority of the parent realm. For example, if +there is no domain name for E40.MIT.EDU, then the adminis- +trator of the MIT.EDU realm can authorize the creation of a +realm with that name. + + This is acceptable because the organization to which +the parent is assigned is presumably the organization +authorized to assign names to its children in the X.500 and +domain name systems as well. If the parent assigns a realm +name without also registering it in the domain name or X.500 +hierarchy, it is the parent's responsibility to make sure +that there will not in the future exists a name identical to +the realm name of the child unless it is assigned to the +same entity as the realm name. + + +7.2. Principal Names + + As was the case for realm names, conventions are needed +to ensure that all agree on what information is implied by a +principal name. The name-type field that is part of the +principal name indicates the kind of information implied by +the name. The name-type should be treated as a hint. +Ignoring the name type, no two names can be the same (i.e. +at least one of the components, or the realm, must be dif- +ferent). This constraint may be eliminated in the future. +The following name types are defined: + + name-type value meaning + + +Section 7.2. - 88 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + NT-UNKNOWN 0 Name type not known + NT-PRINCIPAL 1 General principal name (e.g. username, or DCE principal) + NT-SRV-INST 2 Service and other unique instance (krbtgt) + NT-SRV-HST 3 Service with host name as instance (telnet, rcommands) + NT-SRV-XHST 4 Service with slash-separated host name components + NT-UID 5 Unique ID + + +When a name implies no information other than its uniqueness +at a particular time the name type PRINCIPAL should be used. +The principal name type should be used for users, and it +might also be used for a unique server. If the name is a +unique machine generated ID that is guaranteed never to be +reassigned then the name type of UID should be used (note +that it is generally a bad idea to reassign names of any +type since stale entries might remain in access control +lists). + + If the first component of a name identifies a service +and the remaining components identify an instance of the +service in a server specified manner, then the name type of +SRV-INST should be used. An example of this name type is +the Kerberos ticket-granting service whose name has a first +component of krbtgt and a second component identifying the +realm for which the ticket is valid. + + If instance is a single component following the service +name and the instance identifies the host on which the +server is running, then the name type SRV-HST should be +used. This type is typically used for Internet services +such as telnet and the Berkeley R commands. If the separate +components of the host name appear as successive components +following the name of the service, then the name type SRV- +XHST should be used. This type might be used to identify +servers on hosts with X.500 names where the slash (/) might +otherwise be ambiguous. + + A name type of UNKNOWN should be used when the form of +the name is not known. When comparing names, a name of type +UNKNOWN will match principals authenticated with names of +any type. A principal authenticated with a name of type +UNKNOWN, however, will only match other names of type UNK- +NOWN. + + Names of any type with an initial component of "krbtgt" +are reserved for the Kerberos ticket granting service. See +section 8.2.3 for the form of such names. + +7.2.1. Name of server principals + + The principal identifier for a server on a host will +generally be composed of two parts: (1) the realm of the KDC +with which the server is registered, and (2) a two-component + + +Section 7.2.1. - 89 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +name of type NT-SRV-HST if the host name is an Internet +domain name or a multi-component name of type NT-SRV-XHST if +the name of the host is of a form such as X.500 that allows +slash (/) separators. The first component of the two- or +multi-component name will identify the service and the +latter components will identify the host. Where the name of +the host is not case sensitive (for example, with Internet +domain names) the name of the host must be lower case. If +specified by the application protocol for services such as +telnet and the Berkeley R commands which run with system +privileges, the first component may be the string "host" +instead of a service specific identifier. When a host has +an official name and one or more aliases, the official name +of the host must be used when constructing the name of the +server principal. + +8. Constants and other defined values + + +8.1. Host address types + + All negative values for the host address type are +reserved for local use. All non-negative values are +reserved for officially assigned type fields and interpreta- +tions. + + The values of the types for the following addresses are +chosen to match the defined address family constants in the +Berkeley Standard Distributions of Unix. They can be found +in <sys/socket.h> with symbolic names AF_xxx (where xxx is +an abbreviation of the address family name). + + +Internet addresses + + Internet addresses are 32-bit (4-octet) quantities, +encoded in MSB order. The type of internet addresses is two +(2). + +CHAOSnet addresses + + CHAOSnet addresses are 16-bit (2-octet) quantities, +encoded in MSB order. The type of CHAOSnet addresses is +five (5). + +ISO addresses + + ISO addresses are variable-length. The type of ISO +addresses is seven (7). + +Xerox Network Services (XNS) addresses + + XNS addresses are 48-bit (6-octet) quantities, encoded +in MSB order. The type of XNS addresses is six (6). + + +Section 8.1. - 90 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +AppleTalk Datagram Delivery Protocol (DDP) addresses + + AppleTalk DDP addresses consist of an 8-bit node number +and a 16-bit network number. The first octet of the address +is the node number; the remaining two octets encode the net- +work number in MSB order. The type of AppleTalk DDP +addresses is sixteen (16). + +DECnet Phase IV addresses + + DECnet Phase IV addresses are 16-bit addresses, encoded +in LSB order. The type of DECnet Phase IV addresses is +twelve (12). + +8.2. KDC messages + +8.2.1. IP transport + + When contacting a Kerberos server (KDC) for a +KRB_KDC_REQ request using UDP IP transport, the client shall +send a UDP datagram containing only an encoding of the +request to port 88 (decimal) at the KDC's IP address; the +KDC will respond with a reply datagram containing only an +encoding of the reply message (either a KRB_ERROR or a +KRB_KDC_REP) to the sending port at the sender's IP address. + + Kerberos servers supporting IP transport must accept +UDP requests on port 88 (decimal). Servers may also accept +TCP requests on port 88 (decimal). When the KRB_KDC_REQ +message is sent to the KDC by TCP, a new connection will be +established for each authentication exchange and the +KRB_KDC_REP or KRB_ERROR message will be returned to the +client on the TCP stream that was established for the +request. The connection will be broken after the reply has +been received (or upon time-out). Care must be taken in +managing TCP/IP connections with the KDC to prevent denial +of service attacks based on the number of TCP/IP connections +with the KDC that remain open. + +8.2.2. OSI transport + + During authentication of an OSI client to an OSI +server, the mutual authentication of an OSI server to an OSI +client, the transfer of credentials from an OSI client to an +OSI server, or during exchange of private or integrity +checked messages, Kerberos protocol messages may be treated +as opaque objects and the type of the authentication mechan- +ism will be: + +OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), security(5), + kerberosv5(2)} + +Depending on the situation, the opaque object will be an +authentication header (KRB_AP_REQ), an authentication reply +(KRB_AP_REP), a safe message (KRB_SAFE), a private message + + +Section 8.2.2. - 91 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +(KRB_PRIV), or a credentials message (KRB_CRED). The opaque +data contains an application code as specified in the ASN.1 +description for each message. The application code may be +used by Kerberos to determine the message type. + +8.2.3. Name of the TGS + + The principal identifier of the ticket-granting service +shall be composed of three parts: (1) the realm of the KDC +issuing the TGS ticket (2) a two-part name of type NT-SRV- +INST, with the first part "krbtgt" and the second part the +name of the realm which will accept the ticket-granting +ticket. For example, a ticket-granting ticket issued by the +ATHENA.MIT.EDU realm to be used to get tickets from the +ATHENA.MIT.EDU KDC has a principal identifier of +"ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") +(name). A ticket-granting ticket issued by the +ATHENA.MIT.EDU realm to be used to get tickets from the +MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" +(realm), ("krbtgt", "MIT.EDU") (name). + + +8.3. Protocol constants and associated values + +The following tables list constants used in the protocol and defines their +meanings. + +Encryption type etype value block size minimum pad size confounder size +NULL 0 1 0 0 +des-cbc-crc 1 8 4 8 +des-cbc-md4 2 8 0 8 +des-cbc-md5 3 8 0 8 +<reserved> 4 +des3-cbc-md5 5 8 0 8 +<reserved> 6 +des3-cbc-sha1 7 8 0 8 +sign-dsa-generate 8 (pkinit) +encrypt-rsa-priv 9 (pkinit) +encrypt-rsa-pub 10 (pkinit) +ENCTYPE_PK_CROSS 48 (reserved for pkcross) +<reserved> 0x8003 + +Checksum type sumtype value checksum size +CRC32 1 4 +rsa-md4 2 16 +rsa-md4-des 3 24 +des-mac 4 16 +des-mac-k 5 8 +rsa-md4-des-k 6 16 +rsa-md5 7 16 +rsa-md5-des 8 24 +rsa-md5-des3 9 24 +hmac-sha1-des3 10 20 (I had this as 10, is it 12) + + +Section 8.3. - 92 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +padata type padata-type value + +PA-TGS-REQ 1 +PA-ENC-TIMESTAMP 2 +PA-PW-SALT 3 +<reserved> 4 +PA-ENC-UNIX-TIME 5 +PA-SANDIA-SECUREID 6 +PA-SESAME 7 +PA-OSF-DCE 8 +PA-CYBERSAFE-SECUREID 9 +PA-AFS3-SALT 10 +PA-ETYPE-INFO 11 +SAM-CHALLENGE 12 (sam/otp) +SAM-RESPONSE 13 (sam/otp) +PA-PK-AS-REQ 14 (pkinit) +PA-PK-AS-REP 15 (pkinit) +PA-PK-AS-SIGN 16 (pkinit) +PA-PK-KEY-REQ 17 (pkinit) +PA-PK-KEY-REP 18 (pkinit) + +authorization data type ad-type value +reserved values 0-63 +OSF-DCE 64 +SESAME 65 + +alternate authentication type method-type value +reserved values 0-63 +ATT-CHALLENGE-RESPONSE 64 + +transited encoding type tr-type value +DOMAIN-X500-COMPRESS 1 +reserved values all others + + + +Label Value Meaning or MIT code + +pvno 5 current Kerberos protocol version number + +message types + +KRB_AS_REQ 10 Request for initial authentication +KRB_AS_REP 11 Response to KRB_AS_REQ request +KRB_TGS_REQ 12 Request for authentication based on TGT +KRB_TGS_REP 13 Response to KRB_TGS_REQ request +KRB_AP_REQ 14 application request to server +KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL +KRB_SAFE 20 Safe (checksummed) application message +KRB_PRIV 21 Private (encrypted) application message +KRB_CRED 22 Private (encrypted) message to forward credentials +KRB_ERROR 30 Error response + + +Section 8.3. - 93 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +name types + +KRB_NT_UNKNOWN 0 Name type not known +KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for users +KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) +KRB_NT_SRV_HST 3 Service with host name as instance (telnet, rcommands) +KRB_NT_SRV_XHST 4 Service with host as remaining components +KRB_NT_UID 5 Unique ID + +error codes + +KDC_ERR_NONE 0 No error +KDC_ERR_NAME_EXP 1 Client's entry in database has expired +KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired +KDC_ERR_BAD_PVNO 3 Requested protocol version number not supported +KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key +KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key +KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database +KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database +KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database +KDC_ERR_NULL_KEY 9 The client or server has a null key +KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating +KDC_ERR_NEVER_VALID 11 Requested start time is later than end time +KDC_ERR_POLICY 12 KDC policy rejects request +KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option +KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type +KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type +KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type +KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type +KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked +KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked +KDC_ERR_TGT_REVOKED 20 TGT has been revoked +KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later +KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later +KDC_ERR_KEY_EXPIRED 23 Password has expired - change password to reset +KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid +KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired- +KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match +KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user only +KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path +KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed +KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired +KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid +KRB_AP_ERR_REPEAT 34 Request is a replay +KRB_AP_ERR_NOT_US 35 The ticket isn't for us +KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match +KRB_AP_ERR_SKEW 37 Clock skew too great +KRB_AP_ERR_BADADDR 38 Incorrect net address +KRB_AP_ERR_BADVERSION 39 Protocol version mismatch +KRB_AP_ERR_MSG_TYPE 40 Invalid msg type +KRB_AP_ERR_MODIFIED 41 Message stream modified +KRB_AP_ERR_BADORDER 42 Message out of order +KRB_AP_ERR_BADKEYVER 44 Specified version of key is not available +KRB_AP_ERR_NOKEY 45 Service key not available +KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed +KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction +KRB_AP_ERR_METHOD 48 Alternative authentication method required +KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message + + + +Section 8.3. - 94 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in message +KRB_ERR_GENERIC 60 Generic error (description in e-text) +KRB_ERR_FIELD_TOOLONG 61 Field is too long for this implementation +KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) +KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) +KDC_ERROR_INVALID_SIG 64 (pkinit) +KDC_ERR_KEY_TOO_WEAK 65 (pkinit) + + +9. Interoperability requirements + + Version 5 of the Kerberos protocol supports a myriad of +options. Among these are multiple encryption and checksum +types, alternative encoding schemes for the transited field, +optional mechanisms for pre-authentication, the handling of +tickets with no addresses, options for mutual authentica- +tion, user to user authentication, support for proxies, for- +warding, postdating, and renewing tickets, the format of +realm names, and the handling of authorization data. + + In order to ensure the interoperability of realms, it +is necessary to define a minimal configuration which must be +supported by all implementations. This minimal configura- +tion is subject to change as technology does. For example, +if at some later date it is discovered that one of the +required encryption or checksum algorithms is not secure, it +will be replaced. + +9.1. Specification 1 + + This section defines the first specification of these +options. Implementations which are configured in this way +can be said to support Kerberos Version 5 Specification 1 +(5.1). + +Encryption and checksum methods + +The following encryption and checksum mechanisms must be +supported. Implementations may support other mechanisms as +well, but the additional mechanisms may only be used when +communicating with principals known to also support them: +This list is to be determined. +Encryption: DES-CBC-MD5 +Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 + + +__________________________ +- This error carries additional information in the e- +data field. The contents of the e-data field for this +message is described in section 5.9.1. + + + +Section 9.1. - 95 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +Realm Names + +All implementations must understand hierarchical realms in +both the Internet Domain and the X.500 style. When a ticket +granting ticket for an unknown realm is requested, the KDC +must be able to determine the names of the intermediate +realms between the KDCs realm and the requested realm. + +Transited field encoding + +DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be +supported. Alternative encodings may be supported, but they +may be used only when that encoding is supported by ALL +intermediate realms. + +Pre-authentication methods + +The TGS-REQ method must be supported. The TGS-REQ method is +not used on the initial request. The PA-ENC-TIMESTAMP +method must be supported by clients but whether it is +enabled by default may be determined on a realm by realm +basis. If not used in the initial request and the error +KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC- +TIMESTAMP as an acceptable method, the client should retry +the initial request using the PA-ENC-TIMESTAMP pre- +authentication method. Servers need not support the PA- +ENC-TIMESTAMP method, but if not supported the server should +ignore the presence of PA-ENC-TIMESTAMP pre-authentication +in a request. + +Mutual authentication + +Mutual authentication (via the KRB_AP_REP message) must be +supported. + + +Ticket addresses and flags + +All KDC's must pass on tickets that carry no addresses (i.e. +if a TGT contains no addresses, the KDC will return deriva- +tive tickets), but each realm may set its own policy for +issuing such tickets, and each application server will set +its own policy with respect to accepting them. + + Proxies and forwarded tickets must be supported. Indi- +vidual realms and application servers can set their own pol- +icy on when such tickets will be accepted. + + All implementations must recognize renewable and post- +dated tickets, but need not actually implement them. If +these options are not supported, the starttime and endtime +in the ticket shall specify a ticket's entire useful life. +When a postdated ticket is decoded by a server, all imple- +mentations shall make the presence of the postdated flag + + +Section 9.1. - 96 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +visible to the calling server. + +User-to-user authentication + +Support for user to user authentication (via the ENC-TKT- +IN-SKEY KDC option) must be provided by implementations, but +individual realms may decide as a matter of policy to reject +such requests on a per-principal or realm-wide basis. + +Authorization data + +Implementations must pass all authorization data subfields +from ticket-granting tickets to any derivative tickets +unless directed to suppress a subfield as part of the defin- +ition of that registered subfield type (it is never +incorrect to pass on a subfield, and no registered subfield +types presently specify suppression at the KDC). + + Implementations must make the contents of any authori- +zation data subfields available to the server when a ticket +is used. Implementations are not required to allow clients +to specify the contents of the authorization data fields. + +9.2. Recommended KDC values + +Following is a list of recommended values for a KDC imple- +mentation, based on the list of suggested configuration con- +stants (see section 4.4). + +minimum lifetime 5 minutes + +maximum renewable lifetime1 week + +maximum ticket lifetime1 day + +empty addresses only when suitable restrictions appear + in authorization data + +proxiable, etc. Allowed. + + + + + + + + + + + + + + + + + +Section 9.2. - 97 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +10. REFERENCES + + + +1. B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- + cation Service for Computer Networks," IEEE Communica- + tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). + +2. S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. + Saltzer, Section E.2.1: Kerberos Authentication and + Authorization System, M.I.T. Project Athena, Cambridge, + Massachusetts (December 21, 1987). + +3. J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- + beros: An Authentication Service for Open Network Sys- + tems," pp. 191-202 in Usenix Conference Proceedings, + Dallas, Texas (February, 1988). + +4. Roger M. Needham and Michael D. Schroeder, "Using + Encryption for Authentication in Large Networks of Com- + puters," Communications of the ACM, Vol. 21(12), + pp. 993-999 (December, 1978). + +5. Dorothy E. Denning and Giovanni Maria Sacco, "Time- + stamps in Key Distribution Protocols," Communications + of the ACM, Vol. 24(8), pp. 533-536 (August 1981). + +6. John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, + "The Evolution of the Kerberos Authentication Service," + in an IEEE Computer Society Text soon to be published + (June 1992). + +7. B. Clifford Neuman, "Proxy-Based Authorization and + Accounting for Distributed Systems," in Proceedings of + the 13th International Conference on Distributed Com- + puting Systems, Pittsburgh, PA (May, 1993). + +8. Don Davis and Ralph Swick, "Workstation Services and + Kerberos Authentication at Project Athena," Technical + Memorandum TM-424, MIT Laboratory for Computer Science + (February 1990). + +9. P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- + merfeld, and K. Raeburn, Section E.1: Service Manage- + ment System, M.I.T. Project Athena, Cambridge, Mas- + sachusetts (1987). + +10. CCITT, Recommendation X.509: The Directory Authentica- + tion Framework, December 1988. + +11. J. Pato, Using Pre-Authentication to Avoid Password + Guessing Attacks, Open Software Foundation DCE Request + for Comments 26 (December 1992). + + + +Section 10. - 98 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +12. National Bureau of Standards, U.S. Department of Com- + merce, "Data Encryption Standard," Federal Information + Processing Standards Publication 46, Washington, DC + (1977). + +13. National Bureau of Standards, U.S. Department of Com- + merce, "DES Modes of Operation," Federal Information + Processing Standards Publication 81, Springfield, VA + (December 1980). + +14. Stuart G. Stubblebine and Virgil D. Gligor, "On Message + Integrity in Cryptographic Protocols," in Proceedings + of the IEEE Symposium on Research in Security and + Privacy, Oakland, California (May 1992). + +15. International Organization for Standardization, "ISO + Information Processing Systems - Data Communication - + High-Level Data Link Control Procedure - Frame Struc- + ture," IS 3309 (October 1984). 3rd Edition. + +16. R. Rivest, "The MD4 Message Digest Algorithm," RFC + 1320, MIT Laboratory for Computer Science (April + 1992). + +17. R. Rivest, "The MD5 Message Digest Algorithm," RFC + 1321, MIT Laboratory for Computer Science (April + 1992). + +18. H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication," Working Draft + draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). + + + + + + + + + + + + + + + + + + + + + + + + + +Section 10. - 99 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +A. Pseudo-code for protocol processing + + This appendix provides pseudo-code describing how the +messages are to be constructed and interpreted by clients +and servers. + +A.1. KRB_AS_REQ generation + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_AS_REQ */ + + if(pa_enc_timestamp_required) then + request.padata.padata-type = PA-ENC-TIMESTAMP; + get system_time; + padata-body.patimestamp,pausec = system_time; + encrypt padata-body into request.padata.padata-value + using client.key; /* derived from password */ + endif + + body.kdc-options := users's preferences; + body.cname := user's name; + body.realm := user's realm; + body.sname := service's name; /* usually "krbtgt", "localrealm" */ + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + omit body.enc-authorization-data; + request.req-body := body; + + kerberos := lookup(name of local kerberos server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.2. KRB_AS_REQ verification and KRB_AS_REP generation + decode message into req; + + client := lookup(req.cname,req.realm); + server := lookup(req.sname,req.realm); + + +Section A.2. - 100 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + + get system_time; + kdc_time := system_time.seconds; + + if (!client) then + /* no client in Database */ + error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); + endif + if (!server) then + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + + if(client.pa_enc_timestamp_required and + pa_enc_timestamp not present) then + error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); + endif + + if(pa_enc_timestamp present) then + decrypt req.padata-value into decrypted_enc_timestamp + using client.key; + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + if(decrypted_enc_timestamp is not within allowable skew) then + error_out(KDC_ERR_PREAUTH_FAILED); + endif + if(decrypted_enc_timestamp and usec is replay) + error_out(KDC_ERR_PREAUTH_FAILED); + endif + add decrypted_enc_timestamp and usec to replay cache; + endif + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := req.srealm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + if (req.kdc-options.FORWARDABLE is set) then + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.PROXIABLE is set) then + set new_tkt.flags.PROXIABLE; + endif + + +Section A.2. - 101 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + if (req.kdc-options.ALLOW-POSTDATE is set) then + set new_tkt.flags.MAY-POSTDATE; + endif + if ((req.kdc-options.RENEW is set) or + (req.kdc-options.VALIDATE is set) or + (req.kdc-options.PROXY is set) or + (req.kdc-options.FORWARDED is set) or + (req.kdc-options.ENC-TKT-IN-SKEY is set)) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.session := random_session_key(); + new_tkt.cname := req.cname; + new_tkt.crealm := req.crealm; + new_tkt.transited := empty_transited_field(); + + new_tkt.authtime := kdc_time; + + if (req.kdc-options.POSTDATED is set) then + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + new_tkt.starttime := req.from; + else + omit new_tkt.starttime; /* treated as authtime when omitted */ + endif + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till)) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := req.till; + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if (req.kdc-options.RENEWABLE is set) then + set new_tkt.flags.RENEWABLE; + + +Section A.2. - 102 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm); + else + omit new_tkt.renew-till; /* only present if RENEWABLE */ + endif + + if (req.addresses) then + new_tkt.caddr := req.addresses; + else + omit new_tkt.caddr; + endif + + new_tkt.authorization_data := empty_authorization_data(); + + encode to-be-encrypted part of ticket into OCTET STRING; + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + + + /* Start processing the response */ + + resp.pvno := 5; + resp.msg-type := KRB_AS_REP; + resp.cname := req.cname; + resp.crealm := req.realm; + resp.ticket := new_tkt; + + resp.key := new_tkt.session; + resp.last-req := fetch_last_request_info(client); + resp.nonce := req.nonce; + resp.key-expiration := client.expiration; + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + resp.realm := new_tkt.realm; + resp.sname := new_tkt.sname; + + resp.caddr := new_tkt.caddr; + + encode body of reply into OCTET STRING; + + resp.enc-part := encrypt OCTET STRING + using use_etype, client.key, client.p_kvno; + send(resp); + + + +Section A.2. - 103 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +A.3. KRB_AS_REP verification + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then + set pa_enc_timestamp_required; + goto KRB_AS_REQ; + endif + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key */ + /* from the response immediately */ + + key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, + resp.padata); + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and key; + zero(key); + + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + if near(resp.princ_exp) then + print(warning message); + endif + save_for_later(ticket,session,client,server,times,flags); + +A.4. KRB_AS_REP and KRB_TGS_REP common checks + if (decryption_error() or + (req.cname != resp.cname) or + (req.realm != resp.crealm) or + (req.sname != resp.sname) or + (req.realm != resp.realm) or + (req.nonce != resp.nonce) or + (req.addresses != resp.caddr)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + /* make sure no flags are set that shouldn't be, and that all that */ + /* should be are set */ + if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.from = 0) and + (resp.starttime is not within allowable skew)) then + destroy resp.key; + return KRB_AP_ERR_SKEW; + + +Section A.4. - 104 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + endif + if ((req.from != 0) and (req.from != resp.starttime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.till != 0) and (resp.endtime > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (req.rtime != 0) and (resp.renew-till > req.rtime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.kdc-options.RENEWABLE-OK is set) and + (resp.flags.RENEWABLE) and + (req.till != 0) and + (resp.renew-till > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + +A.5. KRB_TGS_REQ generation + /* Note that make_application_request might have to recursivly */ + /* call this routine to get the appropriate ticket-granting ticket */ + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_TGS_REQ */ + + body.kdc-options := users's preferences; + /* If the TGT is not for the realm of the end-server */ + /* then the sname will be for a TGT for the end-realm */ + /* and the realm of the requested ticket (body.realm) */ + /* will be that of the TGS to which the TGT we are */ + /* sending applies */ + body.sname := service's name; + body.realm := service's realm; + + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + + +Section A.5. - 105 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + endif + + body.enc-authorization-data := user-supplied data; + if (body.kdc-options.ENC-TKT-IN-SKEY) then + body.additional-tickets_ticket := second TGT; + endif + + request.req-body := body; + check := generate_checksum (req.body,checksumtype); + + request.padata[0].padata-type := PA-TGS-REQ; + request.padata[0].padata-value := create a KRB_AP_REQ using + the TGT and checksum + + /* add in any other padata as required/supplied */ + + kerberos := lookup(name of local kerberose server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation + /* note that reading the application request requires first + determining the server for which a ticket was issued, and choosing the + correct key for decryption. The name of the server appears in the + plaintext part of the ticket. */ + + if (no KRB_AP_REQ in req.padata) then + error_out(KDC_ERR_PADATA_TYPE_NOSUPP); + endif + verify KRB_AP_REQ in req.padata; + + /* Note that the realm in which the Kerberos server is operating is + determined by the instance from the ticket-granting ticket. The realm + in the ticket-granting ticket is the realm under which the ticket + granting ticket was issued. It is possible for a single Kerberos + server to support more than one realm. */ + + auth_hdr := KRB_AP_REQ; + tgt := auth_hdr.ticket; + + if (tgt.sname is not a TGT for local realm and is not req.sname) then + error_out(KRB_AP_ERR_NOT_US); + + realm := realm_tgt_is_for(tgt); + + decode remainder of request; + + if (auth_hdr.authenticator.cksum is missing) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + +Section A.6. - 106 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + if (auth_hdr.authenticator.cksum type is not supported) then + error_out(KDC_ERR_SUMTYPE_NOSUPP); + endif + if (auth_hdr.authenticator.cksum is not both collision-proof and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + set computed_checksum := checksum(req); + if (computed_checksum != auth_hdr.authenticatory.cksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + server := lookup(req.sname,realm); + + if (!server) then + if (is_foreign_tgt_name(server)) then + server := best_intermediate_tgs(server); + else + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + endif + + session := generate_random_session_key(); + + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := realm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + new_tkt.caddr := tgt.caddr; + resp.caddr := NULL; /* We only include this if they change */ + if (req.kdc-options.FORWARDABLE is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.FORWARDED is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDED; + + +Section A.6. - 107 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + if (tgt.flags.FORWARDED is set) then + set new_tkt.flags.FORWARDED; + endif + + if (req.kdc-options.PROXIABLE is set) then + if (tgt.flags.PROXIABLE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.PROXY is set) then + if (tgt.flags.PROXIABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXY; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + if (tgt.flags.MAY-POSTDATE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.MAY-POSTDATE; + endif + if (req.kdc-options.POSTDATED is set) then + if (tgt.flags.MAY-POSTDATE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + new_tkt.starttime := req.from; + endif + + + if (req.kdc-options.VALIDATE is set) then + if (tgt.flags.INVALID is reset) then + error_out(KDC_ERR_POLICY); + endif + if (tgt.starttime > kdc_time) then + error_out(KRB_AP_ERR_NYV); + endif + if (check_hot_list(tgt)) then + error_out(KRB_AP_ERR_REPEAT); + endif + tkt := tgt; + reset new_tkt.flags.INVALID; + endif + + +Section A.6. - 108 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, + and those already processed) is set) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.authtime := tgt.authtime; + + if (req.kdc-options.RENEW is set) then + /* Note that if the endtime has already passed, the ticket would */ + /* have been rejected in the initial authentication stage, so */ + /* there is no need to check again here */ + if (tgt.flags.RENEWABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + if (tgt.renew-till >= kdc_time) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + tkt := tgt; + new_tkt.starttime := kdc_time; + old_life := tgt.endttime - tgt.starttime; + new_tkt.endtime := min(tgt.renew-till, + new_tkt.starttime + old_life); + else + new_tkt.starttime := kdc_time; + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm, + tgt.endtime); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till) and + (tgt.flags.RENEWABLE is set) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := min(req.till, tgt.renew-till); + endif + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (tgt.flags.RENEWABLE is set)) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + + +Section A.6. - 109 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm, + tgt.renew-till); + else + new_tkt.renew-till := OMIT; /* leave the renew-till field out */ + endif + if (req.enc-authorization-data is present) then + decrypt req.enc-authorization-data into decrypted_authorization_data + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + endif + new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data + + decrypted_authorization_data; + + new_tkt.key := session; + new_tkt.crealm := tgt.crealm; + new_tkt.cname := req.auth_hdr.ticket.cname; + + if (realm_tgt_is_for(tgt) := tgt.realm) then + /* tgt issued by local realm */ + new_tkt.transited := tgt.transited; + else + /* was issued for this realm by some other realm */ + if (tgt.transited.tr-type not supported) then + error_out(KDC_ERR_TRTYPE_NOSUPP); + endif + new_tkt.transited := compress_transited(tgt.transited + tgt.realm) + endif + + encode encrypted part of new_tkt into OCTET STRING; + if (req.kdc-options.ENC-TKT-IN-SKEY is set) then + if (server not specified) then + server = req.second_ticket.client; + endif + if ((req.second_ticket is not a TGT) or + (req.second_ticket.client != server)) then + error_out(KDC_ERR_POLICY); + endif + + new_tkt.enc-part := encrypt OCTET STRING using + using etype_for_key(second-ticket.key), second-ticket.key; + else + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + endif + + resp.pvno := 5; + resp.msg-type := KRB_TGS_REP; + resp.crealm := tgt.crealm; + resp.cname := tgt.cname; + + + +Section A.6. - 110 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + resp.ticket := new_tkt; + + resp.key := session; + resp.nonce := req.nonce; + resp.last-req := fetch_last_request_info(client); + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + omit resp.key-expiration; + + resp.sname := new_tkt.sname; + resp.realm := new_tkt.realm; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + + encode body of reply into OCTET STRING; + + if (req.padata.authenticator.subkey) + resp.enc-part := encrypt OCTET STRING using use_etype, + req.padata.authenticator.subkey; + else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; + + send(resp); + +A.7. KRB_TGS_REP verification + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key from + the response immediately */ + + if (req.padata.authenticator.subkey) + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and subkey; + else unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and tgt's session key; + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + check authorization_data as necessary; + save_for_later(ticket,session,client,server,times,flags); + + + +Section A.7. - 111 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +A.8. Authenticator generation + body.authenticator-vno := authenticator vno; /* = 5 */ + body.cname, body.crealm := client name; + if (supplying checksum) then + body.cksum := checksum; + endif + get system_time; + body.ctime, body.cusec := system_time; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + +A.9. KRB_AP_REQ generation + obtain ticket and session_key from cache; + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REQ */ + + if (desired(MUTUAL_AUTHENTICATION)) then + set packet.ap-options.MUTUAL-REQUIRED; + else + reset packet.ap-options.MUTUAL-REQUIRED; + endif + if (using session key for ticket) then + set packet.ap-options.USE-SESSION-KEY; + else + reset packet.ap-options.USE-SESSION-KEY; + endif + packet.ticket := ticket; /* ticket */ + generate authenticator; + encode authenticator into OCTET STRING; + encrypt OCTET STRING into packet.authenticator using session_key; + +A.10. KRB_AP_REQ verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REQ) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.ticket.tkt_vno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.ap_options.USE-SESSION-KEY is set) then + retrieve session key from ticket-granting ticket for + packet.ticket.{sname,srealm,enc-part.etype}; + + +Section A.10. - 112 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + else + retrieve service key for + packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; + endif + if (no_key_available) then + if (cannot_find_specified_skvno) then + error_out(KRB_AP_ERR_BADKEYVER); + else + error_out(KRB_AP_ERR_NOKEY); + endif + endif + decrypt packet.ticket.enc-part into decr_ticket using retrieved key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + decrypt packet.authenticator into decr_authenticator + using decr_ticket.key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (decr_authenticator.{cname,crealm} != + decr_ticket.{cname,crealm}) then + error_out(KRB_AP_ERR_BADMATCH); + endif + if (decr_ticket.caddr is present) then + if (sender_address(packet) is not in decr_ticket.caddr) then + error_out(KRB_AP_ERR_BADADDR); + endif + elseif (application requires addresses) then + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(decr_authenticator.ctime, + decr_authenticator.cusec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then + error_out(KRB_AP_ERR_REPEAT); + endif + save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); + get system_time; + if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or + (decr_ticket.flags.INVALID is set)) then + /* it hasn't yet become valid */ + error_out(KRB_AP_ERR_TKT_NYV); + endif + if (system_time-decr_ticket.endtime > CLOCK_SKEW) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + /* caller must check decr_ticket.flags for any pertinent details */ + return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); + +A.11. KRB_AP_REP generation + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REP */ + + +Section A.11. - 113 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + body.ctime := packet.ctime; + body.cusec := packet.cusec; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part; + +A.12. KRB_AP_REP verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REP) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + cleartext := decrypt(packet.enc-part) using ticket's session key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (cleartext.ctime != authenticator.ctime) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.cusec != authenticator.cusec) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.subkey is present) then + save cleartext.subkey for future use; + endif + if (cleartext.seq-number is present) then + save cleartext.seq-number for future verifications; + endif + return(AUTHENTICATION_SUCCEEDED); + +A.13. KRB_SAFE generation + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_SAFE */ + + body.user-data := buffer; /* DATA */ + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + + +Section A.13. - 114 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + checksum.cksumtype := checksum type; + compute checksum over body; + checksum.checksum := checksum value; /* checksum.checksum */ + packet.cksum := checksum; + packet.safe-body := body; + +A.14. KRB_SAFE verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_SAFE) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.checksum.cksumtype is not both collision-proof and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (safe_priv_common_checks_ok(packet)) then + set computed_checksum := checksum(packet.body); + if (computed_checksum != packet.checksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + return (packet, PACKET_IS_GENUINE); + else + return common_checks_error; + endif + +A.15. KRB_SAFE and KRB_PRIV common checks + if (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (((packet.timestamp is present) and + (not in_clock_skew(packet.timestamp,packet.usec))) or + (packet.timestamp is not present and timestamp expected)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + + +Section A.15. - 115 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + if (((packet.seq-number is present) and + ((not in_sequence(packet.seq-number)))) or + (packet.seq-number is not present and sequence expected)) then + error_out(KRB_AP_ERR_BADORDER); + endif + if (packet.timestamp not present and packet.seq-number not present) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + save_identifier(packet.{timestamp,usec,s-address}, + sender_principal(packet)); + + return PACKET_IS_OK; + +A.16. KRB_PRIV generation + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_PRIV */ + + packet.enc-part.etype := encryption type; + + body.user-data := buffer; + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher; + + +A.17. KRB_PRIV verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_PRIV) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + + +Section A.17. - 116 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + + if (safe_priv_common_checks_ok(cleartext)) then + return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); + else + return common_checks_error; + endif + +A.18. KRB_CRED generation + invoke KRB_TGS; /* obtain tickets to be provided to peer */ + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_CRED */ + + for (tickets[n] in tickets to be forwarded) do + packet.tickets[n] = tickets[n].ticket; + done + + packet.enc-part.etype := encryption type; + + for (ticket[n] in tickets to be forwarded) do + body.ticket-info[n].key = tickets[n].session; + body.ticket-info[n].prealm = tickets[n].crealm; + body.ticket-info[n].pname = tickets[n].cname; + body.ticket-info[n].flags = tickets[n].flags; + body.ticket-info[n].authtime = tickets[n].authtime; + body.ticket-info[n].starttime = tickets[n].starttime; + body.ticket-info[n].endtime = tickets[n].endtime; + body.ticket-info[n].renew-till = tickets[n].renew-till; + body.ticket-info[n].srealm = tickets[n].srealm; + body.ticket-info[n].sname = tickets[n].sname; + body.ticket-info[n].caddr = tickets[n].caddr; + done + + get system_time; + body.timestamp, body.usec := system_time; + + if (using nonce) then + body.nonce := nonce; + endif + + if (using s-address) then + body.s-address := sender host addresses; + endif + if (limited recipients) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher + + +Section A.18. - 117 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + using negotiated encryption key; + + +A.19. KRB_CRED verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_CRED) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if ((packet.r-address is present or required) and + (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(packet.timestamp,packet.usec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + if (packet.nonce is required or present) and + (packet.nonce != expected-nonce) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + for (ticket[n] in tickets that were forwarded) do + save_for_later(ticket[n],key[n],principal[n], + server[n],times[n],flags[n]); + return + +A.20. KRB_ERROR generation + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_ERROR */ + + get system_time; + packet.stime, packet.susec := system_time; + packet.realm, packet.sname := server name; + + if (client time available) then + + +Section A.20. - 118 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + packet.ctime, packet.cusec := client_time; + endif + packet.error-code := error code; + if (client name available) then + packet.cname, packet.crealm := client name; + endif + if (error text available) then + packet.e-text := error text; + endif + if (error data available) then + packet.e-data := error data; + endif + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - 119 - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - cxx - Expires 11 January 1998 + + + + + + + + + + + Table of Contents + + + + +Overview .............................................. 2 + +Background ............................................ 2 + +1. Introduction ....................................... 3 + +1.1. Cross-Realm Operation ............................ 5 + +1.2. Authorization .................................... 6 + +1.3. Environmental assumptions ........................ 7 + +1.4. Glossary of terms ................................ 8 + +2. Ticket flag uses and requests ...................... 10 + +2.1. Initial and pre-authenticated tickets ............ 10 + +2.2. Invalid tickets .................................. 11 + +2.3. Renewable tickets ................................ 11 + +2.4. Postdated tickets ................................ 12 + +2.5. Proxiable and proxy tickets ...................... 12 + +2.6. Forwardable tickets .............................. 13 + +2.7. Other KDC options ................................ 14 + +3. Message Exchanges .................................. 14 + +3.1. The Authentication Service Exchange .............. 14 + +3.1.1. Generation of KRB_AS_REQ message ............... 16 + +3.1.2. Receipt of KRB_AS_REQ message .................. 16 + +3.1.3. Generation of KRB_AS_REP message ............... 16 + +3.1.4. Generation of KRB_ERROR message ................ 19 + +3.1.5. Receipt of KRB_AS_REP message .................. 19 + +3.1.6. Receipt of KRB_ERROR message ................... 19 + +3.2. The Client/Server Authentication Exchange ........ 19 + +3.2.1. The KRB_AP_REQ message ......................... 20 + + + - i - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +3.2.2. Generation of a KRB_AP_REQ message ............. 20 + +3.2.3. Receipt of KRB_AP_REQ message .................. 21 + +3.2.4. Generation of a KRB_AP_REP message ............. 23 + +3.2.5. Receipt of KRB_AP_REP message .................. 23 + +3.2.6. Using the encryption key ....................... 24 + +3.3. The Ticket-Granting Service (TGS) Exchange ....... 25 + +3.3.1. Generation of KRB_TGS_REQ message .............. 26 + +3.3.2. Receipt of KRB_TGS_REQ message ................. 27 + +3.3.3. Generation of KRB_TGS_REP message .............. 28 + +3.3.3.1. Checking for revoked tickets ................. 30 + +3.3.3.2. Encoding the transited field ................. 30 + +3.3.4. Receipt of KRB_TGS_REP message ................. 32 + +3.4. The KRB_SAFE Exchange ............................ 32 + +3.4.1. Generation of a KRB_SAFE message ............... 32 + +3.4.2. Receipt of KRB_SAFE message .................... 33 + +3.5. The KRB_PRIV Exchange ............................ 34 + +3.5.1. Generation of a KRB_PRIV message ............... 34 + +3.5.2. Receipt of KRB_PRIV message .................... 34 + +3.6. The KRB_CRED Exchange ............................ 35 + +3.6.1. Generation of a KRB_CRED message ............... 35 + +3.6.2. Receipt of KRB_CRED message .................... 35 + +4. The Kerberos Database .............................. 36 + +4.1. Database contents ................................ 36 + +4.2. Additional fields ................................ 37 + +4.3. Frequently Changing Fields ....................... 38 + +4.4. Site Constants ................................... 39 + +5. Message Specifications ............................. 39 + + + + - ii - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +5.1. ASN.1 Distinguished Encoding Representation ...... 39 + +5.2. ASN.1 Base Definitions ........................... 40 + +5.3. Tickets and Authenticators ....................... 43 + +5.3.1. Tickets ........................................ 43 + +5.3.2. Authenticators ................................. 52 + +5.4. Specifications for the AS and TGS exchanges ...... 54 + +5.4.1. KRB_KDC_REQ definition ......................... 54 + +5.4.2. KRB_KDC_REP definition ......................... 61 + +5.5. Client/Server (CS) message specifications ........ 64 + +5.5.1. KRB_AP_REQ definition .......................... 64 + +5.5.2. KRB_AP_REP definition .......................... 65 + +5.5.3. Error message reply ............................ 67 + +5.6. KRB_SAFE message specification ................... 67 + +5.6.1. KRB_SAFE definition ............................ 67 + +5.7. KRB_PRIV message specification ................... 68 + +5.7.1. KRB_PRIV definition ............................ 68 + +5.8. KRB_CRED message specification ................... 69 + +5.8.1. KRB_CRED definition ............................ 70 + +5.9. Error message specification ...................... 72 + +5.9.1. KRB_ERROR definition ........................... 72 + +6. Encryption and Checksum Specifications ............. 74 + +6.1. Encryption Specifications ........................ 76 + +6.2. Encryption Keys .................................. 78 + +6.3. Encryption Systems ............................... 78 + +6.3.1. The NULL Encryption System (null) .............. 78 + +6.3.2. DES in CBC mode with a CRC-32 checksum (des- +cbc-crc) .............................................. 79 + +6.3.3. DES in CBC mode with an MD4 checksum (des- + + + - iii - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +cbc-md4) .............................................. 79 + +6.3.4. DES in CBC mode with an MD5 checksum (des- +cbc-md5) .............................................. 79 + +6.3.5. Triple DES EDE in outer CBC mode with an SHA1 +checksum (des3-cbc-sha1) .............................. 81 + +6.4. Checksums ........................................ 83 + +6.4.1. The CRC-32 Checksum (crc32) .................... 84 + +6.4.2. The RSA MD4 Checksum (rsa-md4) ................. 84 + +6.4.3. RSA MD4 Cryptographic Checksum Using DES +(rsa-md4-des) ......................................... 84 + +6.4.4. The RSA MD5 Checksum (rsa-md5) ................. 85 + +6.4.5. RSA MD5 Cryptographic Checksum Using DES +(rsa-md5-des) ......................................... 85 + +6.4.6. DES cipher-block chained checksum (des-mac) + +6.4.7. RSA MD4 Cryptographic Checksum Using DES +alternative (rsa-md4-des-k) ........................... 86 + +6.4.8. DES cipher-block chained checksum alternative +(des-mac-k) ........................................... 87 + +7. Naming Constraints ................................. 87 + +7.1. Realm Names ...................................... 87 + +7.2. Principal Names .................................. 88 + +7.2.1. Name of server principals ...................... 89 + +8. Constants and other defined values ................. 90 + +8.1. Host address types ............................... 90 + +8.2. KDC messages ..................................... 91 + +8.2.1. IP transport ................................... 91 + +8.2.2. OSI transport .................................. 91 + +8.2.3. Name of the TGS ................................ 92 + +8.3. Protocol constants and associated values ......... 92 + +9. Interoperability requirements ...................... 95 + + + + - iv - Expires 11 January 1998 + + + + + + + + Version 5 - Specification Revision 6 + + +9.1. Specification 1 .................................. 95 + +9.2. Recommended KDC values ........................... 97 + +10. REFERENCES ........................................ 98 + +A. Pseudo-code for protocol processing ................ 100 + +A.1. KRB_AS_REQ generation ............................ 100 + +A.2. KRB_AS_REQ verification and KRB_AS_REP genera- +tion .................................................. 100 + +A.3. KRB_AS_REP verification .......................... 104 + +A.4. KRB_AS_REP and KRB_TGS_REP common checks ......... 104 + +A.5. KRB_TGS_REQ generation ........................... 105 + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP gen- +eration ............................................... 106 + +A.7. KRB_TGS_REP verification ......................... 111 + +A.8. Authenticator generation ......................... 112 + +A.9. KRB_AP_REQ generation ............................ 112 + +A.10. KRB_AP_REQ verification ......................... 112 + +A.11. KRB_AP_REP generation ........................... 113 + +A.12. KRB_AP_REP verification ......................... 114 + +A.13. KRB_SAFE generation ............................. 114 + +A.14. KRB_SAFE verification ........................... 115 + +A.15. KRB_SAFE and KRB_PRIV common checks ............. 115 + +A.16. KRB_PRIV generation ............................. 116 + +A.17. KRB_PRIV verification ........................... 116 + +A.18. KRB_CRED generation ............................. 117 + +A.19. KRB_CRED verification ........................... 118 + +A.20. KRB_ERROR generation ............................ 118 + + + + + + + + - v - Expires 11 January 1998 + + + + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt new file mode 100644 index 0000000..78db9d7 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt @@ -0,0 +1,6214 @@ + +INTERNET-DRAFT Clifford Neuman + John Kohl + Theodore Ts'o + 21 November 1997 + +The Kerberos Network Authentication Service (V5) + +STATUS OF THIS MEMO + +This document is an Internet-Draft. 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.' + +To learn the current status of any Internet-Draft, please check the +'1id-abstracts.txt' listing contained in the Internet-Drafts Shadow +Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), +ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). + +The distribution of this memo is unlimited. It is filed as +draft-ietf-cat-kerberos-r-01.txt, and expires 21 May 1998. Please send +comments to: krb-protocol@MIT.EDU + +ABSTRACT + +This document provides an overview and specification of Version 5 of the +Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol +and its intended use that require more detailed or clearer explanation than +was provided in RFC1510. This document is intended to provide a detailed +description of the protocol, suitable for implementation, together with +descriptions of the appropriate use of protocol messages and fields within +those messages. + +This document is not intended to describe Kerberos to the end user, system +administrator, or application developer. Higher level papers describing +Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], +are available elsewhere. + +OVERVIEW + +This INTERNET-DRAFT describes the concepts and model upon which the Kerberos +network authentication system is based. It also specifies Version 5 of the +Kerberos protocol. + +The motivations, goals, assumptions, and rationale behind most design +decisions are treated cursorily; they are more fully described in a paper +available in IEEE communications [NT94] and earlier in the Kerberos portion +of the Athena Technical Plan [MNSS87]. The protocols have been a proposed + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +standard and are being considered for advancement for draft standard through +the IETF standard process. Comments are encouraged on the presentation, but +only minor refinements to the protocol as implemented or extensions that fit +within current protocol framework will be considered at this time. + +Requests for addition to an electronic mailing list for discussion of +Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. +This mailing list is gatewayed onto the Usenet as the group +comp.protocols.kerberos. Requests for further information, including +documents and code availability, may be sent to info-kerberos@MIT.EDU. + +BACKGROUND + +The Kerberos model is based in part on Needham and Schroeder's trusted +third-party authentication protocol [NS78] and on modifications suggested by +Denning and Sacco [DS81]. The original design and implementation of Kerberos +Versions 1 through 4 was the work of two former Project Athena staff +members, Steve Miller of Digital Equipment Corporation and Clifford Neuman +(now at the Information Sciences Institute of the University of Southern +California), along with Jerome Saltzer, Technical Director of Project +Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many other members +of Project Athena have also contributed to the work on Kerberos. + +Version 5 of the Kerberos protocol (described in this document) has evolved +from Version 4 based on new requirements and desires for features not +available in Version 4. The design of Version 5 of the Kerberos protocol was +led by Clifford Neuman and John Kohl with much input from the community. The +development of the MIT reference implementation was led at MIT by John Kohl +and Theodore T'so, with help and contributed code from many others. +Reference implementations of both version 4 and version 5 of Kerberos are +publicly available and commercial implementations have been developed and +are widely used. + +Details on the differences between Kerberos Versions 4 and 5 can be found in +[KNT92]. + +1. Introduction + +Kerberos provides a means of verifying the identities of principals, (e.g. a +workstation user or a network server) on an open (unprotected) network. This +is accomplished without relying on assertions by the host operating system, +without basing trust on host addresses, without requiring physical security +of all the hosts on the network, and under the assumption that packets +traveling along the network can be read, modified, and inserted at will[1]. +Kerberos performs authentication under these conditions as a trusted +third-party authentication service by using conventional (shared secret key +[2] cryptography. Kerberos extensions have been proposed and implemented +that provide for the use of public key cryptography during certain phases of +the authentication protocol. These extensions provide for authentication of +users registered with public key certification authorities, and allow the +system to provide certain benefits of public key cryptography in situations +where they are needed. + +The basic Kerberos authentication process proceeds as follows: A client + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +sends a request to the authentication server (AS) requesting 'credentials' +for a given server. The AS responds with these credentials, encrypted in the +client's key. The credentials consist of 1) a 'ticket' for the server and 2) +a temporary encryption key (often called a "session key"). The client +transmits the ticket (which contains the client's identity and a copy of the +session key, all encrypted in the server's key) to the server. The session +key (now shared by the client and server) is used to authenticate the +client, and may optionally be used to authenticate the server. It may also +be used to encrypt further communication between the two parties or to +exchange a separate sub-session key to be used to encrypt further +communication. + +Implementation of the basic protocol consists of one or more authentication +servers running on physically secure hosts. The authentication servers +maintain a database of principals (i.e., users and servers) and their secret +keys. Code libraries provide encryption and implement the Kerberos protocol. +In order to add authentication to its transactions, a typical network +application adds one or two calls to the Kerberos library directly or +through the Generic Security Services Application Programming Interface, +GSSAPI, described in separate document. These calls result in the +transmission of the necessary messages to achieve authentication. + +The Kerberos protocol consists of several sub-protocols (or exchanges). +There are two basic methods by which a client can ask a Kerberos server for +credentials. In the first approach, the client sends a cleartext request for +a ticket for the desired server to the AS. The reply is sent encrypted in +the client's secret key. Usually this request is for a ticket-granting +ticket (TGT) which can later be used with the ticket-granting server (TGS). +In the second method, the client sends a request to the TGS. The client uses +the TGT to authenticate itself to the TGS in the same manner as if it were +contacting any other application server that requires Kerberos +authentication. The reply is encrypted in the session key from the TGT. +Though the protocol specification describes the AS and the TGS as separate +servers, they are implemented in practice as different protocol entry points +within a single Kerberos server. + +Once obtained, credentials may be used to verify the identity of the +principals in a transaction, to ensure the integrity of messages exchanged +between them, or to preserve privacy of the messages. The application is +free to choose whatever protection may be necessary. + +To verify the identities of the principals in a transaction, the client +transmits the ticket to the application server. Since the ticket is sent "in +the clear" (parts of it are encrypted, but this encryption doesn't thwart +replay) and might be intercepted and reused by an attacker, additional +information is sent to prove that the message originated with the principal +to whom the ticket was issued. This information (called the authenticator) +is encrypted in the session key, and includes a timestamp. The timestamp +proves that the message was recently generated and is not a replay. +Encrypting the authenticator in the session key proves that it was generated +by a party possessing the session key. Since no one except the requesting +principal and the server know the session key (it is never sent over the +network in the clear) this guarantees the identity of the client. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +The integrity of the messages exchanged between principals can also be +guaranteed using the session key (passed in the ticket and contained in the +credentials). This approach provides detection of both replay attacks and +message stream modification attacks. It is accomplished by generating and +transmitting a collision-proof checksum (elsewhere called a hash or digest +function) of the client's message, keyed with the session key. Privacy and +integrity of the messages exchanged between principals can be secured by +encrypting the data to be passed using the session key contained in the +ticket or the subsession key found in the authenticator. + +The authentication exchanges mentioned above require read-only access to the +Kerberos database. Sometimes, however, the entries in the database must be +modified, such as when adding new principals or changing a principal's key. +This is done using a protocol between a client and a third Kerberos server, +the Kerberos Administration Server (KADM). There is also a protocol for +maintaining multiple copies of the Kerberos database. Neither of these +protocols are described in this document. + +1.1. Cross-Realm Operation + +The Kerberos protocol is designed to operate across organizational +boundaries. A client in one organization can be authenticated to a server in +another. Each organization wishing to run a Kerberos server establishes its +own 'realm'. The name of the realm in which a client is registered is part +of the client's name, and can be used by the end-service to decide whether +to honor a request. + +By establishing 'inter-realm' keys, the administrators of two realms can +allow a client authenticated in the local realm to prove its identity to +servers in other realms[3]. The exchange of inter-realm keys (a separate key +may be used for each direction) registers the ticket-granting service of +each realm as a principal in the other realm. A client is then able to +obtain a ticket-granting ticket for the remote realm's ticket-granting +service from its local realm. When that ticket-granting ticket is used, the +remote ticket-granting service uses the inter-realm key (which usually +differs from its own normal TGS key) to decrypt the ticket-granting ticket, +and is thus certain that it was issued by the client's own TGS. Tickets +issued by the remote ticket-granting service will indicate to the +end-service that the client was authenticated from another realm. + +A realm is said to communicate with another realm if the two realms share an +inter-realm key, or if the local realm shares an inter-realm key with an +intermediate realm that communicates with the remote realm. An +authentication path is the sequence of intermediate realms that are +transited in communicating from one realm to another. + +Realms are typically organized hierarchically. Each realm shares a key with +its parent and a different key with each child. If an inter-realm key is not +directly shared by two realms, the hierarchical organization allows an +authentication path to be easily constructed. If a hierarchical organization +is not used, it may be necessary to consult a database in order to construct +an authentication path between realms. + +Although realms are typically hierarchical, intermediate realms may be + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +bypassed to achieve cross-realm authentication through alternate +authentication paths (these might be established to make communication +between two realms more efficient). It is important for the end-service to +know which realms were transited when deciding how much faith to place in +the authentication process. To facilitate this decision, a field in each +ticket contains the names of the realms that were involved in authenticating +the client. + +The application server is ultimately responsible for accepting or rejecting +authentication and should check the transited field. The application server +may choose to rely on the KDC for the application server's realm to check +the transited field. The application server's KDC will set the +TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate +realms may also check the transited field as they issue +ticket-granting-tickets for other realms, but they are encouraged not to do +so. A client may request that the KDC's not check the transited field by +setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not +required to honor this flag. + +1.2. Authorization + +As an authentication service, Kerberos provides a means of verifying the +identity of principals on a network. Authentication is usually useful +primarily as a first step in the process of authorization, determining +whether a client may use a service, which objects the client is allowed to +access, and the type of access allowed for each. Kerberos does not, by +itself, provide authorization. Possession of a client ticket for a service +provides only for authentication of the client to that service, and in the +absence of a separate authorization procedure, it should not be considered +by an application as authorizing the use of that service. + +Such separate authorization methods may be implemented as application +specific access control functions and may be based on files such as the +application server, or on separately issued authorization credentials such +as those based on proxies [Neu93] , or on other authorization services. + +Applications should not be modified to accept the issuance of a service +ticket by the Kerberos server (even by an modified Kerberos server) as +granting authority to use the service, since such applications may become +vulnerable to the bypass of this authorization check in an environment if +they interoperate with other KDCs or where other options for application +authentication (e.g. the PKTAPP proposal) are provided. + +1.3. Environmental assumptions + +Kerberos imposes a few assumptions on the environment in which it can +properly function: + + * 'Denial of service' attacks are not solved with Kerberos. There are + places in these protocols where an intruder can prevent an application + from participating in the proper authentication steps. Detection and + solution of such attacks (some of which can appear to be nnot-uncommon + 'normal' failure modes for the system) is usually best left to the + human administrators and users. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + * Principals must keep their secret keys secret. If an intruder somehow + steals a principal's key, it will be able to masquerade as that + principal or impersonate any server to the legitimate principal. + * 'Password guessing' attacks are not solved by Kerberos. If a user + chooses a poor password, it is possible for an attacker to successfully + mount an offline dictionary attack by repeatedly attempting to decrypt, + with successive entries from a dictionary, messages obtained which are + encrypted under a key derived from the user's password. + * Each host on the network must have a clock which is 'loosely + synchronized' to the time of the other hosts; this synchronization is + used to reduce the bookkeeping needs of application servers when they + do replay detection. The degree of "looseness" can be configured on a + per-server basis, but is typically on the order of 5 minutes. If the + clocks are synchronized over the network, the clock synchronization + protocol must itself be secured from network attackers. + * Principal identifiers are not recycled on a short-term basis. A typical + mode of access control will use access control lists (ACLs) to grant + permissions to particular principals. If a stale ACL entry remains for + a deleted principal and the principal identifier is reused, the new + principal will inherit rights specified in the stale ACL entry. By not + re-using principal identifiers, the danger of inadvertent access is + removed. + +1.4. Glossary of terms + +Below is a list of terms used throughout this document. + +Authentication + Verifying the claimed identity of a principal. +Authentication header + A record containing a Ticket and an Authenticator to be presented to a + server as part of the authentication process. +Authentication path + A sequence of intermediate realms transited in the authentication + process when communicating from one realm to another. +Authenticator + A record containing information that can be shown to have been recently + generated using the session key known only by the client and server. +Authorization + The process of determining whether a client may use a service, which + objects the client is allowed to access, and the type of access allowed + for each. +Capability + A token that grants the bearer permission to access an object or + service. In Kerberos, this might be a ticket whose use is restricted by + the contents of the authorization data field, but which lists no + network addresses, together with the session key necessary to use the + ticket. +Ciphertext + The output of an encryption function. Encryption transforms plaintext + into ciphertext. +Client + A process that makes use of a network service on behalf of a user. Note + that in some cases a Server may itself be a client of some other server + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + (e.g. a print server may be a client of a file server). +Credentials + A ticket plus the secret session key necessary to successfully use that + ticket in an authentication exchange. +KDC + Key Distribution Center, a network service that supplies tickets and + temporary session keys; or an instance of that service or the host on + which it runs. The KDC services both initial ticket and ticket-granting + ticket requests. The initial ticket portion is sometimes referred to as + the Authentication Server (or service). The ticket-granting ticket + portion is sometimes referred to as the ticket-granting server (or + service). +Kerberos + Aside from the 3-headed dog guarding Hades, the name given to Project + Athena's authentication service, the protocol used by that service, or + the code used to implement the authentication service. +Plaintext + The input to an encryption function or the output of a decryption + function. Decryption transforms ciphertext into plaintext. +Principal + A uniquely named client or server instance that participates in a + network communication. +Principal identifier + The name used to uniquely identify each different principal. +Seal + To encipher a record containing several fields in such a way that the + fields cannot be individually replaced without either knowledge of the + encryption key or leaving evidence of tampering. +Secret key + An encryption key shared by a principal and the KDC, distributed + outside the bounds of the system, with a long lifetime. In the case of + a human user's principal, the secret key is derived from a password. +Server + A particular Principal which provides a resource to network clients. + The server is sometimes refered to as the Application Server. +Service + A resource provided to network clients; often provided by more than one + server (for example, remote file service). +Session key + A temporary encryption key used between two principals, with a lifetime + limited to the duration of a single login "session". +Sub-session key + A temporary encryption key used between two principals, selected and + exchanged by the principals using the session key, and with a lifetime + limited to the duration of a single association. +Ticket + A record that helps a client authenticate itself to a server; it + contains the client's identity, a session key, a timestamp, and other + information, all sealed using the server's secret key. It only serves + to authenticate a client when presented along with a fresh + Authenticator. + +2. Ticket flag uses and requests + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +Each Kerberos ticket contains a set of flags which are used to indicate +various attributes of that ticket. Most flags may be requested by a client +when the ticket is obtained; some are automatically turned on and off by a +Kerberos server as required. The following sections explain what the various +flags mean, and gives examples of reasons to use such a flag. + +2.1. Initial and pre-authenticated tickets + +The INITIAL flag indicates that a ticket was issued using the AS protocol +and not issued based on a ticket-granting ticket. Application servers that +want to require the demonstrated knowledge of a client's secret key (e.g. a +password-changing program) can insist that this flag be set in any tickets +they accept, and thus be assured that the client's key was recently +presented to the application client. + +The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the +initial authentication, regardless of whether the current ticket was issued +directly (in which case INITIAL will also be set) or issued on the basis of +a ticket-granting ticket (in which case the INITIAL flag is clear, but the +PRE-AUTHENT and HW-AUTHENT flags are carried forward from the +ticket-granting ticket). + +2.2. Invalid tickets + +The INVALID flag indicates that a ticket is invalid. Application servers +must reject tickets which have this flag set. A postdated ticket will +usually be issued in this form. Invalid tickets must be validated by the KDC +before use, by presenting them to the KDC in a TGS request with the VALIDATE +option specified. The KDC will only validate tickets after their starttime +has passed. The validation is required so that postdated tickets which have +been stolen before their starttime can be rendered permanently invalid +(through a hot-list mechanism) (see section 3.3.3.1). + +2.3. Renewable tickets + +Applications may desire to hold tickets which can be valid for long periods +of time. However, this can expose their credentials to potential theft for +equally long periods, and those stolen credentials would be valid until the +expiration time of the ticket(s). Simply using short-lived tickets and +obtaining new ones periodically would require the client to have long-term +access to its secret key, an even greater risk. Renewable tickets can be +used to mitigate the consequences of theft. Renewable tickets have two +"expiration times": the first is when the current instance of the ticket +expires, and the second is the latest permissible value for an individual +expiration time. An application client must periodically (i.e. before it +expires) present a renewable ticket to the KDC, with the RENEW option set in +the KDC request. The KDC will issue a new ticket with a new session key and +a later expiration time. All other fields of the ticket are left unmodified +by the renewal process. When the latest permissible expiration time arrives, +the ticket expires permanently. At each renewal, the KDC may consult a +hot-list to determine if the ticket had been reported stolen since its last +renewal; it will refuse to renew such stolen tickets, and thus the usable +lifetime of stolen tickets is reduced. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +The RENEWABLE flag in a ticket is normally only interpreted by the +ticket-granting service (discussed below in section 3.3). It can usually be +ignored by application servers. However, some particularly careful +application servers may wish to disallow renewable tickets. + +If a renewable ticket is not renewed by its expiration time, the KDC will +not renew the ticket. The RENEWABLE flag is reset by default, but a client +may request it be set by setting the RENEWABLE option in the KRB_AS_REQ +message. If it is set, then the renew-till field in the ticket contains the +time after which the ticket may not be renewed. + +2.4. Postdated tickets + +Applications may occasionally need to obtain tickets for use much later, +e.g. a batch submission system would need tickets to be valid at the time +the batch job is serviced. However, it is dangerous to hold valid tickets in +a batch queue, since they will be on-line longer and more prone to theft. +Postdated tickets provide a way to obtain these tickets from the KDC at job +submission time, but to leave them "dormant" until they are activated and +validated by a further request of the KDC. If a ticket theft were reported +in the interim, the KDC would refuse to validate the ticket, and the thief +would be foiled. + +The MAY-POSTDATE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. This flag +must be set in a ticket-granting ticket in order to issue a postdated ticket +based on the presented ticket. It is reset by default; it may be requested +by a client by setting the ALLOW-POSTDATE option in the KRB_AS_REQ message. +This flag does not allow a client to obtain a postdated ticket-granting +ticket; postdated ticket-granting tickets can only by obtained by requesting +the postdating in the KRB_AS_REQ message. The life (endtime-starttime) of a +postdated ticket will be the remaining life of the ticket-granting ticket at +the time of the request, unless the RENEWABLE option is also set, in which +case it can be the full life (endtime-starttime) of the ticket-granting +ticket. The KDC may limit how far in the future a ticket may be postdated. + +The POSTDATED flag indicates that a ticket has been postdated. The +application server can check the authtime field in the ticket to see when +the original authentication occurred. Some services may choose to reject +postdated tickets, or they may only accept them within a certain period +after the original authentication. When the KDC issues a POSTDATED ticket, +it will also be marked as INVALID, so that the application client must +present the ticket to the KDC to be validated before use. + +2.5. Proxiable and proxy tickets + +At times it may be necessary for a principal to allow a service to perform +an operation on its behalf. The service must be able to take on the identity +of the client, but only for a particular purpose. A principal can allow a +service to take on the principal's identity for a particular purpose by +granting it a proxy. + +The process of granting a proxy using the proxy and proxiable flags is used +to provide credentials for use with specific services. Though conceptually + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +also a proxy, user's wishing to delegate their identity for ANY purpose must +use the ticket forwarding mechanism described in the next section to forward +a ticket granting ticket. + +The PROXIABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. When set, +this flag tells the ticket-granting server that it is OK to issue a new +ticket (but not a ticket-granting ticket) with a different network address +based on this ticket. This flag is set if requested by the client on initial +authentication. By default, the client will request that it be set when +requesting a ticket granting ticket, and reset when requesting any other +ticket. + +This flag allows a client to pass a proxy to a server to perform a remote +request on its behalf, e.g. a print service client can give the print server +a proxy to access the client's files on a particular file server in order to +satisfy a print request. + +In order to complicate the use of stolen credentials, Kerberos tickets are +usually valid from only those network addresses specifically included in the +ticket[4]. When granting a proxy, the client must specify the new network +address from which the proxy is to be used, or indicate that the proxy is to +be issued for use from any address. + +The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. +Application servers may check this flag and at their option they may require +additional authentication from the agent presenting the proxy in order to +provide an audit trail. + +2.6. Forwardable tickets + +Authentication forwarding is an instance of a proxy where the service is +granted complete use of the client's identity. An example where it might be +used is when a user logs in to a remote system and wants authentication to +work from that system as if the login were local. + +The FORWARDABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. The +FORWARDABLE flag has an interpretation similar to that of the PROXIABLE +flag, except ticket-granting tickets may also be issued with different +network addresses. This flag is reset by default, but users may request that +it be set by setting the FORWARDABLE option in the AS request when they +request their initial ticket- granting ticket. + +This flag allows for authentication forwarding without requiring the user to +enter a password again. If the flag is not set, then authentication +forwarding is not permitted, but the same result can still be achieved if +the user engages in the AS exchange specifying the requested network +addresses and supplies a password. + +The FORWARDED flag is set by the TGS when a client presents a ticket with +the FORWARDABLE flag set and requests a forwarded ticket by specifying the +FORWARDED KDC option and supplying a set of addresses for the new ticket. It +is also set in all tickets issued based on tickets with the FORWARDED flag + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +set. Application servers may choose to process FORWARDED tickets differently +than non-FORWARDED tickets. + +2.7. Other KDC options + +There are two additional options which may be set in a client's request of +the KDC. The RENEWABLE-OK option indicates that the client will accept a +renewable ticket if a ticket with the requested life cannot otherwise be +provided. If a ticket with the requested life cannot be provided, then the +KDC may issue a renewable ticket with a renew-till equal to the the +requested endtime. The value of the renew-till field may still be adjusted +by site-determined limits or limits imposed by the individual principal or +server. + +The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. +It indicates that the ticket to be issued for the end server is to be +encrypted in the session key from the a additional second ticket-granting +ticket provided with the request. See section 3.3.3 for specific details. + +3. Message Exchanges + +The following sections describe the interactions between network clients and +servers and the messages involved in those exchanges. + +3.1. The Authentication Service Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_AS_REQ 5.4.1 + 2. Kerberos to client KRB_AS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The Authentication Service (AS) Exchange between the client and the Kerberos +Authentication Server is initiated by a client when it wishes to obtain +authentication credentials for a given server but currently holds no +credentials. In its basic form, the client's secret key is used for +encryption and decryption. This exchange is typically used at the initiation +of a login session to obtain credentials for a Ticket-Granting Server which +will subsequently be used to obtain credentials for other servers (see +section 3.3) without requiring further use of the client's secret key. This +exchange is also used to request credentials for services which must not be +mediated through the Ticket-Granting Service, but rather require a +principal's secret key, such as the password-changing service[5]. This +exchange does not by itself provide any assurance of the the identity of the +user[6]. + +The exchange consists of two messages: KRB_AS_REQ from the client to +Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these +messages are described in sections 5.4.1, 5.4.2, and 5.9.1. + +In the request, the client sends (in cleartext) its own identity and the +identity of the server for which it is requesting credentials. The response, +KRB_AS_REP, contains a ticket for the client to present to the server, and a +session key that will be shared by the client and the server. The session + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +key and additional information are encrypted in the client's secret key. The +KRB_AS_REP message contains information which can be used to detect replays, +and to associate it with the message to which it replies. Various errors can +occur; these are indicated by an error response (KRB_ERROR) instead of the +KRB_AS_REP response. The error message is not encrypted. The KRB_ERROR +message contains information which can be used to associate it with the +message to which it replies. The lack of encryption in the KRB_ERROR message +precludes the ability to detect replays, fabrications, or modifications of +such messages. + +Without preautentication, the authentication server does not know whether +the client is actually the principal named in the request. It simply sends a +reply without knowing or caring whether they are the same. This is +acceptable because nobody but the principal whose identity was given in the +request will be able to use the reply. Its critical information is encrypted +in that principal's key. The initial request supports an optional field that +can be used to pass additional information that might be needed for the +initial exchange. This field may be used for preauthentication as described +in section [hl<>]. + +3.1.1. Generation of KRB_AS_REQ message + +The client may specify a number of options in the initial request. Among +these options are whether pre-authentication is to be performed; whether the +requested ticket is to be renewable, proxiable, or forwardable; whether it +should be postdated or allow postdating of derivative tickets; and whether a +renewable ticket will be accepted in lieu of a non-renewable ticket if the +requested ticket expiration date cannot be satisfied by a non-renewable +ticket (due to configuration constraints; see section 4). See section A.1 +for pseudocode. + +The client prepares the KRB_AS_REQ message and sends it to the KDC. + +3.1.2. Receipt of KRB_AS_REQ message + +If all goes well, processing the KRB_AS_REQ message will result in the +creation of a ticket for the client to present to the server. The format for +the ticket is described in section 5.3.1. The contents of the ticket are +determined as follows. + +3.1.3. Generation of KRB_AS_REP message + +The authentication server looks up the client and server principals named in +the KRB_AS_REQ in its database, extracting their respective keys. If +required, the server pre-authenticates the request, and if the +pre-authentication check fails, an error message with the code +KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the +requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP +is returned. Otherwise it generates a 'random' session key[7]. + +If there are multiple encryption keys registered for a client in the +Kerberos database (or if the key registered supports multiple encryption +types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS +request is used by the KDC to select the encryption method to be used for + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +encrypting the response to the client. If there is more than one supported, +strong encryption type in the etype list, the first valid etype for which an +encryption key is available is used. The encryption method used to respond +to a TGS request is taken from the keytype of the session key found in the +ticket granting ticket. + +When the etype field is present in a KDC request, whether an AS or TGS +request, the KDC will attempt to assign the type of the random session key +from the list of methods in the etype field. The KDC will select the +appropriate type using the list of methods provided together with +information from the Kerberos database indicating acceptable encryption +methods for the application server. The KDC will not issue tickets with a +weak session key encryption type. + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise +the requested start time is checked against the policy of the local realm +(the administrator might decide to prohibit certain types or ranges of +postdated tickets), and if acceptable, the ticket's start time is set as +requested and the INVALID flag is set in the new ticket. The postdated +ticket must be validated before use by presenting it to the KDC after the +start time has been reached. + +The expiration time of the ticket will be set to the minimum of the +following: + + * The expiration time (endtime) requested in the KRB_AS_REQ message. + * The ticket's start time plus the maximum allowable lifetime associated + with the client principal (the authentication server's database + includes a maximum ticket lifetime field in each principal's record; + see section 4). + * The ticket's start time plus the maximum allowable lifetime associated + with the server principal. + * The ticket's start time plus the maximum lifetime set by the policy of + the local realm. + +If the requested expiration time minus the start time (as determined above) +is less than a site-determined minimum lifetime, an error message with code +KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the +ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' +option was requested, then the 'RENEWABLE' flag is set in the new ticket, +and the renew-till value is set as if the 'RENEWABLE' option were requested +(the field and option names are described fully in section 5.4.1). + +If the RENEWABLE option has been requested or if the RENEWABLE-OK option has +been set and a renewable ticket is to be issued, then the renew-till field +is set to the minimum of: + + * Its requested value. + * The start time of the ticket plus the minimum of the two maximum + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + renewable lifetimes associated with the principals' database entries. + * The start time of the ticket plus the maximum renewable lifetime set by + the policy of the local realm. + +The flags field of the new ticket will have the following options set if +they have been requested and if the policy of the local realm allows: +FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new +ticket is post-dated (the start time is in the future), its INVALID flag +will also be set. + +If all of the above succeed, the server formats a KRB_AS_REP message (see +section 5.4.2), copying the addresses in the request into the caddr of the +response, placing any required pre-authentication data into the padata of +the response, and encrypts the ciphertext part in the client's key using the +requested encryption method, and sends it to the client. See section A.2 for +pseudocode. + +3.1.4. Generation of KRB_ERROR message + +Several errors can occur, and the Authentication Server responds by +returning an error message, KRB_ERROR, to the client, with the error-code +and e-text fields set to appropriate values. The error message contents and +details are described in Section 5.9.1. + +3.1.5. Receipt of KRB_AS_REP message + +If the reply message type is KRB_AS_REP, then the client verifies that the +cname and crealm fields in the cleartext portion of the reply match what it +requested. If any padata fields are present, they may be used to derive the +proper secret key to decrypt the message. The client decrypts the encrypted +part of the response using its secret key, verifies that the nonce in the +encrypted part matches the nonce it supplied in its request (to detect +replays). It also verifies that the sname and srealm in the response match +those in the request (or are otherwise expected values), and that the host +address field is also correct. It then stores the ticket, session key, start +and expiration times, and other information for later use. The +key-expiration field from the encrypted part of the response may be checked +to notify the user of impending key expiration (the client program could +then suggest remedial action, such as a password change). See section A.3 +for pseudocode. + +Proper decryption of the KRB_AS_REP message is not sufficient to verify the +identity of the user; the user and an attacker could cooperate to generate a +KRB_AS_REP format message which decrypts properly but is not from the proper +KDC. If the host wishes to verify the identity of the user, it must require +the user to present application credentials which can be verified using a +securely-stored secret key for the host. If those credentials can be +verified, then the identity of the user can be assured. + +3.1.6. Receipt of KRB_ERROR message + +If the reply message type is KRB_ERROR, then the client interprets it as an +error and performs whatever application-specific tasks are necessary to +recover. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +3.2. The Client/Server Authentication Exchange + + Summary +Message direction Message type Section +Client to Application server KRB_AP_REQ 5.5.1 +[optional] Application server to client KRB_AP_REP or 5.5.2 + KRB_ERROR 5.9.1 + +The client/server authentication (CS) exchange is used by network +applications to authenticate the client to the server and vice versa. The +client must have already acquired credentials for the server using the AS or +TGS exchange. + +3.2.1. The KRB_AP_REQ message + +The KRB_AP_REQ contains authentication information which should be part of +the first message in an authenticated transaction. It contains a ticket, an +authenticator, and some additional bookkeeping information (see section +5.5.1 for the exact format). The ticket by itself is insufficient to +authenticate a client, since tickets are passed across the network in +cleartext[DS90], so the authenticator is used to prevent invalid replay of +tickets by proving to the server that the client knows the session key of +the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message is +referred to elsewhere as the 'authentication header.' + +3.2.2. Generation of a KRB_AP_REQ message + +When a client wishes to initiate authentication to a server, it obtains +(either through a credentials cache, the AS exchange, or the TGS exchange) a +ticket and session key for the desired service. The client may re-use any +tickets it holds until they expire. To use a ticket the client constructs a +new Authenticator from the the system time, its name, and optionally an +application specific checksum, an initial sequence number to be used in +KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in +negotiations for a session key unique to this particular session. +Authenticators may not be re-used and will be rejected if replayed to a +server[LGDSR87]. If a sequence number is to be included, it should be +randomly chosen so that even after many messages have been exchanged it is +not likely to collide with other sequence numbers in use. + +The client may indicate a requirement of mutual authentication or the use of +a session-key based ticket by setting the appropriate flag(s) in the +ap-options field of the message. + +The Authenticator is encrypted in the session key and combined with the +ticket to form the KRB_AP_REQ message which is then sent to the end server +along with any additional application-specific information. See section A.9 +for pseudocode. + +3.2.3. Receipt of KRB_AP_REQ message + +Authentication is based on the server's current time of day (clocks must be +loosely synchronized), the authenticator, and the ticket. Several errors are + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +possible. If an error occurs, the server is expected to reply to the client +with a KRB_ERROR message. This message may be encapsulated in the +application protocol if its 'raw' form is not acceptable to the protocol. +The format of error messages is described in section 5.9.1. + +The algorithm for verifying authentication information is as follows. If the +message type is not KRB_AP_REQ, the server returns the KRB_AP_ERR_MSG_TYPE +error. If the key version indicated by the Ticket in the KRB_AP_REQ is not +one the server can use (e.g., it indicates an old key, and the server no +longer possesses a copy of the old key), the KRB_AP_ERR_BADKEYVER error is +returned. If the USE-SESSION-KEY flag is set in the ap-options field, it +indicates to the server that the ticket is encrypted in the session key from +the server's ticket-granting ticket rather than its secret key[10]. Since it +is possible for the server to be registered in multiple realms, with +different keys in each, the srealm field in the unencrypted portion of the +ticket in the KRB_AP_REQ is used to specify which secret key the server +should use to decrypt that ticket. The KRB_AP_ERR_NOKEY error code is +returned if the server doesn't have the proper key to decipher the ticket. + +The ticket is decrypted using the version of the server's key specified by +the ticket. If the decryption routines detect a modification of the ticket +(each encryption system must provide safeguards to detect modified +ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned +(chances are good that different keys were used to encrypt and decrypt). + +The authenticator is decrypted using the session key extracted from the +decrypted ticket. If decryption shows it to have been modified, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the client +from the ticket are compared against the same fields in the authenticator. +If they don't match, the KRB_AP_ERR_BADMATCH error is returned (they might +not match, for example, if the wrong session key was used to encrypt the +authenticator). The addresses in the ticket (if any) are then searched for +an address matching the operating-system reported address of the client. If +no match is found or the server insists on ticket addresses but none are +present in the ticket, the KRB_AP_ERR_BADADDR error is returned. + +If the local (server) time and the client time in the authenticator differ +by more than the allowable clock skew (e.g., 5 minutes), the KRB_AP_ERR_SKEW +error is returned. If the server name, along with the client name, time and +microsecond fields from the Authenticator match any recently-seen such +tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The server must +remember any authenticator presented within the allowable clock skew, so +that a replay attempt is guaranteed to fail. If a server loses track of any +authenticator presented within the allowable clock skew, it must reject all +requests until the clock skew interval has passed. This assures that any +lost or re-played authenticators will fall outside the allowable clock skew +and can no longer be successfully replayed (If this is not done, an attacker +could conceivably record the ticket and authenticator sent over the network +to a server, then disable the client's host, pose as the disabled host, and +replay the ticket and authenticator to subvert the authentication.). If a +sequence number is provided in the authenticator, the server saves it for +later use in processing KRB_SAFE and/or KRB_PRIV messages. If a subkey is +present, the server either saves it for later use or uses it to help +generate its own choice for a subkey to be returned in a KRB_AP_REP message. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +The server computes the age of the ticket: local (server) time minus the +start time inside the Ticket. If the start time is later than the current +time by more than the allowable clock skew or if the INVALID flag is set in +the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the +current time is later than end time by more than the allowable clock skew, +the KRB_AP_ERR_TKT_EXPIRED error is returned. + +If all these checks succeed without an error, the server is assured that the +client possesses the credentials of the principal named in the ticket and +thus, the client has been authenticated to the server. See section A.10 for +pseudocode. + +Passing these checks provides only authentication of the named principal; it +does not imply authorization to use the named service. Applications must +make a separate authorization decisions based upon the authenticated name of +the user, the requested operation, local acces control information such as +that contained in a .k5login or .k5users file, and possibly a separate +distributed authorization service. + +3.2.4. Generation of a KRB_AP_REP message + +Typically, a client's request will include both the authentication +information and its initial request in the same message, and the server need +not explicitly reply to the KRB_AP_REQ. However, if mutual authentication +(not only authenticating the client to the server, but also the server to +the client) is being performed, the KRB_AP_REQ message will have +MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message is +required in response. As with the error message, this message may be +encapsulated in the application protocol if its "raw" form is not acceptable +to the application's protocol. The timestamp and microsecond field used in +the reply must be the client's timestamp and microsecond field (as provided +in the authenticator)[12]. If a sequence number is to be included, it should +be randomly chosen as described above for the authenticator. A subkey may be +included if the server desires to negotiate a different subkey. The +KRB_AP_REP message is encrypted in the session key extracted from the +ticket. See section A.11 for pseudocode. + +3.2.5. Receipt of KRB_AP_REP message + +If a KRB_AP_REP message is returned, the client uses the session key from +the credentials obtained for the server[13] to decrypt the message, and +verifies that the timestamp and microsecond fields match those in the +Authenticator it sent to the server. If they match, then the client is +assured that the server is genuine. The sequence number and subkey (if +present) are retained for later use. See section A.12 for pseudocode. + +3.2.6. Using the encryption key + +After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and server +share an encryption key which can be used by the application. The 'true +session key' to be used for KRB_PRIV, KRB_SAFE, or other +application-specific uses may be chosen by the application based on the +subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +the use of this session key will be implicit in the protocol; in others the +method of use must be chosen from several alternatives. We leave the +protocol negotiations of how to use the key (e.g. selecting an encryption or +checksum type) to the application programmer; the Kerberos protocol does not +constrain the implementation options, but an example of how this might be +done follows. + +One way that an application may choose to negotiate a key to be used for +subequent integrity and privacy protection is for the client to propose a +key in the subkey field of the authenticator. The server can then choose a +key using the proposed key from the client as input, returning the new +subkey in the subkey field of the application reply. This key could then be +used for subsequent communication. To make this example more concrete, if +the encryption method in use required a 56 bit key, and for whatever reason, +one of the parties was prevented from using a key with more than 40 unknown +bits, this method would allow the the party which is prevented from using +more than 40 bits to either propose (if the client) an initial key with a +known quantity for 16 of those bits, or to mask 16 of the bits (if the +server) with the known quantity. The application implementor is warned, +however, that this is only an example, and that an analysis of the +particular crytosystem to be used, and the reasons for limiting the key +length, must be made before deciding whether it is acceptable to mask bits +of the key. + +With both the one-way and mutual authentication exchanges, the peers should +take care not to send sensitive information to each other without proper +assurances. In particular, applications that require privacy or integrity +should use the KRB_AP_REP response from the server to client to assure both +client and server of their peer's identity. If an application protocol +requires privacy of its messages, it can use the KRB_PRIV message (section +3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. + +3.3. The Ticket-Granting Service (TGS) Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_TGS_REQ 5.4.1 + 2. Kerberos to client KRB_TGS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The TGS exchange between a client and the Kerberos Ticket-Granting Server is +initiated by a client when it wishes to obtain authentication credentials +for a given server (which might be registered in a remote realm), when it +wishes to renew or validate an existing ticket, or when it wishes to obtain +a proxy ticket. In the first case, the client must already have acquired a +ticket for the Ticket-Granting Service using the AS exchange (the +ticket-granting ticket is usually obtained when a client initially +authenticates to the system, such as when a user logs in). The message +format for the TGS exchange is almost identical to that for the AS exchange. +The primary difference is that encryption and decryption in the TGS exchange +does not take place under the client's key. Instead, the session key from +the ticket-granting ticket or renewable ticket, or sub-session key from an +Authenticator is used. As is the case for all application servers, expired +tickets are not accepted by the TGS, so once a renewable or ticket-granting + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +ticket expires, the client must use a separate exchange to obtain valid +tickets. + +The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the +client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or +KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the +client plus a request for credentials. The authentication information +consists of the authentication header (KRB_AP_REQ) which includes the +client's previously obtained ticket-granting, renewable, or invalid ticket. +In the ticket-granting ticket and proxy cases, the request may include one +or more of: a list of network addresses, a collection of typed authorization +data to be sealed in the ticket for authorization use by the application +server, or additional tickets (the use of which are described later). The +TGS reply (KRB_TGS_REP) contains the requested credentials, encrypted in the +session key from the ticket-granting ticket or renewable ticket, or if +present, in the sub-session key from the Authenticator (part of the +authentication header). The KRB_ERROR message contains an error code and +text explaining what went wrong. The KRB_ERROR message is not encrypted. The +KRB_TGS_REP message contains information which can be used to detect +replays, and to associate it with the message to which it replies. The +KRB_ERROR message also contains information which can be used to associate +it with the message to which it replies, but the lack of encryption in the +KRB_ERROR message precludes the ability to detect replays or fabrications of +such messages. + +3.3.1. Generation of KRB_TGS_REQ message + +Before sending a request to the ticket-granting service, the client must +determine in which realm the application server is registered[15]. If the +client does not already possess a ticket-granting ticket for the appropriate +realm, then one must be obtained. This is first attempted by requesting a +ticket-granting ticket for the destination realm from a Kerberos server for +which the client does posess a ticket-granting ticket (using the KRB_TGS_REQ +message recursively). The Kerberos server may return a TGT for the desired +realm in which case one can proceed. Alternatively, the Kerberos server may +return a TGT for a realm which is 'closer' to the desired realm (further +along the standard hierarchical path), in which case this step must be +repeated with a Kerberos server in the realm specified in the returned TGT. +If neither are returned, then the request must be retried with a Kerberos +server for a realm higher in the hierarchy. This request will itself require +a ticket-granting ticket for the higher realm which must be obtained by +recursively applying these directions. + +Once the client obtains a ticket-granting ticket for the appropriate realm, +it determines which Kerberos servers serve that realm, and contacts one. The +list might be obtained through a configuration file or network service or it +may be generated from the name of the realm; as long as the secret keys +exchanged by realms are kept secret, only denial of service results from +using a false Kerberos server. + +As in the AS exchange, the client may specify a number of options in the +KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing +an authentication header as an element of the padata field, and including +the same fields as used in the KRB_AS_REQ message along with several + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +optional fields: the enc-authorization-data field for application server use +and additional tickets required by some options. + +In preparing the authentication header, the client can select a sub-session +key under which the response from the Kerberos server will be encrypted[16]. +If the sub-session key is not specified, the session key from the +ticket-granting ticket will be used. If the enc-authorization-data is +present, it must be encrypted in the sub-session key, if present, from the +authenticator portion of the authentication header, or if not present, using +the session key from the ticket-granting ticket. + +Once prepared, the message is sent to a Kerberos server for the destination +realm. See section A.5 for pseudocode. + +3.3.2. Receipt of KRB_TGS_REQ message + +The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ +message, but there are many additional checks to be performed. First, the +Kerberos server must determine which server the accompanying ticket is for +and it must select the appropriate key to decrypt it. For a normal +KRB_TGS_REQ message, it will be for the ticket granting service, and the +TGS's key will be used. If the TGT was issued by another realm, then the +appropriate inter-realm key must be used. If the accompanying ticket is not +a ticket granting ticket for the current realm, but is for an application +server in the current realm, the RENEW, VALIDATE, or PROXY options are +specified in the request, and the server for which a ticket is requested is +the server named in the accompanying ticket, then the KDC will decrypt the +ticket in the authentication header using the key of the server for which it +was issued. If no ticket can be found in the padata field, the +KDC_ERR_PADATA_TYPE_NOSUPP error is returned. + +Once the accompanying ticket has been decrypted, the user-supplied checksum +in the Authenticator must be verified against the contents of the request, +and the message rejected if the checksums do not match (with an error code +of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not +collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the +checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is +returned. If the authorization-data are present, they are decrypted using +the sub-session key from the Authenticator. + +If any of the decryptions indicate failed integrity checks, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. + +3.3.3. Generation of KRB_TGS_REP message + +The KRB_TGS_REP message shares its format with the KRB_AS_REP (KRB_KDC_REP), +but with its type field set to KRB_TGS_REP. The detailed specification is in +section 5.4.2. + +The response will include a ticket for the requested server. The Kerberos +database is queried to retrieve the record for the requested server +(including the key with which the ticket will be encrypted). If the request +is for a ticket granting ticket for a remote realm, and if no key is shared +with the requested realm, then the Kerberos server will select the realm + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +"closest" to the requested realm with which it does share a key, and use +that realm instead. This is the only case where the response from the KDC +will be for a different server than that requested by the client. + +By default, the address field, the client's name and realm, the list of +transited realms, the time of initial authentication, the expiration time, +and the authorization data of the newly-issued ticket will be copied from +the ticket-granting ticket (TGT) or renewable ticket. If the transited field +needs to be updated, but the transited type is not supported, the +KDC_ERR_TRTYPE_NOSUPP error is returned. + +If the request specifies an endtime, then the endtime of the new ticket is +set to the minimum of (a) that request, (b) the endtime from the TGT, and +(c) the starttime of the TGT plus the minimum of the maximum life for the +application server and the maximum life for the local realm (the maximum +life for the requesting principal was already applied when the TGT was +issued). If the new ticket is to be a renewal, then the endtime above is +replaced by the minimum of (a) the value of the renew_till field of the +ticket and (b) the starttime for the new ticket plus the life +(endtime-starttime) of the old ticket. + +If the FORWARDED option has been requested, then the resulting ticket will +contain the addresses specified by the client. This option will only be +honored if the FORWARDABLE flag is set in the TGT. The PROXY option is +similar; the resulting ticket will contain the addresses specified by the +client. It will be honored only if the PROXIABLE flag in the TGT is set. The +PROXY option will not be honored on requests for additional ticket-granting +tickets. + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified or the MAY-POSTDATE flag is not set in the TGT, then the +error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the ticket-granting +ticket has the MAY-POSTDATE flag set, then the resulting ticket will be +postdated and the requested starttime is checked against the policy of the +local realm. If acceptable, the ticket's start time is set as requested, and +the INVALID flag is set. The postdated ticket must be validated before use +by presenting it to the KDC after the starttime has been reached. However, +in no case may the starttime, endtime, or renew-till time of a newly-issued +postdated ticket extend beyond the renew-till time of the ticket-granting +ticket. + +If the ENC-TKT-IN-SKEY option has been specified and an additional ticket +has been included in the request, the KDC will decrypt the additional ticket +using the key for the server to which the additional ticket was issued and +verify that it is a ticket-granting ticket. If the name of the requested +server is missing from the request, the name of the client in the additional +ticket will be used. Otherwise the name of the requested server will be +compared to the name of the client in the additional ticket and if +different, the request will be rejected. If the request succeeds, the +session key from the additional ticket will be used to encrypt the new + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +ticket that is issued instead of using the key of the server for which the +new ticket will be used[17]. + +If the name of the server in the ticket that is presented to the KDC as part +of the authentication header is not that of the ticket-granting server +itself, the server is registered in the realm of the KDC, and the RENEW +option is requested, then the KDC will verify that the RENEWABLE flag is set +in the ticket, that the INVALID flag is not set in the ticket, and that the +renew_till time is still in the future. If the VALIDATE option is rqeuested, +the KDC will check that the starttime has passed and the INVALID flag is +set. If the PROXY option is requested, then the KDC will check that the +PROXIABLE flag is set in the ticket. If the tests succeed, and the ticket +passes the hotlist check described in the next paragraph, the KDC will issue +the appropriate new ticket. + +3.3.3.1. Checking for revoked tickets + +Whenever a request is made to the ticket-granting server, the presented +ticket(s) is(are) checked against a hot-list of tickets which have been +canceled. This hot-list might be implemented by storing a range of issue +timestamps for 'suspect tickets'; if a presented ticket had an authtime in +that range, it would be rejected. In this way, a stolen ticket-granting +ticket or renewable ticket cannot be used to gain additional tickets +(renewals or otherwise) once the theft has been reported. Any normal ticket +obtained before it was reported stolen will still be valid (because they +require no interaction with the KDC), but only until their normal expiration +time. + +The ciphertext part of the response in the KRB_TGS_REP message is encrypted +in the sub-session key from the Authenticator, if present, or the session +key key from the ticket-granting ticket. It is not encrypted using the +client's secret key. Furthermore, the client's key's expiration date and the +key version number fields are left out since these values are stored along +with the client's database record, and that record is not needed to satisfy +a request based on a ticket-granting ticket. See section A.6 for pseudocode. + +3.3.3.2. Encoding the transited field + +If the identity of the server in the TGT that is presented to the KDC as +part of the authentication header is that of the ticket-granting service, +but the TGT was issued from another realm, the KDC will look up the +inter-realm key shared with that realm and use that key to decrypt the +ticket. If the ticket is valid, then the KDC will honor the request, subject +to the constraints outlined above in the section describing the AS exchange. +The realm part of the client's identity will be taken from the +ticket-granting ticket. The name of the realm that issued the +ticket-granting ticket will be added to the transited field of the ticket to +be issued. This is accomplished by reading the transited field from the +ticket-granting ticket (which is treated as an unordered set of realm +names), adding the new realm to the set, then constructing and writing out +its encoded (shorthand) form (this may involve a rearrangement of the +existing encoding). + +Note that the ticket-granting service does not add the name of its own + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +realm. Instead, its responsibility is to add the name of the previous realm. +This prevents a malicious Kerberos server from intentionally leaving out its +own name (it could, however, omit other realms' names). + +The names of neither the local realm nor the principal's realm are to be +included in the transited field. They appear elsewhere in the ticket and +both are known to have taken part in authenticating the principal. Since the +endpoints are not included, both local and single-hop inter-realm +authentication result in a transited field that is empty. + +Because the name of each realm transited is added to this field, it might +potentially be very long. To decrease the length of this field, its contents +are encoded. The initially supported encoding is optimized for the normal +case of inter-realm communication: a hierarchical arrangement of realms +using either domain or X.500 style realm names. This encoding (called +DOMAIN-X500-COMPRESS) is now described. + +Realm names in the transited field are separated by a ",". The ",", "\", +trailing "."s, and leading spaces (" ") are special characters, and if they +are part of a realm name, they must be quoted in the transited field by +preced- ing them with a "\". + +A realm name ending with a "." is interpreted as being prepended to the +previous realm. For example, we can encode traversal of EDU, MIT.EDU, +ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: + + "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". + +Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that they +would not be included in this field, and we would have: + + "EDU,MIT.,WASHINGTON.EDU" + +A realm name beginning with a "/" is interpreted as being appended to the +previous realm[18]. If it is to stand by itself, then it should be preceded +by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, +/COM/HP, /COM, and /COM/DEC as: + + "/COM,/HP,/APOLLO, /COM/DEC". + +Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they +they would not be included in this field, and we would have: + + "/COM,/HP" + +A null subfield preceding or following a "," indicates that all realms +between the previous realm and the next realm have been traversed[19]. Thus, +"," means that all realms along the path between the client and the server +have been traversed. ",EDU, /COM," means that that all realms from the +client's realm up to EDU (in a domain style hierarchy) have been traversed, +and that everything from /COM down to the server's realm in an X.500 style +has also been traversed. This could occur if the EDU realm in one hierarchy +shares an inter-realm key directly with the /COM realm in another hierarchy. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +3.3.4. Receipt of KRB_TGS_REP message + +When the KRB_TGS_REP is received by the client, it is processed in the same +manner as the KRB_AS_REP processing described above. The primary difference +is that the ciphertext part of the response must be decrypted using the +session key from the ticket-granting ticket rather than the client's secret +key. See section A.7 for pseudocode. + +3.4. The KRB_SAFE Exchange + +The KRB_SAFE message may be used by clients requiring the ability to detect +modifications of messages they exchange. It achieves this by including a +keyed collision-proof checksum of the user data and some control +information. The checksum is keyed with an encryption key (usually the last +key negotiated via subkeys, or the session key if no negotiation has +occured). + +3.4.1. Generation of a KRB_SAFE message + +When an application wishes to send a KRB_SAFE message, it collects its data +and the appropriate control information and computes a checksum over them. +The checksum algorithm should be a keyed one-way hash function (such as the +RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES MAC), +generated using the sub-session key if present, or the session key. +Different algorithms may be selected by changing the checksum type in the +message. Unkeyed or non-collision-proof checksums are not suitable for this +use. + +The control information for the KRB_SAFE message includes both a timestamp +and a sequence number. The designer of an application using the KRB_SAFE +message must choose at least one of the two mechanisms. This choice should +be based on the needs of the application protocol. + +Sequence numbers are useful when all messages sent will be received by one's +peer. Connection state is presently required to maintain the session key, so +maintaining the next sequence number should not present an additional +problem. + +If the application protocol is expected to tolerate lost messages without +them being resent, the use of the timestamp is the appropriate replay +detection mechanism. Using timestamps is also the appropriate mechanism for +multi-cast protocols where all of one's peers share a common sub-session +key, but some messages will be sent to a subset of one's peers. + +After computing the checksum, the client then transmits the information and +checksum to the recipient in the message format specified in section 5.6.1. + +3.4.2. Receipt of KRB_SAFE message + +When an application receives a KRB_SAFE message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + +The message is first checked by verifying that the protocol version and type +fields match the current version and KRB_SAFE, respectively. A mismatch + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application verifies that the checksum used is a collision-proof keyed +checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. The +recipient verifies that the operating system's report of the sender's +address matches the sender's address in the message, and (if a recipient +address is specified or the recipient requires an address) that one of the +recipient's addresses appears as the recipient's address in the message. A +failed match for either case generates a KRB_AP_ERR_BADADDR error. Then the +timestamp and usec and/or the sequence number fields are checked. If +timestamp and usec are expected and not present, or they are present but not +current, the KRB_AP_ERR_SKEW error is generated. If the server name, along +with the client name, time and microsecond fields from the Authenticator +match any recently-seen (sent or received[20] ) such tuples, the +KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence number is +included, or a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or +a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. +Finally, the checksum is computed over the data and control information, and +if it doesn't match the received checksum, a KRB_AP_ERR_MODIFIED error is +generated. + +If all the checks succeed, the application is assured that the message was +generated by its peer and was not modi- fied in transit. + +3.5. The KRB_PRIV Exchange + +The KRB_PRIV message may be used by clients requiring confidentiality and +the ability to detect modifications of exchanged messages. It achieves this +by encrypting the messages and adding control information. + +3.5.1. Generation of a KRB_PRIV message + +When an application wishes to send a KRB_PRIV message, it collects its data +and the appropriate control information (specified in section 5.7.1) and +encrypts them under an encryption key (usually the last key negotiated via +subkeys, or the session key if no negotiation has occured). As part of the +control information, the client must choose to use either a timestamp or a +sequence number (or both); see the discussion in section 3.4.1 for +guidelines on which to use. After the user data and control information are +encrypted, the client transmits the ciphertext and some 'envelope' +information to the recipient. + +3.5.2. Receipt of KRB_PRIV message + +When an application receives a KRB_PRIV message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + +The message is first checked by verifying that the protocol version and type +fields match the current version and KRB_PRIV, respectively. A mismatch +generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application then decrypts the ciphertext and processes the resultant +plaintext. If decryption shows the data to have been modified, a +KRB_AP_ERR_BAD_INTEGRITY error is generated. The recipient verifies that the +operating system's report of the sender's address matches the sender's + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +address in the message, and (if a recipient address is specified or the +recipient requires an address) that one of the recipient's addresses appears +as the recipient's address in the message. A failed match for either case +generates a KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the +sequence number fields are checked. If timestamp and usec are expected and +not present, or they are present but not current, the KRB_AP_ERR_SKEW error +is generated. If the server name, along with the client name, time and +microsecond fields from the Authenticator match any recently-seen such +tuples, the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence +number is included, or a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or +a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. + +If all the checks succeed, the application can assume the message was +generated by its peer, and was securely transmitted (without intruders able +to see the unencrypted contents). + +3.6. The KRB_CRED Exchange + +The KRB_CRED message may be used by clients requiring the ability to send +Kerberos credentials from one host to another. It achieves this by sending +the tickets together with encrypted data containing the session keys and +other information associated with the tickets. + +3.6.1. Generation of a KRB_CRED message + +When an application wishes to send a KRB_CRED message it first (using the +KRB_TGS exchange) obtains credentials to be sent to the remote host. It then +constructs a KRB_CRED message using the ticket or tickets so obtained, +placing the session key needed to use each ticket in the key field of the +corresponding KrbCredInfo sequence of the encrypted part of the the KRB_CRED +message. + +Other information associated with each ticket and obtained during the +KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence in +the encrypted part of the KRB_CRED message. The current time and, if +specifically required by the application the nonce, s-address, and r-address +fields, are placed in the encrypted part of the KRB_CRED message which is +then encrypted under an encryption key previosuly exchanged in the KRB_AP +exchange (usually the last key negotiated via subkeys, or the session key if +no negotiation has occured). + +3.6.2. Receipt of KRB_CRED message + +When an application receives a KRB_CRED message, it verifies it. If any +error occurs, an error code is reported for use by the application. The +message is verified by checking that the protocol version and type fields +match the current version and KRB_CRED, respectively. A mismatch generates a +KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then +decrypts the ciphertext and processes the resultant plaintext. If decryption +shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is +generated. + +If present or required, the recipient verifies that the operating system's + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +report of the sender's address matches the sender's address in the message, +and that one of the recipient's addresses appears as the recipient's address +in the message. A failed match for either case generates a +KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce field +if required) are checked next. If the timestamp and usec are not present, or +they are present but not current, the KRB_AP_ERR_SKEW error is generated. + +If all the checks succeed, the application stores each of the new tickets in +its ticket cache together with the session key and other information in the +corresponding KrbCredInfo sequence from the encrypted part of the KRB_CRED +message. + +4. The Kerberos Database + +The Kerberos server must have access to a database contain- ing the +principal identifiers and secret keys of principals to be authenticated[21]. + +4.1. Database contents + +A database entry should contain at least the following fields: + +Field Value + +name Principal's identifier +key Principal's secret key +p_kvno Principal's key version +max_life Maximum lifetime for Tickets +max_renewable_life Maximum total lifetime for renewable Tickets + +The name field is an encoding of the principal's identifier. The key field +contains an encryption key. This key is the principal's secret key. (The key +can be encrypted before storage under a Kerberos "master key" to protect it +in case the database is compromised but the master key is not. In that case, +an extra field must be added to indicate the master key version used, see +below.) The p_kvno field is the key version number of the principal's secret +key. The max_life field contains the maximum allowable lifetime (endtime - +starttime) for any Ticket issued for this principal. The max_renewable_life +field contains the maximum allowable total lifetime for any renewable Ticket +issued for this principal. (See section 3.1 for a description of how these +lifetimes are used in determining the lifetime of a given Ticket.) + +A server may provide KDC service to several realms, as long as the database +representation provides a mechanism to distinguish between principal records +with identifiers which differ only in the realm name. + +When an application server's key changes, if the change is routine (i.e. not +the result of disclosure of the old key), the old key should be retained by +the server until all tickets that had been issued using that key have +expired. Because of this, it is possible for several keys to be active for a +single principal. Ciphertext encrypted in a principal's key is always tagged +with the version of the key that was used for encryption, to help the +recipient find the proper key for decryption. + +When more than one key is active for a particular principal, the principal + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +will have more than one record in the Kerberos database. The keys and key +version numbers will differ between the records (the rest of the fields may +or may not be the same). Whenever Kerberos issues a ticket, or responds to a +request for initial authentication, the most recent key (known by the +Kerberos server) will be used for encryption. This is the key with the +highest key version number. + +4.2. Additional fields + +Project Athena's KDC implementation uses additional fields in its database: + +Field Value + +K_kvno Kerberos' key version +expiration Expiration date for entry +attributes Bit field of attributes +mod_date Timestamp of last modification +mod_name Modifying principal's identifier + +The K_kvno field indicates the key version of the Kerberos master key under +which the principal's secret key is encrypted. + +After an entry's expiration date has passed, the KDC will return an error to +any client attempting to gain tickets as or for the principal. (A database +may want to maintain two expiration dates: one for the principal, and one +for the principal's current key. This allows password aging to work +independently of the principal's expiration date. However, due to the +limited space in the responses, the KDC must combine the key expiration and +principal expiration date into a single value called 'key_exp', which is +used as a hint to the user to take administrative action.) + +The attributes field is a bitfield used to govern the operations involving +the principal. This field might be useful in conjunction with user +registration procedures, for site-specific policy implementations (Project +Athena currently uses it for their user registration process controlled by +the system-wide database service, Moira [LGDSR87]), to identify whether a +principal can play the role of a client or server or both, to note whether a +server is appropriate trusted to recieve credentials delegated by a client, +or to identify the 'string to key' conversion algorithm used for a +principal's key[22]. Other bits are used to indicate that certain ticket +options should not be allowed in tickets encrypted under a principal's key +(one bit each): Disallow issuing postdated tickets, disallow issuing +forwardable tickets, disallow issuing tickets based on TGT authentication, +disallow issuing renewable tickets, disallow issuing proxiable tickets, and +disallow issuing tickets for which the principal is the server. + +The mod_date field contains the time of last modification of the entry, and +the mod_name field contains the name of the principal which last modified +the entry. + +4.3. Frequently Changing Fields + +Some KDC implementations may wish to maintain the last time that a request +was made by a particular principal. Information that might be maintained + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +includes the time of the last request, the time of the last request for a +ticket-granting ticket, the time of the last use of a ticket-granting +ticket, or other times. This information can then be returned to the user in +the last-req field (see section 5.2). + +Other frequently changing information that can be maintained is the latest +expiration time for any tickets that have been issued using each key. This +field would be used to indicate how long old keys must remain valid to allow +the continued use of outstanding tickets. + +4.4. Site Constants + +The KDC implementation should have the following configurable constants or +options, to allow an administrator to make and enforce policy decisions: + + * The minimum supported lifetime (used to determine whether the + KDC_ERR_NEVER_VALID error should be returned). This constant should + reflect reasonable expectations of round-trip time to the KDC, + encryption/decryption time, and processing time by the client and + target server, and it should allow for a minimum 'useful' lifetime. + * The maximum allowable total (renewable) lifetime of a ticket + (renew_till - starttime). + * The maximum allowable lifetime of a ticket (endtime - starttime). + * Whether to allow the issue of tickets with empty address fields + (including the ability to specify that such tickets may only be issued + if the request specifies some authorization_data). + * Whether proxiable, forwardable, renewable or post-datable tickets are + to be issued. + +5. Message Specifications + +The following sections describe the exact contents and encoding of protocol +messages and objects. The ASN.1 base definitions are presented in the first +subsection. The remaining subsections specify the protocol objects (tickets +and authenticators) and messages. Specification of encryption and checksum +techniques, and the fields related to them, appear in section 6. + +5.1. ASN.1 Distinguished Encoding Representation + +All uses of ASN.1 in Kerberos shall use the Distinguished Encoding +Representation of the data elements as described in the X.509 specification, +section 8.7 [X509-88]. + +5.2. ASN.1 Base Definitions + +The following ASN.1 base definitions are used in the rest of this section. +Note that since the underscore character (_) is not permitted in ASN.1 +names, the hyphen (-) is used in its place for the purposes of ASN.1 names. + +Realm ::= GeneralString +PrincipalName ::= SEQUENCE { + name-type[0] INTEGER, + name-string[1] SEQUENCE OF GeneralString +} + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +Kerberos realms are encoded as GeneralStrings. Realms shall not contain a +character with the code 0 (the ASCII NUL). Most realms will usually consist +of several components separated by periods (.), in the style of Internet +Domain Names, or separated by slashes (/) in the style of X.500 names. +Acceptable forms for realm names are specified in section 7. A PrincipalName +is a typed sequence of components consisting of the following sub-fields: + +name-type + This field specifies the type of name that follows. Pre-defined values + for this field are specified in section 7.2. The name-type should be + treated as a hint. Ignoring the name type, no two names can be the same + (i.e. at least one of the components, or the realm, must be different). + This constraint may be eliminated in the future. +name-string + This field encodes a sequence of components that form a name, each + component encoded as a GeneralString. Taken together, a PrincipalName + and a Realm form a principal identifier. Most PrincipalNames will have + only a few components (typically one or two). + +KerberosTime ::= GeneralizedTime + -- Specifying UTC time zone (Z) + +The timestamps used in Kerberos are encoded as GeneralizedTimes. An encoding +shall specify the UTC time zone (Z) and shall not include any fractional +portions of the seconds. It further shall not include any separators. +Example: The only valid format for UTC time 6 minutes, 27 seconds after 9 pm +on 6 November 1985 is 19851106210627Z. + +HostAddress ::= SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING +} + +HostAddresses ::= SEQUENCE OF HostAddress + +The host adddress encodings consists of two fields: + +addr-type + This field specifies the type of address that follows. Pre-defined + values for this field are specified in section 8.1. +address + This field encodes a single address of type addr-type. + +The two forms differ slightly. HostAddress contains exactly one address; +HostAddresses contains a sequence of possibly many addresses. + +AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type[0] INTEGER, + ad-data[1] OCTET STRING +} + +ad-data + This field contains authorization data to be interpreted according to + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + the value of the corresponding ad-type field. +ad-type + This field specifies the format for the ad-data subfield. All negative + values are reserved for local use. Non-negative values are reserved for + registered use. + +Each sequence of type and data is refered to as an authorization element. +Elements may be application specific, however, there is a common set of +recursive elements that should be understood by all implementations. These +elements contain other elements embedded within them, and the interpretation +of the encapsulating element determines which of the embedded elements must +be interpreted, and which may be ignored. Definitions for these common +elements may be found in Appendix B. + +TicketExtensions ::= SEQUENCE OF SEQUENCE { + te-type[0] INTEGER, + te-data[1] OCTET STRING +} + + + +te-data + This field contains opaque data that must be caried with the ticket to + support extensions to the Kerberos protocol including but not limited + to some forms of inter-realm key exchange and plaintext authorization + data. See appendix C for some common uses of this field. +te-type + This field specifies the format for the te-data subfield. All negative + values are reserved for local use. Non-negative values are reserved for + registered use. + +APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) +} + +TicketFlags ::= BIT STRING { + reserved(0), + forwardable(1), + forwarded(2), + proxiable(3), + proxy(4), + may-postdate(5), + postdated(6), + invalid(7), + renewable(8), + initial(9), + pre-authent(10), + hw-authent(11), + transited-policy-checked(12), + ok-as-delegate(13) +} + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +KDCOptions ::= BIT STRING { + 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), + unused12(12), + unused13(13), + disable-transited-check(26), + renewable-ok(27), + enc-tkt-in-skey(28), + renew(30), + validate(31) +} + +ASN.1 Bit strings have a length and a value. When used in Kerberos for the +APOptions, TicketFlags, and KDCOptions, the length of the bit string on +generated values should be the smallest multiple of 32 bits needed to +include the highest order bit that is set (1), but in no case less than 32 +bits. Implementations should accept values of bit strings of any length and +treat the value of flags cooresponding to bits beyond the end of the bit +string as if the bit were reset (0). Comparisonof bit strings of different +length should treat the smaller string as if it were padded with zeros +beyond the high order bits to the length of the longer string[23]. + +LastReq ::= SEQUENCE OF SEQUENCE { + lr-type[0] INTEGER, + lr-value[1] KerberosTime +} + +lr-type + This field indicates how the following lr-value field is to be + interpreted. Negative values indicate that the information pertains + only to the responding server. Non-negative values pertain to all + servers for the realm. If the lr-type field is zero (0), then no + information is conveyed by the lr-value subfield. If the absolute value + of the lr-type field is one (1), then the lr-value subfield is the time + of last initial request for a TGT. If it is two (2), then the lr-value + subfield is the time of last initial request. If it is three (3), then + the lr-value subfield is the time of issue for the newest + ticket-granting ticket used. If it is four (4), then the lr-value + subfield is the time of the last renewal. If it is five (5), then the + lr-value subfield is the time of last request (of any type). +lr-value + This field contains the time of the last request. the time must be + interpreted according to the contents of the accompanying lr-type + subfield. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, +EncryptionKey, EncryptionType, and KeyType. + +5.3. Tickets and Authenticators + +This section describes the format and encryption parameters for tickets and +authenticators. When a ticket or authenticator is included in a protocol +message it is treated as an opaque object. + +5.3.1. Tickets + +A ticket is a record that helps a client authenticate to a service. A Ticket +contains the following information: + +Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno[0] INTEGER, + realm[1] Realm, + sname[2] PrincipalName, + enc-part[3] EncryptedData, + extensions[4] TicketExtensions OPTIONAL +} + +-- Encrypted part of ticket +EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL +} +-- encoded Transited field +TransitedEncoding ::= SEQUENCE { + tr-type[0] INTEGER, -- must be registered + contents[1] OCTET STRING +} + +The encoding of EncTicketPart is encrypted in the key shared by Kerberos and +the end server (the server's secret key). See section 6 for the format of +the ciphertext. + +tkt-vno + This field specifies the version number for the ticket format. This + document describes version number 5. +realm + This field specifies the realm that issued a ticket. It also serves to + identify the realm part of the server's principal identifier. Since a + Kerberos server can only issue tickets for servers within its realm, + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + the two will always be identical. +sname + This field specifies the name part of the server's identity. +enc-part + This field holds the encrypted encoding of the EncTicketPart sequence. +extensions + This optional field contains a sequence of extentions that may be used + to carry information that must be carried with the ticket to support + several extensions, including but not limited to plaintext + authorization data, tokens for exchanging inter-realm keys, and other + information that must be associated with a ticket for use by the + application server. See Appendix C for definitions of some common + extensions. + + Note that some older versions of Kerberos did not support this field. + Because this is an optional field it will not break older clients, but + older clients might strip this field from the ticket before sending it + to the application server. This limits the usefulness of this ticket + field to environments where the ticket will not be parsed and + reconstructed by these older Kerberos clients. + + If it is known that the client will strip this field from the ticket, + as an interim measure the KDC may append this field to the end of the + enc-part of the ticket and append a traler indicating the lenght of the + appended extensions field. (this paragraph is open for discussion, + including the form of the traler). +flags + This field indicates which of various options were used or requested + when the ticket was issued. It is a bit-field, where the selected + options are indicated by the bit being set (1), and the unselected + options and reserved fields being reset (0). Bit 0 is the most + significant bit. The encoding of the bits is specified in section 5.2. + The flags are described in more detail above in section 2. The meanings + of the flags are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. When set, this + flag tells the ticket-granting server + that it is OK to issue a new ticket- + granting ticket with a different network + address based on the presented ticket. + + 2 FORWARDED + When set, this flag indicates that the + ticket has either been forwarded or was + issued based on authentication involving + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + a forwarded ticket-granting ticket. + + 3 PROXIABLE + The PROXIABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. The PROXIABLE + flag has an interpretation identical to + that of the FORWARDABLE flag, except + that the PROXIABLE flag tells the + ticket-granting server that only non- + ticket-granting tickets may be issued + with different network addresses. + + 4 PROXY + When set, this flag indicates that a + ticket is a proxy. + + 5 MAY-POSTDATE + The MAY-POSTDATE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. This flag tells + the ticket-granting server that a post- + dated ticket may be issued based on this + ticket-granting ticket. + + 6 POSTDATED + This flag indicates that this ticket has + been postdated. The end-service can + check the authtime field to see when the + original authentication occurred. + + 7 INVALID + This flag indicates that a ticket is + invalid, and it must be validated by the + KDC before use. Application servers + must reject tickets which have this flag + set. + + 8 RENEWABLE + The RENEWABLE flag is normally only + interpreted by the TGS, and can usually + be ignored by end servers (some particu- + larly careful servers may wish to disal- + low renewable tickets). A renewable + ticket can be used to obtain a replace- + ment ticket that expires at a later + date. + + 9 INITIAL + This flag indicates that this ticket was + issued using the AS protocol, and not + issued based on a ticket-granting + ticket. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + 10 PRE-AUTHENT + This flag indicates that during initial + authentication, the client was authenti- + cated by the KDC before a ticket was + issued. The strength of the pre- + authentication method is not indicated, + but is acceptable to the KDC. + + 11 HW-AUTHENT + This flag indicates that the protocol + employed for initial authentication + required the use of hardware expected to + be possessed solely by the named client. + The hardware authentication method is + selected by the KDC and the strength of + the method is not indicated. + + 12 TRANSITED This flag indicates that the KDC for the + POLICY-CHECKED realm has checked the transited field + against a realm defined policy for + trusted certifiers. If this flag is + reset (0), then the application server + must check the transited field itself, + and if unable to do so it must reject + the authentication. If the flag is set + (1) then the application server may skip + its own validation of the transited + field, relying on the validation + performed by the KDC. At its option the + application server may still apply its + own validation based on a separate + policy for acceptance. + + 13 OK-AS-DELEGATE This flag indicates that the server (not + the client) specified in the ticket has + been determined by policy of the realm + to be a suitable recipient of + delegation. A client can use the + presence of this flag to help it make a + decision whether to delegate credentials + (either grant a proxy or a forwarded + ticket granting ticket) to this server. + The client is free to ignore the value + of this flag. When setting this flag, + an administrator should consider the + Security and placement of the server on + which the service will run, as well as + whether the service requires the use of + delegated credentials. + + 14 ANONYMOUS + This flag indicates that the principal + named in the ticket is a generic princi- + pal for the realm and does not identify + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + the individual using the ticket. The + purpose of the ticket is only to + securely distribute a session key, and + not to identify the user. Subsequent + requests using the same ticket and ses- + sion may be considered as originating + from the same user, but requests with + the same username but a different ticket + are likely to originate from different + users. + + 15-31 RESERVED + Reserved for future use. + +key + This field exists in the ticket and the KDC response and is used to + pass the session key from Kerberos to the application server and the + client. The field's encoding is described in section 6.2. +crealm + This field contains the name of the realm in which the client is + registered and in which initial authentication took place. +cname + This field contains the name part of the client's principal identifier. +transited + This field lists the names of the Kerberos realms that took part in + authenticating the user to whom this ticket was issued. It does not + specify the order in which the realms were transited. See section + 3.3.3.2 for details on how this field encodes the traversed realms. +authtime + This field indicates the time of initial authentication for the named + principal. It is the time of issue for the original ticket on which + this ticket is based. It is included in the ticket to provide + additional information to the end service, and to provide the necessary + information for implementation of a `hot list' service at the KDC. An + end service that is particularly paranoid could refuse to accept + tickets for which the initial authentication occurred "too far" in the + past. This field is also returned as part of the response from the KDC. + When returned as part of the response to initial authentication + (KRB_AS_REP), this is the current time on the Ker- beros server[24]. +starttime + This field in the ticket specifies the time after which the ticket is + valid. Together with endtime, this field specifies the life of the + ticket. If it is absent from the ticket, its value should be treated as + that of the authtime field. +endtime + This field contains the time after which the ticket will not be honored + (its expiration time). Note that individual services may place their + own limits on the life of a ticket and may reject tickets which have + not yet expired. As such, this is really an upper bound on the + expiration time for the ticket. +renew-till + This field is only present in tickets that have the RENEWABLE flag set + in the flags field. It indicates the maximum endtime that may be + included in a renewal. It can be thought of as the absolute expiration + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + time for the ticket, including all renewals. +caddr + This field in a ticket contains zero (if omitted) or more (if present) + host addresses. These are the addresses from which the ticket can be + used. If there are no addresses, the ticket can be used from any + location. The decision by the KDC to issue or by the end server to + accept zero-address tickets is a policy decision and is left to the + Kerberos and end-service administrators; they may refuse to issue or + accept such tickets. The suggested and default policy, however, is that + such tickets will only be issued or accepted when additional + information that can be used to restrict the use of the ticket is + included in the authorization_data field. Such a ticket is a + capability. + + Network addresses are included in the ticket to make it harder for an + attacker to use stolen credentials. Because the session key is not sent + over the network in cleartext, credentials can't be stolen simply by + listening to the network; an attacker has to gain access to the session + key (perhaps through operating system security breaches or a careless + user's unattended session) to make use of stolen tickets. + + It is important to note that the network address from which a + connection is received cannot be reliably determined. Even if it could + be, an attacker who has compromised the client's worksta- tion could + use the credentials from there. Including the network addresses only + makes it more difficult, not impossible, for an attacker to walk off + with stolen credentials and then use them from a "safe" location. +authorization-data + The authorization-data field is used to pass authorization data from + the principal on whose behalf a ticket was issued to the application + service. If no authorization data is included, this field will be left + out. Experience has shown that the name of this field is confusing, and + that a better name for this field would be restrictions. Unfortunately, + it is not possible to change the name of this field at this time. + + This field contains restrictions on any authority obtained on the basis + of authentication using the ticket. It is possible for any principal in + posession of credentials to add entries to the authorization data field + since these entries further restrict what can be done with the ticket. + Such additions can be made by specifying the additional entries when a + new ticket is obtained during the TGS exchange, or they may be added + during chained delegation using the authorization data field of the + authenticator. + + Because entries may be added to this field by the holder of + credentials, it is not allowable for the presence of an entry in the + authorization data field of a ticket to amplify the priveleges one + would obtain from using a ticket. + + The data in this field may be specific to the end service; the field + will contain the names of service specific objects, and the rights to + those objects. The format for this field is described in section 5.2. + Although Kerberos is not concerned with the format of the contents of + the sub-fields, it does carry type information (ad-type). + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + By using the authorization_data field, a principal is able to issue a + proxy that is valid for a specific purpose. For example, a client + wishing to print a file can obtain a file server proxy to be passed to + the print server. By specifying the name of the file in the + authorization_data field, the file server knows that the print server + can only use the client's rights when accessing the particular file to + be printed. + + A separate service providing authorization or certifying group + membership may be built using the authorization-data field. In this + case, the entity granting authorization (not the authorized entity), + obtains a ticket in its own name (e.g. the ticket is issued in the name + of a privelege server), and this entity adds restrictions on its own + authority and delegates the restricted authority through a proxy to the + client. The client would then present this authorization credential to + the application server separately from the authentication exchange. + + Similarly, if one specifies the authorization-data field of a proxy and + leaves the host addresses blank, the resulting ticket and session key + can be treated as a capability. See [Neu93] for some suggested uses of + this field. + + The authorization-data field is optional and does not have to be + included in a ticket. + +5.3.2. Authenticators + +An authenticator is a record sent with a ticket to a server to certify the +client's knowledge of the encryption key in the ticket, to help the server +detect replays, and to help choose a "true session key" to use with the +particular session. The encoding is encrypted in the ticket's session key +shared by the client and the server: + +-- Unencrypted authenticator +Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL +} + + +authenticator-vno + This field specifies the version number for the format of the + authenticator. This document specifies version 5. +crealm and cname + These fields are the same as those described for the ticket in section + 5.3.1. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +cksum + This field contains a checksum of the the applica- tion data that + accompanies the KRB_AP_REQ. +cusec + This field contains the microsecond part of the client's timestamp. Its + value (before encryption) ranges from 0 to 999999. It often appears + along with ctime. The two fields are used together to specify a + reasonably accurate timestamp. +ctime + This field contains the current time on the client's host. +subkey + This field contains the client's choice for an encryption key which is + to be used to protect this specific application session. Unless an + application specifies otherwise, if this field is left out the session + key from the ticket will be used. +seq-number + This optional field includes the initial sequence number to be used by + the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to + detect replays (It may also be used by application specific messages). + When included in the authenticator this field specifies the initial + sequence number for messages from the client to the server. When + included in the AP-REP message, the initial sequence number is that for + messages from the server to the client. When used in KRB_PRIV or + KRB_SAFE messages, it is incremented by one after each message is sent. + + For sequence numbers to adequately support the detection of replays + they should be non-repeating, even across connection boundaries. The + initial sequence number should be random and uniformly distributed + across the full space of possible sequence numbers, so that it cannot + be guessed by an attacker and so that it and the successive sequence + numbers do not repeat other sequences. +authorization-data + This field is the same as described for the ticket in section 5.3.1. It + is optional and will only appear when additional restrictions are to be + placed on the use of a ticket, beyond those carried in the ticket + itself. + +5.4. Specifications for the AS and TGS exchanges + +This section specifies the format of the messages used in the exchange +between the client and the Kerberos server. The format of possible error +messages appears in section 5.9.1. + +5.4.1. KRB_KDC_REQ definition + +The KRB_KDC_REQ message has no type of its own. Instead, its type is one of +KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an initial +ticket or an additional ticket. In either case, the message is sent from the +client to the Authentication Server to request credentials for a service. + +The message fields are: + +AS-REQ ::= [APPLICATION 10] KDC-REQ +TGS-REQ ::= [APPLICATION 12] KDC-REQ + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +KDC-REQ ::= SEQUENCE { + pvno[1] INTEGER, + msg-type[2] INTEGER, + padata[3] SEQUENCE OF PA-DATA OPTIONAL, + req-body[4] KDC-REQ-BODY +} + +PA-DATA ::= SEQUENCE { + padata-type[1] INTEGER, + padata-value[2] OCTET STRING, + -- might be encoded AP-REQ +} + +KDC-REQ-BODY ::= SEQUENCE { + kdc-options[0] KDCOptions, + cname[1] PrincipalName OPTIONAL, + -- Used only in AS-REQ + realm[2] Realm, -- Server's realm + -- Also client's in AS-REQ + sname[3] PrincipalName OPTIONAL, + from[4] KerberosTime OPTIONAL, + till[5] KerberosTime OPTIONAL, + rtime[6] KerberosTime OPTIONAL, + nonce[7] INTEGER, + etype[8] SEQUENCE OF INTEGER, + -- EncryptionType, + -- in preference order + addresses[9] HostAddresses OPTIONAL, + enc-authorization-data[10] EncryptedData OPTIONAL, + -- Encrypted AuthorizationData + -- encoding + additional-tickets[11] SEQUENCE OF Ticket OPTIONAL +} + +The fields in this message are: + +pvno + This field is included in each message, and specifies the protocol + version number. This document specifies protocol version 5. +msg-type + This field indicates the type of a protocol message. It will almost + always be the same as the application identifier associated with a + message. It is included to make the identifier more readily accessible + to the application. For the KDC-REQ message, this type will be + KRB_AS_REQ or KRB_TGS_REQ. +padata + The padata (pre-authentication data) field contains a sequence of + authentication information which may be needed before credentials can + be issued or decrypted. In the case of requests for additional tickets + (KRB_TGS_REQ), this field will include an element with padata-type of + PA-TGS-REQ and data of an authentication header (ticket-granting ticket + and authenticator). The checksum in the authenticator (which must be + collision-proof) is to be computed over the KDC-REQ-BODY encoding. In + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + most requests for initial authentication (KRB_AS_REQ) and most replies + (KDC-REP), the padata field will be left out. + + This field may also contain information needed by certain extensions to + the Kerberos protocol. For example, it might be used to initially + verify the identity of a client before any response is returned. This + is accomplished with a padata field with padata-type equal to + PA-ENC-TIMESTAMP and padata-value defined as follows: + + padata-type ::= PA-ENC-TIMESTAMP + padata-value ::= EncryptedData -- PA-ENC-TS-ENC + + PA-ENC-TS-ENC ::= SEQUENCE { + patimestamp[0] KerberosTime, -- client's time + pausec[1] INTEGER OPTIONAL + } + + with patimestamp containing the client's time and pausec containing the + microseconds which may be omitted if a client will not generate more + than one request per second. The ciphertext (padata-value) consists of + the PA-ENC-TS-ENC sequence, encrypted using the client's secret key. + + [use-specified-kvno item is here for discussion and may be removed] It + may also be used by the client to specify the version of a key that is + being used for accompanying preauthentication, and/or which should be + used to encrypt the reply from the KDC. + + PA-USE-SPECIFIED-KVNO ::= Integer + + The KDC should only accept and abide by the value of the + use-specified-kvno preauthentication data field when the specified key + is still valid and until use of a new key is confirmed. This situation + is likely to occur primarily during the period during which an updated + key is propagating to other KDC's in a realm. + + The padata field can also contain information needed to help the KDC or + the client select the key needed for generating or decrypting the + response. This form of the padata is useful for supporting the use of + certain token cards with Kerberos. The details of such extensions are + specified in separate documents. See [Pat92] for additional uses of + this field. +padata-type + The padata-type element of the padata field indicates the way that the + padata-value element is to be interpreted. Negative values of + padata-type are reserved for unregistered use; non-negative values are + used for a registered interpretation of the element type. +req-body + This field is a placeholder delimiting the extent of the remaining + fields. If a checksum is to be calculated over the request, it is + calculated over an encoding of the KDC-REQ-BODY sequence which is + enclosed within the req-body field. +kdc-options + This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the + KDC and indicates the flags that the client wants set on the tickets as + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + well as other information that is to modify the behavior of the KDC. + Where appropriate, the name of an option may be the same as the flag + that is set by that option. Although in most case, the bit in the + options field will be the same as that in the flags field, this is not + guaranteed, so it is not acceptable to simply copy the options field to + the flags field. There are various checks that must be made before + honoring an option anyway. + + The kdc_options field is a bit-field, where the selected options are + indicated by the bit being set (1), and the unselected options and + reserved fields being reset (0). The encoding of the bits is specified + in section 5.2. The options are described in more detail above in + section 2. The meanings of the options are: + + Bit(s) Name Description + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE option indicates that + the ticket to be issued is to have its + forwardable flag set. It may only be + set on the initial request, or in a sub- + sequent request if the ticket-granting + ticket on which it is based is also for- + wardable. + + 2 FORWARDED + The FORWARDED option is only specified + in a request to the ticket-granting + server and will only be honored if the + ticket-granting ticket in the request + has its FORWARDABLE bit set. This + option indicates that this is a request + for forwarding. The address(es) of the + host from which the resulting ticket is + to be valid are included in the + addresses field of the request. + + 3 PROXIABLE + The PROXIABLE option indicates that the + ticket to be issued is to have its prox- + iable flag set. It may only be set on + the initial request, or in a subsequent + request if the ticket-granting ticket on + which it is based is also proxiable. + + 4 PROXY + The PROXY option indicates that this is + a request for a proxy. This option will + only be honored if the ticket-granting + ticket in the request has its PROXIABLE + bit set. The address(es) of the host + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + from which the resulting ticket is to be + valid are included in the addresses + field of the request. + + 5 ALLOW-POSTDATE + The ALLOW-POSTDATE option indicates that + the ticket to be issued is to have its + MAY-POSTDATE flag set. It may only be + set on the initial request, or in a sub- + sequent request if the ticket-granting + ticket on which it is based also has its + MAY-POSTDATE flag set. + + 6 POSTDATED + The POSTDATED option indicates that this + is a request for a postdated ticket. + This option will only be honored if the + ticket-granting ticket on which it is + based has its MAY-POSTDATE flag set. + The resulting ticket will also have its + INVALID flag set, and that flag may be + reset by a subsequent request to the KDC + after the starttime in the ticket has + been reached. + + 7 UNUSED + This option is presently unused. + + 8 RENEWABLE + The RENEWABLE option indicates that the + ticket to be issued is to have its + RENEWABLE flag set. It may only be set + on the initial request, or when the + ticket-granting ticket on which the + request is based is also renewable. If + this option is requested, then the rtime + field in the request contains the + desired absolute expiration time for the + ticket. + + 9-13 UNUSED + These options are presently unused. + + 14 REQUEST-ANONYMOUS + The REQUEST-ANONYMOUS option indicates + that the ticket to be issued is not to + identify the user to which it was + issued. Instead, the principal identif- + ier is to be generic, as specified by + the policy of the realm (e.g. usually + anonymous@realm). The purpose of the + ticket is only to securely distribute a + session key, and not to identify the + user. The ANONYMOUS flag on the ticket + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + to be returned should be set. If the + local realms policy does not permit + anonymous credentials, the request is to + be rejected. + + 15-25 RESERVED + Reserved for future use. + + 26 DISABLE-TRANSITED-CHECK + By default the KDC will check the + transited field of a ticket-granting- + ticket against the policy of the local + realm before it will issue derivative + tickets based on the ticket granting + ticket. If this flag is set in the + request, checking of the transited field + is disabled. Tickets issued without the + performance of this check will be noted + by the reset (0) value of the + TRANSITED-POLICY-CHECKED flag, + indicating to the application server + that the tranisted field must be checked + locally. KDC's are encouraged but not + required to honor the + DISABLE-TRANSITED-CHECK option. + + 27 RENEWABLE-OK + The RENEWABLE-OK option indicates that a + renewable ticket will be acceptable if a + ticket with the requested life cannot + otherwise be provided. If a ticket with + the requested life cannot be provided, + then a renewable ticket may be issued + with a renew-till equal to the the + requested endtime. The value of the + renew-till field may still be limited by + local limits, or limits selected by the + individual principal or server. + + 28 ENC-TKT-IN-SKEY + This option is used only by the ticket- + granting service. The ENC-TKT-IN-SKEY + option indicates that the ticket for the + end server is to be encrypted in the + session key from the additional ticket- + granting ticket provided. + + 29 RESERVED + Reserved for future use. + + 30 RENEW + This option is used only by the ticket- + granting service. The RENEW option + indicates that the present request is + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + for a renewal. The ticket provided is + encrypted in the secret key for the + server on which it is valid. This + option will only be honored if the + ticket to be renewed has its RENEWABLE + flag set and if the time in its renew- + till field has not passed. The ticket + to be renewed is passed in the padata + field as part of the authentication + header. + + 31 VALIDATE + This option is used only by the ticket- + granting service. The VALIDATE option + indicates that the request is to vali- + date a postdated ticket. It will only + be honored if the ticket presented is + postdated, presently has its INVALID + flag set, and would be otherwise usable + at this time. A ticket cannot be vali- + dated before its starttime. The ticket + presented for validation is encrypted in + the key of the server for which it is + valid and is passed in the padata field + as part of the authentication header. + +cname and sname + These fields are the same as those described for the ticket in section + 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is + specified. If absent, the name of the server is taken from the name of + the client in the ticket passed as additional-tickets. +enc-authorization-data + The enc-authorization-data, if present (and it can only be present in + the TGS_REQ form), is an encoding of the desired authorization-data + encrypted under the sub-session key if present in the Authenticator, or + alternatively from the session key in the ticket-granting ticket, both + from the padata field in the KRB_AP_REQ. +realm + This field specifies the realm part of the server's principal + identifier. In the AS exchange, this is also the realm part of the + client's principal identifier. +from + This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket + requests when the requested ticket is to be postdated. It specifies the + desired start time for the requested ticket. If this field is omitted + then the KDC should use the current time instead. +till + This field contains the expiration date requested by the client in a + ticket request. It is optional and if omitted the requested ticket is + to have the maximum endtime permitted according to KDC policy for the + parties to the authentication exchange as limited by expiration date of + the ticket granting ticket or other preauthentication credentials. +rtime + This field is the requested renew-till time sent from a client to the + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + KDC in a ticket request. It is optional. +nonce + This field is part of the KDC request and response. It it intended to + hold a random number generated by the client. If the same number is + included in the encrypted response from the KDC, it provides evidence + that the response is fresh and has not been replayed by an attacker. + Nonces must never be re-used. Ideally, it should be generated randomly, + but if the correct time is known, it may suffice[25]. +etype + This field specifies the desired encryption algorithm to be used in the + response. +addresses + This field is included in the initial request for tickets, and + optionally included in requests for additional tickets from the + ticket-granting server. It specifies the addresses from which the + requested ticket is to be valid. Normally it includes the addresses for + the client's host. If a proxy is requested, this field will contain + other addresses. The contents of this field are usually copied by the + KDC into the caddr field of the resulting ticket. +additional-tickets + Additional tickets may be optionally included in a request to the + ticket-granting server. If the ENC-TKT-IN-SKEY option has been + specified, then the session key from the additional ticket will be used + in place of the server's key to encrypt the new ticket. If more than + one option which requires additional tickets has been specified, then + the additional tickets are used in the order specified by the ordering + of the options bits (see kdc-options, above). + +The application code will be either ten (10) or twelve (12) depending on +whether the request is for an initial ticket (AS-REQ) or for an additional +ticket (TGS-REQ). + +The optional fields (addresses, authorization-data and additional-tickets) +are only included if necessary to perform the operation specified in the +kdc-options field. + +It should be noted that in KRB_TGS_REQ, the protocol version number appears +twice and two different message types appear: the KRB_TGS_REQ message +contains these fields as does the authentication header (KRB_AP_REQ) that is +passed in the padata field. + +5.4.2. KRB_KDC_REP definition + +The KRB_KDC_REP message format is used for the reply from the KDC for either +an initial (AS) request or a subsequent (TGS) request. There is no message +type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or +KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply +depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in +the client's secret key, and the client's key version number is included in +the key version number for the encrypted data. For KRB_TGS_REP, the +ciphertext is encrypted in the sub-session key from the Authenticator, or if +absent, the session key from the ticket-granting ticket used in the request. +In that case, no version number will be present in the EncryptedData +sequence. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +The KRB_KDC_REP message contains the following fields: + +AS-REP ::= [APPLICATION 11] KDC-REP +TGS-REP ::= [APPLICATION 13] KDC-REP + +KDC-REP ::= SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + padata[2] SEQUENCE OF PA-DATA OPTIONAL, + crealm[3] Realm, + cname[4] PrincipalName, + ticket[5] Ticket, + enc-part[6] EncryptedData +} + +EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart +EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart + +EncKDCRepPart ::= SEQUENCE { + key[0] EncryptionKey, + last-req[1] LastReq, + nonce[2] INTEGER, + key-expiration[3] KerberosTime OPTIONAL, + flags[4] TicketFlags, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + srealm[9] Realm, + sname[10] PrincipalName, + caddr[11] HostAddresses OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is either + KRB_AS_REP or KRB_TGS_REP. +padata + This field is described in detail in section 5.4.1. One possible use + for this field is to encode an alternate "mix-in" string to be used + with a string-to-key algorithm (such as is described in section 6.3.2). + This ability is useful to ease transitions if a realm name needs to + change (e.g. when a company is acquired); in such a case all existing + password-derived entries in the KDC database would be flagged as + needing a special mix-in string until the next password change. +crealm, cname, srealm and sname + These fields are the same as those described for the ticket in section + 5.3.1. +ticket + The newly-issued ticket, from section 5.3.1. +enc-part + This field is a place holder for the ciphertext and related information + that forms the encrypted part of a message. The description of the + encrypted part of the message follows each appearance of this field. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + The encrypted part is encoded as described in section 6.1. +key + This field is the same as described for the ticket in section 5.3.1. +last-req + This field is returned by the KDC and specifies the time(s) of the last + request by a principal. Depending on what information is available, + this might be the last time that a request for a ticket-granting ticket + was made, or the last time that a request based on a ticket-granting + ticket was successful. It also might cover all servers for a realm, or + just the particular server. Some implementations may display this + information to the user to aid in discovering unauthorized use of one's + identity. It is similar in spirit to the last login time displayed when + logging into timesharing systems. +nonce + This field is described above in section 5.4.1. +key-expiration + The key-expiration field is part of the response from the KDC and + specifies the time that the client's secret key is due to expire. The + expiration might be the result of password aging or an account + expiration. This field will usually be left out of the TGS reply since + the response to the TGS request is encrypted in a session key and no + client information need be retrieved from the KDC database. It is up to + the application client (usually the login program) to take appropriate + action (such as notifying the user) if the expiration time is imminent. +flags, authtime, starttime, endtime, renew-till and caddr + These fields are duplicates of those found in the encrypted portion of + the attached ticket (see section 5.3.1), provided so the client may + verify they match the intended request and to assist in proper ticket + caching. If the message is of type KRB_TGS_REP, the caddr field will + only be filled in if the request was for a proxy or forwarded ticket, + or if the user is substituting a subset of the addresses from the + ticket granting ticket. If the client-requested addresses are not + present or not used, then the addresses contained in the ticket will be + the same as those included in the ticket-granting ticket. + +5.5. Client/Server (CS) message specifications + +This section specifies the format of the messages used for the +authentication of the client to the application server. + +5.5.1. KRB_AP_REQ definition + +The KRB_AP_REQ message contains the Kerberos protocol version number, the +message type KRB_AP_REQ, an options field to indicate any options in use, +and the ticket and authenticator themselves. The KRB_AP_REQ message is often +referred to as the 'authentication header'. + +AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData +} + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) +} + + + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REQ. +ap-options + This field appears in the application request (KRB_AP_REQ) and affects + the way the request is processed. It is a bit-field, where the selected + options are indicated by the bit being set (1), and the unselected + options and reserved fields being reset (0). The encoding of the bits + is specified in section 5.2. The meanings of the options are: + + Bit(s) Name Description + 0 RESERVED + Reserved for future expansion of this + field. + + 1 USE-SESSION-KEY + The USE-SESSION-KEY option indicates + that the ticket the client is presenting + to a server is encrypted in the session + key from the server's ticket-granting + ticket. When this option is not speci- + fied, the ticket is encrypted in the + server's secret key. + + 2 MUTUAL-REQUIRED + The MUTUAL-REQUIRED option tells the + server that the client requires mutual + authentication, and that it must respond + with a KRB_AP_REP message. + + 3-31 RESERVED + Reserved for future use. +ticket + This field is a ticket authenticating the client to the server. +authenticator + This contains the authenticator, which includes the client's choice of + a subkey. Its encoding is described in section 5.3.2. + +5.5.2. KRB_AP_REP definition + +The KRB_AP_REP message contains the Kerberos protocol version number, the +message type, and an encrypted time- stamp. The message is sent in in +response to an application request (KRB_AP_REQ) where the mutual +authentication option has been selected in the ap-options field. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[2] EncryptedData +} + +EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { + ctime[0] KerberosTime, + cusec[1] INTEGER, + subkey[2] EncryptionKey OPTIONAL, + seq-number[3] INTEGER OPTIONAL +} + +The encoded EncAPRepPart is encrypted in the shared session key of the +ticket. The optional subkey field can be used in an application-arranged +negotiation to choose a per association session key. + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REP. +enc-part + This field is described above in section 5.4.2. +ctime + This field contains the current time on the client's host. +cusec + This field contains the microsecond part of the client's timestamp. +subkey + This field contains an encryption key which is to be used to protect + this specific application session. See section 3.2.6 for specifics on + how this field is used to negotiate a key. Unless an application + specifies otherwise, if this field is left out, the sub-session key + from the authenticator, or if also left out, the session key from the + ticket will be used. + +5.5.3. Error message reply + +If an error occurs while processing the application request, the KRB_ERROR +message will be sent in response. See section 5.9.1 for the format of the +error message. The cname and crealm fields may be left out if the server +cannot determine their appropriate values from the corresponding KRB_AP_REQ +message. If the authenticator was decipherable, the ctime and cusec fields +will contain the values from it. + +5.6. KRB_SAFE message specification + +This section specifies the format of a message that can be used by either +side (client or server) of an application to send a tamper-proof message to +its peer. It presumes that a session key has previously been exchanged (for +example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.6.1. KRB_SAFE definition + +The KRB_SAFE message contains user data along with a collision-proof +checksum keyed with the last encryption key negotiated via subkeys, or the + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +session key if no negotiation has occured. The message fields are: + +KRB-SAFE ::= [APPLICATION 20] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + safe-body[2] KRB-SAFE-BODY, + cksum[3] Checksum +} + +KRB-SAFE-BODY ::= SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_SAFE. +safe-body + This field is a placeholder for the body of the KRB-SAFE message. It is + to be encoded separately and then have the checksum computed over it, + for use in the cksum field. +cksum + This field contains the checksum of the application data. Checksum + details are described in section 6.4. The checksum is computed over the + encoding of the KRB-SAFE-BODY sequence. +user-data + This field is part of the KRB_SAFE and KRB_PRIV messages and contain + the application specific data that is being passed from the sender to + the recipient. +timestamp + This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents + are the current time as known by the sender of the message. By checking + the timestamp, the recipient of the message is able to make sure that + it was recently generated, and is not a replay. +usec + This field is part of the KRB_SAFE and KRB_PRIV headers. It contains + the microsecond part of the timestamp. +seq-number + This field is described above in section 5.3.2. +s-address + This field specifies the address in use by the sender of the message. +r-address + This field specifies the address in use by the recipient of the + message. It may be omitted for some uses (such as broadcast protocols), + but the recipient may arbitrarily reject such messages. This field + along with s-address can be used to help detect messages which have + been incorrectly or maliciously delivered to the wrong recipient. + +5.7. KRB_PRIV message specification + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +This section specifies the format of a message that can be used by either +side (client or server) of an application to securely and privately send a +message to its peer. It presumes that a session key has previously been +exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.7.1. KRB_PRIV definition + +The KRB_PRIV message contains user data encrypted in the Session Key. The +message fields are: + +KRB-PRIV ::= [APPLICATION 21] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[3] EncryptedData +} + +EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, -- sender's addr + r-address[5] HostAddress OPTIONAL -- recip's addr +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_PRIV. +enc-part + This field holds an encoding of the EncKrbPrivPart sequence encrypted + under the session key[32]. This encrypted encoding is used for the + enc-part field of the KRB-PRIV message. See section 6 for the format of + the ciphertext. +user-data, timestamp, usec, s-address and r-address + These fields are described above in section 5.6.1. +seq-number + This field is described above in section 5.3.2. + +5.8. KRB_CRED message specification + +This section specifies the format of a message that can be used to send +Kerberos credentials from one principal to another. It is presented here to +encourage a common mechanism to be used by applications when forwarding +tickets or providing proxies to subordinate servers. It presumes that a +session key has already been exchanged perhaps by using the +KRB_AP_REQ/KRB_AP_REP messages. + +5.8.1. KRB_CRED definition + +The KRB_CRED message contains a sequence of tickets to be sent and +information needed to use the tickets, including the session key from each. +The information needed to use the tickets is encrypted under an encryption +key previously exchanged or transferred alongside the KRB_CRED message. The +message fields are: + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +KRB-CRED ::= [APPLICATION 22] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, -- KRB_CRED + tickets[2] SEQUENCE OF Ticket, + enc-part[3] EncryptedData +} + +EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { + ticket-info[0] SEQUENCE OF KrbCredInfo, + nonce[1] INTEGER OPTIONAL, + timestamp[2] KerberosTime OPTIONAL, + usec[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +KrbCredInfo ::= SEQUENCE { + key[0] EncryptionKey, + prealm[1] Realm OPTIONAL, + pname[2] PrincipalName OPTIONAL, + flags[3] TicketFlags OPTIONAL, + authtime[4] KerberosTime OPTIONAL, + starttime[5] KerberosTime OPTIONAL, + endtime[6] KerberosTime OPTIONAL + renew-till[7] KerberosTime OPTIONAL, + srealm[8] Realm OPTIONAL, + sname[9] PrincipalName OPTIONAL, + caddr[10] HostAddresses OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_CRED. +tickets + These are the tickets obtained from the KDC specifically for use by the + intended recipient. Successive tickets are paired with the + corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED + message. +enc-part + This field holds an encoding of the EncKrbCredPart sequence encrypted + under the session key shared between the sender and the intended + recipient. This encrypted encoding is used for the enc-part field of + the KRB-CRED message. See section 6 for the format of the ciphertext. +nonce + If practical, an application may require the inclusion of a nonce + generated by the recipient of the message. If the same value is + included as the nonce in the message, it provides evidence that the + message is fresh and has not been replayed by an attacker. A nonce must + never be re-used; it should be generated randomly by the recipient of + the message and provided to the sender of the message in an application + specific manner. +timestamp and usec + These fields specify the time that the KRB-CRED message was generated. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + The time is used to provide assurance that the message is fresh. +s-address and r-address + These fields are described above in section 5.6.1. They are used + optionally to provide additional assurance of the integrity of the + KRB-CRED message. +key + This field exists in the corresponding ticket passed by the KRB-CRED + message and is used to pass the session key from the sender to the + intended recipient. The field's encoding is described in section 6.2. + +The following fields are optional. If present, they can be associated with +the credentials in the remote ticket file. If left out, then it is assumed +that the recipient of the credentials already knows their value. + +prealm and pname + The name and realm of the delegated principal identity. +flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr + These fields contain the values of the correspond- ing fields from the + ticket found in the ticket field. Descriptions of the fields are + identical to the descriptions in the KDC-REP message. + +5.9. Error message specification + +This section specifies the format for the KRB_ERROR message. The fields +included in the message are intended to return as much information as +possible about an error. It is not expected that all the information +required by the fields will be available for all types of errors. If the +appropriate information is not available when the message is composed, the +corresponding field will be left out of the message. + +Note that since the KRB_ERROR message is not protected by any encryption, it +is quite possible for an intruder to synthesize or modify such a message. In +particular, this means that the client should not use any fields in this +message for security-critical purposes, such as setting a system clock or +generating a fresh authenticator. The message can be useful, however, for +advising a user on the reason for some failure. + +5.9.1. KRB_ERROR definition + +The KRB_ERROR message consists of the following fields: + +KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + e-data[12] OCTET STRING OPTIONAL, + e-cksum[13] Checksum OPTIONAL, + e-typed-data[14] SEQUENCE of ETypedData OPTIONAL +} + +ETypedData ::= SEQUENCE { + e-data-type [1] INTEGER, + e-data-value [2] OCTET STRING, +} + + + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_ERROR. +ctime + This field is described above in section 5.4.1. +cusec + This field is described above in section 5.5.2. +stime + This field contains the current time on the server. It is of type + KerberosTime. +susec + This field contains the microsecond part of the server's timestamp. Its + value ranges from 0 to 999999. It appears along with stime. The two + fields are used in conjunction to specify a reasonably accurate + timestamp. +error-code + This field contains the error code returned by Kerberos or the server + when a request fails. To interpret the value of this field see the list + of error codes in section 8. Implementations are encouraged to provide + for national language support in the display of error messages. +crealm, cname, srealm and sname + These fields are described above in section 5.3.1. +e-text + This field contains additional text to help explain the error code + associated with the failed request (for example, it might include a + principal name which was unknown). +e-data + This field contains additional data about the error for use by the + application to help it recover from or handle the error. If the + errorcode is KDC_ERR_PREAUTH_REQUIRED, then the e-data field will + contain an encoding of a sequence of padata fields, each corresponding + to an acceptable pre-authentication method and optionally containing + data for the method: + + METHOD-DATA ::= SEQUENCE of PA-DATA + + If the error-code is KRB_AP_ERR_METHOD, then the e-data field will + contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type[0] INTEGER, + method-data[1] OCTET STRING OPTIONAL + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + } + + method-type will indicate the required alternate method; method-data + will contain any required additional information. +e-cksum + This field contains an optional checksum for the KRB-ERROR message. The + checksum is calculated over the Kerberos ASN.1 encoding of the + KRB-ERROR message with the checksum absent. The checksum is then added + to the KRB-ERROR structure and the message is re-encoded. The Checksum + should be calculated using the session key from the ticket granting + ticket or service ticket, where available. If the error is in response + to a TGS or AP request, the checksum should be calculated uing the the + session key from the client's ticket. If the error is in response to an + AS request, then the checksum should be calulated using the client's + secret key ONLY if there has been suitable preauthentication to prove + knowledge of the secret key by the client[33]. If a checksum can not be + computed because the key to be used is not available, no checksum will + be included. +e-typed-data + [This field for discussion, may be deleted from final spec] This field + contains optional data that may be used to help the client recover from + the indicated error. [This could contain the METHOD-DATA specified + since I don't think anyone actually uses it yet. It could also contain + the PA-DATA sequence for the preauth required error if we had a clear + way to transition to the use of this field from the use of the untype + e-data field.] For example, this field may specify the key version of + the key used to verify preauthentication: + + e-data-type := 20 -- Key version number + e-data-value := Integer -- Key version number used to verify + preauthentication + +6. Encryption and Checksum Specifications + +The Kerberos protocols described in this document are designed to use stream +encryption ciphers, which can be simulated using commonly available block +encryption ciphers, such as the Data Encryption Standard, [DES77] in +conjunction with block chaining and checksum methods [DESM80]. Encryption is +used to prove the identities of the network entities participating in +message exchanges. The Key Distribution Center for each realm is trusted by +all principals registered in that realm to store a secret key in confidence. +Proof of knowledge of this secret key is used to verify the authenticity of +a principal. + +The KDC uses the principal's secret key (in the AS exchange) or a shared +session key (in the TGS exchange) to encrypt responses to ticket requests; +the ability to obtain the secret key or session key implies the knowledge of +the appropriate keys and the identity of the KDC. The ability of a principal +to decrypt the KDC response and present a Ticket and a properly formed +Authenticator (generated with the session key from the KDC response) to a +service verifies the identity of the principal; likewise the ability of the +service to extract the session key from the Ticket and prove its knowledge +thereof in a response verifies the identity of the service. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +The Kerberos protocols generally assume that the encryption used is secure +from cryptanalysis; however, in some cases, the order of fields in the +encrypted portions of messages are arranged to minimize the effects of +poorly chosen keys. It is still important to choose good keys. If keys are +derived from user-typed passwords, those passwords need to be well chosen to +make brute force attacks more difficult. Poorly chosen keys still make easy +targets for intruders. + +The following sections specify the encryption and checksum mechanisms +currently defined for Kerberos. The encodings, chaining, and padding +requirements for each are described. For encryption methods, it is often +desirable to place random information (often referred to as a confounder) at +the start of the message. The requirements for a confounder are specified +with each encryption mechanism. + +Some encryption systems use a block-chaining method to improve the the +security characteristics of the ciphertext. However, these chaining methods +often don't provide an integrity check upon decryption. Such systems (such +as DES in CBC mode) must be augmented with a checksum of the plain-text +which can be verified at decryption and used to detect any tampering or +damage. Such checksums should be good at detecting burst errors in the +input. If any damage is detected, the decryption routine is expected to +return an error indicating the failure of an integrity check. Each +encryption type is expected to provide and verify an appropriate checksum. +The specification of each encryption method sets out its checksum +requirements. + +Finally, where a key is to be derived from a user's password, an algorithm +for converting the password to a key of the appropriate type is included. It +is desirable for the string to key function to be one-way, and for the +mapping to be different in different realms. This is important because users +who are registered in more than one realm will often use the same password +in each, and it is desirable that an attacker compromising the Kerberos +server in one realm not obtain or derive the user's key in another. + +For an discussion of the integrity characteristics of the candidate +encryption and checksum methods considered for Kerberos, the the reader is +referred to [SG92]. + +6.1. Encryption Specifications + +The following ASN.1 definition describes all encrypted messages. The +enc-part field which appears in the unencrypted part of messages in section +5 is a sequence consisting of an encryption type, an optional key version +number, and the ciphertext. + +EncryptedData ::= SEQUENCE { + etype[0] INTEGER, -- EncryptionType + kvno[1] INTEGER OPTIONAL, + cipher[2] OCTET STRING -- ciphertext +} + + + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +etype + This field identifies which encryption algorithm was used to encipher + the cipher. Detailed specifications for selected encryption types + appear later in this section. +kvno + This field contains the version number of the key under which data is + encrypted. It is only present in messages encrypted under long lasting + keys, such as principals' secret keys. +cipher + This field contains the enciphered text, encoded as an OCTET STRING. + +The cipher field is generated by applying the specified encryption algorithm +to data composed of the message and algorithm-specific inputs. Encryption +mechanisms defined for use with Kerberos must take sufficient measures to +guarantee the integrity of the plaintext, and we recommend they also take +measures to protect against precomputed dictionary attacks. If the +encryption algorithm is not itself capable of doing so, the protections can +often be enhanced by adding a checksum and a confounder. + +The suggested format for the data to be encrypted includes a confounder, a +checksum, the encoded plaintext, and any necessary padding. The msg-seq +field contains the part of the protocol message described in section 5 which +is to be encrypted. The confounder, checksum, and padding are all untagged +and untyped, and their length is exactly sufficient to hold the appropriate +item. The type and length is implicit and specified by the particular +encryption type being used (etype). The format for the data to be encrypted +is described in the following diagram: + + +-----------+----------+-------------+-----+ + |confounder | check | msg-seq | pad | + +-----------+----------+-------------+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +CipherText ::= ENCRYPTED SEQUENCE { + confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, + check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, + msg-seq[2] MsgSequence, + pad UNTAGGED OCTET STRING(pad_length) OPTIONAL +} + +One generates a random confounder of the appropriate length, placing it in +confounder; zeroes out check; calculates the appropriate checksum over +confounder, check, and msg-seq, placing the result in check; adds the +necessary padding; then encrypts using the specified encryption type and the +appropriate key. + +Unless otherwise specified, a definition of an encryption algorithm that +specifies a checksum, a length for the confounder field, or an octet +boundary for padding uses this ciphertext format[36]. Those fields which are +not specified will be omitted. + +In the interest of allowing all implementations using a particular + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +encryption type to communicate with all others using that type, the +specification of an encryption type defines any checksum that is needed as +part of the encryption process. If an alternative checksum is to be used, a +new encryption type must be defined. + +Some cryptosystems require additional information beyond the key and the +data to be encrypted. For example, DES, when used in cipher-block-chaining +mode, requires an initialization vector. If required, the description for +each encryption type must specify the source of such additional information. +6.2. Encryption Keys + +The sequence below shows the encoding of an encryption key: + + EncryptionKey ::= SEQUENCE { + keytype[0] INTEGER, + keyvalue[1] OCTET STRING + } + +keytype + This field specifies the type of encryption key that follows in the + keyvalue field. It will almost always correspond to the encryption + algorithm used to generate the EncryptedData, though more than one + algorithm may use the same type of key (the mapping is many to one). + This might happen, for example, if the encryption algorithm uses an + alternate checksum algorithm for an integrity check, or a different + chaining mechanism. +keyvalue + This field contains the key itself, encoded as an octet string. + +All negative values for the encryption key type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpreta- tions. + +6.3. Encryption Systems + +6.3.1. The NULL Encryption System (null) + +If no encryption is in use, the encryption system is said to be the NULL +encryption system. In the NULL encryption system there is no checksum, +confounder or padding. The ciphertext is simply the plaintext. The NULL Key +is used by the null encryption system and is zero octets in length, with +keytype zero (0). + +6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) + +The des-cbc-crc encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. A +CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the +confounder and message sequence (msg-seq) and placed in the cksum field. DES +blocks are 8 bytes. As a result, the data to be encrypted (the concatenation +of confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. The details of the encryption of this data are identical +to those for the des-cbc-md5 encryption mode. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +Note that, since the CRC-32 checksum is not collision-proof, an attacker +could use a probabilistic chosen-plaintext attack to generate a valid +message even if a confounder is used [SG92]. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. The use of the CRC-32 as the checksum for ticket or +authenticator is no longer mandated as an interoperability requirement for +Kerberos Version 5 Specification 1 (See section 9.1 for specific details). + +6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) + +The des-cbc-md4 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD4 checksum (described in [MD492]) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. The details of the encryption of this data are identical +to those for the des-cbc-md5 encryption mode. + +6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) + +The des-cbc-md5 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD5 checksum (described in [MD5-92].) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. + +Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are +concatenated to make the 64-bit inputs for the DES algorithms. The first +octet supplies the 8 most significant bits (with the octet's MSbit used as +the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., +and the eighth octet supplies the 8 least significant bits. + +Encryption under DES using cipher block chaining requires an additional +input in the form of an initialization vector. Unless otherwise specified, +zero should be used as the initialization vector. Kerberos' use of DES +requires an 8 octet confounder. + +The DES specifications identify some 'weak' and 'semi-weak' keys; those keys +shall not be used for encrypting messages for use in Kerberos. Additionally, +because of the way that keys are derived for the encryption of checksums, +keys shall not be used that yield 'weak' or 'semi-weak' keys when +eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. + +A DES key is 8 octets of data, with keytype one (1). This consists of 56 +bits of key, and 8 parity bits (one per octet). The key is encoded as a +series of 8 octets written in MSB-first order. The bits within the key are +also encoded in MSB order. For example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where +B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity +bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the +MSbit). [See the FIPS 81 introduction for reference.] + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +String to key transformation + +To generate a DES key from a text string (password), the text string +normally must have the realm and each component of the principal's name +appended[37], then padded with ASCII nulls to an 8 byte boundary. This +string is then fan-folded and eXclusive-ORed with itself to form an 8 byte +DES key. The parity is corrected on the key, and it is used to generate a +DES CBC checksum on the initial string (with the realm and name appended). +Next, parity is corrected on the CBC checksum. If the result matches a +'weak' or 'semi-weak' key as described in the DES specification, it is +eXclusive-ORed with the constant 00000000000000F0. Finally, the result is +returned as the key. Pseudocode follows: + + string_to_key(string,realm,name) { + odd = 1; + s = string + realm; + for(each component in name) { + s = s + component; + } + tempkey = NULL; + pad(s); /* with nulls to 8 byte boundary */ + for(8byteblock in s) { + if(odd == 0) { + odd = 1; + reverse(8byteblock) + } + else odd = 0; + tempkey = tempkey XOR 8byteblock; + } + fixparity(tempkey); + key = DES-CBC-check(s,tempkey); + fixparity(key); + if(is_weak_key_key(key)) + key = key XOR 0xF0; + return(key); + } + +6.3.5. Triple DES EDE in outer CBC mode with an SHA1 check-sum +(des3-cbc-sha1) + +The des3-cbc-sha1 encryption encodes information using three Data Encryption +Standard transformations with three DES keys. The first key is used to +perform a DES ECB encryption on an eight-octet data block using the first +DES key, followed by a DES ECB decryption of the result using the second DES +key, and a DES ECB encryption of the result using the third DES key. Because +DES blocks are 8 bytes, the data to be encrypted (the concatenation of +confounder, checksum, and message) must first be padded to an 8 byte +boundary before encryption. To support the outer CBC mode, the input is +padded to an eight-octet boundary. The first 8 octets of the data to be +encrypted (the confounder) is exclusive-ored with an initialization vector +of zero and then ECB encrypted using triple DES as described above. +Subsequent blocks of 8 octets are exclusive-ored with the ciphertext +produced by the encryption on the previous block before ECB encryption. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +An HMAC-SHA1 checksum (described in [KBC96].) is applied to the confounder +and message sequence (msg-seq) and placed in the cksum field. + +Plaintext are encoded as blocks of 8 octets which are concatenated to make +the 64-bit inputs for the DES algorithms. The first octet supplies the 8 +most significant bits (with the octet's MSbit used as the DES input block's +MSbit, etc.), the second octet the next 8 bits, ..., and the eighth octet +supplies the 8 least significant bits. + +Encryption under Triple DES using cipher block chaining requires an +additional input in the form of an initialization vector. Unless otherwise +specified, zero should be used as the initialization vector. Kerberos' use +of DES requires an 8 octet confounder. + +The DES specifications identify some 'weak' and 'semi-weak' keys; those keys +shall not be used for encrypting messages for use in Kerberos. Additionally, +because of the way that keys are derived for the encryption of checksums, +keys shall not be used that yield 'weak' or 'semi-weak' keys when +eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. + +A Triple DES key is 24 octets of data, with keytype seven (7). This consists +of 168 bits of key, and 24 parity bits (one per octet). The key is encoded +as a series of 24 octets written in MSB-first order, with the first 8 octets +treated as the first DES key, the second 8 octets as the second key, and the +third 8 octets the third DES key. The bits within each key are also encoded +in MSB order. For example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where +B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity +bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the +MSbit). [See the FIPS 81 introduction for reference.] + +Key derivation for specified operations (Horowitz) + +[Discussion is needed for this section, especially since it does not simply +derive key generation, but also specifies encryption using triple DES in a +manner that is different than the basic template that was specified for +single DES and similar systems] + +In the Kerberos protocol cryptographic keys are used in a number of places. +In order to minimize the effect of compromising a key, it is desirable to +use a different key in each of these places. Key derivation [Horowitz96] can +be used to construct different keys for each operation from the keys +transported on the network or derived from the password specified by the +user. + +For each place where a key is used in Kerberos, a ``key usage'' is specified +for that purpose. The key, key usage, and encryption/checksum type together +describe the transformation from plaintext to ciphertext. For backwards +compatibility, this key derivation is only specified here for encryption +methods based on triple DES. Encryption methods specified for use by +Kerberos in the future should specify the key derivation function to be +used. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +Kerberos requires that the ciphertext component of EncryptedData be +tamper-resistant as well as confidential. This implies encryption and +integrity functions, which must each use their own separate keys. So, for +each key usage, two keys must be generated, one for encryption (Ke), and one +for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + +where the key usage is represented as a 32 bit integer in network byte +order. The ciphertest must be generated from the plaintext as follows: + + ciphertext = E(Ke, confounder | length | plaintext | padding) | + H(Ki, confounder | length | plaintext | padding) + +The confounder and padding are specific to the encryption algorithm E. + +When generating a checksum only, there is no need for a confounder or +padding. Again, a new key (Kc) must be used. Checksums must be generated +from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + MAC = H(Kc, length | plaintext) + + +Note that each enctype is described by an encryption algorithm E and a keyed +hash algorithm H, and each checksum type is described by a keyed hash +algorithm H. HMAC, with an appropriate hash, is recommended for use as H. + +The key usage value will be taken from the following list of places where +keys are used in the Kerberos protocol, with key usage values and Kerberos +specification section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + 10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) + 11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) + 12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) + + 13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) + 14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) + 15. KRB-SAFE cksum, keyed with a key chosen by the application + (section 5.8.1) + + 16. Data which is defined in some specification outside of + Kerberos to be encrypted using Kerberos encryption type. + 17. Data which is defined in some specification outside of + Kerberos to be checksummed using Kerberos checksum type. + + 18. KRB-ERROR checksum (e-cksum in section 5.9.1) + 19. AD-KDCIssued checksum (ad-checksum in appendix B.1) + 20. Checksum for Mandatory Ticket Extensions (appendix B.6) + 21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) + +String to key transformation + +To generate a DES key from a text string (password), the text string +normally must have the realm and each component of the principal's name +appended[38]. + +The input string (with any salt data appended to it) is n-folded into a 24 +octet (192 bit) string. To n-fold a number X, replicate the input value to a +length that is the least common multiple of n and the length of X. Before +each repetition, the input X is rotated to the right by 13 bit positions. +The successive n-bit chunks are added together using 1's-complement addition +(addition with end-around carry) to yield a n-bit result. (This +transformation was proposed by Richard Basch) + +Each successive set of 8 octets is taken as a DES key, and its parity is +adjusted in the same manner as previously described. If any of the three +sets of 8 octets match a 'weak' or 'semi-weak key as described in the DES +specification, that chunk is eXclusive-ORed with the hexadecimal constant +00000000000000F0. The resulting DES keys are then used in sequence to +perform a Triple-DES CBC encryption of the n-folded input string (appended +with any salt data), using a zero initial vector. Parity, weak, and +semi-weak keys are once again corrected and the result is returned as the 24 +octet key. + +Pseudocode follows: + + string_to_key(string,realm,name) { + s = string + realm; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + for(each component in name) { + s = s + component; + } + tkey[24] = fold(s); + fixparity(tkey); + if(isweak(tkey[0-7])) tkey[0-7] = tkey[0-7] XOR 0xF0; + if(isweak(tkey[8-15])) tkey[8-15] = tkey[8-15] XOR 0xF0; + if(is_weak(tkey[16-23])) tkey[16-23] = tkey[16-23] XOR 0xF0; + key[24] = 3DES-CBC(data=fold(s),key=tkey,iv=0); + fixparity(key); + if(is_weak(key[0-7])) key[0-7] = key[0-7] XOR 0xF0; + if(is_weak(key[8-15])) key[8-15] = key[8-15] XOR 0xF0; + if(is_weak(key[16-23])) key[16-23] = key[16-23] XOR 0xF0; + return(key); + } + +6.4. Checksums + +The following is the ASN.1 definition used for a checksum: + + Checksum ::= SEQUENCE { + cksumtype[0] INTEGER, + checksum[1] OCTET STRING + } + +cksumtype + This field indicates the algorithm used to generate the accompanying + checksum. +checksum + This field contains the checksum itself, encoded as an octet string. + +Detailed specification of selected checksum types appear later in this +section. Negative values for the checksum type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpretations. + +Checksums used by Kerberos can be classified by two properties: whether they +are collision-proof, and whether they are keyed. It is infeasible to find +two plaintexts which generate the same checksum value for a collision-proof +checksum. A key is required to perturb or initialize the algorithm in a +keyed checksum. To prevent message-stream modification by an active +attacker, unkeyed checksums should only be used when the checksum and +message will be subsequently encrypted (e.g. the checksums defined as part +of the encryption algorithms covered earlier in this section). + +Collision-proof checksums can be made tamper-proof if the checksum value is +encrypted before inclusion in a message. In such cases, the composition of +the checksum and the encryption algorithm must be considered a separate +checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum +algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for the +encrypted forms of unkeyed collision-proof checksums, Kerberos prepends a +confounder before the checksum is calculated. + +6.4.1. The CRC-32 Checksum (crc32) + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +The CRC-32 checksum calculates a checksum based on a cyclic redundancy check +as described in ISO 3309 [ISO3309]. The resulting checksum is four (4) +octets in length. The CRC-32 is neither keyed nor collision-proof. The use +of this checksum is not recommended. An attacker using a probabilistic +chosen-plaintext attack as described in [SG92] might be able to generate an +alternative message that satisfies the checksum. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. + +6.4.2. The RSA MD4 Checksum (rsa-md4) + +The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm +[MD4-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed to +be collision-proof. + +6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) + +The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD4 +checksum algorithm, and encrypting the confounder and the checksum using DES +in cipher-block-chaining (CBC) mode using a variant of the key, where the +variant is computed by eXclusive-ORing the key with the constant +F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The +resulting checksum is 24 octets long (8 octets of which are redundant). This +checksum is tamper-proof and believed to be collision-proof. + +The DES specifications identify some weak keys' and 'semi-weak keys'; those +keys shall not be used for generating RSA-MD4 checksums for use in Kerberos. + +The format for the checksum is described in the follow- ing diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.4. The RSA MD5 Checksum (rsa-md5) + +The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. +[MD5-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed to +be collision-proof. + +6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD5 +checksum algorithm, and encrypting the confounder and the checksum using DES +in cipher-block-chaining (CBC) mode using a variant of the key, where the +variant is computed by eXclusive-ORing the key with the hexadecimal constant +F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting +checksum is 24 octets long (8 octets of which are redundant). This checksum +is tamper-proof and believed to be collision-proof. + +The DES specifications identify some 'weak keys' and 'semi-weak keys'; those +keys shall not be used for encrypting RSA-MD5 checksums for use in Kerberos. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.6. DES cipher-block chained checksum (des-mac) + +The DES-MAC checksum is computed by prepending an 8 octet confounder to the +plaintext, performing a DES CBC-mode encryption on the result using the key +and an initialization vector of zero, taking the last block of the +ciphertext, prepending the same confounder and encrypting the pair using DES +in cipher-block-chaining (CBC) mode using a a variant of the key, where the +variant is computed by eXclusive-ORing the key with the hexadecimal constant +F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting +checksum is 128 bits (16 octets) long, 64 bits of which are redundant. This +checksum is tamper-proof and collision-proof. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ +| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(8) +} + +The DES specifications identify some 'weak' and 'semi-weak' keys; those keys +shall not be used for generating DES-MAC checksums for use in Kerberos, nor + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +shall a key be used whose variant is 'weak' or 'semi-weak'. + +6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) + +The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by +applying the RSA MD4 checksum algorithm and encrypting the results using DES +in cipher-block-chaining (CBC) mode using a DES key as both key and +initialization vector. The resulting checksum is 16 octets long. This +checksum is tamper-proof and believed to be collision-proof. Note that this +checksum type is the old method for encoding the RSA-MD4-DES checksum and it +is no longer recommended. + +6.4.8. DES cipher-block chained checksum alternative (des-mac-k) + +The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption +of the plaintext, and using the last block of the ciphertext as the checksum +value. It is keyed with an encryption key and an initialization vector; any +uses which do not specify an additional initialization vector will use the +key as both key and initialization vector. The resulting checksum is 64 bits +(8 octets) long. This checksum is tamper-proof and collision-proof. Note +that this checksum type is the old method for encoding the DES-MAC checksum +and it is no longer recommended. The DES specifications identify some 'weak +keys' and 'semi-weak keys'; those keys shall not be used for generating +DES-MAC checksums for use in Kerberos. + +7. Naming Constraints + +7.1. Realm Names + +Although realm names are encoded as GeneralStrings and although a realm can +technically select any name it chooses, interoperability across realm +boundaries requires agreement on how realm names are to be assigned, and +what information they imply. + +To enforce these conventions, each realm must conform to the conventions +itself, and it must require that any realms with which inter-realm keys are +shared also conform to the conventions and require the same from its +neighbors. + +Kerberos realm names are case sensitive. Realm names that differ only in the +case of the characters are not equivalent. There are presently four styles +of realm names: domain, X500, other, and reserved. Examples of each style +follow: + + domain: ATHENA.MIT.EDU (example) + X500: C=US/O=OSF (example) + other: NAMETYPE:rest/of.name=without-restrictions (example) + reserved: reserved, but will not conflict with above + +Domain names must look like domain names: they consist of components +separated by periods (.) and they contain neither colons (:) nor slashes +(/). Domain names must be converted to upper case when used as realm names. + +X.500 names contain an equal (=) and cannot contain a colon (:) before the + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +equal. The realm names for X.500 names will be string representations of the +names with components separated by slashes. Leading and trailing slashes +will not be included. + +Names that fall into the other category must begin with a prefix that +contains no equal (=) or period (.) and the prefix must be followed by a +colon (:) and the rest of the name. All prefixes must be assigned before +they may be used. Presently none are assigned. + +The reserved category includes strings which do not fall into the first +three categories. All names in this category are reserved. It is unlikely +that names will be assigned to this category unless there is a very strong +argument for not using the 'other' category. + +These rules guarantee that there will be no conflicts between the various +name styles. The following additional constraints apply to the assignment of +realm names in the domain and X.500 categories: the name of a realm for the +domain or X.500 formats must either be used by the organization owning (to +whom it was assigned) an Internet domain name or X.500 name, or in the case +that no such names are registered, authority to use a realm name may be +derived from the authority of the parent realm. For example, if there is no +domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can +authorize the creation of a realm with that name. + +This is acceptable because the organization to which the parent is assigned +is presumably the organization authorized to assign names to its children in +the X.500 and domain name systems as well. If the parent assigns a realm +name without also registering it in the domain name or X.500 hierarchy, it +is the parent's responsibility to make sure that there will not in the +future exists a name identical to the realm name of the child unless it is +assigned to the same entity as the realm name. + +7.2. Principal Names + +As was the case for realm names, conventions are needed to ensure that all +agree on what information is implied by a principal name. The name-type +field that is part of the principal name indicates the kind of information +implied by the name. The name-type should be treated as a hint. Ignoring the +name type, no two names can be the same (i.e. at least one of the +components, or the realm, must be different). The following name types are +defined: + + name-type value meaning + + NT-UNKNOWN 0 Name type not known + NT-PRINCIPAL 1 General principal name (e.g. username, or DCE principal) + NT-SRV-INST 2 Service and other unique instance (krbtgt) + NT-SRV-HST 3 Service with host name as instance (telnet, rcommands) + NT-SRV-XHST 4 Service with slash-separated host name components + NT-UID 5 Unique ID + NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] + +When a name implies no information other than its uniqueness at a particular +time the name type PRINCIPAL should be used. The principal name type should + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +be used for users, and it might also be used for a unique server. If the +name is a unique machine generated ID that is guaranteed never to be +reassigned then the name type of UID should be used (note that it is +generally a bad idea to reassign names of any type since stale entries might +remain in access control lists). + +If the first component of a name identifies a service and the remaining +components identify an instance of the service in a server specified manner, +then the name type of SRV-INST should be used. An example of this name type +is the Kerberos ticket-granting service whose name has a first component of +krbtgt and a second component identifying the realm for which the ticket is +valid. + +If instance is a single component following the service name and the +instance identifies the host on which the server is running, then the name +type SRV-HST should be used. This type is typically used for Internet +services such as telnet and the Berkeley R commands. If the separate +components of the host name appear as successive components following the +name of the service, then the name type SRV-XHST should be used. This type +might be used to identify servers on hosts with X.500 names where the slash +(/) might otherwise be ambiguous. + +A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 +certificiate is translated into a Kerberos name. The encoding of the X.509 +name as a Kerberos principal shall conform to the encoding rules specified +in RFC 1779. + +A name type of UNKNOWN should be used when the form of the name is not +known. When comparing names, a name of type UNKNOWN will match principals +authenticated with names of any type. A principal authenticated with a name +of type UNKNOWN, however, will only match other names of type UNKNOWN. + +Names of any type with an initial component of 'krbtgt' are reserved for the +Kerberos ticket granting service. See section 8.2.3 for the form of such +names. + +7.2.1. Name of server principals + +The principal identifier for a server on a host will generally be composed +of two parts: (1) the realm of the KDC with which the server is registered, +and (2) a two-component name of type NT-SRV-HST if the host name is an +Internet domain name or a multi-component name of type NT-SRV-XHST if the +name of the host is of a form such as X.500 that allows slash (/) +separators. The first component of the two- or multi-component name will +identify the service and the latter components will identify the host. Where +the name of the host is not case sensitive (for example, with Internet +domain names) the name of the host must be lower case. If specified by the +application protocol for services such as telnet and the Berkeley R commands +which run with system privileges, the first component may be the string +'host' instead of a service specific identifier. When a host has an official +name and one or more aliases, the official name of the host must be used +when constructing the name of the server principal. + +8. Constants and other defined values + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +8.1. Host address types + +All negative values for the host address type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpretations. + +The values of the types for the following addresses are chosen to match the +defined address family constants in the Berkeley Standard Distributions of +Unix. They can be found in with symbolic names AF_xxx (where xxx is an +abbreviation of the address family name). + +Internet (IPv4) Addresses + +Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB +order. The type of IPv4 addresses is two (2). + +Internet (IPv6) Addresses + +IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The +type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The +following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: + + * the Unspecified Address + * the Loopback Address + * Link-Local addresses + +IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. + +CHAOSnet addresses + +CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. +The type of CHAOSnet addresses is five (5). + +ISO addresses + +ISO addresses are variable-length. The type of ISO addresses is seven (7). + +Xerox Network Services (XNS) addresses + +XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The +type of XNS addresses is six (6). + +AppleTalk Datagram Delivery Protocol (DDP) addresses + +AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit network +number. The first octet of the address is the node number; the remaining two +octets encode the network number in MSB order. The type of AppleTalk DDP +addresses is sixteen (16). + +DECnet Phase IV addresses + +DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The +type of DECnet Phase IV addresses is twelve (12). + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +8.2. KDC messages + +8.2.1. UDP/IP transport + +When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP +IP transport, the client shall send a UDP datagram containing only an +encoding of the request to port 88 (decimal) at the KDC's IP address; the +KDC will respond with a reply datagram containing only an encoding of the +reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at +the sender's IP address. Kerberos servers supporting IP transport must +accept UDP requests on port 88 (decimal). The response to a request made +through UDP/IP transport must also use UDP/IP transport. + +8.2.2. TCP/IP transport + +Kerberos servers (KDC's) must accept TCP requests on port 88 (decimal). When +the KRB_KDC_REQ message is sent to the KDC over a TCP stream, a new +connection will be established for each authentication exchange (request and +response). The KRB_KDC_REP or KRB_ERROR message will be returned to the +client on the same TCP stream that was established for the request. The +connection will be broken after the reply has been received (or upon +time-out). Care must be taken in managing TCP/IP connections with the KDC to +prevent denial of service attacks based on the number of TCP/IP connections +with the KDC that remain open. If multiple exchanges with the KDC are needed +for certain forms of preauthentication, multiple TCP connections will be +required. The response to a request made through TCP/IP transport must also +use TCP/IP transport. + +The first four octets of the TCP stream used to transmit the request request +will encode in network byte order the length of the request (KRB_KDC_REQ), +and the length will be followed by the request itself. The response will +similarly be preceeded by a 4 octet encoding in network byte order of the +length of the KRB_KDC_REP or the KRB_ERROR message and will be followed by +the KRB_KDC_REP or the KRB_ERROR response. + +8.2.3. OSI transport + +During authentication of an OSI client to an OSI server, the mutual +authentication of an OSI server to an OSI client, the transfer of +credentials from an OSI client to an OSI server, or during exchange of +private or integrity checked messages, Kerberos protocol messages may be +treated as opaque objects and the type of the authentication mechanism will +be: + +OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), security(5),kerberosv5(2)} + +Depending on the situation, the opaque object will be an authentication +header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message +(KRB_SAFE), a private message (KRB_PRIV), or a credentials message +(KRB_CRED). The opaque data contains an application code as specified in the +ASN.1 description for each message. The application code may be used by +Kerberos to determine the message type. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +8.2.3. Name of the TGS + +The principal identifier of the ticket-granting service shall be composed of +three parts: (1) the realm of the KDC issuing the TGS ticket (2) a two-part +name of type NT-SRV-INST, with the first part "krbtgt" and the second part +the name of the realm which will accept the ticket-granting ticket. For +example, a ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be +used to get tickets from the ATHENA.MIT.EDU KDC has a principal identifier +of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A +ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be used to get +tickets from the MIT.EDU realm has a principal identifier of +"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). + +8.3. Protocol constants and associated values + +The following tables list constants used in the protocol and defines their +meanings. + +Encryption type etype value block size minimum pad size confounder size +NULL 0 1 0 0 +des-cbc-crc 1 8 4 8 +des-cbc-md4 2 8 0 8 +des-cbc-md5 3 8 0 8 + 4 +des3-cbc-md5 5 8 0 8 + 6 +des3-cbc-sha1 7 8 0 8 +sign-dsa-generate 8 (pkinit) +encrypt-rsa-priv 9 (pkinit) +encrypt-rsa-pub 10 (pkinit) +rsa-pub-md5 11 (pkinit) +rsa-pub-sha1 12 (pkinit) +ENCTYPE_PK_CROSS 48 (reserved for pkcross) + 0x8003 + +Checksum type sumtype value checksum size +CRC32 1 4 +rsa-md4 2 16 +rsa-md4-des 3 24 +des-mac 4 16 +des-mac-k 5 8 +rsa-md4-des-k 6 16 +rsa-md5 7 16 +rsa-md5-des 8 24 +rsa-md5-des3 9 24 +hmac-sha1-des3 10 20 (I had this as 10, is it 12) + +padata type padata-type value + +PA-TGS-REQ 1 +PA-ENC-TIMESTAMP 2 +PA-PW-SALT 3 + 4 +PA-ENC-UNIX-TIME 5 + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +PA-SANDIA-SECUREID 6 +PA-SESAME 7 +PA-OSF-DCE 8 +PA-CYBERSAFE-SECUREID 9 +PA-AFS3-SALT 10 +PA-ETYPE-INFO 11 +SAM-CHALLENGE 12 (sam/otp) +SAM-RESPONSE 13 (sam/otp) +PA-PK-AS-REQ 14 (pkinit) +PA-PK-AS-REP 15 (pkinit) +PA-PK-AS-SIGN 16 (pkinit) +PA-PK-KEY-REQ 17 (pkinit) +PA-PK-KEY-REP 18 (pkinit) +PA-USE-SPECIFIED-KVNO 20 + +authorization data type ad-type value +AD-KDC-ISSUED 1 +AD-INTENDED-FOR-SERVER 2 +AD-INTENDED-FOR-APPLICATION-CLASS 3 +AD-IF-RELEVANT 4 +AD-OR 5 +AD-MANDATORY-TICKET-EXTENSIONS 6 +AD-IN-TICKET-EXTENSIONS 7 +reserved values 8-63 +OSF-DCE 64 +SESAME 65 + +Ticket Extension Types + +TE-TYPE-NULL 0 Null ticket extension +TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data + 2 TE-TYPE-PKCROSS-KDC (I have reservations) +TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket +TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp + 5 TE-TYPE-DEST-HOST (I have reservations) + +alternate authentication type method-type value +reserved values 0-63 +ATT-CHALLENGE-RESPONSE 64 + +transited encoding type tr-type value +DOMAIN-X500-COMPRESS 1 +reserved values all others + +Label Value Meaning or MIT code + +pvno 5 current Kerberos protocol version number + +message types + +KRB_AS_REQ 10 Request for initial authentication +KRB_AS_REP 11 Response to KRB_AS_REQ request +KRB_TGS_REQ 12 Request for authentication based on TGT +KRB_TGS_REP 13 Response to KRB_TGS_REQ request + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +KRB_AP_REQ 14 application request to server +KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL +KRB_SAFE 20 Safe (checksummed) application message +KRB_PRIV 21 Private (encrypted) application message +KRB_CRED 22 Private (encrypted) message to forward credentials +KRB_ERROR 30 Error response + +name types + +KRB_NT_UNKNOWN 0 Name type not known +KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for users +KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) +KRB_NT_SRV_HST 3 Service with host name as instance (telnet, rcommands) +KRB_NT_SRV_XHST 4 Service with host as remaining components +KRB_NT_UID 5 Unique ID +KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] + +error codes + +KDC_ERR_NONE 0 No error +KDC_ERR_NAME_EXP 1 Client's entry in database has expired +KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired +KDC_ERR_BAD_PVNO 3 Requested protocol version number not + supported +KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key +KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key +KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database +KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database +KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database +KDC_ERR_NULL_KEY 9 The client or server has a null key +KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating +KDC_ERR_NEVER_VALID 11 Requested start time is later than end time +KDC_ERR_POLICY 12 KDC policy rejects request +KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option +KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type +KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type +KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type +KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type +KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked +KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked +KDC_ERR_TGT_REVOKED 20 TGT has been revoked +KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later +KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later +KDC_ERR_KEY_EXPIRED 23 Password has expired - change password + to reset +KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid +KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired [40] +KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match +KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user only +KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path +KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed +KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired +KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid +KRB_AP_ERR_REPEAT 34 Request is a replay +KRB_AP_ERR_NOT_US 35 The ticket isn't for us +KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +KRB_AP_ERR_SKEW 37 Clock skew too great +KRB_AP_ERR_BADADDR 38 Incorrect net address +KRB_AP_ERR_BADVERSION 39 Protocol version mismatch +KRB_AP_ERR_MSG_TYPE 40 Invalid msg type +KRB_AP_ERR_MODIFIED 41 Message stream modified +KRB_AP_ERR_BADORDER 42 Message out of order +KRB_AP_ERR_BADKEYVER 44 Specified version of key is not available +KRB_AP_ERR_NOKEY 45 Service key not available +KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed +KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction +KRB_AP_ERR_METHOD 48 Alternative authentication method required +KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message +KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in message +KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path +KRB_ERR_GENERIC 60 Generic error (description in e-text) +KRB_ERR_FIELD_TOOLONG 61 Field is too long for this implementation +KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) +KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) +KDC_ERROR_INVALID_SIG 64 (pkinit) +KDC_ERR_KEY_TOO_WEAK 65 (pkinit) +KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) + +9. Interoperability requirements + +Version 5 of the Kerberos protocol supports a myriad of options. Among these +are multiple encryption and checksum types, alternative encoding schemes for +the transited field, optional mechanisms for pre-authentication, the +handling of tickets with no addresses, options for mutual authentication, +user to user authentication, support for proxies, forwarding, postdating, +and renewing tickets, the format of realm names, and the handling of +authorization data. + +In order to ensure the interoperability of realms, it is necessary to define +a minimal configuration which must be supported by all implementations. This +minimal configuration is subject to change as technology does. For example, +if at some later date it is discovered that one of the required encryption +or checksum algorithms is not secure, it will be replaced. + +9.1. Specification 2 + +This section defines the second specification of these options. +Implementations which are configured in this way can be said to support +Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may +be found in RFC1510. + +Transport + +TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance +to specification 2. Kerberos clients claiming conformance to specification 2 +must support UDP/IP transport for messages with the KDC and may support +TCP/IP transport. + +Encryption and checksum methods + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +The following encryption and checksum mechanisms must be supported. +Implementations may support other mechanisms as well, but the additional +mechanisms may only be used when communicating with principals known to also +support them: This list is to be determined. + +Encryption: DES-CBC-MD5 +Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 + +Realm Names + +All implementations must understand hierarchical realms in both the Internet +Domain and the X.500 style. When a ticket granting ticket for an unknown +realm is requested, the KDC must be able to determine the names of the +intermediate realms between the KDCs realm and the requested realm. + +Transited field encoding + +DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. +Alternative encodings may be supported, but they may be used only when that +encoding is supported by ALL intermediate realms. + +Pre-authentication methods + +The TGS-REQ method must be supported. The TGS-REQ method is not used on the +initial request. The PA-ENC-TIMESTAMP method must be supported by clients +but whether it is enabled by default may be determined on a realm by realm +basis. If not used in the initial request and the error +KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an +acceptable method, the client should retry the initial request using the +PA-ENC-TIMESTAMP preauthentication method. Servers need not support the +PA-ENC-TIMESTAMP method, but if not supported the server should ignore the +presence of PA-ENC-TIMESTAMP pre-authentication in a request. + +Mutual authentication + +Mutual authentication (via the KRB_AP_REP message) must be supported. + +Ticket addresses and flags + +All KDC's must pass on tickets that carry no addresses (i.e. if a TGT +contains no addresses, the KDC will return derivative tickets), but each +realm may set its own policy for issuing such tickets, and each application +server will set its own policy with respect to accepting them. + +Proxies and forwarded tickets must be supported. Individual realms and +application servers can set their own policy on when such tickets will be +accepted. + +All implementations must recognize renewable and postdated tickets, but need +not actually implement them. If these options are not supported, the +starttime and endtime in the ticket shall specify a ticket's entire useful +life. When a postdated ticket is decoded by a server, all implementations +shall make the presence of the postdated flag visible to the calling server. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +User-to-user authentication + +Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC option) +must be provided by implementations, but individual realms may decide as a +matter of policy to reject such requests on a per-principal or realm-wide +basis. + +Authorization data + +Implementations must pass all authorization data subfields from +ticket-granting tickets to any derivative tickets unless directed to +suppress a subfield as part of the definition of that registered subfield +type (it is never incorrect to pass on a subfield, and no registered +subfield types presently specify suppression at the KDC). + +Implementations must make the contents of any authorization data subfields +available to the server when a ticket is used. Implementations are not +required to allow clients to specify the contents of the authorization data +fields. + +9.2. Recommended KDC values + +Following is a list of recommended values for a KDC implementation, based on +the list of suggested configuration constants (see section 4.4). + +minimum lifetime 5 minutes +maximum renewable lifetime 1 week +maximum ticket lifetime 1 day +empty addresses only when suitable restrictions appear + in authorization data +proxiable, etc. Allowed. + +10. REFERENCES + +[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- + cation Service for Computer Networks," IEEE Communica- + tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). + +[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. + Saltzer, Section E.2.1: Kerberos Authentication and + Authorization System, M.I.T. Project Athena, Cambridge, + Massachusetts (December 21, 1987). + +[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- + beros: An Authentication Service for Open Network Sys- + tems," pp. 191-202 in Usenix Conference Proceedings, + Dallas, Texas (February, 1988). + +[NS78] Roger M. Needham and Michael D. Schroeder, "Using + Encryption for Authentication in Large Networks of Com- + puters," Communications of the ACM, Vol. 21(12), + pp. 993-999 (December, 1978). + +[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + stamps in Key Distribution Protocols," Communications + of the ACM, Vol. 24(8), pp. 533-536 (August 1981). + +[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, + "The Evolution of the Kerberos Authentication Service," + in an IEEE Computer Society Text soon to be published + (June 1992). + +[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and + Accounting for Distributed Systems," in Proceedings of + the 13th International Conference on Distributed Com- + puting Systems, Pittsburgh, PA (May, 1993). + +[DS90] Don Davis and Ralph Swick, "Workstation Services and + Kerberos Authentication at Project Athena," Technical + Memorandum TM-424, MIT Laboratory for Computer Science + (February 1990). + +[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- + merfeld, and K. Raeburn, Section E.1: Service Manage- + ment System, M.I.T. Project Athena, Cambridge, Mas- + sachusetts (1987). + +[X509-88] CCITT, Recommendation X.509: The Directory Authentica- + tion Framework, December 1988. + +[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password + Guessing Attacks, Open Software Foundation DCE Request + for Comments 26 (December 1992). + +[DES77] National Bureau of Standards, U.S. Department of Com- + merce, "Data Encryption Standard," Federal Information + Processing Standards Publication 46, Washington, DC + (1977). + +[DESM80] National Bureau of Standards, U.S. Department of Com- + merce, "DES Modes of Operation," Federal Information + Processing Standards Publication 81, Springfield, VA + (December 1980). + +[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message + Integrity in Cryptographic Protocols," in Proceedings + of the IEEE Symposium on Research in Security and + Privacy, Oakland, California (May 1992). + +[IS3309] International Organization for Standardization, "ISO + Information Processing Systems - Data Communication - + High-Level Data Link Control Procedure - Frame Struc- + ture," IS 3309 (October 1984). 3rd Edition. + +[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC + 1320, MIT Laboratory for Computer Science (April + 1992). + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC + 1321, MIT Laboratory for Computer Science (April + 1992). + +[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication," Working Draft + draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). + +A. Pseudo-code for protocol processing + +This appendix provides pseudo-code describing how the messages are to be +constructed and interpreted by clients and servers. + +A.1. KRB_AS_REQ generation + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_AS_REQ */ + + if(pa_enc_timestamp_required) then + request.padata.padata-type = PA-ENC-TIMESTAMP; + get system_time; + padata-body.patimestamp,pausec = system_time; + encrypt padata-body into request.padata.padata-value + using client.key; /* derived from password */ + endif + + body.kdc-options := users's preferences; + body.cname := user's name; + body.realm := user's realm; + body.sname := service's name; /* usually "krbtgt", "localrealm" */ + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + omit body.enc-authorization-data; + request.req-body := body; + + kerberos := lookup(name of local kerberos server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + retry or use alternate server; + endif + +A.2. KRB_AS_REQ verification and KRB_AS_REP generation + + decode message into req; + + client := lookup(req.cname,req.realm); + server := lookup(req.sname,req.realm); + + get system_time; + kdc_time := system_time.seconds; + + if (!client) then + /* no client in Database */ + error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); + endif + if (!server) then + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + + if(client.pa_enc_timestamp_required and + pa_enc_timestamp not present) then + error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); + endif + + if(pa_enc_timestamp present) then + decrypt req.padata-value into decrypted_enc_timestamp + using client.key; + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + if(decrypted_enc_timestamp is not within allowable skew) then + error_out(KDC_ERR_PREAUTH_FAILED); + endif + if(decrypted_enc_timestamp and usec is replay) + error_out(KDC_ERR_PREAUTH_FAILED); + endif + add decrypted_enc_timestamp and usec to replay cache; + endif + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := req.srealm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + if (req.kdc-options.FORWARDABLE is set) then + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.PROXIABLE is set) then + set new_tkt.flags.PROXIABLE; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + set new_tkt.flags.MAY-POSTDATE; + endif + if ((req.kdc-options.RENEW is set) or + (req.kdc-options.VALIDATE is set) or + (req.kdc-options.PROXY is set) or + (req.kdc-options.FORWARDED is set) or + (req.kdc-options.ENC-TKT-IN-SKEY is set)) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.session := random_session_key(); + new_tkt.cname := req.cname; + new_tkt.crealm := req.crealm; + new_tkt.transited := empty_transited_field(); + + new_tkt.authtime := kdc_time; + + if (req.kdc-options.POSTDATED is set) then + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + new_tkt.starttime := req.from; + else + omit new_tkt.starttime; /* treated as authtime when omitted */ + endif + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till)) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := req.till; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if (req.kdc-options.RENEWABLE is set) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm); + else + omit new_tkt.renew-till; /* only present if RENEWABLE */ + endif + + if (req.addresses) then + new_tkt.caddr := req.addresses; + else + omit new_tkt.caddr; + endif + + new_tkt.authorization_data := empty_authorization_data(); + + encode to-be-encrypted part of ticket into OCTET STRING; + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + + /* Start processing the response */ + + resp.pvno := 5; + resp.msg-type := KRB_AS_REP; + resp.cname := req.cname; + resp.crealm := req.realm; + resp.ticket := new_tkt; + + resp.key := new_tkt.session; + resp.last-req := fetch_last_request_info(client); + resp.nonce := req.nonce; + resp.key-expiration := client.expiration; + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + resp.realm := new_tkt.realm; + resp.sname := new_tkt.sname; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + resp.caddr := new_tkt.caddr; + + encode body of reply into OCTET STRING; + + resp.enc-part := encrypt OCTET STRING + using use_etype, client.key, client.p_kvno; + send(resp); + +A.3. KRB_AS_REP verification + + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then + set pa_enc_timestamp_required; + goto KRB_AS_REQ; + endif + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key */ + /* from the response immediately */ + + key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, + resp.padata); + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and key; + zero(key); + + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + if near(resp.princ_exp) then + print(warning message); + endif + save_for_later(ticket,session,client,server,times,flags); + +A.4. KRB_AS_REP and KRB_TGS_REP common checks + + if (decryption_error() or + (req.cname != resp.cname) or + (req.realm != resp.crealm) or + (req.sname != resp.sname) or + (req.realm != resp.realm) or + (req.nonce != resp.nonce) or + (req.addresses != resp.caddr)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + /* make sure no flags are set that shouldn't be, and that all that */ + /* should be are set */ + if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.from = 0) and + (resp.starttime is not within allowable skew)) then + destroy resp.key; + return KRB_AP_ERR_SKEW; + endif + if ((req.from != 0) and (req.from != resp.starttime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.till != 0) and (resp.endtime > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (req.rtime != 0) and (resp.renew-till > req.rtime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.kdc-options.RENEWABLE-OK is set) and + (resp.flags.RENEWABLE) and + (req.till != 0) and + (resp.renew-till > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + +A.5. KRB_TGS_REQ generation + + /* Note that make_application_request might have to recursivly */ + /* call this routine to get the appropriate ticket-granting ticket */ + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_TGS_REQ */ + + body.kdc-options := users's preferences; + /* If the TGT is not for the realm of the end-server */ + /* then the sname will be for a TGT for the end-realm */ + /* and the realm of the requested ticket (body.realm) */ + /* will be that of the TGS to which the TGT we are */ + /* sending applies */ + body.sname := service's name; + body.realm := service's realm; + + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + + body.enc-authorization-data := user-supplied data; + if (body.kdc-options.ENC-TKT-IN-SKEY) then + body.additional-tickets_ticket := second TGT; + endif + + request.req-body := body; + check := generate_checksum (req.body,checksumtype); + + request.padata[0].padata-type := PA-TGS-REQ; + request.padata[0].padata-value := create a KRB_AP_REQ using + the TGT and checksum + + /* add in any other padata as required/supplied */ + + kerberos := lookup(name of local kerberose server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation + + /* note that reading the application request requires first + determining the server for which a ticket was issued, and choosing the + correct key for decryption. The name of the server appears in the + plaintext part of the ticket. */ + + if (no KRB_AP_REQ in req.padata) then + error_out(KDC_ERR_PADATA_TYPE_NOSUPP); + endif + verify KRB_AP_REQ in req.padata; + + /* Note that the realm in which the Kerberos server is operating is + determined by the instance from the ticket-granting ticket. The realm + in the ticket-granting ticket is the realm under which the ticket + granting ticket was issued. It is possible for a single Kerberos + server to support more than one realm. */ + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + auth_hdr := KRB_AP_REQ; + tgt := auth_hdr.ticket; + + if (tgt.sname is not a TGT for local realm and is not req.sname) then + error_out(KRB_AP_ERR_NOT_US); + + realm := realm_tgt_is_for(tgt); + + decode remainder of request; + + if (auth_hdr.authenticator.cksum is missing) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + if (auth_hdr.authenticator.cksum type is not supported) then + error_out(KDC_ERR_SUMTYPE_NOSUPP); + endif + if (auth_hdr.authenticator.cksum is not both collision-proof and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + set computed_checksum := checksum(req); + if (computed_checksum != auth_hdr.authenticatory.cksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + server := lookup(req.sname,realm); + + if (!server) then + if (is_foreign_tgt_name(req.sname)) then + server := best_intermediate_tgs(req.sname); + else + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + endif + + session := generate_random_session_key(); + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := realm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + new_tkt.caddr := tgt.caddr; + resp.caddr := NULL; /* We only include this if they change */ + if (req.kdc-options.FORWARDABLE is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.FORWARDED is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDED; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + if (tgt.flags.FORWARDED is set) then + set new_tkt.flags.FORWARDED; + endif + + if (req.kdc-options.PROXIABLE is set) then + if (tgt.flags.PROXIABLE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.PROXY is set) then + if (tgt.flags.PROXIABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXY; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + if (tgt.flags.MAY-POSTDATE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.MAY-POSTDATE; + endif + if (req.kdc-options.POSTDATED is set) then + if (tgt.flags.MAY-POSTDATE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + new_tkt.starttime := req.from; + endif + + if (req.kdc-options.VALIDATE is set) then + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + if (tgt.flags.INVALID is reset) then + error_out(KDC_ERR_POLICY); + endif + if (tgt.starttime > kdc_time) then + error_out(KRB_AP_ERR_NYV); + endif + if (check_hot_list(tgt)) then + error_out(KRB_AP_ERR_REPEAT); + endif + tkt := tgt; + reset new_tkt.flags.INVALID; + endif + + if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, + and those already processed) is set) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.authtime := tgt.authtime; + + if (req.kdc-options.RENEW is set) then + /* Note that if the endtime has already passed, the ticket would */ + /* have been rejected in the initial authentication stage, so */ + /* there is no need to check again here */ + if (tgt.flags.RENEWABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + if (tgt.renew-till < kdc_time) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + tkt := tgt; + new_tkt.starttime := kdc_time; + old_life := tgt.endttime - tgt.starttime; + new_tkt.endtime := min(tgt.renew-till, + new_tkt.starttime + old_life); + else + new_tkt.starttime := kdc_time; + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm, + tgt.endtime); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till) and + (tgt.flags.RENEWABLE is set) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := min(req.till, tgt.renew-till); + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + endif + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (tgt.flags.RENEWABLE is set)) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm, + tgt.renew-till); + else + new_tkt.renew-till := OMIT; /* leave the renew-till field out */ + endif + if (req.enc-authorization-data is present) then + decrypt req.enc-authorization-data into decrypted_authorization_data + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + endif + new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data + + decrypted_authorization_data; + + new_tkt.key := session; + new_tkt.crealm := tgt.crealm; + new_tkt.cname := req.auth_hdr.ticket.cname; + + if (realm_tgt_is_for(tgt) := tgt.realm) then + /* tgt issued by local realm */ + new_tkt.transited := tgt.transited; + else + /* was issued for this realm by some other realm */ + if (tgt.transited.tr-type not supported) then + error_out(KDC_ERR_TRTYPE_NOSUPP); + endif + new_tkt.transited := compress_transited(tgt.transited + tgt.realm) + /* Don't check tranited field if TGT for foreign realm, + * or requested not to check */ + if (is_not_foreign_tgt_name(new_tkt.server) + && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then + /* Check it, so end-server does not have to + * but don't fail, end-server may still accept it */ + if (check_transited_field(new_tkt.transited) == OK) + set new_tkt.flags.TRANSITED-POLICY-CHECKED; + endif + endif + endif + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + encode encrypted part of new_tkt into OCTET STRING; + if (req.kdc-options.ENC-TKT-IN-SKEY is set) then + if (server not specified) then + server = req.second_ticket.client; + endif + if ((req.second_ticket is not a TGT) or + (req.second_ticket.client != server)) then + error_out(KDC_ERR_POLICY); + endif + + new_tkt.enc-part := encrypt OCTET STRING using + using etype_for_key(second-ticket.key), second-ticket.key; + else + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + endif + + resp.pvno := 5; + resp.msg-type := KRB_TGS_REP; + resp.crealm := tgt.crealm; + resp.cname := tgt.cname; + resp.ticket := new_tkt; + + resp.key := session; + resp.nonce := req.nonce; + resp.last-req := fetch_last_request_info(client); + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + omit resp.key-expiration; + + resp.sname := new_tkt.sname; + resp.realm := new_tkt.realm; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + encode body of reply into OCTET STRING; + + if (req.padata.authenticator.subkey) + resp.enc-part := encrypt OCTET STRING using use_etype, + req.padata.authenticator.subkey; + else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; + + send(resp); + +A.7. KRB_TGS_REP verification + + decode response into resp; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + if (resp.msg-type = KRB_ERROR) then + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key from + the response immediately */ + + if (req.padata.authenticator.subkey) + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and subkey; + else unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and tgt's session key; + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + check authorization_data as necessary; + save_for_later(ticket,session,client,server,times,flags); + +A.8. Authenticator generation + + body.authenticator-vno := authenticator vno; /* = 5 */ + body.cname, body.crealm := client name; + if (supplying checksum) then + body.cksum := checksum; + endif + get system_time; + body.ctime, body.cusec := system_time; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + +A.9. KRB_AP_REQ generation + + obtain ticket and session_key from cache; + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REQ */ + + if (desired(MUTUAL_AUTHENTICATION)) then + set packet.ap-options.MUTUAL-REQUIRED; + else + reset packet.ap-options.MUTUAL-REQUIRED; + endif + if (using session key for ticket) then + set packet.ap-options.USE-SESSION-KEY; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + else + reset packet.ap-options.USE-SESSION-KEY; + endif + packet.ticket := ticket; /* ticket */ + generate authenticator; + encode authenticator into OCTET STRING; + encrypt OCTET STRING into packet.authenticator using session_key; + +A.10. KRB_AP_REQ verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REQ) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.ticket.tkt_vno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.ap_options.USE-SESSION-KEY is set) then + retrieve session key from ticket-granting ticket for + packet.ticket.{sname,srealm,enc-part.etype}; + else + retrieve service key for + packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; + endif + if (no_key_available) then + if (cannot_find_specified_skvno) then + error_out(KRB_AP_ERR_BADKEYVER); + else + error_out(KRB_AP_ERR_NOKEY); + endif + endif + decrypt packet.ticket.enc-part into decr_ticket using retrieved key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + decrypt packet.authenticator into decr_authenticator + using decr_ticket.key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (decr_authenticator.{cname,crealm} != + decr_ticket.{cname,crealm}) then + error_out(KRB_AP_ERR_BADMATCH); + endif + if (decr_ticket.caddr is present) then + if (sender_address(packet) is not in decr_ticket.caddr) then + error_out(KRB_AP_ERR_BADADDR); + endif + elseif (application requires addresses) then + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(decr_authenticator.ctime, + decr_authenticator.cusec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then + error_out(KRB_AP_ERR_REPEAT); + endif + save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); + get system_time; + if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or + (decr_ticket.flags.INVALID is set)) then + /* it hasn't yet become valid */ + error_out(KRB_AP_ERR_TKT_NYV); + endif + if (system_time-decr_ticket.endtime > CLOCK_SKEW) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + if (decr_ticket.transited) then + /* caller may ignore the TRANSITED-POLICY-CHECKED and do + * check anyway */ + if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then + if (check_transited_field(decr_ticket.transited) then + error_out(KDC_AP_PATH_NOT_ACCPETED); + endif + endif + endif + /* caller must check decr_ticket.flags for any pertinent details */ + return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); + +A.11. KRB_AP_REP generation + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REP */ + + body.ctime := packet.ctime; + body.cusec := packet.cusec; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part; + +A.12. KRB_AP_REP verification + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REP) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + cleartext := decrypt(packet.enc-part) using ticket's session key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (cleartext.ctime != authenticator.ctime) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.cusec != authenticator.cusec) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.subkey is present) then + save cleartext.subkey for future use; + endif + if (cleartext.seq-number is present) then + save cleartext.seq-number for future verifications; + endif + return(AUTHENTICATION_SUCCEEDED); + +A.13. KRB_SAFE generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_SAFE */ + + body.user-data := buffer; /* DATA */ + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + checksum.cksumtype := checksum type; + compute checksum over body; + checksum.checksum := checksum value; /* checksum.checksum */ + packet.cksum := checksum; + packet.safe-body := body; + +A.14. KRB_SAFE verification + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_SAFE) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.checksum.cksumtype is not both collision-proof and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (safe_priv_common_checks_ok(packet)) then + set computed_checksum := checksum(packet.body); + if (computed_checksum != packet.checksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + return (packet, PACKET_IS_GENUINE); + else + return common_checks_error; + endif + +A.15. KRB_SAFE and KRB_PRIV common checks + + if (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (((packet.timestamp is present) and + (not in_clock_skew(packet.timestamp,packet.usec))) or + (packet.timestamp is not present and timestamp expected)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + + if (((packet.seq-number is present) and + ((not in_sequence(packet.seq-number)))) or + (packet.seq-number is not present and sequence expected)) then + error_out(KRB_AP_ERR_BADORDER); + endif + if (packet.timestamp not present and packet.seq-number not present) + then + error_out(KRB_AP_ERR_MODIFIED); + endif + + save_identifier(packet.{timestamp,usec,s-address}, + sender_principal(packet)); + + return PACKET_IS_OK; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +A.16. KRB_PRIV generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_PRIV */ + + packet.enc-part.etype := encryption type; + + body.user-data := buffer; + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher; + +A.17. KRB_PRIV verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_PRIV) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + + if (safe_priv_common_checks_ok(cleartext)) then + return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); + else + return common_checks_error; + endif + +A.18. KRB_CRED generation + + invoke KRB_TGS; /* obtain tickets to be provided to peer */ + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_CRED */ + + for (tickets[n] in tickets to be forwarded) do + packet.tickets[n] = tickets[n].ticket; + done + + packet.enc-part.etype := encryption type; + + for (ticket[n] in tickets to be forwarded) do + body.ticket-info[n].key = tickets[n].session; + body.ticket-info[n].prealm = tickets[n].crealm; + body.ticket-info[n].pname = tickets[n].cname; + body.ticket-info[n].flags = tickets[n].flags; + body.ticket-info[n].authtime = tickets[n].authtime; + body.ticket-info[n].starttime = tickets[n].starttime; + body.ticket-info[n].endtime = tickets[n].endtime; + body.ticket-info[n].renew-till = tickets[n].renew-till; + body.ticket-info[n].srealm = tickets[n].srealm; + body.ticket-info[n].sname = tickets[n].sname; + body.ticket-info[n].caddr = tickets[n].caddr; + done + + get system_time; + body.timestamp, body.usec := system_time; + + if (using nonce) then + body.nonce := nonce; + endif + + if (using s-address) then + body.s-address := sender host addresses; + endif + if (limited recipients) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher + using negotiated encryption key; + +A.19. KRB_CRED verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_CRED) then + error_out(KRB_AP_ERR_MSG_TYPE); + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if ((packet.r-address is present or required) and + (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(packet.timestamp,packet.usec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + if (packet.nonce is required or present) and + (packet.nonce != expected-nonce) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + for (ticket[n] in tickets that were forwarded) do + save_for_later(ticket[n],key[n],principal[n], + server[n],times[n],flags[n]); + return + +A.20. KRB_ERROR generation + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_ERROR */ + + get system_time; + packet.stime, packet.susec := system_time; + packet.realm, packet.sname := server name; + + if (client time available) then + packet.ctime, packet.cusec := client_time; + endif + packet.error-code := error code; + if (client name available) then + packet.cname, packet.crealm := client name; + endif + if (error text available) then + packet.e-text := error text; + endif + if (error data available) then + packet.e-data := error data; + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + endif + +B. Definition of common authorization data elements + +This appendix contains the definitions of common authorization data +elements. These common authorization data elements are recursivly defined, +meaning the ad-data for these types will itself contain a sequence of +authorization data whose interpretation is affected by the encapsulating +element. Depending on the meaning of the encapsulating element, the +encapsulated elements may be ignored, might be interpreted as issued +directly by the KDC, or they might be stored in a separate plaintext part of +the ticket. The types of the encapsulating elements are specified as part of +the Kerberos specification ebcause the behavior based on these values should +be understood across implementations whereas other elements need only be +understood by the applications which they affect. + +In the definitions that follow, the value of the ad-type for the element +will be specified in the subsection number, and the value of the ad-data +will be as shown in the ASN.1 structure that follows the subsection heading. + +B.1. KDC Issued + +AD-KDCIssued SEQUENCE { + ad-checksum[0] Checksum, + i-realm[1] Realm OPTIONAL, + i-sname[2] PrincipalName OPTIONAL, + elements[3] AuthorizationData. +} + +ad-checksum + A checksum over the elements field using a cryptographic checksum + method that is identical to the checksum used to protect the ticket + itself (i.e. using the same hash function and the same encryption + algorithm used to encrypt the ticket) and using a key derived from the + same key used to protect the ticket. +i-realm, i-sname + The name of the issuing principal if different from the KDC itself. + This field would be used when the KDC can verify the authenticity of + elements signed by the issuing principal and it allows this KDC to + notify the application server of the validity of those elements. +elements + A sequence of authorization data elements issued by the KDC. + +The KDC-issued ad-data field is intended to provide a means for Kerberos +principal credentials to embed within themselves privilege attributes and +other mechanisms for positive authorization, amplifying the priveleges of +the principal beyond what can be done using a credentials without such an +a-data element. + +This can not be provided without this element because the definition of the +authorization-data field allows elements to be added at will by the bearer +of a TGT at the time that they request service tickets and elements may also +be added to a delegated ticket by inclusion in the authenticator. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +For KDC-issued elements this is prevented because the elements are signed by +the KDC by including a checksum encrypted using the server's key (the same +key used to encrypt the ticket - or a key derived from that key). Elements +encapsulated with in the KDC-issued element will be ignored by the +application server if this "signature" is not present. Further, elements +encapsulated within this element from a ticket granting ticket may be +interpreted by the KDC, and used as a basis according to policy for +including new signed elements within derivative tickets, but they will not +be copied to a derivative ticket directly. If they are copied directly to a +derivative ticket by a KDC that is not aware of this element, the signature +will not be correct for the application ticket elements, and the field will +be ignored by the application server. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + +B.2. Intended for server + +AD-INTENDED-FOR-SERVER SEQUENCE { + intended-server[0] SEQUENCE OF PrincipalName + elements[1] AuthorizationData +} + +AD elements encapsulated within the intended-for-server element may be +ignored if the application server is not in the list of principal names of +intended servers. Further, a KDC issuing a ticket for an application server +can remove this element if the application server is not in the list of +intended servers. + +Application servers should check for their principal name in the +intended-server field of this element. If their principal name is not found, +this element should be ignored. If found, then the encapsulated elements +should be evaluated in the same manner as if they were present in the top +level authorization data field. Applications and application servers that do +not implement this element should reject tickets that contain authorization +data elements of this type. + +B.3. Intended for application class + +AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] +SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements +encapsulated within the intended-for-application-class element may be +ignored if the application server is not in one of the named classes of +application servers. Examples of application server classes include +"FILESYSTEM", and other kinds of servers. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + +B.4. If relevant + +AD-IF-RELEVANT AuthorizationData + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +AD elements encapsulated within the if-relevant element are intended for +interpretation only by application servers that understand the particular +ad-type of the embedded element. Application servers that do not understand +the type of an element embedded within the if-relevant element may ignore +the uninterpretable element. This element promotes interoperability across +implementations which may have local extensions for authorization. + +B.5. And-Or + +AD-AND-OR SEQUENCE { + condition-count[0] INTEGER, + elements[1] AuthorizationData +} + +When restrictive AD elements encapsulated within the and-or element are +encountered, only the number specified in condition-count of the +encapsulated conditions must be met in order to satisfy this element. This +element may be used to implement an "or" operation by setting the +condition-count field to 1, and it may specify an "and" operation by setting +the condition count to the number of embedded elements. Application servers +that do not implement this element must reject tickets that contain +authorization data elements of this type. + +B.6. Mandatory ticket extensions + +AD-Mandatory-Ticket-Extensions Checksum + +An authorization data element of type mandatory-ticket-extensions specifies +a collision-proof checksum using the same has angorithm used to protect the +integrity of the ticket itself. This checksum will be calculated over the +entire extensions field. If there are more than one extension, all will be +covered by the checksum. This restriction indicates that the ticket should +not be accepted if the checksum does not match that calculated over the +ticket extensions. Application servers that do not implement this element +must reject tickets that contain authorization data elements of this type. + +B.7. Authorization Data in ticket extensions + +AD-IN-Ticket-Extensions Checksum + +An authorization data element of type in-ticket-extensions specifies a +collision-proof checksum using the same has angorithm used to protect the +integrity of the ticket itself. This checksum is calculated over a separate +external AuthorizationData field carried in the ticket extensions. +Application servers that do not implement this element must reject tickets +that contain authorization data elements of this type. Application servers +that do implement this element will search the ticket extensions for +authorization data fields, calculate the specified checksum over each +authorization data field and look for one matching the checksum in this +in-ticket-extensions element. If not found, then the ticket must be +rejected. If found, the corresponding authorization data elements will be +interpreted in the same manner as if they were contained in the top level +authorization data field. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +Note that if multiple external authorization data fields are present in a +ticket, each will have a corresponding element of type in-ticket-extensions +in the top level authorization data field, and the external entries will be +linked to the corresponding element by their checksums. + +C. Definition of common ticket extensions + +This appendix contains the definitions of common ticket extensions. Support +for these extensions is optional. However, certain extensions have +associated authorization data elements that may require rejection of a +ticket containing an extension by application servers that do not implement +the particular extension. Other extensions have been defined beyond those +described in this specification. Such extensions are described elswhere and +for some of those extensions the reserved number may be found in the list of +constants. + +It is known that older versions of Kerberos did not support this field, and +that some clients will strip this field from a ticket when they parse and +then reassemble a ticket as it is passed to the application servers. The +presence of the extension will not break such clients, but any functionaly +dependent on the extensions will not work when such tickets are handled by +old clients. In such situations, some implementation may use alternate +methods to transmit the information in the extensions field. + +C.1. Null ticket extension + +TE-NullExtension OctetString -- The empty Octet String + +The te-data field in the null ticket extension is an octet string of lenght +zero. This extension may be included in a ticket granting ticket so that the +KDC can determine on presentation of the ticket granting ticket whether the +client software will strip the extensions field. + +C.2. External Authorization Data + +TE-ExternalAuthorizationData AuthorizationData + +The te-data field in the external authorization data ticket extension is +field of type AuthorizationData containing one or more authorization data +elements. If present, a corresponding authorization data element will be +present in the primary authorization data for the ticket and that element +will contain a checksum of the external authorization data ticket extension. +---------------------------------------------------------------------------- +[TM] Project Athena, Athena, and Kerberos are trademarks of the +Massachusetts Institute of Technology (MIT). No commercial use of these +trademarks may be made without prior written permission of MIT. + +[1] Note, however, that many applications use Kerberos' functions only upon +the initiation of a stream-based network connection. Unless an application +subsequently provides integrity protection for the data stream, the identity +verification applies only to the initiation of the connection, and does not +guarantee that subsequent messages on the connection originate from the same +principal. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +[2] Secret and private are often used interchangeably in the literature. In +our usage, it takes two (or more) to share a secret, thus a shared DES key +is a secret key. Something is only private when no one but its owner knows +it. Thus, in public key cryptosystems, one has a public and a private key. + +[3] Of course, with appropriate permission the client could arrange +registration of a separately-named prin- cipal in a remote realm, and engage +in normal exchanges with that realm's services. However, for even small +numbers of clients this becomes cumbersome, and more automatic methods as +described here are necessary. + +[4] Though it is permissible to request or issue tick- ets with no network +addresses specified. + +[5] The password-changing request must not be honored unless the requester +can provide the old password (the user's current secret key). Otherwise, it +would be possible for someone to walk up to an unattended ses- sion and +change another user's password. + +[6] To authenticate a user logging on to a local system, the credentials +obtained in the AS exchange may first be used in a TGS exchange to obtain +credentials for a local server. Those credentials must then be verified by a +local server through successful completion of the Client/Server exchange. + +[7] "Random" means that, among other things, it should be impossible to +guess the next session key based on knowledge of past session keys. This can +only be achieved in a pseudo-random number generator if it is based on +cryptographic principles. It is more desirable to use a truly random number +generator, such as one based on measurements of random physical phenomena. + +[8] Tickets contain both an encrypted and unencrypted portion, so cleartext +here refers to the entire unit, which can be copied from one message and +replayed in another without any cryptographic skill. + +[9] Note that this can make applications based on unreliable transports +difficult to code correctly. If the transport might deliver duplicated +messages, either a new authenticator must be generated for each retry, or +the application server must match requests and replies and replay the first +reply in response to a detected duplicate. + +[10] This is used for user-to-user authentication as described in [8]. + +[11] Note that the rejection here is restricted to authenticators from the +same principal to the same server. Other client principals communicating +with the same server principal should not be have their authenticators +rejected if the time and microsecond fields happen to match some other +client's authenticator. + +[12] In the Kerberos version 4 protocol, the timestamp in the reply was the +client's timestamp plus one. This is not necessary in version 5 because +version 5 messages are formatted in such a way that it is not possible to +create the reply by judicious message surgery (even in encrypted form) +without knowledge of the appropriate encryption keys. + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + + +[13] Note that for encrypting the KRB_AP_REP message, the sub-session key is +not used, even if present in the Authenticator. + +[14] Implementations of the protocol may wish to provide routines to choose +subkeys based on session keys and random numbers and to generate a +negotiated key to be returned in the KRB_AP_REP message. + +[15]This can be accomplished in several ways. It might be known beforehand +(since the realm is part of the principal identifier), it might be stored in +a nameserver, or it might be obtained from a configura- tion file. If the +realm to be used is obtained from a nameserver, there is a danger of being +spoofed if the nameservice providing the realm name is not authenti- cated. +This might result in the use of a realm which has been compromised, and +would result in an attacker's ability to compromise the authentication of +the application server to the client. + +[16] If the client selects a sub-session key, care must be taken to ensure +the randomness of the selected sub- session key. One approach would be to +generate a random number and XOR it with the session key from the +ticket-granting ticket. + +[17] This allows easy implementation of user-to-user authentication [8], +which uses ticket-granting ticket session keys in lieu of secret server keys +in situa- tions where such secret keys could be easily comprom- ised. + +[18] For the purpose of appending, the realm preceding the first listed +realm is considered to be the null realm (""). + +[19] For the purpose of interpreting null subfields, the client's realm is +considered to precede those in the transited field, and the server's realm +is considered to follow them. + +[20] This means that a client and server running on the same host and +communicating with one another using the KRB_SAFE messages should not share +a common replay cache to detect KRB_SAFE replays. + +[21] The implementation of the Kerberos server need not combine the database +and the server on the same machine; it is feasible to store the principal +database in, say, a network name service, as long as the entries stored +therein are protected from disclosure to and modification by unauthorized +parties. However, we recommend against such strategies, as they can make +system management and threat analysis quite complex. + +[22] See the discussion of the padata field in section 5.4.2 for details on +why this can be useful. + +[23] Warning for implementations that unpack and repack data structures +during the generation and verification of embedded checksums: Because any +checksums applied to data structures must be checked against the original +data the length of bit strings must be preserved within a data structure +between the time that a checksum is generated through transmission to the +time that the checksum is verified. + + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +[24] It is NOT recommended that this time value be used to adjust the +workstation's clock since the workstation cannot reliably determine that +such a KRB_AS_REP actually came from the proper KDC in a timely manner. + +[25] Note, however, that if the time is used as the nonce, one must make +sure that the workstation time is monotonically increasing. If the time is +ever reset backwards, there is a small, but finite, probability that a nonce +will be reused. + +[27] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[29] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[31] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[32] If supported by the encryption method in use, an initialization vector +may be passed to the encryption procedure, in order to achieve proper cipher +chaining. The initialization vector might come from the last block of the +ciphertext from the previous KRB_PRIV message, but it is the application's +choice whether or not to use such an initialization vector. If left out, the +default initialization vector for the encryption algorithm will be used. + +[33] This prevents an attacker who generates an incorrect AS request from +obtaining verifiable plaintext for use in an off-line password guessing +attack. + +[35] In the above specification, UNTAGGED OCTET STRING(length) is the +notation for an octet string with its tag and length removed. It is not a +valid ASN.1 type. The tag bits and length must be removed from the +confounder since the purpose of the confounder is so that the message starts +with random data, but the tag and its length are fixed. For other fields, +the length and tag would be redundant if they were included because they are +specified by the encryption type. [36] The ordering of the fields in the +CipherText is important. Additionally, messages encoded in this format must +include a length as part of the msg-seq field. This allows the recipient to +verify that the message has not been truncated. Without a length, an +attacker could use a chosen plaintext attack to generate a message which +could be truncated, while leaving the checksum intact. Note that if the +msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length +is part of that encoding. + +[37] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[38] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[39] A variant of the key is used to limit the use of a key to a particular +function, separating the functions of generating a checksum from other +encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 +was chosen because it maintains key parity. The properties of DES precluded + + +draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 + +the use of the complement. The same constant is used for similar purpose in +the Message Integrity Check in the Privacy Enhanced Mail standard. + +[40] This error carries additional information in the e- data field. The +contents of the e-data field for this message is described in section 5.9.1. diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt new file mode 100644 index 0000000..06d997d --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt @@ -0,0 +1,6766 @@ + + + +INTERNET-DRAFT Clifford Neuman + John Kohl + Theodore Ts'o + November 18th, 1998 + +The Kerberos Network Authentication Service (V5) + +STATUS OF THIS MEMO + +This document is an Internet-Draft. 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.' + +To learn the current status of any Internet-Draft, please check the +'1id-abstracts.txt' listing contained in the Internet-Drafts Shadow +Directories on ftp.ietf.org (US East Coast), nic.nordu.net (Europe), +ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). + +The distribution of this memo is unlimited. It is filed as +draft-ietf-cat-kerberos-revisions-03.txt, and expires May 18th, 1999. +Please send comments to: krb-protocol@MIT.EDU + +ABSTRACT + +This document provides an overview and specification of Version 5 of the +Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol +and its intended use that require more detailed or clearer explanation than +was provided in RFC1510. This document is intended to provide a detailed +description of the protocol, suitable for implementation, together with +descriptions of the appropriate use of protocol messages and fields within +those messages. + +This document is not intended to describe Kerberos to the end user, system +administrator, or application developer. Higher level papers describing +Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], +are available elsewhere. + +OVERVIEW + +This INTERNET-DRAFT describes the concepts and model upon which the +Kerberos network authentication system is based. It also specifies Version +5 of the Kerberos protocol. + +The motivations, goals, assumptions, and rationale behind most design +decisions are treated cursorily; they are more fully described in a paper +available in IEEE communications [NT94] and earlier in the Kerberos portion +of the Athena Technical Plan [MNSS87]. The protocols have been a proposed +standard and are being considered for advancement for draft standard +through the IETF standard process. Comments are encouraged on the +presentation, but only minor refinements to the protocol as implemented or +extensions that fit within current protocol framework will be considered at + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +this time. + +Requests for addition to an electronic mailing list for discussion of +Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. +This mailing list is gatewayed onto the Usenet as the group +comp.protocols.kerberos. Requests for further information, including +documents and code availability, may be sent to info-kerberos@MIT.EDU. + +BACKGROUND + +The Kerberos model is based in part on Needham and Schroeder's trusted +third-party authentication protocol [NS78] and on modifications suggested +by Denning and Sacco [DS81]. The original design and implementation of +Kerberos Versions 1 through 4 was the work of two former Project Athena +staff members, Steve Miller of Digital Equipment Corporation and Clifford +Neuman (now at the Information Sciences Institute of the University of +Southern California), along with Jerome Saltzer, Technical Director of +Project Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many +other members of Project Athena have also contributed to the work on +Kerberos. + +Version 5 of the Kerberos protocol (described in this document) has evolved +from Version 4 based on new requirements and desires for features not +available in Version 4. The design of Version 5 of the Kerberos protocol +was led by Clifford Neuman and John Kohl with much input from the +community. The development of the MIT reference implementation was led at +MIT by John Kohl and Theodore T'so, with help and contributed code from +many others. Since RFC1510 was issued, extensions and revisions to the +protocol have been proposed by many individuals. Some of these proposals +are reflected in this document. Where such changes involved significant +effort, the document cites the contribution of the proposer. + +Reference implementations of both version 4 and version 5 of Kerberos are +publicly available and commercial implementations have been developed and +are widely used. Details on the differences between Kerberos Versions 4 and +5 can be found in [KNT92]. + +1. Introduction + +Kerberos provides a means of verifying the identities of principals, (e.g. +a workstation user or a network server) on an open (unprotected) network. +This is accomplished without relying on assertions by the host operating +system, without basing trust on host addresses, without requiring physical +security of all the hosts on the network, and under the assumption that +packets traveling along the network can be read, modified, and inserted at +will[1]. Kerberos performs authentication under these conditions as a +trusted third-party authentication service by using conventional (shared +secret key [2] cryptography. Kerberos extensions have been proposed and +implemented that provide for the use of public key cryptography during +certain phases of the authentication protocol. These extensions provide for +authentication of users registered with public key certification +authorities, and allow the system to provide certain benefits of public key +cryptography in situations where they are needed. + +The basic Kerberos authentication process proceeds as follows: A client +sends a request to the authentication server (AS) requesting 'credentials' +for a given server. The AS responds with these credentials, encrypted in +the client's key. The credentials consist of 1) a 'ticket' for the server +and 2) a temporary encryption key (often called a "session key"). The + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +client transmits the ticket (which contains the client's identity and a +copy of the session key, all encrypted in the server's key) to the server. +The session key (now shared by the client and server) is used to +authenticate the client, and may optionally be used to authenticate the +server. It may also be used to encrypt further communication between the +two parties or to exchange a separate sub-session key to be used to encrypt +further communication. + +Implementation of the basic protocol consists of one or more authentication +servers running on physically secure hosts. The authentication servers +maintain a database of principals (i.e., users and servers) and their +secret keys. Code libraries provide encryption and implement the Kerberos +protocol. In order to add authentication to its transactions, a typical +network application adds one or two calls to the Kerberos library directly +or through the Generic Security Services Application Programming Interface, +GSSAPI, described in separate document. These calls result in the +transmission of the necessary messages to achieve authentication. + +The Kerberos protocol consists of several sub-protocols (or exchanges). +There are two basic methods by which a client can ask a Kerberos server for +credentials. In the first approach, the client sends a cleartext request +for a ticket for the desired server to the AS. The reply is sent encrypted +in the client's secret key. Usually this request is for a ticket-granting +ticket (TGT) which can later be used with the ticket-granting server (TGS). +In the second method, the client sends a request to the TGS. The client +uses the TGT to authenticate itself to the TGS in the same manner as if it +were contacting any other application server that requires Kerberos +authentication. The reply is encrypted in the session key from the TGT. +Though the protocol specification describes the AS and the TGS as separate +servers, they are implemented in practice as different protocol entry +points within a single Kerberos server. + +Once obtained, credentials may be used to verify the identity of the +principals in a transaction, to ensure the integrity of messages exchanged +between them, or to preserve privacy of the messages. The application is +free to choose whatever protection may be necessary. + +To verify the identities of the principals in a transaction, the client +transmits the ticket to the application server. Since the ticket is sent +"in the clear" (parts of it are encrypted, but this encryption doesn't +thwart replay) and might be intercepted and reused by an attacker, +additional information is sent to prove that the message originated with +the principal to whom the ticket was issued. This information (called the +authenticator) is encrypted in the session key, and includes a timestamp. +The timestamp proves that the message was recently generated and is not a +replay. Encrypting the authenticator in the session key proves that it was +generated by a party possessing the session key. Since no one except the +requesting principal and the server know the session key (it is never sent +over the network in the clear) this guarantees the identity of the client. + +The integrity of the messages exchanged between principals can also be +guaranteed using the session key (passed in the ticket and contained in the +credentials). This approach provides detection of both replay attacks and +message stream modification attacks. It is accomplished by generating and +transmitting a collision-proof checksum (elsewhere called a hash or digest +function) of the client's message, keyed with the session key. Privacy and +integrity of the messages exchanged between principals can be secured by +encrypting the data to be passed using the session key contained in the +ticket or the subsession key found in the authenticator. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +The authentication exchanges mentioned above require read-only access to +the Kerberos database. Sometimes, however, the entries in the database must +be modified, such as when adding new principals or changing a principal's +key. This is done using a protocol between a client and a third Kerberos +server, the Kerberos Administration Server (KADM). There is also a protocol +for maintaining multiple copies of the Kerberos database. Neither of these +protocols are described in this document. + +1.1. Cross-Realm Operation + +The Kerberos protocol is designed to operate across organizational +boundaries. A client in one organization can be authenticated to a server +in another. Each organization wishing to run a Kerberos server establishes +its own 'realm'. The name of the realm in which a client is registered is +part of the client's name, and can be used by the end-service to decide +whether to honor a request. + +By establishing 'inter-realm' keys, the administrators of two realms can +allow a client authenticated in the local realm to prove its identity to +servers in other realms[3]. The exchange of inter-realm keys (a separate +key may be used for each direction) registers the ticket-granting service +of each realm as a principal in the other realm. A client is then able to +obtain a ticket-granting ticket for the remote realm's ticket-granting +service from its local realm. When that ticket-granting ticket is used, the +remote ticket-granting service uses the inter-realm key (which usually +differs from its own normal TGS key) to decrypt the ticket-granting ticket, +and is thus certain that it was issued by the client's own TGS. Tickets +issued by the remote ticket-granting service will indicate to the +end-service that the client was authenticated from another realm. + +A realm is said to communicate with another realm if the two realms share +an inter-realm key, or if the local realm shares an inter-realm key with an +intermediate realm that communicates with the remote realm. An +authentication path is the sequence of intermediate realms that are +transited in communicating from one realm to another. + +Realms are typically organized hierarchically. Each realm shares a key with +its parent and a different key with each child. If an inter-realm key is +not directly shared by two realms, the hierarchical organization allows an +authentication path to be easily constructed. If a hierarchical +organization is not used, it may be necessary to consult a database in +order to construct an authentication path between realms. + +Although realms are typically hierarchical, intermediate realms may be +bypassed to achieve cross-realm authentication through alternate +authentication paths (these might be established to make communication +between two realms more efficient). It is important for the end-service to +know which realms were transited when deciding how much faith to place in +the authentication process. To facilitate this decision, a field in each +ticket contains the names of the realms that were involved in +authenticating the client. + +The application server is ultimately responsible for accepting or rejecting +authentication and should check the transited field. The application server +may choose to rely on the KDC for the application server's realm to check +the transited field. The application server's KDC will set the +TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate +realms may also check the transited field as they issue + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +ticket-granting-tickets for other realms, but they are encouraged not to do +so. A client may request that the KDC's not check the transited field by +setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not +required to honor this flag. + +1.2. Authorization + +As an authentication service, Kerberos provides a means of verifying the +identity of principals on a network. Authentication is usually useful +primarily as a first step in the process of authorization, determining +whether a client may use a service, which objects the client is allowed to +access, and the type of access allowed for each. Kerberos does not, by +itself, provide authorization. Possession of a client ticket for a service +provides only for authentication of the client to that service, and in the +absence of a separate authorization procedure, it should not be considered +by an application as authorizing the use of that service. + +Such separate authorization methods may be implemented as application +specific access control functions and may be based on files such as the +application server, or on separately issued authorization credentials such +as those based on proxies [Neu93] , or on other authorization services. + +Applications should not be modified to accept the issuance of a service +ticket by the Kerberos server (even by an modified Kerberos server) as +granting authority to use the service, since such applications may become +vulnerable to the bypass of this authorization check in an environment if +they interoperate with other KDCs or where other options for application +authentication (e.g. the PKTAPP proposal) are provided. + +1.3. Environmental assumptions + +Kerberos imposes a few assumptions on the environment in which it can +properly function: + + * 'Denial of service' attacks are not solved with Kerberos. There are + places in these protocols where an intruder can prevent an application + from participating in the proper authentication steps. Detection and + solution of such attacks (some of which can appear to be nnot-uncommon + 'normal' failure modes for the system) is usually best left to the + human administrators and users. + * Principals must keep their secret keys secret. If an intruder somehow + steals a principal's key, it will be able to masquerade as that + principal or impersonate any server to the legitimate principal. + * 'Password guessing' attacks are not solved by Kerberos. If a user + chooses a poor password, it is possible for an attacker to + successfully mount an offline dictionary attack by repeatedly + attempting to decrypt, with successive entries from a dictionary, + messages obtained which are encrypted under a key derived from the + user's password. + * Each host on the network must have a clock which is 'loosely + synchronized' to the time of the other hosts; this synchronization is + used to reduce the bookkeeping needs of application servers when they + do replay detection. The degree of "looseness" can be configured on a + per-server basis, but is typically on the order of 5 minutes. If the + clocks are synchronized over the network, the clock synchronization + protocol must itself be secured from network attackers. + * Principal identifiers are not recycled on a short-term basis. A + typical mode of access control will use access control lists (ACLs) to + grant permissions to particular principals. If a stale ACL entry + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + remains for a deleted principal and the principal identifier is + reused, the new principal will inherit rights specified in the stale + ACL entry. By not re-using principal identifiers, the danger of + inadvertent access is removed. + +1.4. Glossary of terms + +Below is a list of terms used throughout this document. + +Authentication + Verifying the claimed identity of a principal. +Authentication header + A record containing a Ticket and an Authenticator to be presented to a + server as part of the authentication process. +Authentication path + A sequence of intermediate realms transited in the authentication + process when communicating from one realm to another. +Authenticator + A record containing information that can be shown to have been + recently generated using the session key known only by the client and + server. +Authorization + The process of determining whether a client may use a service, which + objects the client is allowed to access, and the type of access + allowed for each. +Capability + A token that grants the bearer permission to access an object or + service. In Kerberos, this might be a ticket whose use is restricted + by the contents of the authorization data field, but which lists no + network addresses, together with the session key necessary to use the + ticket. +Ciphertext + The output of an encryption function. Encryption transforms plaintext + into ciphertext. +Client + A process that makes use of a network service on behalf of a user. + Note that in some cases a Server may itself be a client of some other + server (e.g. a print server may be a client of a file server). +Credentials + A ticket plus the secret session key necessary to successfully use + that ticket in an authentication exchange. +KDC + Key Distribution Center, a network service that supplies tickets and + temporary session keys; or an instance of that service or the host on + which it runs. The KDC services both initial ticket and + ticket-granting ticket requests. The initial ticket portion is + sometimes referred to as the Authentication Server (or service). The + ticket-granting ticket portion is sometimes referred to as the + ticket-granting server (or service). +Kerberos + Aside from the 3-headed dog guarding Hades, the name given to Project + Athena's authentication service, the protocol used by that service, or + the code used to implement the authentication service. +Plaintext + The input to an encryption function or the output of a decryption + function. Decryption transforms ciphertext into plaintext. +Principal + A uniquely named client or server instance that participates in a + network communication. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +Principal identifier + The name used to uniquely identify each different principal. +Seal + To encipher a record containing several fields in such a way that the + fields cannot be individually replaced without either knowledge of the + encryption key or leaving evidence of tampering. +Secret key + An encryption key shared by a principal and the KDC, distributed + outside the bounds of the system, with a long lifetime. In the case of + a human user's principal, the secret key is derived from a password. +Server + A particular Principal which provides a resource to network clients. + The server is sometimes refered to as the Application Server. +Service + A resource provided to network clients; often provided by more than + one server (for example, remote file service). +Session key + A temporary encryption key used between two principals, with a + lifetime limited to the duration of a single login "session". +Sub-session key + A temporary encryption key used between two principals, selected and + exchanged by the principals using the session key, and with a lifetime + limited to the duration of a single association. +Ticket + A record that helps a client authenticate itself to a server; it + contains the client's identity, a session key, a timestamp, and other + information, all sealed using the server's secret key. It only serves + to authenticate a client when presented along with a fresh + Authenticator. + +2. Ticket flag uses and requests + +Each Kerberos ticket contains a set of flags which are used to indicate +various attributes of that ticket. Most flags may be requested by a client +when the ticket is obtained; some are automatically turned on and off by a +Kerberos server as required. The following sections explain what the +various flags mean, and gives examples of reasons to use such a flag. + +2.1. Initial and pre-authenticated tickets + +The INITIAL flag indicates that a ticket was issued using the AS protocol +and not issued based on a ticket-granting ticket. Application servers that +want to require the demonstrated knowledge of a client's secret key (e.g. a +password-changing program) can insist that this flag be set in any tickets +they accept, and thus be assured that the client's key was recently +presented to the application client. + +The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the +initial authentication, regardless of whether the current ticket was issued +directly (in which case INITIAL will also be set) or issued on the basis of +a ticket-granting ticket (in which case the INITIAL flag is clear, but the +PRE-AUTHENT and HW-AUTHENT flags are carried forward from the +ticket-granting ticket). + +2.2. Invalid tickets + +The INVALID flag indicates that a ticket is invalid. Application servers +must reject tickets which have this flag set. A postdated ticket will +usually be issued in this form. Invalid tickets must be validated by the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +KDC before use, by presenting them to the KDC in a TGS request with the +VALIDATE option specified. The KDC will only validate tickets after their +starttime has passed. The validation is required so that postdated tickets +which have been stolen before their starttime can be rendered permanently +invalid (through a hot-list mechanism) (see section 3.3.3.1). + +2.3. Renewable tickets + +Applications may desire to hold tickets which can be valid for long periods +of time. However, this can expose their credentials to potential theft for +equally long periods, and those stolen credentials would be valid until the +expiration time of the ticket(s). Simply using short-lived tickets and +obtaining new ones periodically would require the client to have long-term +access to its secret key, an even greater risk. Renewable tickets can be +used to mitigate the consequences of theft. Renewable tickets have two +"expiration times": the first is when the current instance of the ticket +expires, and the second is the latest permissible value for an individual +expiration time. An application client must periodically (i.e. before it +expires) present a renewable ticket to the KDC, with the RENEW option set +in the KDC request. The KDC will issue a new ticket with a new session key +and a later expiration time. All other fields of the ticket are left +unmodified by the renewal process. When the latest permissible expiration +time arrives, the ticket expires permanently. At each renewal, the KDC may +consult a hot-list to determine if the ticket had been reported stolen +since its last renewal; it will refuse to renew such stolen tickets, and +thus the usable lifetime of stolen tickets is reduced. + +The RENEWABLE flag in a ticket is normally only interpreted by the +ticket-granting service (discussed below in section 3.3). It can usually be +ignored by application servers. However, some particularly careful +application servers may wish to disallow renewable tickets. + +If a renewable ticket is not renewed by its expiration time, the KDC will +not renew the ticket. The RENEWABLE flag is reset by default, but a client +may request it be set by setting the RENEWABLE option in the KRB_AS_REQ +message. If it is set, then the renew-till field in the ticket contains the +time after which the ticket may not be renewed. + +2.4. Postdated tickets + +Applications may occasionally need to obtain tickets for use much later, +e.g. a batch submission system would need tickets to be valid at the time +the batch job is serviced. However, it is dangerous to hold valid tickets +in a batch queue, since they will be on-line longer and more prone to +theft. Postdated tickets provide a way to obtain these tickets from the KDC +at job submission time, but to leave them "dormant" until they are +activated and validated by a further request of the KDC. If a ticket theft +were reported in the interim, the KDC would refuse to validate the ticket, +and the thief would be foiled. + +The MAY-POSTDATE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. This +flag must be set in a ticket-granting ticket in order to issue a postdated +ticket based on the presented ticket. It is reset by default; it may be +requested by a client by setting the ALLOW-POSTDATE option in the +KRB_AS_REQ message. This flag does not allow a client to obtain a postdated +ticket-granting ticket; postdated ticket-granting tickets can only by +obtained by requesting the postdating in the KRB_AS_REQ message. The life +(endtime-starttime) of a postdated ticket will be the remaining life of the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +ticket-granting ticket at the time of the request, unless the RENEWABLE +option is also set, in which case it can be the full life +(endtime-starttime) of the ticket-granting ticket. The KDC may limit how +far in the future a ticket may be postdated. + +The POSTDATED flag indicates that a ticket has been postdated. The +application server can check the authtime field in the ticket to see when +the original authentication occurred. Some services may choose to reject +postdated tickets, or they may only accept them within a certain period +after the original authentication. When the KDC issues a POSTDATED ticket, +it will also be marked as INVALID, so that the application client must +present the ticket to the KDC to be validated before use. + +2.5. Proxiable and proxy tickets + +At times it may be necessary for a principal to allow a service to perform +an operation on its behalf. The service must be able to take on the +identity of the client, but only for a particular purpose. A principal can +allow a service to take on the principal's identity for a particular +purpose by granting it a proxy. + +The process of granting a proxy using the proxy and proxiable flags is used +to provide credentials for use with specific services. Though conceptually +also a proxy, user's wishing to delegate their identity for ANY purpose +must use the ticket forwarding mechanism described in the next section to +forward a ticket granting ticket. + +The PROXIABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. When +set, this flag tells the ticket-granting server that it is OK to issue a +new ticket (but not a ticket-granting ticket) with a different network +address based on this ticket. This flag is set if requested by the client +on initial authentication. By default, the client will request that it be +set when requesting a ticket granting ticket, and reset when requesting any +other ticket. + +This flag allows a client to pass a proxy to a server to perform a remote +request on its behalf, e.g. a print service client can give the print +server a proxy to access the client's files on a particular file server in +order to satisfy a print request. + +In order to complicate the use of stolen credentials, Kerberos tickets are +usually valid from only those network addresses specifically included in +the ticket[4]. When granting a proxy, the client must specify the new +network address from which the proxy is to be used, or indicate that the +proxy is to be issued for use from any address. + +The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. +Application servers may check this flag and at their option they may +require additional authentication from the agent presenting the proxy in +order to provide an audit trail. + +2.6. Forwardable tickets + +Authentication forwarding is an instance of a proxy where the service is +granted complete use of the client's identity. An example where it might be +used is when a user logs in to a remote system and wants authentication to +work from that system as if the login were local. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +The FORWARDABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. The +FORWARDABLE flag has an interpretation similar to that of the PROXIABLE +flag, except ticket-granting tickets may also be issued with different +network addresses. This flag is reset by default, but users may request +that it be set by setting the FORWARDABLE option in the AS request when +they request their initial ticket- granting ticket. + +This flag allows for authentication forwarding without requiring the user +to enter a password again. If the flag is not set, then authentication +forwarding is not permitted, but the same result can still be achieved if +the user engages in the AS exchange specifying the requested network +addresses and supplies a password. + +The FORWARDED flag is set by the TGS when a client presents a ticket with +the FORWARDABLE flag set and requests a forwarded ticket by specifying the +FORWARDED KDC option and supplying a set of addresses for the new ticket. +It is also set in all tickets issued based on tickets with the FORWARDED +flag set. Application servers may choose to process FORWARDED tickets +differently than non-FORWARDED tickets. + +2.7. Other KDC options + +There are two additional options which may be set in a client's request of +the KDC. The RENEWABLE-OK option indicates that the client will accept a +renewable ticket if a ticket with the requested life cannot otherwise be +provided. If a ticket with the requested life cannot be provided, then the +KDC may issue a renewable ticket with a renew-till equal to the the +requested endtime. The value of the renew-till field may still be adjusted +by site-determined limits or limits imposed by the individual principal or +server. + +The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. +It indicates that the ticket to be issued for the end server is to be +encrypted in the session key from the a additional second ticket-granting +ticket provided with the request. See section 3.3.3 for specific details. + +3. Message Exchanges + +The following sections describe the interactions between network clients +and servers and the messages involved in those exchanges. + +3.1. The Authentication Service Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_AS_REQ 5.4.1 + 2. Kerberos to client KRB_AS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The Authentication Service (AS) Exchange between the client and the +Kerberos Authentication Server is initiated by a client when it wishes to +obtain authentication credentials for a given server but currently holds no +credentials. In its basic form, the client's secret key is used for +encryption and decryption. This exchange is typically used at the +initiation of a login session to obtain credentials for a Ticket-Granting +Server which will subsequently be used to obtain credentials for other +servers (see section 3.3) without requiring further use of the client's +secret key. This exchange is also used to request credentials for services + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +which must not be mediated through the Ticket-Granting Service, but rather +require a principal's secret key, such as the password-changing service[5]. +This exchange does not by itself provide any assurance of the the identity +of the user[6]. + +The exchange consists of two messages: KRB_AS_REQ from the client to +Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these +messages are described in sections 5.4.1, 5.4.2, and 5.9.1. + +In the request, the client sends (in cleartext) its own identity and the +identity of the server for which it is requesting credentials. The +response, KRB_AS_REP, contains a ticket for the client to present to the +server, and a session key that will be shared by the client and the server. +The session key and additional information are encrypted in the client's +secret key. The KRB_AS_REP message contains information which can be used +to detect replays, and to associate it with the message to which it +replies. Various errors can occur; these are indicated by an error response +(KRB_ERROR) instead of the KRB_AS_REP response. The error message is not +encrypted. The KRB_ERROR message contains information which can be used to +associate it with the message to which it replies. The lack of encryption +in the KRB_ERROR message precludes the ability to detect replays, +fabrications, or modifications of such messages. + +Without preautentication, the authentication server does not know whether +the client is actually the principal named in the request. It simply sends +a reply without knowing or caring whether they are the same. This is +acceptable because nobody but the principal whose identity was given in the +request will be able to use the reply. Its critical information is +encrypted in that principal's key. The initial request supports an optional +field that can be used to pass additional information that might be needed +for the initial exchange. This field may be used for preauthentication as +described in section [hl<>]. + +3.1.1. Generation of KRB_AS_REQ message + +The client may specify a number of options in the initial request. Among +these options are whether pre-authentication is to be performed; whether +the requested ticket is to be renewable, proxiable, or forwardable; whether +it should be postdated or allow postdating of derivative tickets; and +whether a renewable ticket will be accepted in lieu of a non-renewable +ticket if the requested ticket expiration date cannot be satisfied by a +non-renewable ticket (due to configuration constraints; see section 4). See +section A.1 for pseudocode. + +The client prepares the KRB_AS_REQ message and sends it to the KDC. + +3.1.2. Receipt of KRB_AS_REQ message + +If all goes well, processing the KRB_AS_REQ message will result in the +creation of a ticket for the client to present to the server. The format +for the ticket is described in section 5.3.1. The contents of the ticket +are determined as follows. + +3.1.3. Generation of KRB_AS_REP message + +The authentication server looks up the client and server principals named +in the KRB_AS_REQ in its database, extracting their respective keys. If +required, the server pre-authenticates the request, and if the +pre-authentication check fails, an error message with the code + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the +requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP +is returned. Otherwise it generates a 'random' session key[7]. + +If there are multiple encryption keys registered for a client in the +Kerberos database (or if the key registered supports multiple encryption +types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS +request is used by the KDC to select the encryption method to be used for +encrypting the response to the client. If there is more than one supported, +strong encryption type in the etype list, the first valid etype for which +an encryption key is available is used. The encryption method used to +respond to a TGS request is taken from the keytype of the session key found +in the ticket granting ticket. + +When the etype field is present in a KDC request, whether an AS or TGS +request, the KDC will attempt to assign the type of the random session key +from the list of methods in the etype field. The KDC will select the +appropriate type using the list of methods provided together with +information from the Kerberos database indicating acceptable encryption +methods for the application server. The KDC will not issue tickets with a +weak session key encryption type. + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. +Otherwise the requested start time is checked against the policy of the +local realm (the administrator might decide to prohibit certain types or +ranges of postdated tickets), and if acceptable, the ticket's start time is +set as requested and the INVALID flag is set in the new ticket. The +postdated ticket must be validated before use by presenting it to the KDC +after the start time has been reached. + +The expiration time of the ticket will be set to the minimum of the +following: + + * The expiration time (endtime) requested in the KRB_AS_REQ message. + * The ticket's start time plus the maximum allowable lifetime associated + with the client principal (the authentication server's database + includes a maximum ticket lifetime field in each principal's record; + see section 4). + * The ticket's start time plus the maximum allowable lifetime associated + with the server principal. + * The ticket's start time plus the maximum lifetime set by the policy of + the local realm. + +If the requested expiration time minus the start time (as determined above) +is less than a site-determined minimum lifetime, an error message with code +KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the +ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' +option was requested, then the 'RENEWABLE' flag is set in the new ticket, +and the renew-till value is set as if the 'RENEWABLE' option were requested +(the field and option names are described fully in section 5.4.1). + +If the RENEWABLE option has been requested or if the RENEWABLE-OK option +has been set and a renewable ticket is to be issued, then the renew-till +field is set to the minimum of: + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + * Its requested value. + * The start time of the ticket plus the minimum of the two maximum + renewable lifetimes associated with the principals' database entries. + * The start time of the ticket plus the maximum renewable lifetime set + by the policy of the local realm. + +The flags field of the new ticket will have the following options set if +they have been requested and if the policy of the local realm allows: +FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new +ticket is post-dated (the start time is in the future), its INVALID flag +will also be set. + +If all of the above succeed, the server formats a KRB_AS_REP message (see +section 5.4.2), copying the addresses in the request into the caddr of the +response, placing any required pre-authentication data into the padata of +the response, and encrypts the ciphertext part in the client's key using +the requested encryption method, and sends it to the client. See section +A.2 for pseudocode. + +3.1.4. Generation of KRB_ERROR message + +Several errors can occur, and the Authentication Server responds by +returning an error message, KRB_ERROR, to the client, with the error-code +and e-text fields set to appropriate values. The error message contents and +details are described in Section 5.9.1. + +3.1.5. Receipt of KRB_AS_REP message + +If the reply message type is KRB_AS_REP, then the client verifies that the +cname and crealm fields in the cleartext portion of the reply match what it +requested. If any padata fields are present, they may be used to derive the +proper secret key to decrypt the message. The client decrypts the encrypted +part of the response using its secret key, verifies that the nonce in the +encrypted part matches the nonce it supplied in its request (to detect +replays). It also verifies that the sname and srealm in the response match +those in the request (or are otherwise expected values), and that the host +address field is also correct. It then stores the ticket, session key, +start and expiration times, and other information for later use. The +key-expiration field from the encrypted part of the response may be checked +to notify the user of impending key expiration (the client program could +then suggest remedial action, such as a password change). See section A.3 +for pseudocode. + +Proper decryption of the KRB_AS_REP message is not sufficient to verify the +identity of the user; the user and an attacker could cooperate to generate +a KRB_AS_REP format message which decrypts properly but is not from the +proper KDC. If the host wishes to verify the identity of the user, it must +require the user to present application credentials which can be verified +using a securely-stored secret key for the host. If those credentials can +be verified, then the identity of the user can be assured. + +3.1.6. Receipt of KRB_ERROR message + +If the reply message type is KRB_ERROR, then the client interprets it as an +error and performs whatever application-specific tasks are necessary to +recover. + +3.2. The Client/Server Authentication Exchange + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + Summary +Message direction Message type Section +Client to Application server KRB_AP_REQ 5.5.1 +[optional] Application server to client KRB_AP_REP or 5.5.2 + KRB_ERROR 5.9.1 + +The client/server authentication (CS) exchange is used by network +applications to authenticate the client to the server and vice versa. The +client must have already acquired credentials for the server using the AS +or TGS exchange. + +3.2.1. The KRB_AP_REQ message + +The KRB_AP_REQ contains authentication information which should be part of +the first message in an authenticated transaction. It contains a ticket, an +authenticator, and some additional bookkeeping information (see section +5.5.1 for the exact format). The ticket by itself is insufficient to +authenticate a client, since tickets are passed across the network in +cleartext[DS90], so the authenticator is used to prevent invalid replay of +tickets by proving to the server that the client knows the session key of +the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message +is referred to elsewhere as the 'authentication header.' + +3.2.2. Generation of a KRB_AP_REQ message + +When a client wishes to initiate authentication to a server, it obtains +(either through a credentials cache, the AS exchange, or the TGS exchange) +a ticket and session key for the desired service. The client may re-use any +tickets it holds until they expire. To use a ticket the client constructs a +new Authenticator from the the system time, its name, and optionally an +application specific checksum, an initial sequence number to be used in +KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in +negotiations for a session key unique to this particular session. +Authenticators may not be re-used and will be rejected if replayed to a +server[LGDSR87]. If a sequence number is to be included, it should be +randomly chosen so that even after many messages have been exchanged it is +not likely to collide with other sequence numbers in use. + +The client may indicate a requirement of mutual authentication or the use +of a session-key based ticket by setting the appropriate flag(s) in the +ap-options field of the message. + +The Authenticator is encrypted in the session key and combined with the +ticket to form the KRB_AP_REQ message which is then sent to the end server +along with any additional application-specific information. See section A.9 +for pseudocode. + +3.2.3. Receipt of KRB_AP_REQ message + +Authentication is based on the server's current time of day (clocks must be +loosely synchronized), the authenticator, and the ticket. Several errors +are possible. If an error occurs, the server is expected to reply to the +client with a KRB_ERROR message. This message may be encapsulated in the +application protocol if its 'raw' form is not acceptable to the protocol. +The format of error messages is described in section 5.9.1. + +The algorithm for verifying authentication information is as follows. If +the message type is not KRB_AP_REQ, the server returns the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +KRB_AP_ERR_MSG_TYPE error. If the key version indicated by the Ticket in +the KRB_AP_REQ is not one the server can use (e.g., it indicates an old +key, and the server no longer possesses a copy of the old key), the +KRB_AP_ERR_BADKEYVER error is returned. If the USE-SESSION-KEY flag is set +in the ap-options field, it indicates to the server that the ticket is +encrypted in the session key from the server's ticket-granting ticket +rather than its secret key[10]. Since it is possible for the server to be +registered in multiple realms, with different keys in each, the srealm +field in the unencrypted portion of the ticket in the KRB_AP_REQ is used to +specify which secret key the server should use to decrypt that ticket. The +KRB_AP_ERR_NOKEY error code is returned if the server doesn't have the +proper key to decipher the ticket. + +The ticket is decrypted using the version of the server's key specified by +the ticket. If the decryption routines detect a modification of the ticket +(each encryption system must provide safeguards to detect modified +ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned +(chances are good that different keys were used to encrypt and decrypt). + +The authenticator is decrypted using the session key extracted from the +decrypted ticket. If decryption shows it to have been modified, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the +client from the ticket are compared against the same fields in the +authenticator. If they don't match, the KRB_AP_ERR_BADMATCH error is +returned (they might not match, for example, if the wrong session key was +used to encrypt the authenticator). The addresses in the ticket (if any) +are then searched for an address matching the operating-system reported +address of the client. If no match is found or the server insists on ticket +addresses but none are present in the ticket, the KRB_AP_ERR_BADADDR error +is returned. + +If the local (server) time and the client time in the authenticator differ +by more than the allowable clock skew (e.g., 5 minutes), the +KRB_AP_ERR_SKEW error is returned. If the server name, along with the +client name, time and microsecond fields from the Authenticator match any +recently-seen such tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The +server must remember any authenticator presented within the allowable clock +skew, so that a replay attempt is guaranteed to fail. If a server loses +track of any authenticator presented within the allowable clock skew, it +must reject all requests until the clock skew interval has passed. This +assures that any lost or re-played authenticators will fall outside the +allowable clock skew and can no longer be successfully replayed (If this is +not done, an attacker could conceivably record the ticket and authenticator +sent over the network to a server, then disable the client's host, pose as +the disabled host, and replay the ticket and authenticator to subvert the +authentication.). If a sequence number is provided in the authenticator, +the server saves it for later use in processing KRB_SAFE and/or KRB_PRIV +messages. If a subkey is present, the server either saves it for later use +or uses it to help generate its own choice for a subkey to be returned in a +KRB_AP_REP message. + +The server computes the age of the ticket: local (server) time minus the +start time inside the Ticket. If the start time is later than the current +time by more than the allowable clock skew or if the INVALID flag is set in +the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the +current time is later than end time by more than the allowable clock skew, +the KRB_AP_ERR_TKT_EXPIRED error is returned. + +If all these checks succeed without an error, the server is assured that + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +the client possesses the credentials of the principal named in the ticket +and thus, the client has been authenticated to the server. See section A.10 +for pseudocode. + +Passing these checks provides only authentication of the named principal; +it does not imply authorization to use the named service. Applications must +make a separate authorization decisions based upon the authenticated name +of the user, the requested operation, local acces control information such +as that contained in a .k5login or .k5users file, and possibly a separate +distributed authorization service. + +3.2.4. Generation of a KRB_AP_REP message + +Typically, a client's request will include both the authentication +information and its initial request in the same message, and the server +need not explicitly reply to the KRB_AP_REQ. However, if mutual +authentication (not only authenticating the client to the server, but also +the server to the client) is being performed, the KRB_AP_REQ message will +have MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message +is required in response. As with the error message, this message may be +encapsulated in the application protocol if its "raw" form is not +acceptable to the application's protocol. The timestamp and microsecond +field used in the reply must be the client's timestamp and microsecond +field (as provided in the authenticator)[12]. If a sequence number is to be +included, it should be randomly chosen as described above for the +authenticator. A subkey may be included if the server desires to negotiate +a different subkey. The KRB_AP_REP message is encrypted in the session key +extracted from the ticket. See section A.11 for pseudocode. + +3.2.5. Receipt of KRB_AP_REP message + +If a KRB_AP_REP message is returned, the client uses the session key from +the credentials obtained for the server[13] to decrypt the message, and +verifies that the timestamp and microsecond fields match those in the +Authenticator it sent to the server. If they match, then the client is +assured that the server is genuine. The sequence number and subkey (if +present) are retained for later use. See section A.12 for pseudocode. + +3.2.6. Using the encryption key + +After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and +server share an encryption key which can be used by the application. The +'true session key' to be used for KRB_PRIV, KRB_SAFE, or other +application-specific uses may be chosen by the application based on the +subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, +the use of this session key will be implicit in the protocol; in others the +method of use must be chosen from several alternatives. We leave the +protocol negotiations of how to use the key (e.g. selecting an encryption +or checksum type) to the application programmer; the Kerberos protocol does +not constrain the implementation options, but an example of how this might +be done follows. + +One way that an application may choose to negotiate a key to be used for +subequent integrity and privacy protection is for the client to propose a +key in the subkey field of the authenticator. The server can then choose a +key using the proposed key from the client as input, returning the new +subkey in the subkey field of the application reply. This key could then be +used for subsequent communication. To make this example more concrete, if +the encryption method in use required a 56 bit key, and for whatever + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +reason, one of the parties was prevented from using a key with more than 40 +unknown bits, this method would allow the the party which is prevented from +using more than 40 bits to either propose (if the client) an initial key +with a known quantity for 16 of those bits, or to mask 16 of the bits (if +the server) with the known quantity. The application implementor is warned, +however, that this is only an example, and that an analysis of the +particular crytosystem to be used, and the reasons for limiting the key +length, must be made before deciding whether it is acceptable to mask bits +of the key. + +With both the one-way and mutual authentication exchanges, the peers should +take care not to send sensitive information to each other without proper +assurances. In particular, applications that require privacy or integrity +should use the KRB_AP_REP response from the server to client to assure both +client and server of their peer's identity. If an application protocol +requires privacy of its messages, it can use the KRB_PRIV message (section +3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. + +3.3. The Ticket-Granting Service (TGS) Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_TGS_REQ 5.4.1 + 2. Kerberos to client KRB_TGS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The TGS exchange between a client and the Kerberos Ticket-Granting Server +is initiated by a client when it wishes to obtain authentication +credentials for a given server (which might be registered in a remote +realm), when it wishes to renew or validate an existing ticket, or when it +wishes to obtain a proxy ticket. In the first case, the client must already +have acquired a ticket for the Ticket-Granting Service using the AS +exchange (the ticket-granting ticket is usually obtained when a client +initially authenticates to the system, such as when a user logs in). The +message format for the TGS exchange is almost identical to that for the AS +exchange. The primary difference is that encryption and decryption in the +TGS exchange does not take place under the client's key. Instead, the +session key from the ticket-granting ticket or renewable ticket, or +sub-session key from an Authenticator is used. As is the case for all +application servers, expired tickets are not accepted by the TGS, so once a +renewable or ticket-granting ticket expires, the client must use a separate +exchange to obtain valid tickets. + +The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the +client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or +KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the +client plus a request for credentials. The authentication information +consists of the authentication header (KRB_AP_REQ) which includes the +client's previously obtained ticket-granting, renewable, or invalid ticket. +In the ticket-granting ticket and proxy cases, the request may include one +or more of: a list of network addresses, a collection of typed +authorization data to be sealed in the ticket for authorization use by the +application server, or additional tickets (the use of which are described +later). The TGS reply (KRB_TGS_REP) contains the requested credentials, +encrypted in the session key from the ticket-granting ticket or renewable +ticket, or if present, in the sub-session key from the Authenticator (part +of the authentication header). The KRB_ERROR message contains an error code +and text explaining what went wrong. The KRB_ERROR message is not +encrypted. The KRB_TGS_REP message contains information which can be used + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +to detect replays, and to associate it with the message to which it +replies. The KRB_ERROR message also contains information which can be used +to associate it with the message to which it replies, but the lack of +encryption in the KRB_ERROR message precludes the ability to detect replays +or fabrications of such messages. + +3.3.1. Generation of KRB_TGS_REQ message + +Before sending a request to the ticket-granting service, the client must +determine in which realm the application server is registered[15]. If the +client does not already possess a ticket-granting ticket for the +appropriate realm, then one must be obtained. This is first attempted by +requesting a ticket-granting ticket for the destination realm from a +Kerberos server for which the client does posess a ticket-granting ticket +(using the KRB_TGS_REQ message recursively). The Kerberos server may return +a TGT for the desired realm in which case one can proceed. Alternatively, +the Kerberos server may return a TGT for a realm which is 'closer' to the +desired realm (further along the standard hierarchical path), in which case +this step must be repeated with a Kerberos server in the realm specified in +the returned TGT. If neither are returned, then the request must be retried +with a Kerberos server for a realm higher in the hierarchy. This request +will itself require a ticket-granting ticket for the higher realm which +must be obtained by recursively applying these directions. + +Once the client obtains a ticket-granting ticket for the appropriate realm, +it determines which Kerberos servers serve that realm, and contacts one. +The list might be obtained through a configuration file or network service +or it may be generated from the name of the realm; as long as the secret +keys exchanged by realms are kept secret, only denial of service results +from using a false Kerberos server. + +As in the AS exchange, the client may specify a number of options in the +KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing +an authentication header as an element of the padata field, and including +the same fields as used in the KRB_AS_REQ message along with several +optional fields: the enc-authorization-data field for application server +use and additional tickets required by some options. + +In preparing the authentication header, the client can select a sub-session +key under which the response from the Kerberos server will be +encrypted[16]. If the sub-session key is not specified, the session key +from the ticket-granting ticket will be used. If the enc-authorization-data +is present, it must be encrypted in the sub-session key, if present, from +the authenticator portion of the authentication header, or if not present, +using the session key from the ticket-granting ticket. + +Once prepared, the message is sent to a Kerberos server for the destination +realm. See section A.5 for pseudocode. + +3.3.2. Receipt of KRB_TGS_REQ message + +The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ +message, but there are many additional checks to be performed. First, the +Kerberos server must determine which server the accompanying ticket is for +and it must select the appropriate key to decrypt it. For a normal +KRB_TGS_REQ message, it will be for the ticket granting service, and the +TGS's key will be used. If the TGT was issued by another realm, then the +appropriate inter-realm key must be used. If the accompanying ticket is not +a ticket granting ticket for the current realm, but is for an application + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +server in the current realm, the RENEW, VALIDATE, or PROXY options are +specified in the request, and the server for which a ticket is requested is +the server named in the accompanying ticket, then the KDC will decrypt the +ticket in the authentication header using the key of the server for which +it was issued. If no ticket can be found in the padata field, the +KDC_ERR_PADATA_TYPE_NOSUPP error is returned. + +Once the accompanying ticket has been decrypted, the user-supplied checksum +in the Authenticator must be verified against the contents of the request, +and the message rejected if the checksums do not match (with an error code +of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not +collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the +checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is +returned. If the authorization-data are present, they are decrypted using +the sub-session key from the Authenticator. + +If any of the decryptions indicate failed integrity checks, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. + +3.3.3. Generation of KRB_TGS_REP message + +The KRB_TGS_REP message shares its format with the KRB_AS_REP +(KRB_KDC_REP), but with its type field set to KRB_TGS_REP. The detailed +specification is in section 5.4.2. + +The response will include a ticket for the requested server. The Kerberos +database is queried to retrieve the record for the requested server +(including the key with which the ticket will be encrypted). If the request +is for a ticket granting ticket for a remote realm, and if no key is shared +with the requested realm, then the Kerberos server will select the realm +"closest" to the requested realm with which it does share a key, and use +that realm instead. This is the only case where the response from the KDC +will be for a different server than that requested by the client. + +By default, the address field, the client's name and realm, the list of +transited realms, the time of initial authentication, the expiration time, +and the authorization data of the newly-issued ticket will be copied from +the ticket-granting ticket (TGT) or renewable ticket. If the transited +field needs to be updated, but the transited type is not supported, the +KDC_ERR_TRTYPE_NOSUPP error is returned. + +If the request specifies an endtime, then the endtime of the new ticket is +set to the minimum of (a) that request, (b) the endtime from the TGT, and +(c) the starttime of the TGT plus the minimum of the maximum life for the +application server and the maximum life for the local realm (the maximum +life for the requesting principal was already applied when the TGT was +issued). If the new ticket is to be a renewal, then the endtime above is +replaced by the minimum of (a) the value of the renew_till field of the +ticket and (b) the starttime for the new ticket plus the life +(endtime-starttime) of the old ticket. + +If the FORWARDED option has been requested, then the resulting ticket will +contain the addresses specified by the client. This option will only be +honored if the FORWARDABLE flag is set in the TGT. The PROXY option is +similar; the resulting ticket will contain the addresses specified by the +client. It will be honored only if the PROXIABLE flag in the TGT is set. +The PROXY option will not be honored on requests for additional +ticket-granting tickets. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified or the MAY-POSTDATE flag is not set in the TGT, then the +error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the +ticket-granting ticket has the MAY-POSTDATE flag set, then the resulting +ticket will be postdated and the requested starttime is checked against the +policy of the local realm. If acceptable, the ticket's start time is set as +requested, and the INVALID flag is set. The postdated ticket must be +validated before use by presenting it to the KDC after the starttime has +been reached. However, in no case may the starttime, endtime, or renew-till +time of a newly-issued postdated ticket extend beyond the renew-till time +of the ticket-granting ticket. + +If the ENC-TKT-IN-SKEY option has been specified and an additional ticket +has been included in the request, the KDC will decrypt the additional +ticket using the key for the server to which the additional ticket was +issued and verify that it is a ticket-granting ticket. If the name of the +requested server is missing from the request, the name of the client in the +additional ticket will be used. Otherwise the name of the requested server +will be compared to the name of the client in the additional ticket and if +different, the request will be rejected. If the request succeeds, the +session key from the additional ticket will be used to encrypt the new +ticket that is issued instead of using the key of the server for which the +new ticket will be used[17]. + +If the name of the server in the ticket that is presented to the KDC as +part of the authentication header is not that of the ticket-granting server +itself, the server is registered in the realm of the KDC, and the RENEW +option is requested, then the KDC will verify that the RENEWABLE flag is +set in the ticket, that the INVALID flag is not set in the ticket, and that +the renew_till time is still in the future. If the VALIDATE option is +rqeuested, the KDC will check that the starttime has passed and the INVALID +flag is set. If the PROXY option is requested, then the KDC will check that +the PROXIABLE flag is set in the ticket. If the tests succeed, and the +ticket passes the hotlist check described in the next paragraph, the KDC +will issue the appropriate new ticket. + +3.3.3.1. Checking for revoked tickets + +Whenever a request is made to the ticket-granting server, the presented +ticket(s) is(are) checked against a hot-list of tickets which have been +canceled. This hot-list might be implemented by storing a range of issue +timestamps for 'suspect tickets'; if a presented ticket had an authtime in +that range, it would be rejected. In this way, a stolen ticket-granting +ticket or renewable ticket cannot be used to gain additional tickets +(renewals or otherwise) once the theft has been reported. Any normal ticket +obtained before it was reported stolen will still be valid (because they +require no interaction with the KDC), but only until their normal +expiration time. + +The ciphertext part of the response in the KRB_TGS_REP message is encrypted +in the sub-session key from the Authenticator, if present, or the session +key key from the ticket-granting ticket. It is not encrypted using the +client's secret key. Furthermore, the client's key's expiration date and +the key version number fields are left out since these values are stored +along with the client's database record, and that record is not needed to + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +satisfy a request based on a ticket-granting ticket. See section A.6 for +pseudocode. + +3.3.3.2. Encoding the transited field + +If the identity of the server in the TGT that is presented to the KDC as +part of the authentication header is that of the ticket-granting service, +but the TGT was issued from another realm, the KDC will look up the +inter-realm key shared with that realm and use that key to decrypt the +ticket. If the ticket is valid, then the KDC will honor the request, +subject to the constraints outlined above in the section describing the AS +exchange. The realm part of the client's identity will be taken from the +ticket-granting ticket. The name of the realm that issued the +ticket-granting ticket will be added to the transited field of the ticket +to be issued. This is accomplished by reading the transited field from the +ticket-granting ticket (which is treated as an unordered set of realm +names), adding the new realm to the set, then constructing and writing out +its encoded (shorthand) form (this may involve a rearrangement of the +existing encoding). + +Note that the ticket-granting service does not add the name of its own +realm. Instead, its responsibility is to add the name of the previous +realm. This prevents a malicious Kerberos server from intentionally leaving +out its own name (it could, however, omit other realms' names). + +The names of neither the local realm nor the principal's realm are to be +included in the transited field. They appear elsewhere in the ticket and +both are known to have taken part in authenticating the principal. Since +the endpoints are not included, both local and single-hop inter-realm +authentication result in a transited field that is empty. + +Because the name of each realm transited is added to this field, it might +potentially be very long. To decrease the length of this field, its +contents are encoded. The initially supported encoding is optimized for the +normal case of inter-realm communication: a hierarchical arrangement of +realms using either domain or X.500 style realm names. This encoding +(called DOMAIN-X500-COMPRESS) is now described. + +Realm names in the transited field are separated by a ",". The ",", "\", +trailing "."s, and leading spaces (" ") are special characters, and if they +are part of a realm name, they must be quoted in the transited field by +preced- ing them with a "\". + +A realm name ending with a "." is interpreted as being prepended to the +previous realm. For example, we can encode traversal of EDU, MIT.EDU, +ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: + + "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". + +Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that +they would not be included in this field, and we would have: + + "EDU,MIT.,WASHINGTON.EDU" + +A realm name beginning with a "/" is interpreted as being appended to the +previous realm[18]. If it is to stand by itself, then it should be preceded +by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, +/COM/HP, /COM, and /COM/DEC as: + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + "/COM,/HP,/APOLLO, /COM/DEC". + +Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they +they would not be included in this field, and we would have: + + "/COM,/HP" + +A null subfield preceding or following a "," indicates that all realms +between the previous realm and the next realm have been traversed[19]. +Thus, "," means that all realms along the path between the client and the +server have been traversed. ",EDU, /COM," means that that all realms from +the client's realm up to EDU (in a domain style hierarchy) have been +traversed, and that everything from /COM down to the server's realm in an +X.500 style has also been traversed. This could occur if the EDU realm in +one hierarchy shares an inter-realm key directly with the /COM realm in +another hierarchy. + +3.3.4. Receipt of KRB_TGS_REP message + +When the KRB_TGS_REP is received by the client, it is processed in the same +manner as the KRB_AS_REP processing described above. The primary difference +is that the ciphertext part of the response must be decrypted using the +session key from the ticket-granting ticket rather than the client's secret +key. See section A.7 for pseudocode. + +3.4. The KRB_SAFE Exchange + +The KRB_SAFE message may be used by clients requiring the ability to detect +modifications of messages they exchange. It achieves this by including a +keyed collision-proof checksum of the user data and some control +information. The checksum is keyed with an encryption key (usually the last +key negotiated via subkeys, or the session key if no negotiation has +occured). + +3.4.1. Generation of a KRB_SAFE message + +When an application wishes to send a KRB_SAFE message, it collects its data +and the appropriate control information and computes a checksum over them. +The checksum algorithm should be a keyed one-way hash function (such as the +RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES +MAC), generated using the sub-session key if present, or the session key. +Different algorithms may be selected by changing the checksum type in the +message. Unkeyed or non-collision-proof checksums are not suitable for this +use. + +The control information for the KRB_SAFE message includes both a timestamp +and a sequence number. The designer of an application using the KRB_SAFE +message must choose at least one of the two mechanisms. This choice should +be based on the needs of the application protocol. + +Sequence numbers are useful when all messages sent will be received by +one's peer. Connection state is presently required to maintain the session +key, so maintaining the next sequence number should not present an +additional problem. + +If the application protocol is expected to tolerate lost messages without +them being resent, the use of the timestamp is the appropriate replay +detection mechanism. Using timestamps is also the appropriate mechanism for +multi-cast protocols where all of one's peers share a common sub-session + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +key, but some messages will be sent to a subset of one's peers. + +After computing the checksum, the client then transmits the information and +checksum to the recipient in the message format specified in section 5.6.1. + +3.4.2. Receipt of KRB_SAFE message + +When an application receives a KRB_SAFE message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + +The message is first checked by verifying that the protocol version and +type fields match the current version and KRB_SAFE, respectively. A +mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. +The application verifies that the checksum used is a collision-proof keyed +checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. +The recipient verifies that the operating system's report of the sender's +address matches the sender's address in the message, and (if a recipient +address is specified or the recipient requires an address) that one of the +recipient's addresses appears as the recipient's address in the message. A +failed match for either case generates a KRB_AP_ERR_BADADDR error. Then the +timestamp and usec and/or the sequence number fields are checked. If +timestamp and usec are expected and not present, or they are present but +not current, the KRB_AP_ERR_SKEW error is generated. If the server name, +along with the client name, time and microsecond fields from the +Authenticator match any recently-seen (sent or received[20] ) such tuples, +the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence number +is included, or a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or +a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. +Finally, the checksum is computed over the data and control information, +and if it doesn't match the received checksum, a KRB_AP_ERR_MODIFIED error +is generated. + +If all the checks succeed, the application is assured that the message was +generated by its peer and was not modi- fied in transit. + +3.5. The KRB_PRIV Exchange + +The KRB_PRIV message may be used by clients requiring confidentiality and +the ability to detect modifications of exchanged messages. It achieves this +by encrypting the messages and adding control information. + +3.5.1. Generation of a KRB_PRIV message + +When an application wishes to send a KRB_PRIV message, it collects its data +and the appropriate control information (specified in section 5.7.1) and +encrypts them under an encryption key (usually the last key negotiated via +subkeys, or the session key if no negotiation has occured). As part of the +control information, the client must choose to use either a timestamp or a +sequence number (or both); see the discussion in section 3.4.1 for +guidelines on which to use. After the user data and control information are +encrypted, the client transmits the ciphertext and some 'envelope' +information to the recipient. + +3.5.2. Receipt of KRB_PRIV message + +When an application receives a KRB_PRIV message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +The message is first checked by verifying that the protocol version and +type fields match the current version and KRB_PRIV, respectively. A +mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. +The application then decrypts the ciphertext and processes the resultant +plaintext. If decryption shows the data to have been modified, a +KRB_AP_ERR_BAD_INTEGRITY error is generated. The recipient verifies that +the operating system's report of the sender's address matches the sender's +address in the message, and (if a recipient address is specified or the +recipient requires an address) that one of the recipient's addresses +appears as the recipient's address in the message. A failed match for +either case generates a KRB_AP_ERR_BADADDR error. Then the timestamp and +usec and/or the sequence number fields are checked. If timestamp and usec +are expected and not present, or they are present but not current, the +KRB_AP_ERR_SKEW error is generated. If the server name, along with the +client name, time and microsecond fields from the Authenticator match any +recently-seen such tuples, the KRB_AP_ERR_REPEAT error is generated. If an +incorrect sequence number is included, or a sequence number is expected but +not present, the KRB_AP_ERR_BADORDER error is generated. If neither a +time-stamp and usec or a sequence number is present, a KRB_AP_ERR_MODIFIED +error is generated. + +If all the checks succeed, the application can assume the message was +generated by its peer, and was securely transmitted (without intruders able +to see the unencrypted contents). + +3.6. The KRB_CRED Exchange + +The KRB_CRED message may be used by clients requiring the ability to send +Kerberos credentials from one host to another. It achieves this by sending +the tickets together with encrypted data containing the session keys and +other information associated with the tickets. + +3.6.1. Generation of a KRB_CRED message + +When an application wishes to send a KRB_CRED message it first (using the +KRB_TGS exchange) obtains credentials to be sent to the remote host. It +then constructs a KRB_CRED message using the ticket or tickets so obtained, +placing the session key needed to use each ticket in the key field of the +corresponding KrbCredInfo sequence of the encrypted part of the the +KRB_CRED message. + +Other information associated with each ticket and obtained during the +KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence +in the encrypted part of the KRB_CRED message. The current time and, if +specifically required by the application the nonce, s-address, and +r-address fields, are placed in the encrypted part of the KRB_CRED message +which is then encrypted under an encryption key previosuly exchanged in the +KRB_AP exchange (usually the last key negotiated via subkeys, or the +session key if no negotiation has occured). + +3.6.2. Receipt of KRB_CRED message + +When an application receives a KRB_CRED message, it verifies it. If any +error occurs, an error code is reported for use by the application. The +message is verified by checking that the protocol version and type fields +match the current version and KRB_CRED, respectively. A mismatch generates +a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then +decrypts the ciphertext and processes the resultant plaintext. If +decryption shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +error is generated. + +If present or required, the recipient verifies that the operating system's +report of the sender's address matches the sender's address in the message, +and that one of the recipient's addresses appears as the recipient's +address in the message. A failed match for either case generates a +KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce +field if required) are checked next. If the timestamp and usec are not +present, or they are present but not current, the KRB_AP_ERR_SKEW error is +generated. + +If all the checks succeed, the application stores each of the new tickets +in its ticket cache together with the session key and other information in +the corresponding KrbCredInfo sequence from the encrypted part of the +KRB_CRED message. + +4. The Kerberos Database + +The Kerberos server must have access to a database contain- ing the +principal identifiers and secret keys of principals to be +authenticated[21]. + +4.1. Database contents + +A database entry should contain at least the following fields: + +Field Value + +name Principal's identifier +key Principal's secret key +p_kvno Principal's key version +max_life Maximum lifetime for Tickets +max_renewable_life Maximum total lifetime for renewable Tickets + +The name field is an encoding of the principal's identifier. The key field +contains an encryption key. This key is the principal's secret key. (The +key can be encrypted before storage under a Kerberos "master key" to +protect it in case the database is compromised but the master key is not. +In that case, an extra field must be added to indicate the master key +version used, see below.) The p_kvno field is the key version number of the +principal's secret key. The max_life field contains the maximum allowable +lifetime (endtime - starttime) for any Ticket issued for this principal. +The max_renewable_life field contains the maximum allowable total lifetime +for any renewable Ticket issued for this principal. (See section 3.1 for a +description of how these lifetimes are used in determining the lifetime of +a given Ticket.) + +A server may provide KDC service to several realms, as long as the database +representation provides a mechanism to distinguish between principal +records with identifiers which differ only in the realm name. + +When an application server's key changes, if the change is routine (i.e. +not the result of disclosure of the old key), the old key should be +retained by the server until all tickets that had been issued using that +key have expired. Because of this, it is possible for several keys to be +active for a single principal. Ciphertext encrypted in a principal's key is +always tagged with the version of the key that was used for encryption, to +help the recipient find the proper key for decryption. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +When more than one key is active for a particular principal, the principal +will have more than one record in the Kerberos database. The keys and key +version numbers will differ between the records (the rest of the fields may +or may not be the same). Whenever Kerberos issues a ticket, or responds to +a request for initial authentication, the most recent key (known by the +Kerberos server) will be used for encryption. This is the key with the +highest key version number. + +4.2. Additional fields + +Project Athena's KDC implementation uses additional fields in its database: + +Field Value + +K_kvno Kerberos' key version +expiration Expiration date for entry +attributes Bit field of attributes +mod_date Timestamp of last modification +mod_name Modifying principal's identifier + +The K_kvno field indicates the key version of the Kerberos master key under +which the principal's secret key is encrypted. + +After an entry's expiration date has passed, the KDC will return an error +to any client attempting to gain tickets as or for the principal. (A +database may want to maintain two expiration dates: one for the principal, +and one for the principal's current key. This allows password aging to work +independently of the principal's expiration date. However, due to the +limited space in the responses, the KDC must combine the key expiration and +principal expiration date into a single value called 'key_exp', which is +used as a hint to the user to take administrative action.) + +The attributes field is a bitfield used to govern the operations involving +the principal. This field might be useful in conjunction with user +registration procedures, for site-specific policy implementations (Project +Athena currently uses it for their user registration process controlled by +the system-wide database service, Moira [LGDSR87]), to identify whether a +principal can play the role of a client or server or both, to note whether +a server is appropriate trusted to recieve credentials delegated by a +client, or to identify the 'string to key' conversion algorithm used for a +principal's key[22]. Other bits are used to indicate that certain ticket +options should not be allowed in tickets encrypted under a principal's key +(one bit each): Disallow issuing postdated tickets, disallow issuing +forwardable tickets, disallow issuing tickets based on TGT authentication, +disallow issuing renewable tickets, disallow issuing proxiable tickets, and +disallow issuing tickets for which the principal is the server. + +The mod_date field contains the time of last modification of the entry, and +the mod_name field contains the name of the principal which last modified +the entry. + +4.3. Frequently Changing Fields + +Some KDC implementations may wish to maintain the last time that a request +was made by a particular principal. Information that might be maintained +includes the time of the last request, the time of the last request for a +ticket-granting ticket, the time of the last use of a ticket-granting +ticket, or other times. This information can then be returned to the user +in the last-req field (see section 5.2). + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +Other frequently changing information that can be maintained is the latest +expiration time for any tickets that have been issued using each key. This +field would be used to indicate how long old keys must remain valid to +allow the continued use of outstanding tickets. + +4.4. Site Constants + +The KDC implementation should have the following configurable constants or +options, to allow an administrator to make and enforce policy decisions: + + * The minimum supported lifetime (used to determine whether the + KDC_ERR_NEVER_VALID error should be returned). This constant should + reflect reasonable expectations of round-trip time to the KDC, + encryption/decryption time, and processing time by the client and + target server, and it should allow for a minimum 'useful' lifetime. + * The maximum allowable total (renewable) lifetime of a ticket + (renew_till - starttime). + * The maximum allowable lifetime of a ticket (endtime - starttime). + * Whether to allow the issue of tickets with empty address fields + (including the ability to specify that such tickets may only be issued + if the request specifies some authorization_data). + * Whether proxiable, forwardable, renewable or post-datable tickets are + to be issued. + +5. Message Specifications + +The following sections describe the exact contents and encoding of protocol +messages and objects. The ASN.1 base definitions are presented in the first +subsection. The remaining subsections specify the protocol objects (tickets +and authenticators) and messages. Specification of encryption and checksum +techniques, and the fields related to them, appear in section 6. + +Optional field in ASN.1 sequences + +For optional integer value and date fields in ASN.1 sequences where a +default value has been specified, certain default values will not be +allowed in the encoding because these values will always be represented +through defaulting by the absence of the optional field. For example, one +will not send a microsecond zero value because one must make sure that +there is only one way to encode this value. + +Additional fields in ASN.1 sequences + +Implementations receiving Kerberos messages with additional fields present +in ASN.1 sequences should carry the those fields through unmodified when +the message is forwarded. Implementation should drop such fields if the +sequence is reencoded. + +5.1. ASN.1 Distinguished Encoding Representation + +All uses of ASN.1 in Kerberos shall use the Distinguished Encoding +Representation of the data elements as described in the X.509 +specification, section 8.7 [X509-88]. + +5.3. ASN.1 Base Definitions + +The following ASN.1 base definitions are used in the rest of this section. +Note that since the underscore character (_) is not permitted in ASN.1 + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +names, the hyphen (-) is used in its place for the purposes of ASN.1 names. + +Realm ::= GeneralString +PrincipalName ::= SEQUENCE { + name-type[0] INTEGER, + name-string[1] SEQUENCE OF GeneralString +} + +Kerberos realms are encoded as GeneralStrings. Realms shall not contain a +character with the code 0 (the ASCII NUL). Most realms will usually consist +of several components separated by periods (.), in the style of Internet +Domain Names, or separated by slashes (/) in the style of X.500 names. +Acceptable forms for realm names are specified in section 7. A +PrincipalName is a typed sequence of components consisting of the following +sub-fields: + +name-type + This field specifies the type of name that follows. Pre-defined values + for this field are specified in section 7.2. The name-type should be + treated as a hint. Ignoring the name type, no two names can be the + same (i.e. at least one of the components, or the realm, must be + different). This constraint may be eliminated in the future. +name-string + This field encodes a sequence of components that form a name, each + component encoded as a GeneralString. Taken together, a PrincipalName + and a Realm form a principal identifier. Most PrincipalNames will have + only a few components (typically one or two). + +KerberosTime ::= GeneralizedTime + -- Specifying UTC time zone (Z) + +The timestamps used in Kerberos are encoded as GeneralizedTimes. An +encoding shall specify the UTC time zone (Z) and shall not include any +fractional portions of the seconds. It further shall not include any +separators. Example: The only valid format for UTC time 6 minutes, 27 +seconds after 9 pm on 6 November 1985 is 19851106210627Z. + +HostAddress ::= SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING +} + +HostAddresses ::= SEQUENCE OF HostAddress + +The host adddress encodings consists of two fields: + +addr-type + This field specifies the type of address that follows. Pre-defined + values for this field are specified in section 8.1. +address + This field encodes a single address of type addr-type. + +The two forms differ slightly. HostAddress contains exactly one address; +HostAddresses contains a sequence of possibly many addresses. + +AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type[0] INTEGER, + ad-data[1] OCTET STRING +} + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +ad-data + This field contains authorization data to be interpreted according to + the value of the corresponding ad-type field. +ad-type + This field specifies the format for the ad-data subfield. All negative + values are reserved for local use. Non-negative values are reserved + for registered use. + +Each sequence of type and data is refered to as an authorization element. +Elements may be application specific, however, there is a common set of +recursive elements that should be understood by all implementations. These +elements contain other elements embedded within them, and the +interpretation of the encapsulating element determines which of the +embedded elements must be interpreted, and which may be ignored. +Definitions for these common elements may be found in Appendix B. + +TicketExtensions ::= SEQUENCE OF SEQUENCE { + te-type[0] INTEGER, + te-data[1] OCTET STRING +} + + + +te-data + This field contains opaque data that must be caried with the ticket to + support extensions to the Kerberos protocol including but not limited + to some forms of inter-realm key exchange and plaintext authorization + data. See appendix C for some common uses of this field. +te-type + This field specifies the format for the te-data subfield. All negative + values are reserved for local use. Non-negative values are reserved + for registered use. + +APOptions ::= BIT STRING + -- reserved(0), + -- use-session-key(1), + -- mutual-required(2) + +TicketFlags ::= BIT STRING + -- reserved(0), + -- forwardable(1), + -- forwarded(2), + -- proxiable(3), + -- proxy(4), + -- may-postdate(5), + -- postdated(6), + -- invalid(7), + -- renewable(8), + -- initial(9), + -- pre-authent(10), + -- hw-authent(11), + -- transited-policy-checked(12), + -- ok-as-delegate(13) + +KDCOptions ::= BIT STRING + -- reserved(0), + -- forwardable(1), + -- forwarded(2), + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + -- proxiable(3), + -- proxy(4), + -- allow-postdate(5), + -- postdated(6), + -- unused7(7), + -- renewable(8), + -- unused9(9), + -- unused10(10), + -- unused11(11), + -- unused12(12), + -- unused13(13), + -- disable-transited-check(26), + -- renewable-ok(27), + -- enc-tkt-in-skey(28), + -- renew(30), + -- validate(31) + +ASN.1 Bit strings have a length and a value. When used in Kerberos for the +APOptions, TicketFlags, and KDCOptions, the length of the bit string on +generated values should be the smallest number of bits needed to include +the highest order bit that is set (1), but in no case less than 32 bits. +The ASN.1 representation of the bit strings uses unnamed bits, with the +meaning of the individual bits defined by the comments in the specification +above. Implementations should accept values of bit strings of any length +and treat the value of flags corresponding to bits beyond the end of the +bit string as if the bit were reset (0). Comparison of bit strings of +different length should treat the smaller string as if it were padded with +zeros beyond the high order bits to the length of the longer string[23]. + +LastReq ::= SEQUENCE OF SEQUENCE { + lr-type[0] INTEGER, + lr-value[1] KerberosTime +} + +lr-type + This field indicates how the following lr-value field is to be + interpreted. Negative values indicate that the information pertains + only to the responding server. Non-negative values pertain to all + servers for the realm. If the lr-type field is zero (0), then no + information is conveyed by the lr-value subfield. If the absolute + value of the lr-type field is one (1), then the lr-value subfield is + the time of last initial request for a TGT. If it is two (2), then the + lr-value subfield is the time of last initial request. If it is three + (3), then the lr-value subfield is the time of issue for the newest + ticket-granting ticket used. If it is four (4), then the lr-value + subfield is the time of the last renewal. If it is five (5), then the + lr-value subfield is the time of last request (of any type). If it is + (6), then the lr-value subfield is the time when the password will + expire. +lr-value + This field contains the time of the last request. the time must be + interpreted according to the contents of the accompanying lr-type + subfield. + +See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, +EncryptionKey, EncryptionType, and KeyType. + +5.3. Tickets and Authenticators + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +This section describes the format and encryption parameters for tickets and +authenticators. When a ticket or authenticator is included in a protocol +message it is treated as an opaque object. + +5.3.1. Tickets + +A ticket is a record that helps a client authenticate to a service. A +Ticket contains the following information: + +Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno[0] INTEGER, + realm[1] Realm, + sname[2] PrincipalName, + enc-part[3] EncryptedData, + extensions[4] TicketExtensions OPTIONAL +} + +-- Encrypted part of ticket +EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL +} +-- encoded Transited field +TransitedEncoding ::= SEQUENCE { + tr-type[0] INTEGER, -- must be +registered + contents[1] OCTET STRING +} + +The encoding of EncTicketPart is encrypted in the key shared by Kerberos +and the end server (the server's secret key). See section 6 for the format +of the ciphertext. + +tkt-vno + This field specifies the version number for the ticket format. This + document describes version number 5. +realm + This field specifies the realm that issued a ticket. It also serves to + identify the realm part of the server's principal identifier. Since a + Kerberos server can only issue tickets for servers within its realm, + the two will always be identical. +sname + This field specifies the name part of the server's identity. +enc-part + This field holds the encrypted encoding of the EncTicketPart sequence. +extensions + This optional field contains a sequence of extentions that may be used + to carry information that must be carried with the ticket to support + several extensions, including but not limited to plaintext + authorization data, tokens for exchanging inter-realm keys, and other + information that must be associated with a ticket for use by the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + application server. See Appendix C for definitions of some common + extensions. + + Note that some older versions of Kerberos did not support this field. + Because this is an optional field it will not break older clients, but + older clients might strip this field from the ticket before sending it + to the application server. This limits the usefulness of this ticket + field to environments where the ticket will not be parsed and + reconstructed by these older Kerberos clients. + + If it is known that the client will strip this field from the ticket, + as an interim measure the KDC may append this field to the end of the + enc-part of the ticket and append a traler indicating the lenght of + the appended extensions field. (this paragraph is open for discussion, + including the form of the traler). +flags + This field indicates which of various options were used or requested + when the ticket was issued. It is a bit-field, where the selected + options are indicated by the bit being set (1), and the unselected + options and reserved fields being reset (0). Bit 0 is the most + significant bit. The encoding of the bits is specified in section 5.2. + The flags are described in more detail above in section 2. The + meanings of the flags are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. When set, this + flag tells the ticket-granting server + that it is OK to issue a new ticket- + granting ticket with a different network + address based on the presented ticket. + + 2 FORWARDED + When set, this flag indicates that the + ticket has either been forwarded or was + issued based on authentication involving + a forwarded ticket-granting ticket. + + 3 PROXIABLE + The PROXIABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. The PROXIABLE + flag has an interpretation identical to + that of the FORWARDABLE flag, except + that the PROXIABLE flag tells the + ticket-granting server that only non- + ticket-granting tickets may be issued + with different network addresses. + + 4 PROXY + When set, this flag indicates that a + ticket is a proxy. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + 5 MAY-POSTDATE + The MAY-POSTDATE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. This flag tells + the ticket-granting server that a post- + dated ticket may be issued based on this + ticket-granting ticket. + + 6 POSTDATED + This flag indicates that this ticket has + been postdated. The end-service can + check the authtime field to see when the + original authentication occurred. + + 7 INVALID + This flag indicates that a ticket is + invalid, and it must be validated by the + KDC before use. Application servers + must reject tickets which have this flag + set. + + 8 RENEWABLE + The RENEWABLE flag is normally only + interpreted by the TGS, and can usually + be ignored by end servers (some particu- + larly careful servers may wish to disal- + low renewable tickets). A renewable + ticket can be used to obtain a replace- + ment ticket that expires at a later + date. + + 9 INITIAL + This flag indicates that this ticket was + issued using the AS protocol, and not + issued based on a ticket-granting + ticket. + + 10 PRE-AUTHENT + This flag indicates that during initial + authentication, the client was authenti- + cated by the KDC before a ticket was + issued. The strength of the pre- + authentication method is not indicated, + but is acceptable to the KDC. + + 11 HW-AUTHENT + This flag indicates that the protocol + employed for initial authentication + required the use of hardware expected to + be possessed solely by the named client. + The hardware authentication method is + selected by the KDC and the strength of + the method is not indicated. + + 12 TRANSITED This flag indicates that the KDC for the + POLICY-CHECKED realm has checked the transited field + against a realm defined policy for + trusted certifiers. If this flag is + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + reset (0), then the application server + must check the transited field itself, + and if unable to do so it must reject + the authentication. If the flag is set + (1) then the application server may skip + its own validation of the transited + field, relying on the validation + performed by the KDC. At its option the + application server may still apply its + own validation based on a separate + policy for acceptance. + + 13 OK-AS-DELEGATE This flag indicates that the server (not + the client) specified in the ticket has + been determined by policy of the realm + to be a suitable recipient of + delegation. A client can use the + presence of this flag to help it make a + decision whether to delegate credentials + (either grant a proxy or a forwarded + ticket granting ticket) to this server. + The client is free to ignore the value + of this flag. When setting this flag, + an administrator should consider the + Security and placement of the server on + which the service will run, as well as + whether the service requires the use of + delegated credentials. + + 14 ANONYMOUS + This flag indicates that the principal + named in the ticket is a generic princi- + pal for the realm and does not identify + the individual using the ticket. The + purpose of the ticket is only to + securely distribute a session key, and + not to identify the user. Subsequent + requests using the same ticket and ses- + sion may be considered as originating + from the same user, but requests with + the same username but a different ticket + are likely to originate from different + users. + + 15-31 RESERVED + Reserved for future use. + +key + This field exists in the ticket and the KDC response and is used to + pass the session key from Kerberos to the application server and the + client. The field's encoding is described in section 6.2. +crealm + This field contains the name of the realm in which the client is + registered and in which initial authentication took place. +cname + This field contains the name part of the client's principal + identifier. +transited + This field lists the names of the Kerberos realms that took part in + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + authenticating the user to whom this ticket was issued. It does not + specify the order in which the realms were transited. See section + 3.3.3.2 for details on how this field encodes the traversed realms. + When the names of CA's are to be embedded inthe transited field (as + specified for some extentions to the protocol), the X.500 names of the + CA's should be mapped into items in the transited field using the + mapping defined by RFC2253. +authtime + This field indicates the time of initial authentication for the named + principal. It is the time of issue for the original ticket on which + this ticket is based. It is included in the ticket to provide + additional information to the end service, and to provide the + necessary information for implementation of a `hot list' service at + the KDC. An end service that is particularly paranoid could refuse to + accept tickets for which the initial authentication occurred "too far" + in the past. This field is also returned as part of the response from + the KDC. When returned as part of the response to initial + authentication (KRB_AS_REP), this is the current time on the Ker- + beros server[24]. +starttime + This field in the ticket specifies the time after which the ticket is + valid. Together with endtime, this field specifies the life of the + ticket. If it is absent from the ticket, its value should be treated + as that of the authtime field. +endtime + This field contains the time after which the ticket will not be + honored (its expiration time). Note that individual services may place + their own limits on the life of a ticket and may reject tickets which + have not yet expired. As such, this is really an upper bound on the + expiration time for the ticket. +renew-till + This field is only present in tickets that have the RENEWABLE flag set + in the flags field. It indicates the maximum endtime that may be + included in a renewal. It can be thought of as the absolute expiration + time for the ticket, including all renewals. +caddr + This field in a ticket contains zero (if omitted) or more (if present) + host addresses. These are the addresses from which the ticket can be + used. If there are no addresses, the ticket can be used from any + location. The decision by the KDC to issue or by the end server to + accept zero-address tickets is a policy decision and is left to the + Kerberos and end-service administrators; they may refuse to issue or + accept such tickets. The suggested and default policy, however, is + that such tickets will only be issued or accepted when additional + information that can be used to restrict the use of the ticket is + included in the authorization_data field. Such a ticket is a + capability. + + Network addresses are included in the ticket to make it harder for an + attacker to use stolen credentials. Because the session key is not + sent over the network in cleartext, credentials can't be stolen simply + by listening to the network; an attacker has to gain access to the + session key (perhaps through operating system security breaches or a + careless user's unattended session) to make use of stolen tickets. + + It is important to note that the network address from which a + connection is received cannot be reliably determined. Even if it could + be, an attacker who has compromised the client's worksta- tion could + use the credentials from there. Including the network addresses only + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + makes it more difficult, not impossible, for an attacker to walk off + with stolen credentials and then use them from a "safe" location. +authorization-data + The authorization-data field is used to pass authorization data from + the principal on whose behalf a ticket was issued to the application + service. If no authorization data is included, this field will be left + out. Experience has shown that the name of this field is confusing, + and that a better name for this field would be restrictions. + Unfortunately, it is not possible to change the name of this field at + this time. + + This field contains restrictions on any authority obtained on the + basis of authentication using the ticket. It is possible for any + principal in posession of credentials to add entries to the + authorization data field since these entries further restrict what can + be done with the ticket. Such additions can be made by specifying the + additional entries when a new ticket is obtained during the TGS + exchange, or they may be added during chained delegation using the + authorization data field of the authenticator. + + Because entries may be added to this field by the holder of + credentials, it is not allowable for the presence of an entry in the + authorization data field of a ticket to amplify the priveleges one + would obtain from using a ticket. + + The data in this field may be specific to the end service; the field + will contain the names of service specific objects, and the rights to + those objects. The format for this field is described in section 5.2. + Although Kerberos is not concerned with the format of the contents of + the sub-fields, it does carry type information (ad-type). + + By using the authorization_data field, a principal is able to issue a + proxy that is valid for a specific purpose. For example, a client + wishing to print a file can obtain a file server proxy to be passed to + the print server. By specifying the name of the file in the + authorization_data field, the file server knows that the print server + can only use the client's rights when accessing the particular file to + be printed. + + A separate service providing authorization or certifying group + membership may be built using the authorization-data field. In this + case, the entity granting authorization (not the authorized entity), + obtains a ticket in its own name (e.g. the ticket is issued in the + name of a privelege server), and this entity adds restrictions on its + own authority and delegates the restricted authority through a proxy + to the client. The client would then present this authorization + credential to the application server separately from the + authentication exchange. + + Similarly, if one specifies the authorization-data field of a proxy + and leaves the host addresses blank, the resulting ticket and session + key can be treated as a capability. See [Neu93] for some suggested + uses of this field. + + The authorization-data field is optional and does not have to be + included in a ticket. + +5.3.2. Authenticators + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +An authenticator is a record sent with a ticket to a server to certify the +client's knowledge of the encryption key in the ticket, to help the server +detect replays, and to help choose a "true session key" to use with the +particular session. The encoding is encrypted in the ticket's session key +shared by the client and the server: + +-- Unencrypted authenticator +Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL +} + + +authenticator-vno + This field specifies the version number for the format of the + authenticator. This document specifies version 5. +crealm and cname + These fields are the same as those described for the ticket in section + 5.3.1. +cksum + This field contains a checksum of the the applica- tion data that + accompanies the KRB_AP_REQ. +cusec + This field contains the microsecond part of the client's timestamp. + Its value (before encryption) ranges from 0 to 999999. It often + appears along with ctime. The two fields are used together to specify + a reasonably accurate timestamp. +ctime + This field contains the current time on the client's host. +subkey + This field contains the client's choice for an encryption key which is + to be used to protect this specific application session. Unless an + application specifies otherwise, if this field is left out the session + key from the ticket will be used. +seq-number + This optional field includes the initial sequence number to be used by + the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to + detect replays (It may also be used by application specific messages). + When included in the authenticator this field specifies the initial + sequence number for messages from the client to the server. When + included in the AP-REP message, the initial sequence number is that + for messages from the server to the client. When used in KRB_PRIV or + KRB_SAFE messages, it is incremented by one after each message is + sent. Sequence numbers fall in the range of 0 through 2^32 - 1 and + wrap to zero following the value 2^32 - 1. + + For sequence numbers to adequately support the detection of replays + they should be non-repeating, even across connection boundaries. The + initial sequence number should be random and uniformly distributed + across the full space of possible sequence numbers, so that it cannot + be guessed by an attacker and so that it and the successive sequence + numbers do not repeat other sequences. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +authorization-data + This field is the same as described for the ticket in section 5.3.1. + It is optional and will only appear when additional restrictions are + to be placed on the use of a ticket, beyond those carried in the + ticket itself. + +5.4. Specifications for the AS and TGS exchanges + +This section specifies the format of the messages used in the exchange +between the client and the Kerberos server. The format of possible error +messages appears in section 5.9.1. + +5.4.1. KRB_KDC_REQ definition + +The KRB_KDC_REQ message has no type of its own. Instead, its type is one of +KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an +initial ticket or an additional ticket. In either case, the message is sent +from the client to the Authentication Server to request credentials for a +service. + +The message fields are: + +AS-REQ ::= [APPLICATION 10] KDC-REQ +TGS-REQ ::= [APPLICATION 12] KDC-REQ + +KDC-REQ ::= SEQUENCE { + pvno[1] INTEGER, + msg-type[2] INTEGER, + padata[3] SEQUENCE OF PA-DATA OPTIONAL, + req-body[4] KDC-REQ-BODY +} + +PA-DATA ::= SEQUENCE { + padata-type[1] INTEGER, + padata-value[2] OCTET STRING, + -- might be encoded AP-REQ +} + +KDC-REQ-BODY ::= SEQUENCE { + kdc-options[0] KDCOptions, + cname[1] PrincipalName OPTIONAL, + -- Used only in AS-REQ + realm[2] Realm, -- Server's realm + -- Also client's in AS-REQ + sname[3] PrincipalName OPTIONAL, + from[4] KerberosTime OPTIONAL, + till[5] KerberosTime OPTIONAL, + rtime[6] KerberosTime OPTIONAL, + nonce[7] INTEGER, + etype[8] SEQUENCE OF INTEGER, + -- EncryptionType, + -- in preference order + addresses[9] HostAddresses OPTIONAL, + enc-authorization-data[10] EncryptedData OPTIONAL, + -- Encrypted AuthorizationData + -- encoding + additional-tickets[11] SEQUENCE OF Ticket OPTIONAL +} + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +The fields in this message are: + +pvno + This field is included in each message, and specifies the protocol + version number. This document specifies protocol version 5. +msg-type + This field indicates the type of a protocol message. It will almost + always be the same as the application identifier associated with a + message. It is included to make the identifier more readily accessible + to the application. For the KDC-REQ message, this type will be + KRB_AS_REQ or KRB_TGS_REQ. +padata + The padata (pre-authentication data) field contains a sequence of + authentication information which may be needed before credentials can + be issued or decrypted. In the case of requests for additional tickets + (KRB_TGS_REQ), this field will include an element with padata-type of + PA-TGS-REQ and data of an authentication header (ticket-granting + ticket and authenticator). The checksum in the authenticator (which + must be collision-proof) is to be computed over the KDC-REQ-BODY + encoding. In most requests for initial authentication (KRB_AS_REQ) and + most replies (KDC-REP), the padata field will be left out. + + This field may also contain information needed by certain extensions + to the Kerberos protocol. For example, it might be used to initially + verify the identity of a client before any response is returned. This + is accomplished with a padata field with padata-type equal to + PA-ENC-TIMESTAMP and padata-value defined as follows: + + padata-type ::= PA-ENC-TIMESTAMP + padata-value ::= EncryptedData -- PA-ENC-TS-ENC + + PA-ENC-TS-ENC ::= SEQUENCE { + patimestamp[0] KerberosTime, -- client's time + pausec[1] INTEGER OPTIONAL + } + + with patimestamp containing the client's time and pausec containing + the microseconds which may be omitted if a client will not generate + more than one request per second. The ciphertext (padata-value) + consists of the PA-ENC-TS-ENC sequence, encrypted using the client's + secret key. + + [use-specified-kvno item is here for discussion and may be removed] It + may also be used by the client to specify the version of a key that is + being used for accompanying preauthentication, and/or which should be + used to encrypt the reply from the KDC. + + PA-USE-SPECIFIED-KVNO ::= Integer + + The KDC should only accept and abide by the value of the + use-specified-kvno preauthentication data field when the specified key + is still valid and until use of a new key is confirmed. This situation + is likely to occur primarily during the period during which an updated + key is propagating to other KDC's in a realm. + + The padata field can also contain information needed to help the KDC + or the client select the key needed for generating or decrypting the + response. This form of the padata is useful for supporting the use of + certain token cards with Kerberos. The details of such extensions are + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + specified in separate documents. See [Pat92] for additional uses of + this field. +padata-type + The padata-type element of the padata field indicates the way that the + padata-value element is to be interpreted. Negative values of + padata-type are reserved for unregistered use; non-negative values are + used for a registered interpretation of the element type. +req-body + This field is a placeholder delimiting the extent of the remaining + fields. If a checksum is to be calculated over the request, it is + calculated over an encoding of the KDC-REQ-BODY sequence which is + enclosed within the req-body field. +kdc-options + This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the + KDC and indicates the flags that the client wants set on the tickets + as well as other information that is to modify the behavior of the + KDC. Where appropriate, the name of an option may be the same as the + flag that is set by that option. Although in most case, the bit in the + options field will be the same as that in the flags field, this is not + guaranteed, so it is not acceptable to simply copy the options field + to the flags field. There are various checks that must be made before + honoring an option anyway. + + The kdc_options field is a bit-field, where the selected options are + indicated by the bit being set (1), and the unselected options and + reserved fields being reset (0). The encoding of the bits is specified + in section 5.2. The options are described in more detail above in + section 2. The meanings of the options are: + + Bit(s) Name Description + 0 RESERVED + Reserved for future expansion of +this + field. + + 1 FORWARDABLE + The FORWARDABLE option indicates +that + the ticket to be issued is to have +its + forwardable flag set. It may only +be + set on the initial request, or in a +sub- + sequent request if the +ticket-granting + ticket on which it is based is also +for- + wardable. + + 2 FORWARDED + The FORWARDED option is only +specified + in a request to the +ticket-granting + server and will only be honored if +the + ticket-granting ticket in the +request + has its FORWARDABLE bit set. +This + option indicates that this is a +request + for forwarding. The address(es) of +the + host from which the resulting ticket +is + to be valid are included in +the + addresses field of the request. + + 3 PROXIABLE + The PROXIABLE option indicates that +the + ticket to be issued is to have its +prox- + iable flag set. It may only be set +on + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + the initial request, or in a +subsequent + request if the ticket-granting ticket +on + which it is based is also proxiable. + + 4 PROXY + The PROXY option indicates that this +is + a request for a proxy. This option +will + only be honored if the +ticket-granting + ticket in the request has its +PROXIABLE + bit set. The address(es) of the +host + from which the resulting ticket is to +be + valid are included in the +addresses + field of the request. + + 5 ALLOW-POSTDATE + The ALLOW-POSTDATE option indicates +that + the ticket to be issued is to have +its + MAY-POSTDATE flag set. It may only +be + set on the initial request, or in a +sub- + sequent request if the +ticket-granting + ticket on which it is based also has +its + MAY-POSTDATE flag set. + + 6 POSTDATED + The POSTDATED option indicates that +this + is a request for a postdated +ticket. + This option will only be honored if +the + ticket-granting ticket on which + it is based has its MAY-POSTDATE + flag set. + The resulting ticket will also have +its + INVALID flag set, and that flag may +be + reset by a subsequent request to the +KDC + after the starttime in the ticket +has + been reached. + + 7 UNUSED + This option is presently unused. + + 8 RENEWABLE + The RENEWABLE option indicates that +the + ticket to be issued is to have +its + RENEWABLE flag set. It may only be +set + on the initial request, or when +the + ticket-granting ticket on which +the + request is based is also renewable. +If + this option is requested, then the +rtime + field in the request contains +the + desired absolute expiration time for +the + ticket. + + 9-13 UNUSED + These options are presently unused. + + 14 REQUEST-ANONYMOUS + The REQUEST-ANONYMOUS option +indicates + that the ticket to be issued is not +to + identify the user to which it +was + issued. Instead, the principal +identif- + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + ier is to be generic, as specified +by + the policy of the realm (e.g. +usually + anonymous@realm). The purpose of +the + ticket is only to securely distribute +a + session key, and not to identify +the + user. The ANONYMOUS flag on the +ticket + to be returned should be set. If +the + local realms policy does not +permit + anonymous credentials, the request is +to + be rejected. + + 15-25 RESERVED + Reserved for future use. + + 26 DISABLE-TRANSITED-CHECK + By default the KDC will check the + transited field of a ticket-granting- + ticket against the policy of the local + realm before it will issue derivative + tickets based on the ticket granting + ticket. If this flag is set in the + request, checking of the transited +field + is disabled. Tickets issued without +the + performance of this check will be +noted + by the reset (0) value of the + TRANSITED-POLICY-CHECKED flag, + indicating to the application server + that the tranisted field must be +checked + locally. KDC's are encouraged but not + required to honor the + DISABLE-TRANSITED-CHECK option. + + 27 RENEWABLE-OK + The RENEWABLE-OK option indicates that +a + renewable ticket will be acceptable if +a + ticket with the requested life +cannot + otherwise be provided. If a ticket +with + the requested life cannot be +provided, + then a renewable ticket may be +issued + with a renew-till equal to the +the + requested endtime. The value of +the + renew-till field may still be limited +by + local limits, or limits selected by +the + individual principal or server. + + 28 ENC-TKT-IN-SKEY + This option is used only by the +ticket- + granting service. The +ENC-TKT-IN-SKEY + option indicates that the ticket for +the + end server is to be encrypted in +the + session key from the additional +ticket- + granting ticket provided. + + 29 RESERVED + Reserved for future use. + + 30 RENEW + This option is used only by the +ticket- + granting service. The RENEW +option + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + indicates that the present request +is + for a renewal. The ticket provided +is + encrypted in the secret key for +the + server on which it is valid. +This + option will only be honored if +the + ticket to be renewed has its +RENEWABLE + flag set and if the time in its +renew- + till field has not passed. The +ticket + to be renewed is passed in the +padata + field as part of the +authentication + header. + + 31 VALIDATE + This option is used only by the +ticket- + granting service. The VALIDATE +option + indicates that the request is to +vali- + date a postdated ticket. It will +only + be honored if the ticket presented +is + postdated, presently has its +INVALID + flag set, and would be otherwise +usable + at this time. A ticket cannot be +vali- + dated before its starttime. The +ticket + presented for validation is encrypted +in + the key of the server for which it +is + valid and is passed in the padata +field + as part of the authentication header. + +cname and sname + These fields are the same as those described for the ticket in section + 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is + specified. If absent, the name of the server is taken from the name of + the client in the ticket passed as additional-tickets. +enc-authorization-data + The enc-authorization-data, if present (and it can only be present in + the TGS_REQ form), is an encoding of the desired authorization-data + encrypted under the sub-session key if present in the Authenticator, + or alternatively from the session key in the ticket-granting ticket, + both from the padata field in the KRB_AP_REQ. +realm + This field specifies the realm part of the server's principal + identifier. In the AS exchange, this is also the realm part of the + client's principal identifier. +from + This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket + requests when the requested ticket is to be postdated. It specifies + the desired start time for the requested ticket. If this field is + omitted then the KDC should use the current time instead. +till + This field contains the expiration date requested by the client in a + ticket request. It is optional and if omitted the requested ticket is + to have the maximum endtime permitted according to KDC policy for the + parties to the authentication exchange as limited by expiration date + of the ticket granting ticket or other preauthentication credentials. +rtime + This field is the requested renew-till time sent from a client to the + KDC in a ticket request. It is optional. +nonce + This field is part of the KDC request and response. It it intended to + hold a random number generated by the client. If the same number is + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + included in the encrypted response from the KDC, it provides evidence + that the response is fresh and has not been replayed by an attacker. + Nonces must never be re-used. Ideally, it should be generated + randomly, but if the correct time is known, it may suffice[25]. +etype + This field specifies the desired encryption algorithm to be used in + the response. +addresses + This field is included in the initial request for tickets, and + optionally included in requests for additional tickets from the + ticket-granting server. It specifies the addresses from which the + requested ticket is to be valid. Normally it includes the addresses + for the client's host. If a proxy is requested, this field will + contain other addresses. The contents of this field are usually copied + by the KDC into the caddr field of the resulting ticket. +additional-tickets + Additional tickets may be optionally included in a request to the + ticket-granting server. If the ENC-TKT-IN-SKEY option has been + specified, then the session key from the additional ticket will be + used in place of the server's key to encrypt the new ticket. If more + than one option which requires additional tickets has been specified, + then the additional tickets are used in the order specified by the + ordering of the options bits (see kdc-options, above). + +The application code will be either ten (10) or twelve (12) depending on +whether the request is for an initial ticket (AS-REQ) or for an additional +ticket (TGS-REQ). + +The optional fields (addresses, authorization-data and additional-tickets) +are only included if necessary to perform the operation specified in the +kdc-options field. + +It should be noted that in KRB_TGS_REQ, the protocol version number appears +twice and two different message types appear: the KRB_TGS_REQ message +contains these fields as does the authentication header (KRB_AP_REQ) that +is passed in the padata field. + +5.4.2. KRB_KDC_REP definition + +The KRB_KDC_REP message format is used for the reply from the KDC for +either an initial (AS) request or a subsequent (TGS) request. There is no +message type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP +or KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply +depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in +the client's secret key, and the client's key version number is included in +the key version number for the encrypted data. For KRB_TGS_REP, the +ciphertext is encrypted in the sub-session key from the Authenticator, or +if absent, the session key from the ticket-granting ticket used in the +request. In that case, no version number will be present in the +EncryptedData sequence. + +The KRB_KDC_REP message contains the following fields: + +AS-REP ::= [APPLICATION 11] KDC-REP +TGS-REP ::= [APPLICATION 13] KDC-REP + +KDC-REP ::= SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + padata[2] SEQUENCE OF PA-DATA OPTIONAL, + crealm[3] Realm, + cname[4] PrincipalName, + ticket[5] Ticket, + enc-part[6] EncryptedData +} + +EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart +EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart + +EncKDCRepPart ::= SEQUENCE { + key[0] EncryptionKey, + last-req[1] LastReq, + nonce[2] INTEGER, + key-expiration[3] KerberosTime OPTIONAL, + flags[4] TicketFlags, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + srealm[9] Realm, + sname[10] PrincipalName, + caddr[11] HostAddresses OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is either + KRB_AS_REP or KRB_TGS_REP. +padata + This field is described in detail in section 5.4.1. One possible use + for this field is to encode an alternate "mix-in" string to be used + with a string-to-key algorithm (such as is described in section + 6.3.2). This ability is useful to ease transitions if a realm name + needs to change (e.g. when a company is acquired); in such a case all + existing password-derived entries in the KDC database would be flagged + as needing a special mix-in string until the next password change. +crealm, cname, srealm and sname + These fields are the same as those described for the ticket in section + 5.3.1. +ticket + The newly-issued ticket, from section 5.3.1. +enc-part + This field is a place holder for the ciphertext and related + information that forms the encrypted part of a message. The + description of the encrypted part of the message follows each + appearance of this field. The encrypted part is encoded as described + in section 6.1. +key + This field is the same as described for the ticket in section 5.3.1. +last-req + This field is returned by the KDC and specifies the time(s) of the + last request by a principal. Depending on what information is + available, this might be the last time that a request for a + ticket-granting ticket was made, or the last time that a request based + on a ticket-granting ticket was successful. It also might cover all + servers for a realm, or just the particular server. Some + implementations may display this information to the user to aid in + discovering unauthorized use of one's identity. It is similar in + spirit to the last login time displayed when logging into timesharing + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + systems. +nonce + This field is described above in section 5.4.1. +key-expiration + The key-expiration field is part of the response from the KDC and + specifies the time that the client's secret key is due to expire. The + expiration might be the result of password aging or an account + expiration. This field will usually be left out of the TGS reply since + the response to the TGS request is encrypted in a session key and no + client information need be retrieved from the KDC database. It is up + to the application client (usually the login program) to take + appropriate action (such as notifying the user) if the expiration time + is imminent. +flags, authtime, starttime, endtime, renew-till and caddr + These fields are duplicates of those found in the encrypted portion of + the attached ticket (see section 5.3.1), provided so the client may + verify they match the intended request and to assist in proper ticket + caching. If the message is of type KRB_TGS_REP, the caddr field will + only be filled in if the request was for a proxy or forwarded ticket, + or if the user is substituting a subset of the addresses from the + ticket granting ticket. If the client-requested addresses are not + present or not used, then the addresses contained in the ticket will + be the same as those included in the ticket-granting ticket. + +5.5. Client/Server (CS) message specifications + +This section specifies the format of the messages used for the +authentication of the client to the application server. + +5.5.1. KRB_AP_REQ definition + +The KRB_AP_REQ message contains the Kerberos protocol version number, the +message type KRB_AP_REQ, an options field to indicate any options in use, +and the ticket and authenticator themselves. The KRB_AP_REQ message is +often referred to as the 'authentication header'. + +AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData +} + +APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) +} + + + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REQ. +ap-options + This field appears in the application request (KRB_AP_REQ) and affects + the way the request is processed. It is a bit-field, where the + selected options are indicated by the bit being set (1), and the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + unselected options and reserved fields being reset (0). The encoding + of the bits is specified in section 5.2. The meanings of the options + are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of +this + field. + + 1 USE-SESSION-KEY + The USE-SESSION-KEY option +indicates + that the ticket the client is +presenting + to a server is encrypted in the +session + key from the server's +ticket-granting + ticket. When this option is not +speci- + fied, the ticket is encrypted in +the + server's secret key. + + 2 MUTUAL-REQUIRED + The MUTUAL-REQUIRED option tells +the + server that the client requires +mutual + authentication, and that it must +respond + with a KRB_AP_REP message. + + 3-31 RESERVED + Reserved for future use. + +ticket + This field is a ticket authenticating the client to the server. +authenticator + This contains the authenticator, which includes the client's choice of + a subkey. Its encoding is described in section 5.3.2. + +5.5.2. KRB_AP_REP definition + +The KRB_AP_REP message contains the Kerberos protocol version number, the +message type, and an encrypted time- stamp. The message is sent in in +response to an application request (KRB_AP_REQ) where the mutual +authentication option has been selected in the ap-options field. + +AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[2] EncryptedData +} + +EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { + ctime[0] KerberosTime, + cusec[1] INTEGER, + subkey[2] EncryptionKey OPTIONAL, + seq-number[3] INTEGER OPTIONAL +} + +The encoded EncAPRepPart is encrypted in the shared session key of the +ticket. The optional subkey field can be used in an application-arranged +negotiation to choose a per association session key. + +pvno and msg-type + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REP. +enc-part + This field is described above in section 5.4.2. +ctime + This field contains the current time on the client's host. +cusec + This field contains the microsecond part of the client's timestamp. +subkey + This field contains an encryption key which is to be used to protect + this specific application session. See section 3.2.6 for specifics on + how this field is used to negotiate a key. Unless an application + specifies otherwise, if this field is left out, the sub-session key + from the authenticator, or if also left out, the session key from the + ticket will be used. + +5.5.3. Error message reply + +If an error occurs while processing the application request, the KRB_ERROR +message will be sent in response. See section 5.9.1 for the format of the +error message. The cname and crealm fields may be left out if the server +cannot determine their appropriate values from the corresponding KRB_AP_REQ +message. If the authenticator was decipherable, the ctime and cusec fields +will contain the values from it. + +5.6. KRB_SAFE message specification + +This section specifies the format of a message that can be used by either +side (client or server) of an application to send a tamper-proof message to +its peer. It presumes that a session key has previously been exchanged (for +example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.6.1. KRB_SAFE definition + +The KRB_SAFE message contains user data along with a collision-proof +checksum keyed with the last encryption key negotiated via subkeys, or the +session key if no negotiation has occured. The message fields are: + +KRB-SAFE ::= [APPLICATION 20] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + safe-body[2] KRB-SAFE-BODY, + cksum[3] Checksum +} + +KRB-SAFE-BODY ::= SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_SAFE. +safe-body + This field is a placeholder for the body of the KRB-SAFE message. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +cksum + This field contains the checksum of the application data. Checksum + details are described in section 6.4. The checksum is computed over + the encoding of the KRB-SAFE sequence. First, the cksum is zeroed and + the checksum is computed over the encoding of the KRB-SAFE sequence, + then the checksum is set to the result of that computation, and + finally the KRB-SAFE sequence is encoded again. +user-data + This field is part of the KRB_SAFE and KRB_PRIV messages and contain + the application specific data that is being passed from the sender to + the recipient. +timestamp + This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents + are the current time as known by the sender of the message. By + checking the timestamp, the recipient of the message is able to make + sure that it was recently generated, and is not a replay. +usec + This field is part of the KRB_SAFE and KRB_PRIV headers. It contains + the microsecond part of the timestamp. +seq-number + This field is described above in section 5.3.2. +s-address + This field specifies the address in use by the sender of the message. +r-address + This field specifies the address in use by the recipient of the + message. It may be omitted for some uses (such as broadcast + protocols), but the recipient may arbitrarily reject such messages. + This field along with s-address can be used to help detect messages + which have been incorrectly or maliciously delivered to the wrong + recipient. + +5.7. KRB_PRIV message specification + +This section specifies the format of a message that can be used by either +side (client or server) of an application to securely and privately send a +message to its peer. It presumes that a session key has previously been +exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.7.1. KRB_PRIV definition + +The KRB_PRIV message contains user data encrypted in the Session Key. The +message fields are: + +KRB-PRIV ::= [APPLICATION 21] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[3] EncryptedData +} + +EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, -- sender's +addr + r-address[5] HostAddress OPTIONAL -- recip's +addr +} + +pvno and msg-type + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + These fields are described above in section 5.4.1. msg-type is + KRB_PRIV. +enc-part + This field holds an encoding of the EncKrbPrivPart sequence encrypted + under the session key[32]. This encrypted encoding is used for the + enc-part field of the KRB-PRIV message. See section 6 for the format + of the ciphertext. +user-data, timestamp, usec, s-address and r-address + These fields are described above in section 5.6.1. +seq-number + This field is described above in section 5.3.2. + +5.8. KRB_CRED message specification + +This section specifies the format of a message that can be used to send +Kerberos credentials from one principal to another. It is presented here to +encourage a common mechanism to be used by applications when forwarding +tickets or providing proxies to subordinate servers. It presumes that a +session key has already been exchanged perhaps by using the +KRB_AP_REQ/KRB_AP_REP messages. + +5.8.1. KRB_CRED definition + +The KRB_CRED message contains a sequence of tickets to be sent and +information needed to use the tickets, including the session key from each. +The information needed to use the tickets is encrypted under an encryption +key previously exchanged or transferred alongside the KRB_CRED message. The +message fields are: + +KRB-CRED ::= [APPLICATION 22] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, -- KRB_CRED + tickets[2] SEQUENCE OF Ticket, + enc-part[3] EncryptedData +} + +EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { + ticket-info[0] SEQUENCE OF KrbCredInfo, + nonce[1] INTEGER OPTIONAL, + timestamp[2] KerberosTime OPTIONAL, + usec[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +KrbCredInfo ::= SEQUENCE { + key[0] EncryptionKey, + prealm[1] Realm OPTIONAL, + pname[2] PrincipalName OPTIONAL, + flags[3] TicketFlags OPTIONAL, + authtime[4] KerberosTime OPTIONAL, + starttime[5] KerberosTime OPTIONAL, + endtime[6] KerberosTime OPTIONAL + renew-till[7] KerberosTime OPTIONAL, + srealm[8] Realm OPTIONAL, + sname[9] PrincipalName OPTIONAL, + caddr[10] HostAddresses OPTIONAL +} + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_CRED. +tickets + These are the tickets obtained from the KDC specifically for use by + the intended recipient. Successive tickets are paired with the + corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED + message. +enc-part + This field holds an encoding of the EncKrbCredPart sequence encrypted + under the session key shared between the sender and the intended + recipient. This encrypted encoding is used for the enc-part field of + the KRB-CRED message. See section 6 for the format of the ciphertext. +nonce + If practical, an application may require the inclusion of a nonce + generated by the recipient of the message. If the same value is + included as the nonce in the message, it provides evidence that the + message is fresh and has not been replayed by an attacker. A nonce + must never be re-used; it should be generated randomly by the + recipient of the message and provided to the sender of the message in + an application specific manner. +timestamp and usec + These fields specify the time that the KRB-CRED message was generated. + The time is used to provide assurance that the message is fresh. +s-address and r-address + These fields are described above in section 5.6.1. They are used + optionally to provide additional assurance of the integrity of the + KRB-CRED message. +key + This field exists in the corresponding ticket passed by the KRB-CRED + message and is used to pass the session key from the sender to the + intended recipient. The field's encoding is described in section 6.2. + +The following fields are optional. If present, they can be associated with +the credentials in the remote ticket file. If left out, then it is assumed +that the recipient of the credentials already knows their value. + +prealm and pname + The name and realm of the delegated principal identity. +flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr + These fields contain the values of the correspond- ing fields from the + ticket found in the ticket field. Descriptions of the fields are + identical to the descriptions in the KDC-REP message. + +5.9. Error message specification + +This section specifies the format for the KRB_ERROR message. The fields +included in the message are intended to return as much information as +possible about an error. It is not expected that all the information +required by the fields will be available for all types of errors. If the +appropriate information is not available when the message is composed, the +corresponding field will be left out of the message. + +Note that since the KRB_ERROR message is not protected by any encryption, +it is quite possible for an intruder to synthesize or modify such a +message. In particular, this means that the client should not use any +fields in this message for security-critical purposes, such as setting a +system clock or generating a fresh authenticator. The message can be +useful, however, for advising a user on the reason for some failure. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +5.9.1. KRB_ERROR definition + +The KRB_ERROR message consists of the following fields: + +KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL, + e-cksum[13] Checksum OPTIONAL, + e-typed-data[14] SEQUENCE of ETypedData +OPTIONAL +} + +ETypedData ::= SEQUENCE { + e-data-type [1] INTEGER, + e-data-value [2] OCTET STRING, +} + + + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_ERROR. +ctime + This field is described above in section 5.4.1. +cusec + This field is described above in section 5.5.2. +stime + This field contains the current time on the server. It is of type + KerberosTime. +susec + This field contains the microsecond part of the server's timestamp. + Its value ranges from 0 to 999999. It appears along with stime. The + two fields are used in conjunction to specify a reasonably accurate + timestamp. +error-code + This field contains the error code returned by Kerberos or the server + when a request fails. To interpret the value of this field see the + list of error codes in section 8. Implementations are encouraged to + provide for national language support in the display of error + messages. +crealm, cname, srealm and sname + These fields are described above in section 5.3.1. +e-text + This field contains additional text to help explain the error code + associated with the failed request (for example, it might include a + principal name which was unknown). +e-data + This field contains additional data about the error for use by the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + application to help it recover from or handle the error. If the + errorcode is KDC_ERR_PREAUTH_REQUIRED, then the e-data field will + contain an encoding of a sequence of padata fields, each corresponding + to an acceptable pre-authentication method and optionally containing + data for the method: + + METHOD-DATA ::= SEQUENCE of PA-DATA + + If the error-code is KRB_AP_ERR_METHOD, then the e-data field will + contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type[0] INTEGER, + method-data[1] OCTET STRING OPTIONAL + } + + method-type will indicate the required alternate method; method-data + will contain any required additional information. +e-cksum + This field contains an optional checksum for the KRB-ERROR message. + The checksum is calculated over the Kerberos ASN.1 encoding of the + KRB-ERROR message with the checksum absent. The checksum is then added + to the KRB-ERROR structure and the message is re-encoded. The Checksum + should be calculated using the session key from the ticket granting + ticket or service ticket, where available. If the error is in response + to a TGS or AP request, the checksum should be calculated uing the the + session key from the client's ticket. If the error is in response to + an AS request, then the checksum should be calulated using the + client's secret key ONLY if there has been suitable preauthentication + to prove knowledge of the secret key by the client[33]. If a checksum + can not be computed because the key to be used is not available, no + checksum will be included. +e-typed-data + [This field for discussion, may be deleted from final spec] This field + contains optional data that may be used to help the client recover + from the indicated error. [This could contain the METHOD-DATA + specified since I don't think anyone actually uses it yet. It could + also contain the PA-DATA sequence for the preauth required error if we + had a clear way to transition to the use of this field from the use of + the untype e-data field.] For example, this field may specify the key + version of the key used to verify preauthentication: + + e-data-type := 20 -- Key version number + e-data-value := Integer -- Key version number used to verify +preauthentication + +6. Encryption and Checksum Specifications + +The Kerberos protocols described in this document are designed to use +stream encryption ciphers, which can be simulated using commonly available +block encryption ciphers, such as the Data Encryption Standard, [DES77] in +conjunction with block chaining and checksum methods [DESM80]. Encryption +is used to prove the identities of the network entities participating in +message exchanges. The Key Distribution Center for each realm is trusted by +all principals registered in that realm to store a secret key in +confidence. Proof of knowledge of this secret key is used to verify the +authenticity of a principal. + +The KDC uses the principal's secret key (in the AS exchange) or a shared +session key (in the TGS exchange) to encrypt responses to ticket requests; + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +the ability to obtain the secret key or session key implies the knowledge +of the appropriate keys and the identity of the KDC. The ability of a +principal to decrypt the KDC response and present a Ticket and a properly +formed Authenticator (generated with the session key from the KDC response) +to a service verifies the identity of the principal; likewise the ability +of the service to extract the session key from the Ticket and prove its +knowledge thereof in a response verifies the identity of the service. + +The Kerberos protocols generally assume that the encryption used is secure +from cryptanalysis; however, in some cases, the order of fields in the +encrypted portions of messages are arranged to minimize the effects of +poorly chosen keys. It is still important to choose good keys. If keys are +derived from user-typed passwords, those passwords need to be well chosen +to make brute force attacks more difficult. Poorly chosen keys still make +easy targets for intruders. + +The following sections specify the encryption and checksum mechanisms +currently defined for Kerberos. The encodings, chaining, and padding +requirements for each are described. For encryption methods, it is often +desirable to place random information (often referred to as a confounder) +at the start of the message. The requirements for a confounder are +specified with each encryption mechanism. + +Some encryption systems use a block-chaining method to improve the the +security characteristics of the ciphertext. However, these chaining methods +often don't provide an integrity check upon decryption. Such systems (such +as DES in CBC mode) must be augmented with a checksum of the plain-text +which can be verified at decryption and used to detect any tampering or +damage. Such checksums should be good at detecting burst errors in the +input. If any damage is detected, the decryption routine is expected to +return an error indicating the failure of an integrity check. Each +encryption type is expected to provide and verify an appropriate checksum. +The specification of each encryption method sets out its checksum +requirements. + +Finally, where a key is to be derived from a user's password, an algorithm +for converting the password to a key of the appropriate type is included. +It is desirable for the string to key function to be one-way, and for the +mapping to be different in different realms. This is important because +users who are registered in more than one realm will often use the same +password in each, and it is desirable that an attacker compromising the +Kerberos server in one realm not obtain or derive the user's key in +another. + +For an discussion of the integrity characteristics of the candidate +encryption and checksum methods considered for Kerberos, the the reader is +referred to [SG92]. + +6.1. Encryption Specifications + +The following ASN.1 definition describes all encrypted messages. The +enc-part field which appears in the unencrypted part of messages in section +5 is a sequence consisting of an encryption type, an optional key version +number, and the ciphertext. + +EncryptedData ::= SEQUENCE { + etype[0] INTEGER, -- EncryptionType + kvno[1] INTEGER OPTIONAL, + cipher[2] OCTET STRING -- ciphertext + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +} + + + +etype + This field identifies which encryption algorithm was used to encipher + the cipher. Detailed specifications for selected encryption types + appear later in this section. +kvno + This field contains the version number of the key under which data is + encrypted. It is only present in messages encrypted under long lasting + keys, such as principals' secret keys. +cipher + This field contains the enciphered text, encoded as an OCTET STRING. + +The cipher field is generated by applying the specified encryption +algorithm to data composed of the message and algorithm-specific inputs. +Encryption mechanisms defined for use with Kerberos must take sufficient +measures to guarantee the integrity of the plaintext, and we recommend they +also take measures to protect against precomputed dictionary attacks. If +the encryption algorithm is not itself capable of doing so, the protections +can often be enhanced by adding a checksum and a confounder. + +The suggested format for the data to be encrypted includes a confounder, a +checksum, the encoded plaintext, and any necessary padding. The msg-seq +field contains the part of the protocol message described in section 5 +which is to be encrypted. The confounder, checksum, and padding are all +untagged and untyped, and their length is exactly sufficient to hold the +appropriate item. The type and length is implicit and specified by the +particular encryption type being used (etype). The format for the data to +be encrypted is described in the following diagram: + + +-----------+----------+-------------+-----+ + |confounder | check | msg-seq | pad | + +-----------+----------+-------------+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +CipherText ::= ENCRYPTED SEQUENCE { + confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, + check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, + msg-seq[2] MsgSequence, + pad UNTAGGED OCTET STRING(pad_length) OPTIONAL +} + +One generates a random confounder of the appropriate length, placing it in +confounder; zeroes out check; calculates the appropriate checksum over +confounder, check, and msg-seq, placing the result in check; adds the +necessary padding; then encrypts using the specified encryption type and +the appropriate key. + +Unless otherwise specified, a definition of an encryption algorithm that +specifies a checksum, a length for the confounder field, or an octet +boundary for padding uses this ciphertext format[36]. Those fields which +are not specified will be omitted. + +In the interest of allowing all implementations using a particular +encryption type to communicate with all others using that type, the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +specification of an encryption type defines any checksum that is needed as +part of the encryption process. If an alternative checksum is to be used, a +new encryption type must be defined. + +Some cryptosystems require additional information beyond the key and the +data to be encrypted. For example, DES, when used in cipher-block-chaining +mode, requires an initialization vector. If required, the description for +each encryption type must specify the source of such additional +information. 6.2. Encryption Keys + +The sequence below shows the encoding of an encryption key: + + EncryptionKey ::= SEQUENCE { + keytype[0] INTEGER, + keyvalue[1] OCTET STRING + } + +keytype + This field specifies the type of encryption key that follows in the + keyvalue field. It will almost always correspond to the encryption + algorithm used to generate the EncryptedData, though more than one + algorithm may use the same type of key (the mapping is many to one). + This might happen, for example, if the encryption algorithm uses an + alternate checksum algorithm for an integrity check, or a different + chaining mechanism. +keyvalue + This field contains the key itself, encoded as an octet string. + +All negative values for the encryption key type are reserved for local use. +All non-negative values are reserved for officially assigned type fields +and interpreta- tions. + +6.3. Encryption Systems + +6.3.1. The NULL Encryption System (null) + +If no encryption is in use, the encryption system is said to be the NULL +encryption system. In the NULL encryption system there is no checksum, +confounder or padding. The ciphertext is simply the plaintext. The NULL Key +is used by the null encryption system and is zero octets in length, with +keytype zero (0). + +6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) + +The des-cbc-crc encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +A CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the +confounder and message sequence (msg-seq) and placed in the cksum field. +DES blocks are 8 bytes. As a result, the data to be encrypted (the +concatenation of confounder, checksum, and message) must be padded to an 8 +byte boundary before encryption. The details of the encryption of this data +are identical to those for the des-cbc-md5 encryption mode. + +Note that, since the CRC-32 checksum is not collision-proof, an attacker +could use a probabilistic chosen-plaintext attack to generate a valid +message even if a confounder is used [SG92]. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. The use of the CRC-32 as the checksum for ticket or +authenticator is no longer mandated as an interoperability requirement for + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +Kerberos Version 5 Specification 1 (See section 9.1 for specific details). + +6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) + +The des-cbc-md4 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD4 checksum (described in [MD492]) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. The details of the encryption of this data are identical +to those for the des-cbc-md5 encryption mode. + +6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) + +The des-cbc-md5 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD5 checksum (described in [MD5-92].) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. + +Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are +concatenated to make the 64-bit inputs for the DES algorithms. The first +octet supplies the 8 most significant bits (with the octet's MSbit used as +the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., +and the eighth octet supplies the 8 least significant bits. + +Encryption under DES using cipher block chaining requires an additional +input in the form of an initialization vector. Unless otherwise specified, +zero should be used as the initialization vector. Kerberos' use of DES +requires an 8 octet confounder. + +The DES specifications identify some 'weak' and 'semi-weak' keys; those +keys shall not be used for encrypting messages for use in Kerberos. +Additionally, because of the way that keys are derived for the encryption +of checksums, keys shall not be used that yield 'weak' or 'semi-weak' keys +when eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. + +A DES key is 8 octets of data, with keytype one (1). This consists of 56 +bits of key, and 8 parity bits (one per octet). The key is encoded as a +series of 8 octets written in MSB-first order. The bits within the key are +also encoded in MSB order. For example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where +B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the +parity bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 +as the MSbit). [See the FIPS 81 introduction for reference.] + +String to key transformation + +To generate a DES key from a text string (password), a "salt" is +concatenated to the text string, and then padded with ASCII nulls to an 8 +byte boundary. This "salt" is normally the realm and each component of the +principal's name appended. However, sometimes different salts are used --- +for example, when a realm is renamed, or if a user changes her username, or +for compatibility with Kerberos V4 (whose string-to-key algorithm uses a +null string for the salt). This string is then fan-folded and +eXclusive-ORed with itself to form an 8 byte DES key. Before + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +eXclusive-ORing a block, every byte is shifted one bit to the left to leave +the lowest bit zero. The key is the "corrected" by correcting the parity on +the key, and if the key matches a 'weak' or 'semi-weak' key as described in +the DES specification, it is eXclusive-ORed with the constant +00000000000000F0. This key is then used to generate a DES CBC checksum on +the initial string (with the salt appended). The result of the CBC checksum +is the "corrected" as described above to form the result which is return as +the key. Pseudocode follows: + + name_to_default_salt(realm, name) { + s = realm + for(each component in name) { + s = s + component; + } + return s; + } + + key_correction(key) { + fixparity(key); + if (is_weak_key_key(key)) + key = key XOR 0xF0; + return(key); + } + + string_to_key(string,salt) { + + odd = 1; + s = string + salt; + tempkey = NULL; + pad(s); /* with nulls to 8 byte boundary */ + for(8byteblock in s) { + if(odd == 0) { + odd = 1; + reverse(8byteblock) + } + else odd = 0; + left shift every byte in 8byteblock one bit; + tempkey = tempkey XOR 8byteblock; + } + tempkey = key_correction(tempkey); + key = key_correction(DES-CBC-check(s,tempkey)); + return(key); + } + +6.3.5. Triple DES with HMAC-SHA1 Kerberos Encryption Type with Key +Derivation [Horowitz] + +NOTE: This description currently refers to documents, the contents of which +might be bettered included by value in this spec. The description below was +provided by Marc Horowitz, and the form in which it will finally appear is +yet to be determined. This description is included in this version of the +draft because it does describe the implemenation ready for use with the MIT +implementation. Note also that the encryption identifier has been left +unspecified here because the value from Marc Horowitz's spec conflicted +with some other impmenentations implemented based on perevious versions of +the specification. + +This encryption type is based on the Triple DES cryptosystem, the HMAC-SHA1 +[Krawczyk96] message authentication algorithm, and key derivation for + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +Kerberos V5 [HorowitzB96]. + +The des3-cbc-hmac-sha1 encryption type has been assigned the value ??. The +hmac-sha1-des3 checksum type has been assigned the value 12. + +Encryption Type des3-cbc-hmac-sha1 + +EncryptedData using this type must be generated as described in +[Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC mode. The +keyed hash algorithm is HMAC-SHA1. Unless otherwise specified, a zero IV +must be used. If the length of the input data is not a multiple of the +block size, zero octets must be used to pad the plaintext to the next +eight-octet boundary. The counfounder must be eight random octets (one +block). + +Checksum Type hmac-sha1-des3 + +Checksums using this type must be generated as described in [Horowitz96]. +The keyed hash algorithm is HMAC-SHA1. + +Common Requirements + +The EncryptionKey value is 24 octets long. The 7 most significant bits of +each octet contain key bits, and the least significant bit is the inverse +of the xor of the key bits. + +For the purposes of key derivation, the block size is 64 bits, and the key +size is 168 bits. The 168 bits output by key derivation are converted to an +EncryptionKey value as follows. First, the 168 bits are divided into three +groups of 56 bits, which are expanded individually into 64 bits as follows: + + 1 2 3 4 5 6 7 p + 9 10 11 12 13 14 15 p +17 18 19 20 21 22 23 p +25 26 27 28 29 30 31 p +33 34 35 36 37 38 39 p +41 42 43 44 45 46 47 p +49 50 51 52 53 54 55 p +56 48 40 32 24 16 8 p + +The "p" bits are parity bits computed over the data bits. The output of the +three expansions are concatenated to form the EncryptionKey value. + +When the HMAC-SHA1 of a string is computed, the key is used in the +EncryptedKey form. + +Key Derivation + +In the Kerberos protocol, cryptographic keys are used in a number of +places. In order to minimize the effect of compromising a key, it is +desirable to use a different key for each of these places. Key derivation +[Horowitz96] can be used to construct different keys for each operation +from the keys transported on the network. For this to be possible, a small +change to the specification is necessary. + +This section specifies a profile for the use of key derivation [Horowitz96] +with Kerberos. For each place where a key is used, a ``key usage'' must is +specified for that purpose. The key, key usage, and encryption/checksum +type together describe the transformation from plaintext to ciphertext, or + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +plaintext to checksum. + +Key Usage Values + +This is a complete list of places keys are used in the kerberos protocol, +with key usage values and RFC 1510 section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) +10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) +11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) +12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) +13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) +14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) +15. KRB-SAVE cksum, keyed with a key chosen by the application + (section 5.8.1) +18. KRB-ERROR checksum (e-cksum in section 5.9.1) +19. AD-KDCIssued checksum (ad-checksum in appendix B.1) +20. Checksum for Mandatory Ticket Extensions (appendix B.6) +21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) + +Key usage values between 1024 and 2047 (inclusive) are reserved for +application use. Applications should use even values for encryption and odd +values for checksums within this range. + +A few of these key usages need a little clarification. A service which +receives an AP-REQ has no way to know if the enclosed Ticket was part of an +AS-REP or TGS-REP. Therefore, key usage 2 must always be used for +generating a Ticket, whether it is in response to an AS- REQ or TGS-REQ. + +There might exist other documents which define protocols in terms of the +RFC1510 encryption types or checksum types. Such documents would not know +about key usages. In order that these documents continue to be meaningful +until they are updated, key usages 1024 and 1025 must be used to derive +keys for encryption and checksums, respectively. New protocols defined in + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +terms of the Kerberos encryption and checksum types should use their own +key usages. Key usages may be registered with IANA to avoid conflicts. Key +usages must be unsigned 32 bit integers. Zero is not permitted. + +Defining Cryptosystems Using Key Derivation + +Kerberos requires that the ciphertext component of EncryptedData be +tamper-resistant as well as confidential. This implies encryption and +integrity functions, which must each use their own separate keys. So, for +each key usage, two keys must be generated, one for encryption (Ke), and +one for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + +where the protocol key is from the EncryptionKey from the wire protocol, +and the key usage is represented as a 32 bit integer in network byte order. +The ciphertest must be generated from the plaintext as follows: + + ciphertext = E(Ke, confounder | plaintext | padding) | + H(Ki, confounder | plaintext | padding) + +The confounder and padding are specific to the encryption algorithm E. + +When generating a checksum only, there is no need for a confounder or +padding. Again, a new key (Kc) must be used. Checksums must be generated +from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + + MAC = H(Kc, plaintext) + +Note that each enctype is described by an encryption algorithm E and a +keyed hash algorithm H, and each checksum type is described by a keyed hash +algorithm H. HMAC, with an appropriate hash, is recommended for use as H. + +Key Derivation from Passwords + +The well-known constant for password key derivation must be the byte string +{0x6b 0x65 0x72 0x62 0x65 0x72 0x6f 0x73}. These values correspond to the +ASCII encoding for the string "kerberos". + +6.4. Checksums + +The following is the ASN.1 definition used for a checksum: + + Checksum ::= SEQUENCE { + cksumtype[0] INTEGER, + checksum[1] OCTET STRING + } + +cksumtype + This field indicates the algorithm used to generate the accompanying + checksum. +checksum + This field contains the checksum itself, encoded as an octet string. + +Detailed specification of selected checksum types appear later in this +section. Negative values for the checksum type are reserved for local use. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +All non-negative values are reserved for officially assigned type fields +and interpretations. + +Checksums used by Kerberos can be classified by two properties: whether +they are collision-proof, and whether they are keyed. It is infeasible to +find two plaintexts which generate the same checksum value for a +collision-proof checksum. A key is required to perturb or initialize the +algorithm in a keyed checksum. To prevent message-stream modification by an +active attacker, unkeyed checksums should only be used when the checksum +and message will be subsequently encrypted (e.g. the checksums defined as +part of the encryption algorithms covered earlier in this section). + +Collision-proof checksums can be made tamper-proof if the checksum value is +encrypted before inclusion in a message. In such cases, the composition of +the checksum and the encryption algorithm must be considered a separate +checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum +algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for +the encrypted forms of unkeyed collision-proof checksums, Kerberos prepends +a confounder before the checksum is calculated. + +6.4.1. The CRC-32 Checksum (crc32) + +The CRC-32 checksum calculates a checksum based on a cyclic redundancy +check as described in ISO 3309 [ISO3309]. The resulting checksum is four +(4) octets in length. The CRC-32 is neither keyed nor collision-proof. The +use of this checksum is not recommended. An attacker using a probabilistic +chosen-plaintext attack as described in [SG92] might be able to generate an +alternative message that satisfies the checksum. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. + +6.4.2. The RSA MD4 Checksum (rsa-md4) + +The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm +[MD4-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed +to be collision-proof. + +6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) + +The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD4 +checksum algorithm, and encrypting the confounder and the checksum using +DES in cipher-block-chaining (CBC) mode using a variant of the key, where +the variant is computed by eXclusive-ORing the key with the constant +F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The +resulting checksum is 24 octets long (8 octets of which are redundant). +This checksum is tamper-proof and believed to be collision-proof. + +The DES specifications identify some weak keys' and 'semi-weak keys'; those +keys shall not be used for generating RSA-MD4 checksums for use in +Kerberos. + +The format for the checksum is described in the follow- ing diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.4. The RSA MD5 Checksum (rsa-md5) + +The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. +[MD5-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed +to be collision-proof. + +6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) + +The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD5 +checksum algorithm, and encrypting the confounder and the checksum using +DES in cipher-block-chaining (CBC) mode using a variant of the key, where +the variant is computed by eXclusive-ORing the key with the hexadecimal +constant F0F0F0F0F0F0F0F0. The initialization vector should be zero. The +resulting checksum is 24 octets long (8 octets of which are redundant). +This checksum is tamper-proof and believed to be collision-proof. + +The DES specifications identify some 'weak keys' and 'semi-weak keys'; +those keys shall not be used for encrypting RSA-MD5 checksums for use in +Kerberos. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.6. DES cipher-block chained checksum (des-mac) + +The DES-MAC checksum is computed by prepending an 8 octet confounder to the +plaintext, performing a DES CBC-mode encryption on the result using the key +and an initialization vector of zero, taking the last block of the +ciphertext, prepending the same confounder and encrypting the pair using +DES in cipher-block-chaining (CBC) mode using a a variant of the key, where +the variant is computed by eXclusive-ORing the key with the hexadecimal +constant F0F0F0F0F0F0F0F0. The initialization vector should be zero. The +resulting checksum is 128 bits (16 octets) long, 64 bits of which are +redundant. This checksum is tamper-proof and collision-proof. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(8) +} + +The DES specifications identify some 'weak' and 'semi-weak' keys; those +keys shall not be used for generating DES-MAC checksums for use in +Kerberos, nor shall a key be used whose variant is 'weak' or 'semi-weak'. + +6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) + +The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by +applying the RSA MD4 checksum algorithm and encrypting the results using +DES in cipher-block-chaining (CBC) mode using a DES key as both key and +initialization vector. The resulting checksum is 16 octets long. This +checksum is tamper-proof and believed to be collision-proof. Note that this +checksum type is the old method for encoding the RSA-MD4-DES checksum and +it is no longer recommended. + +6.4.8. DES cipher-block chained checksum alternative (des-mac-k) + +The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption +of the plaintext, and using the last block of the ciphertext as the +checksum value. It is keyed with an encryption key and an initialization +vector; any uses which do not specify an additional initialization vector +will use the key as both key and initialization vector. The resulting +checksum is 64 bits (8 octets) long. This checksum is tamper-proof and +collision-proof. Note that this checksum type is the old method for +encoding the DES-MAC checksum and it is no longer recommended. The DES +specifications identify some 'weak keys' and 'semi-weak keys'; those keys +shall not be used for generating DES-MAC checksums for use in Kerberos. + +7. Naming Constraints + +7.1. Realm Names + +Although realm names are encoded as GeneralStrings and although a realm can +technically select any name it chooses, interoperability across realm +boundaries requires agreement on how realm names are to be assigned, and +what information they imply. + +To enforce these conventions, each realm must conform to the conventions +itself, and it must require that any realms with which inter-realm keys are +shared also conform to the conventions and require the same from its +neighbors. + +Kerberos realm names are case sensitive. Realm names that differ only in +the case of the characters are not equivalent. There are presently four +styles of realm names: domain, X500, other, and reserved. Examples of each +style follow: + + domain: ATHENA.MIT.EDU (example) + X500: C=US/O=OSF (example) + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + other: NAMETYPE:rest/of.name=without-restrictions (example) + reserved: reserved, but will not conflict with above + +Domain names must look like domain names: they consist of components +separated by periods (.) and they contain neither colons (:) nor slashes +(/). Domain names must be converted to upper case when used as realm names. + +X.500 names contain an equal (=) and cannot contain a colon (:) before the +equal. The realm names for X.500 names will be string representations of +the names with components separated by slashes. Leading and trailing +slashes will not be included. + +Names that fall into the other category must begin with a prefix that +contains no equal (=) or period (.) and the prefix must be followed by a +colon (:) and the rest of the name. All prefixes must be assigned before +they may be used. Presently none are assigned. + +The reserved category includes strings which do not fall into the first +three categories. All names in this category are reserved. It is unlikely +that names will be assigned to this category unless there is a very strong +argument for not using the 'other' category. + +These rules guarantee that there will be no conflicts between the various +name styles. The following additional constraints apply to the assignment +of realm names in the domain and X.500 categories: the name of a realm for +the domain or X.500 formats must either be used by the organization owning +(to whom it was assigned) an Internet domain name or X.500 name, or in the +case that no such names are registered, authority to use a realm name may +be derived from the authority of the parent realm. For example, if there is +no domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm +can authorize the creation of a realm with that name. + +This is acceptable because the organization to which the parent is assigned +is presumably the organization authorized to assign names to its children +in the X.500 and domain name systems as well. If the parent assigns a realm +name without also registering it in the domain name or X.500 hierarchy, it +is the parent's responsibility to make sure that there will not in the +future exists a name identical to the realm name of the child unless it is +assigned to the same entity as the realm name. + +7.2. Principal Names + +As was the case for realm names, conventions are needed to ensure that all +agree on what information is implied by a principal name. The name-type +field that is part of the principal name indicates the kind of information +implied by the name. The name-type should be treated as a hint. Ignoring +the name type, no two names can be the same (i.e. at least one of the +components, or the realm, must be different). The following name types are +defined: + + name-type value meaning + + NT-UNKNOWN 0 Name type not known + NT-PRINCIPAL 1 General principal name (e.g. username, or DCE +principal) + NT-SRV-INST 2 Service and other unique instance (krbtgt) + NT-SRV-HST 3 Service with host name as instance (telnet, +rcommands) + NT-SRV-XHST 4 Service with slash-separated host name components + NT-UID 5 Unique ID + NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +When a name implies no information other than its uniqueness at a +particular time the name type PRINCIPAL should be used. The principal name +type should be used for users, and it might also be used for a unique +server. If the name is a unique machine generated ID that is guaranteed +never to be reassigned then the name type of UID should be used (note that +it is generally a bad idea to reassign names of any type since stale +entries might remain in access control lists). + +If the first component of a name identifies a service and the remaining +components identify an instance of the service in a server specified +manner, then the name type of SRV-INST should be used. An example of this +name type is the Kerberos ticket-granting service whose name has a first +component of krbtgt and a second component identifying the realm for which +the ticket is valid. + +If instance is a single component following the service name and the +instance identifies the host on which the server is running, then the name +type SRV-HST should be used. This type is typically used for Internet +services such as telnet and the Berkeley R commands. If the separate +components of the host name appear as successive components following the +name of the service, then the name type SRV-XHST should be used. This type +might be used to identify servers on hosts with X.500 names where the slash +(/) might otherwise be ambiguous. + +A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 +certificiate is translated into a Kerberos name. The encoding of the X.509 +name as a Kerberos principal shall conform to the encoding rules specified +in RFC 2253. + +A name type of UNKNOWN should be used when the form of the name is not +known. When comparing names, a name of type UNKNOWN will match principals +authenticated with names of any type. A principal authenticated with a name +of type UNKNOWN, however, will only match other names of type UNKNOWN. + +Names of any type with an initial component of 'krbtgt' are reserved for +the Kerberos ticket granting service. See section 8.2.3 for the form of +such names. + +7.2.1. Name of server principals + +The principal identifier for a server on a host will generally be composed +of two parts: (1) the realm of the KDC with which the server is registered, +and (2) a two-component name of type NT-SRV-HST if the host name is an +Internet domain name or a multi-component name of type NT-SRV-XHST if the +name of the host is of a form such as X.500 that allows slash (/) +separators. The first component of the two- or multi-component name will +identify the service and the latter components will identify the host. +Where the name of the host is not case sensitive (for example, with +Internet domain names) the name of the host must be lower case. If +specified by the application protocol for services such as telnet and the +Berkeley R commands which run with system privileges, the first component +may be the string 'host' instead of a service specific identifier. When a +host has an official name and one or more aliases, the official name of the +host must be used when constructing the name of the server principal. + +8. Constants and other defined values + +8.1. Host address types + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +All negative values for the host address type are reserved for local use. +All non-negative values are reserved for officially assigned type fields +and interpretations. + +The values of the types for the following addresses are chosen to match the +defined address family constants in the Berkeley Standard Distributions of +Unix. They can be found in with symbolic names AF_xxx (where xxx is an +abbreviation of the address family name). + +Internet (IPv4) Addresses + +Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB +order. The type of IPv4 addresses is two (2). + +Internet (IPv6) Addresses [Westerlund] + +IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The +type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The +following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: + + * the Unspecified Address + * the Loopback Address + * Link-Local addresses + +IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. + +CHAOSnet addresses + +CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. +The type of CHAOSnet addresses is five (5). + +ISO addresses + +ISO addresses are variable-length. The type of ISO addresses is seven (7). + +Xerox Network Services (XNS) addresses + +XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The +type of XNS addresses is six (6). + +AppleTalk Datagram Delivery Protocol (DDP) addresses + +AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit +network number. The first octet of the address is the node number; the +remaining two octets encode the network number in MSB order. The type of +AppleTalk DDP addresses is sixteen (16). + +DECnet Phase IV addresses + +DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The +type of DECnet Phase IV addresses is twelve (12). + +Netbios addresses + +Netbios addresses are 16-octet addresses typically composed of 1 to 15 +characters, trailing blank (ascii char 20) filled, with a 16th octet of +0x0. The type of Netbios addresses is 20 (0x14). + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +8.2. KDC messages + +8.2.1. UDP/IP transport + +When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP +IP transport, the client shall send a UDP datagram containing only an +encoding of the request to port 88 (decimal) at the KDC's IP address; the +KDC will respond with a reply datagram containing only an encoding of the +reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at +the sender's IP address. Kerberos servers supporting IP transport must +accept UDP requests on port 88 (decimal). The response to a request made +through UDP/IP transport must also use UDP/IP transport. + +8.2.2. TCP/IP transport [Westerlund,Danielsson] + +Kerberos servers (KDC's) should accept TCP requests on port 88 (decimal) +and clients should support the sending of TCP requests on port 88 +(decimal). When the KRB_KDC_REQ message is sent to the KDC over a TCP +stream, a new connection will be established for each authentication +exchange (request and response). The KRB_KDC_REP or KRB_ERROR message will +be returned to the client on the same TCP stream that was established for +the request. The response to a request made through TCP/IP transport must +also use TCP/IP transport. Implementors should note that some extentions to +the Kerberos protocol will not work if any implementation not supporting +the TCP transport is involved (client or KDC). Implementors are strongly +urged to support the TCP transport on both the client and server and are +advised that the current notation of "should" support will likely change in +the future to must support. The KDC may close the TCP stream after sending +a response, but may leave the stream open if it expects a followup - in +which case it may close the stream at any time if resource constratints or +other factors make it desirable to do so. Care must be taken in managing +TCP/IP connections with the KDC to prevent denial of service attacks based +on the number of TCP/IP connections with the KDC that remain open. If +multiple exchanges with the KDC are needed for certain forms of +preauthentication, multiple TCP connections may be required. A client may +close the stream after receiving response, and should close the stream if +it does not expect to send followup messages. The client must be prepared +to have the stream closed by the KDC at anytime, in which case it must +simply connect again when it is ready to send subsequent messages. + +The first four octets of the TCP stream used to transmit the request +request will encode in network byte order the length of the request +(KRB_KDC_REQ), and the length will be followed by the request itself. The +response will similarly be preceeded by a 4 octet encoding in network byte +order of the length of the KRB_KDC_REP or the KRB_ERROR message and will be +followed by the KRB_KDC_REP or the KRB_ERROR response. If the sign bit is +set on integer represented by the first 4 octets, then the next 4 octets +will be read, extending the length of the field by another 4 octets (less 1 +bit). + +8.2.3. OSI transport + +During authentication of an OSI client to an OSI server, the mutual +authentication of an OSI server to an OSI client, the transfer of +credentials from an OSI client to an OSI server, or during exchange of +private or integrity checked messages, Kerberos protocol messages may be +treated as opaque objects and the type of the authentication mechanism will +be: + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), +security(5),kerberosv5(2)} + +Depending on the situation, the opaque object will be an authentication +header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message +(KRB_SAFE), a private message (KRB_PRIV), or a credentials message +(KRB_CRED). The opaque data contains an application code as specified in +the ASN.1 description for each message. The application code may be used by +Kerberos to determine the message type. + +8.2.3. Name of the TGS + +The principal identifier of the ticket-granting service shall be composed +of three parts: (1) the realm of the KDC issuing the TGS ticket (2) a +two-part name of type NT-SRV-INST, with the first part "krbtgt" and the +second part the name of the realm which will accept the ticket-granting +ticket. For example, a ticket-granting ticket issued by the ATHENA.MIT.EDU +realm to be used to get tickets from the ATHENA.MIT.EDU KDC has a principal +identifier of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") +(name). A ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be +used to get tickets from the MIT.EDU realm has a principal identifier of +"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). + +8.3. Protocol constants and associated values + +The following tables list constants used in the protocol and defines their +meanings. Ranges are specified in the "specification" section that limit +the values of constants for which values are defined here. This allows +implementations to make assumptions about the maximum values that will be +received for these constants. Implementation receiving values outside the +range specified in the "specification" section may reject the request, but +they must recover cleanly. + +Encryption type etype value block size minimum pad size confounder +size +NULL 0 1 0 0 +des-cbc-crc 1 8 4 8 +des-cbc-md4 2 8 0 8 +des-cbc-md5 3 8 0 8 + 4 +des3-cbc-md5 5 8 0 8 + 6 +des3-cbc-sha1 7 8 0 8 +sign-dsa-generate 8 (pkinit) +encrypt-rsa-priv 9 (pkinit) +encrypt-rsa-pub 10 (pkinit) +rsa-pub-md5 11 (pkinit) +rsa-pub-sha1 12 (pkinit) +des3kd-cbc-sha1 ?? 8 0 8 +ENCTYPE_PK_CROSS 48 (reserved for pkcross) + 0x8003 + +Checksum type sumtype value checksum size +CRC32 1 4 +rsa-md4 2 16 +rsa-md4-des 3 24 +des-mac 4 16 +des-mac-k 5 8 +rsa-md4-des-k 6 16 +rsa-md5 7 16 +rsa-md5-des 8 24 + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +rsa-md5-des3 9 24 +hmac-sha1-des3 12 20 (I had this as 10, is it +12) + +padata type padata-type value + +PA-TGS-REQ 1 +PA-ENC-TIMESTAMP 2 +PA-PW-SALT 3 + 4 +PA-ENC-UNIX-TIME 5 +PA-SANDIA-SECUREID 6 +PA-SESAME 7 +PA-OSF-DCE 8 +PA-CYBERSAFE-SECUREID 9 +PA-AFS3-SALT 10 +PA-ETYPE-INFO 11 +SAM-CHALLENGE 12 (sam/otp) +SAM-RESPONSE 13 (sam/otp) +PA-PK-AS-REQ 14 (pkinit) +PA-PK-AS-REP 15 (pkinit) +PA-PK-AS-SIGN 16 (pkinit) +PA-PK-KEY-REQ 17 (pkinit) +PA-PK-KEY-REP 18 (pkinit) +PA-USE-SPECIFIED-KVNO 20 + +authorization data type ad-type value +AD-KDC-ISSUED 1 +AD-INTENDED-FOR-SERVER 2 +AD-INTENDED-FOR-APPLICATION-CLASS 3 +AD-IF-RELEVANT 4 +AD-OR 5 +AD-MANDATORY-TICKET-EXTENSIONS 6 +AD-IN-TICKET-EXTENSIONS 7 +reserved values 8-63 +OSF-DCE 64 +SESAME 65 + +Ticket Extension Types + +TE-TYPE-NULL 0 Null ticket extension +TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data + 2 TE-TYPE-PKCROSS-KDC (I have reservations) +TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket +TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp + 5 TE-TYPE-DEST-HOST (I have reservations) + +alternate authentication type method-type value +reserved values 0-63 +ATT-CHALLENGE-RESPONSE 64 + +transited encoding type tr-type value +DOMAIN-X500-COMPRESS 1 +reserved values all others + +Label Value Meaning or MIT code + +pvno 5 current Kerberos protocol version number + +message types + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +KRB_AS_REQ 10 Request for initial authentication +KRB_AS_REP 11 Response to KRB_AS_REQ request +KRB_TGS_REQ 12 Request for authentication based on TGT +KRB_TGS_REP 13 Response to KRB_TGS_REQ request +KRB_AP_REQ 14 application request to server +KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL +KRB_SAFE 20 Safe (checksummed) application message +KRB_PRIV 21 Private (encrypted) application message +KRB_CRED 22 Private (encrypted) message to forward +credentials +KRB_ERROR 30 Error response + +name types + +KRB_NT_UNKNOWN 0 Name type not known +KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for +users +KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) +KRB_NT_SRV_HST 3 Service with host name as instance (telnet, +rcommands) +KRB_NT_SRV_XHST 4 Service with host as remaining components +KRB_NT_UID 5 Unique ID +KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253] + +error codes + +KDC_ERR_NONE 0 No error +KDC_ERR_NAME_EXP 1 Client's entry in database has expired +KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired +KDC_ERR_BAD_PVNO 3 Requested protocol version number not +supported +KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key +KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key +KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database +KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database +KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database +KDC_ERR_NULL_KEY 9 The client or server has a null key +KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating +KDC_ERR_NEVER_VALID 11 Requested start time is later than end +time +KDC_ERR_POLICY 12 KDC policy rejects request +KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option +KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type +KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type +KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type +KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type +KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked +KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked +KDC_ERR_TGT_REVOKED 20 TGT has been revoked +KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later +KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later +KDC_ERR_KEY_EXPIRED 23 Password has expired - change password +to reset +KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was +invalid +KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired +[40] +KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match +KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user +only +KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path +KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field +failed +KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired +KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid +KRB_AP_ERR_REPEAT 34 Request is a replay +KRB_AP_ERR_NOT_US 35 The ticket isn't for us +KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +KRB_AP_ERR_SKEW 37 Clock skew too great +KRB_AP_ERR_BADADDR 38 Incorrect net address +KRB_AP_ERR_BADVERSION 39 Protocol version mismatch +KRB_AP_ERR_MSG_TYPE 40 Invalid msg type +KRB_AP_ERR_MODIFIED 41 Message stream modified +KRB_AP_ERR_BADORDER 42 Message out of order +KRB_AP_ERR_BADKEYVER 44 Specified version of key is not +available +KRB_AP_ERR_NOKEY 45 Service key not available +KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed +KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction +KRB_AP_ERR_METHOD 48 Alternative authentication method +required +KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message +KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in +message +KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path +KRB_ERR_RESPONSE_TOO_BIG 52 Response too big for UDP, retry with TCP +KRB_ERR_GENERIC 60 Generic error (description in e-text) +KRB_ERR_FIELD_TOOLONG 61 Field is too long for this +implementation +KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) +KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) +KDC_ERROR_INVALID_SIG 64 (pkinit) +KDC_ERR_KEY_TOO_WEAK 65 (pkinit) +KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) + +9. Interoperability requirements + +Version 5 of the Kerberos protocol supports a myriad of options. Among +these are multiple encryption and checksum types, alternative encoding +schemes for the transited field, optional mechanisms for +pre-authentication, the handling of tickets with no addresses, options for +mutual authentication, user to user authentication, support for proxies, +forwarding, postdating, and renewing tickets, the format of realm names, +and the handling of authorization data. + +In order to ensure the interoperability of realms, it is necessary to +define a minimal configuration which must be supported by all +implementations. This minimal configuration is subject to change as +technology does. For example, if at some later date it is discovered that +one of the required encryption or checksum algorithms is not secure, it +will be replaced. + +9.1. Specification 2 + +This section defines the second specification of these options. +Implementations which are configured in this way can be said to support +Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may +be found in RFC1510. + +Transport + +TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance +to specification 2. Kerberos clients claiming conformance to specification +2 must support UDP/IP transport for messages with the KDC and should +support TCP/IP transport. + +Encryption and checksum methods + +The following encryption and checksum mechanisms must be supported. +Implementations may support other mechanisms as well, but the additional +mechanisms may only be used when communicating with principals known to + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +also support them: This list is to be determined. + +Encryption: DES-CBC-MD5 +Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 + +Realm Names + +All implementations must understand hierarchical realms in both the +Internet Domain and the X.500 style. When a ticket granting ticket for an +unknown realm is requested, the KDC must be able to determine the names of +the intermediate realms between the KDCs realm and the requested realm. + +Transited field encoding + +DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. +Alternative encodings may be supported, but they may be used only when that +encoding is supported by ALL intermediate realms. + +Pre-authentication methods + +The TGS-REQ method must be supported. The TGS-REQ method is not used on the +initial request. The PA-ENC-TIMESTAMP method must be supported by clients +but whether it is enabled by default may be determined on a realm by realm +basis. If not used in the initial request and the error +KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an +acceptable method, the client should retry the initial request using the +PA-ENC-TIMESTAMP preauthentication method. Servers need not support the +PA-ENC-TIMESTAMP method, but if not supported the server should ignore the +presence of PA-ENC-TIMESTAMP pre-authentication in a request. + +Mutual authentication + +Mutual authentication (via the KRB_AP_REP message) must be supported. + +Ticket addresses and flags + +All KDC's must pass on tickets that carry no addresses (i.e. if a TGT +contains no addresses, the KDC will return derivative tickets), but each +realm may set its own policy for issuing such tickets, and each application +server will set its own policy with respect to accepting them. + +Proxies and forwarded tickets must be supported. Individual realms and +application servers can set their own policy on when such tickets will be +accepted. + +All implementations must recognize renewable and postdated tickets, but +need not actually implement them. If these options are not supported, the +starttime and endtime in the ticket shall specify a ticket's entire useful +life. When a postdated ticket is decoded by a server, all implementations +shall make the presence of the postdated flag visible to the calling +server. + +User-to-user authentication + +Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC +option) must be provided by implementations, but individual realms may +decide as a matter of policy to reject such requests on a per-principal or +realm-wide basis. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +Authorization data + +Implementations must pass all authorization data subfields from +ticket-granting tickets to any derivative tickets unless directed to +suppress a subfield as part of the definition of that registered subfield +type (it is never incorrect to pass on a subfield, and no registered +subfield types presently specify suppression at the KDC). + +Implementations must make the contents of any authorization data subfields +available to the server when a ticket is used. Implementations are not +required to allow clients to specify the contents of the authorization data +fields. + +Constant ranges + +All protocol constants are constrained to 32 bit (signed) values unless +further constrained by the protocol definition. This limit is provided to +allow implementations to make assumptions about the maximum values that +will be received for these constants. Implementation receiving values +outside this range may reject the request, but they must recover cleanly. + +9.2. Recommended KDC values + +Following is a list of recommended values for a KDC implementation, based +on the list of suggested configuration constants (see section 4.4). + +minimum lifetime 5 minutes +maximum renewable lifetime 1 week +maximum ticket lifetime 1 day +empty addresses only when suitable restrictions appear + in authorization data +proxiable, etc. Allowed. + +10. REFERENCES + +[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- + cation Service for Computer Networks," IEEE Communica- + tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). + +[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. + Saltzer, Section E.2.1: Kerberos Authentication and + Authorization System, M.I.T. Project Athena, Cambridge, + Massachusetts (December 21, 1987). + +[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- + beros: An Authentication Service for Open Network Sys- + tems," pp. 191-202 in Usenix Conference Proceedings, + Dallas, Texas (February, 1988). + +[NS78] Roger M. Needham and Michael D. Schroeder, "Using + Encryption for Authentication in Large Networks of Com- + puters," Communications of the ACM, Vol. 21(12), + pp. 993-999 (December, 1978). + +[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- + stamps in Key Distribution Protocols," Communications + of the ACM, Vol. 24(8), pp. 533-536 (August 1981). + +[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + "The Evolution of the Kerberos Authentication Service," + in an IEEE Computer Society Text soon to be published + (June 1992). + +[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and + Accounting for Distributed Systems," in Proceedings of + the 13th International Conference on Distributed Com- + puting Systems, Pittsburgh, PA (May, 1993). + +[DS90] Don Davis and Ralph Swick, "Workstation Services and + Kerberos Authentication at Project Athena," Technical + Memorandum TM-424, MIT Laboratory for Computer Science + (February 1990). + +[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- + merfeld, and K. Raeburn, Section E.1: Service Manage- + ment System, M.I.T. Project Athena, Cambridge, Mas- + sachusetts (1987). + +[X509-88] CCITT, Recommendation X.509: The Directory Authentica- + tion Framework, December 1988. + +[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password + Guessing Attacks, Open Software Foundation DCE Request + for Comments 26 (December 1992). + +[DES77] National Bureau of Standards, U.S. Department of Com- + merce, "Data Encryption Standard," Federal Information + Processing Standards Publication 46, Washington, DC + (1977). + +[DESM80] National Bureau of Standards, U.S. Department of Com- + merce, "DES Modes of Operation," Federal Information + Processing Standards Publication 81, Springfield, VA + (December 1980). + +[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message + Integrity in Cryptographic Protocols," in Proceedings + of the IEEE Symposium on Research in Security and + Privacy, Oakland, California (May 1992). + +[IS3309] International Organization for Standardization, "ISO + Information Processing Systems - Data Communication - + High-Level Data Link Control Procedure - Frame Struc- + ture," IS 3309 (October 1984). 3rd Edition. + +[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC + 1320, MIT Laboratory for Computer Science (April + 1992). + +[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC + 1321, MIT Laboratory for Computer Science (April + 1992). + +[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication," Working Draft + draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). + +[Horowitz96] Horowitz, M., "Key Derivation for Authentication, + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + Integrity, and Privacy", draft-horowitz-key-derivation-02.txt, + August 1998. + +[HorowitzB96] Horowitz, M., "Key Derivation for Kerberos V5", draft- + horowitz-kerb-key-derivation-01.txt, September 1998. + +[Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: + Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- + md5-01.txt, August, 1996. + +A. Pseudo-code for protocol processing + +This appendix provides pseudo-code describing how the messages are to be +constructed and interpreted by clients and servers. + +A.1. KRB_AS_REQ generation + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_AS_REQ */ + + if(pa_enc_timestamp_required) then + request.padata.padata-type = PA-ENC-TIMESTAMP; + get system_time; + padata-body.patimestamp,pausec = system_time; + encrypt padata-body into request.padata.padata-value + using client.key; /* derived from password */ + endif + + body.kdc-options := users's preferences; + body.cname := user's name; + body.realm := user's realm; + body.sname := service's name; /* usually "krbtgt", "localrealm" */ + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + omit body.enc-authorization-data; + request.req-body := body; + + kerberos := lookup(name of local kerberos server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +A.2. KRB_AS_REQ verification and KRB_AS_REP generation + + decode message into req; + + client := lookup(req.cname,req.realm); + server := lookup(req.sname,req.realm); + + get system_time; + kdc_time := system_time.seconds; + + if (!client) then + /* no client in Database */ + error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); + endif + if (!server) then + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + + if(client.pa_enc_timestamp_required and + pa_enc_timestamp not present) then + error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); + endif + + if(pa_enc_timestamp present) then + decrypt req.padata-value into decrypted_enc_timestamp + using client.key; + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + if(decrypted_enc_timestamp is not within allowable skew) +then + error_out(KDC_ERR_PREAUTH_FAILED); + endif + if(decrypted_enc_timestamp and usec is replay) + error_out(KDC_ERR_PREAUTH_FAILED); + endif + add decrypted_enc_timestamp and usec to replay cache; + endif + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := req.srealm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + if (req.kdc-options.FORWARDABLE is set) then + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.PROXIABLE is set) then + set new_tkt.flags.PROXIABLE; + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + set new_tkt.flags.MAY-POSTDATE; + endif + if ((req.kdc-options.RENEW is set) or + (req.kdc-options.VALIDATE is set) or + (req.kdc-options.PROXY is set) or + (req.kdc-options.FORWARDED is set) or + (req.kdc-options.ENC-TKT-IN-SKEY is set)) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.session := random_session_key(); + new_tkt.cname := req.cname; + new_tkt.crealm := req.crealm; + new_tkt.transited := empty_transited_field(); + + new_tkt.authtime := kdc_time; + + if (req.kdc-options.POSTDATED is set) then + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + new_tkt.starttime := req.from; + else + omit new_tkt.starttime; /* treated as authtime when omitted */ + endif + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till)) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := req.till; + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if (req.kdc-options.RENEWABLE is set) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + +new_tkt.starttime+client.max_rlife, + +new_tkt.starttime+server.max_rlife, + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +new_tkt.starttime+max_rlife_for_realm); + else + omit new_tkt.renew-till; /* only present if RENEWABLE */ + endif + + if (req.addresses) then + new_tkt.caddr := req.addresses; + else + omit new_tkt.caddr; + endif + + new_tkt.authorization_data := empty_authorization_data(); + + encode to-be-encrypted part of ticket into OCTET STRING; + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + + /* Start processing the response */ + + resp.pvno := 5; + resp.msg-type := KRB_AS_REP; + resp.cname := req.cname; + resp.crealm := req.realm; + resp.ticket := new_tkt; + + resp.key := new_tkt.session; + resp.last-req := fetch_last_request_info(client); + resp.nonce := req.nonce; + resp.key-expiration := client.expiration; + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + resp.realm := new_tkt.realm; + resp.sname := new_tkt.sname; + + resp.caddr := new_tkt.caddr; + + encode body of reply into OCTET STRING; + + resp.enc-part := encrypt OCTET STRING + using use_etype, client.key, client.p_kvno; + send(resp); + +A.3. KRB_AS_REP verification + + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then + set pa_enc_timestamp_required; + goto KRB_AS_REQ; + endif + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key */ + /* from the response immediately */ + + key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, + resp.padata); + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and key; + zero(key); + + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + if near(resp.princ_exp) then + print(warning message); + endif + save_for_later(ticket,session,client,server,times,flags); + +A.4. KRB_AS_REP and KRB_TGS_REP common checks + + if (decryption_error() or + (req.cname != resp.cname) or + (req.realm != resp.crealm) or + (req.sname != resp.sname) or + (req.realm != resp.realm) or + (req.nonce != resp.nonce) or + (req.addresses != resp.caddr)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + /* make sure no flags are set that shouldn't be, and that all that +*/ + /* should be are set +*/ + if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.from = 0) and + (resp.starttime is not within allowable skew)) then + destroy resp.key; + return KRB_AP_ERR_SKEW; + endif + if ((req.from != 0) and (req.from != resp.starttime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.till != 0) and (resp.endtime > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (req.rtime != 0) and (resp.renew-till > req.rtime)) then + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.kdc-options.RENEWABLE-OK is set) and + (resp.flags.RENEWABLE) and + (req.till != 0) and + (resp.renew-till > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + +A.5. KRB_TGS_REQ generation + + /* Note that make_application_request might have to recursivly +*/ + /* call this routine to get the appropriate ticket-granting ticket +*/ + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_TGS_REQ */ + + body.kdc-options := users's preferences; + /* If the TGT is not for the realm of the end-server */ + /* then the sname will be for a TGT for the end-realm */ + /* and the realm of the requested ticket (body.realm) */ + /* will be that of the TGS to which the TGT we are */ + /* sending applies */ + body.sname := service's name; + body.realm := service's realm; + + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + + body.enc-authorization-data := user-supplied data; + if (body.kdc-options.ENC-TKT-IN-SKEY) then + body.additional-tickets_ticket := second TGT; + endif + + request.req-body := body; + check := generate_checksum (req.body,checksumtype); + + request.padata[0].padata-type := PA-TGS-REQ; + request.padata[0].padata-value := create a KRB_AP_REQ using + the TGT and checksum + + /* add in any other padata as required/supplied */ + kerberos := lookup(name of local kerberose server (or servers)); + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation + + /* note that reading the application request requires first + determining the server for which a ticket was issued, and choosing +the + correct key for decryption. The name of the server appears in the + plaintext part of the ticket. */ + + if (no KRB_AP_REQ in req.padata) then + error_out(KDC_ERR_PADATA_TYPE_NOSUPP); + endif + verify KRB_AP_REQ in req.padata; + + /* Note that the realm in which the Kerberos server is operating is + determined by the instance from the ticket-granting ticket. The +realm + in the ticket-granting ticket is the realm under which the ticket + granting ticket was issued. It is possible for a single Kerberos + server to support more than one realm. */ + + auth_hdr := KRB_AP_REQ; + tgt := auth_hdr.ticket; + + if (tgt.sname is not a TGT for local realm and is not req.sname) +then + error_out(KRB_AP_ERR_NOT_US); + + realm := realm_tgt_is_for(tgt); + + decode remainder of request; + + if (auth_hdr.authenticator.cksum is missing) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + if (auth_hdr.authenticator.cksum type is not supported) then + error_out(KDC_ERR_SUMTYPE_NOSUPP); + endif + if (auth_hdr.authenticator.cksum is not both collision-proof and +keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + set computed_checksum := checksum(req); + if (computed_checksum != auth_hdr.authenticatory.cksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + server := lookup(req.sname,realm); + + if (!server) then + if (is_foreign_tgt_name(req.sname)) then + server := best_intermediate_tgs(req.sname); + else + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + endif + endif + + session := generate_random_session_key(); + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := realm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + new_tkt.caddr := tgt.caddr; + resp.caddr := NULL; /* We only include this if they change */ + if (req.kdc-options.FORWARDABLE is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.FORWARDED is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDED; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + if (tgt.flags.FORWARDED is set) then + set new_tkt.flags.FORWARDED; + endif + + if (req.kdc-options.PROXIABLE is set) then + if (tgt.flags.PROXIABLE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.PROXY is set) then + if (tgt.flags.PROXIABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXY; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + if (tgt.flags.MAY-POSTDATE is reset) + error_out(KDC_ERR_BADOPTION); + endif + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + set new_tkt.flags.MAY-POSTDATE; + endif + if (req.kdc-options.POSTDATED is set) then + if (tgt.flags.MAY-POSTDATE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + new_tkt.starttime := req.from; + endif + + if (req.kdc-options.VALIDATE is set) then + if (tgt.flags.INVALID is reset) then + error_out(KDC_ERR_POLICY); + endif + if (tgt.starttime > kdc_time) then + error_out(KRB_AP_ERR_NYV); + endif + if (check_hot_list(tgt)) then + error_out(KRB_AP_ERR_REPEAT); + endif + tkt := tgt; + reset new_tkt.flags.INVALID; + endif + + if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, + and those already processed) is set) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.authtime := tgt.authtime; + + if (req.kdc-options.RENEW is set) then + /* Note that if the endtime has already passed, the ticket would +*/ + /* have been rejected in the initial authentication stage, so +*/ + /* there is no need to check again here +*/ + if (tgt.flags.RENEWABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + if (tgt.renew-till < kdc_time) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + tkt := tgt; + new_tkt.starttime := kdc_time; + old_life := tgt.endttime - tgt.starttime; + new_tkt.endtime := min(tgt.renew-till, + new_tkt.starttime + old_life); + else + new_tkt.starttime := kdc_time; + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm, + tgt.endtime); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till) and + (tgt.flags.RENEWABLE is set) then + /* we set the RENEWABLE option for later processing +*/ + set req.kdc-options.RENEWABLE; + req.rtime := min(req.till, tgt.renew-till); + endif + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (tgt.flags.RENEWABLE is set)) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + +new_tkt.starttime+client.max_rlife, + +new_tkt.starttime+server.max_rlife, + +new_tkt.starttime+max_rlife_for_realm, + tgt.renew-till); + else + new_tkt.renew-till := OMIT; /* leave the renew-till field +out */ + endif + if (req.enc-authorization-data is present) then + decrypt req.enc-authorization-data into +decrypted_authorization_data + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + endif + new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data ++ + decrypted_authorization_data; + + new_tkt.key := session; + new_tkt.crealm := tgt.crealm; + new_tkt.cname := req.auth_hdr.ticket.cname; + + if (realm_tgt_is_for(tgt) := tgt.realm) then + /* tgt issued by local realm */ + new_tkt.transited := tgt.transited; + else + /* was issued for this realm by some other realm */ + if (tgt.transited.tr-type not supported) then + error_out(KDC_ERR_TRTYPE_NOSUPP); + endif + new_tkt.transited := compress_transited(tgt.transited + +tgt.realm) + /* Don't check tranited field if TGT for foreign realm, + * or requested not to check */ + if (is_not_foreign_tgt_name(new_tkt.server) + && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + /* Check it, so end-server does not have to + * but don't fail, end-server may still accept it */ + if (check_transited_field(new_tkt.transited) == OK) + set new_tkt.flags.TRANSITED-POLICY-CHECKED; + endif + endif + endif + + encode encrypted part of new_tkt into OCTET STRING; + if (req.kdc-options.ENC-TKT-IN-SKEY is set) then + if (server not specified) then + server = req.second_ticket.client; + endif + if ((req.second_ticket is not a TGT) or + (req.second_ticket.client != server)) then + error_out(KDC_ERR_POLICY); + endif + + new_tkt.enc-part := encrypt OCTET STRING using + using etype_for_key(second-ticket.key), +second-ticket.key; + else + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, +server.p_kvno; + endif + + resp.pvno := 5; + resp.msg-type := KRB_TGS_REP; + resp.crealm := tgt.crealm; + resp.cname := tgt.cname; + resp.ticket := new_tkt; + + resp.key := session; + resp.nonce := req.nonce; + resp.last-req := fetch_last_request_info(client); + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + omit resp.key-expiration; + + resp.sname := new_tkt.sname; + resp.realm := new_tkt.realm; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + encode body of reply into OCTET STRING; + + if (req.padata.authenticator.subkey) + resp.enc-part := encrypt OCTET STRING using use_etype, + req.padata.authenticator.subkey; + else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; + + send(resp); + +A.7. KRB_TGS_REP verification + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key from + the response immediately */ + + if (req.padata.authenticator.subkey) + unencrypted part of resp := decode of decrypt of +resp.enc-part + using resp.enc-part.etype and subkey; + else unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and tgt's session +key; + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + check authorization_data as necessary; + save_for_later(ticket,session,client,server,times,flags); + +A.8. Authenticator generation + + body.authenticator-vno := authenticator vno; /* = 5 */ + body.cname, body.crealm := client name; + if (supplying checksum) then + body.cksum := checksum; + endif + get system_time; + body.ctime, body.cusec := system_time; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + +A.9. KRB_AP_REQ generation + + obtain ticket and session_key from cache; + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REQ */ + + if (desired(MUTUAL_AUTHENTICATION)) then + set packet.ap-options.MUTUAL-REQUIRED; + else + reset packet.ap-options.MUTUAL-REQUIRED; + endif + if (using session key for ticket) then + set packet.ap-options.USE-SESSION-KEY; + else + reset packet.ap-options.USE-SESSION-KEY; + endif + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + packet.ticket := ticket; /* ticket */ + generate authenticator; + encode authenticator into OCTET STRING; + encrypt OCTET STRING into packet.authenticator using session_key; + +A.10. KRB_AP_REQ verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REQ) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.ticket.tkt_vno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.ap_options.USE-SESSION-KEY is set) then + retrieve session key from ticket-granting ticket for + packet.ticket.{sname,srealm,enc-part.etype}; + else + retrieve service key for + packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; + endif + if (no_key_available) then + if (cannot_find_specified_skvno) then + error_out(KRB_AP_ERR_BADKEYVER); + else + error_out(KRB_AP_ERR_NOKEY); + endif + endif + decrypt packet.ticket.enc-part into decr_ticket using retrieved key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + decrypt packet.authenticator into decr_authenticator + using decr_ticket.key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (decr_authenticator.{cname,crealm} != + decr_ticket.{cname,crealm}) then + error_out(KRB_AP_ERR_BADMATCH); + endif + if (decr_ticket.caddr is present) then + if (sender_address(packet) is not in decr_ticket.caddr) then + error_out(KRB_AP_ERR_BADADDR); + endif + elseif (application requires addresses) then + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(decr_authenticator.ctime, + decr_authenticator.cusec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + error_out(KRB_AP_ERR_REPEAT); + endif + save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); + get system_time; + if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or + (decr_ticket.flags.INVALID is set)) then + /* it hasn't yet become valid */ + error_out(KRB_AP_ERR_TKT_NYV); + endif + if (system_time-decr_ticket.endtime > CLOCK_SKEW) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + if (decr_ticket.transited) then + /* caller may ignore the TRANSITED-POLICY-CHECKED and do + * check anyway */ + if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then + if (check_transited_field(decr_ticket.transited) then + error_out(KDC_AP_PATH_NOT_ACCPETED); + endif + endif + endif + /* caller must check decr_ticket.flags for any pertinent details */ + return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); + +A.11. KRB_AP_REP generation + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REP */ + + body.ctime := packet.ctime; + body.cusec := packet.cusec; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part; + +A.12. KRB_AP_REP verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REP) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + cleartext := decrypt(packet.enc-part) using ticket's session key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + if (cleartext.ctime != authenticator.ctime) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.cusec != authenticator.cusec) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.subkey is present) then + save cleartext.subkey for future use; + endif + if (cleartext.seq-number is present) then + save cleartext.seq-number for future verifications; + endif + return(AUTHENTICATION_SUCCEEDED); + +A.13. KRB_SAFE generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_SAFE */ + + body.user-data := buffer; /* DATA */ + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + checksum.cksumtype := checksum type; + compute checksum over body; + checksum.checksum := checksum value; /* checksum.checksum */ + packet.cksum := checksum; + packet.safe-body := body; + +A.14. KRB_SAFE verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_SAFE) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.checksum.cksumtype is not both collision-proof and keyed) +then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (safe_priv_common_checks_ok(packet)) then + set computed_checksum := checksum(packet.body); + if (computed_checksum != packet.checksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + return (packet, PACKET_IS_GENUINE); + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + else + return common_checks_error; + endif + +A.15. KRB_SAFE and KRB_PRIV common checks + + if (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (((packet.timestamp is present) and + (not in_clock_skew(packet.timestamp,packet.usec))) or + (packet.timestamp is not present and timestamp expected)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + + if (((packet.seq-number is present) and + ((not in_sequence(packet.seq-number)))) or + (packet.seq-number is not present and sequence expected)) then + error_out(KRB_AP_ERR_BADORDER); + endif + if (packet.timestamp not present and packet.seq-number not present) +then + error_out(KRB_AP_ERR_MODIFIED); + endif + + save_identifier(packet.{timestamp,usec,s-address}, + sender_principal(packet)); + + return PACKET_IS_OK; + +A.16. KRB_PRIV generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_PRIV */ + + packet.enc-part.etype := encryption type; + + body.user-data := buffer; + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher; + +A.17. KRB_PRIV verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_PRIV) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + + if (safe_priv_common_checks_ok(cleartext)) then + return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); + else + return common_checks_error; + endif + +A.18. KRB_CRED generation + + invoke KRB_TGS; /* obtain tickets to be provided to peer */ + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_CRED */ + + for (tickets[n] in tickets to be forwarded) do + packet.tickets[n] = tickets[n].ticket; + done + + packet.enc-part.etype := encryption type; + + for (ticket[n] in tickets to be forwarded) do + body.ticket-info[n].key = tickets[n].session; + body.ticket-info[n].prealm = tickets[n].crealm; + body.ticket-info[n].pname = tickets[n].cname; + body.ticket-info[n].flags = tickets[n].flags; + body.ticket-info[n].authtime = tickets[n].authtime; + body.ticket-info[n].starttime = tickets[n].starttime; + body.ticket-info[n].endtime = tickets[n].endtime; + body.ticket-info[n].renew-till = tickets[n].renew-till; + body.ticket-info[n].srealm = tickets[n].srealm; + body.ticket-info[n].sname = tickets[n].sname; + body.ticket-info[n].caddr = tickets[n].caddr; + done + + get system_time; + body.timestamp, body.usec := system_time; + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + + if (using nonce) then + body.nonce := nonce; + endif + + if (using s-address) then + body.s-address := sender host addresses; + endif + if (limited recipients) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher + using negotiated encryption key; + +A.19. KRB_CRED verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_CRED) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if ((packet.r-address is present or required) and + (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(packet.timestamp,packet.usec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + if (packet.nonce is required or present) and + (packet.nonce != expected-nonce) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + for (ticket[n] in tickets that were forwarded) do + save_for_later(ticket[n],key[n],principal[n], + server[n],times[n],flags[n]); + return + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +A.20. KRB_ERROR generation + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_ERROR */ + + get system_time; + packet.stime, packet.susec := system_time; + packet.realm, packet.sname := server name; + + if (client time available) then + packet.ctime, packet.cusec := client_time; + endif + packet.error-code := error code; + if (client name available) then + packet.cname, packet.crealm := client name; + endif + if (error text available) then + packet.e-text := error text; + endif + if (error data available) then + packet.e-data := error data; + endif + +B. Definition of common authorization data elements + +This appendix contains the definitions of common authorization data +elements. These common authorization data elements are recursivly defined, +meaning the ad-data for these types will itself contain a sequence of +authorization data whose interpretation is affected by the encapsulating +element. Depending on the meaning of the encapsulating element, the +encapsulated elements may be ignored, might be interpreted as issued +directly by the KDC, or they might be stored in a separate plaintext part +of the ticket. The types of the encapsulating elements are specified as +part of the Kerberos specification because the behavior based on these +values should be understood across implementations whereas other elements +need only be understood by the applications which they affect. + +In the definitions that follow, the value of the ad-type for the element +will be specified in the subsection number, and the value of the ad-data +will be as shown in the ASN.1 structure that follows the subsection +heading. + +B.1. KDC Issued + +AD-KDCIssued SEQUENCE { + ad-checksum[0] Checksum, + i-realm[1] Realm OPTIONAL, + i-sname[2] PrincipalName OPTIONAL, + elements[3] AuthorizationData. +} + +ad-checksum + A checksum over the elements field using a cryptographic checksum + method that is identical to the checksum used to protect the ticket + itself (i.e. using the same hash function and the same encryption + algorithm used to encrypt the ticket) and using a key derived from the + same key used to protect the ticket. +i-realm, i-sname + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + The name of the issuing principal if different from the KDC itself. + This field would be used when the KDC can verify the authenticity of + elements signed by the issuing principal and it allows this KDC to + notify the application server of the validity of those elements. +elements + A sequence of authorization data elements issued by the KDC. + +The KDC-issued ad-data field is intended to provide a means for Kerberos +principal credentials to embed within themselves privilege attributes and +other mechanisms for positive authorization, amplifying the priveleges of +the principal beyond what can be done using a credentials without such an +a-data element. + +This can not be provided without this element because the definition of the +authorization-data field allows elements to be added at will by the bearer +of a TGT at the time that they request service tickets and elements may +also be added to a delegated ticket by inclusion in the authenticator. + +For KDC-issued elements this is prevented because the elements are signed +by the KDC by including a checksum encrypted using the server's key (the +same key used to encrypt the ticket - or a key derived from that key). +Elements encapsulated with in the KDC-issued element will be ignored by the +application server if this "signature" is not present. Further, elements +encapsulated within this element from a ticket granting ticket may be +interpreted by the KDC, and used as a basis according to policy for +including new signed elements within derivative tickets, but they will not +be copied to a derivative ticket directly. If they are copied directly to a +derivative ticket by a KDC that is not aware of this element, the signature +will not be correct for the application ticket elements, and the field will +be ignored by the application server. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + +B.2. Intended for server + +AD-INTENDED-FOR-SERVER SEQUENCE { + intended-server[0] SEQUENCE OF PrincipalName + elements[1] AuthorizationData +} + +AD elements encapsulated within the intended-for-server element may be +ignored if the application server is not in the list of principal names of +intended servers. Further, a KDC issuing a ticket for an application server +can remove this element if the application server is not in the list of +intended servers. + +Application servers should check for their principal name in the +intended-server field of this element. If their principal name is not +found, this element should be ignored. If found, then the encapsulated +elements should be evaluated in the same manner as if they were present in +the top level authorization data field. Applications and application +servers that do not implement this element should reject tickets that +contain authorization data elements of this type. + +B.3. Intended for application class + +AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements +encapsulated within the intended-for-application-class element may be +ignored if the application server is not in one of the named classes of +application servers. Examples of application server classes include +"FILESYSTEM", and other kinds of servers. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + +B.4. If relevant + +AD-IF-RELEVANT AuthorizationData + +AD elements encapsulated within the if-relevant element are intended for +interpretation only by application servers that understand the particular +ad-type of the embedded element. Application servers that do not understand +the type of an element embedded within the if-relevant element may ignore +the uninterpretable element. This element promotes interoperability across +implementations which may have local extensions for authorization. + +B.5. And-Or + +AD-AND-OR SEQUENCE { + condition-count[0] INTEGER, + elements[1] AuthorizationData +} + +When restrictive AD elements encapsulated within the and-or element are +encountered, only the number specified in condition-count of the +encapsulated conditions must be met in order to satisfy this element. This +element may be used to implement an "or" operation by setting the +condition-count field to 1, and it may specify an "and" operation by +setting the condition count to the number of embedded elements. Application +servers that do not implement this element must reject tickets that contain +authorization data elements of this type. + +B.6. Mandatory ticket extensions + +AD-Mandatory-Ticket-Extensions Checksum + +An authorization data element of type mandatory-ticket-extensions specifies +a collision-proof checksum using the same hash algorithm used to protect +the integrity of the ticket itself. This checksum will be calculated over +an individual extension field. If there are more than one extension, +multiple Mandatory-Ticket-Extensions authorization data elements may be +present, each with a checksum for a different extension field. This +restriction indicates that the ticket should not be accepted if a ticket +extension is not present in the ticket for which the checksum does not +match that checksum specified in the authorization data element. +Application servers that do not implement this element must reject tickets +that contain authorization data elements of this type. + +B.7. Authorization Data in ticket extensions + +AD-IN-Ticket-Extensions Checksum + +An authorization data element of type in-ticket-extensions specifies a +collision-proof checksum using the same hash algorithm used to protect the + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +integrity of the ticket itself. This checksum is calculated over a separate +external AuthorizationData field carried in the ticket extensions. +Application servers that do not implement this element must reject tickets +that contain authorization data elements of this type. Application servers +that do implement this element will search the ticket extensions for +authorization data fields, calculate the specified checksum over each +authorization data field and look for one matching the checksum in this +in-ticket-extensions element. If not found, then the ticket must be +rejected. If found, the corresponding authorization data elements will be +interpreted in the same manner as if they were contained in the top level +authorization data field. + +Note that if multiple external authorization data fields are present in a +ticket, each will have a corresponding element of type in-ticket-extensions +in the top level authorization data field, and the external entries will be +linked to the corresponding element by their checksums. + +C. Definition of common ticket extensions + +This appendix contains the definitions of common ticket extensions. Support +for these extensions is optional. However, certain extensions have +associated authorization data elements that may require rejection of a +ticket containing an extension by application servers that do not implement +the particular extension. Other extensions have been defined beyond those +described in this specification. Such extensions are described elswhere and +for some of those extensions the reserved number may be found in the list +of constants. + +It is known that older versions of Kerberos did not support this field, and +that some clients will strip this field from a ticket when they parse and +then reassemble a ticket as it is passed to the application servers. The +presence of the extension will not break such clients, but any functionaly +dependent on the extensions will not work when such tickets are handled by +old clients. In such situations, some implementation may use alternate +methods to transmit the information in the extensions field. + +C.1. Null ticket extension + +TE-NullExtension OctetString -- The empty Octet String + +The te-data field in the null ticket extension is an octet string of lenght +zero. This extension may be included in a ticket granting ticket so that +the KDC can determine on presentation of the ticket granting ticket whether +the client software will strip the extensions field. + +C.2. External Authorization Data + +TE-ExternalAuthorizationData AuthorizationData + +The te-data field in the external authorization data ticket extension is +field of type AuthorizationData containing one or more authorization data +elements. If present, a corresponding authorization data element will be +present in the primary authorization data for the ticket and that element +will contain a checksum of the external authorization data ticket +extension. + ------------------------------------------------------------------------ +[TM] Project Athena, Athena, and Kerberos are trademarks of the +Massachusetts Institute of Technology (MIT). No commercial use of these +trademarks may be made without prior written permission of MIT. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +[1] Note, however, that many applications use Kerberos' functions only upon +the initiation of a stream-based network connection. Unless an application +subsequently provides integrity protection for the data stream, the +identity verification applies only to the initiation of the connection, and +does not guarantee that subsequent messages on the connection originate +from the same principal. + +[2] Secret and private are often used interchangeably in the literature. In +our usage, it takes two (or more) to share a secret, thus a shared DES key +is a secret key. Something is only private when no one but its owner knows +it. Thus, in public key cryptosystems, one has a public and a private key. + +[3] Of course, with appropriate permission the client could arrange +registration of a separately-named prin- cipal in a remote realm, and +engage in normal exchanges with that realm's services. However, for even +small numbers of clients this becomes cumbersome, and more automatic +methods as described here are necessary. + +[4] Though it is permissible to request or issue tick- ets with no network +addresses specified. + +[5] The password-changing request must not be honored unless the requester +can provide the old password (the user's current secret key). Otherwise, it +would be possible for someone to walk up to an unattended ses- sion and +change another user's password. + +[6] To authenticate a user logging on to a local system, the credentials +obtained in the AS exchange may first be used in a TGS exchange to obtain +credentials for a local server. Those credentials must then be verified by +a local server through successful completion of the Client/Server exchange. + +[7] "Random" means that, among other things, it should be impossible to +guess the next session key based on knowledge of past session keys. This +can only be achieved in a pseudo-random number generator if it is based on +cryptographic principles. It is more desirable to use a truly random number +generator, such as one based on measurements of random physical phenomena. + +[8] Tickets contain both an encrypted and unencrypted portion, so cleartext +here refers to the entire unit, which can be copied from one message and +replayed in another without any cryptographic skill. + +[9] Note that this can make applications based on unreliable transports +difficult to code correctly. If the transport might deliver duplicated +messages, either a new authenticator must be generated for each retry, or +the application server must match requests and replies and replay the first +reply in response to a detected duplicate. + +[10] This is used for user-to-user authentication as described in [8]. + +[11] Note that the rejection here is restricted to authenticators from the +same principal to the same server. Other client principals communicating +with the same server principal should not be have their authenticators +rejected if the time and microsecond fields happen to match some other +client's authenticator. + +[12] In the Kerberos version 4 protocol, the timestamp in the reply was the +client's timestamp plus one. This is not necessary in version 5 because +version 5 messages are formatted in such a way that it is not possible to + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + +create the reply by judicious message surgery (even in encrypted form) +without knowledge of the appropriate encryption keys. + +[13] Note that for encrypting the KRB_AP_REP message, the sub-session key +is not used, even if present in the Authenticator. + +[14] Implementations of the protocol may wish to provide routines to choose +subkeys based on session keys and random numbers and to generate a +negotiated key to be returned in the KRB_AP_REP message. + +[15]This can be accomplished in several ways. It might be known beforehand +(since the realm is part of the principal identifier), it might be stored +in a nameserver, or it might be obtained from a configura- tion file. If +the realm to be used is obtained from a nameserver, there is a danger of +being spoofed if the nameservice providing the realm name is not authenti- +cated. This might result in the use of a realm which has been compromised, +and would result in an attacker's ability to compromise the authentication +of the application server to the client. + +[16] If the client selects a sub-session key, care must be taken to ensure +the randomness of the selected sub- session key. One approach would be to +generate a random number and XOR it with the session key from the +ticket-granting ticket. + +[17] This allows easy implementation of user-to-user authentication [8], +which uses ticket-granting ticket session keys in lieu of secret server +keys in situa- tions where such secret keys could be easily comprom- ised. + +[18] For the purpose of appending, the realm preceding the first listed +realm is considered to be the null realm (""). + +[19] For the purpose of interpreting null subfields, the client's realm is +considered to precede those in the transited field, and the server's realm +is considered to follow them. + +[20] This means that a client and server running on the same host and +communicating with one another using the KRB_SAFE messages should not share +a common replay cache to detect KRB_SAFE replays. + +[21] The implementation of the Kerberos server need not combine the +database and the server on the same machine; it is feasible to store the +principal database in, say, a network name service, as long as the entries +stored therein are protected from disclosure to and modification by +unauthorized parties. However, we recommend against such strategies, as +they can make system management and threat analysis quite complex. + +[22] See the discussion of the padata field in section 5.4.2 for details on +why this can be useful. + +[23] Warning for implementations that unpack and repack data structures +during the generation and verification of embedded checksums: Because any +checksums applied to data structures must be checked against the original +data the length of bit strings must be preserved within a data structure +between the time that a checksum is generated through transmission to the +time that the checksum is verified. + +[24] It is NOT recommended that this time value be used to adjust the +workstation's clock since the workstation cannot reliably determine that +such a KRB_AS_REP actually came from the proper KDC in a timely manner. + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + + +INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 + + + +[25] Note, however, that if the time is used as the nonce, one must make +sure that the workstation time is monotonically increasing. If the time is +ever reset backwards, there is a small, but finite, probability that a +nonce will be reused. + +[27] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[29] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[31] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[32] If supported by the encryption method in use, an initialization vector +may be passed to the encryption procedure, in order to achieve proper +cipher chaining. The initialization vector might come from the last block +of the ciphertext from the previous KRB_PRIV message, but it is the +application's choice whether or not to use such an initialization vector. +If left out, the default initialization vector for the encryption algorithm +will be used. + +[33] This prevents an attacker who generates an incorrect AS request from +obtaining verifiable plaintext for use in an off-line password guessing +attack. + +[35] In the above specification, UNTAGGED OCTET STRING(length) is the +notation for an octet string with its tag and length removed. It is not a +valid ASN.1 type. The tag bits and length must be removed from the +confounder since the purpose of the confounder is so that the message +starts with random data, but the tag and its length are fixed. For other +fields, the length and tag would be redundant if they were included because +they are specified by the encryption type. [36] The ordering of the fields +in the CipherText is important. Additionally, messages encoded in this +format must include a length as part of the msg-seq field. This allows the +recipient to verify that the message has not been truncated. Without a +length, an attacker could use a chosen plaintext attack to generate a +message which could be truncated, while leaving the checksum intact. Note +that if the msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, +then the length is part of that encoding. + +[37] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[38] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[39] A variant of the key is used to limit the use of a key to a particular +function, separating the functions of generating a checksum from other +encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 +was chosen because it maintains key parity. The properties of DES precluded +the use of the complement. The same constant is used for similar purpose in +the Message Integrity Check in the Privacy Enhanced Mail standard. + +[40] This error carries additional information in the e- data field. The +contents of the e-data field for this message is described in section +5.9.1. + + +Neuman, Ts'o, Kohl Expires: 18 May 1999 + diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt new file mode 100644 index 0000000..16af15d --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt @@ -0,0 +1,6780 @@ +INTERNET-DRAFT Clifford Neuman + John Kohl + Theodore Ts'o + June 25, 1999 + Expires December 25, 1999 +draft-ietf-cat-kerberos-revisions-04.txt + +The Kerberos Network Authentication Service (V5) + +STATUS OF THIS MEMO + +This document is an Internet-Draft and is in full conformance with all +provisions of Section 10 of RFC2026. 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. To learn the current status of any +Internet-Draft, please check the '1id-abstracts.txt' listing contained in +the Internet-Drafts Shadow Directories. + +The distribution of this memo is unlimited. It is filed as +draft-ietf-cat-kerberos-revisions-04.txt, and expires December 25th, 1999. +Please send comments to: krb-protocol@MIT.EDU + +ABSTRACT + +This document provides an overview and specification of Version 5 of the +Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol +and its intended use that require more detailed or clearer explanation than +was provided in RFC1510. This document is intended to provide a detailed +description of the protocol, suitable for implementation, together with +descriptions of the appropriate use of protocol messages and fields within +those messages. + +This document is not intended to describe Kerberos to the end user, system +administrator, or application developer. Higher level papers describing +Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], +are available elsewhere. + +OVERVIEW + +This INTERNET-DRAFT describes the concepts and model upon which the Kerberos +network authentication system is based. It also specifies Version 5 of the +Kerberos protocol. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The motivations, goals, assumptions, and rationale behind most design +decisions are treated cursorily; they are more fully described in a paper +available in IEEE communications [NT94] and earlier in the Kerberos portion +of the Athena Technical Plan [MNSS87]. The protocols have been a proposed +standard and are being considered for advancement for draft standard through +the IETF standard process. Comments are encouraged on the presentation, but +only minor refinements to the protocol as implemented or extensions that fit +within current protocol framework will be considered at this time. + +Requests for addition to an electronic mailing list for discussion of +Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. +This mailing list is gatewayed onto the Usenet as the group +comp.protocols.kerberos. Requests for further information, including +documents and code availability, may be sent to info-kerberos@MIT.EDU. + +BACKGROUND + +The Kerberos model is based in part on Needham and Schroeder's trusted +third-party authentication protocol [NS78] and on modifications suggested by +Denning and Sacco [DS81]. The original design and implementation of Kerberos +Versions 1 through 4 was the work of two former Project Athena staff +members, Steve Miller of Digital Equipment Corporation and Clifford Neuman +(now at the Information Sciences Institute of the University of Southern +California), along with Jerome Saltzer, Technical Director of Project +Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many other members +of Project Athena have also contributed to the work on Kerberos. + +Version 5 of the Kerberos protocol (described in this document) has evolved +from Version 4 based on new requirements and desires for features not +available in Version 4. The design of Version 5 of the Kerberos protocol was +led by Clifford Neuman and John Kohl with much input from the community. The +development of the MIT reference implementation was led at MIT by John Kohl +and Theodore T'so, with help and contributed code from many others. Since +RFC1510 was issued, extensions and revisions to the protocol have been +proposed by many individuals. Some of these proposals are reflected in this +document. Where such changes involved significant effort, the document cites +the contribution of the proposer. + +Reference implementations of both version 4 and version 5 of Kerberos are +publicly available and commercial implementations have been developed and +are widely used. Details on the differences between Kerberos Versions 4 and +5 can be found in [KNT92]. + +1. Introduction + +Kerberos provides a means of verifying the identities of principals, (e.g. a +workstation user or a network server) on an open (unprotected) network. This +is accomplished without relying on assertions by the host operating system, +without basing trust on host addresses, without requiring physical security +of all the hosts on the network, and under the assumption that packets +traveling along the network can be read, modified, and inserted at will[1]. +Kerberos performs authentication under these conditions as a trusted +third-party authentication service by using conventional (shared secret key +[2] cryptography. Kerberos extensions have been proposed and implemented +that provide for the use of public key cryptography during certain phases of +the authentication protocol. These extensions provide for authentication of + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +users registered with public key certification authorities, and allow the +system to provide certain benefits of public key cryptography in situations +where they are needed. + +The basic Kerberos authentication process proceeds as follows: A client +sends a request to the authentication server (AS) requesting 'credentials' +for a given server. The AS responds with these credentials, encrypted in the +client's key. The credentials consist of 1) a 'ticket' for the server and 2) +a temporary encryption key (often called a "session key"). The client +transmits the ticket (which contains the client's identity and a copy of the +session key, all encrypted in the server's key) to the server. The session +key (now shared by the client and server) is used to authenticate the +client, and may optionally be used to authenticate the server. It may also +be used to encrypt further communication between the two parties or to +exchange a separate sub-session key to be used to encrypt further +communication. + +Implementation of the basic protocol consists of one or more authentication +servers running on physically secure hosts. The authentication servers +maintain a database of principals (i.e., users and servers) and their secret +keys. Code libraries provide encryption and implement the Kerberos protocol. +In order to add authentication to its transactions, a typical network +application adds one or two calls to the Kerberos library directly or +through the Generic Security Services Application Programming Interface, +GSSAPI, described in separate document. These calls result in the +transmission of the necessary messages to achieve authentication. + +The Kerberos protocol consists of several sub-protocols (or exchanges). +There are two basic methods by which a client can ask a Kerberos server for +credentials. In the first approach, the client sends a cleartext request for +a ticket for the desired server to the AS. The reply is sent encrypted in +the client's secret key. Usually this request is for a ticket-granting +ticket (TGT) which can later be used with the ticket-granting server (TGS). +In the second method, the client sends a request to the TGS. The client uses +the TGT to authenticate itself to the TGS in the same manner as if it were +contacting any other application server that requires Kerberos +authentication. The reply is encrypted in the session key from the TGT. +Though the protocol specification describes the AS and the TGS as separate +servers, they are implemented in practice as different protocol entry points +within a single Kerberos server. + +Once obtained, credentials may be used to verify the identity of the +principals in a transaction, to ensure the integrity of messages exchanged +between them, or to preserve privacy of the messages. The application is +free to choose whatever protection may be necessary. + +To verify the identities of the principals in a transaction, the client +transmits the ticket to the application server. Since the ticket is sent "in +the clear" (parts of it are encrypted, but this encryption doesn't thwart +replay) and might be intercepted and reused by an attacker, additional +information is sent to prove that the message originated with the principal +to whom the ticket was issued. This information (called the authenticator) +is encrypted in the session key, and includes a timestamp. The timestamp +proves that the message was recently generated and is not a replay. +Encrypting the authenticator in the session key proves that it was generated +by a party possessing the session key. Since no one except the requesting +principal and the server know the session key (it is never sent over the +network in the clear) this guarantees the identity of the client. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The integrity of the messages exchanged between principals can also be +guaranteed using the session key (passed in the ticket and contained in the +credentials). This approach provides detection of both replay attacks and +message stream modification attacks. It is accomplished by generating and +transmitting a collision-proof checksum (elsewhere called a hash or digest +function) of the client's message, keyed with the session key. Privacy and +integrity of the messages exchanged between principals can be secured by +encrypting the data to be passed using the session key contained in the +ticket or the subsession key found in the authenticator. + +The authentication exchanges mentioned above require read-only access to the +Kerberos database. Sometimes, however, the entries in the database must be +modified, such as when adding new principals or changing a principal's key. +This is done using a protocol between a client and a third Kerberos server, +the Kerberos Administration Server (KADM). There is also a protocol for +maintaining multiple copies of the Kerberos database. Neither of these +protocols are described in this document. + +1.1. Cross-Realm Operation + +The Kerberos protocol is designed to operate across organizational +boundaries. A client in one organization can be authenticated to a server in +another. Each organization wishing to run a Kerberos server establishes its +own 'realm'. The name of the realm in which a client is registered is part +of the client's name, and can be used by the end-service to decide whether +to honor a request. + +By establishing 'inter-realm' keys, the administrators of two realms can +allow a client authenticated in the local realm to prove its identity to +servers in other realms[3]. The exchange of inter-realm keys (a separate key +may be used for each direction) registers the ticket-granting service of +each realm as a principal in the other realm. A client is then able to +obtain a ticket-granting ticket for the remote realm's ticket-granting +service from its local realm. When that ticket-granting ticket is used, the +remote ticket-granting service uses the inter-realm key (which usually +differs from its own normal TGS key) to decrypt the ticket-granting ticket, +and is thus certain that it was issued by the client's own TGS. Tickets +issued by the remote ticket-granting service will indicate to the +end-service that the client was authenticated from another realm. + +A realm is said to communicate with another realm if the two realms share an +inter-realm key, or if the local realm shares an inter-realm key with an +intermediate realm that communicates with the remote realm. An +authentication path is the sequence of intermediate realms that are +transited in communicating from one realm to another. + +Realms are typically organized hierarchically. Each realm shares a key with +its parent and a different key with each child. If an inter-realm key is not +directly shared by two realms, the hierarchical organization allows an +authentication path to be easily constructed. If a hierarchical organization +is not used, it may be necessary to consult a database in order to construct +an authentication path between realms. + +Although realms are typically hierarchical, intermediate realms may be +bypassed to achieve cross-realm authentication through alternate +authentication paths (these might be established to make communication +between two realms more efficient). It is important for the end-service to + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +know which realms were transited when deciding how much faith to place in +the authentication process. To facilitate this decision, a field in each +ticket contains the names of the realms that were involved in authenticating +the client. + +The application server is ultimately responsible for accepting or rejecting +authentication and should check the transited field. The application server +may choose to rely on the KDC for the application server's realm to check +the transited field. The application server's KDC will set the +TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate +realms may also check the transited field as they issue +ticket-granting-tickets for other realms, but they are encouraged not to do +so. A client may request that the KDC's not check the transited field by +setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not +required to honor this flag. + +1.2. Authorization + +As an authentication service, Kerberos provides a means of verifying the +identity of principals on a network. Authentication is usually useful +primarily as a first step in the process of authorization, determining +whether a client may use a service, which objects the client is allowed to +access, and the type of access allowed for each. Kerberos does not, by +itself, provide authorization. Possession of a client ticket for a service +provides only for authentication of the client to that service, and in the +absence of a separate authorization procedure, it should not be considered +by an application as authorizing the use of that service. + +Such separate authorization methods may be implemented as application +specific access control functions and may be based on files such as the +application server, or on separately issued authorization credentials such +as those based on proxies [Neu93] , or on other authorization services. + +Applications should not be modified to accept the issuance of a service +ticket by the Kerberos server (even by an modified Kerberos server) as +granting authority to use the service, since such applications may become +vulnerable to the bypass of this authorization check in an environment if +they interoperate with other KDCs or where other options for application +authentication (e.g. the PKTAPP proposal) are provided. + +1.3. Environmental assumptions + +Kerberos imposes a few assumptions on the environment in which it can +properly function: + + * 'Denial of service' attacks are not solved with Kerberos. There are + places in these protocols where an intruder can prevent an application + from participating in the proper authentication steps. Detection and + solution of such attacks (some of which can appear to be nnot-uncommon + 'normal' failure modes for the system) is usually best left to the + human administrators and users. + * Principals must keep their secret keys secret. If an intruder somehow + steals a principal's key, it will be able to masquerade as that + principal or impersonate any server to the legitimate principal. + * 'Password guessing' attacks are not solved by Kerberos. If a user + chooses a poor password, it is possible for an attacker to successfully + mount an offline dictionary attack by repeatedly attempting to decrypt, + with successive entries from a dictionary, messages obtained which are + encrypted under a key derived from the user's password. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + * Each host on the network must have a clock which is 'loosely + synchronized' to the time of the other hosts; this synchronization is + used to reduce the bookkeeping needs of application servers when they + do replay detection. The degree of "looseness" can be configured on a + per-server basis, but is typically on the order of 5 minutes. If the + clocks are synchronized over the network, the clock synchronization + protocol must itself be secured from network attackers. + * Principal identifiers are not recycled on a short-term basis. A typical + mode of access control will use access control lists (ACLs) to grant + permissions to particular principals. If a stale ACL entry remains for + a deleted principal and the principal identifier is reused, the new + principal will inherit rights specified in the stale ACL entry. By not + re-using principal identifiers, the danger of inadvertent access is + removed. + +1.4. Glossary of terms + +Below is a list of terms used throughout this document. + +Authentication + Verifying the claimed identity of a principal. +Authentication header + A record containing a Ticket and an Authenticator to be presented to a + server as part of the authentication process. +Authentication path + A sequence of intermediate realms transited in the authentication + process when communicating from one realm to another. +Authenticator + A record containing information that can be shown to have been recently + generated using the session key known only by the client and server. +Authorization + The process of determining whether a client may use a service, which + objects the client is allowed to access, and the type of access allowed + for each. +Capability + A token that grants the bearer permission to access an object or + service. In Kerberos, this might be a ticket whose use is restricted by + the contents of the authorization data field, but which lists no + network addresses, together with the session key necessary to use the + ticket. +Ciphertext + The output of an encryption function. Encryption transforms plaintext + into ciphertext. +Client + A process that makes use of a network service on behalf of a user. Note + that in some cases a Server may itself be a client of some other server + (e.g. a print server may be a client of a file server). +Credentials + A ticket plus the secret session key necessary to successfully use that + ticket in an authentication exchange. +KDC + Key Distribution Center, a network service that supplies tickets and + temporary session keys; or an instance of that service or the host on + which it runs. The KDC services both initial ticket and ticket-granting + ticket requests. The initial ticket portion is sometimes referred to as + the Authentication Server (or service). The ticket-granting ticket + portion is sometimes referred to as the ticket-granting server (or + service). + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Kerberos + Aside from the 3-headed dog guarding Hades, the name given to Project + Athena's authentication service, the protocol used by that service, or + the code used to implement the authentication service. +Plaintext + The input to an encryption function or the output of a decryption + function. Decryption transforms ciphertext into plaintext. +Principal + A uniquely named client or server instance that participates in a + network communication. +Principal identifier + The name used to uniquely identify each different principal. +Seal + To encipher a record containing several fields in such a way that the + fields cannot be individually replaced without either knowledge of the + encryption key or leaving evidence of tampering. +Secret key + An encryption key shared by a principal and the KDC, distributed + outside the bounds of the system, with a long lifetime. In the case of + a human user's principal, the secret key is derived from a password. +Server + A particular Principal which provides a resource to network clients. + The server is sometimes refered to as the Application Server. +Service + A resource provided to network clients; often provided by more than one + server (for example, remote file service). +Session key + A temporary encryption key used between two principals, with a lifetime + limited to the duration of a single login "session". +Sub-session key + A temporary encryption key used between two principals, selected and + exchanged by the principals using the session key, and with a lifetime + limited to the duration of a single association. +Ticket + A record that helps a client authenticate itself to a server; it + contains the client's identity, a session key, a timestamp, and other + information, all sealed using the server's secret key. It only serves + to authenticate a client when presented along with a fresh + Authenticator. + +2. Ticket flag uses and requests + +Each Kerberos ticket contains a set of flags which are used to indicate +various attributes of that ticket. Most flags may be requested by a client +when the ticket is obtained; some are automatically turned on and off by a +Kerberos server as required. The following sections explain what the various +flags mean, and gives examples of reasons to use such a flag. + +2.1. Initial and pre-authenticated tickets + +The INITIAL flag indicates that a ticket was issued using the AS protocol +and not issued based on a ticket-granting ticket. Application servers that +want to require the demonstrated knowledge of a client's secret key (e.g. a +password-changing program) can insist that this flag be set in any tickets +they accept, and thus be assured that the client's key was recently +presented to the application client. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the +initial authentication, regardless of whether the current ticket was issued +directly (in which case INITIAL will also be set) or issued on the basis of +a ticket-granting ticket (in which case the INITIAL flag is clear, but the +PRE-AUTHENT and HW-AUTHENT flags are carried forward from the +ticket-granting ticket). + +2.2. Invalid tickets + +The INVALID flag indicates that a ticket is invalid. Application servers +must reject tickets which have this flag set. A postdated ticket will +usually be issued in this form. Invalid tickets must be validated by the KDC +before use, by presenting them to the KDC in a TGS request with the VALIDATE +option specified. The KDC will only validate tickets after their starttime +has passed. The validation is required so that postdated tickets which have +been stolen before their starttime can be rendered permanently invalid +(through a hot-list mechanism) (see section 3.3.3.1). + +2.3. Renewable tickets + +Applications may desire to hold tickets which can be valid for long periods +of time. However, this can expose their credentials to potential theft for +equally long periods, and those stolen credentials would be valid until the +expiration time of the ticket(s). Simply using short-lived tickets and +obtaining new ones periodically would require the client to have long-term +access to its secret key, an even greater risk. Renewable tickets can be +used to mitigate the consequences of theft. Renewable tickets have two +"expiration times": the first is when the current instance of the ticket +expires, and the second is the latest permissible value for an individual +expiration time. An application client must periodically (i.e. before it +expires) present a renewable ticket to the KDC, with the RENEW option set in +the KDC request. The KDC will issue a new ticket with a new session key and +a later expiration time. All other fields of the ticket are left unmodified +by the renewal process. When the latest permissible expiration time arrives, +the ticket expires permanently. At each renewal, the KDC may consult a +hot-list to determine if the ticket had been reported stolen since its last +renewal; it will refuse to renew such stolen tickets, and thus the usable +lifetime of stolen tickets is reduced. + +The RENEWABLE flag in a ticket is normally only interpreted by the +ticket-granting service (discussed below in section 3.3). It can usually be +ignored by application servers. However, some particularly careful +application servers may wish to disallow renewable tickets. + +If a renewable ticket is not renewed by its expiration time, the KDC will +not renew the ticket. The RENEWABLE flag is reset by default, but a client +may request it be set by setting the RENEWABLE option in the KRB_AS_REQ +message. If it is set, then the renew-till field in the ticket contains the +time after which the ticket may not be renewed. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +2.4. Postdated tickets + +Applications may occasionally need to obtain tickets for use much later, +e.g. a batch submission system would need tickets to be valid at the time +the batch job is serviced. However, it is dangerous to hold valid tickets in +a batch queue, since they will be on-line longer and more prone to theft. +Postdated tickets provide a way to obtain these tickets from the KDC at job +submission time, but to leave them "dormant" until they are activated and +validated by a further request of the KDC. If a ticket theft were reported +in the interim, the KDC would refuse to validate the ticket, and the thief +would be foiled. + +The MAY-POSTDATE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. This flag +must be set in a ticket-granting ticket in order to issue a postdated ticket +based on the presented ticket. It is reset by default; it may be requested +by a client by setting the ALLOW-POSTDATE option in the KRB_AS_REQ message. +This flag does not allow a client to obtain a postdated ticket-granting +ticket; postdated ticket-granting tickets can only by obtained by requesting +the postdating in the KRB_AS_REQ message. The life (endtime-starttime) of a +postdated ticket will be the remaining life of the ticket-granting ticket at +the time of the request, unless the RENEWABLE option is also set, in which +case it can be the full life (endtime-starttime) of the ticket-granting +ticket. The KDC may limit how far in the future a ticket may be postdated. + +The POSTDATED flag indicates that a ticket has been postdated. The +application server can check the authtime field in the ticket to see when +the original authentication occurred. Some services may choose to reject +postdated tickets, or they may only accept them within a certain period +after the original authentication. When the KDC issues a POSTDATED ticket, +it will also be marked as INVALID, so that the application client must +present the ticket to the KDC to be validated before use. + +2.5. Proxiable and proxy tickets + +At times it may be necessary for a principal to allow a service to perform +an operation on its behalf. The service must be able to take on the identity +of the client, but only for a particular purpose. A principal can allow a +service to take on the principal's identity for a particular purpose by +granting it a proxy. + +The process of granting a proxy using the proxy and proxiable flags is used +to provide credentials for use with specific services. Though conceptually +also a proxy, user's wishing to delegate their identity for ANY purpose must +use the ticket forwarding mechanism described in the next section to forward +a ticket granting ticket. + +The PROXIABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. When set, +this flag tells the ticket-granting server that it is OK to issue a new +ticket (but not a ticket-granting ticket) with a different network address +based on this ticket. This flag is set if requested by the client on initial +authentication. By default, the client will request that it be set when +requesting a ticket granting ticket, and reset when requesting any other +ticket. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +This flag allows a client to pass a proxy to a server to perform a remote +request on its behalf, e.g. a print service client can give the print server +a proxy to access the client's files on a particular file server in order to +satisfy a print request. + +In order to complicate the use of stolen credentials, Kerberos tickets are +usually valid from only those network addresses specifically included in the +ticket[4]. When granting a proxy, the client must specify the new network +address from which the proxy is to be used, or indicate that the proxy is to +be issued for use from any address. + +The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. +Application servers may check this flag and at their option they may require +additional authentication from the agent presenting the proxy in order to +provide an audit trail. + +2.6. Forwardable tickets + +Authentication forwarding is an instance of a proxy where the service is +granted complete use of the client's identity. An example where it might be +used is when a user logs in to a remote system and wants authentication to +work from that system as if the login were local. + +The FORWARDABLE flag in a ticket is normally only interpreted by the +ticket-granting service. It can be ignored by application servers. The +FORWARDABLE flag has an interpretation similar to that of the PROXIABLE +flag, except ticket-granting tickets may also be issued with different +network addresses. This flag is reset by default, but users may request that +it be set by setting the FORWARDABLE option in the AS request when they +request their initial ticket- granting ticket. + +This flag allows for authentication forwarding without requiring the user to +enter a password again. If the flag is not set, then authentication +forwarding is not permitted, but the same result can still be achieved if +the user engages in the AS exchange specifying the requested network +addresses and supplies a password. + +The FORWARDED flag is set by the TGS when a client presents a ticket with +the FORWARDABLE flag set and requests a forwarded ticket by specifying the +FORWARDED KDC option and supplying a set of addresses for the new ticket. It +is also set in all tickets issued based on tickets with the FORWARDED flag +set. Application servers may choose to process FORWARDED tickets differently +than non-FORWARDED tickets. + +2.7. Other KDC options + +There are two additional options which may be set in a client's request of +the KDC. The RENEWABLE-OK option indicates that the client will accept a +renewable ticket if a ticket with the requested life cannot otherwise be +provided. If a ticket with the requested life cannot be provided, then the +KDC may issue a renewable ticket with a renew-till equal to the the +requested endtime. The value of the renew-till field may still be adjusted +by site-determined limits or limits imposed by the individual principal or +server. + +The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. +It indicates that the ticket to be issued for the end server is to be +encrypted in the session key from the a additional second ticket-granting +ticket provided with the request. See section 3.3.3 for specific details. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3. Message Exchanges + +The following sections describe the interactions between network clients and +servers and the messages involved in those exchanges. + +3.1. The Authentication Service Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_AS_REQ 5.4.1 + 2. Kerberos to client KRB_AS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The Authentication Service (AS) Exchange between the client and the Kerberos +Authentication Server is initiated by a client when it wishes to obtain +authentication credentials for a given server but currently holds no +credentials. In its basic form, the client's secret key is used for +encryption and decryption. This exchange is typically used at the initiation +of a login session to obtain credentials for a Ticket-Granting Server which +will subsequently be used to obtain credentials for other servers (see +section 3.3) without requiring further use of the client's secret key. This +exchange is also used to request credentials for services which must not be +mediated through the Ticket-Granting Service, but rather require a +principal's secret key, such as the password-changing service[5]. This +exchange does not by itself provide any assurance of the the identity of the +user[6]. + +The exchange consists of two messages: KRB_AS_REQ from the client to +Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these +messages are described in sections 5.4.1, 5.4.2, and 5.9.1. + +In the request, the client sends (in cleartext) its own identity and the +identity of the server for which it is requesting credentials. The response, +KRB_AS_REP, contains a ticket for the client to present to the server, and a +session key that will be shared by the client and the server. The session +key and additional information are encrypted in the client's secret key. The +KRB_AS_REP message contains information which can be used to detect replays, +and to associate it with the message to which it replies. Various errors can +occur; these are indicated by an error response (KRB_ERROR) instead of the +KRB_AS_REP response. The error message is not encrypted. The KRB_ERROR +message contains information which can be used to associate it with the +message to which it replies. The lack of encryption in the KRB_ERROR message +precludes the ability to detect replays, fabrications, or modifications of +such messages. + +Without preautentication, the authentication server does not know whether +the client is actually the principal named in the request. It simply sends a +reply without knowing or caring whether they are the same. This is +acceptable because nobody but the principal whose identity was given in the +request will be able to use the reply. Its critical information is encrypted +in that principal's key. The initial request supports an optional field that +can be used to pass additional information that might be needed for the +initial exchange. This field may be used for preauthentication as described +in section [hl<>]. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.1.1. Generation of KRB_AS_REQ message + +The client may specify a number of options in the initial request. Among +these options are whether pre-authentication is to be performed; whether the +requested ticket is to be renewable, proxiable, or forwardable; whether it +should be postdated or allow postdating of derivative tickets; and whether a +renewable ticket will be accepted in lieu of a non-renewable ticket if the +requested ticket expiration date cannot be satisfied by a non-renewable +ticket (due to configuration constraints; see section 4). See section A.1 +for pseudocode. + +The client prepares the KRB_AS_REQ message and sends it to the KDC. + +3.1.2. Receipt of KRB_AS_REQ message + +If all goes well, processing the KRB_AS_REQ message will result in the +creation of a ticket for the client to present to the server. The format for +the ticket is described in section 5.3.1. The contents of the ticket are +determined as follows. + +3.1.3. Generation of KRB_AS_REP message + +The authentication server looks up the client and server principals named in +the KRB_AS_REQ in its database, extracting their respective keys. If +required, the server pre-authenticates the request, and if the +pre-authentication check fails, an error message with the code +KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the +requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP +is returned. Otherwise it generates a 'random' session key[7]. + +If there are multiple encryption keys registered for a client in the +Kerberos database (or if the key registered supports multiple encryption +types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS +request is used by the KDC to select the encryption method to be used for +encrypting the response to the client. If there is more than one supported, +strong encryption type in the etype list, the first valid etype for which an +encryption key is available is used. The encryption method used to respond +to a TGS request is taken from the keytype of the session key found in the +ticket granting ticket. [***I will change the example keytypes to be 3DES +based examples 7/14***] + +When the etype field is present in a KDC request, whether an AS or TGS +request, the KDC will attempt to assign the type of the random session key +from the list of methods in the etype field. The KDC will select the +appropriate type using the list of methods provided together with +information from the Kerberos database indicating acceptable encryption +methods for the application server. The KDC will not issue tickets with a +weak session key encryption type. + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise +the requested start time is checked against the policy of the local realm +(the administrator might decide to prohibit certain types or ranges of +postdated tickets), and if acceptable, the ticket's start time is set as + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +requested and the INVALID flag is set in the new ticket. The postdated +ticket must be validated before use by presenting it to the KDC after the +start time has been reached. + +The expiration time of the ticket will be set to the minimum of the +following: + + * The expiration time (endtime) requested in the KRB_AS_REQ message. + * The ticket's start time plus the maximum allowable lifetime associated + with the client principal (the authentication server's database + includes a maximum ticket lifetime field in each principal's record; + see section 4). + * The ticket's start time plus the maximum allowable lifetime associated + with the server principal. + * The ticket's start time plus the maximum lifetime set by the policy of + the local realm. + +If the requested expiration time minus the start time (as determined above) +is less than a site-determined minimum lifetime, an error message with code +KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the +ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' +option was requested, then the 'RENEWABLE' flag is set in the new ticket, +and the renew-till value is set as if the 'RENEWABLE' option were requested +(the field and option names are described fully in section 5.4.1). + +If the RENEWABLE option has been requested or if the RENEWABLE-OK option has +been set and a renewable ticket is to be issued, then the renew-till field +is set to the minimum of: + + * Its requested value. + * The start time of the ticket plus the minimum of the two maximum + renewable lifetimes associated with the principals' database entries. + * The start time of the ticket plus the maximum renewable lifetime set by + the policy of the local realm. + +The flags field of the new ticket will have the following options set if +they have been requested and if the policy of the local realm allows: +FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new +ticket is post-dated (the start time is in the future), its INVALID flag +will also be set. + +If all of the above succeed, the server formats a KRB_AS_REP message (see +section 5.4.2), copying the addresses in the request into the caddr of the +response, placing any required pre-authentication data into the padata of +the response, and encrypts the ciphertext part in the client's key using the +requested encryption method, and sends it to the client. See section A.2 for +pseudocode. + +3.1.4. Generation of KRB_ERROR message + +Several errors can occur, and the Authentication Server responds by +returning an error message, KRB_ERROR, to the client, with the error-code +and e-text fields set to appropriate values. The error message contents and +details are described in Section 5.9.1. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.1.5. Receipt of KRB_AS_REP message + +If the reply message type is KRB_AS_REP, then the client verifies that the +cname and crealm fields in the cleartext portion of the reply match what it +requested. If any padata fields are present, they may be used to derive the +proper secret key to decrypt the message. The client decrypts the encrypted +part of the response using its secret key, verifies that the nonce in the +encrypted part matches the nonce it supplied in its request (to detect +replays). It also verifies that the sname and srealm in the response match +those in the request (or are otherwise expected values), and that the host +address field is also correct. It then stores the ticket, session key, start +and expiration times, and other information for later use. The +key-expiration field from the encrypted part of the response may be checked +to notify the user of impending key expiration (the client program could +then suggest remedial action, such as a password change). See section A.3 +for pseudocode. + +Proper decryption of the KRB_AS_REP message is not sufficient to verify the +identity of the user; the user and an attacker could cooperate to generate a +KRB_AS_REP format message which decrypts properly but is not from the proper +KDC. If the host wishes to verify the identity of the user, it must require +the user to present application credentials which can be verified using a +securely-stored secret key for the host. If those credentials can be +verified, then the identity of the user can be assured. + +3.1.6. Receipt of KRB_ERROR message + +If the reply message type is KRB_ERROR, then the client interprets it as an +error and performs whatever application-specific tasks are necessary to +recover. + +3.2. The Client/Server Authentication Exchange + + Summary +Message direction Message type Section +Client to Application server KRB_AP_REQ 5.5.1 +[optional] Application server to client KRB_AP_REP or 5.5.2 + KRB_ERROR 5.9.1 + +The client/server authentication (CS) exchange is used by network +applications to authenticate the client to the server and vice versa. The +client must have already acquired credentials for the server using the AS or +TGS exchange. + +3.2.1. The KRB_AP_REQ message + +The KRB_AP_REQ contains authentication information which should be part of +the first message in an authenticated transaction. It contains a ticket, an +authenticator, and some additional bookkeeping information (see section +5.5.1 for the exact format). The ticket by itself is insufficient to +authenticate a client, since tickets are passed across the network in +cleartext[DS90], so the authenticator is used to prevent invalid replay of +tickets by proving to the server that the client knows the session key of +the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message is +referred to elsewhere as the 'authentication header.' + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.2.2. Generation of a KRB_AP_REQ message + +When a client wishes to initiate authentication to a server, it obtains +(either through a credentials cache, the AS exchange, or the TGS exchange) a +ticket and session key for the desired service. The client may re-use any +tickets it holds until they expire. To use a ticket the client constructs a +new Authenticator from the the system time, its name, and optionally an +application specific checksum, an initial sequence number to be used in +KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in +negotiations for a session key unique to this particular session. +Authenticators may not be re-used and will be rejected if replayed to a +server[LGDSR87]. If a sequence number is to be included, it should be +randomly chosen so that even after many messages have been exchanged it is +not likely to collide with other sequence numbers in use. + +The client may indicate a requirement of mutual authentication or the use of +a session-key based ticket by setting the appropriate flag(s) in the +ap-options field of the message. + +The Authenticator is encrypted in the session key and combined with the +ticket to form the KRB_AP_REQ message which is then sent to the end server +along with any additional application-specific information. See section A.9 +for pseudocode. + +3.2.3. Receipt of KRB_AP_REQ message + +Authentication is based on the server's current time of day (clocks must be +loosely synchronized), the authenticator, and the ticket. Several errors are +possible. If an error occurs, the server is expected to reply to the client +with a KRB_ERROR message. This message may be encapsulated in the +application protocol if its 'raw' form is not acceptable to the protocol. +The format of error messages is described in section 5.9.1. + +The algorithm for verifying authentication information is as follows. If the +message type is not KRB_AP_REQ, the server returns the KRB_AP_ERR_MSG_TYPE +error. If the key version indicated by the Ticket in the KRB_AP_REQ is not +one the server can use (e.g., it indicates an old key, and the server no +longer possesses a copy of the old key), the KRB_AP_ERR_BADKEYVER error is +returned. If the USE-SESSION-KEY flag is set in the ap-options field, it +indicates to the server that the ticket is encrypted in the session key from +the server's ticket-granting ticket rather than its secret key[10]. Since it +is possible for the server to be registered in multiple realms, with +different keys in each, the srealm field in the unencrypted portion of the +ticket in the KRB_AP_REQ is used to specify which secret key the server +should use to decrypt that ticket. The KRB_AP_ERR_NOKEY error code is +returned if the server doesn't have the proper key to decipher the ticket. + +The ticket is decrypted using the version of the server's key specified by +the ticket. If the decryption routines detect a modification of the ticket +(each encryption system must provide safeguards to detect modified +ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned +(chances are good that different keys were used to encrypt and decrypt). + +The authenticator is decrypted using the session key extracted from the +decrypted ticket. If decryption shows it to have been modified, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the client +from the ticket are compared against the same fields in the authenticator. +If they don't match, the KRB_AP_ERR_BADMATCH error is returned (they might + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +not match, for example, if the wrong session key was used to encrypt the +authenticator). The addresses in the ticket (if any) are then searched for +an address matching the operating-system reported address of the client. If +no match is found or the server insists on ticket addresses but none are +present in the ticket, the KRB_AP_ERR_BADADDR error is returned. + +If the local (server) time and the client time in the authenticator differ +by more than the allowable clock skew (e.g., 5 minutes), the KRB_AP_ERR_SKEW +error is returned. If the server name, along with the client name, time and +microsecond fields from the Authenticator match any recently-seen such +tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The server must +remember any authenticator presented within the allowable clock skew, so +that a replay attempt is guaranteed to fail. If a server loses track of any +authenticator presented within the allowable clock skew, it must reject all +requests until the clock skew interval has passed. This assures that any +lost or re-played authenticators will fall outside the allowable clock skew +and can no longer be successfully replayed (If this is not done, an attacker +could conceivably record the ticket and authenticator sent over the network +to a server, then disable the client's host, pose as the disabled host, and +replay the ticket and authenticator to subvert the authentication.). If a +sequence number is provided in the authenticator, the server saves it for +later use in processing KRB_SAFE and/or KRB_PRIV messages. If a subkey is +present, the server either saves it for later use or uses it to help +generate its own choice for a subkey to be returned in a KRB_AP_REP message. + +The server computes the age of the ticket: local (server) time minus the +start time inside the Ticket. If the start time is later than the current +time by more than the allowable clock skew or if the INVALID flag is set in +the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the +current time is later than end time by more than the allowable clock skew, +the KRB_AP_ERR_TKT_EXPIRED error is returned. + +If all these checks succeed without an error, the server is assured that the +client possesses the credentials of the principal named in the ticket and +thus, the client has been authenticated to the server. See section A.10 for +pseudocode. + +Passing these checks provides only authentication of the named principal; it +does not imply authorization to use the named service. Applications must +make a separate authorization decisions based upon the authenticated name of +the user, the requested operation, local acces control information such as +that contained in a .k5login or .k5users file, and possibly a separate +distributed authorization service. + +3.2.4. Generation of a KRB_AP_REP message + +Typically, a client's request will include both the authentication +information and its initial request in the same message, and the server need +not explicitly reply to the KRB_AP_REQ. However, if mutual authentication +(not only authenticating the client to the server, but also the server to +the client) is being performed, the KRB_AP_REQ message will have +MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message is +required in response. As with the error message, this message may be +encapsulated in the application protocol if its "raw" form is not acceptable +to the application's protocol. The timestamp and microsecond field used in +the reply must be the client's timestamp and microsecond field (as provided +in the authenticator)[12]. If a sequence number is to be included, it should +be randomly chosen as described above for the authenticator. A subkey may be + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +included if the server desires to negotiate a different subkey. The +KRB_AP_REP message is encrypted in the session key extracted from the +ticket. See section A.11 for pseudocode. + +3.2.5. Receipt of KRB_AP_REP message + +If a KRB_AP_REP message is returned, the client uses the session key from +the credentials obtained for the server[13] to decrypt the message, and +verifies that the timestamp and microsecond fields match those in the +Authenticator it sent to the server. If they match, then the client is +assured that the server is genuine. The sequence number and subkey (if +present) are retained for later use. See section A.12 for pseudocode. + +3.2.6. Using the encryption key + +After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and server +share an encryption key which can be used by the application. The 'true +session key' to be used for KRB_PRIV, KRB_SAFE, or other +application-specific uses may be chosen by the application based on the +subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, +the use of this session key will be implicit in the protocol; in others the +method of use must be chosen from several alternatives. We leave the +protocol negotiations of how to use the key (e.g. selecting an encryption or +checksum type) to the application programmer; the Kerberos protocol does not +constrain the implementation options, but an example of how this might be +done follows. + +One way that an application may choose to negotiate a key to be used for +subequent integrity and privacy protection is for the client to propose a +key in the subkey field of the authenticator. The server can then choose a +key using the proposed key from the client as input, returning the new +subkey in the subkey field of the application reply. This key could then be +used for subsequent communication. To make this example more concrete, if +the encryption method in use required a 56 bit key, and for whatever reason, +one of the parties was prevented from using a key with more than 40 unknown +bits, this method would allow the the party which is prevented from using +more than 40 bits to either propose (if the client) an initial key with a +known quantity for 16 of those bits, or to mask 16 of the bits (if the +server) with the known quantity. The application implementor is warned, +however, that this is only an example, and that an analysis of the +particular crytosystem to be used, and the reasons for limiting the key +length, must be made before deciding whether it is acceptable to mask bits +of the key. + +With both the one-way and mutual authentication exchanges, the peers should +take care not to send sensitive information to each other without proper +assurances. In particular, applications that require privacy or integrity +should use the KRB_AP_REP response from the server to client to assure both +client and server of their peer's identity. If an application protocol +requires privacy of its messages, it can use the KRB_PRIV message (section +3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.3. The Ticket-Granting Service (TGS) Exchange + + Summary + Message direction Message type Section + 1. Client to Kerberos KRB_TGS_REQ 5.4.1 + 2. Kerberos to client KRB_TGS_REP or 5.4.2 + KRB_ERROR 5.9.1 + +The TGS exchange between a client and the Kerberos Ticket-Granting Server is +initiated by a client when it wishes to obtain authentication credentials +for a given server (which might be registered in a remote realm), when it +wishes to renew or validate an existing ticket, or when it wishes to obtain +a proxy ticket. In the first case, the client must already have acquired a +ticket for the Ticket-Granting Service using the AS exchange (the +ticket-granting ticket is usually obtained when a client initially +authenticates to the system, such as when a user logs in). The message +format for the TGS exchange is almost identical to that for the AS exchange. +The primary difference is that encryption and decryption in the TGS exchange +does not take place under the client's key. Instead, the session key from +the ticket-granting ticket or renewable ticket, or sub-session key from an +Authenticator is used. As is the case for all application servers, expired +tickets are not accepted by the TGS, so once a renewable or ticket-granting +ticket expires, the client must use a separate exchange to obtain valid +tickets. + +The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the +client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or +KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the +client plus a request for credentials. The authentication information +consists of the authentication header (KRB_AP_REQ) which includes the +client's previously obtained ticket-granting, renewable, or invalid ticket. +In the ticket-granting ticket and proxy cases, the request may include one +or more of: a list of network addresses, a collection of typed authorization +data to be sealed in the ticket for authorization use by the application +server, or additional tickets (the use of which are described later). The +TGS reply (KRB_TGS_REP) contains the requested credentials, encrypted in the +session key from the ticket-granting ticket or renewable ticket, or if +present, in the sub-session key from the Authenticator (part of the +authentication header). The KRB_ERROR message contains an error code and +text explaining what went wrong. The KRB_ERROR message is not encrypted. The +KRB_TGS_REP message contains information which can be used to detect +replays, and to associate it with the message to which it replies. The +KRB_ERROR message also contains information which can be used to associate +it with the message to which it replies, but the lack of encryption in the +KRB_ERROR message precludes the ability to detect replays or fabrications of +such messages. + +3.3.1. Generation of KRB_TGS_REQ message + +Before sending a request to the ticket-granting service, the client must +determine in which realm the application server is registered[15]. If the +client does not already possess a ticket-granting ticket for the appropriate +realm, then one must be obtained. This is first attempted by requesting a +ticket-granting ticket for the destination realm from a Kerberos server for +which the client does posess a ticket-granting ticket (using the KRB_TGS_REQ +message recursively). The Kerberos server may return a TGT for the desired +realm in which case one can proceed. Alternatively, the Kerberos server may +return a TGT for a realm which is 'closer' to the desired realm (further + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +along the standard hierarchical path), in which case this step must be +repeated with a Kerberos server in the realm specified in the returned TGT. +If neither are returned, then the request must be retried with a Kerberos +server for a realm higher in the hierarchy. This request will itself require +a ticket-granting ticket for the higher realm which must be obtained by +recursively applying these directions. + +Once the client obtains a ticket-granting ticket for the appropriate realm, +it determines which Kerberos servers serve that realm, and contacts one. The +list might be obtained through a configuration file or network service or it +may be generated from the name of the realm; as long as the secret keys +exchanged by realms are kept secret, only denial of service results from +using a false Kerberos server. + +As in the AS exchange, the client may specify a number of options in the +KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing +an authentication header as an element of the padata field, and including +the same fields as used in the KRB_AS_REQ message along with several +optional fields: the enc-authorization-data field for application server use +and additional tickets required by some options. + +In preparing the authentication header, the client can select a sub-session +key under which the response from the Kerberos server will be encrypted[16]. +If the sub-session key is not specified, the session key from the +ticket-granting ticket will be used. If the enc-authorization-data is +present, it must be encrypted in the sub-session key, if present, from the +authenticator portion of the authentication header, or if not present, using +the session key from the ticket-granting ticket. + +Once prepared, the message is sent to a Kerberos server for the destination +realm. See section A.5 for pseudocode. + +3.3.2. Receipt of KRB_TGS_REQ message + +The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ +message, but there are many additional checks to be performed. First, the +Kerberos server must determine which server the accompanying ticket is for +and it must select the appropriate key to decrypt it. For a normal +KRB_TGS_REQ message, it will be for the ticket granting service, and the +TGS's key will be used. If the TGT was issued by another realm, then the +appropriate inter-realm key must be used. If the accompanying ticket is not +a ticket granting ticket for the current realm, but is for an application +server in the current realm, the RENEW, VALIDATE, or PROXY options are +specified in the request, and the server for which a ticket is requested is +the server named in the accompanying ticket, then the KDC will decrypt the +ticket in the authentication header using the key of the server for which it +was issued. If no ticket can be found in the padata field, the +KDC_ERR_PADATA_TYPE_NOSUPP error is returned. + +Once the accompanying ticket has been decrypted, the user-supplied checksum +in the Authenticator must be verified against the contents of the request, +and the message rejected if the checksums do not match (with an error code +of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not +collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the +checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is +returned. If the authorization-data are present, they are decrypted using +the sub-session key from the Authenticator. + +If any of the decryptions indicate failed integrity checks, the +KRB_AP_ERR_BAD_INTEGRITY error is returned. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.3.3. Generation of KRB_TGS_REP message + +The KRB_TGS_REP message shares its format with the KRB_AS_REP (KRB_KDC_REP), +but with its type field set to KRB_TGS_REP. The detailed specification is in +section 5.4.2. + +The response will include a ticket for the requested server. The Kerberos +database is queried to retrieve the record for the requested server +(including the key with which the ticket will be encrypted). If the request +is for a ticket granting ticket for a remote realm, and if no key is shared +with the requested realm, then the Kerberos server will select the realm +"closest" to the requested realm with which it does share a key, and use +that realm instead. This is the only case where the response from the KDC +will be for a different server than that requested by the client. + +By default, the address field, the client's name and realm, the list of +transited realms, the time of initial authentication, the expiration time, +and the authorization data of the newly-issued ticket will be copied from +the ticket-granting ticket (TGT) or renewable ticket. If the transited field +needs to be updated, but the transited type is not supported, the +KDC_ERR_TRTYPE_NOSUPP error is returned. + +If the request specifies an endtime, then the endtime of the new ticket is +set to the minimum of (a) that request, (b) the endtime from the TGT, and +(c) the starttime of the TGT plus the minimum of the maximum life for the +application server and the maximum life for the local realm (the maximum +life for the requesting principal was already applied when the TGT was +issued). If the new ticket is to be a renewal, then the endtime above is +replaced by the minimum of (a) the value of the renew_till field of the +ticket and (b) the starttime for the new ticket plus the life +(endtime-starttime) of the old ticket. + +If the FORWARDED option has been requested, then the resulting ticket will +contain the addresses specified by the client. This option will only be +honored if the FORWARDABLE flag is set in the TGT. The PROXY option is +similar; the resulting ticket will contain the addresses specified by the +client. It will be honored only if the PROXIABLE flag in the TGT is set. The +PROXY option will not be honored on requests for additional ticket-granting +tickets. + +If the requested start time is absent, indicates a time in the past, or is +within the window of acceptable clock skew for the KDC and the POSTDATE +option has not been specified, then the start time of the ticket is set to +the authentication server's current time. If it indicates a time in the +future beyond the acceptable clock skew, but the POSTDATED option has not +been specified or the MAY-POSTDATE flag is not set in the TGT, then the +error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the ticket-granting +ticket has the MAY-POSTDATE flag set, then the resulting ticket will be +postdated and the requested starttime is checked against the policy of the +local realm. If acceptable, the ticket's start time is set as requested, and +the INVALID flag is set. The postdated ticket must be validated before use +by presenting it to the KDC after the starttime has been reached. However, +in no case may the starttime, endtime, or renew-till time of a newly-issued +postdated ticket extend beyond the renew-till time of the ticket-granting +ticket. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +If the ENC-TKT-IN-SKEY option has been specified and an additional ticket +has been included in the request, the KDC will decrypt the additional ticket +using the key for the server to which the additional ticket was issued and +verify that it is a ticket-granting ticket. If the name of the requested +server is missing from the request, the name of the client in the additional +ticket will be used. Otherwise the name of the requested server will be +compared to the name of the client in the additional ticket and if +different, the request will be rejected. If the request succeeds, the +session key from the additional ticket will be used to encrypt the new +ticket that is issued instead of using the key of the server for which the +new ticket will be used[17]. + +If the name of the server in the ticket that is presented to the KDC as part +of the authentication header is not that of the ticket-granting server +itself, the server is registered in the realm of the KDC, and the RENEW +option is requested, then the KDC will verify that the RENEWABLE flag is set +in the ticket, that the INVALID flag is not set in the ticket, and that the +renew_till time is still in the future. If the VALIDATE option is rqeuested, +the KDC will check that the starttime has passed and the INVALID flag is +set. If the PROXY option is requested, then the KDC will check that the +PROXIABLE flag is set in the ticket. If the tests succeed, and the ticket +passes the hotlist check described in the next paragraph, the KDC will issue +the appropriate new ticket. + +3.3.3.1. Checking for revoked tickets + +Whenever a request is made to the ticket-granting server, the presented +ticket(s) is(are) checked against a hot-list of tickets which have been +canceled. This hot-list might be implemented by storing a range of issue +timestamps for 'suspect tickets'; if a presented ticket had an authtime in +that range, it would be rejected. In this way, a stolen ticket-granting +ticket or renewable ticket cannot be used to gain additional tickets +(renewals or otherwise) once the theft has been reported. Any normal ticket +obtained before it was reported stolen will still be valid (because they +require no interaction with the KDC), but only until their normal expiration +time. + +The ciphertext part of the response in the KRB_TGS_REP message is encrypted +in the sub-session key from the Authenticator, if present, or the session +key key from the ticket-granting ticket. It is not encrypted using the +client's secret key. Furthermore, the client's key's expiration date and the +key version number fields are left out since these values are stored along +with the client's database record, and that record is not needed to satisfy +a request based on a ticket-granting ticket. See section A.6 for pseudocode. + +3.3.3.2. Encoding the transited field + +If the identity of the server in the TGT that is presented to the KDC as +part of the authentication header is that of the ticket-granting service, +but the TGT was issued from another realm, the KDC will look up the +inter-realm key shared with that realm and use that key to decrypt the +ticket. If the ticket is valid, then the KDC will honor the request, subject +to the constraints outlined above in the section describing the AS exchange. +The realm part of the client's identity will be taken from the +ticket-granting ticket. The name of the realm that issued the +ticket-granting ticket will be added to the transited field of the ticket to +be issued. This is accomplished by reading the transited field from the +ticket-granting ticket (which is treated as an unordered set of realm + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +names), adding the new realm to the set, then constructing and writing out +its encoded (shorthand) form (this may involve a rearrangement of the +existing encoding). + +Note that the ticket-granting service does not add the name of its own +realm. Instead, its responsibility is to add the name of the previous realm. +This prevents a malicious Kerberos server from intentionally leaving out its +own name (it could, however, omit other realms' names). + +The names of neither the local realm nor the principal's realm are to be +included in the transited field. They appear elsewhere in the ticket and +both are known to have taken part in authenticating the principal. Since the +endpoints are not included, both local and single-hop inter-realm +authentication result in a transited field that is empty. + +Because the name of each realm transited is added to this field, it might +potentially be very long. To decrease the length of this field, its contents +are encoded. The initially supported encoding is optimized for the normal +case of inter-realm communication: a hierarchical arrangement of realms +using either domain or X.500 style realm names. This encoding (called +DOMAIN-X500-COMPRESS) is now described. + +Realm names in the transited field are separated by a ",". The ",", "\", +trailing "."s, and leading spaces (" ") are special characters, and if they +are part of a realm name, they must be quoted in the transited field by +preced- ing them with a "\". + +A realm name ending with a "." is interpreted as being prepended to the +previous realm. For example, we can encode traversal of EDU, MIT.EDU, +ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: + + "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". + +Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that they +would not be included in this field, and we would have: + + "EDU,MIT.,WASHINGTON.EDU" + +A realm name beginning with a "/" is interpreted as being appended to the +previous realm[18]. If it is to stand by itself, then it should be preceded +by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, +/COM/HP, /COM, and /COM/DEC as: + + "/COM,/HP,/APOLLO, /COM/DEC". + +Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they +they would not be included in this field, and we would have: + + "/COM,/HP" + +A null subfield preceding or following a "," indicates that all realms +between the previous realm and the next realm have been traversed[19]. Thus, +"," means that all realms along the path between the client and the server +have been traversed. ",EDU, /COM," means that that all realms from the +client's realm up to EDU (in a domain style hierarchy) have been traversed, +and that everything from /COM down to the server's realm in an X.500 style +has also been traversed. This could occur if the EDU realm in one hierarchy +shares an inter-realm key directly with the /COM realm in another hierarchy. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +3.3.4. Receipt of KRB_TGS_REP message + +When the KRB_TGS_REP is received by the client, it is processed in the same +manner as the KRB_AS_REP processing described above. The primary difference +is that the ciphertext part of the response must be decrypted using the +session key from the ticket-granting ticket rather than the client's secret +key. See section A.7 for pseudocode. + +3.4. The KRB_SAFE Exchange + +The KRB_SAFE message may be used by clients requiring the ability to detect +modifications of messages they exchange. It achieves this by including a +keyed collision-proof checksum of the user data and some control +information. The checksum is keyed with an encryption key (usually the last +key negotiated via subkeys, or the session key if no negotiation has +occured). + +3.4.1. Generation of a KRB_SAFE message + +When an application wishes to send a KRB_SAFE message, it collects its data +and the appropriate control information and computes a checksum over them. +The checksum algorithm should be a keyed one-way hash function (such as the +RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES MAC), +generated using the sub-session key if present, or the session key. +Different algorithms may be selected by changing the checksum type in the +message. Unkeyed or non-collision-proof checksums are not suitable for this +use. + +The control information for the KRB_SAFE message includes both a timestamp +and a sequence number. The designer of an application using the KRB_SAFE +message must choose at least one of the two mechanisms. This choice should +be based on the needs of the application protocol. + +Sequence numbers are useful when all messages sent will be received by one's +peer. Connection state is presently required to maintain the session key, so +maintaining the next sequence number should not present an additional +problem. + +If the application protocol is expected to tolerate lost messages without +them being resent, the use of the timestamp is the appropriate replay +detection mechanism. Using timestamps is also the appropriate mechanism for +multi-cast protocols where all of one's peers share a common sub-session +key, but some messages will be sent to a subset of one's peers. + +After computing the checksum, the client then transmits the information and +checksum to the recipient in the message format specified in section 5.6.1. + +3.4.2. Receipt of KRB_SAFE message + +When an application receives a KRB_SAFE message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + +The message is first checked by verifying that the protocol version and type +fields match the current version and KRB_SAFE, respectively. A mismatch +generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application verifies that the checksum used is a collision-proof keyed +checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. If +the sender's address was included in the control information, the recipient + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +verifies that the operating system's report of the sender's address matches +the sender's address in the message, and (if a recipient address is +specified or the recipient requires an address) that one of the recipient's +addresses appears as the recipient's address in the message. A failed match +for either case generates a KRB_AP_ERR_BADADDR error. Then the timestamp and +usec and/or the sequence number fields are checked. If timestamp and usec +are expected and not present, or they are present but not current, the +KRB_AP_ERR_SKEW error is generated. If the server name, along with the +client name, time and microsecond fields from the Authenticator match any +recently-seen (sent or received[20] ) such tuples, the KRB_AP_ERR_REPEAT +error is generated. If an incorrect sequence number is included, or a +sequence number is expected but not present, the KRB_AP_ERR_BADORDER error +is generated. If neither a time-stamp and usec or a sequence number is +present, a KRB_AP_ERR_MODIFIED error is generated. Finally, the checksum is +computed over the data and control information, and if it doesn't match the +received checksum, a KRB_AP_ERR_MODIFIED error is generated. + +If all the checks succeed, the application is assured that the message was +generated by its peer and was not modi- fied in transit. + +3.5. The KRB_PRIV Exchange + +The KRB_PRIV message may be used by clients requiring confidentiality and +the ability to detect modifications of exchanged messages. It achieves this +by encrypting the messages and adding control information. + +3.5.1. Generation of a KRB_PRIV message + +When an application wishes to send a KRB_PRIV message, it collects its data +and the appropriate control information (specified in section 5.7.1) and +encrypts them under an encryption key (usually the last key negotiated via +subkeys, or the session key if no negotiation has occured). As part of the +control information, the client must choose to use either a timestamp or a +sequence number (or both); see the discussion in section 3.4.1 for +guidelines on which to use. After the user data and control information are +encrypted, the client transmits the ciphertext and some 'envelope' +information to the recipient. + +3.5.2. Receipt of KRB_PRIV message + +When an application receives a KRB_PRIV message, it verifies it as follows. +If any error occurs, an error code is reported for use by the application. + +The message is first checked by verifying that the protocol version and type +fields match the current version and KRB_PRIV, respectively. A mismatch +generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The +application then decrypts the ciphertext and processes the resultant +plaintext. If decryption shows the data to have been modified, a +KRB_AP_ERR_BAD_INTEGRITY error is generated. If the sender's address was +included in the control information, the recipient verifies that the +operating system's report of the sender's address matches the sender's +address in the message, and (if a recipient address is specified or the +recipient requires an address) that one of the recipient's addresses appears +as the recipient's address in the message. A failed match for either case +generates a KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the +sequence number fields are checked. If timestamp and usec are expected and +not present, or they are present but not current, the KRB_AP_ERR_SKEW error +is generated. If the server name, along with the client name, time and + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +microsecond fields from the Authenticator match any recently-seen such +tuples, the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence +number is included, or a sequence number is expected but not present, the +KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or +a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. + +If all the checks succeed, the application can assume the message was +generated by its peer, and was securely transmitted (without intruders able +to see the unencrypted contents). + +3.6. The KRB_CRED Exchange + +The KRB_CRED message may be used by clients requiring the ability to send +Kerberos credentials from one host to another. It achieves this by sending +the tickets together with encrypted data containing the session keys and +other information associated with the tickets. + +3.6.1. Generation of a KRB_CRED message + +When an application wishes to send a KRB_CRED message it first (using the +KRB_TGS exchange) obtains credentials to be sent to the remote host. It then +constructs a KRB_CRED message using the ticket or tickets so obtained, +placing the session key needed to use each ticket in the key field of the +corresponding KrbCredInfo sequence of the encrypted part of the the KRB_CRED +message. + +Other information associated with each ticket and obtained during the +KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence in +the encrypted part of the KRB_CRED message. The current time and, if +specifically required by the application the nonce, s-address, and r-address +fields, are placed in the encrypted part of the KRB_CRED message which is +then encrypted under an encryption key previosuly exchanged in the KRB_AP +exchange (usually the last key negotiated via subkeys, or the session key if +no negotiation has occured). + +3.6.2. Receipt of KRB_CRED message + +When an application receives a KRB_CRED message, it verifies it. If any +error occurs, an error code is reported for use by the application. The +message is verified by checking that the protocol version and type fields +match the current version and KRB_CRED, respectively. A mismatch generates a +KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then +decrypts the ciphertext and processes the resultant plaintext. If decryption +shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is +generated. + +If present or required, the recipient verifies that the operating system's +report of the sender's address matches the sender's address in the message, +and that one of the recipient's addresses appears as the recipient's address +in the message. A failed match for either case generates a +KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce field +if required) are checked next. If the timestamp and usec are not present, or +they are present but not current, the KRB_AP_ERR_SKEW error is generated. + +If all the checks succeed, the application stores each of the new tickets in +its ticket cache together with the session key and other information in the +corresponding KrbCredInfo sequence from the encrypted part of the KRB_CRED +message. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +4. The Kerberos Database + +The Kerberos server must have access to a database contain- ing the +principal identifiers and secret keys of principals to be authenticated[21]. + +4.1. Database contents + +A database entry should contain at least the following fields: + +Field Value + +name Principal's identifier +key Principal's secret key +p_kvno Principal's key version +max_life Maximum lifetime for Tickets +max_renewable_life Maximum total lifetime for renewable Tickets + +The name field is an encoding of the principal's identifier. The key field +contains an encryption key. This key is the principal's secret key. (The key +can be encrypted before storage under a Kerberos "master key" to protect it +in case the database is compromised but the master key is not. In that case, +an extra field must be added to indicate the master key version used, see +below.) The p_kvno field is the key version number of the principal's secret +key. The max_life field contains the maximum allowable lifetime (endtime - +starttime) for any Ticket issued for this principal. The max_renewable_life +field contains the maximum allowable total lifetime for any renewable Ticket +issued for this principal. (See section 3.1 for a description of how these +lifetimes are used in determining the lifetime of a given Ticket.) + +A server may provide KDC service to several realms, as long as the database +representation provides a mechanism to distinguish between principal records +with identifiers which differ only in the realm name. + +When an application server's key changes, if the change is routine (i.e. not +the result of disclosure of the old key), the old key should be retained by +the server until all tickets that had been issued using that key have +expired. Because of this, it is possible for several keys to be active for a +single principal. Ciphertext encrypted in a principal's key is always tagged +with the version of the key that was used for encryption, to help the +recipient find the proper key for decryption. + +When more than one key is active for a particular principal, the principal +will have more than one record in the Kerberos database. The keys and key +version numbers will differ between the records (the rest of the fields may +or may not be the same). Whenever Kerberos issues a ticket, or responds to a +request for initial authentication, the most recent key (known by the +Kerberos server) will be used for encryption. This is the key with the +highest key version number. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +4.2. Additional fields + +Project Athena's KDC implementation uses additional fields in its database: + +Field Value + +K_kvno Kerberos' key version +expiration Expiration date for entry +attributes Bit field of attributes +mod_date Timestamp of last modification +mod_name Modifying principal's identifier + +The K_kvno field indicates the key version of the Kerberos master key under +which the principal's secret key is encrypted. + +After an entry's expiration date has passed, the KDC will return an error to +any client attempting to gain tickets as or for the principal. (A database +may want to maintain two expiration dates: one for the principal, and one +for the principal's current key. This allows password aging to work +independently of the principal's expiration date. However, due to the +limited space in the responses, the KDC must combine the key expiration and +principal expiration date into a single value called 'key_exp', which is +used as a hint to the user to take administrative action.) + +The attributes field is a bitfield used to govern the operations involving +the principal. This field might be useful in conjunction with user +registration procedures, for site-specific policy implementations (Project +Athena currently uses it for their user registration process controlled by +the system-wide database service, Moira [LGDSR87]), to identify whether a +principal can play the role of a client or server or both, to note whether a +server is appropriate trusted to recieve credentials delegated by a client, +or to identify the 'string to key' conversion algorithm used for a +principal's key[22]. Other bits are used to indicate that certain ticket +options should not be allowed in tickets encrypted under a principal's key +(one bit each): Disallow issuing postdated tickets, disallow issuing +forwardable tickets, disallow issuing tickets based on TGT authentication, +disallow issuing renewable tickets, disallow issuing proxiable tickets, and +disallow issuing tickets for which the principal is the server. + +The mod_date field contains the time of last modification of the entry, and +the mod_name field contains the name of the principal which last modified +the entry. + +4.3. Frequently Changing Fields + +Some KDC implementations may wish to maintain the last time that a request +was made by a particular principal. Information that might be maintained +includes the time of the last request, the time of the last request for a +ticket-granting ticket, the time of the last use of a ticket-granting +ticket, or other times. This information can then be returned to the user in +the last-req field (see section 5.2). + +Other frequently changing information that can be maintained is the latest +expiration time for any tickets that have been issued using each key. This +field would be used to indicate how long old keys must remain valid to allow +the continued use of outstanding tickets. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +4.4. Site Constants + +The KDC implementation should have the following configurable constants or +options, to allow an administrator to make and enforce policy decisions: + + * The minimum supported lifetime (used to determine whether the + KDC_ERR_NEVER_VALID error should be returned). This constant should + reflect reasonable expectations of round-trip time to the KDC, + encryption/decryption time, and processing time by the client and + target server, and it should allow for a minimum 'useful' lifetime. + * The maximum allowable total (renewable) lifetime of a ticket + (renew_till - starttime). + * The maximum allowable lifetime of a ticket (endtime - starttime). + * Whether to allow the issue of tickets with empty address fields + (including the ability to specify that such tickets may only be issued + if the request specifies some authorization_data). + * Whether proxiable, forwardable, renewable or post-datable tickets are + to be issued. + +5. Message Specifications + +The following sections describe the exact contents and encoding of protocol +messages and objects. The ASN.1 base definitions are presented in the first +subsection. The remaining subsections specify the protocol objects (tickets +and authenticators) and messages. Specification of encryption and checksum +techniques, and the fields related to them, appear in section 6. + +Optional field in ASN.1 sequences + +For optional integer value and date fields in ASN.1 sequences where a +default value has been specified, certain default values will not be allowed +in the encoding because these values will always be represented through +defaulting by the absence of the optional field. For example, one will not +send a microsecond zero value because one must make sure that there is only +one way to encode this value. + +Additional fields in ASN.1 sequences + +Implementations receiving Kerberos messages with additional fields present +in ASN.1 sequences should carry the those fields through, unmodified, when +the message is forwarded. Implementations should not drop such fields if the +sequence is reencoded. + +5.1. ASN.1 Distinguished Encoding Representation + +All uses of ASN.1 in Kerberos shall use the Distinguished Encoding +Representation of the data elements as described in the X.509 specification, +section 8.7 [X509-88]. + +5.3. ASN.1 Base Definitions + +The following ASN.1 base definitions are used in the rest of this section. +Note that since the underscore character (_) is not permitted in ASN.1 +names, the hyphen (-) is used in its place for the purposes of ASN.1 names. + +Realm ::= GeneralString +PrincipalName ::= SEQUENCE { + name-type[0] INTEGER, + name-string[1] SEQUENCE OF GeneralString +} + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Kerberos realms are encoded as GeneralStrings. Realms shall not contain a +character with the code 0 (the ASCII NUL). Most realms will usually consist +of several components separated by periods (.), in the style of Internet +Domain Names, or separated by slashes (/) in the style of X.500 names. +Acceptable forms for realm names are specified in section 7. A PrincipalName +is a typed sequence of components consisting of the following sub-fields: + +name-type + This field specifies the type of name that follows. Pre-defined values + for this field are specified in section 7.2. The name-type should be + treated as a hint. Ignoring the name type, no two names can be the same + (i.e. at least one of the components, or the realm, must be different). + This constraint may be eliminated in the future. +name-string + This field encodes a sequence of components that form a name, each + component encoded as a GeneralString. Taken together, a PrincipalName + and a Realm form a principal identifier. Most PrincipalNames will have + only a few components (typically one or two). + +KerberosTime ::= GeneralizedTime + -- Specifying UTC time zone (Z) + +The timestamps used in Kerberos are encoded as GeneralizedTimes. An encoding +shall specify the UTC time zone (Z) and shall not include any fractional +portions of the seconds. It further shall not include any separators. +Example: The only valid format for UTC time 6 minutes, 27 seconds after 9 pm +on 6 November 1985 is 19851106210627Z. + +HostAddress ::= SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING +} + +HostAddresses ::= SEQUENCE OF HostAddress + +The host adddress encodings consists of two fields: + +addr-type + This field specifies the type of address that follows. Pre-defined + values for this field are specified in section 8.1. +address + This field encodes a single address of type addr-type. + +The two forms differ slightly. HostAddress contains exactly one address; +HostAddresses contains a sequence of possibly many addresses. + +AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type[0] INTEGER, + ad-data[1] OCTET STRING +} + +ad-data + This field contains authorization data to be interpreted according to + the value of the corresponding ad-type field. +ad-type + This field specifies the format for the ad-data subfield. All negative + values are reserved for local use. Non-negative values are reserved for + registered use. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Each sequence of type and data is refered to as an authorization element. +Elements may be application specific, however, there is a common set of +recursive elements that should be understood by all implementations. These +elements contain other elements embedded within them, and the interpretation +of the encapsulating element determines which of the embedded elements must +be interpreted, and which may be ignored. Definitions for these common +elements may be found in Appendix B. + +TicketExtensions ::= SEQUENCE OF SEQUENCE { + te-type[0] INTEGER, + te-data[1] OCTET STRING +} + +te-data + This field contains opaque data that must be caried with the ticket to + support extensions to the Kerberos protocol including but not limited + to some forms of inter-realm key exchange and plaintext authorization + data. See appendix C for some common uses of this field. +te-type + This field specifies the format for the te-data subfield. All negative + values are reserved for local use. Non-negative values are reserved for + registered use. + +APOptions ::= BIT STRING + -- reserved(0), + -- use-session-key(1), + -- mutual-required(2) + +TicketFlags ::= BIT STRING + -- reserved(0), + -- forwardable(1), + -- forwarded(2), + -- proxiable(3), + -- proxy(4), + -- may-postdate(5), + -- postdated(6), + -- invalid(7), + -- renewable(8), + -- initial(9), + -- pre-authent(10), + -- hw-authent(11), + -- transited-policy-checked(12), + -- ok-as-delegate(13) + +KDCOptions ::= BIT STRING + -- reserved(0), + -- forwardable(1), + -- forwarded(2), + -- proxiable(3), + -- proxy(4), + -- allow-postdate(5), + -- postdated(6), + -- unused7(7), + -- renewable(8), + -- unused9(9), + -- unused10(10), + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + -- unused11(11), + -- unused12(12), + -- unused13(13), + -- disable-transited-check(26), + -- renewable-ok(27), + -- enc-tkt-in-skey(28), + -- renew(30), + -- validate(31) + +ASN.1 Bit strings have a length and a value. When used in Kerberos for the +APOptions, TicketFlags, and KDCOptions, the length of the bit string on +generated values should be the smallest number of bits needed to include the +highest order bit that is set (1), but in no case less than 32 bits. The +ASN.1 representation of the bit strings uses unnamed bits, with the meaning +of the individual bits defined by the comments in the specification above. +Implementations should accept values of bit strings of any length and treat +the value of flags corresponding to bits beyond the end of the bit string as +if the bit were reset (0). Comparison of bit strings of different length +should treat the smaller string as if it were padded with zeros beyond the +high order bits to the length of the longer string[23]. + +LastReq ::= SEQUENCE OF SEQUENCE { + lr-type[0] INTEGER, + lr-value[1] KerberosTime +} + +lr-type + This field indicates how the following lr-value field is to be + interpreted. Negative values indicate that the information pertains + only to the responding server. Non-negative values pertain to all + servers for the realm. If the lr-type field is zero (0), then no + information is conveyed by the lr-value subfield. If the absolute value + of the lr-type field is one (1), then the lr-value subfield is the time + of last initial request for a TGT. If it is two (2), then the lr-value + subfield is the time of last initial request. If it is three (3), then + the lr-value subfield is the time of issue for the newest + ticket-granting ticket used. If it is four (4), then the lr-value + subfield is the time of the last renewal. If it is five (5), then the + lr-value subfield is the time of last request (of any type). If it is + (6), then the lr-value subfield is the time when the password will + expire. +lr-value + This field contains the time of the last request. the time must be + interpreted according to the contents of the accompanying lr-type + subfield. + +See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, +EncryptionKey, EncryptionType, and KeyType. + +5.3. Tickets and Authenticators + +This section describes the format and encryption parameters for tickets and +authenticators. When a ticket or authenticator is included in a protocol +message it is treated as an opaque object. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +5.3.1. Tickets + +A ticket is a record that helps a client authenticate to a service. A Ticket +contains the following information: + +Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno[0] INTEGER, + realm[1] Realm, + sname[2] PrincipalName, + enc-part[3] EncryptedData, + extensions[4] TicketExtensions OPTIONAL +} + +-- Encrypted part of ticket +EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL +} +-- encoded Transited field +TransitedEncoding ::= SEQUENCE { + tr-type[0] INTEGER, -- must be +registered + contents[1] OCTET STRING +} + +The encoding of EncTicketPart is encrypted in the key shared by Kerberos and +the end server (the server's secret key). See section 6 for the format of +the ciphertext. + +tkt-vno + This field specifies the version number for the ticket format. This + document describes version number 5. +realm + This field specifies the realm that issued a ticket. It also serves to + identify the realm part of the server's principal identifier. Since a + Kerberos server can only issue tickets for servers within its realm, + the two will always be identical. +sname + This field specifies all components of the name part of the server's + identity, including those parts that identify a specific instance of a + service. +enc-part + This field holds the encrypted encoding of the EncTicketPart sequence. +extensions + [*** This change is still subject to discussion. Several alternatives + for this - including none at all - will be distributed to the cat and + krb-protocol mailing lists before the Oslo IETF, and an alternative + will be selected and the spec modified by 7/14/99 ***] This optional + field contains a sequence of extentions that may be used to carry + information that must be carried with the ticket to support several + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + extensions, including but not limited to plaintext authorization data, + tokens for exchanging inter-realm keys, and other information that must + be associated with a ticket for use by the application server. See + Appendix C for definitions of some common extensions. + + Note that some older versions of Kerberos did not support this field. + Because this is an optional field it will not break older clients, but + older clients might strip this field from the ticket before sending it + to the application server. This limits the usefulness of this ticket + field to environments where the ticket will not be parsed and + reconstructed by these older Kerberos clients. + + If it is known that the client will strip this field from the ticket, + as an interim measure the KDC may append this field to the end of the + enc-part of the ticket and append a traler indicating the lenght of the + appended extensions field. (this paragraph is open for discussion, + including the form of the traler). +flags + This field indicates which of various options were used or requested + when the ticket was issued. It is a bit-field, where the selected + options are indicated by the bit being set (1), and the unselected + options and reserved fields being reset (0). Bit 0 is the most + significant bit. The encoding of the bits is specified in section 5.2. + The flags are described in more detail above in section 2. The meanings + of the flags are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 FORWARDABLE + The FORWARDABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. When set, this + flag tells the ticket-granting server + that it is OK to issue a new ticket- + granting ticket with a different network + address based on the presented ticket. + + 2 FORWARDED + When set, this flag indicates that the + ticket has either been forwarded or was + issued based on authentication involving + a forwarded ticket-granting ticket. + + 3 PROXIABLE + The PROXIABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. The PROXIABLE + flag has an interpretation identical to + that of the FORWARDABLE flag, except + that the PROXIABLE flag tells the + ticket-granting server that only non- + ticket-granting tickets may be issued + with different network addresses. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 4 PROXY + When set, this flag indicates that a + ticket is a proxy. + + 5 MAY-POSTDATE + The MAY-POSTDATE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. This flag tells + the ticket-granting server that a post- + dated ticket may be issued based on this + ticket-granting ticket. + + 6 POSTDATED + This flag indicates that this ticket has + been postdated. The end-service can + check the authtime field to see when the + original authentication occurred. + + 7 INVALID + This flag indicates that a ticket is + invalid, and it must be validated by the + KDC before use. Application servers + must reject tickets which have this flag + set. + + 8 RENEWABLE + The RENEWABLE flag is normally only + interpreted by the TGS, and can usually + be ignored by end servers (some particu- + larly careful servers may wish to disal- + low renewable tickets). A renewable + ticket can be used to obtain a replace- + ment ticket that expires at a later + date. + + 9 INITIAL + This flag indicates that this ticket was + issued using the AS protocol, and not + issued based on a ticket-granting + ticket. + + 10 PRE-AUTHENT + This flag indicates that during initial + authentication, the client was authenti- + cated by the KDC before a ticket was + issued. The strength of the pre- + authentication method is not indicated, + but is acceptable to the KDC. + + 11 HW-AUTHENT + This flag indicates that the protocol + employed for initial authentication + required the use of hardware expected to + be possessed solely by the named client. + The hardware authentication method is + selected by the KDC and the strength of + the method is not indicated. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 12 TRANSITED This flag indicates that the KDC for the + POLICY-CHECKED realm has checked the transited field + against a realm defined policy for + trusted certifiers. If this flag is + reset (0), then the application server + must check the transited field itself, + and if unable to do so it must reject + the authentication. If the flag is set + (1) then the application server may skip + its own validation of the transited + field, relying on the validation + performed by the KDC. At its option the + application server may still apply its + own validation based on a separate + policy for acceptance. + + 13 OK-AS-DELEGATE This flag indicates that the server (not + the client) specified in the ticket has + been determined by policy of the realm + to be a suitable recipient of + delegation. A client can use the + presence of this flag to help it make a + decision whether to delegate credentials + (either grant a proxy or a forwarded + ticket granting ticket) to this server. + The client is free to ignore the value + of this flag. When setting this flag, + an administrator should consider the + Security and placement of the server on + which the service will run, as well as + whether the service requires the use of + delegated credentials. + + 14 ANONYMOUS + This flag indicates that the principal + named in the ticket is a generic princi- + pal for the realm and does not identify + the individual using the ticket. The + purpose of the ticket is only to + securely distribute a session key, and + not to identify the user. Subsequent + requests using the same ticket and ses- + sion may be considered as originating + from the same user, but requests with + the same username but a different ticket + are likely to originate from different + users. + + 15-31 RESERVED + Reserved for future use. + +key + This field exists in the ticket and the KDC response and is used to + pass the session key from Kerberos to the application server and the + client. The field's encoding is described in section 6.2. +crealm + This field contains the name of the realm in which the client is + registered and in which initial authentication took place. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +cname + This field contains the name part of the client's principal identifier. +transited + This field lists the names of the Kerberos realms that took part in + authenticating the user to whom this ticket was issued. It does not + specify the order in which the realms were transited. See section + 3.3.3.2 for details on how this field encodes the traversed realms. + When the names of CA's are to be embedded inthe transited field (as + specified for some extentions to the protocol), the X.500 names of the + CA's should be mapped into items in the transited field using the + mapping defined by RFC2253. +authtime + This field indicates the time of initial authentication for the named + principal. It is the time of issue for the original ticket on which + this ticket is based. It is included in the ticket to provide + additional information to the end service, and to provide the necessary + information for implementation of a `hot list' service at the KDC. An + end service that is particularly paranoid could refuse to accept + tickets for which the initial authentication occurred "too far" in the + past. This field is also returned as part of the response from the KDC. + When returned as part of the response to initial authentication + (KRB_AS_REP), this is the current time on the Ker- beros server[24]. +starttime + This field in the ticket specifies the time after which the ticket is + valid. Together with endtime, this field specifies the life of the + ticket. If it is absent from the ticket, its value should be treated as + that of the authtime field. +endtime + This field contains the time after which the ticket will not be honored + (its expiration time). Note that individual services may place their + own limits on the life of a ticket and may reject tickets which have + not yet expired. As such, this is really an upper bound on the + expiration time for the ticket. +renew-till + This field is only present in tickets that have the RENEWABLE flag set + in the flags field. It indicates the maximum endtime that may be + included in a renewal. It can be thought of as the absolute expiration + time for the ticket, including all renewals. +caddr + This field in a ticket contains zero (if omitted) or more (if present) + host addresses. These are the addresses from which the ticket can be + used. If there are no addresses, the ticket can be used from any + location. The decision by the KDC to issue or by the end server to + accept zero-address tickets is a policy decision and is left to the + Kerberos and end-service administrators; they may refuse to issue or + accept such tickets. The suggested and default policy, however, is that + such tickets will only be issued or accepted when additional + information that can be used to restrict the use of the ticket is + included in the authorization_data field. Such a ticket is a + capability. + + Network addresses are included in the ticket to make it harder for an + attacker to use stolen credentials. Because the session key is not sent + over the network in cleartext, credentials can't be stolen simply by + listening to the network; an attacker has to gain access to the session + key (perhaps through operating system security breaches or a careless + user's unattended session) to make use of stolen tickets. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + It is important to note that the network address from which a + connection is received cannot be reliably determined. Even if it could + be, an attacker who has compromised the client's workstation could use + the credentials from there. Including the network addresses only makes + it more difficult, not impossible, for an attacker to walk off with + stolen credentials and then use them from a "safe" location. +authorization-data + The authorization-data field is used to pass authorization data from + the principal on whose behalf a ticket was issued to the application + service. If no authorization data is included, this field will be left + out. Experience has shown that the name of this field is confusing, and + that a better name for this field would be restrictions. Unfortunately, + it is not possible to change the name of this field at this time. + + This field contains restrictions on any authority obtained on the basis + of authentication using the ticket. It is possible for any principal in + posession of credentials to add entries to the authorization data field + since these entries further restrict what can be done with the ticket. + Such additions can be made by specifying the additional entries when a + new ticket is obtained during the TGS exchange, or they may be added + during chained delegation using the authorization data field of the + authenticator. + + Because entries may be added to this field by the holder of + credentials, it is not allowable for the presence of an entry in the + authorization data field of a ticket to amplify the priveleges one + would obtain from using a ticket. + + The data in this field may be specific to the end service; the field + will contain the names of service specific objects, and the rights to + those objects. The format for this field is described in section 5.2. + Although Kerberos is not concerned with the format of the contents of + the sub-fields, it does carry type information (ad-type). + + By using the authorization_data field, a principal is able to issue a + proxy that is valid for a specific purpose. For example, a client + wishing to print a file can obtain a file server proxy to be passed to + the print server. By specifying the name of the file in the + authorization_data field, the file server knows that the print server + can only use the client's rights when accessing the particular file to + be printed. + + A separate service providing authorization or certifying group + membership may be built using the authorization-data field. In this + case, the entity granting authorization (not the authorized entity), + obtains a ticket in its own name (e.g. the ticket is issued in the name + of a privelege server), and this entity adds restrictions on its own + authority and delegates the restricted authority through a proxy to the + client. The client would then present this authorization credential to + the application server separately from the authentication exchange. + + Similarly, if one specifies the authorization-data field of a proxy and + leaves the host addresses blank, the resulting ticket and session key + can be treated as a capability. See [Neu93] for some suggested uses of + this field. + + The authorization-data field is optional and does not have to be + included in a ticket. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +5.3.2. Authenticators + +An authenticator is a record sent with a ticket to a server to certify the +client's knowledge of the encryption key in the ticket, to help the server +detect replays, and to help choose a "true session key" to use with the +particular session. The encoding is encrypted in the ticket's session key +shared by the client and the server: + +-- Unencrypted authenticator +Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL +} + +authenticator-vno + This field specifies the version number for the format of the + authenticator. This document specifies version 5. +crealm and cname + These fields are the same as those described for the ticket in section + 5.3.1. +cksum + This field contains a checksum of the the applica- tion data that + accompanies the KRB_AP_REQ. +cusec + This field contains the microsecond part of the client's timestamp. Its + value (before encryption) ranges from 0 to 999999. It often appears + along with ctime. The two fields are used together to specify a + reasonably accurate timestamp. +ctime + This field contains the current time on the client's host. +subkey + This field contains the client's choice for an encryption key which is + to be used to protect this specific application session. Unless an + application specifies otherwise, if this field is left out the session + key from the ticket will be used. +seq-number + This optional field includes the initial sequence number to be used by + the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to + detect replays (It may also be used by application specific messages). + When included in the authenticator this field specifies the initial + sequence number for messages from the client to the server. When + included in the AP-REP message, the initial sequence number is that for + messages from the server to the client. When used in KRB_PRIV or + KRB_SAFE messages, it is incremented by one after each message is sent. + Sequence numbers fall in the range of 0 through 2^32 - 1 and wrap to + zero following the value 2^32 - 1. + + For sequence numbers to adequately support the detection of replays + they should be non-repeating, even across connection boundaries. The + initial sequence number should be random and uniformly distributed + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + across the full space of possible sequence numbers, so that it cannot + be guessed by an attacker and so that it and the successive sequence + numbers do not repeat other sequences. +authorization-data + This field is the same as described for the ticket in section 5.3.1. It + is optional and will only appear when additional restrictions are to be + placed on the use of a ticket, beyond those carried in the ticket + itself. + +5.4. Specifications for the AS and TGS exchanges + +This section specifies the format of the messages used in the exchange +between the client and the Kerberos server. The format of possible error +messages appears in section 5.9.1. + +5.4.1. KRB_KDC_REQ definition + +The KRB_KDC_REQ message has no type of its own. Instead, its type is one of +KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an initial +ticket or an additional ticket. In either case, the message is sent from the +client to the Authentication Server to request credentials for a service. + +The message fields are: + +AS-REQ ::= [APPLICATION 10] KDC-REQ +TGS-REQ ::= [APPLICATION 12] KDC-REQ + +KDC-REQ ::= SEQUENCE { + pvno[1] INTEGER, + msg-type[2] INTEGER, + padata[3] SEQUENCE OF PA-DATA OPTIONAL, + req-body[4] KDC-REQ-BODY +} + +PA-DATA ::= SEQUENCE { + padata-type[1] INTEGER, + padata-value[2] OCTET STRING, + -- might be encoded AP-REQ +} + +KDC-REQ-BODY ::= SEQUENCE { + kdc-options[0] KDCOptions, + cname[1] PrincipalName OPTIONAL, + -- Used only in AS-REQ + realm[2] Realm, -- Server's realm + -- Also client's in AS-REQ + sname[3] PrincipalName OPTIONAL, + from[4] KerberosTime OPTIONAL, + till[5] KerberosTime OPTIONAL, + rtime[6] KerberosTime OPTIONAL, + nonce[7] INTEGER, + etype[8] SEQUENCE OF INTEGER, + -- EncryptionType, + -- in preference order + addresses[9] HostAddresses OPTIONAL, + enc-authorization-data[10] EncryptedData OPTIONAL, + -- Encrypted AuthorizationData + -- encoding + additional-tickets[11] SEQUENCE OF Ticket OPTIONAL +} + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The fields in this message are: + +pvno + This field is included in each message, and specifies the protocol + version number. This document specifies protocol version 5. +msg-type + This field indicates the type of a protocol message. It will almost + always be the same as the application identifier associated with a + message. It is included to make the identifier more readily accessible + to the application. For the KDC-REQ message, this type will be + KRB_AS_REQ or KRB_TGS_REQ. +padata + The padata (pre-authentication data) field contains a sequence of + authentication information which may be needed before credentials can + be issued or decrypted. In the case of requests for additional tickets + (KRB_TGS_REQ), this field will include an element with padata-type of + PA-TGS-REQ and data of an authentication header (ticket-granting ticket + and authenticator). The checksum in the authenticator (which must be + collision-proof) is to be computed over the KDC-REQ-BODY encoding. In + most requests for initial authentication (KRB_AS_REQ) and most replies + (KDC-REP), the padata field will be left out. + + This field may also contain information needed by certain extensions to + the Kerberos protocol. For example, it might be used to initially + verify the identity of a client before any response is returned. This + is accomplished with a padata field with padata-type equal to + PA-ENC-TIMESTAMP and padata-value defined as follows: + + padata-type ::= PA-ENC-TIMESTAMP + padata-value ::= EncryptedData -- PA-ENC-TS-ENC + + PA-ENC-TS-ENC ::= SEQUENCE { + patimestamp[0] KerberosTime, -- client's time + pausec[1] INTEGER OPTIONAL + } + + with patimestamp containing the client's time and pausec containing the + microseconds which may be omitted if a client will not generate more + than one request per second. The ciphertext (padata-value) consists of + the PA-ENC-TS-ENC sequence, encrypted using the client's secret key. + + [use-specified-kvno item is here for discussion and may be removed] It + may also be used by the client to specify the version of a key that is + being used for accompanying preauthentication, and/or which should be + used to encrypt the reply from the KDC. + + PA-USE-SPECIFIED-KVNO ::= Integer + + The KDC should only accept and abide by the value of the + use-specified-kvno preauthentication data field when the specified key + is still valid and until use of a new key is confirmed. This situation + is likely to occur primarily during the period during which an updated + key is propagating to other KDC's in a realm. + + The padata field can also contain information needed to help the KDC or + the client select the key needed for generating or decrypting the + response. This form of the padata is useful for supporting the use of + certain token cards with Kerberos. The details of such extensions are + specified in separate documents. See [Pat92] for additional uses of + this field. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +padata-type + The padata-type element of the padata field indicates the way that the + padata-value element is to be interpreted. Negative values of + padata-type are reserved for unregistered use; non-negative values are + used for a registered interpretation of the element type. +req-body + This field is a placeholder delimiting the extent of the remaining + fields. If a checksum is to be calculated over the request, it is + calculated over an encoding of the KDC-REQ-BODY sequence which is + enclosed within the req-body field. +kdc-options + This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the + KDC and indicates the flags that the client wants set on the tickets as + well as other information that is to modify the behavior of the KDC. + Where appropriate, the name of an option may be the same as the flag + that is set by that option. Although in most case, the bit in the + options field will be the same as that in the flags field, this is not + guaranteed, so it is not acceptable to simply copy the options field to + the flags field. There are various checks that must be made before + honoring an option anyway. + + The kdc_options field is a bit-field, where the selected options are + indicated by the bit being set (1), and the unselected options and + reserved fields being reset (0). The encoding of the bits is specified + in section 5.2. The options are described in more detail above in + section 2. The meanings of the options are: + + Bit(s) Name Description + 0 RESERVED + Reserved for future expansion of +this + field. + + 1 FORWARDABLE + The FORWARDABLE option indicates +that + the ticket to be issued is to have +its + forwardable flag set. It may only +be + set on the initial request, or in a +sub- + sequent request if the +ticket-granting + ticket on which it is based is also +for- + wardable. + + 2 FORWARDED + The FORWARDED option is only +specified + in a request to the +ticket-granting + server and will only be honored if +the + ticket-granting ticket in the +request + has its FORWARDABLE bit set. +This + option indicates that this is a +request + for forwarding. The address(es) of +the + host from which the resulting ticket +is + to be valid are included in +the + addresses field of the request. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 3 PROXIABLE + The PROXIABLE option indicates that +the + ticket to be issued is to have its +prox- + iable flag set. It may only be set +on + the initial request, or in a +subsequent + request if the ticket-granting ticket +on + which it is based is also proxiable. + + 4 PROXY + The PROXY option indicates that this +is + a request for a proxy. This option +will + only be honored if the +ticket-granting + ticket in the request has its +PROXIABLE + bit set. The address(es) of the +host + from which the resulting ticket is to +be + valid are included in the +addresses + field of the request. + + 5 ALLOW-POSTDATE + The ALLOW-POSTDATE option indicates +that + the ticket to be issued is to have +its + MAY-POSTDATE flag set. It may only +be + set on the initial request, or in a +sub- + sequent request if the +ticket-granting + ticket on which it is based also has +its + MAY-POSTDATE flag set. + + 6 POSTDATED + The POSTDATED option indicates that +this + is a request for a postdated +ticket. + This option will only be honored if +the + ticket-granting ticket on which it +is + based has its MAY-POSTDATE flag +set. + The resulting ticket will also have +its + INVALID flag set, and that flag may +be + reset by a subsequent request to the +KDC + after the starttime in the ticket +has + been reached. + + 7 UNUSED + This option is presently unused. + + 8 RENEWABLE + The RENEWABLE option indicates that +the + ticket to be issued is to have +its + RENEWABLE flag set. It may only be +set + on the initial request, or when +the + ticket-granting ticket on which +the + request is based is also renewable. +If + this option is requested, then the +rtime + field in the request contains +the + desired absolute expiration time for +the + ticket. + + 9-13 UNUSED + These options are presently unused. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 14 REQUEST-ANONYMOUS + The REQUEST-ANONYMOUS option +indicates + that the ticket to be issued is not +to + identify the user to which it +was + issued. Instead, the principal +identif- + ier is to be generic, as specified +by + the policy of the realm (e.g. +usually + anonymous@realm). The purpose of +the + ticket is only to securely distribute +a + session key, and not to identify +the + user. The ANONYMOUS flag on the +ticket + to be returned should be set. If +the + local realms policy does not +permit + anonymous credentials, the request is +to + be rejected. + + 15-25 RESERVED + Reserved for future use. + + 26 DISABLE-TRANSITED-CHECK + By default the KDC will check the + transited field of a ticket-granting- + ticket against the policy of the local + realm before it will issue derivative + tickets based on the ticket granting + ticket. If this flag is set in the + request, checking of the transited +field + is disabled. Tickets issued without +the + performance of this check will be +noted + by the reset (0) value of the + TRANSITED-POLICY-CHECKED flag, + indicating to the application server + that the tranisted field must be +checked + locally. KDC's are encouraged but not + required to honor the + DISABLE-TRANSITED-CHECK option. + + 27 RENEWABLE-OK + The RENEWABLE-OK option indicates that +a + renewable ticket will be acceptable if +a + ticket with the requested life +cannot + otherwise be provided. If a ticket +with + the requested life cannot be +provided, + then a renewable ticket may be +issued + with a renew-till equal to the +the + requested endtime. The value of +the + renew-till field may still be limited +by + local limits, or limits selected by +the + individual principal or server. + + 28 ENC-TKT-IN-SKEY + This option is used only by the +ticket- + granting service. The +ENC-TKT-IN-SKEY + option indicates that the ticket for +the + end server is to be encrypted in +the + session key from the additional +ticket- + granting ticket provided. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 29 RESERVED + Reserved for future use. + + 30 RENEW + This option is used only by the +ticket- + granting service. The RENEW +option + indicates that the present request +is + for a renewal. The ticket provided +is + encrypted in the secret key for +the + server on which it is valid. +This + option will only be honored if +the + ticket to be renewed has its +RENEWABLE + flag set and if the time in its +renew- + till field has not passed. The +ticket + to be renewed is passed in the +padata + field as part of the +authentication + header. + + 31 VALIDATE + This option is used only by the +ticket- + granting service. The VALIDATE +option + indicates that the request is to +vali- + date a postdated ticket. It will +only + be honored if the ticket presented +is + postdated, presently has its +INVALID + flag set, and would be otherwise +usable + at this time. A ticket cannot be +vali- + dated before its starttime. The +ticket + presented for validation is encrypted +in + the key of the server for which it +is + valid and is passed in the padata +field + as part of the authentication header. + +cname and sname + These fields are the same as those described for the ticket in section + 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is + specified. If absent, the name of the server is taken from the name of + the client in the ticket passed as additional-tickets. +enc-authorization-data + The enc-authorization-data, if present (and it can only be present in + the TGS_REQ form), is an encoding of the desired authorization-data + encrypted under the sub-session key if present in the Authenticator, or + alternatively from the session key in the ticket-granting ticket, both + from the padata field in the KRB_AP_REQ. +realm + This field specifies the realm part of the server's principal + identifier. In the AS exchange, this is also the realm part of the + client's principal identifier. +from + This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket + requests when the requested ticket is to be postdated. It specifies the + desired start time for the requested ticket. If this field is omitted + then the KDC should use the current time instead. +till + This field contains the expiration date requested by the client in a + ticket request. It is optional and if omitted the requested ticket is + to have the maximum endtime permitted according to KDC policy for the + parties to the authentication exchange as limited by expiration date of + the ticket granting ticket or other preauthentication credentials. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +rtime + This field is the requested renew-till time sent from a client to the + KDC in a ticket request. It is optional. +nonce + This field is part of the KDC request and response. It it intended to + hold a random number generated by the client. If the same number is + included in the encrypted response from the KDC, it provides evidence + that the response is fresh and has not been replayed by an attacker. + Nonces must never be re-used. Ideally, it should be generated randomly, + but if the correct time is known, it may suffice[25]. +etype + This field specifies the desired encryption algorithm to be used in the + response. +addresses + This field is included in the initial request for tickets, and + optionally included in requests for additional tickets from the + ticket-granting server. It specifies the addresses from which the + requested ticket is to be valid. Normally it includes the addresses for + the client's host. If a proxy is requested, this field will contain + other addresses. The contents of this field are usually copied by the + KDC into the caddr field of the resulting ticket. +additional-tickets + Additional tickets may be optionally included in a request to the + ticket-granting server. If the ENC-TKT-IN-SKEY option has been + specified, then the session key from the additional ticket will be used + in place of the server's key to encrypt the new ticket. If more than + one option which requires additional tickets has been specified, then + the additional tickets are used in the order specified by the ordering + of the options bits (see kdc-options, above). + +The application code will be either ten (10) or twelve (12) depending on +whether the request is for an initial ticket (AS-REQ) or for an additional +ticket (TGS-REQ). + +The optional fields (addresses, authorization-data and additional-tickets) +are only included if necessary to perform the operation specified in the +kdc-options field. + +It should be noted that in KRB_TGS_REQ, the protocol version number appears +twice and two different message types appear: the KRB_TGS_REQ message +contains these fields as does the authentication header (KRB_AP_REQ) that is +passed in the padata field. + +5.4.2. KRB_KDC_REP definition + +The KRB_KDC_REP message format is used for the reply from the KDC for either +an initial (AS) request or a subsequent (TGS) request. There is no message +type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or +KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply +depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in +the client's secret key, and the client's key version number is included in +the key version number for the encrypted data. For KRB_TGS_REP, the +ciphertext is encrypted in the sub-session key from the Authenticator, or if +absent, the session key from the ticket-granting ticket used in the request. +In that case, no version number will be present in the EncryptedData +sequence. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The KRB_KDC_REP message contains the following fields: + +AS-REP ::= [APPLICATION 11] KDC-REP +TGS-REP ::= [APPLICATION 13] KDC-REP + +KDC-REP ::= SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + padata[2] SEQUENCE OF PA-DATA OPTIONAL, + crealm[3] Realm, + cname[4] PrincipalName, + ticket[5] Ticket, + enc-part[6] EncryptedData +} + +EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart +EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart + +EncKDCRepPart ::= SEQUENCE { + key[0] EncryptionKey, + last-req[1] LastReq, + nonce[2] INTEGER, + key-expiration[3] KerberosTime OPTIONAL, + flags[4] TicketFlags, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + srealm[9] Realm, + sname[10] PrincipalName, + caddr[11] HostAddresses OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is either + KRB_AS_REP or KRB_TGS_REP. +padata + This field is described in detail in section 5.4.1. One possible use + for this field is to encode an alternate "mix-in" string to be used + with a string-to-key algorithm (such as is described in section 6.3.2). + This ability is useful to ease transitions if a realm name needs to + change (e.g. when a company is acquired); in such a case all existing + password-derived entries in the KDC database would be flagged as + needing a special mix-in string until the next password change. +crealm, cname, srealm and sname + These fields are the same as those described for the ticket in section + 5.3.1. +ticket + The newly-issued ticket, from section 5.3.1. +enc-part + This field is a place holder for the ciphertext and related information + that forms the encrypted part of a message. The description of the + encrypted part of the message follows each appearance of this field. + The encrypted part is encoded as described in section 6.1. +key + This field is the same as described for the ticket in section 5.3.1. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +last-req + This field is returned by the KDC and specifies the time(s) of the last + request by a principal. Depending on what information is available, + this might be the last time that a request for a ticket-granting ticket + was made, or the last time that a request based on a ticket-granting + ticket was successful. It also might cover all servers for a realm, or + just the particular server. Some implementations may display this + information to the user to aid in discovering unauthorized use of one's + identity. It is similar in spirit to the last login time displayed when + logging into timesharing systems. +nonce + This field is described above in section 5.4.1. +key-expiration + The key-expiration field is part of the response from the KDC and + specifies the time that the client's secret key is due to expire. The + expiration might be the result of password aging or an account + expiration. This field will usually be left out of the TGS reply since + the response to the TGS request is encrypted in a session key and no + client information need be retrieved from the KDC database. It is up to + the application client (usually the login program) to take appropriate + action (such as notifying the user) if the expiration time is imminent. +flags, authtime, starttime, endtime, renew-till and caddr + These fields are duplicates of those found in the encrypted portion of + the attached ticket (see section 5.3.1), provided so the client may + verify they match the intended request and to assist in proper ticket + caching. If the message is of type KRB_TGS_REP, the caddr field will + only be filled in if the request was for a proxy or forwarded ticket, + or if the user is substituting a subset of the addresses from the + ticket granting ticket. If the client-requested addresses are not + present or not used, then the addresses contained in the ticket will be + the same as those included in the ticket-granting ticket. + +5.5. Client/Server (CS) message specifications + +This section specifies the format of the messages used for the +authentication of the client to the application server. + +5.5.1. KRB_AP_REQ definition + +The KRB_AP_REQ message contains the Kerberos protocol version number, the +message type KRB_AP_REQ, an options field to indicate any options in use, +and the ticket and authenticator themselves. The KRB_AP_REQ message is often +referred to as the 'authentication header'. + +AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData +} + +APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) +} + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REQ. +ap-options + This field appears in the application request (KRB_AP_REQ) and affects + the way the request is processed. It is a bit-field, where the selected + options are indicated by the bit being set (1), and the unselected + options and reserved fields being reset (0). The encoding of the bits + is specified in section 5.2. The meanings of the options are: + + Bit(s) Name Description + + 0 RESERVED + Reserved for future expansion of this + field. + + 1 USE-SESSION-KEY + The USE-SESSION-KEY option indicates + that the ticket the client is presenting + to a server is encrypted in the session + key from the server's ticket-granting + ticket. When this option is not speci- + fied, the ticket is encrypted in the + server's secret key. + + 2 MUTUAL-REQUIRED + The MUTUAL-REQUIRED option tells the + server that the client requires mutual + authentication, and that it must respond + with a KRB_AP_REP message. + + 3-31 RESERVED + Reserved for future use. + +ticket + This field is a ticket authenticating the client to the server. +authenticator + This contains the authenticator, which includes the client's choice of + a subkey. Its encoding is described in section 5.3.2. + +5.5.2. KRB_AP_REP definition + +The KRB_AP_REP message contains the Kerberos protocol version number, the +message type, and an encrypted time- stamp. The message is sent in in +response to an application request (KRB_AP_REQ) where the mutual +authentication option has been selected in the ap-options field. + +AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[2] EncryptedData +} + +EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { + ctime[0] KerberosTime, + cusec[1] INTEGER, + subkey[2] EncryptionKey OPTIONAL, + seq-number[3] INTEGER OPTIONAL +} + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The encoded EncAPRepPart is encrypted in the shared session key of the +ticket. The optional subkey field can be used in an application-arranged +negotiation to choose a per association session key. + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_AP_REP. +enc-part + This field is described above in section 5.4.2. +ctime + This field contains the current time on the client's host. +cusec + This field contains the microsecond part of the client's timestamp. +subkey + This field contains an encryption key which is to be used to protect + this specific application session. See section 3.2.6 for specifics on + how this field is used to negotiate a key. Unless an application + specifies otherwise, if this field is left out, the sub-session key + from the authenticator, or if also left out, the session key from the + ticket will be used. + +5.5.3. Error message reply + +If an error occurs while processing the application request, the KRB_ERROR +message will be sent in response. See section 5.9.1 for the format of the +error message. The cname and crealm fields may be left out if the server +cannot determine their appropriate values from the corresponding KRB_AP_REQ +message. If the authenticator was decipherable, the ctime and cusec fields +will contain the values from it. + +5.6. KRB_SAFE message specification + +This section specifies the format of a message that can be used by either +side (client or server) of an application to send a tamper-proof message to +its peer. It presumes that a session key has previously been exchanged (for +example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.6.1. KRB_SAFE definition + +The KRB_SAFE message contains user data along with a collision-proof +checksum keyed with the last encryption key negotiated via subkeys, or the +session key if no negotiation has occured. The message fields are: + +KRB-SAFE ::= [APPLICATION 20] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + safe-body[2] KRB-SAFE-BODY, + cksum[3] Checksum +} + +KRB-SAFE-BODY ::= SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_SAFE. +safe-body + This field is a placeholder for the body of the KRB-SAFE message. +cksum + This field contains the checksum of the application data. Checksum + details are described in section 6.4. The checksum is computed over the + encoding of the KRB-SAFE sequence. First, the cksum is zeroed and the + checksum is computed over the encoding of the KRB-SAFE sequence, then + the checksum is set to the result of that computation, and finally the + KRB-SAFE sequence is encoded again. +user-data + This field is part of the KRB_SAFE and KRB_PRIV messages and contain + the application specific data that is being passed from the sender to + the recipient. +timestamp + This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents + are the current time as known by the sender of the message. By checking + the timestamp, the recipient of the message is able to make sure that + it was recently generated, and is not a replay. +usec + This field is part of the KRB_SAFE and KRB_PRIV headers. It contains + the microsecond part of the timestamp. +seq-number + This field is described above in section 5.3.2. +s-address + This field specifies the address in use by the sender of the message. + It may be omitted if not required by the application protocol. The + application designer considering omission of this field is warned, that + the inclusion of this address prevents some kinds of replay attacks + (e.g., reflection attacks) and that it is only acceptable to omit this + address if there is sufficient information in the integrity protected + part of the application message for the recipient to unambiguously + determine if it was the intended recipient. +r-address + This field specifies the address in use by the recipient of the + message. It may be omitted for some uses (such as broadcast protocols), + but the recipient may arbitrarily reject such messages. This field + along with s-address can be used to help detect messages which have + been incorrectly or maliciously delivered to the wrong recipient. + +5.7. KRB_PRIV message specification + +This section specifies the format of a message that can be used by either +side (client or server) of an application to securely and privately send a +message to its peer. It presumes that a session key has previously been +exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). + +5.7.1. KRB_PRIV definition + +The KRB_PRIV message contains user data encrypted in the Session Key. The +message fields are: + +KRB-PRIV ::= [APPLICATION 21] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[3] EncryptedData +} + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, -- sender's +addr + r-address[5] HostAddress OPTIONAL -- recip's +addr +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_PRIV. +enc-part + This field holds an encoding of the EncKrbPrivPart sequence encrypted + under the session key[32]. This encrypted encoding is used for the + enc-part field of the KRB-PRIV message. See section 6 for the format of + the ciphertext. +user-data, timestamp, usec, s-address and r-address + These fields are described above in section 5.6.1. +seq-number + This field is described above in section 5.3.2. + +5.8. KRB_CRED message specification + +This section specifies the format of a message that can be used to send +Kerberos credentials from one principal to another. It is presented here to +encourage a common mechanism to be used by applications when forwarding +tickets or providing proxies to subordinate servers. It presumes that a +session key has already been exchanged perhaps by using the +KRB_AP_REQ/KRB_AP_REP messages. + +5.8.1. KRB_CRED definition + +The KRB_CRED message contains a sequence of tickets to be sent and +information needed to use the tickets, including the session key from each. +The information needed to use the tickets is encrypted under an encryption +key previously exchanged or transferred alongside the KRB_CRED message. The +message fields are: + +KRB-CRED ::= [APPLICATION 22] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, -- KRB_CRED + tickets[2] SEQUENCE OF Ticket, + enc-part[3] EncryptedData +} + +EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { + ticket-info[0] SEQUENCE OF KrbCredInfo, + nonce[1] INTEGER OPTIONAL, + timestamp[2] KerberosTime OPTIONAL, + usec[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL +} + +KrbCredInfo ::= SEQUENCE { + key[0] EncryptionKey, + prealm[1] Realm OPTIONAL, + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + pname[2] PrincipalName OPTIONAL, + flags[3] TicketFlags OPTIONAL, + authtime[4] KerberosTime OPTIONAL, + starttime[5] KerberosTime OPTIONAL, + endtime[6] KerberosTime OPTIONAL + renew-till[7] KerberosTime OPTIONAL, + srealm[8] Realm OPTIONAL, + sname[9] PrincipalName OPTIONAL, + caddr[10] HostAddresses OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_CRED. +tickets + These are the tickets obtained from the KDC specifically for use by the + intended recipient. Successive tickets are paired with the + corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED + message. +enc-part + This field holds an encoding of the EncKrbCredPart sequence encrypted + under the session key shared between the sender and the intended + recipient. This encrypted encoding is used for the enc-part field of + the KRB-CRED message. See section 6 for the format of the ciphertext. +nonce + If practical, an application may require the inclusion of a nonce + generated by the recipient of the message. If the same value is + included as the nonce in the message, it provides evidence that the + message is fresh and has not been replayed by an attacker. A nonce must + never be re-used; it should be generated randomly by the recipient of + the message and provided to the sender of the message in an application + specific manner. +timestamp and usec + These fields specify the time that the KRB-CRED message was generated. + The time is used to provide assurance that the message is fresh. +s-address and r-address + These fields are described above in section 5.6.1. They are used + optionally to provide additional assurance of the integrity of the + KRB-CRED message. +key + This field exists in the corresponding ticket passed by the KRB-CRED + message and is used to pass the session key from the sender to the + intended recipient. The field's encoding is described in section 6.2. + +The following fields are optional. If present, they can be associated with +the credentials in the remote ticket file. If left out, then it is assumed +that the recipient of the credentials already knows their value. + +prealm and pname + The name and realm of the delegated principal identity. +flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr + These fields contain the values of the correspond- ing fields from the + ticket found in the ticket field. Descriptions of the fields are + identical to the descriptions in the KDC-REP message. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +5.9. Error message specification + +This section specifies the format for the KRB_ERROR message. The fields +included in the message are intended to return as much information as +possible about an error. It is not expected that all the information +required by the fields will be available for all types of errors. If the +appropriate information is not available when the message is composed, the +corresponding field will be left out of the message. + +Note that since the KRB_ERROR message is only optionally integrity +protected, it is quite possible for an intruder to synthesize or modify such +a message. In particular, this means that unless appropriate integrity +protection mechanisms have been applied to the KRB_ERROR message, the client +should not use any fields in this message for security-critical purposes, +such as setting a system clock or generating a fresh authenticator. The +message can be useful, however, for advising a user on the reason for some +failure. + +5.9.1. KRB_ERROR definition + +The KRB_ERROR message consists of the following fields: + +KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL, + e-cksum[13] Checksum OPTIONAL, +(*REMOVE7/14*) e-typed-data[14] SEQUENCE of ETypedData +OPTIONAL +} + +pvno and msg-type + These fields are described above in section 5.4.1. msg-type is + KRB_ERROR. +ctime + This field is described above in section 5.4.1. +cusec + This field is described above in section 5.5.2. +stime + This field contains the current time on the server. It is of type + KerberosTime. +susec + This field contains the microsecond part of the server's timestamp. Its + value ranges from 0 to 999999. It appears along with stime. The two + fields are used in conjunction to specify a reasonably accurate + timestamp. + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +error-code + This field contains the error code returned by Kerberos or the server + when a request fails. To interpret the value of this field see the list + of error codes in section 8. Implementations are encouraged to provide + for national language support in the display of error messages. +crealm, cname, srealm and sname + These fields are described above in section 5.3.1. +e-text + This field contains additional text to help explain the error code + associated with the failed request (for example, it might include a + principal name which was unknown). +e-data + This field contains additional data about the error for use by the + application to help it recover from or handle the error. If present, + this field will contain the encoding of a sequence of TypedData + (TYPED-DATA below), unless the errorcode is KDC_ERR_PREAUTH_REQUIRED, + in which case it will contain the encoding of a sequence of of padata + fields (METHOD-DATA below), each corresponding to an acceptable + pre-authentication method and optionally containing data for the + method: + + TYPED-DATA ::= SEQUENCE of TypeData + METHOD-DATA ::= SEQUENCE of PA-DATA + + TypedData ::= SEQUENCE { + data-type[0] INTEGER, + data-value[1] OCTET STRING OPTIONAL + } + + Note that e-data-types have been reserved for all PA data types defined + prior to July 1999. For the KDC_ERR_PREAUTH_REQUIRED message, when + using new PA data types defined in July 1999 or later, the METHOD-DATA + sequence must itself be encapsulated in an TypedData element of type + TD-PADATA. All new implementations interpreting the METHOD-DATA field + for the KDC_ERR_PREAUTH_REQUIRED message must accept a type of + TD-PADATA, extract the typed data field and interpret the use any + elements encapsulated in the TD-PADATA elements as if they were present + in the METHOD-DATA sequence. +e-cksum + This field contains an optional checksum for the KRB-ERROR message. The + checksum is calculated over the Kerberos ASN.1 encoding of the + KRB-ERROR message with the checksum absent. The checksum is then added + to the KRB-ERROR structure and the message is re-encoded. The Checksum + should be calculated using the session key from the ticket granting + ticket or service ticket, where available. If the error is in response + to a TGS or AP request, the checksum should be calculated uing the the + session key from the client's ticket. If the error is in response to an + AS request, then the checksum should be calulated using the client's + secret key ONLY if there has been suitable preauthentication to prove + knowledge of the secret key by the client[33]. If a checksum can not be + computed because the key to be used is not available, no checksum will + be included. +e-typed-data + [***Will be deleted 7/14***] This field contains optional data that may + be used to help the client recover from the indicated error. [This + could contain the METHOD-DATA specified since I don't think anyone + actually uses it yet. It could also contain the PA-DATA sequence for + the preauth required error if we had a clear way to transition to the + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + use of this field from the use of the untyped e-data field.] For + example, this field may specify the key version of the key used to + verify preauthentication: + + e-data-type := 20 -- Key version number + e-data-value := Integer -- Key version number used to + verify preauthentication + +6. Encryption and Checksum Specifications + +The Kerberos protocols described in this document are designed to use stream +encryption ciphers, which can be simulated using commonly available block +encryption ciphers, such as the Data Encryption Standard, [DES77] in +conjunction with block chaining and checksum methods [DESM80]. Encryption is +used to prove the identities of the network entities participating in +message exchanges. The Key Distribution Center for each realm is trusted by +all principals registered in that realm to store a secret key in confidence. +Proof of knowledge of this secret key is used to verify the authenticity of +a principal. [*** Discussion above will change to use 3DES as example +7/14/99 ***] + +The KDC uses the principal's secret key (in the AS exchange) or a shared +session key (in the TGS exchange) to encrypt responses to ticket requests; +the ability to obtain the secret key or session key implies the knowledge of +the appropriate keys and the identity of the KDC. The ability of a principal +to decrypt the KDC response and present a Ticket and a properly formed +Authenticator (generated with the session key from the KDC response) to a +service verifies the identity of the principal; likewise the ability of the +service to extract the session key from the Ticket and prove its knowledge +thereof in a response verifies the identity of the service. + +The Kerberos protocols generally assume that the encryption used is secure +from cryptanalysis; however, in some cases, the order of fields in the +encrypted portions of messages are arranged to minimize the effects of +poorly chosen keys. It is still important to choose good keys. If keys are +derived from user-typed passwords, those passwords need to be well chosen to +make brute force attacks more difficult. Poorly chosen keys still make easy +targets for intruders. + +The following sections specify the encryption and checksum mechanisms +currently defined for Kerberos. The encodings, chaining, and padding +requirements for each are described. For encryption methods, it is often +desirable to place random information (often referred to as a confounder) at +the start of the message. The requirements for a confounder are specified +with each encryption mechanism. + +Some encryption systems use a block-chaining method to improve the the +security characteristics of the ciphertext. However, these chaining methods +often don't provide an integrity check upon decryption. Such systems (such +as DES in CBC mode) must be augmented with a checksum of the plain-text +which can be verified at decryption and used to detect any tampering or +damage. Such checksums should be good at detecting burst errors in the +input. If any damage is detected, the decryption routine is expected to +return an error indicating the failure of an integrity check. Each +encryption type is expected to provide and verify an appropriate checksum. +The specification of each encryption method sets out its checksum +requirements. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Finally, where a key is to be derived from a user's password, an algorithm +for converting the password to a key of the appropriate type is included. It +is desirable for the string to key function to be one-way, and for the +mapping to be different in different realms. This is important because users +who are registered in more than one realm will often use the same password +in each, and it is desirable that an attacker compromising the Kerberos +server in one realm not obtain or derive the user's key in another. + +For an discussion of the integrity characteristics of the candidate +encryption and checksum methods considered for Kerberos, the reader is +referred to [SG92]. + +6.1. Encryption Specifications + +The following ASN.1 definition describes all encrypted messages. The +enc-part field which appears in the unencrypted part of messages in section +5 is a sequence consisting of an encryption type, an optional key version +number, and the ciphertext. + +EncryptedData ::= SEQUENCE { + etype[0] INTEGER, -- EncryptionType + kvno[1] INTEGER OPTIONAL, + cipher[2] OCTET STRING -- ciphertext +} + +etype + This field identifies which encryption algorithm was used to encipher + the cipher. Detailed specifications for selected encryption types + appear later in this section. +kvno + This field contains the version number of the key under which data is + encrypted. It is only present in messages encrypted under long lasting + keys, such as principals' secret keys. +cipher + This field contains the enciphered text, encoded as an OCTET STRING. + +The cipher field is generated by applying the specified encryption algorithm +to data composed of the message and algorithm-specific inputs. Encryption +mechanisms defined for use with Kerberos must take sufficient measures to +guarantee the integrity of the plaintext, and we recommend they also take +measures to protect against precomputed dictionary attacks. If the +encryption algorithm is not itself capable of doing so, the protections can +often be enhanced by adding a checksum and a confounder. + +The suggested format for the data to be encrypted includes a confounder, a +checksum, the encoded plaintext, and any necessary padding. The msg-seq +field contains the part of the protocol message described in section 5 which +is to be encrypted. The confounder, checksum, and padding are all untagged +and untyped, and their length is exactly sufficient to hold the appropriate +item. The type and length is implicit and specified by the particular +encryption type being used (etype). The format for the data to be encrypted +is described in the following diagram: + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + +-----------+----------+-------------+-----+ + |confounder | check | msg-seq | pad | + +-----------+----------+-------------+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +CipherText ::= ENCRYPTED SEQUENCE { + confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, + check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, + msg-seq[2] MsgSequence, + pad UNTAGGED OCTET STRING(pad_length) OPTIONAL +} + +One generates a random confounder of the appropriate length, placing it in +confounder; zeroes out check; calculates the appropriate checksum over +confounder, check, and msg-seq, placing the result in check; adds the +necessary padding; then encrypts using the specified encryption type and the +appropriate key. + +Unless otherwise specified, a definition of an encryption algorithm that +specifies a checksum, a length for the confounder field, or an octet +boundary for padding uses this ciphertext format[36]. Those fields which are +not specified will be omitted. + +In the interest of allowing all implementations using a particular +encryption type to communicate with all others using that type, the +specification of an encryption type defines any checksum that is needed as +part of the encryption process. If an alternative checksum is to be used, a +new encryption type must be defined. + +Some cryptosystems require additional information beyond the key and the +data to be encrypted. For example, DES, when used in cipher-block-chaining +mode, requires an initialization vector. If required, the description for +each encryption type must specify the source of such additional information. +6.2. Encryption Keys + +The sequence below shows the encoding of an encryption key: + + EncryptionKey ::= SEQUENCE { + keytype[0] INTEGER, + keyvalue[1] OCTET STRING + } + +keytype + This field specifies the type of encryption that is to be performed + using the key that follows in the keyvalue field. It will always + correspond to the etype to be used to generate or decode the + EncryptedData. In cases when multiple algorithms use a common kind of + key (e.g., if the encryption algorithm uses an alternate checksum + algorithm for an integrity check, or a different chaining mechanism), + the keytype provides information needed to determine which algorithm is + to be used. +keyvalue + This field contains the key itself, encoded as an octet string. + +All negative values for the encryption key type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpreta- tions. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +6.3. Encryption Systems + +6.3.1. The NULL Encryption System (null) + +If no encryption is in use, the encryption system is said to be the NULL +encryption system. In the NULL encryption system there is no checksum, +confounder or padding. The ciphertext is simply the plaintext. The NULL Key +is used by the null encryption system and is zero octets in length, with +keytype zero (0). + +6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) + +The des-cbc-crc encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. A +CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the +confounder and message sequence (msg-seq) and placed in the cksum field. DES +blocks are 8 bytes. As a result, the data to be encrypted (the concatenation +of confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. The details of the encryption of this data are identical +to those for the des-cbc-md5 encryption mode. + +Note that, since the CRC-32 checksum is not collision-proof, an attacker +could use a probabilistic chosen-plaintext attack to generate a valid +message even if a confounder is used [SG92]. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. The use of the CRC-32 as the checksum for ticket or +authenticator is no longer mandated as an interoperability requirement for +Kerberos Version 5 Specification 1 (See section 9.1 for specific details). + +6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) + +The des-cbc-md4 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD4 checksum (described in [MD492]) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. The details of the encryption of this data are identical +to those for the des-cbc-md5 encryption mode. + +6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) + +The des-cbc-md5 encryption mode encrypts information under the Data +Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. +An MD5 checksum (described in [MD5-92].) is applied to the confounder and +message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 +bytes. As a result, the data to be encrypted (the concatenation of +confounder, checksum, and message) must be padded to an 8 byte boundary +before encryption. + +Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are +concatenated to make the 64-bit inputs for the DES algorithms. The first +octet supplies the 8 most significant bits (with the octet's MSbit used as +the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., +and the eighth octet supplies the 8 least significant bits. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Encryption under DES using cipher block chaining requires an additional +input in the form of an initialization vector. Unless otherwise specified, +zero should be used as the initialization vector. Kerberos' use of DES +requires an 8 octet confounder. + +The DES specifications identify some 'weak' and 'semi-weak' keys; those keys +shall not be used for encrypting messages for use in Kerberos. Additionally, +because of the way that keys are derived for the encryption of checksums, +keys shall not be used that yield 'weak' or 'semi-weak' keys when +eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. + +A DES key is 8 octets of data, with keytype one (1). This consists of 56 +bits of key, and 8 parity bits (one per octet). The key is encoded as a +series of 8 octets written in MSB-first order. The bits within the key are +also encoded in MSB order. For example, if the encryption key is +(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where +B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity +bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the +MSbit). [See the FIPS 81 introduction for reference.] + +String to key transformation + +To generate a DES key from a text string (password), a "salt" is +concatenated to the text string, and then padded with ASCII nulls to an 8 +byte boundary. This "salt" is normally the realm and each component of the +principal's name appended. However, sometimes different salts are used --- +for example, when a realm is renamed, or if a user changes her username, or +for compatibility with Kerberos V4 (whose string-to-key algorithm uses a +null string for the salt). This string is then fan-folded and eXclusive-ORed +with itself to form an 8 byte DES key. Before eXclusive-ORing a block, every +byte is shifted one bit to the left to leave the lowest bit zero. The key is +the "corrected" by correcting the parity on the key, and if the key matches +a 'weak' or 'semi-weak' key as described in the DES specification, it is +eXclusive-ORed with the constant 00000000000000F0. This key is then used to +generate a DES CBC checksum on the initial string (with the salt appended). +The result of the CBC checksum is the "corrected" as described above to form +the result which is return as the key. Pseudocode follows: + + name_to_default_salt(realm, name) { + s = realm + for(each component in name) { + s = s + component; + } + return s; + } + + key_correction(key) { + fixparity(key); + if (is_weak_key_key(key)) + key = key XOR 0xF0; + return(key); + } + + string_to_key(string,salt) { + + odd = 1; + s = string + salt; + tempkey = NULL; + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + pad(s); /* with nulls to 8 byte boundary */ + for(8byteblock in s) { + if(odd == 0) { + odd = 1; + reverse(8byteblock) + } + else odd = 0; + left shift every byte in 8byteblock one bit; + tempkey = tempkey XOR 8byteblock; + } + tempkey = key_correction(tempkey); + key = key_correction(DES-CBC-check(s,tempkey)); + return(key); + } + +6.3.5. Triple DES with HMAC-SHA1 Kerberos Encryption Type with Key +Derivation [Horowitz] + +[*** Note that there are several 3DES varients in use in different Kerberos +implemenations, updates to this section will be sent to the cat list and +krb-protocol list prior to the Oslo IETF, including the key derivation and +non-key derivation varients ***] NOTE: This description currently refers to +documents, the contents of which might be bettered included by value in this +spec. The description below was provided by Marc Horowitz, and the form in +which it will finally appear is yet to be determined. This description is +included in this version of the draft because it does describe the +implemenation ready for use with the MIT implementation. Note also that the +encryption identifier has been left unspecified here because the value from +Marc Horowitz's spec conflicted with some other impmenentations implemented +based on perevious versions of the specification. + +This encryption type is based on the Triple DES cryptosystem, the HMAC-SHA1 +[Krawczyk96] message authentication algorithm, and key derivation for +Kerberos V5 [HorowitzB96]. + +The des3-cbc-hmac-sha1 encryption type has been assigned the value ??. The +hmac-sha1-des3 checksum type has been assigned the value 12. + +Encryption Type des3-cbc-hmac-sha1 + +EncryptedData using this type must be generated as described in +[Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC mode. The +keyed hash algorithm is HMAC-SHA1. Unless otherwise specified, a zero IV +must be used. If the length of the input data is not a multiple of the block +size, zero octets must be used to pad the plaintext to the next eight-octet +boundary. The counfounder must be eight random octets (one block). + +Checksum Type hmac-sha1-des3 + +Checksums using this type must be generated as described in [Horowitz96]. +The keyed hash algorithm is HMAC-SHA1. + +Common Requirements + +The EncryptionKey value is 24 octets long. The 7 most significant bits of +each octet contain key bits, and the least significant bit is the inverse of +the xor of the key bits. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +For the purposes of key derivation, the block size is 64 bits, and the key +size is 168 bits. The 168 bits output by key derivation are converted to an +EncryptionKey value as follows. First, the 168 bits are divided into three +groups of 56 bits, which are expanded individually into 64 bits as follows: + + 1 2 3 4 5 6 7 p + 9 10 11 12 13 14 15 p +17 18 19 20 21 22 23 p +25 26 27 28 29 30 31 p +33 34 35 36 37 38 39 p +41 42 43 44 45 46 47 p +49 50 51 52 53 54 55 p +56 48 40 32 24 16 8 p + +The "p" bits are parity bits computed over the data bits. The output of the +three expansions are concatenated to form the EncryptionKey value. + +When the HMAC-SHA1 of a string is computed, the key is used in the +EncryptedKey form. + +Key Derivation + +In the Kerberos protocol, cryptographic keys are used in a number of places. +In order to minimize the effect of compromising a key, it is desirable to +use a different key for each of these places. Key derivation [Horowitz96] +can be used to construct different keys for each operation from the keys +transported on the network. For this to be possible, a small change to the +specification is necessary. + +This section specifies a profile for the use of key derivation [Horowitz96] +with Kerberos. For each place where a key is used, a ``key usage'' must is +specified for that purpose. The key, key usage, and encryption/checksum type +together describe the transformation from plaintext to ciphertext, or +plaintext to checksum. + +Key Usage Values + +This is a complete list of places keys are used in the kerberos protocol, +with key usage values and RFC 1510 section numbers: + + 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the + client key (section 5.4.1) + 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or + application session key), encrypted with the service key + (section 5.4.2) + 3. AS-REP encrypted part (includes tgs session key or application + session key), encrypted with the client key (section 5.4.2) + 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + session key (section 5.4.1) + 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs + authenticator subkey (section 5.4.1) + 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed + with the tgs session key (sections 5.3.2, 5.4.1) + 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs + authenticator subkey), encrypted with the tgs session key + (section 5.3.2) + 8. TGS-REP encrypted part (includes application session key), + encrypted with the tgs session key (section 5.4.2) + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + 9. TGS-REP encrypted part (includes application session key), + encrypted with the tgs authenticator subkey (section 5.4.2) +10. AP-REQ Authenticator cksum, keyed with the application session + key (section 5.3.2) +11. AP-REQ Authenticator (includes application authenticator + subkey), encrypted with the application session key (section + 5.3.2) +12. AP-REP encrypted part (includes application session subkey), + encrypted with the application session key (section 5.5.2) +13. KRB-PRIV encrypted part, encrypted with a key chosen by the + application (section 5.7.1) +14. KRB-CRED encrypted part, encrypted with a key chosen by the + application (section 5.6.1) +15. KRB-SAVE cksum, keyed with a key chosen by the application + (section 5.8.1) +18. KRB-ERROR checksum (e-cksum in section 5.9.1) +19. AD-KDCIssued checksum (ad-checksum in appendix B.1) +20. Checksum for Mandatory Ticket Extensions (appendix B.6) +21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) + +Key usage values between 1024 and 2047 (inclusive) are reserved for +application use. Applications should use even values for encryption and odd +values for checksums within this range. + +A few of these key usages need a little clarification. A service which +receives an AP-REQ has no way to know if the enclosed Ticket was part of an +AS-REP or TGS-REP. Therefore, key usage 2 must always be used for generating +a Ticket, whether it is in response to an AS- REQ or TGS-REQ. + +There might exist other documents which define protocols in terms of the +RFC1510 encryption types or checksum types. Such documents would not know +about key usages. In order that these documents continue to be meaningful +until they are updated, key usages 1024 and 1025 must be used to derive keys +for encryption and checksums, respectively. New protocols defined in terms +of the Kerberos encryption and checksum types should use their own key +usages. Key usages may be registered with IANA to avoid conflicts. Key +usages must be unsigned 32 bit integers. Zero is not permitted. + +Defining Cryptosystems Using Key Derivation + +Kerberos requires that the ciphertext component of EncryptedData be +tamper-resistant as well as confidential. This implies encryption and +integrity functions, which must each use their own separate keys. So, for +each key usage, two keys must be generated, one for encryption (Ke), and one +for integrity (Ki): + + Ke = DK(protocol key, key usage | 0xAA) + Ki = DK(protocol key, key usage | 0x55) + +where the protocol key is from the EncryptionKey from the wire protocol, and +the key usage is represented as a 32 bit integer in network byte order. The +ciphertest must be generated from the plaintext as follows: + + ciphertext = E(Ke, confounder | plaintext | padding) | + H(Ki, confounder | plaintext | padding) + +The confounder and padding are specific to the encryption algorithm E. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +When generating a checksum only, there is no need for a confounder or +padding. Again, a new key (Kc) must be used. Checksums must be generated +from the plaintext as follows: + + Kc = DK(protocol key, key usage | 0x99) + + MAC = H(Kc, plaintext) + +Note that each enctype is described by an encryption algorithm E and a keyed +hash algorithm H, and each checksum type is described by a keyed hash +algorithm H. HMAC, with an appropriate hash, is recommended for use as H. + +Key Derivation from Passwords + +The well-known constant for password key derivation must be the byte string +{0x6b 0x65 0x72 0x62 0x65 0x72 0x6f 0x73}. These values correspond to the +ASCII encoding for the string "kerberos". + +6.4. Checksums + +The following is the ASN.1 definition used for a checksum: + + Checksum ::= SEQUENCE { + cksumtype[0] INTEGER, + checksum[1] OCTET STRING + } + +cksumtype + This field indicates the algorithm used to generate the accompanying + checksum. +checksum + This field contains the checksum itself, encoded as an octet string. + +Detailed specification of selected checksum types appear later in this +section. Negative values for the checksum type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpretations. + +Checksums used by Kerberos can be classified by two properties: whether they +are collision-proof, and whether they are keyed. It is infeasible to find +two plaintexts which generate the same checksum value for a collision-proof +checksum. A key is required to perturb or initialize the algorithm in a +keyed checksum. To prevent message-stream modification by an active +attacker, unkeyed checksums should only be used when the checksum and +message will be subsequently encrypted (e.g. the checksums defined as part +of the encryption algorithms covered earlier in this section). + +Collision-proof checksums can be made tamper-proof if the checksum value is +encrypted before inclusion in a message. In such cases, the composition of +the checksum and the encryption algorithm must be considered a separate +checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum +algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for the +encrypted forms of unkeyed collision-proof checksums, Kerberos prepends a +confounder before the checksum is calculated. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +6.4.1. The CRC-32 Checksum (crc32) + +The CRC-32 checksum calculates a checksum based on a cyclic redundancy check +as described in ISO 3309 [ISO3309]. The resulting checksum is four (4) +octets in length. The CRC-32 is neither keyed nor collision-proof. The use +of this checksum is not recommended. An attacker using a probabilistic +chosen-plaintext attack as described in [SG92] might be able to generate an +alternative message that satisfies the checksum. The use of collision-proof +checksums is recommended for environments where such attacks represent a +significant threat. + +6.4.2. The RSA MD4 Checksum (rsa-md4) + +The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm +[MD4-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed to +be collision-proof. + +6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) + +The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD4 +checksum algorithm, and encrypting the confounder and the checksum using DES +in cipher-block-chaining (CBC) mode using a variant of the key, where the +variant is computed by eXclusive-ORing the key with the constant +F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The +resulting checksum is 24 octets long (8 octets of which are redundant). This +checksum is tamper-proof and believed to be collision-proof. + +The DES specifications identify some weak keys' and 'semi-weak keys'; those +keys shall not be used for generating RSA-MD4 checksums for use in Kerberos. + +The format for the checksum is described in the follow- ing diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.4. The RSA MD5 Checksum (rsa-md5) + +The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. +[MD5-92]. The algorithm takes as input an input message of arbitrary length +and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed to +be collision-proof. + +6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) + +The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by +prepending an 8 octet confounder before the text, applying the RSA MD5 +checksum algorithm, and encrypting the confounder and the checksum using DES + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +in cipher-block-chaining (CBC) mode using a variant of the key, where the +variant is computed by eXclusive-ORing the key with the hexadecimal constant +F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting +checksum is 24 octets long (8 octets of which are redundant). This checksum +is tamper-proof and believed to be collision-proof. + +The DES specifications identify some 'weak keys' and 'semi-weak keys'; those +keys shall not be used for encrypting RSA-MD5 checksums for use in Kerberos. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ +| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) +} + +6.4.6. DES cipher-block chained checksum (des-mac) + +The DES-MAC checksum is computed by prepending an 8 octet confounder to the +plaintext, performing a DES CBC-mode encryption on the result using the key +and an initialization vector of zero, taking the last block of the +ciphertext, prepending the same confounder and encrypting the pair using DES +in cipher-block-chaining (CBC) mode using a a variant of the key, where the +variant is computed by eXclusive-ORing the key with the hexadecimal constant +F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting +checksum is 128 bits (16 octets) long, 64 bits of which are redundant. This +checksum is tamper-proof and collision-proof. + +The format for the checksum is described in the following diagram: + ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ +| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | ++--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ + +The format cannot be described in ASN.1, but for those who prefer an +ASN.1-like notation: + +des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(8) +} + +The DES specifications identify some 'weak' and 'semi-weak' keys; those keys +shall not be used for generating DES-MAC checksums for use in Kerberos, nor +shall a key be used whose variant is 'weak' or 'semi-weak'. + +6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) + +The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by +applying the RSA MD4 checksum algorithm and encrypting the results using DES +in cipher-block-chaining (CBC) mode using a DES key as both key and + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +initialization vector. The resulting checksum is 16 octets long. This +checksum is tamper-proof and believed to be collision-proof. Note that this +checksum type is the old method for encoding the RSA-MD4-DES checksum and it +is no longer recommended. + +6.4.8. DES cipher-block chained checksum alternative (des-mac-k) + +The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption +of the plaintext, and using the last block of the ciphertext as the checksum +value. It is keyed with an encryption key and an initialization vector; any +uses which do not specify an additional initialization vector will use the +key as both key and initialization vector. The resulting checksum is 64 bits +(8 octets) long. This checksum is tamper-proof and collision-proof. Note +that this checksum type is the old method for encoding the DES-MAC checksum +and it is no longer recommended. The DES specifications identify some 'weak +keys' and 'semi-weak keys'; those keys shall not be used for generating +DES-MAC checksums for use in Kerberos. + +7. Naming Constraints + +7.1. Realm Names + +Although realm names are encoded as GeneralStrings and although a realm can +technically select any name it chooses, interoperability across realm +boundaries requires agreement on how realm names are to be assigned, and +what information they imply. + +To enforce these conventions, each realm must conform to the conventions +itself, and it must require that any realms with which inter-realm keys are +shared also conform to the conventions and require the same from its +neighbors. + +Kerberos realm names are case sensitive. Realm names that differ only in the +case of the characters are not equivalent. There are presently four styles +of realm names: domain, X500, other, and reserved. Examples of each style +follow: + + domain: ATHENA.MIT.EDU (example) + X500: C=US/O=OSF (example) + other: NAMETYPE:rest/of.name=without-restrictions (example) + reserved: reserved, but will not conflict with above + +Domain names must look like domain names: they consist of components +separated by periods (.) and they contain neither colons (:) nor slashes +(/). Domain names must be converted to upper case when used as realm names. + +X.500 names contain an equal (=) and cannot contain a colon (:) before the +equal. The realm names for X.500 names will be string representations of the +names with components separated by slashes. Leading and trailing slashes +will not be included. + +Names that fall into the other category must begin with a prefix that +contains no equal (=) or period (.) and the prefix must be followed by a +colon (:) and the rest of the name. All prefixes must be assigned before +they may be used. Presently none are assigned. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +The reserved category includes strings which do not fall into the first +three categories. All names in this category are reserved. It is unlikely +that names will be assigned to this category unless there is a very strong +argument for not using the 'other' category. + +These rules guarantee that there will be no conflicts between the various +name styles. The following additional constraints apply to the assignment of +realm names in the domain and X.500 categories: the name of a realm for the +domain or X.500 formats must either be used by the organization owning (to +whom it was assigned) an Internet domain name or X.500 name, or in the case +that no such names are registered, authority to use a realm name may be +derived from the authority of the parent realm. For example, if there is no +domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can +authorize the creation of a realm with that name. + +This is acceptable because the organization to which the parent is assigned +is presumably the organization authorized to assign names to its children in +the X.500 and domain name systems as well. If the parent assigns a realm +name without also registering it in the domain name or X.500 hierarchy, it +is the parent's responsibility to make sure that there will not in the +future exists a name identical to the realm name of the child unless it is +assigned to the same entity as the realm name. + +7.2. Principal Names + +As was the case for realm names, conventions are needed to ensure that all +agree on what information is implied by a principal name. The name-type +field that is part of the principal name indicates the kind of information +implied by the name. The name-type should be treated as a hint. Ignoring the +name type, no two names can be the same (i.e. at least one of the +components, or the realm, must be different). The following name types are +defined: + + name-type value meaning + + NT-UNKNOWN 0 Name type not known + NT-PRINCIPAL 1 General principal name (e.g. username, or DCE +principal) + NT-SRV-INST 2 Service and other unique instance (krbtgt) + NT-SRV-HST 3 Service with host name as instance (telnet, +rcommands) + NT-SRV-XHST 4 Service with slash-separated host name components + NT-UID 5 Unique ID + NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] + +When a name implies no information other than its uniqueness at a particular +time the name type PRINCIPAL should be used. The principal name type should +be used for users, and it might also be used for a unique server. If the +name is a unique machine generated ID that is guaranteed never to be +reassigned then the name type of UID should be used (note that it is +generally a bad idea to reassign names of any type since stale entries might +remain in access control lists). + +If the first component of a name identifies a service and the remaining +components identify an instance of the service in a server specified manner, +then the name type of SRV-INST should be used. An example of this name type +is the Kerberos ticket-granting service whose name has a first component of +krbtgt and a second component identifying the realm for which the ticket is +valid. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +If instance is a single component following the service name and the +instance identifies the host on which the server is running, then the name +type SRV-HST should be used. This type is typically used for Internet +services such as telnet and the Berkeley R commands. If the separate +components of the host name appear as successive components following the +name of the service, then the name type SRV-XHST should be used. This type +might be used to identify servers on hosts with X.500 names where the slash +(/) might otherwise be ambiguous. + +A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 +certificiate is translated into a Kerberos name. The encoding of the X.509 +name as a Kerberos principal shall conform to the encoding rules specified +in RFC 2253. + +A name type of UNKNOWN should be used when the form of the name is not +known. When comparing names, a name of type UNKNOWN will match principals +authenticated with names of any type. A principal authenticated with a name +of type UNKNOWN, however, will only match other names of type UNKNOWN. + +Names of any type with an initial component of 'krbtgt' are reserved for the +Kerberos ticket granting service. See section 8.2.3 for the form of such +names. + +7.2.1. Name of server principals + +The principal identifier for a server on a host will generally be composed +of two parts: (1) the realm of the KDC with which the server is registered, +and (2) a two-component name of type NT-SRV-HST if the host name is an +Internet domain name or a multi-component name of type NT-SRV-XHST if the +name of the host is of a form such as X.500 that allows slash (/) +separators. The first component of the two- or multi-component name will +identify the service and the latter components will identify the host. Where +the name of the host is not case sensitive (for example, with Internet +domain names) the name of the host must be lower case. If specified by the +application protocol for services such as telnet and the Berkeley R commands +which run with system privileges, the first component may be the string +'host' instead of a service specific identifier. When a host has an official +name and one or more aliases, the official name of the host must be used +when constructing the name of the server principal. + +8. Constants and other defined values + +8.1. Host address types + +All negative values for the host address type are reserved for local use. +All non-negative values are reserved for officially assigned type fields and +interpretations. + +The values of the types for the following addresses are chosen to match the +defined address family constants in the Berkeley Standard Distributions of +Unix. They can be found in with symbolic names AF_xxx (where xxx is an +abbreviation of the address family name). + +Internet (IPv4) Addresses + +Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB +order. The type of IPv4 addresses is two (2). + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Internet (IPv6) Addresses [Westerlund] + +IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The +type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The +following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: + + * the Unspecified Address + * the Loopback Address + * Link-Local addresses + +IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. + +CHAOSnet addresses + +CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. +The type of CHAOSnet addresses is five (5). + +ISO addresses + +ISO addresses are variable-length. The type of ISO addresses is seven (7). + +Xerox Network Services (XNS) addresses + +XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The +type of XNS addresses is six (6). + +AppleTalk Datagram Delivery Protocol (DDP) addresses + +AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit network +number. The first octet of the address is the node number; the remaining two +octets encode the network number in MSB order. The type of AppleTalk DDP +addresses is sixteen (16). + +DECnet Phase IV addresses + +DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The +type of DECnet Phase IV addresses is twelve (12). + +Netbios addresses + +Netbios addresses are 16-octet addresses typically composed of 1 to 15 +characters, trailing blank (ascii char 20) filled, with a 16th octet of 0x0. +The type of Netbios addresses is 20 (0x14). + +8.2. KDC messages + +8.2.1. UDP/IP transport + +When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP +IP transport, the client shall send a UDP datagram containing only an +encoding of the request to port 88 (decimal) at the KDC's IP address; the +KDC will respond with a reply datagram containing only an encoding of the +reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at +the sender's IP address. Kerberos servers supporting IP transport must +accept UDP requests on port 88 (decimal). The response to a request made +through UDP/IP transport must also use UDP/IP transport. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +8.2.2. TCP/IP transport [Westerlund,Danielsson] + +Kerberos servers (KDC's) should accept TCP requests on port 88 (decimal) and +clients should support the sending of TCP requests on port 88 (decimal). +When the KRB_KDC_REQ message is sent to the KDC over a TCP stream, a new +connection will be established for each authentication exchange (request and +response). The KRB_KDC_REP or KRB_ERROR message will be returned to the +client on the same TCP stream that was established for the request. The +response to a request made through TCP/IP transport must also use TCP/IP +transport. Implementors should note that some extentions to the Kerberos +protocol will not work if any implementation not supporting the TCP +transport is involved (client or KDC). Implementors are strongly urged to +support the TCP transport on both the client and server and are advised that +the current notation of "should" support will likely change in the future to +must support. The KDC may close the TCP stream after sending a response, but +may leave the stream open if it expects a followup - in which case it may +close the stream at any time if resource constratints or other factors make +it desirable to do so. Care must be taken in managing TCP/IP connections +with the KDC to prevent denial of service attacks based on the number of +TCP/IP connections with the KDC that remain open. If multiple exchanges with +the KDC are needed for certain forms of preauthentication, multiple TCP +connections may be required. A client may close the stream after receiving +response, and should close the stream if it does not expect to send followup +messages. The client must be prepared to have the stream closed by the KDC +at anytime, in which case it must simply connect again when it is ready to +send subsequent messages. + +The first four octets of the TCP stream used to transmit the request request +will encode in network byte order the length of the request (KRB_KDC_REQ), +and the length will be followed by the request itself. The response will +similarly be preceeded by a 4 octet encoding in network byte order of the +length of the KRB_KDC_REP or the KRB_ERROR message and will be followed by +the KRB_KDC_REP or the KRB_ERROR response. If the sign bit is set on the +integer represented by the first 4 octets, then the next 4 octets will be +read, extending the length of the field by another 4 octets (less the sign +bit which is reserved for future expansion). + +8.2.3. OSI transport + +During authentication of an OSI client to an OSI server, the mutual +authentication of an OSI server to an OSI client, the transfer of +credentials from an OSI client to an OSI server, or during exchange of +private or integrity checked messages, Kerberos protocol messages may be +treated as opaque objects and the type of the authentication mechanism will +be: + +OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), + security(5),kerberosv5(2)} + +Depending on the situation, the opaque object will be an authentication +header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message +(KRB_SAFE), a private message (KRB_PRIV), or a credentials message +(KRB_CRED). The opaque data contains an application code as specified in the +ASN.1 description for each message. The application code may be used by +Kerberos to determine the message type. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +8.2.3. Name of the TGS + +The principal identifier of the ticket-granting service shall be composed of +three parts: (1) the realm of the KDC issuing the TGS ticket (2) a two-part +name of type NT-SRV-INST, with the first part "krbtgt" and the second part +the name of the realm which will accept the ticket-granting ticket. For +example, a ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be +used to get tickets from the ATHENA.MIT.EDU KDC has a principal identifier +of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A +ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be used to get +tickets from the MIT.EDU realm has a principal identifier of +"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). + +8.3. Protocol constants and associated values + +The following tables list constants used in the protocol and defines their +meanings. Ranges are specified in the "specification" section that limit the +values of constants for which values are defined here. This allows +implementations to make assumptions about the maximum values that will be +received for these constants. Implementation receiving values outside the +range specified in the "specification" section may reject the request, but +they must recover cleanly. + +Encryption type etype value block size minimum pad size confounder +size +NULL 0 1 0 0 +des-cbc-crc 1 8 4 8 +des-cbc-md4 2 8 0 8 +des-cbc-md5 3 8 0 8 + 4 +des3-cbc-md5 5 8 0 8 + 6 +des3-cbc-sha1 7 8 0 8 +sign-dsa-generate 8 +(old-pkinit-will-remove) +dsaWithSHA1-CmsOID 9 (pkinit) +md5WithRSAEncryption-CmsOID 10 (pkinit) +sha1WithRSAEncryption-CmsOID 11 (pkinit) +rc2CBC-EnvOID 12 (pkinit) +rsaEncryption-EnvOID 13 (pkinit from PKCS#1 +v1.5) +rsaES-OAEP-ENV-OID 14 (pkinit from PKCS#1 +v2.0) +des-ede3-cbc-Env-OID 15 (pkinit) +des3kd-cbc-sha1 ?? 8 0 8 +ENCTYPE_PK_CROSS 48 (reserved for pkcross) + 0x8003 + +Checksum type sumtype value checksum size +CRC32 1 4 +rsa-md4 2 16 +rsa-md4-des 3 24 +des-mac 4 16 +des-mac-k 5 8 +rsa-md4-des-k 6 16 +rsa-md5 7 16 +rsa-md5-des 8 24 +rsa-md5-des3 9 24 +hmac-sha1-des3 12 20 (I had this as 10, is it +12) + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +padata type padata-type value + +PA-TGS-REQ 1 +PA-ENC-TIMESTAMP 2 +PA-PW-SALT 3 + 4 +PA-ENC-UNIX-TIME 5 +PA-SANDIA-SECUREID 6 +PA-SESAME 7 +PA-OSF-DCE 8 +PA-CYBERSAFE-SECUREID 9 +PA-AFS3-SALT 10 +PA-ETYPE-INFO 11 +SAM-CHALLENGE 12 (sam/otp) +SAM-RESPONSE 13 (sam/otp) +PA-PK-AS-REQ 14 (pkinit) +PA-PK-AS-REP 15 (pkinit) +PA-PK-AS-SIGN 16 (***remove on 7/14***) +PA-PK-KEY-REQ 17 (***remove on 7/14***) +PA-PK-KEY-REP 18 (***remove on 7/14***) +PA-USE-SPECIFIED-KVNO 20 +SAM-REDIRECT 21 (sam/otp) +PA-GET-FROM-TYPED-DATA 22 + +data-type value form of typed-data + + 1-21 +TD-PADATA 22 +TD-PKINIT-CMS-CERTIFICATES 101 CertificateSet from CMS +TD-KRB-PRINCIPAL 102 +TD-KRB-REALM 103 +TD-TRUSTED-CERTIFIERS 104 +TD-CERTIFICATE-INDEX 105 + +authorization data type ad-type value +AD-IF-RELEVANT 1 +AD-INTENDED-FOR-SERVER 2 +AD-INTENDED-FOR-APPLICATION-CLASS 3 +AD-KDC-ISSUED 4 +AD-OR 5 +AD-MANDATORY-TICKET-EXTENSIONS 6 +AD-IN-TICKET-EXTENSIONS 7 +reserved values 8-63 +OSF-DCE 64 +SESAME 65 + +Ticket Extension Types + +TE-TYPE-NULL 0 Null ticket extension +TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data + 2 TE-TYPE-PKCROSS-KDC (I have reservations) +TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket +TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp + 5 TE-TYPE-DEST-HOST (I have reservations) + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +alternate authentication type method-type value +reserved values 0-63 +ATT-CHALLENGE-RESPONSE 64 + +transited encoding type tr-type value +DOMAIN-X500-COMPRESS 1 +reserved values all others + +Label Value Meaning or MIT code + +pvno 5 current Kerberos protocol version number + +message types + +KRB_AS_REQ 10 Request for initial authentication +KRB_AS_REP 11 Response to KRB_AS_REQ request +KRB_TGS_REQ 12 Request for authentication based on TGT +KRB_TGS_REP 13 Response to KRB_TGS_REQ request +KRB_AP_REQ 14 application request to server +KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL +KRB_SAFE 20 Safe (checksummed) application message +KRB_PRIV 21 Private (encrypted) application message +KRB_CRED 22 Private (encrypted) message to forward +credentials +KRB_ERROR 30 Error response + +name types + +KRB_NT_UNKNOWN 0 Name type not known +KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for +users +KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) +KRB_NT_SRV_HST 3 Service with host name as instance (telnet, +rcommands) +KRB_NT_SRV_XHST 4 Service with host as remaining components +KRB_NT_UID 5 Unique ID +KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253] + +error codes + +KDC_ERR_NONE 0 No error +KDC_ERR_NAME_EXP 1 Client's entry in database has expired +KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired +KDC_ERR_BAD_PVNO 3 Requested protocol version # not +supported +KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key +KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key +KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database +KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database +KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database +KDC_ERR_NULL_KEY 9 The client or server has a null key +KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating +KDC_ERR_NEVER_VALID 11 Requested start time is later than end +time +KDC_ERR_POLICY 12 KDC policy rejects request +KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option +KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type +KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type +KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type +KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type +KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked +KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked +KDC_ERR_TGT_REVOKED 20 TGT has been revoked + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later +KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later +KDC_ERR_KEY_EXPIRED 23 Password has expired - change password +KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was +invalid +KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired +[40] +KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match +KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user +only +KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path +KDC_ERR_SVC_UNAVAILABLE 29 A service is not available +KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field +failed +KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired +KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid +KRB_AP_ERR_REPEAT 34 Request is a replay +KRB_AP_ERR_NOT_US 35 The ticket isn't for us +KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match +KRB_AP_ERR_SKEW 37 Clock skew too great +KRB_AP_ERR_BADADDR 38 Incorrect net address +KRB_AP_ERR_BADVERSION 39 Protocol version mismatch +KRB_AP_ERR_MSG_TYPE 40 Invalid msg type +KRB_AP_ERR_MODIFIED 41 Message stream modified +KRB_AP_ERR_BADORDER 42 Message out of order +KRB_AP_ERR_BADKEYVER 44 Specified version of key is not +available +KRB_AP_ERR_NOKEY 45 Service key not available +KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed +KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction +KRB_AP_ERR_METHOD 48 Alternative authentication method +required +KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message +KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in +message +KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path +KRB_ERR_RESPONSE_TOO_BIG 52 Response too big for UDP, retry with TCP +KRB_ERR_GENERIC 60 Generic error (description in e-text) +KRB_ERR_FIELD_TOOLONG 61 Field is too long for this +implementation +KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) +KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) +KDC_ERROR_INVALID_SIG 64 (pkinit) +KDC_ERR_KEY_TOO_WEAK 65 (pkinit) +KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) +KRB_AP_ERR_NO_TGT 67 (user-to-user) +KDC_ERR_WRONG_REALM 68 (user-to-user) +KRB_AP_ERR_USER_TO_USER_REQUIRED 69 (user-to-user) +KDC_ERR_CANT_VERIFY_CERTIFICATE 70 (pkinit) +KDC_ERR_INVALID_CERTIFICATE 71 (pkinit) +KDC_ERR_REVOKED_CERTIFICATE 72 (pkinit) +KDC_ERR_REVOCATION_STATUS_UNKNOWN 73 (pkinit) +KDC_ERR_REVOCATION_STATUS_UNAVAILABLE 74 (pkinit) +KDC_ERR_CLIENT_NAME_MISMATCH 75 (pkinit) +KDC_ERR_KDC_NAME_MISMATCH 76 (pkinit) + +9. Interoperability requirements + +Version 5 of the Kerberos protocol supports a myriad of options. Among these +are multiple encryption and checksum types, alternative encoding schemes for +the transited field, optional mechanisms for pre-authentication, the +handling of tickets with no addresses, options for mutual authentication, +user to user authentication, support for proxies, forwarding, postdating, +and renewing tickets, the format of realm names, and the handling of +authorization data. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +In order to ensure the interoperability of realms, it is necessary to define +a minimal configuration which must be supported by all implementations. This +minimal configuration is subject to change as technology does. For example, +if at some later date it is discovered that one of the required encryption +or checksum algorithms is not secure, it will be replaced. + +9.1. Specification 2 + +This section defines the second specification of these options. +Implementations which are configured in this way can be said to support +Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may +be found in RFC1510. + +Transport + +TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance +to specification 2. Kerberos clients claiming conformance to specification 2 +must support UDP/IP transport for messages with the KDC and should support +TCP/IP transport. + +Encryption and checksum methods + +The following encryption and checksum mechanisms must be supported. +Implementations may support other mechanisms as well, but the additional +mechanisms may only be used when communicating with principals known to also +support them: This list is to be determined. [***This section will change, +and alternatives will be sent to the cat and krb-protocol list prior to the +Oslo IETF - change will be made 7/14/99 ***] + +Encryption: DES-CBC-MD5 +Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 + +Realm Names + +All implementations must understand hierarchical realms in both the Internet +Domain and the X.500 style. When a ticket granting ticket for an unknown +realm is requested, the KDC must be able to determine the names of the +intermediate realms between the KDCs realm and the requested realm. + +Transited field encoding + +DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. +Alternative encodings may be supported, but they may be used only when that +encoding is supported by ALL intermediate realms. + +Pre-authentication methods + +The TGS-REQ method must be supported. The TGS-REQ method is not used on the +initial request. The PA-ENC-TIMESTAMP method must be supported by clients +but whether it is enabled by default may be determined on a realm by realm +basis. If not used in the initial request and the error +KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an +acceptable method, the client should retry the initial request using the +PA-ENC-TIMESTAMP preauthentication method. Servers need not support the +PA-ENC-TIMESTAMP method, but if not supported the server should ignore the +presence of PA-ENC-TIMESTAMP pre-authentication in a request. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +Mutual authentication + +Mutual authentication (via the KRB_AP_REP message) must be supported. + +Ticket addresses and flags + +All KDC's must pass on tickets that carry no addresses (i.e. if a TGT +contains no addresses, the KDC will return derivative tickets), but each +realm may set its own policy for issuing such tickets, and each application +server will set its own policy with respect to accepting them. + +Proxies and forwarded tickets must be supported. Individual realms and +application servers can set their own policy on when such tickets will be +accepted. + +All implementations must recognize renewable and postdated tickets, but need +not actually implement them. If these options are not supported, the +starttime and endtime in the ticket shall specify a ticket's entire useful +life. When a postdated ticket is decoded by a server, all implementations +shall make the presence of the postdated flag visible to the calling server. + +User-to-user authentication + +Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC option) +must be provided by implementations, but individual realms may decide as a +matter of policy to reject such requests on a per-principal or realm-wide +basis. + +Authorization data + +Implementations must pass all authorization data subfields from +ticket-granting tickets to any derivative tickets unless directed to +suppress a subfield as part of the definition of that registered subfield +type (it is never incorrect to pass on a subfield, and no registered +subfield types presently specify suppression at the KDC). + +Implementations must make the contents of any authorization data subfields +available to the server when a ticket is used. Implementations are not +required to allow clients to specify the contents of the authorization data +fields. + +Constant ranges + +All protocol constants are constrained to 32 bit (signed) values unless +further constrained by the protocol definition. This limit is provided to +allow implementations to make assumptions about the maximum values that will +be received for these constants. Implementation receiving values outside +this range may reject the request, but they must recover cleanly. + +9.2. Recommended KDC values + +Following is a list of recommended values for a KDC implementation, based on +the list of suggested configuration constants (see section 4.4). + +minimum lifetime 5 minutes +maximum renewable lifetime 1 week +maximum ticket lifetime 1 day +empty addresses only when suitable restrictions appear + in authorization data +proxiable, etc. Allowed. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +10. REFERENCES + +[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- + cation Service for Computer Networks," IEEE Communica- + tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). + +[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. + Saltzer, Section E.2.1: Kerberos Authentication and + Authorization System, M.I.T. Project Athena, Cambridge, + Massachusetts (December 21, 1987). + +[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- + beros: An Authentication Service for Open Network Sys- + tems," pp. 191-202 in Usenix Conference Proceedings, + Dallas, Texas (February, 1988). + +[NS78] Roger M. Needham and Michael D. Schroeder, "Using + Encryption for Authentication in Large Networks of Com- + puters," Communications of the ACM, Vol. 21(12), + pp. 993-999 (December, 1978). + +[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- + stamps in Key Distribution Protocols," Communications + of the ACM, Vol. 24(8), pp. 533-536 (August 1981). + +[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, + "The Evolution of the Kerberos Authentication Service," + in an IEEE Computer Society Text soon to be published + (June 1992). + +[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and + Accounting for Distributed Systems," in Proceedings of + the 13th International Conference on Distributed Com- + puting Systems, Pittsburgh, PA (May, 1993). + +[DS90] Don Davis and Ralph Swick, "Workstation Services and + Kerberos Authentication at Project Athena," Technical + Memorandum TM-424, MIT Laboratory for Computer Science + (February 1990). + +[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- + merfeld, and K. Raeburn, Section E.1: Service Manage- + ment System, M.I.T. Project Athena, Cambridge, Mas- + sachusetts (1987). + +[X509-88] CCITT, Recommendation X.509: The Directory Authentica- + tion Framework, December 1988. + +[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password + Guessing Attacks, Open Software Foundation DCE Request + for Comments 26 (December 1992). + +[DES77] National Bureau of Standards, U.S. Department of Com- + merce, "Data Encryption Standard," Federal Information + Processing Standards Publication 46, Washington, DC + (1977). + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +[DESM80] National Bureau of Standards, U.S. Department of Com- + merce, "DES Modes of Operation," Federal Information + Processing Standards Publication 81, Springfield, VA + (December 1980). + +[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message + Integrity in Cryptographic Protocols," in Proceedings + of the IEEE Symposium on Research in Security and + Privacy, Oakland, California (May 1992). + +[IS3309] International Organization for Standardization, "ISO + Information Processing Systems - Data Communication - + High-Level Data Link Control Procedure - Frame Struc- + ture," IS 3309 (October 1984). 3rd Edition. + +[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC + 1320, MIT Laboratory for Computer Science (April + 1992). + +[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC + 1321, MIT Laboratory for Computer Science (April + 1992). + +[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication," Working Draft + draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). + +[Horowitz96] Horowitz, M., "Key Derivation for Authentication, + Integrity, and Privacy", draft-horowitz-key-derivation-02.txt, + August 1998. + +[HorowitzB96] Horowitz, M., "Key Derivation for Kerberos V5", draft- + horowitz-kerb-key-derivation-01.txt, September 1998. + +[Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: + Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- + md5-01.txt, August, 1996. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A. Pseudo-code for protocol processing + +This appendix provides pseudo-code describing how the messages are to be +constructed and interpreted by clients and servers. + +A.1. KRB_AS_REQ generation + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_AS_REQ */ + + if(pa_enc_timestamp_required) then + request.padata.padata-type = PA-ENC-TIMESTAMP; + get system_time; + padata-body.patimestamp,pausec = system_time; + encrypt padata-body into request.padata.padata-value + using client.key; /* derived from password */ + endif + + body.kdc-options := users's preferences; + body.cname := user's name; + body.realm := user's realm; + body.sname := service's name; /* usually "krbtgt", "localrealm" */ + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + omit body.enc-authorization-data; + request.req-body := body; + + kerberos := lookup(name of local kerberos server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.2. KRB_AS_REQ verification and KRB_AS_REP generation + + decode message into req; + + client := lookup(req.cname,req.realm); + server := lookup(req.sname,req.realm); + + get system_time; + kdc_time := system_time.seconds; + + if (!client) then + /* no client in Database */ + error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); + endif + if (!server) then + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + + if(client.pa_enc_timestamp_required and + pa_enc_timestamp not present) then + error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); + endif + + if(pa_enc_timestamp present) then + decrypt req.padata-value into decrypted_enc_timestamp + using client.key; + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + if(decrypted_enc_timestamp is not within allowable skew) +then + error_out(KDC_ERR_PREAUTH_FAILED); + endif + if(decrypted_enc_timestamp and usec is replay) + error_out(KDC_ERR_PREAUTH_FAILED); + endif + add decrypted_enc_timestamp and usec to replay cache; + endif + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := req.srealm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + if (req.kdc-options.FORWARDABLE is set) then + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.PROXIABLE is set) then + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + set new_tkt.flags.PROXIABLE; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + set new_tkt.flags.MAY-POSTDATE; + endif + if ((req.kdc-options.RENEW is set) or + (req.kdc-options.VALIDATE is set) or + (req.kdc-options.PROXY is set) or + (req.kdc-options.FORWARDED is set) or + (req.kdc-options.ENC-TKT-IN-SKEY is set)) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.session := random_session_key(); + new_tkt.cname := req.cname; + new_tkt.crealm := req.crealm; + new_tkt.transited := empty_transited_field(); + + new_tkt.authtime := kdc_time; + + if (req.kdc-options.POSTDATED is set) then + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + new_tkt.starttime := req.from; + else + omit new_tkt.starttime; /* treated as authtime when omitted */ + endif + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till)) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := req.till; + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if (req.kdc-options.RENEWABLE is set) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm); + else + omit new_tkt.renew-till; /* only present if RENEWABLE */ + endif + + if (req.addresses) then + new_tkt.caddr := req.addresses; + else + omit new_tkt.caddr; + endif + + new_tkt.authorization_data := empty_authorization_data(); + + encode to-be-encrypted part of ticket into OCTET STRING; + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + + /* Start processing the response */ + + resp.pvno := 5; + resp.msg-type := KRB_AS_REP; + resp.cname := req.cname; + resp.crealm := req.realm; + resp.ticket := new_tkt; + + resp.key := new_tkt.session; + resp.last-req := fetch_last_request_info(client); + resp.nonce := req.nonce; + resp.key-expiration := client.expiration; + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + resp.realm := new_tkt.realm; + resp.sname := new_tkt.sname; + + resp.caddr := new_tkt.caddr; + + encode body of reply into OCTET STRING; + + resp.enc-part := encrypt OCTET STRING + using use_etype, client.key, client.p_kvno; + send(resp); + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.3. KRB_AS_REP verification + + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then + set pa_enc_timestamp_required; + goto KRB_AS_REQ; + endif + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key */ + /* from the response immediately */ + + key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, + resp.padata); + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and key; + zero(key); + + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + if near(resp.princ_exp) then + print(warning message); + endif + save_for_later(ticket,session,client,server,times,flags); + +A.4. KRB_AS_REP and KRB_TGS_REP common checks + + if (decryption_error() or + (req.cname != resp.cname) or + (req.realm != resp.crealm) or + (req.sname != resp.sname) or + (req.realm != resp.realm) or + (req.nonce != resp.nonce) or + (req.addresses != resp.caddr)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + /* make sure no flags are set that shouldn't be, and that all that +*/ + /* should be are set +*/ + if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.from = 0) and + (resp.starttime is not within allowable skew)) then + destroy resp.key; + return KRB_AP_ERR_SKEW; + endif + if ((req.from != 0) and (req.from != resp.starttime)) then + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.till != 0) and (resp.endtime > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (req.rtime != 0) and (resp.renew-till > req.rtime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.kdc-options.RENEWABLE-OK is set) and + (resp.flags.RENEWABLE) and + (req.till != 0) and + (resp.renew-till > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + +A.5. KRB_TGS_REQ generation + + /* Note that make_application_request might have to recursivly +*/ + /* call this routine to get the appropriate ticket-granting ticket +*/ + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_TGS_REQ */ + + body.kdc-options := users's preferences; + /* If the TGT is not for the realm of the end-server */ + /* then the sname will be for a TGT for the end-realm */ + /* and the realm of the requested ticket (body.realm) */ + /* will be that of the TGS to which the TGT we are */ + /* sending applies */ + body.sname := service's name; + body.realm := service's realm; + + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + + body.enc-authorization-data := user-supplied data; + if (body.kdc-options.ENC-TKT-IN-SKEY) then + body.additional-tickets_ticket := second TGT; + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + endif + + request.req-body := body; + check := generate_checksum (req.body,checksumtype); + + request.padata[0].padata-type := PA-TGS-REQ; + request.padata[0].padata-value := create a KRB_AP_REQ using + the TGT and checksum + + /* add in any other padata as required/supplied */ + + kerberos := lookup(name of local kerberose server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation + + /* note that reading the application request requires first + determining the server for which a ticket was issued, and choosing +the + correct key for decryption. The name of the server appears in the + plaintext part of the ticket. */ + + if (no KRB_AP_REQ in req.padata) then + error_out(KDC_ERR_PADATA_TYPE_NOSUPP); + endif + verify KRB_AP_REQ in req.padata; + + /* Note that the realm in which the Kerberos server is operating is + determined by the instance from the ticket-granting ticket. The +realm + in the ticket-granting ticket is the realm under which the ticket + granting ticket was issued. It is possible for a single Kerberos + server to support more than one realm. */ + + auth_hdr := KRB_AP_REQ; + tgt := auth_hdr.ticket; + + if (tgt.sname is not a TGT for local realm and is not req.sname) +then + error_out(KRB_AP_ERR_NOT_US); + + realm := realm_tgt_is_for(tgt); + + decode remainder of request; + + if (auth_hdr.authenticator.cksum is missing) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + if (auth_hdr.authenticator.cksum type is not supported) then + error_out(KDC_ERR_SUMTYPE_NOSUPP); + endif + if (auth_hdr.authenticator.cksum is not both collision-proof and + keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + set computed_checksum := checksum(req); + if (computed_checksum != auth_hdr.authenticatory.cksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + server := lookup(req.sname,realm); + + if (!server) then + if (is_foreign_tgt_name(req.sname)) then + server := best_intermediate_tgs(req.sname); + else + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + endif + + session := generate_random_session_key(); + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := realm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + new_tkt.caddr := tgt.caddr; + resp.caddr := NULL; /* We only include this if they change */ + if (req.kdc-options.FORWARDABLE is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.FORWARDED is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDED; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + if (tgt.flags.FORWARDED is set) then + set new_tkt.flags.FORWARDED; + endif + + if (req.kdc-options.PROXIABLE is set) then + if (tgt.flags.PROXIABLE is reset) + error_out(KDC_ERR_BADOPTION); + endif + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.PROXY is set) then + if (tgt.flags.PROXIABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXY; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + + if (req.kdc-options.ALLOW-POSTDATE is set) then + if (tgt.flags.MAY-POSTDATE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.MAY-POSTDATE; + endif + if (req.kdc-options.POSTDATED is set) then + if (tgt.flags.MAY-POSTDATE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + new_tkt.starttime := req.from; + endif + + if (req.kdc-options.VALIDATE is set) then + if (tgt.flags.INVALID is reset) then + error_out(KDC_ERR_POLICY); + endif + if (tgt.starttime > kdc_time) then + error_out(KRB_AP_ERR_NYV); + endif + if (check_hot_list(tgt)) then + error_out(KRB_AP_ERR_REPEAT); + endif + tkt := tgt; + reset new_tkt.flags.INVALID; + endif + + if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, + and those already processed) is set) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.authtime := tgt.authtime; + + if (req.kdc-options.RENEW is set) then + /* Note that if the endtime has already passed, the ticket would +*/ + /* have been rejected in the initial authentication stage, so +*/ + /* there is no need to check again here +*/ + if (tgt.flags.RENEWABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + if (tgt.renew-till < kdc_time) then + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + tkt := tgt; + new_tkt.starttime := kdc_time; + old_life := tgt.endttime - tgt.starttime; + new_tkt.endtime := min(tgt.renew-till, + new_tkt.starttime + old_life); + else + new_tkt.starttime := kdc_time; + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm, + tgt.endtime); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till) and + (tgt.flags.RENEWABLE is set) then + /* we set the RENEWABLE option for later processing +*/ + set req.kdc-options.RENEWABLE; + req.rtime := min(req.till, tgt.renew-till); + endif + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (tgt.flags.RENEWABLE is set)) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm, + tgt.renew-till); + else + new_tkt.renew-till := OMIT; /* leave the renew-till field out +*/ + endif + if (req.enc-authorization-data is present) then + decrypt req.enc-authorization-data into +decrypted_authorization_data + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + endif + new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data ++ + decrypted_authorization_data; + + new_tkt.key := session; + new_tkt.crealm := tgt.crealm; + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + new_tkt.cname := req.auth_hdr.ticket.cname; + + if (realm_tgt_is_for(tgt) := tgt.realm) then + /* tgt issued by local realm */ + new_tkt.transited := tgt.transited; + else + /* was issued for this realm by some other realm */ + if (tgt.transited.tr-type not supported) then + error_out(KDC_ERR_TRTYPE_NOSUPP); + endif + new_tkt.transited := compress_transited(tgt.transited + +tgt.realm) + /* Don't check tranited field if TGT for foreign realm, + * or requested not to check */ + if (is_not_foreign_tgt_name(new_tkt.server) + && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then + /* Check it, so end-server does not have to + * but don't fail, end-server may still accept it */ + if (check_transited_field(new_tkt.transited) == OK) + set new_tkt.flags.TRANSITED-POLICY-CHECKED; + endif + endif + endif + + encode encrypted part of new_tkt into OCTET STRING; + if (req.kdc-options.ENC-TKT-IN-SKEY is set) then + if (server not specified) then + server = req.second_ticket.client; + endif + if ((req.second_ticket is not a TGT) or + (req.second_ticket.client != server)) then + error_out(KDC_ERR_POLICY); + endif + + new_tkt.enc-part := encrypt OCTET STRING using + using etype_for_key(second-ticket.key), second-ticket.key; + else + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + endif + + resp.pvno := 5; + resp.msg-type := KRB_TGS_REP; + resp.crealm := tgt.crealm; + resp.cname := tgt.cname; + resp.ticket := new_tkt; + + resp.key := session; + resp.nonce := req.nonce; + resp.last-req := fetch_last_request_info(client); + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + omit resp.key-expiration; + + resp.sname := new_tkt.sname; + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + resp.realm := new_tkt.realm; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + encode body of reply into OCTET STRING; + + if (req.padata.authenticator.subkey) + resp.enc-part := encrypt OCTET STRING using use_etype, + req.padata.authenticator.subkey; + else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; + + send(resp); + +A.7. KRB_TGS_REP verification + + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key from + the response immediately */ + + if (req.padata.authenticator.subkey) + unencrypted part of resp := decode of decrypt of +resp.enc-part + using resp.enc-part.etype and subkey; + else unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and tgt's session key; + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + check authorization_data as necessary; + save_for_later(ticket,session,client,server,times,flags); + +A.8. Authenticator generation + + body.authenticator-vno := authenticator vno; /* = 5 */ + body.cname, body.crealm := client name; + if (supplying checksum) then + body.cksum := checksum; + endif + get system_time; + body.ctime, body.cusec := system_time; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.9. KRB_AP_REQ generation + + obtain ticket and session_key from cache; + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REQ */ + + if (desired(MUTUAL_AUTHENTICATION)) then + set packet.ap-options.MUTUAL-REQUIRED; + else + reset packet.ap-options.MUTUAL-REQUIRED; + endif + if (using session key for ticket) then + set packet.ap-options.USE-SESSION-KEY; + else + reset packet.ap-options.USE-SESSION-KEY; + endif + packet.ticket := ticket; /* ticket */ + generate authenticator; + encode authenticator into OCTET STRING; + encrypt OCTET STRING into packet.authenticator using session_key; + +A.10. KRB_AP_REQ verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REQ) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.ticket.tkt_vno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.ap_options.USE-SESSION-KEY is set) then + retrieve session key from ticket-granting ticket for + packet.ticket.{sname,srealm,enc-part.etype}; + else + retrieve service key for + packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; + endif + if (no_key_available) then + if (cannot_find_specified_skvno) then + error_out(KRB_AP_ERR_BADKEYVER); + else + error_out(KRB_AP_ERR_NOKEY); + endif + endif + decrypt packet.ticket.enc-part into decr_ticket using retrieved key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + decrypt packet.authenticator into decr_authenticator + using decr_ticket.key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + endif + if (decr_authenticator.{cname,crealm} != + decr_ticket.{cname,crealm}) then + error_out(KRB_AP_ERR_BADMATCH); + endif + if (decr_ticket.caddr is present) then + if (sender_address(packet) is not in decr_ticket.caddr) then + error_out(KRB_AP_ERR_BADADDR); + endif + elseif (application requires addresses) then + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(decr_authenticator.ctime, + decr_authenticator.cusec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then + error_out(KRB_AP_ERR_REPEAT); + endif + save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); + get system_time; + if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or + (decr_ticket.flags.INVALID is set)) then + /* it hasn't yet become valid */ + error_out(KRB_AP_ERR_TKT_NYV); + endif + if (system_time-decr_ticket.endtime > CLOCK_SKEW) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + if (decr_ticket.transited) then + /* caller may ignore the TRANSITED-POLICY-CHECKED and do + * check anyway */ + if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then + if (check_transited_field(decr_ticket.transited) then + error_out(KDC_AP_PATH_NOT_ACCPETED); + endif + endif + endif + /* caller must check decr_ticket.flags for any pertinent details */ + return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.11. KRB_AP_REP generation + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REP */ + + body.ctime := packet.ctime; + body.cusec := packet.cusec; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part; + +A.12. KRB_AP_REP verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REP) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + cleartext := decrypt(packet.enc-part) using ticket's session key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (cleartext.ctime != authenticator.ctime) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.cusec != authenticator.cusec) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.subkey is present) then + save cleartext.subkey for future use; + endif + if (cleartext.seq-number is present) then + save cleartext.seq-number for future verifications; + endif + return(AUTHENTICATION_SUCCEEDED); + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.13. KRB_SAFE generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_SAFE */ + + body.user-data := buffer; /* DATA */ + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + checksum.cksumtype := checksum type; + compute checksum over body; + checksum.checksum := checksum value; /* checksum.checksum */ + packet.cksum := checksum; + packet.safe-body := body; + +A.14. KRB_SAFE verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_SAFE) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.checksum.cksumtype is not both collision-proof + and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (safe_priv_common_checks_ok(packet)) then + set computed_checksum := checksum(packet.body); + if (computed_checksum != packet.checksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + return (packet, PACKET_IS_GENUINE); + else + return common_checks_error; + endif + +A.15. KRB_SAFE and KRB_PRIV common checks + + if (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (((packet.timestamp is present) and + (not in_clock_skew(packet.timestamp,packet.usec))) or + (packet.timestamp is not present and timestamp expected)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + + if (((packet.seq-number is present) and + ((not in_sequence(packet.seq-number)))) or + (packet.seq-number is not present and sequence expected)) then + error_out(KRB_AP_ERR_BADORDER); + endif + if (packet.timestamp not present and packet.seq-number + not present) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + save_identifier(packet.{timestamp,usec,s-address}, + sender_principal(packet)); + + return PACKET_IS_OK; + +A.16. KRB_PRIV generation + + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_PRIV */ + + packet.enc-part.etype := encryption type; + + body.user-data := buffer; + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher; + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.17. KRB_PRIV verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_PRIV) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + + if (safe_priv_common_checks_ok(cleartext)) then + return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); + else + return common_checks_error; + endif + +A.18. KRB_CRED generation + + invoke KRB_TGS; /* obtain tickets to be provided to peer */ + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_CRED */ + + for (tickets[n] in tickets to be forwarded) do + packet.tickets[n] = tickets[n].ticket; + done + + packet.enc-part.etype := encryption type; + + for (ticket[n] in tickets to be forwarded) do + body.ticket-info[n].key = tickets[n].session; + body.ticket-info[n].prealm = tickets[n].crealm; + body.ticket-info[n].pname = tickets[n].cname; + body.ticket-info[n].flags = tickets[n].flags; + body.ticket-info[n].authtime = tickets[n].authtime; + body.ticket-info[n].starttime = tickets[n].starttime; + body.ticket-info[n].endtime = tickets[n].endtime; + body.ticket-info[n].renew-till = tickets[n].renew-till; + body.ticket-info[n].srealm = tickets[n].srealm; + body.ticket-info[n].sname = tickets[n].sname; + body.ticket-info[n].caddr = tickets[n].caddr; + done + + get system_time; + body.timestamp, body.usec := system_time; + + if (using nonce) then + body.nonce := nonce; + endif + + if (using s-address) then + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + + body.s-address := sender host addresses; + endif + if (limited recipients) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher + using negotiated encryption key; + +A.19. KRB_CRED verification + + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_CRED) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if ((packet.r-address is present or required) and + (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(packet.timestamp,packet.usec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) then + error_out(KRB_AP_ERR_REPEAT); + endif + if (packet.nonce is required or present) and + (packet.nonce != expected-nonce) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + for (ticket[n] in tickets that were forwarded) do + save_for_later(ticket[n],key[n],principal[n], + server[n],times[n],flags[n]); + return + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +A.20. KRB_ERROR generation + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_ERROR */ + + get system_time; + packet.stime, packet.susec := system_time; + packet.realm, packet.sname := server name; + + if (client time available) then + packet.ctime, packet.cusec := client_time; + endif + packet.error-code := error code; + if (client name available) then + packet.cname, packet.crealm := client name; + endif + if (error text available) then + packet.e-text := error text; + endif + if (error data available) then + packet.e-data := error data; + endif + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +B. Definition of common authorization data elements + +This appendix contains the definitions of common authorization data +elements. These common authorization data elements are recursivly defined, +meaning the ad-data for these types will itself contain a sequence of +authorization data whose interpretation is affected by the encapsulating +element. Depending on the meaning of the encapsulating element, the +encapsulated elements may be ignored, might be interpreted as issued +directly by the KDC, or they might be stored in a separate plaintext part of +the ticket. The types of the encapsulating elements are specified as part of +the Kerberos specification because the behavior based on these values should +be understood across implementations whereas other elements need only be +understood by the applications which they affect. + +In the definitions that follow, the value of the ad-type for the element +will be specified in the subsection number, and the value of the ad-data +will be as shown in the ASN.1 structure that follows the subsection heading. + +B.1. If relevant + +AD-IF-RELEVANT AuthorizationData + +AD elements encapsulated within the if-relevant element are intended for +interpretation only by application servers that understand the particular +ad-type of the embedded element. Application servers that do not understand +the type of an element embedded within the if-relevant element may ignore +the uninterpretable element. This element promotes interoperability across +implementations which may have local extensions for authorization. + +B.2. Intended for server + +AD-INTENDED-FOR-SERVER SEQUENCE { + intended-server[0] SEQUENCE OF PrincipalName + elements[1] AuthorizationData +} + +AD elements encapsulated within the intended-for-server element may be +ignored if the application server is not in the list of principal names of +intended servers. Further, a KDC issuing a ticket for an application server +can remove this element if the application server is not in the list of +intended servers. + +Application servers should check for their principal name in the +intended-server field of this element. If their principal name is not found, +this element should be ignored. If found, then the encapsulated elements +should be evaluated in the same manner as if they were present in the top +level authorization data field. Applications and application servers that do +not implement this element should reject tickets that contain authorization +data elements of this type. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +B.3. Intended for application class + +AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] +SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements +encapsulated within the intended-for-application-class element may be +ignored if the application server is not in one of the named classes of +application servers. Examples of application server classes include +"FILESYSTEM", and other kinds of servers. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + +B.4. KDC Issued + +AD-KDCIssued SEQUENCE { + ad-checksum[0] Checksum, + i-realm[1] Realm OPTIONAL, + i-sname[2] PrincipalName OPTIONAL, + elements[3] AuthorizationData. +} + +ad-checksum + A checksum over the elements field using a cryptographic checksum + method that is identical to the checksum used to protect the ticket + itself (i.e. using the same hash function and the same encryption + algorithm used to encrypt the ticket) and using a key derived from the + same key used to protect the ticket. +i-realm, i-sname + The name of the issuing principal if different from the KDC itself. + This field would be used when the KDC can verify the authenticity of + elements signed by the issuing principal and it allows this KDC to + notify the application server of the validity of those elements. +elements + A sequence of authorization data elements issued by the KDC. + +The KDC-issued ad-data field is intended to provide a means for Kerberos +principal credentials to embed within themselves privilege attributes and +other mechanisms for positive authorization, amplifying the priveleges of +the principal beyond what can be done using a credentials without such an +a-data element. + +This can not be provided without this element because the definition of the +authorization-data field allows elements to be added at will by the bearer +of a TGT at the time that they request service tickets and elements may also +be added to a delegated ticket by inclusion in the authenticator. + +For KDC-issued elements this is prevented because the elements are signed by +the KDC by including a checksum encrypted using the server's key (the same +key used to encrypt the ticket - or a key derived from that key). Elements +encapsulated with in the KDC-issued element will be ignored by the +application server if this "signature" is not present. Further, elements +encapsulated within this element from a ticket granting ticket may be +interpreted by the KDC, and used as a basis according to policy for +including new signed elements within derivative tickets, but they will not +be copied to a derivative ticket directly. If they are copied directly to a +derivative ticket by a KDC that is not aware of this element, the signature +will not be correct for the application ticket elements, and the field will +be ignored by the application server. + +This element and the elements it encapulates may be safely ignored by +applications, application servers, and KDCs that do not implement this +element. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +B.5. And-Or + +AD-AND-OR SEQUENCE { + condition-count[0] INTEGER, + elements[1] AuthorizationData +} + +When restrictive AD elements encapsulated within the and-or element are +encountered, only the number specified in condition-count of the +encapsulated conditions must be met in order to satisfy this element. This +element may be used to implement an "or" operation by setting the +condition-count field to 1, and it may specify an "and" operation by setting +the condition count to the number of embedded elements. Application servers +that do not implement this element must reject tickets that contain +authorization data elements of this type. + +B.6. Mandatory ticket extensions + +AD-Mandatory-Ticket-Extensions Checksum + +An authorization data element of type mandatory-ticket-extensions specifies +a collision-proof checksum using the same hash algorithm used to protect the +integrity of the ticket itself. This checksum will be calculated over an +individual extension field. If there are more than one extension, multiple +Mandatory-Ticket-Extensions authorization data elements may be present, each +with a checksum for a different extension field. This restriction indicates +that the ticket should not be accepted if a ticket extension is not present +in the ticket for which the checksum does not match that checksum specified +in the authorization data element. Application servers that do not implement +this element must reject tickets that contain authorization data elements of +this type. + +B.7. Authorization Data in ticket extensions + +AD-IN-Ticket-Extensions Checksum + +An authorization data element of type in-ticket-extensions specifies a +collision-proof checksum using the same hash algorithm used to protect the +integrity of the ticket itself. This checksum is calculated over a separate +external AuthorizationData field carried in the ticket extensions. +Application servers that do not implement this element must reject tickets +that contain authorization data elements of this type. Application servers +that do implement this element will search the ticket extensions for +authorization data fields, calculate the specified checksum over each +authorization data field and look for one matching the checksum in this +in-ticket-extensions element. If not found, then the ticket must be +rejected. If found, the corresponding authorization data elements will be +interpreted in the same manner as if they were contained in the top level +authorization data field. + +Note that if multiple external authorization data fields are present in a +ticket, each will have a corresponding element of type in-ticket-extensions +in the top level authorization data field, and the external entries will be +linked to the corresponding element by their checksums. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +C. Definition of common ticket extensions + +This appendix contains the definitions of common ticket extensions. Support +for these extensions is optional. However, certain extensions have +associated authorization data elements that may require rejection of a +ticket containing an extension by application servers that do not implement +the particular extension. Other extensions have been defined beyond those +described in this specification. Such extensions are described elswhere and +for some of those extensions the reserved number may be found in the list of +constants. + +It is known that older versions of Kerberos did not support this field, and +that some clients will strip this field from a ticket when they parse and +then reassemble a ticket as it is passed to the application servers. The +presence of the extension will not break such clients, but any functionaly +dependent on the extensions will not work when such tickets are handled by +old clients. In such situations, some implementation may use alternate +methods to transmit the information in the extensions field. + +C.1. Null ticket extension + +TE-NullExtension OctetString -- The empty Octet String + +The te-data field in the null ticket extension is an octet string of lenght +zero. This extension may be included in a ticket granting ticket so that the +KDC can determine on presentation of the ticket granting ticket whether the +client software will strip the extensions field. + +C.2. External Authorization Data + +TE-ExternalAuthorizationData AuthorizationData + +The te-data field in the external authorization data ticket extension is +field of type AuthorizationData containing one or more authorization data +elements. If present, a corresponding authorization data element will be +present in the primary authorization data for the ticket and that element +will contain a checksum of the external authorization data ticket extension. + ------------------------------------------------------------------------ +[TM] Project Athena, Athena, and Kerberos are trademarks of the +Massachusetts Institute of Technology (MIT). No commercial use of these +trademarks may be made without prior written permission of MIT. + +[1] Note, however, that many applications use Kerberos' functions only upon +the initiation of a stream-based network connection. Unless an application +subsequently provides integrity protection for the data stream, the identity +verification applies only to the initiation of the connection, and does not +guarantee that subsequent messages on the connection originate from the same +principal. + +[2] Secret and private are often used interchangeably in the literature. In +our usage, it takes two (or more) to share a secret, thus a shared DES key +is a secret key. Something is only private when no one but its owner knows +it. Thus, in public key cryptosystems, one has a public and a private key. + +[3] Of course, with appropriate permission the client could arrange +registration of a separately-named prin- cipal in a remote realm, and engage +in normal exchanges with that realm's services. However, for even small +numbers of clients this becomes cumbersome, and more automatic methods as +described here are necessary. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +[4] Though it is permissible to request or issue tick- ets with no network +addresses specified. + +[5] The password-changing request must not be honored unless the requester +can provide the old password (the user's current secret key). Otherwise, it +would be possible for someone to walk up to an unattended ses- sion and +change another user's password. + +[6] To authenticate a user logging on to a local system, the credentials +obtained in the AS exchange may first be used in a TGS exchange to obtain +credentials for a local server. Those credentials must then be verified by a +local server through successful completion of the Client/Server exchange. + +[7] "Random" means that, among other things, it should be impossible to +guess the next session key based on knowledge of past session keys. This can +only be achieved in a pseudo-random number generator if it is based on +cryptographic principles. It is more desirable to use a truly random number +generator, such as one based on measurements of random physical phenomena. + +[8] Tickets contain both an encrypted and unencrypted portion, so cleartext +here refers to the entire unit, which can be copied from one message and +replayed in another without any cryptographic skill. + +[9] Note that this can make applications based on unreliable transports +difficult to code correctly. If the transport might deliver duplicated +messages, either a new authenticator must be generated for each retry, or +the application server must match requests and replies and replay the first +reply in response to a detected duplicate. + +[10] This is used for user-to-user authentication as described in [8]. + +[11] Note that the rejection here is restricted to authenticators from the +same principal to the same server. Other client principals communicating +with the same server principal should not be have their authenticators +rejected if the time and microsecond fields happen to match some other +client's authenticator. + +[12] In the Kerberos version 4 protocol, the timestamp in the reply was the +client's timestamp plus one. This is not necessary in version 5 because +version 5 messages are formatted in such a way that it is not possible to +create the reply by judicious message surgery (even in encrypted form) +without knowledge of the appropriate encryption keys. + +[13] Note that for encrypting the KRB_AP_REP message, the sub-session key is +not used, even if present in the Authenticator. + +[14] Implementations of the protocol may wish to provide routines to choose +subkeys based on session keys and random numbers and to generate a +negotiated key to be returned in the KRB_AP_REP message. + +[15]This can be accomplished in several ways. It might be known beforehand +(since the realm is part of the principal identifier), it might be stored in +a nameserver, or it might be obtained from a configura- tion file. If the +realm to be used is obtained from a nameserver, there is a danger of being +spoofed if the nameservice providing the realm name is not authenti- cated. +This might result in the use of a realm which has been compromised, and +would result in an attacker's ability to compromise the authentication of +the application server to the client. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +[16] If the client selects a sub-session key, care must be taken to ensure +the randomness of the selected sub- session key. One approach would be to +generate a random number and XOR it with the session key from the +ticket-granting ticket. + +[17] This allows easy implementation of user-to-user authentication [8], +which uses ticket-granting ticket session keys in lieu of secret server keys +in situa- tions where such secret keys could be easily comprom- ised. + +[18] For the purpose of appending, the realm preceding the first listed +realm is considered to be the null realm (""). + +[19] For the purpose of interpreting null subfields, the client's realm is +considered to precede those in the transited field, and the server's realm +is considered to follow them. + +[20] This means that a client and server running on the same host and +communicating with one another using the KRB_SAFE messages should not share +a common replay cache to detect KRB_SAFE replays. + +[21] The implementation of the Kerberos server need not combine the database +and the server on the same machine; it is feasible to store the principal +database in, say, a network name service, as long as the entries stored +therein are protected from disclosure to and modification by unauthorized +parties. However, we recommend against such strategies, as they can make +system management and threat analysis quite complex. + +[22] See the discussion of the padata field in section 5.4.2 for details on +why this can be useful. + +[23] Warning for implementations that unpack and repack data structures +during the generation and verification of embedded checksums: Because any +checksums applied to data structures must be checked against the original +data the length of bit strings must be preserved within a data structure +between the time that a checksum is generated through transmission to the +time that the checksum is verified. + +[24] It is NOT recommended that this time value be used to adjust the +workstation's clock since the workstation cannot reliably determine that +such a KRB_AS_REP actually came from the proper KDC in a timely manner. + +[25] Note, however, that if the time is used as the nonce, one must make +sure that the workstation time is monotonically increasing. If the time is +ever reset backwards, there is a small, but finite, probability that a nonce +will be reused. + +[27] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[29] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + +[31] An application code in the encrypted part of a message provides an +additional check that the message was decrypted properly. + + +Neuman, Ts'o, Kohl Expires: 25 December, +1999 + +INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, +1999 + +[32] If supported by the encryption method in use, an initialization vector +may be passed to the encryption procedure, in order to achieve proper cipher +chaining. The initialization vector might come from the last block of the +ciphertext from the previous KRB_PRIV message, but it is the application's +choice whether or not to use such an initialization vector. If left out, the +default initialization vector for the encryption algorithm will be used. + +[33] This prevents an attacker who generates an incorrect AS request from +obtaining verifiable plaintext for use in an off-line password guessing +attack. + +[35] In the above specification, UNTAGGED OCTET STRING(length) is the +notation for an octet string with its tag and length removed. It is not a +valid ASN.1 type. The tag bits and length must be removed from the +confounder since the purpose of the confounder is so that the message starts +with random data, but the tag and its length are fixed. For other fields, +the length and tag would be redundant if they were included because they are +specified by the encryption type. [36] The ordering of the fields in the +CipherText is important. Additionally, messages encoded in this format must +include a length as part of the msg-seq field. This allows the recipient to +verify that the message has not been truncated. Without a length, an +attacker could use a chosen plaintext attack to generate a message which +could be truncated, while leaving the checksum intact. Note that if the +msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length +is part of that encoding. + +[37] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[38] In some cases, it may be necessary to use a different "mix-in" string +for compatibility reasons; see the discussion of padata in section 5.4.2. + +[39] A variant of the key is used to limit the use of a key to a particular +function, separating the functions of generating a checksum from other +encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 +was chosen because it maintains key parity. The properties of DES precluded +the use of the complement. The same constant is used for similar purpose in +the Message Integrity Check in the Privacy Enhanced Mail standard. + +[40] This error carries additional information in the e- data field. The +contents of the e-data field for this message is described in section 5.9.1. diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt new file mode 100644 index 0000000..e76a0e4 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt @@ -0,0 +1,250 @@ +INTERNET-DRAFT Ken Hornstein +<draft-ietf-cat-krb-dns-locate-00.txt> NRL +June 21, 1999 Jeffrey Altman +Expires: December 21, 1999 Columbia University + + Distributing Kerberos KDC and Realm Information with DNS + +Status of this Memo + + This document is an Internet-Draft and is in full conformance with + all provisions of Section 10 of RFC2026. + + 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. + + Distribution of this memo is unlimited. It is filed as <draft-ietf- + cat-krb-dns-locate-00.txt>, and expires on December 21, 1999. Please + send comments to the authors. + +Abstract + + Neither the Kerberos V5 protocol [RFC1510] nor the Kerberos V4 proto- + col [RFC????] describe any mechanism for clients to learn critical + configuration information necessary for proper operation of the pro- + tocol. Such information includes the location of Kerberos key dis- + tribution centers or a mapping between DNS domains and Kerberos + realms. + + Current Kerberos implementations generally store such configuration + information in a file on each client machine. Experience has shown + this method of storing configuration information presents problems + with out-of-date information and scaling problems, especially when + +Hornstein, Altman [Page 1] + +RFC DRAFT June 21, 1999 + + using cross-realm authentication. + + This memo describes a method for using the Domain Name System + [RFC1035] for storing such configuration information. Specifically, + methods for storing KDC location and hostname/domain name to realm + mapping information are discussed. + +Overview - KDC location information + + KDC location information is to be stored using the DNS SRV RR [RFC + 2052]. The format of this RR is as follows: + + Service.Proto.Realm TTL Class SRV Priority Weight Port Target + + The Service name for Kerberos is always "_kerberos". + + The Proto can be either "_udp" or "_tcp". If these records are to be + used, a "_udp" record MUST be included. If the Kerberos implementa- + tion supports TCP transport, a "_tcp" record SHOULD be included. + + The Realm is the Kerberos realm that this record corresponds to. + + TTL, Class, SRV, Priority, Weight, Port, and Target have the standard + meaning as defined in RFC 2052. + +Example - KDC location information + + These are DNS records for a Kerberos realm ASDF.COM. It has two Ker- + beros servers, kdc1.asdf.com and kdc2.asdf.com. Queries should be + directed to kdc1.asdf.com first as per the specified priority. + Weights are not used in these records. + + _kerberos._udp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com. + _kerberos._udp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com. + +Overview - KAdmin location information + + Kadmin location information is to be stored using the DNS SRV RR [RFC + 2052]. The format of this RR is as follows: + + Service.Proto.Realm TTL Class SRV Priority Weight Port Target + + The Service name for Kadmin is always "_kadmin". + + The Proto can be either "_udp" or "_tcp". If these records are to be + used, a "_tcp" record MUST be included. If the Kadmin implementation + supports UDP transport, a "_udp" record SHOULD be included. + +Hornstein, Altman [Page 2] + +RFC DRAFT June 21, 1999 + + The Realm is the Kerberos realm that this record corresponds to. + + TTL, Class, SRV, Priority, Weight, Port, and Target have the standard + meaning as defined in RFC 2052. + +Example - Kadmin location information + + These are DNS records for a Kerberos realm ASDF.COM. It has one Kad- + min server, kdc1.asdf.com. + + _kadmin._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com. + +Overview - Hostname/domain name to Kerberos realm mapping + + Information on the mapping of DNS hostnames and domain names to Ker- + beros realms is stored using DNS TXT records [RFC 1035]. These + records have the following format. + + Service.Name TTL Class TXT Realm + + The Service field is always "_kerberos", and prefixes all entries of + this type. + + The Name is a DNS hostname or domain name. This is explained in + greater detail below. + + TTL, Class, and TXT have the standard DNS meaning as defined in RFC + 1035. + + The Realm is the data for the TXT RR, and consists simply of the Ker- + beros realm that corresponds to the Name specified. + + When a Kerberos client wishes to utilize a host-specific service, it + will perform a DNS TXT query, using the hostname in the Name field of + the DNS query. If the record is not found, the first label of the + name is stripped and the query is retried. + + Compliant implementations MUST query the full hostname and the most + specific domain name (the hostname with the first label removed). + Compliant implementations SHOULD try stripping all subsequent labels + until a match is found or the Name field is empty. + +Example - Hostname/domain name to Kerberos realm mapping + + For the previously mentioned ASDF.COM realm and domain, some sample + records might be as follows: + + _kerberos.asdf.com. IN TXT "ASDF.COM" + +Hornstein, Altman [Page 3] + +RFC DRAFT June 21, 1999 + + _kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM" + _kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM" + + Let us suppose that in this case, a Kerberos client wishes to use a + Kerberized service on the host foo.asdf.com. It would first query: + + _kerberos.foo.asdf.com. IN TXT + + Finding no match, it would then query: + + _kerberos.asdf.com. IN TXT + + And find an answer of ASDF.COM. This would be the realm that + foo.asdf.com resides in. + + If another Kerberos client wishes to use a Kerberized service on the + host salesserver.asdf.com, it would query: + + _kerberos.salesserver.asdf.com IN TXT + + And find an answer of SALES.ASDF.COM. + +Security considerations + + As DNS is deployed today, it is an unsecure service. Thus the infor- + mation returned by it cannot be trusted. However, the use of DNS to + store this configuration information does not introduce any new secu- + rity risks to the Kerberos protocol. + + Current practice is to use hostnames to indicate KDC hosts (stored in + some implementation-dependent location, but generally a local config + file). These hostnames are vulnerable to the standard set of DNS + attacks (denial of service, spoofed entries, etc). The design of the + Kerberos protocol limits attacks of this sort to denial of service. + However, the use of SRV records does not change this attack in any + way. They have the same vulnerabilities that already exist in the + common practice of using hostnames for KDC locations. + + The same holds true for the TXT records used to indicate the domain + name to realm mapping. Current practice is to configure these map- + pings locally. But this again is vulnerable to spoofing via CNAME + records that point to hosts in other domains. This has the same + effect as a spoofed TXT record. + + While the described protocol does not introduce any new security + risks to the best of our knowledge, implementations SHOULD provide a + way of specifying this information locally without the use of DNS. + However, to make this feature worthwhile a lack of any configuration + +Hornstein, Altman [Page 4] + +RFC DRAFT June 21, 1999 + + information on a client should be interpretted as permission to use + DNS. + +Expiration + + This Internet-Draft expires on December 21, 1999. + +References + + [RFC1510] + The Kerberos Network Authentication System; Kohl, Newman; Sep- + tember 1993. + + [RFC1035] + Domain Names - Implementation and Specification; Mockapetris; + November 1987 + + [RFC2052] + A DNS RR for specifying the location of services (DNS SRV); Gul- + brandsen, Vixie; October 1996 + +Authors' Addresses + + Ken Hornstein + US Naval Research Laboratory + Bldg A-49, Room 2 + 4555 Overlook Avenue + Washington DC 20375 USA + + Phone: +1 (202) 404-4765 + EMail: kenh@cmf.nrl.navy.mil + + Jeffrey Altman + The Kermit Project + Columbia University + 612 West 115th Street #716 + New York NY 10025-7799 USA + + Phone: +1 (212) 854-1344 + EMail: jaltman@columbia.edu + +Hornstein, Altman [Page 5] diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt b/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt new file mode 100644 index 0000000..885cf49 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt @@ -0,0 +1,3415 @@ +FTPEXT Working Group R. Elz +Internet Draft University of Melbourne +Expiration Date: April 2000 + P. Hethmon + Hethmon Brothers + + October 1999 + + + Extensions to FTP + + + draft-ietf-ftpext-mlst-08.txt + +Status of this Memo + + This document is an Internet-Draft and is NOT offered in accordance + with Section 10 of RFC2026, and the author does not provide the IETF + with any rights other than to publish as an Internet-Draft. + + 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. + + To view the list Internet-Draft Shadow Directories, see + http://www.ietf.org/shadow.html. + + This entire section has been prepended to this document automatically + during formatting without any direct involvement by the author(s) of + this draft. + + + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 1] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +Abstract + + In order to overcome the problems caused by the undefined format of + the current FTP LIST command output, a new command is needed to + transfer standardized listing information from Server-FTP to User- + FTP. Commands to enable this are defined in this document. + + In order to allow consenting clients and servers to interact more + freely, a quite basic, and optional, virtual file store structure is + defined. + + This proposal also extends the FTP protocol to allow character sets + other than US-ASCII[1] by allowing the transmission of 8-bit + characters and the recommended use of UTF-8[2] encoding. + + Much implemented, but long undocumented, mechanisms to permit + restarts of interrupted data transfers in STREAM mode, are also + included here. + + Lastly, the HOST command has been added to allow a style of "virtual + site" to be constructed. + + Changed in this version of this document: Minor corrections as + discussed on the mailing list, including fixing many typographical + errors; Additional examples. This paragraph will be deleted from the + final version of this document. + + + + + + + + + + + + + + + + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 2] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + + +Table of Contents + + Abstract ................................................ 2 + 1 Introduction ............................................ 4 + 2 Document Conventions .................................... 4 + 2.1 Basic Tokens ............................................ 5 + 2.2 Pathnames ............................................... 5 + 2.3 Times ................................................... 7 + 2.4 Server Replies .......................................... 8 + 3 File Modification Time (MDTM) ........................... 8 + 3.1 Syntax .................................................. 9 + 3.2 Error responses ......................................... 9 + 3.3 FEAT response for MDTM .................................. 9 + 3.4 MDTM Examples ........................................... 10 + 4 File SIZE ............................................... 11 + 4.1 Syntax .................................................. 11 + 4.2 Error responses ......................................... 11 + 4.3 FEAT response for SIZE .................................. 12 + 4.4 Size Examples ........................................... 12 + 5 Restart of Interrupted Transfer (REST) .................. 13 + 5.1 Restarting in STREAM Mode ............................... 13 + 5.2 Error Recovery and Restart .............................. 14 + 5.3 Syntax .................................................. 14 + 5.4 FEAT response for REST .................................. 16 + 5.5 REST Example ............................................ 16 + 6 Virtual FTP servers ..................................... 16 + 6.1 The HOST command ........................................ 18 + 6.2 Syntax of the HOST command .............................. 18 + 6.3 HOST command semantics .................................. 19 + 6.4 HOST command errors ..................................... 21 + 6.5 FEAT response for HOST command .......................... 22 + 7 A Trivial Virtual File Store (TVFS) ..................... 23 + 7.1 TVFS File Names ......................................... 23 + 7.2 TVFS Path Names ......................................... 24 + 7.3 FEAT Response for TVFS .................................. 25 + 7.4 OPTS for TVFS ........................................... 26 + 7.5 TVFS Examples ........................................... 26 + 8 Listings for Machine Processing (MLST and MLSD) ......... 28 + 8.1 Format of MLSx Requests ................................. 29 + 8.2 Format of MLSx Response ................................. 29 + 8.3 Filename encoding ....................................... 32 + 8.4 Format of Facts ......................................... 33 + 8.5 Standard Facts .......................................... 33 + 8.6 System Dependent and Local Facts ........................ 41 + 8.7 MLSx Examples ........................................... 42 + 8.8 FEAT response for MLSx .................................. 50 + + + +Elz & Hethmon [Expires April 2000] [Page 3] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + 8.9 OPTS parameters for MLST ................................ 51 + 9 Impact On Other FTP Commands ............................ 55 + 10 Character sets and Internationalization ................. 56 + 11 IANA Considerations ..................................... 56 + 11.1 The OS specific fact registry ........................... 56 + 11.2 The OS specific filetype registry ....................... 57 + 12 Security Considerations ................................. 57 + 13 References .............................................. 58 + Acknowledgments ......................................... 59 + Copyright ............................................... 60 + Editors' Addresses ...................................... 60 + + + + +1. Introduction + + This document amends the File Transfer Protocol (FTP) [3]. Five new + commands are added: "SIZE", "HOST", "MDTM", "MLST", and "MLSD". The + existing command "REST" is modified. Of those, the "SIZE" and "MDTM" + commands, and the modifications to "REST" have been in wide use for + many years. The others are new. + + These commands allow a client to restart an interrupted transfer in + transfer modes not previously supported in any documented way, to + support the notion of virtual hosts, and to obtain a directory + listing in a machine friendly, predictable, format. + + An optional structure for the server's file store (NVFS) is also + defined, allowing servers that support such a structure to convey + that information to clients in a standard way, thus allowing clients + more certainty in constructing and interpreting path names. + +2. Document Conventions + + This document makes use of the document conventions defined in BCP14 + [4]. That provides the interpretation of capitalized imperative + words like MUST, SHOULD, etc. + + This document also uses notation defined in STD 9 [3]. In + particular, the terms "reply", "user", "NVFS", "file", "pathname", + "FTP commands", "DTP", "user-FTP process", "user-PI", "user-DTP", + "server-FTP process", "server-PI", "server-DTP", "mode", "type", + "NVT", "control connection", "data connection", and "ASCII", are all + used here as defined there. + + Syntax required is defined using the Augmented BNF defined in [5]. + Some general ABNF definitions are required throughout the document, + + + +Elz & Hethmon [Expires April 2000] [Page 4] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + those will be defined later in this section. At first reading, it + may be wise to simply recall that these definitions exist here, and + skip to the next section. + +2.1. Basic Tokens + + This document imports the core definitions given in Appendix A of + [5]. There definitions will be found for basic ABNF elements like + ALPHA, DIGIT, SP, etc. To that, the following terms are added for + use in this document. + + TCHAR = VCHAR / SP / HTAB ; visible plus white space + RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / + "@" / "#" / "$" / "%" / "^" / + "&" / "(" / ")" / "-" / "_" / + "+" / "?" / "/" / "\" / "'" / + DQUOTE ; <"> -- double quote character (%x22) + + The VCHAR (from [5]), TCHAR, and RCHAR types give basic character + types from varying sub-sets of the ASCII character set for use in + various commands and responses. + + token = 1*RCHAR + + A "token" is a string whose precise meaning depends upon the context + in which it is used. In some cases it will be a value from a set of + possible values maintained elsewhere. In others it might be a string + invented by one party to an FTP conversation from whatever sources it + finds relevant. + + Note that in ABNF, string literals are case insensitive. That + convention is preserved in this document, and implies that FTP + commands added by this specification have names that can be + represented in any case. That is, "MDTM" is the same as "mdtm", + "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is + case sensitive. That implies that a "token" is a case sensitive + value. That implication is correct. + +2.2. Pathnames + + Various FTP commands take pathnames as arguments, or return pathnames + in responses. When the MLST command is supported, as indicated in + the response to the FEAT command [6], pathnames are to be transferred + in one of the following two formats. + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 5] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + pathname = utf-8-name / raw + utf-8-name = <a UTF-8 encoded Unicode string> + raw = <any string not being a valid UTF-8 encoding> + + Which format is used is at the option of the user-PI or server-PI + sending the pathname. UTF-8 encodings [2] contain enough internal + structure that it is always, in practice, possible to determine + whether a UTF-8 or raw encoding has been used, in those cases where + it matters. While it is useful for the user-PI to be able to + correctly display a pathname received from the server-PI to the user, + it is far more important for the user-PI to be able to retain and + retransmit the identical pathname when required. Implementations are + advised against converting a UTF-8 pathname to a local encoding, and + then attempting to invert the encoding later. Note that ASCII is a + subset of UTF-8. + + Unless otherwise specified, the pathname is terminated by the CRLF + that terminates the FTP command, or by the CRLF that ends a reply. + Any trailing spaces preceding that CRLF form part of the name. + Exactly one space will precede the pathname and serve as a separator + from the preceding syntax element. Any additional spaces form part + of the pathname. See [7] for a fuller explanation of the character + encoding issues. All implementations supporting MLST MUST support + [7]. + + Implementations should also beware that the control connection uses + Telnet NVT conventions [8], and that the Telnet IAC character, if + part of a pathname sent over the control connection, MUST be + correctly escaped as defined by the Telnet protocol. + + Implementors should also be aware that although Telnet NVT + conventions are used over the control connections, Telnet option + negotiation MUST NOT be attempted. See section 4.1.2.12 of [9]. + +2.2.1. Pathname Syntax + + Except where TVFS is supported (see section 7) this specification + imposes no syntax upon pathnames. Nor does it restrict the character + set from which pathnames are created. This does not imply that the + NVFS is required to make sense of all possible pathnames. Server-PIs + may restrict the syntax of valid pathnames in their NVFS in any + manner appropriate to their implementation or underlying file system. + Similarly, a server-PI may parse the pathname, and assign meaning to + the components detected. + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 6] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +2.2.2. Wildcarding + + For the commands defined in this specification, all pathnames are to + be treated literally. That is, for a pathname given as a parameter + to a command, the file whose name is identical to the pathname given + is implied. No characters from the pathname may be treated as + special or "magic", thus no pattern matching (other than for exact + equality) between the pathname given and the files present in the + NVFS of the Server-FTP is permitted. + + Clients that desire some form of pattern matching functionality must + obtain a listing of the relevant directory, or directories, and + implement their own filename selection procedures. + +2.3. Times + + The syntax of a time value is: + + time-val = 14DIGIT [ "." 1*DIGIT ] + + The leading, mandatory, fourteen digits are to be interpreted as, in + order from the leftmost, four digits giving the year, with a range of + 1000-9999, two digits giving the month of the year, with a range of + 01-12, two digits giving the day of the month, with a range of 01-31, + two digits giving the hour of the day, with a range of 00-23, two + digits giving minutes past the hour, with a range of 00-59, and + finally, two digits giving seconds past the minute, with a range of + 00-60 (with 60 being used only at a leap second). Years in the tenth + century, and earlier, cannot be expressed. This is not considered a + serious defect of the protocol. + + The optional digits, which are preceded by a period, give decimal + fractions of a second. These may be given to whatever precision is + appropriate to the circumstance, however implementations MUST NOT add + precision to time-vals where that precision does not exist in the + underlying value being transmitted. + + Symbolically, a time-val may be viewed as + + YYYYMMDDHHMMSS.sss + + The "." and subsequent digits ("sss") are optional. However the "." + MUST NOT appear unless at least one following digit also appears. + + Time values are always represented in UTC (GMT), and in the Gregorian + calendar regardless of what calendar may have been in use at the date + and time indicated at the location of the server-PI. + + + + +Elz & Hethmon [Expires April 2000] [Page 7] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The technical differences between GMT, TAI, UTC, UT1, UT2, etc, are + not considered here. A server-FTP process should always use the same + time reference, so the times it returns will be consistent. Clients + are not expected to be time synchronized with the server, so the + possible difference in times that might be reported by the different + time standards is not considered important. + +2.4. Server Replies + + Section 4.2 of [3] defines the format and meaning of replies by the + server-PI to FTP commands from the user-PI. Those reply conventions + are used here without change. + + error-response = error-code SP *TCHAR CRLF + error-code = ("4" / "5") 2DIGIT + + Implementors should note that the ABNF syntax (which was not used in + [3]) used in this document, and other FTP related documents, + sometimes shows replies using the one line format. Unless otherwise + explicitly stated, that is not intended to imply that multi-line + responses are not permitted. Implementors should assume that, unless + stated to the contrary, any reply to any FTP command (including QUIT) + may be of the multi-line format described in [3]. + + Throughout this document, replies will be identified by the three + digit code that is their first element. Thus the term "500 reply" + means a reply from the server-PI using the three digit code "500". + +3. File Modification Time (MDTM) + + The FTP command, MODIFICATION TIME (MDTM), can be used to determine + when a file in the server NVFS was last modified. This command has + existed in many FTP servers for many years, as an adjunct to the REST + command for STREAM mode, thus is widely available. However, where + supported, the "modify" fact which can be provided in the result from + the new MLST command is recommended as a superior alternative. + + When attempting to restart a RETRieve, if the User-FTP makes use of + the MDTM command, or "modify" fact, it can check and see if the + modification time of the source file is more recent than the + modification time of the partially transferred file. If it is, then + most likely the source file has changed and it would be unsafe to + restart the previously incomplete file transfer. + + When attempting to restart a STORe, the User FTP can use the MDTM + command to discover the modification time of the partially + transferred file. If it is older than the modification time of the + file that is about to be STORed, then most likely the source file has + + + +Elz & Hethmon [Expires April 2000] [Page 8] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + changed and it would be unsafe to restart the file transfer. + + Note that using MLST (described below) where available, can provide + this information, and much more, thus giving an even better + indication that a file has changed, and that restarting a transfer + would not give valid results. + + Note that this is applicable to any RESTart attempt, regardless of + the mode of the file transfer. + +3.1. Syntax + + The syntax for the MDTM command is: + + mdtm = "MdTm" SP pathname CRLF + + As with all FTP commands, the "MDTM" command label is interpreted in + a case insensitive manner. + + The "pathname" specifies an object in the NVFS which may be the + object of a RETR command. Attempts to query the modification time of + files that are unable to be retrieved generate undefined responses. + + The server-PI will respond to the MDTM command with a 213 reply + giving the last modification time of the file whose pathname was + supplied, or a 550 reply if the file does not exist, the modification + time is unavailable, or some other error has occurred. + + mdtm-response = "213" SP time-val CRLF / + error-response + +3.2. Error responses + + Where the command is correctly parsed, but the modification time is + not available, either because the pathname identifies no existing + entity, or because the information is not available for the entity + named, then a 550 reply should be sent. Where the command cannot be + correctly parsed, a 500 or 501 reply should be sent, as specified in + [3]. + +3.3. FEAT response for MDTM + + When replying to the FEAT command [6], an FTP server process that + supports the MDTM command MUST include a line containing the single + word "MDTM". This MAY be sent in upper or lower case, or a mixture + of both (it is case insensitive) but SHOULD be transmitted in upper + case only. That is, the response SHOULD be + + + + +Elz & Hethmon [Expires April 2000] [Page 9] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + C> Feat + S> 211- <any descriptive text> + S> ... + S> MDTM + S> ... + S> 211 End + + The ellipses indicate place holders where other features may be + included, and are not required. The one space indentation of the + feature lines is mandatory [6]. + +3.4. MDTM Examples + + If we assume the existence of three files, A B and C, and a directory + D, and no other files at all, then the MTDM command may behave as + indicated. The "C>" lines are commands from user-PI to server-PI, + the "S>" lines are server-PI replies. + + C> MDTM A + S> 213 19980615100045.014 + C> MDTM B + S> 213 19980615100045.014 + C> MDTM C + S> 213 19980705132316 + C> MDTM D + S> 550 D is not retrievable + C> MDTM E + S> 550 No file named "E" + C> mdtm file6 + S> 213 19990929003355 + C> MdTm 19990929043300 File6 + S> 213 19991005213102 + C> MdTm 19990929043300 file6 + S> 550 19990929043300 file6: No such file or directory. + + From that we can conclude that both A and B were last modified at the + same time (to the nearest millisecond), and that C was modified 21 + days and several hours later. + + The times are in GMT, so file A was modified on the 15th of June, + 1998, at approximately 11am in London (summer time was then in + effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New + York. All of those represent the same absolute time of course. The + location where the file was modified, and consequently the local wall + clock time at that location, is not available. + + There is no file named "E" in the current directory, but there are + files named both "file6" and "19990929043300 File6". The + + + +Elz & Hethmon [Expires April 2000] [Page 10] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + modification times of those files were obtained. There is no file + named "19990929043300 file6". + +4. File SIZE + + The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer + size of a file from the server-FTP process. That is, the exact + number of octets (8 bit bytes) which would be transmitted over the + data connection should that file be transmitted. This value will + change depending on the current STRUcture, MODE and TYPE of the data + connection, or a data connection which would be created were one + created now. Thus, the result of the SIZE command is dependent on + the currently established STRU, MODE and TYPE parameters. + + The SIZE command returns how many octets would be transferred if the + file were to be transferred using the current transfer structure, + mode and type. This command is normally used in conjunction with the + RESTART (REST) command. The server-PI might need to read the + partially transferred file, do any appropriate conversion, and count + the number of octets that would be generated when sending the file in + order to correctly respond to this command. Estimates of the file + transfer size MUST NOT be returned, only precise information is + acceptable. + +4.1. Syntax + + The syntax of the SIZE command is: + + size = "Size" SP pathname CRLF + + The server-PI will respond to the SIZE command with a 213 reply + giving the transfer size of the file whose pathname was supplied, or + an error response if the file does not exist, the size is + unavailable, or some other error has occurred. The value returned is + in a format suitable for use with the RESTART (REST) command for mode + STREAM, provided the transfer mode and type are not altered. + + size-response = "213" SP 1*DIGIT CRLF / + error-response + +4.2. Error responses + + Where the command is correctly parsed, but the size is not available, + either because the pathname identifies no existing entity, or because + the entity named cannot be transferred in the current MODE and TYPE + (or at all), then a 550 reply should be sent. Where the command + cannot be correctly parsed, a 500 or 501 reply should be sent, as + specified in [3]. + + + +Elz & Hethmon [Expires April 2000] [Page 11] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +4.3. FEAT response for SIZE + + When replying to the FEAT command [6], an FTP server process that + supports the SIZE command MUST include a line containing the single + word "SIZE". This word is case insensitive, and MAY be sent in any + mixture of upper or lower case, however it SHOULD be sent in upper + case. That is, the response SHOULD be + + C> FEAT + S> 211- <any descriptive text> + S> ... + S> SIZE + S> ... + S> 211 END + + The ellipses indicate place holders where other features may be + included, and are not required. The one space indentation of the + feature lines is mandatory [6]. + +4.4. Size Examples + + Consider a text file "Example" stored on a Unix(TM) server where each + end of line is represented by a single octet. Assume the file + contains 112 lines, and 1830 octets total. Then the SIZE command + would produce: + + C> TYPE I + S> 200 Type set to I. + C> size Example + S> 213 1830 + C> TYPE A + S> 200 Type set to A. + C> Size Example + S> 213 1942 + + Notice that with TYPE=A the SIZE command reports an extra 112 octets. + Those are the extra octets that need to be inserted, one at the end + of each line, to provide correct end of line semantics for a transfer + using TYPE=A. Other systems might need to make other changes to the + transfer format of files when converting between TYPEs and MODEs. + The SIZE command takes all of that into account. + + Since calculating the size of a file with this degree of precision + may take considerable effort on the part of the server-PI, user-PIs + should not used this command unless this precision is essential (such + as when about to restart an interrupted transfer). For other uses, + the "Size" fact of the MLST command (see section 8.5.7) ought be + requested. + + + +Elz & Hethmon [Expires April 2000] [Page 12] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +5. Restart of Interrupted Transfer (REST) + + To avoid having to resend the entire file if the file is only + partially transferred, both sides need some way to be able to agree + on where in the data stream to restart the data transfer. + + The FTP specification [3] includes three modes of data transfer, + Stream, Block and Compressed. In Block and Compressed modes, the + data stream that is transferred over the data connection is + formatted, allowing the embedding of restart markers into the stream. + The sending DTP can include a restart marker with whatever + information it needs to be able to restart a file transfer at that + point. The receiving DTP can keep a list of these restart markers, + and correlate them with how the file is being saved. To restart the + file transfer, the receiver just sends back that last restart marker, + and both sides know how to resume the data transfer. Note that there + are some flaws in the description of the restart mechanism in RFC 959 + [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections. + +5.1. Restarting in STREAM Mode + + In Stream mode, the data connection contains just a stream of + unformatted octets of data. Explicit restart markers thus cannot be + inserted into the data stream, they would be indistinguishable from + data. For this reason, the FTP specification [3] did not provide the + ability to do restarts in stream mode. However, there is not really + a need to have explicit restart markers in this case, as restart + markers can be implied by the octet offset into the data stream. + + Because the data stream defines the file in STREAM mode, a different + data stream would represent a different file. Thus, an offset will + always represent the same position within a file. On the other hand, + in other modes than STREAM, the same file can be transferred using + quite different octet sequences, and yet be reconstructed into the + one identical file. Thus an offset into the data stream in transfer + modes other than STREAM would not give an unambiguous restart point. + + If the data representation TYPE is IMAGE, and the STRUcture is File, + for many systems the file will be stored exactly in the same format + as it is sent across the data connection. It is then usually very + easy for the receiver to determine how much data was previously + received, and notify the sender of the offset where the transfer + should be restarted. In other representation types and structures + more effort will be required, but it remains always possible to + determine the offset with finite, but perhaps non-negligible, effort. + In the worst case an FTP process may need to open a data connection + to itself, set the appropriate transfer type and structure, and + actually transmit the file, counting the transmitted octets. + + + +Elz & Hethmon [Expires April 2000] [Page 13] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + If the user-FTP process is intending to restart a retrieve, it will + directly calculate the restart marker, and send that information in + the RESTart command. However, if the user-FTP process is intending + to restart sending the file, it needs to be able to determine how + much data was previously sent, and correctly received and saved. A + new FTP command is needed to get this information. This is the + purpose of the SIZE command, as documented in section 4. + +5.2. Error Recovery and Restart + + STREAM MODE transfers with FILE STRUcture may be restarted even + though no restart marker has been transferred in addition to the data + itself. This is done by using the SIZE command, if needed, in + combination with the RESTART (REST) command, and one of the standard + file transfer commands. + + When using TYPE ASCII or IMAGE, the SIZE command will return the + number of octets that would actually be transferred if the file were + to be sent between the two systems. I.e. with type IMAGE, the SIZE + normally would be the number of octets in the file. With type ASCII, + the SIZE would be the number of octets in the file including any + modifications required to satisfy the TYPE ASCII CR-LF end of line + convention. + +5.3. Syntax + + The syntax for the REST command when the current transfer mode is + STREAM is: + + rest = "Rest" SP 1*DIGIT CRLF + + The numeric value gives the number of octets of the immediately + following transfer to not actually send, effectively causing the + transmission to be restarted at a later point. A value of zero + effectively disables restart, causing the entire file to be + transmitted. The server-PI will respond to the REST command with a + 350 reply, indicating that the REST parameter has been saved, and + that another command, which should be either RETR or STOR, should + then follow to complete the restart. + + rest-response = "350" SP *TCHAR CRLF / + error-response + + Server-FTP processes may permit transfer commands other than RETR and + STOR, such as APPE and STOU, to complete a restart, however, this is + not recommended. STOU (store unique) is undefined in this usage, as + storing the remainder of a file into a unique filename is rarely + going to be useful. If APPE (append) is permitted, it MUST act + + + +Elz & Hethmon [Expires April 2000] [Page 14] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + identically to STOR when a restart marker has been set. That is, in + both cases, octets from the data connection are placed into the file + at the location indicated by the restart marker value. + + The REST command is intended to complete a failed transfer. Use with + RETR is comparatively well defined in all cases, as the client bears + the responsibility of merging the retrieved data with the partially + retrieved file. If it chooses to use the data obtained other than to + complete an earlier transfer, or if it chooses to re-retrieve data + that had been retrieved before, that is its choice. With STOR, + however, the server must insert the data into the file named. The + results are undefined if a client uses REST to do other than restart + to complete a transfer of a file which had previously failed to + completely transfer. In particular, if the restart marker set with a + REST command is not at the end of the data currently stored at the + server, as reported by the server, or if insufficient data are + provided in a STOR that follows a REST to extend the destination file + to at least its previous size, then the effects are undefined. + + The REST command must be the last command issued before the data + transfer command which is to cause a restarted rather than complete + file transfer. The effect of issuing a REST command at any other + time is undefined. The server-PI may react to a badly positioned + REST command by issuing an error response to the following command, + not being a restartable data transfer command, or it may save the + restart value and apply it to the next data transfer command, or it + may silently ignore the inappropriate restart attempt. Because of + this, a user-PI that has issued a REST command, but which has not + successfully transmitted the following data transfer command for any + reason, should send another REST command before the next data + transfer command. If that transfer is not to be restarted, then + "REST 0" should be issued. + + An error-response will follow a REST command only when the server + does not implement the command, or the restart marker value is + syntactically invalid for the current transfer mode. That is, in + STREAM mode, if something other than one or more digits appears in + the parameter to the REST command. Any other errors, including such + problems as restart marker out of range, should be reported when the + following transfer command is issued. Such errors will cause that + transfer request to be rejected with an error indicating the invalid + restart attempt. + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 15] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +5.4. FEAT response for REST + + Where a server-FTP process supports RESTart in STREAM mode, as + specified here, it MUST include in the response to the FEAT command + [6], a line containing exactly the string "REST STREAM". This string + is not case sensitive, but SHOULD be transmitted in upper case. + Where REST is not supported at all, or supported only in block or + compressed modes, the REST line MUST NOT be included in the FEAT + response. Where required, the response SHOULD be + + C> feat + S> 211- <any descriptive text> + S> ... + S> REST STREAM + S> ... + S> 211 end + + The ellipses indicate place holders where other features may be + included, and are not required. The one space indentation of the + feature lines is mandatory [6]. + +5.5. REST Example + + Assume that the transfer of a largish file has previously been + interrupted after 802816 octets had been received, that the previous + transfer was with TYPE=I, and that it has been verified that the file + on the server has not since changed. + + C> TYPE I + S> 200 Type set to I. + C> PORT 127,0,0,1,15,107 + S> 200 PORT command successful. + C> REST 802816 + S> 350 Restarting at 802816. Send STORE or RETRIEVE + C> RETR cap60.pl198.tar + S> 150 Opening BINARY mode data connection + [...] + S> 226 Transfer complete. + +6. Virtual FTP servers + + It has become common in the Internet for many domain names to be + allocated to a single IP address. This has introduced the concept of + a "virtual host", where a host appears to exist as an independent + entity, but in reality shares all of its resources with one, or more, + other such hosts. + + + + + +Elz & Hethmon [Expires April 2000] [Page 16] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + Such an arrangement presents some problems for FTP Servers, as all + the FTP Server can detect is an incoming FTP connection to a + particular IP address. That is, all domain names which share the IP + address also share the FTP server, and more importantly, its NVFS. + This means that the various virtual hosts cannot offer different + virtual file systems to clients, nor can they offer different + authentication systems. + + No scheme can overcome this without modifications of some kind to the + user-PI and the user-FTP process. That process is the only entity + that knows which virtual host is required. It has performed the + domain name to IP address translation, and thus has the original + domain name available. + + One method which could be used to allow a style of virtual host would + be for the client to simply send a "CWD" command after connecting, + using the virtual host name as the argument to the CWD command. This + would allow the server-FTP process to implement the file stores of + the virtual hosts as sub-directories in its NVFS. This is simple, + and supported by essentially all server-FTP implementations without + requiring any code changes. + + While that method is simple to describe, and to implement, it suffers + from several drawbacks. First, the "CWD" command is available only + after the user-PI has authenticated itself to the server-FTP process. + Thus, all virtual hosts would be required to share a common + authentication scheme. Second, either the server-FTP process needs + to be modified to understand the special nature of this first CWD + command, negating most of the advantage of this scheme, or all users + must see the same identical NVFS view upon connecting (they must + connect in the same initial directory) or the NVFS must implement the + full set of virtual host directories at each possible initial + directory for any possible user, or the virtual host will not be + truly transparent. Third, and again unless the server is specially + modified, a user connecting this way to a virtual host would be able + to trivially move to any other virtual host supported at the same + server-FTP process, exposing the nature of the virtual host. + + Other schemes overloading other existing FTP commands have also been + proposed. None of those have sufficient merit to be worth + discussion. + + The conclusion from the examination of the possibilities seems to be + that to obtain an adequate emulation of "real" FTP servers, server + modifications to support virtual hosts are required. A new command + seems most likely to provide the support required. + + + + + +Elz & Hethmon [Expires April 2000] [Page 17] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +6.1. The HOST command + + A new command "HOST" is added to the FTP command set to allow + server-FTP process to determine to which of possibly many virtual + hosts the client wishes to connect. This command is intended to be + issued before the user is authenticated, allowing the authentication + scheme, and set of legal users, to be dependent upon the virtual host + chosen. Server-FTP processes may, if they desire, permit the HOST + command to be issued after the user has been authenticated, or may + treat that as an erroneous sequence of commands. The behavior of the + server-FTP process which does allow late HOST commands is undefined. + One reasonable interpretation would be for the user-PI to be returned + to the state that existed after the TCP connection was first + established, before user authentication. + + Servers should note that the response to the HOST command is a + sensible time to send their "welcome" message. This allows the + message to be personalized for any virtual hosts that are supported, + and also allows the client to have determined supported languages, or + representations, for the message, and other messages, via the FEAT + response, and selected an appropriate one via the LANG command. See + [7] for more information. + +6.2. Syntax of the HOST command + + The HOST command is defined as follows. + + host-command = "Host" SP hostname CRLF + hostname = 1*DNCHAR 1*( "." 1*DNCHAR ) [ "." ] + DNCHAR = ALPHA / DIGIT / "-" / "_" / "$" / + "!" / "%" / "[" / "]" / ":" + host-response = host-ok / error-response + host-ok = "220" [ SP *TCHAR ] CRLF + + As with all FTP commands, the "host" command word is case + independent, and may be specified in any character case desired. + + The "hostname" given as a parameter specifies the virtual host to + which access is desired. It should normally be the same name that + was used to obtain the IP address to which the FTP control connection + was made, after any client conversions to convert an abbreviated or + local alias to a complete (fully qualified) domain name, but before + resolving a DNS alias (owner of a CNAME resource record) to its + canonical name. + + If the client was given a network literal address, and consequently + was not required to derive it from a hostname, it should send the + HOST command with the network address, as specified to it, enclosed + + + +Elz & Hethmon [Expires April 2000] [Page 18] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + in brackets (after eliminating any syntax, which might also be + brackets, but is not required to be, from which the server deduced + that a literal address had been specified.) That is, for example + + HOST [10.1.2.3] + + should be sent if the client had been instructed to connect to + "10.1.2.3", or "[10.1.2.3]", or perhaps even IPv4:10.1.2.3. The + method of indicating to a client that a literal address is to be used + is beyond the scope of this specification. + + The parameter is otherwise to be treated as a "complete domain name", + as that term is defined in section 3.1 of RFC 1034 [10]. That + implies that the name is to be treated as a case independent string, + in that upper case ASCII characters are to be treated as equivalent + to the corresponding lower case ASCII characters, but otherwise + preserved as given. It also implies some limits on the length of the + parameter and of the components that create its internal structure. + Those limits are not altered in any way here. + + RFC 1034 imposes no other restrictions upon what kinds of names can + be stored in the DNS. Nor does RFC 1035. This specification, + however, allows only a restricted set of names for the purposes of + the HOST command. Those restrictions can be inferred from the ABNF + grammar given for the "hostname". + +6.3. HOST command semantics + + Upon receiving the HOST command, before authenticating the user-PI, a + server-FTP process should validate that the hostname given represents + a valid virtual host for that server, and if so, establish the + appropriate environment for that virtual host. The meaning of that + is not specified here, and may range from doing nothing at all, or + performing a simple change of working directory, to much more + elaborate state changes, as required. + + If the hostname specified is unknown at the server, or if the server + is otherwise unwilling to treat the particular connection as a + connection to the hostname specified, the server will respond with a + 504 reply. + + Note: servers may require that the name specified is in some sense + equivalent to the particular network address that was used to reach + the server. + + If the hostname specified would normally be acceptable, but for any + reason is temporarily unavailable, the server SHOULD reply to the + HOST command with a 434 reply. + + + +Elz & Hethmon [Expires April 2000] [Page 19] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The "220" reply code for the HOST command is the same as the code + used on the initial connection established "welcome" message. This + is done deliberately so as to allow the implementation to implement + the front end FTP server as a wrapper which simply waits for the HOST + command, and then invokes an older, RFC959 compliant, server in the + appropriate environment for the particular hostname received. + +6.3.1. The REIN command + + As specified in [3], the REIN command returns the state of the + connection to that it was immediately after the transport connection + was opened. That is not changed here. The effect of a HOST command + will be lost if a REIN command is performed, a new HOST command must + be issued. + + Implementors of user-FTP should be aware that server-FTP + implementations which implement the HOST command as a wrapper around + older implementations will be unable to correctly implement the REIN + command. In such an implementation, REIN will typically return the + server-FTP to the state that existed immediately after the HOST + command was issued, instead of to the state immediately after the + connection was opened. + +6.3.2. User-PI usage of HOST + + A user-PI that conforms to this specification, MUST send the HOST + command after opening the transport connection, or after any REIN + command, before attempting to authenticate the user with the USER + command. + + The following state diagram shows a typical sequence of flow of + control, where the "B" (begin) state is assumed to occur after the + transport connection has opened, or a REIN command has succeeded. + Other commands (such as FEAT [6]) which require no authentication may + have intervened. This diagram is modeled upon (and largely borrowed + from) the similar diagram in section 6 of [3]. + + In this diagram, a three digit reply indicates that precise server + reply code, a single digit on a reply path indicates any server reply + beginning with that digit, other than any three digit replies that + might take another path. + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 20] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + + +---+ HOST +---+ 1,3,5 + | B |---------->| W |----------------- + +---+ +---+ | + | | | + 2,500,502 | | 4,501,503,504 | + -------------- ------------- | + | | | + V 1 | V + +---+ USER +---+-------------->+---+ + | |---------->| W | 2 ----->| E | + +---+ +---+------ | --->+---+ + | | | | | | + 3 | | 4,5 | | | | + -------------- ----- | | | | + | | | | | | + | | | | | | + | --------- | | + | 1| | | | | + V | | | | | + +---+ PASS +---+ 2 | ------->+---+ + | |---------->| W |-------------->| S | + +---+ +---+ ----------->+---+ + | | | | | | + 3 | |4,5| | | | + -------------- -------- | | + | | | | | ---- + | | | | | | + | ----------- | + | 1,3| | | | | + V | 2| | | V + +---+ ACCT +---+-- | ------>+---+ + | |---------->| W | 4,5 --------->| F | + +---+ +---+-------------->+---+ + +6.4. HOST command errors + + The server-PI shall reply with a 500 or 502 reply if the HOST command + is unrecognized or unimplemented. A 503 reply may be sent if the + HOST command is given after a previous HOST command, or after a user + has been authenticated. Alternately, the server may accept the + command at such a time, with server defined behavior. A 501 reply + should be sent if the hostname given is syntactically invalid, and a + 504 reply if a syntactically valid hostname is not a valid virtual + host name for the server. + + In all such cases the server-FTP process should act as if no HOST + command had been given. + + + +Elz & Hethmon [Expires April 2000] [Page 21] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + A user-PI receiving a 500 or 502 reply should assume that the + server-PI does not implement the HOST command style virtual server. + It may then proceed to login as if the HOST command had succeeded, + and perhaps, attempt a CWD command to the hostname after + authenticating the user. + + A user-PI receiving some other error reply should assume that the + virtual HOST is unavailable, and terminate communications. + + A server-PI that receives a USER command, beginning the + authentication sequence, without having received a HOST command + SHOULD NOT reject the USER command. Clients conforming to earlier + FTP specifications do not send HOST commands. In this case the + server may act as if some default virtual host had been explicitly + selected, or may enter an environment different from that of all + supported virtual hosts, perhaps one in which a union of all + available accounts exists, and which presents a NVFS which appears to + contain sub-directories containing the NVFS for all virtual hosts + supported. + +6.5. FEAT response for HOST command + + A server-FTP process that supports the host command, and virtual FTP + servers, MUST include in the response to the FEAT command [6], a + feature line indicating that the HOST command is supported. This + line should contain the single word "HOST". This MAY be sent in + upper or lower case, or a mixture of both (it is case insensitive) + but SHOULD be transmitted in upper case only. That is, the response + SHOULD be + + C> Feat + S> 211- <any descriptive text> + S> ... + S> HOST + S> ... + S> 211 End + + The ellipses indicate place holders where other features may be + included, and are not required. The one space indentation of the + feature lines is mandatory [6]. + + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 22] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +7. A Trivial Virtual File Store (TVFS) + + Traditionally, FTP has placed almost no constraints upon the file + store (NVFS) provided by a server. This specification does not alter + that. However, it has become common for servers to attempt to + provide at least file system naming conventions modeled loosely upon + those of the UNIX(TM) file system. That is, a tree structured file + system, built of directories, each of which can contain other + directories, or other kinds of files, or both. Each file and + directory has a file name relative to the directory that contains it, + except for the directory at the root of the tree, which is contained + in no other directory, and hence has no name of its own. + + That which has so far been described is perfectly consistent with the + standard FTP NVFS and access mechanisms. The "CWD" command is used + to move from one directory to an embedded directory. "CDUP" may be + provided to return to the parent directory, and the various file + manipulation commands ("RETR", "STOR", the rename commands, etc) are + used to manipulate files within the current directory. + + However, it is often useful to be able to reference files other than + by changing directories, especially as FTP provides no guaranteed + mechanism to return to a previous directory. The Trivial Virtual + File Store (TVFS), if implemented, provides that mechanism. + +7.1. TVFS File Names + + Where a server implements the TVFS, no elementary filename shall + contain the character "/". Where the underlying natural file store + permits files, or directories, to contain the "/" character in their + names, a server-PI implementing TVFS must encode that character in + some manner whenever file or directory names are being returned to + the user-PI, and reverse that encoding whenever such names are being + accepted from the user-PI. + + The encoding method to be used is not specified here. Where some + other character is illegal in file and directory names in the + underlying file store, a simple transliteration may be sufficient. + Where there is no suitable substitute character a more complex + encoding scheme, possibly using an escape character, is likely to be + required. + + With the one exception of the unnamed root directory, a TVFS file + name may not be empty. That is, all other file names contain at + least one character. + + With the sole exception of the "/" character, any valid IS10646 + character [11] may be used in a TVFS filename. When transmitted, + + + +Elz & Hethmon [Expires April 2000] [Page 23] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + file name characters are encoded using the UTF-8 encoding [2]. + +7.2. TVFS Path Names + + A TVFS "Path Name" combines the file or directory name of a target + file or directory, with the directory names of zero or more enclosing + directories, so as to allow the target file or directory to be + referenced other than when the server's "current working directory" + is the directory directly containing the target file or directory. + + By definition, every TVFS file or directory name is also a TVFS path + name. Such a path name is valid to reference the file from the + directory containing the name, that is, when that directory is the + server-FTP's current working directory. + + Other TVFS path names are constructed by prefixing a path name by a + name of a directory from which the path is valid, and separating the + two with the "/" character. Such a path name is valid to reference + the file or directory from the directory containing the newly added + directory name. + + Where a path name has been extended to the point where the directory + added is the unnamed root directory, the path name will begin with + the "/" character. Such a path is known as a fully qualified path + name. Fully qualified paths may, obviously, not be further extended, + as, by definition, no directory contains the root directory. Being + unnamed, it cannot be represented in any other directory. A fully + qualified path name is valid to reference the named file or directory + from any location (that is, regardless of what the current working + directory may be) in the virtual file store. + + Any path name which is not a fully qualified path name may be + referred to as a "relative path name" and will only correctly + reference the intended file when the current working directory of the + server-FTP is a directory from which the relative path name is valid. + + As a special case, the path name "/" is defined to be a fully + qualified path name referring to the root directory. That is, the + root directory does not have a directory (or file) name, but does + have a path name. This special path name may be used only as is as a + reference to the root directory. It may not be combined with other + path names using the rules above, as doing so would lead to a path + name containing two consecutive "/" characters, which is an undefined + sequence. + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 24] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +7.2.1. Notes + + + It is not required, or expected, that there be only one fully + qualified path name that will reference any particular file or + directory. + + As a caveat, though the TVFS file store is basically tree + structured, there is no requirement that any file or directory + have only one parent directory. + + As defined, no TVFS path name will ever contain two consecutive + "/" characters. Such a name is not illegal however, and may be + defined by the server for any purpose that suits it. Clients + implementing this specification should not assume any semantics + at all for such names. + + Similarly, other than the special case path that refers to the + root directory, no TVFS path name constructed as defined here + will ever end with the "/" character. Such names are also not + illegal, but are undefined. + + While any legal IS10646 character is permitted to occur in a TVFS + file or directory name, other than "/", server FTP + implementations are not required to support all possible IS10646 + characters. The subset supported is entirely at the discretion + of the server. The case (where it exists) of the characters that + make up file, directory, and path names may be significant. + Unless determined otherwise by means unspecified here, clients + should assume that all such names are comprised of characters + whose case is significant. Servers are free to treat case (or + any other attribute) of a name as irrelevant, and hence map two + names which appear to be distinct onto the same underlying file. + + There are no defined "magic" names, like ".", ".." or "C:". + Servers may implement such names, with any semantics they choose, + but are not required to do so. + + TVFS imposes no particular semantics or properties upon files, + guarantees no access control schemes, or any of the other common + properties of a file store. Only the naming scheme is defined. + +7.3. FEAT Response for TVFS + + In response to the FEAT command [6] a server that wishes to indicate + support for the TVFS as defined here will include a line that begins + with the four characters "TVFS" (in any case, or mixture of cases, + upper case is not required). Servers SHOULD send upper case. + + Such a response to the FEAT command MUST NOT be returned unless the + server implements TVFS as defined here. + + Later specifications may add to the TVFS definition. Such additions + should be notified by means of additional text appended to the TVFS + feature line. Such specifications, if any, will define the extra + + + +Elz & Hethmon [Expires April 2000] [Page 25] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + text. + + Until such a specification is defined, servers should not include + anything after "TVFS" in the TVFS feature line. Clients, however, + should be prepared to deal with arbitrary text following the four + defined characters, and simply ignore it if unrecognized. + + A typical response to the FEAT command issued by a server + implementing only this specification would be: + + C> feat + S> 211- <any descriptive text> + S> ... + S> TVFS + S> ... + S> 211 end + + The ellipses indicate place holders where other features may be + included, and are not required. The one space indentation of the + feature lines is mandatory [6], and is not counted as one of the + first four characters for the purposes of this feature listing. + + The TVFS feature adds no new commands to the FTP command repertoire. + +7.4. OPTS for TVFS + + There are no options in this TVFS specification, and hence there is + no OPTS command defined. + +7.5. TVFS Examples + + Assume a TVFS file store is comprised of a root directory, which + contains two directories (A and B) and two non-directory files (X and + Y). The A directory contains two directories (C and D) and one other + file (Z). The B directory contains just two non-directory files (P + and Q) and the C directory also two non-directory files (also named P + and Q, by chance). The D directory is empty, that is, contains no + files or directories. + + + + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 26] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + This structure may depicted graphically as... + + (unnamed root) + / | \ \ + / | \ \ + A X B Y + /|\ / \ + / | \ / \ + C D Z P Q + / \ + / \ + P Q + + Given this structure, the following fully qualified path names exist. + + / + /A + /B + /X + /Y + /A/C + /A/D + /A/Z + /A/C/P + /A/C/Q + /B/P + /B/Q + + It is clear that none of the paths / /A /B or /A/D refer to the same + directory, as the contents of each is different. Nor do any of / /A + /A/C or /A/D. However /A/C and /B might be the same directory, there + is insufficient information given to tell. Any of the other path + names (/X /Y /A/Z /A/C/P /A/C/Q /B/P and /B/Q) may refer to the same + underlying files, in almost any combination. + + If the current working directory of the server-FTP is /A then the + following path names, in addition to all the fully qualified path + names, are valid + + C + D + Z + C/P + C/Q + + These all refer to the same files or directories as the corresponding + fully qualified path with "/A/" prepended. + + + + +Elz & Hethmon [Expires April 2000] [Page 27] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + That those path names all exist does not imply that the TVFS sever + will necessarily grant any kind of access rights to the named paths, + or that access to the same file via different path names will + necessarily be granted equal rights. + + None of the following relative paths are valid when the current + directory is /A + + A + B + X + Y + B/P + B/Q + P + Q + + Any of those could be made valid by changing the server-FTP's current + working directory to the appropriate directory. Note that the paths + "P" and "Q" might refer to different files depending upon which + directory is selected to cause those to become valid TVFS relative + paths. + +8. Listings for Machine Processing (MLST and MLSD) + + The MLST and MLSD commands are intended to standardize the file and + directory information returned by the Server-FTP process. These + commands differ from the LIST command in that the format of the + replies is strictly defined although extensible. + + Two commands are defined, MLST which provides data about exactly the + object named on its command line, and no others. MLSD on the other + hand will list the contents of a directory if a directory is named, + otherwise a 501 reply will be returned. In either case, if no object + is named, the current directory is assumed. That will cause MLST to + send a one line response, describing the current directory itself, + and MLSD to list the contents of the current directory. + + In the following, the term MLSx will be used wherever either MLST or + MLSD may be inserted. + + The MLST and MLSD commands also extend the FTP protocol as presented + in RFC 959 [3] and RFC 1123 [9] to allow that transmission of 8-bit + data over the control connection. Note this is not specifying + character sets which are 8-bit, but specifying that FTP + implementations are to specifically allow the transmission and + reception of 8-bit bytes, with all bits significant, over the control + connection. That is, all 256 possible octet values are permitted. + + + +Elz & Hethmon [Expires April 2000] [Page 28] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The MLSx command allows both UTF-8/Unicode and "raw" forms as + arguments, and in responses both to the MLST and MLSD commands, and + all other FTP commands which take pathnames as arguments. + +8.1. Format of MLSx Requests + + The MLST and MLSD commands each allow a single optional argument. + This argument may be either a directory name or, for MLST only, a + filename. For these purposes, a "filename" is the name of any entity + in the server NVFS which is not a directory. Where TVFS is + supported, any TVFS relative path name valid in the current working + directory, or any TVFS fully qualified path name, may be given. If a + directory name is given then MLSD must return a listing of the + contents of the named directory, otherwise it issues a 501 reply, and + does not open a data connection. In all cases for MLST, a single set + of fact lines (usually a single fact line) containing the information + about the named file or directory shall be returned over the control + connection, without opening a data connection. + + If no argument is given then MLSD must return a listing of the + contents of the current working directory, and MLST must return a + listing giving information about the current working directory + itself. For these purposes, the contents of a directory are whatever + filenames (not pathnames) the server-PI will allow to be referenced + when the current working directory is the directory named, and which + the server-PI desires to reveal to the user-PI. + + No title, header, or summary, lines, or any other formatting, other + than as is specified below, is ever returned in the output of an MLST + or MLSD command. + + If the Client-FTP sends an invalid argument, the Server-FTP MUST + reply with an error code of 501. + + The syntax for the MLSx command is: + + mlst = "MLst" [ SP pathname ] CRLF + mlsd = "MLsD" [ SP pathname ] CRLF + +8.2. Format of MLSx Response + + The format of a response to an MLSx command is as follows: + + mlst-response = control-response / error-response + mlsd-response = ( initial-response final-response ) / + error-response + + + + + +Elz & Hethmon [Expires April 2000] [Page 29] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + control-response = "250-" [ response-message ] CRLF + 1*( SP entry CRLF ) + "250" [ SP response-message ] CRLF + + initial-response = "150" [ SP response-message ] CRLF + final-response = "226" SP response-message CRLF + + response-message = *TCHAR + + data-response = *( entry CRLF ) + + entry = [ facts ] SP pathname + facts = 1*( fact ";" ) + fact = factname "=" value + factname = "Size" / "Modify" / "Create" / + "Type" / "Unique" / "Perm" / + "Lang" / "Media-Type" / "CharSet" / + os-depend-fact / local-fact + os-depend-fact = <IANA assigned OS name> "." token + local-fact = "X." token + value = *RCHAR + + Upon receipt of a MLSx command, the server will verify the parameter, + and if invalid return an error-response. For this purpose, the + parameter should be considered to be invalid if the client issuing + the command does not have permission to perform the request + operation. + + If valid, then for an MLST command, the server-PI will send the first + (leading) line of the control response, the entry for the pathname + given, or the current directory if no pathname was provided, and the + terminating line. Normally exactly one entry would be returned, more + entries are permitted only when required to represent a file that is + to have multiple "Type" facts returned. + + Note that for MLST the fact set is preceded by a space. That is + provided to guarantee that the fact set cannot be accidentally + interpreted as the terminating line of the control response, but is + required even when that would not be possible. Exactly one space + exists between the set of facts and the pathname. Where no facts are + present, there will be exactly two leading spaces before the + pathname. No spaces are permitted in the facts, any other spaces in + the response are to be treated as being a part of the pathname. + + If the command was an MLSD command, the server will open a data + connection as indicated in section 3.2 of RFC959 [3]. If that fails, + the server will return an error-response. If all is OK, the server + will return the initial-response, send the appropriate data-response + + + +Elz & Hethmon [Expires April 2000] [Page 30] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + over the new data connection, close that connection, and then send + the final-response over the control connection. The grammar above + defines the format for the data-response, which defines the format of + the data returned over the data connection established. + + The data connection opened for a MLSD response shall be a connection + as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given, + whatever FTP transfer type, mode and structure had actually been set, + and without causing those settings to be altered for future commands. + That is, this transfer type shall be set for the duration of the data + connection established for this command only. While the content of + the data sent can be viewed as a series of lines, implementations + should note that there is no maximum line length defined. + Implementations should be prepared to deal with arbitrarily long + lines. + + The facts part of the specification would contain a series of "file + facts" about the file or directory named on the same line. Typical + information to be presented would include file size, last + modification time, creation time, a unique identifier, and a + file/directory flag. + + The complete format for a successful reply to the MLSD command would + be: + + facts SP pathname CRLF + facts SP pathname CRLF + facts SP pathname CRLF + ... + + Note that the format is intended for machine processing, not human + viewing, and as such the format is very rigid. Implementations MUST + NOT vary the format by, for example, inserting extra spaces for + readability, replacing spaces by tabs, including header or title + lines, or inserting blank lines, or in any other way alter this + format. Exactly one space is always required after the set of facts + (which may be empty). More spaces may be present on a line if, and + only if, the file name presented contains significant spaces. The + set of facts must not contain any spaces anywhere inside it. Facts + should be provided in each output line only if they both provide + relevant information about the file named on the same line, and they + are in the set requested by the user-PI. There is no requirement + that the same set of facts be provided for each file, or that the + facts presented occur in the same order for each file. + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 31] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +8.3. Filename encoding + + An FTP implementation supporting the MLSx commands must be 8-bit + clean. This is necessary in order to transmit UTF-8 encoded + filenames. This specification recommends the use of UTF-8 encoded + filenames. FTP implementations SHOULD use UTF-8 whenever possible to + encourage the maximum interoperability. + + Filenames are not restricted to UTF-8, however treatment of arbitrary + character encodings is not specified by this standard. Applications + are encouraged to treat non-UTF-8 encodings of filenames as octet + sequences. + + Note that this encoding is unrelated to that of the contents of the + file, even if the file contains character data. + + Further information about filename encoding for FTP may be found in + "Internationalization of the File Transfer Protocol" [7]. + +8.3.1. Notes about the Filename + + The filename returned in the MLST response should be the same name as + was specified in the MLST command, or, where TVFS is supported, a + fully qualified TVFS path naming the same file. Where no argument + was given to the MLST command, the server-PI may either include an + empty filename in the response, or it may supply a name that refers + to the current directory, if such a name is available. Where TVFS is + supported, a fully qualified path name of the current directory + SHOULD be returned. + + Filenames returned in the output from an MLSD command SHOULD be + unqualified names within the directory named, or the current + directory if no argument was given. That is, the directory named in + the MLSD command SHOULD NOT appear as a component of the filenames + returned. + + If the server-FTP process is able, and the "type" fact is being + returned, it MAY return in the MLSD response, an entry whose type is + "cdir", which names the directory from which the contents of the + listing were obtained. Where TVFS is supported, the name MAY be the + fully qualified path name of the directory, or MAY be any other path + name which is valid to refer to that directory from the current + working directory of the server-FTP. Where more than one name + exists, multiple of these entries may be returned. In a sense, the + "cdir" entry can be viewed as a heading for the MLSD output. + However, it is not required to be the first entry returned, and may + occur anywhere within the listing. + + + + +Elz & Hethmon [Expires April 2000] [Page 32] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + When TVFS is supported, a user-PI can refer to any file or directory + in the listing by combining a type "cdir" name, with the appropriate + name from the directory listing using the procedure defined in + section 7.2. + + Alternatively, whether TVFS is supported or not, the user-PI can + issue a CWD command ([3]) giving a name of type "cdir" from the + listing returned, and from that point reference the files returned in + the MLSD response from which the cdir was obtained by using the + filename components of the listing. + +8.4. Format of Facts + + The "facts" for a file in a reply to a MLSx command consist of + information about that file. The facts are a series of keyword=value + pairs each followed by semi-colon (";") characters. An individual + fact may not contain a semi-colon in its name or value. The complete + series of facts may not contain the space character. See the + definition or "RCHAR" in section 2.1 for a list of the characters + that can occur in a fact value. Not all are applicable to all facts. + + A sample of a typical series of facts would be: (spread over two + lines for presentation here only) + + size=4161;lang=en-US;modify=19970214165800;create=19961001124534; + type=file;x.myfact=foo,bar; + +8.5. Standard Facts + + This document defines a standard set of facts as follows: + + size -- Size in octets + modify -- Last modification time + create -- Creation time + type -- Entry type + unique -- Unique id of file/directory + perm -- File permissions, whether read, write, execute is + allowed for the login id. + lang -- Language of the filename per IANA[12] registry. + media-type -- MIME media-type of file contents per IANA registry. + charset -- Character set per IANA registry (if not UTF-8) + + Fact names are case-insensitive. Size, size, SIZE, and SiZe are the + same fact. + + Further operating system specific keywords could be specified by + using the IANA operating system name as a prefix (examples only): + + + + +Elz & Hethmon [Expires April 2000] [Page 33] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + OS/2.ea -- OS/2 extended attributes + MACOS.rf -- MacIntosh resource forks + UNIX.mode -- Unix file modes (permissions) + + Implementations may define keywords for experimental, or private use. + All such keywords MUST begin with the two character sequence "x.". + As type names are case independent, "x." and "X." are equivalent. + For example: + + x.ver -- Version information + x.desc -- File description + x.type -- File type + +8.5.1. The type Fact + + The type fact needs a special description. Part of the problem with + current practices is deciding when a file is a directory. If it is a + directory, is it the current directory, a regular directory, or a + parent directory? The MLST specification makes this unambiguous + using the type fact. The type fact given specifies information about + the object listed on the same line of the MLST response. + + Five values are possible for the type fact: + + file -- a file entry + cdir -- the listed directory + pdir -- a parent directory + dir -- a directory or sub-directory + OS.name=type -- an OS or file system dependent file type + + The syntax is defined to be: + + type-fact = type-label "=" type-val + type-label = "Type" + type-val = "File" / "cdir" / "pdir" / "dir" / + os-type + +8.5.1.1. type=file + + The presence of the type=file fact indicates the listed entry is a + file containing non-system data. That is, it may be transferred from + one system to another of quite different characteristics, and perhaps + still be meaningful. + +8.5.1.2. type=cdir + + The type=cdir fact indicates the listed entry contains a pathname of + the directory whose contents are listed. An entry of this type will + + + +Elz & Hethmon [Expires April 2000] [Page 34] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + only be returned as a part of the result of an MLSD command when the + type fact is included, and provides a name for the listed directory, + and facts about that directory. In a sense, it can be viewed as + representing the title of the listing, in a machine friendly format. + It may appear at any point of the listing, it is not restricted to + appearing at the start, though frequently may do so, and may occur + multiple times. It MUST NOT be included if the type fact is not + included, or there would be no way for the user-PI to distinguish the + name of the directory from an entry in the directory. + + Where TVFS is supported by the server-FTP, this name may be used to + construct path names with which to refer to the files and directories + returned in the same MLSD output (see section 7.2). These path names + are only expected to work when the server-PI's position in the NVFS + file tree is the same as its position when the MLSD command was + issued, unless a fully qualified path name results. + + Where TVFS is not supported, the only defined semantics associated + with a "type=cdir" entry are that, provided the current working + directory of the server-PI has not been changed, a pathname of type + "cdir" may be used as an argument to a CWD command, which will cause + the current directory of the server-PI to change so that the + directory which was listed in its current working directory. + +8.5.1.3. type=dir + + If present, the type=dir entry gives the name of a directory. Such + an entry typically cannot be transferred from one system to another + using RETR, etc, but should (permissions permitting) be able to be + the object of an MLSD command. + +8.5.1.4. type=pdir + + If present, which will occur only in the response to a MLSD command + when the type fact is included, the type=pdir entry represents a + pathname of the parent directory of the listed directory. As well as + having the properties of a type=dir, a CWD command that uses the + pathname from this entry should change the user to a parent directory + of the listed directory. If the listed directory is the current + directory, a CDUP command may also have the effect of changing to the + named directory. User-FTP processes should note not all responses + will include this information, and that some systems may provide + multiple type=pdir responses. + + Where TVFS is supported, a "type=pdir" name may be a relative path + name, or a fully qualified path name. A relative path name will be + relative to the directory being listed, not to the current directory + of the server-PI at the time. + + + +Elz & Hethmon [Expires April 2000] [Page 35] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + For the purposes of this type value, a "parent directory" is any + directory in which there is an entry of type=dir which refers to the + directory in which the type=pdir entity was found. Thus it is not + required that all entities with type=pdir refer to the same + directory. The "unique" fact (if supported) can be used to determine + whether there is a relationship between the type=pdir entries or not. + +8.5.1.5. System defined types + + Files types that are specific to a specific operating system, or file + system, can be encoded using the "OS." type names. The format is: + + os-type = "OS." os-name "=" os-type + os-name = <an IANA registered operating system name> + os-type = token + + The "os-name" indicates the specific system type which supports the + particular localtype. OS specific types are registered by the IANA + using the procedures specified in section 11. The "os-type" provides + the system dependent information as to the type of the file listed. + The os-name and os-type strings in an os-type are case independent. + "OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or + would, if such a type were registered.) + + Note: Where the underlying system supports a file type which is + essentially an indirect pointer to another file, the NVFS + representation of that type should normally be to represent the file + which the reference indicates. That is, the underlying basic file + will appear more than once in the NVFS, each time with the "unique" + fact (see immediately following section) containing the same value, + indicating that the same file is represented by all such names. + User-PIs transferring the file need then transfer it only once, and + then insert their own form of indirect reference to construct + alternate names where desired, or perhaps even copy the local file if + that is the only way to provide two names with the same content. A + file which would be a reference to another file, if only the other + file actually existed, may be represented in any OS dependent manner + appropriate, or not represented at all. + +8.5.1.6. Multiple types + + Where a file is such that it may validly, and sensibly, treated by + the server-PI as being of more than one of the above types, then + multiple entries should be returned, each with its own "Type" fact of + the appropriate type, and each containing the same pathname. This + may occur, for example, with a structured file, which may contain + sub-files, and where the server-PI permits the structured file to be + treated as a unit, or treated as a directory allowing the sub-files + + + +Elz & Hethmon [Expires April 2000] [Page 36] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + within it to be referenced. + +8.5.2. The unique Fact + + The unique fact is used to present a unique identifier for a file or + directory in the NVFS accessed via a server-FTP process. The value + of this fact should be the same for any number of pathnames that + refer to the same underlying file. The fact should have different + values for names which reference distinct files. The mapping between + files, and unique fact tokens should be maintained, and remain + consistent, for at least the lifetime of the control connection from + user-PI to server-PI. + + unique-fact = "Unique" "=" token + + This fact would be expected to be used by Server-FTPs whose host + system allows things such as symbolic links so that the same file may + be represented in more than one directory on the server. The only + conclusion that should be drawn is that if two different names each + have the same value for the unique fact, they refer to the same + underlying object. The value of the unique fact (the token) should + be considered an opaque string for comparison purposes, and is a case + dependent value. The tokens "A" and "a" do not represent the same + underlying object. + +8.5.3. The modify Fact + + The modify fact is used to determine the last time the content of the + file (or directory) indicated was modified. Any change of substance + to the file should cause this value to alter. That is, if a change + is made to a file such that the results of a RETR command would + differ, then the value of the modify fact should alter. User-PIs + should not assume that a different modify fact value indicates that + the file contents are necessarily different than when last retrieved. + Some systems may alter the value of the modify fact for other + reasons, though this is discouraged wherever possible. Also a file + may alter, and then be returned to its previous content, which would + often be indicated as two incremental alterations to the value of the + modify fact. + + For directories, this value should alter whenever a change occurs to + the directory such that different filenames would (or might) be + included in MLSD output of that directory. + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 37] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + modify-fact = "Modify" "=" time-val + +8.5.4. The create Fact + + The create fact indicates when a file, or directory, was first + created. Exactly what "creation" is for this purpose is not + specified here, and may vary from server to server. About all that + can be said about the value returned is that it can never indicate a + later time than the modify fact. + + create-fact = "Create" "=" time-val + + Implementation Note: Implementors of this fact on UNIX(TM) systems + should note that the unix "stat" "st_ctime" field does not give + creation time, and that unix file systems do not record creation + time at all. Unix (and POSIX) implementations will normally not + include this fact. + +8.5.5. The perm Fact + + The perm fact is used to indicate access rights the current FTP user + has over the object listed. Its value is always an unordered + sequence of alphabetic characters. + + perm-fact = "Perm" "=" *pvals + pvals = "a" / "c" / "d" / "e" / "f" / + "l" / "m" / "p" / "r" / "w" + + There are ten permission indicators currently defined. Many are + meaningful only when used with a particular type of object. The + indicators are case independent, "d" and "D" are the same indicator. + + The "a" permission applies to objects of type=file, and indicates + that the APPE (append) command may be applied to the file named. + + The "c" permission applies to objects of type=dir (and type=pdir, + type=cdir). It indicates that files may be created in the directory + named. That is, that a STOU command is likely to succeed, and that + STOR and APPE commands might succeed if the file named did not + previously exist, but is to be created in the directory object that + has the "c" permission. It also indicates that the RNTO command is + likely to succeed for names in the directory. + + The "d" permission applies to all types. It indicates that the + object named may be deleted, that is, that the RMD command may be + applied to it if it is a directory, and otherwise that the DELE + command may be applied to it. + + + + +Elz & Hethmon [Expires April 2000] [Page 38] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The "e" permission applies to the directory types. When set on an + object of type=dir, type=cdir, or type=pdir it indicates that a CWD + command naming the object should succeed, and the user should be able + to enter the directory named. For type=pdir it also indicates that + the CDUP command may succeed (if this particular pathname is the one + to which a CDUP would apply.) + + The "f" permission for objects indicates that the object named may be + renamed - that is, may be the object of an RNFR command. + + The "l" permission applies to the directory file types, and indicates + that the listing commands, LIST, NLST, and MLSD may be applied to the + directory in question. + + The "m" permission applies to directory types, and indicates that the + MKD command may be used to create a new directory within the + directory under consideration. + + The "p" permission applies to directory types, and indicates that + objects in the directory may be deleted, or (stretching naming a + little) that the directory may be purged. Note: it does not indicate + that the RMD command may be used to remove the directory named + itself, the "d" permission indicator indicates that. + + The "r" permission applies to type=file objects, and for some + systems, perhaps to other types of objects, and indicates that the + RETR command may be applied to that object. + + The "w" permission applies to type=file objects, and for some + systems, perhaps to other types of objects, and indicates that the + STOR command may be applied to the object named. + + Note: That a permission indicator is set can never imply that the + appropriate command is guaranteed to work - just that it might. + Other system specific limitations, such as limitations on + available space for storing files, may cause an operation to + fail, where the permission flags may have indicated that it was + likely to succeed. The permissions are a guide only. + + Implementation note: The permissions are described here as they apply + to FTP commands. They may not map easily into particular + permissions available on the server's operating system. Servers + are expected to synthesize these permission bits from the + permission information available from operating system. For + example, to correctly determine whether the "D" permission bit + should be set on a directory for a server running on the + UNIX(TM) operating system, the server should check that the + directory named is empty, and that the user has write permission + + + +Elz & Hethmon [Expires April 2000] [Page 39] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + on both the directory under consideration, and its parent + directory. + + Some systems may have more specific permissions than those + listed here, such systems should map those to the flags defined + as best they are able. Other systems may have only more broad + access controls. They will generally have just a few possible + permutations of permission flags, however they should attempt to + correctly represent what is permitted. + +8.5.6. The lang Fact + + The lang fact describes the natural language of the filename for use + in display purposes. Values used here should be taken from the + language registry of the IANA. See [13] for the syntax, and + procedures, related to language tags. + + lang-fact = "Lang" "=" token + + Server-FTP implementations MUST NOT guess language values. Language + values must be determined in an unambiguous way such as file system + tagging of language or by user configuration. Note that the lang + fact provides no information at all about the content of a file, only + about the encoding of its name. + +8.5.7. The size Fact + + The size fact applies to non-directory file types and should always + reflect the approximate size of the file. This should be as accurate + as the server can make it, without going to extraordinary lengths, + such as reading the entire file. The size is expressed in units of + octets of data in the file. + + Given limitations in some systems, Client-FTP implementations must + understand this size may not be precise and may change between the + time of a MLST and RETR operation. + + Clients that need highly accurate size information for some + particular reason should use the SIZE command as defined in section + 4. The most common need for this accuracy is likely to be in + conjunction with the REST command described in section 5. The size + fact, on the other hand, should be used for purposes such as + indicating to a human user the approximate size of the file to be + transferred, and perhaps to give an idea of expected transfer + completion time. + + + + + + +Elz & Hethmon [Expires April 2000] [Page 40] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + size-fact = "Size" "=" 1*DIGIT + +8.5.8. The media-type Fact + + The media-type fact represents the IANA media type of the file named, + and applies only to non-directory types. The list of values used + must follow the guidelines set by the IANA registry. + + media-type = "Media-Type" "=" <per IANA guidelines> + + Server-FTP implementations MUST NOT guess media type values. Media + type values must be determined in an unambiguous way such as file + system tagging of media-type or by user configuration. This fact + gives information about the content of the file named. Both the + primary media type, and any appropriate subtype should be given, + separated by a slash "/" as is traditional. + +8.5.9. The charset Fact + + The charset fact provides the IANA character set name, or alias, for + the encoded pathnames in a MLSx response. The default character set + is UTF-8 unless specified otherwise. FTP implementations SHOULD use + UTF-8 if possible to encourage maximum interoperability. The value + of this fact applies to the pathname only, and provides no + information about the contents of the file. + + charset-type = "Charset" "=" token + +8.5.10. Required facts + + Servers are not required to support any particular set of the + available facts. However, servers SHOULD, if conceivably possible, + support at least the type, perm, size, unique, and modify facts. + +8.6. System Dependent and Local Facts + + By using an system dependent fact, or a local fact, a server-PI may + communicate to the user-PI information about the file named which is + peculiar to the underlying file system. + +8.6.1. System Dependent Facts + + System dependent fact names are labeled by prefixing a label + identifying the specific information returned by the name of the + appropriate operating system from the IANA maintained list of + operating system names. + + + + + +Elz & Hethmon [Expires April 2000] [Page 41] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The value of an OS dependent fact may be whatever is appropriate to + convey the information available. It must be encoded as a "token" as + defined in section 2.1 however. + + In order to allow reliable interoperation between users of system + dependent facts, the IANA will maintain a registry of system + dependent fact names, their syntax, and the interpretation to be + given to their values. Registrations of system dependent facts are + to be accomplished according to the procedures of section 11. + +8.6.2. Local Facts + + Implementations may also make available other facts of their own + choosing. As the method of interpretation of such information will + generally not be widely understood, server-PIs should be aware that + clients will typically ignore any local facts provided. As there is + no registration of locally defined facts, it is entirely possible + that different servers will use the same local fact name to provide + vastly different information. Hence user-PIs should be hesitant + about making any use of any information in a locally defined fact + without some other specific assurance that the particular fact is one + that they do comprehend. + + Local fact names all begin with the sequence "X.". The rest of the + name is a "token" (see section 2.1). The value of a local fact can + be anything at all, provided it can be encoded as a "token". + +8.7. MLSx Examples + + The following examples are all taken from dialogues between existing + FTP clients and servers. Because of this, not all possible + variations of possible response formats are shown in the examples. + This should not be taken as limiting the options of other server + implementors. Where the examples show OS dependent information, that + is to be treated as being purely for the purposes of demonstration of + some possible OS specific information that could be defined. As at + the time of the writing of this document, no OS specific facts or + file types have been defined, the examples shown here should not be + treated as in any way to be preferred over other possible similar + definitions. Consult the IANA registries to determine what types and + facts have been defined. + + In the examples shown, only relevant commands and responses have been + included. This is not to imply that other commands (including + authentication, directory modification, PORT or PASV commands, or + similar) would not be present in an actual connection, or were not, + in fact, actually used in the examples before editing. Note also + that the formats shown are those that are transmitted between client + + + +Elz & Hethmon [Expires April 2000] [Page 42] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + and server, not formats which would normally ever be reported to the + user of the client. + + In the examples, lines that begin "C> " were sent over the control + connection from the client to the server, lines that begin "S> " were + sent over the control connection from the server to the client, and + lines that begin "D> " were sent from the server to the client over a + data connection created just to send those lines and closed + immediately after. No examples here show data transferred over a + data connection from the client to the server. In all cases, the + prefixes shown above, including the one space, have been added for + the purposes of this document, and are not a part of the data + exchanged between client and server. + +8.7.1. Simple MLST + + C> PWD + S> 257 "/tmp" is current directory. + C> MLst cap60.pl198.tar.gz + S> 250- Listing cap60.pl198.tar.gz + S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz + S> 250 End + + The client first asked to be told the current directory of the + server. This was purely for the purposes of clarity of this example. + The client then requested facts about a specific file. The server + returned the "250-" first control-response line, followed by a single + line of facts about the file, followed by the terminating "250 " + line. The text on the control-response line and the terminating line + can be anything the server decides to send. Notice that the fact + line is indented by a single space. Notice also that there are no + spaces in the set of facts returned, until the single space before + the filename. The filename returned on the fact line is a fully + qualified pathname of the file listed. The facts returned show that + the line refers to a file, that file contains approximately 1024990 + bytes, though more or less than that may be transferred if the file + is retrieved, and a different number may be required to store the + file at the client's file store, and the connected user has + permission to retrieve the file but not to do anything else + particularly interesting. + +8.7.2. MLST of a directory + + C> PWD + S> 257 "/" is current directory. + C> MLst tmp + S> 250- Listing tmp + S> Type=dir;Modify=19981107085215;Perm=el; /tmp + + + +Elz & Hethmon [Expires April 2000] [Page 43] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + S> 250 End + + Again the PWD is just for the purposes of demonstration for the + example. The MLST fact line this time shows that the file listed is + a directory, that it was last modified at 08:52:15 on the 7th of + November, 1998 UTC, and that the user has permission to enter the + directory, and to list its contents, but not to modify it in any way. + Again, the fully qualified path name of the directory listed is + given. + +8.7.3. MLSD of a directory + + C> MLSD tmp + S> 150 BINARY connection open for MLSD tmp + D> Type=cdir;Modify=19981107085215;Perm=el; tmp + D> Type=cdir;Modify=19981107085215;Perm=el; /tmp + D> Type=pdir;Modify=19990112030508;Perm=el; .. + D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z + D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c + D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt + D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch + D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx + D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif + D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx + D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx + D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx + D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz + S> 226 MLSD completed + + In this example notice that there is no leading space on the fact + lines returned over the data connection. Also notice that two lines + of "type=cdir" have been given. These show two alternate names for + the directory listed, one a fully qualified pathname, and the other a + local name relative to the servers current directory when the MLSD + was performed. Note that all other filenames in the output are + relative to the directory listed, though the server could, if it + chose, give a fully qualified path name for the "type=pdir" line. + This server has chosen not to. The other files listed present a + fairly boring set of files that are present in the listed directory. + Note that there is no particular order in which they are listed. + They are not sorted by filename, by size, or by modify time. Note + also that the "perm" fact has an empty value for the file + "capmux.tar.z" indicating that the connected user has no permissions + at all for that file. This server has chosen to present the "cdir" + and "pdir" lines before the lines showing the content of the + directory, it is not required to do so. The "size" fact does not + provide any meaningful information for a directory, so is not + included in the fact lines for the directory types shown. + + + +Elz & Hethmon [Expires April 2000] [Page 44] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +8.7.4. A more complex example + + C> MLst test + S> 250- Listing test + S> Type=dir;Perm=el;Unique=keVO1+ZF4 test + S> 250 End + C> MLSD test + S> 150 BINARY connection open for MLSD test + D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test + D> Type=pdir;Perm=e;Unique=keVO1+d?3; .. + D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar + D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device + D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block + D> Type=file;Perm=awr;Unique=keVO1+8G4; writable + D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous + D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec + D> Type=file;Perm=r;Unique=keVO1+EG4; two words + D> Type=file;Perm=r;Unique=keVO1+IH4; leading space + D> Type=file;Perm=r;Unique=keVO1+1G4; file1 + D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming + D> Type=file;Perm=r;Unique=keVO1+1G4; file2 + D> Type=file;Perm=r;Unique=keVO1+1G4; file3 + D> Type=file;Perm=r;Unique=keVO1+1G4; file4 + S> 226 MLSD completed + C> MLSD test/incoming + S> 150 BINARY connection open for MLSD test/incoming + D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming + D> Type=pdir;Perm=el;Unique=keVO1+ZF4; .. + D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar + D> Type=file;Perm=awdrf;Unique=keVO1+LH4; + D> Type=file;Perm=rf;Unique=keVO1+1G4; file5 + D> Type=file;Perm=rf;Unique=keVO1+1G4; file6 + D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty + S> 226 MLSD completed + + For the purposes of this example the fact set requested has been + modified to delete the "size" and "modify" facts, and add the + "unique" fact. First, facts about a filename have been obtained via + MLST. Note that no fully qualified path name was given this time. + That was because the server was unable to determine that information. + Then having determined that the filename represents a directory, that + directory has been listed. That listing also shows no fully + qualified path name, for the same reason, thus has but a single + "type=cdir" line. This directory (which was created especially for + the purpose) contains several interesting files. There are some with + OS dependent file types, several sub-directories, and several + ordinary files. + + + + +Elz & Hethmon [Expires April 2000] [Page 45] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + Not much can be said here about the OS dependent file types, as none + of the information shown there should be treated as any more than + possibilities. It can be seen that the OS type of the server is + "unix" though, which is one of the OS types in the IANA registry of + Operating System names. + + Of the three directories listed, "no-exec" has no permission granted + to this user to access at all. From the "Unique" fact values, it can + be determined that "promiscuous" and "incoming" in fact represent the + same directory. Its permissions show that the connected user has + permission to do essentially anything other than to delete the + directory. That directory was later listed. It happens that the + directory can not be deleted because it is not empty. + + Of the normal files listed, two contain spaces in their names. The + file called " leading space" actually contains two spaces in its + name, one before the "l" and one between the "g" and the "s". The + two spaces that separate the facts from the visible part of the path + name make that clear. The file "writable" has the "a" and "w" + permission bits set, and consequently the connected user should be + able to STOR or APPE to that file. + + The other four file names, "file1", "file2", "file3", and "file4" all + represent the same underlying file, as can be seen from the values of + the "unique" facts of each. It happens that "file1" and "file2" are + Unix "hard" links, and that "file3" and "file4" are "soft" or + "symbolic" links to the first two. None of that information is + available via standard MLST facts, it is sufficient for the purposes + of FTP to note that all represent the same file, and that the same + data would be fetched no matter which of them was retrieved, and that + all would be simultaneously modified were data stored in any. + + Finally, the sub-directory "incoming" is listed. Since "promiscuous" + is the same directory there would be no point listing it as well. In + that directory, the files "file5" and "file6" represent still more + names for the "file1" file we have seen before. Notice the entry + between that for "bar" and "file5". Though it is not possible to + easily represent it in this document, that shows a file with a name + comprising exactly three spaces (" "). A client will have no + difficulty determining that name from the output presented to it + however. The directory "empty" is, as its name implies, empty, + though that is not shown here. It can, however, be deleted, as can + file "bar" and the file whose name is three spaces. All the files + that reside in this directory can be renamed. This is a consequence + of the UNIX semantics of the directory that contains them being + modifiable. + + + + + +Elz & Hethmon [Expires April 2000] [Page 46] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +8.7.5. More accurate time information + + C> MLst file1 + S> 250- Listing file1 + S> Type=file;Modify=19990929003355.237; file1 + S> 250 End + + In this example, the server-FTP is indicating that "file1" was last + modified 237 milliseconds after 00:33:55 UTC on the 29th of + September, 1999. + +8.7.6. A different server + + C> MLST + S> 250-Begin + S> type=dir;unique=AQkAAAAAAAABCAAA; / + S> 250 End. + C> MLSD . + S> 150 Opening ASCII mode data connection for MLS. + D> type=cdir;unique=AQkAAAAAAAABCAAA; / + D> type=dir;unique=AQkAAAAAAAABEAAA; bin + D> type=dir;unique=AQkAAAAAAAABGAAA; etc + D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife + D> type=dir;unique=AQkAAAAAAAABoAAA; incoming + D> type=dir;unique=AQkAAAAAAAABIAAA; lib + D> type=dir;unique=AQkAAAAAAAABWAEA; linux + D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd + D> type=dir;unique=AQkAAAAAAAABGAEA; outbox + D> type=dir;unique=AQkAAAAAAAABuAAA; quake2 + D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff + S> 226 Listing completed. + C> MLSD linux + S> 150 Opening ASCII mode data connection for MLS. + D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux + D> type=pdir;unique=AQkAAAAAAAABCAAA; / + D> type=dir;unique=AQkAAAAAAAABeAEA; firewall + D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world + D> type=dir;unique=AQkAAAAAAAABYAEA; kernel + D> type=dir;unique=AQkAAAAAAAABmAEA; scripts + D> type=dir;unique=AQkAAAAAAAABkAEA; security + S> 226 Listing completed. + C> MLSD linux/kernel + S> 150 Opening ASCII mode data connection for MLS. + D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel + D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux + D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config + D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz + D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz + + + +Elz & Hethmon [Expires April 2000] [Page 47] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + S> 226 Listing completed. + + Note that this server returns its "unique" fact value in quite a + different format. It also returns fully qualified path names for the + "pdir" entry. + +8.7.7. Some IANA files + + C> MLSD . + S> 150 BINARY connection open for MLSD . + D> Type=cdir;Modify=19990219183438; /iana/assignments + D> Type=pdir;Modify=19990112030453; .. + D> Type=dir;Modify=19990219073522; media-types + D> Type=dir;Modify=19990112033515; character-set-info + D> Type=dir;Modify=19990112033529; languages + D> Type=file;Size=44242;Modify=19990217230400; character-sets + D> Type=file;Size=1947;Modify=19990209215600; operating-system-names + S> 226 MLSD completed + C> MLSD media-types + S> 150 BINARY connection open for MLSD media-types + D> Type=cdir;Modify=19990219073522; media-types + D> Type=cdir;Modify=19990219073522; /iana/assignments/media-types + D> Type=pdir;Modify=19990219183438; .. + D> Type=dir;Modify=19990112033045; text + D> Type=dir;Modify=19990219183442; image + D> Type=dir;Modify=19990112033216; multipart + D> Type=dir;Modify=19990112033254; video + D> Type=file;Size=30249;Modify=19990218032700; media-types + S> 226 MLSD completed + C> MLSD character-set-info + S> 150 BINARY connection open for MLSD character-set-info + D> Type=cdir;Modify=19990112033515; character-set-info + D> Type=cdir;Modify=19990112033515; /iana/assignments/character-set-info + D> Type=pdir;Modify=19990219183438; .. + D> Type=file;Size=1234;Modify=19980903020400; windows-1251 + D> Type=file;Size=4557;Modify=19980922001400; tis-620 + D> Type=file;Size=801;Modify=19970324130000; ibm775 + D> Type=file;Size=552;Modify=19970320130000; ibm866 + D> Type=file;Size=922;Modify=19960505140000; windows-1258 + S> 226 MLSD completed + C> MLSD languages + S> 150 BINARY connection open for MLSD languages + D> Type=cdir;Modify=19990112033529; languages + D> Type=cdir;Modify=19990112033529; /iana/assignments/languages + D> Type=pdir;Modify=19990219183438; .. + D> Type=file;Size=2391;Modify=19980309130000; default + D> Type=file;Size=943;Modify=19980309130000; tags + D> Type=file;Size=870;Modify=19971026130000; navajo + + + +Elz & Hethmon [Expires April 2000] [Page 48] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + D> Type=file;Size=699;Modify=19950911140000; no-bok + S> 226 MLSD completed + C> PWD + S> 257 "/iana/assignments" is current directory. + + This example shows some of the IANA maintained files that are + relevant for this specification in MLSD format. Note that these + listings have been edited by deleting many entries, the actual + listings are much longer. + +8.7.8. A stress test of case (in)dependence + + The following example is intended to make clear some cases where case + dependent strings are permitted in the MLSx commands, and where case + independent strings are required. + + C> MlsD . + S> 150 BINARY connection open for MLSD . + D> Type=pdir;Modify=19990929011228;Perm=el;Unique=keVO1+ZF4; .. + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; FILE2 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+aG8; file3 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+ag8; FILE3 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file1 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file2 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Ag8; File3 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; File1 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; File2 + D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bd8; FILE1 + S> 226 MLSD completed + + Note first that the "MLSD" command, shown here as "MlsD" is case + independent. Clients may issue this command in any case, or + combination of cases, they desire. This is the case for all FTP + commands. + + Next, notice the labels of the facts. These are also case + independent strings, Server-FTP is permitted to return them in any + case they desire. User-FTP must be prepared to deal with any case, + though it may do this by mapping the labels to a common case if + desired. + + Then, notice that there are nine objects of "type" file returned. In + a case independent NVFS these would represent three different file + names, "file1", "file2", and "file3". With a case dependent NVFS all + nine represent different file names. Either is possible, server-FTPs + may implement a case dependent or a case independent NVFS. User-FTPs + must allow for case dependent selection of files to manipulate on the + server. + + + +Elz & Hethmon [Expires April 2000] [Page 49] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + Lastly, notice that the value of the "unique" fact is case dependent. + In the example shown, "file1", "File1", and "file2" all have the same + "unique" fact value "keVO1+bD8", and thus all represent the same + underlying file. On the other hand, "FILE1" has a different "unique" + fact value ("keVO1+bd8") and hence represents a different file. + Similarly, "FILE2" and "File2" are two names for the same underlying + file, whereas "file3", "File3" and "FILE3" all represent different + underlying files. + + That the approximate sizes ("size" fact) and last modification times + ("modify" fact) are the same in all cases might be no more than a + coincidence. + + It is not suggested that the operators of server-FTPs create NVFS + which stress the protocols to this extent, however both user and + server implementations must be prepared to deal with such extreme + examples. + +8.8. FEAT response for MLSx + + When responding to the FEAT command, a server-FTP process that + supports MLST, and MLSD, plus internationalization of pathnames, MUST + indicate that this support exists. It does this by including a MLST + feature line. As well as indicating the basic support, the MLST + feature line indicates which MLST facts are available from the + server, and which of those will be returned if no subsequent "OPTS + MLST" command is sent. + + mlst-feat = SP "MLST" [SP factlist] CRLF + factlist = 1*( factname ["*"] ";" ) + + The initial space shown in the mlst-feat response is that required by + the FEAT command, two spaces are not permitted. If no factlist is + given, then the server-FTP process is indicating that it supports + MLST, but implements no facts. Only pathnames can be returned. This + would be a minimal MLST implementation, and useless for most + practical purposes. Where the factlist is present, the factnames + included indicate the facts supported by the server. Where the + optional asterisk appears after a factname, that fact will be + included in MLST format responses, until an "OPTS MLST" is given to + alter the list of facts returned. After that, subsequent FEAT + commands will return the asterisk to show the facts selected by the + most recent "OPTS MLST". + + Note that there is no distinct FEAT output for MLSD. The presence of + the MLST feature indicates that both MLST and MLSD are supported. + + + + + +Elz & Hethmon [Expires April 2000] [Page 50] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +8.8.1. Examples + + C> Feat + S> 211- Features supported + S> REST STREAM + S> MDTM + S> SIZE + S> TVFS + S> UTF8 + S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + + Aside from some features irrelevant here, this server indicates that + it supports MLST including several, but not all, standard facts, all + of which it will send by default. It also supports two OS dependent + facts, and one locally defined fact. The latter three must be + requested expressly by the client for this server to supply them. + + C> Feat + S> 211-Extensions supported: + S> CLNT + S> MDTM + S> MLST type*;size*;modify*;UNIX.mode*;UNIX.owner;UNIX.group;unique; + S> PASV + S> REST STREAM + S> SIZE + S> TVFS + S> Compliance Level: 19981201 (IETF mlst-05) + S> 211 End. + + Again, in addition to some irrelevant features here, this server + indicates that it supports MLST, four of the standard facts, one of + which ("unique") is not enabled by default, and several OS dependent + facts, one of which is provided by the server by default. This + server actually supported more OS dependent facts. Others were + deleted for the purposes of this document to comply with document + formatting restrictions. + +8.9. OPTS parameters for MLST + + For the MLSx commands, the Client-FTP may specify a list of facts it + wishes to be returned in all subsequent MLSx commands until another + OPTS MLST command is sent. The format is specified by: + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 51] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + mlst-opts = "OPTS" SP "MLST" + [ SP 1*( factname ";" ) ] + + By sending the "OPTS MLST" command, the client requests the server to + include only the facts listed as arguments to the command in + subsequent output from MLSx commands. Facts not included in the + "OPTS MLST" command MUST NOT be returned by the server. Facts that + are included should be returned for each entry returned from the MLSx + command where they meaningfully apply. Facts requested that are not + supported, or which are inappropriate to the file or directory being + listed should simply be omitted from the MLSx output. This is not an + error. Note that where no factname arguments are present, the client + is requesting that only the file names be returned. In this case, + and in any other case where no facts are included in the result, the + space that separates the fact names and their values from the file + name is still required. That is, the first character of the output + line will be a space, (or two characters will be spaces when the line + is returned over the control connection,) and the file name will + start immediately thereafter. + + Clients should note that generating values for some facts can be + possible, but very expensive, for some servers. It is generally + acceptable to retrieve any of the facts that the server offers as its + default set before any "OPTS MLST" command has been given, however + clients should use particular caution before requesting any facts not + in that set. That is, while other facts may be available from the + server, clients should refrain from requesting such facts unless + there is a particular operational requirement for that particular + information, which ought be more significant than perhaps simply + improving the information displayed to an end user. + + Note, there is no "OPTS MLSD" command, the fact names set with the + "OPTS MLST" command apply to both MLST and MLSD commands. + + Servers are not required to accept "OPTS MLST" commands before + authentication of the user-PI, but may choose to permit them. + +8.9.1. OPTS MLST Response + + The "response-message" from [6] to a successful OPTS MLST command has + the following syntax. + + mlst-opt-resp = "MLST OPTS" [ SP 1*( factname ";" ) ] + + This defines the "response-message" as used in the "opts-good" + message in RFC2389 [6]. + + + + + +Elz & Hethmon [Expires April 2000] [Page 52] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + The facts named in the response are those which the server will now + include in MLST (and MLSD) response, after the processing of the + "OPTS MLST" command. Any facts from the request not supported by the + server will be omitted from this response message. If no facts will + be included, the list of facts will be empty. Note that the list of + facts returned will be the same as those marked by a trailing + asterisk ("*") in a subsequent FEAT command response. There is no + requirement that the order of the facts returned be the same as that + in which they were requested, or that in which they will be listed in + a FEAT command response, or that in which facts are returned in MLST + responses. The fixed string "MLST OPTS" in the response may be + returned in any case, or mixture of cases. + +8.9.2. Examples + + C> Feat + S> 211- Features supported + S> MLST Type*;Size;Modify*;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + C> OptS Mlst Type;UNIX.mode;Perm; + S> 201 MLST OPTS Type;Perm;UNIX.mode; + C> Feat + S> 211- Features supported + S> MLST Type*;Size;Modify;Perm*;Unique;UNIX.mode*;UNIX.chgd;X.hidden; + S> 211 End + C> opts MLst lang;type;charset;create; + S> 201 MLST OPTS Type; + C> Feat + S> 211- Features supported + S> MLST Type*;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + C> OPTS mlst size;frogs; + S> 201 MLST OPTS Size; + C> Feat + S> 211- Features supported + S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + C> opts MLst unique type; + S> 501 Invalid MLST options + C> Feat + S> 211- Features supported + S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + + For the purposes of this example, features other than MLST have been + deleted from the output to avoid clutter. The example shows the + initial default feature output for MLST. The facts requested are + then changed by the client. The first change shows facts that are + + + +Elz & Hethmon [Expires April 2000] [Page 53] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + available from the server being selected. Subsequent FEAT output + shows the altered features as being returned. The client then + attempts to select some standard features which the server does not + support. This is not an error, however the server simply ignores the + requests for unsupported features, as the FEAT output that follows + shows. Then, the client attempts to request a non-standard, and + unsupported, feature. The server ignores that, and selects only the + supported features requested. Lastly, the client sends a request + containing a syntax error (spaces cannot appear in the factlist.) The + server-FTP sends an error response and completely ignores the + request, leaving the fact set selected as it had been previously. + + Note that in all cases, except the error response, the response lists + the facts that have been selected. + + C> Feat + S> 211- Features supported + S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + C> Opts MLST + S> 201 MLST OPTS + C> Feat + S> 211- Features supported + S> MLST Type;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; + S> 211 End + C> MLst tmp + S> 250- Listing tmp + S> /tmp + S> 250 End + C> OPTS mlst unique;size; + S> 201 MLST OPTS Size;Unique; + C> MLst tmp + S> 250- Listing tmp + S> Unique=keVO1+YZ5; /tmp + S> 250 End + C> OPTS mlst unique;type;modify; + S> 201 MLST OPTS Type;Modify;Unique; + C> MLst tmp + S> 250- Listing tmp + S> Type=dir;Modify=19990930152225;Unique=keVO1+YZ5; /tmp + S> 250 End + C> OPTS mlst fish;cakes; + S> 201 MLST OPTS + C> MLst tmp + S> 250- Listing tmp + S> /tmp + S> 250 End + C> OptS Mlst Modify;Unique; + + + +Elz & Hethmon [Expires April 2000] [Page 54] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + S> 201 MLST OPTS Modify;Unique; + C> MLst tmp + S> 250- Listing tmp + S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp + S> 250 End + C> opts MLst fish cakes; + S> 501 Invalid MLST options + C> MLst tmp + S> 250- Listing tmp + S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp + S> 250 End + + This example shows the effect of changing the facts requested upon + subsequent MLST commands. Notice that a syntax error leaves the set + of selected facts unchanged. Also notice exactly two spaces + preceding the pathname when no facts were selected, either + deliberately, or because none of the facts requested were available. + +9. Impact On Other FTP Commands + + Along with the introduction of MLST, traditional FTP commands must be + extended to allow for the use of more than US-ASCII or EBCDIC + character sets. In general, the support of MLST requires support for + arbitrary character sets wherever filenames and directory names are + allowed. This applies equally to both arguments given to the + following commands and to the replies from them, as appropriate. + + CWD + RETR + STOR + STOU + APPE + RNFR + RNTO + DELE + RMD + MKD + PWD + STAT + + The arguments to all of these commands should be processed the same + way that MLST commands and responses are processed with respect to + handling embedded spaces, CRs and NULs. See section 2.2. + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 55] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +10. Character sets and Internationalization + + FTP commands are protocol elements, and are always expressed in + ASCII. FTP responses are composed of the numeric code, which is a + protocol element, and a message, which is often expected to convey + information to the user. It is not expected that users normally + interact directly with the protocol elements, rather the user FTP- + process constructs the commands, and interprets the results, in the + manner best suited for the particular user. Explanatory text in + responses generally has no particular meaning to the protocol. The + numeric codes provide all necessary information. Server-PIs are free + to provide the text in any language that can be adequately + represented in ASCII, or where an alternative language and + representation has been negotiated (see [7]) in that language and + representation. + + Pathnames are expected to be encoded in UTF-8 allowing essentially + any character to be represented in a pathname. Meaningful pathnames + are defined by the server NVFS. + + No restrictions at all are placed upon the contents of files + transferred using the FTP protocols. Unless the "media-type" fact is + provided in a MLSx response nor is any advice given here which would + allow determining the content type. That information is assumed to + be obtained via other means. + +11. IANA Considerations + + This specification makes use of some lists of values currently + maintained by the IANA, and creates two new lists for the IANA to + maintain. It does not add any values to any existing registries. + + The existing IANA registries used by this specification are modified + using mechanisms specified elsewhere. + +11.1. The OS specific fact registry + + A registry of OS specific fact names shall be maintained by the IANA. + The OS names for the OS portion of the fact name must be taken from + the IANA's list of registered OS names. To add a fact name to this + OS specific registry of OS specific facts, an applicant must send to + the IANA a request, in which is specified the OS name, the OS + specific fact name, a definition of the syntax of the fact value, + which must conform to the syntax of a token as given in this + document, and a specification of the semantics to be associated with + the particular fact and its values. Upon receipt of such an + application, and if the combination of OS name and OS specific fact + name has not been previously defined, the IANA will add the + + + +Elz & Hethmon [Expires April 2000] [Page 56] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + specification to the registry. + + Any examples of OS specific facts found in this document are to be + treated as examples of possible OS specific facts, and do not form a + part of the IANA's registry merely because of being included in this + document. + +11.2. The OS specific filetype registry + + A registry of OS specific file types shall be maintained by the IANA. + The OS names for the OS portion of the fact name must be taken from + the IANA's list of registered OS names. To add a file type to this + OS specific registry of OS specific file types, an applicant must + send to the IANA a request, in which is specified the OS name, the OS + specific file type, a definition of the syntax of the fact value, + which must conform to the syntax of a token as given in this + document, and a specification of the semantics to be associated with + the particular fact and its values. Upon receipt of such an + application, and if the combination of OS name and OS specific file + type has not been previously defined, the IANA will add the + specification to the registry. + + Any examples of OS specific file types found in this document are to + be treated as potential OS specific file types only, and do not form + a part of the IANA's registry merely because of being included in + this document. + +12. Security Considerations + + This memo does not directly concern security. It is not believed + that any of the mechanisms documented here impact in any particular + way upon the security of FTP. + + Implementing the SIZE command, and perhaps some of the facts of the + MDLx commands, may impose a considerable load on the server, which + could lead to denial of service attacks. Servers have, however, + implemented this for many years, without significant reported + difficulties. + + With the introduction of virtual hosts to FTP, and the possible + accompanying multiple authentication environments, server + implementors will need to take some care to ensure that integrity is + maintained. + + The FEAT and OPTS commands may be issued before the FTP + authentication has occurred [6]. This allows unauthenticated clients + to determine which of the features defined here are supported, and to + negotiate the fact list for MLSx output. No actual MLSx commands may + + + +Elz & Hethmon [Expires April 2000] [Page 57] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + be issued however, and no problems with permitting the selection of + the format prior to authentication are foreseen. + + A general discussion of issues related to the security of FTP can be + found in [14]. + +13. References + + [1] Coded Character Set--7-bit American Standard Code for Information + Interchange, ANSI X3.4-1986. + + [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO + 10646", RFC 2044, October 1996. + + [3] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", + STD 9, RFC 959, October 1985 + + [4] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997 + + [5] Crocker, D., Overell, P., "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997 + + [6] Hethmon, P., Elz, R., "Feature negotiation mechanism for the + File Transfer Protocol", RFC 2389, August 1998 + + [7] Curtin, W., "Internationalization of the File Transfer Protocol", + RFC 2640, July 1999 + + [8] Postel, J., Reynolds, J., "Telnet protocol Specification" + STD 8, RFC 854, May 1983 + + [9] Braden, R,. "Requirements for Internet Hosts -- Application + and Support", STD 3, RFC 1123, October 1989 + + [10] Mockapetris, P., "Domain Names - Concepts and Facilities" + STD 13, RFC 1034, November 1987 + + [11] ISO/IEC 10646-1:1993 "Universal multiple-octet coded character set + (UCS) -- Part 1: Architecture and basic multilingual plane", + International Standard -- Information Technology, 1993 + + [12] Internet Assigned Numbers Authority. http://www.iana.org + Email: iana@iana.org. + + [13] Alvestrand, H., "Tags for the Identification of Languages" + RFC 1766, March 1995 + + + + +Elz & Hethmon [Expires April 2000] [Page 58] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + + [14] Allman, M., Ostermann, S., "FTP Security Considerations" + RFC 2577, May 1999 + +Acknowledgments + + This document is a product of the FTPEXT working group of the IETF. + + The following people are among those who have contributed to this + document: + + Alex Belits + D. J. Bernstein + Dave Cridland + Martin J. Duerst + Mike Gleason + Mark Harris + Alun Jones + James Matthews + Luke Mewburn + Jan Mikkelsen + Keith Moore + Buz Owen + Mark Symons + Stephen Tihor + and the entire FTPEXT working group of the IETF. + + Apologies are offered to any inadvertently omitted. + + Bernhard Rosenkraenzer suggested the HOST command, and initially + described it. + + The description of the modifications to the REST command and the MDTM + and SIZE commands comes from a set of modifications suggested for + RFC959 by Rick Adams in 1989. A draft containing just those + commands, edited by David Borman, has been merged with this document. + + Mike Gleason provided access to the FTP server used in some of the + examples. + + All of the examples in this document are taken from actual + client/server exchanges, though some have been edited for brevity, or + to meet document formatting requirements. + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 59] + + +Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 + + +Copyright + + This document is in the public domain. Any and all copyright + protection that might apply in any jurisdiction is expressly + disclaimed. + +Editors' Addresses + + Robert Elz + University of Melbourne + Department of Computer Science + Parkville, Vic 3052 + Australia + + Email: kre@munnari.OZ.AU + + + Paul Hethmon + Hethmon Brothers + 2305 Chukar Road + Knoxville, TN 37923 USA + + Phone: +1 423 690 8990 + Email: phethmon@hethmon.com + + + + + + + + + + + + + + + + + + + + + + + + + + + +Elz & Hethmon [Expires April 2000] [Page 60] diff --git a/crypto/heimdal/doc/standardisation/rfc1508.txt b/crypto/heimdal/doc/standardisation/rfc1508.txt new file mode 100644 index 0000000..132b855 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1508.txt @@ -0,0 +1,2747 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1508 Geer Zolot Associates + September 1993 + + + Generic Security Service Application Program Interface + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This Generic Security Service Application Program Interface (GSS-API) + definition provides security services to callers in a generic + fashion, supportable with a range of underlying mechanisms and + technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of underlying + mechanism and programming language environment, and is to be + complemented by other, related specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to + be implemented in order to realize GSS-API services atop + particular security mechanisms + +Table of Contents + + 1. GSS-API Characteristics and Concepts ....................... 2 + 1.1. GSS-API Constructs ....................................... 5 + 1.1.1. Credentials ........................................... 5 + 1.1.2. Tokens ................................................ 6 + 1.1.3. Security Contexts ..................................... 7 + 1.1.4. Mechanism Types ....................................... 8 + 1.1.5. Naming ................................................ 9 + 1.1.6. Channel Bindings ...................................... 10 + 1.2. GSS-API Features and Issues ............................. 11 + 1.2.1. Status Reporting ...................................... 11 + 1.2.2. Per-Message Security Service Availability ............. 12 + 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 + 1.2.4. Quality of Protection ................................. 15 + + + +Linn [Page 1] + +RFC 1508 Generic Security Interface September 1993 + + + 2. Interface Descriptions ..................................... 15 + 2.1. Credential management calls ............................. 17 + 2.1.1. GSS_Acquire_cred call ................................. 17 + 2.1.2. GSS_Release_cred call ................................. 19 + 2.1.3. GSS_Inquire_cred call ................................. 20 + 2.2. Context-level calls ..................................... 21 + 2.2.1. GSS_Init_sec_context call ............................. 21 + 2.2.2. GSS_Accept_sec_context call ........................... 26 + 2.2.3. GSS_Delete_sec_context call ........................... 29 + 2.2.4. GSS_Process_context_token call ........................ 30 + 2.2.5. GSS_Context_time call ................................. 31 + 2.3. Per-message calls ....................................... 32 + 2.3.1. GSS_Sign call ......................................... 32 + 2.3.2. GSS_Verify call ....................................... 33 + 2.3.3. GSS_Seal call ......................................... 35 + 2.3.4. GSS_Unseal call ....................................... 36 + 2.4. Support calls ........................................... 37 + 2.4.1. GSS_Display_status call ............................... 37 + 2.4.2. GSS_Indicate_mechs call ............................... 38 + 2.4.3. GSS_Compare_name call ................................. 38 + 2.4.4. GSS_Display_name call ................................. 39 + 2.4.5. GSS_Import_name call .................................. 40 + 2.4.6. GSS_Release_name call ................................. 41 + 2.4.7. GSS_Release_buffer call ............................... 41 + 2.4.8. GSS_Release_oid_set call .............................. 42 + 3. Mechanism-Specific Example Scenarios ....................... 42 + 3.1. Kerberos V5, single-TGT ................................. 43 + 3.2. Kerberos V5, double-TGT ................................. 43 + 3.3. X.509 Authentication Framework .......................... 44 + 4. Related Activities ......................................... 45 + 5. Acknowledgments ............................................ 46 + 6. Security Considerations .................................... 46 + 7. Author's Address ........................................... 46 + Appendix A .................................................... 47 + Appendix B .................................................... 48 + Appendix C .................................................... 49 + +1. GSS-API Characteristics and Concepts + + The operational paradigm in which GSS-API operates is as follows. A + typical GSS-API caller is itself a communications protocol, calling + on GSS-API in order to protect its communications with + authentication, integrity, and/or confidentiality security services. + A GSS-API caller accepts tokens provided to it by its local GSS-API + implementation and transfers the tokens to a peer on a remote system; + that peer passes the received tokens to its local GSS-API + implementation for processing. The security services available + through GSS-API in this fashion are implementable (and have been + + + +Linn [Page 2] + +RFC 1508 Generic Security Interface September 1993 + + + implemented) over a range of underlying mechanisms based on secret- + key and public-key cryptographic technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and + GSS_Accept_sec_context() calls), from the operations of providing + per-message data origin authentication and data integrity protection + (GSS_Sign() and GSS_Verify() calls) for messages subsequently + transferred in conjunction with that context. Per-message GSS_Seal() + and GSS_Unseal() calls provide the data origin authentication and + data integrity services which GSS_Sign() and GSS_Verify() offer, and + also support selection of confidentiality services as a caller + option. Additional calls provide supportive functions to the GSS- + API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example assumes that the + underlying authentication technology is capable of authenticating a + client to a server using elements carried within a single token, and + of authenticating the server to the client (mutual authentication) + with a single returned token; this assumption holds for presently- + documented CAT mechanisms but is not necessarily true for other + cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + output_token to be passed to the server, and indicates + GSS_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_COMPLETE status. The client sends the output_token to the server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_COMPLETE status, provides the client's authenticated identity in + the src_name result, and provides an output_token to be passed to the + client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + + + +Linn [Page 3] + +RFC 1508 Generic Security Interface September 1993 + + + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_COMPLETE status, indicating successful mutual authentication and + the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Seal(). + GSS_Seal() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + encapsulates the result into output_message, indicating GSS_COMPLETE + status. The client sends the output_message to the server. + + The server passes the received message to GSS_Unseal(). GSS_Unseal + inverts the encapsulation performed by GSS_Seal(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unseal() indicates successful validation by + returning GSS_COMPLETE status along with the resultant + output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. GSS_Delete_sec_context() returns a + context_token for the server to pass to the client. + + The client passes the returned context_token to + GSS_Process_context_token(), which returns GSS_COMPLETE status after + deleting context-level information at the client system. + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, thereby + invoking GSS-API facilities in conjunction with that protocol's + + + +Linn [Page 4] + +RFC 1508 Generic Security Interface September 1993 + + + communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1. GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1. Credentials + + Credentials structures provide the prerequisites enabling peers to + establish security contexts with each other. A caller may designate + that its default credential be used for context establishment calls + without presenting an explicit handle to that credential. + Alternately, those GSS-API callers which need to make explicit + selection of particular credentials structures may make references to + those credentials through GSS-API-provided credential handles + ("cred_handles"). + + A single credential structure may be used for initiation of outbound + contexts and acceptance of inbound contexts. Callers needing to + operate in only one of these modes may designate this fact when + credentials are acquired for use, allowing underlying mechanisms to + optimize their processing and storage requirements. The credential + elements defined by a particular mechanism may contain multiple + cryptographic keys, e.g., to enable authentication and message + encryption to be performed with different algorithms. + + A single credential structure may accommodate credential information + associated with multiple underlying mechanisms (mech_types); a + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target; the + primary motivation for supporting credential sets representing + multiple mech_types is to allow initiators on systems which are + + + +Linn [Page 5] + +RFC 1508 Generic Security Interface September 1993 + + + equipped to handle multiple types to initiate contexts to targets on + other systems which can accommodate only a subset of the set + supported at the initiator's system. + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + as the default credentials installed on behalf of a process + +1.1.2. Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens are exchanged in conjunction with an established context to + provide protective security services for corresponding data messages. + The internal contents of both classes of tokens are specific to the + particular underlying mechanism used to support the GSS-API; Appendix + B of this document provides a uniform recommendation for designers of + GSS-API support mechanisms, encapsulating mechanism-specific + information along with a globally-interpretable mechanism identifier. + + + + +Linn [Page 6] + +RFC 1508 Generic Security Interface September 1993 + + + Tokens are opaque from the viewpoint of GSS-API callers. They are + generated within the GSS-API implementation at an end system, + provided to a GSS-API caller to be transferred to the peer GSS-API + caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. Tokens may be output by + GSS-API primitives (and are to be transferred to GSS-API peers) + independent of the status indications which those primitives + indicate. Token transfer may take place in an in-band manner, + integrated into the same protocol stream used by the GSS-API callers + for other data transfers, or in an out-of-band manner across a + logically separate channel. + + Development of GSS-API support primitives based on a particular + underlying cryptographic technique and protocol does not necessarily + imply that GSS-API callers invoking that GSS-API mechanism type will + be able to interoperate with peers invoking the same technique and + protocol outside the GSS-API paradigm. For example, the format of + GSS-API tokens defined in conjunction with a particular mechanism, + and the techniques used to integrate those tokens into callers' + protocols, may not be the same as those used by non-GSS-API callers + of the same underlying technique. + +1.1.3. Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + + + +Linn [Page 7] + +RFC 1508 Generic Security Interface September 1993 + + + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. + +1.1.4. Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name + + lookup of a target's name in a naming service or other database in + order to identify mech_types supported by that target + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Appendix B, represented as Object Identifiers (OIDs)) serve to + qualify the interpretation of associated tokens. (The structure and + encoding of Object Identifiers is defined in ISO/IEC 8824, + "Specification of Abstract Syntax Notation One (ASN.1)" and in + ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract + Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs + serves to preclude ambiguous interpretation of mech_type specifiers. + + + +Linn [Page 8] + +RFC 1508 Generic Security Interface September 1993 + + + The OID representing the DASS MechType, for example, is + 1.3.12.2.1011.7.5. + +1.1.5. Naming + + The GSS-API avoids prescription of naming structures, treating the + names transferred across the interface in order to initiate and + accept security contexts as opaque octet string quantities. This + approach supports the GSS-API's goal of implementability atop a range + of underlying security mechanisms, recognizing the fact that + different mechanisms process and authenticate names which are + presented in different forms. Generalized services offering + translation functions among arbitrary sets of naming environments are + outside the scope of the GSS-API; availability and use of local + conversion functions to translate among the naming formats supported + within a given end system is anticipated. + + Two distinct classes of name representations are used in conjunction + with different GSS-API parameters: + + a printable form (denoted by OCTET STRING), for acceptance from + and presentation to users; printable name forms are accompanied by + OID tags identifying the namespace to which they correspond + + an internal form (denoted by INTERNAL NAME), opaque to callers and + defined by individual GSS-API implementations; GSS-API + implementations supporting multiple namespace types are + responsible for maintaining internal tags to disambiguate the + interpretation of particular names + + Tagging of printable names allows GSS-API callers and underlying + GSS-API mechanisms to disambiguate name types and to determine + whether an associated name's type is one which they are capable of + processing, avoiding aliasing problems which could result from + misinterpreting a name of one type as a name of another type. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), and internal name deallocation + (GSS_Release_name()) functions are defined. (It is anticipated that + these proposed GSS-API calls will be implemented in many end systems + based on system-specific name manipulation primitives already extant + within those end systems; inclusion within the GSS-API is intended to + + + +Linn [Page 9] + +RFC 1508 Generic Security Interface September 1993 + + + offer GSS-API callers a portable means to perform specific + operations, supportive of authorization and audit requirements, on + authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + +1.1.6. Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information, used by GSS-API callers to bind + the establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel and of protection mechanisms + applied to that communications channel. Verification by one peer of + chan_binding information provided by the other peer to a context + serves to protect against various active attacks. The caller + initiating a security context must determine the chan_binding values + before making the GSS_Init_sec_context() call, and consistent values + must be provided by both peers to a context. Callers should not + assume that underlying mechanisms provide confidentiality protection + for channel binding information. + + Use or non-use of the GSS-API channel binding facility is a caller + option, and GSS-API supporting mechanisms can support operation in an + environment where NULL channel bindings are presented. When non-NULL + channel bindings are used, certain mechanisms will offer enhanced + security value by interpreting the bindings' content (rather than + simply representing those bindings, or signatures computed on them, + within tokens) and will therefore depend on presentation of specific + data in a defined format. To this end, agreements among mechanism + implementors are defining conventional interpretations for the + contents of channel binding arguments, including address specifiers + (with content dependent on communications protocol environment) for + context initiators and acceptors. (These conventions are being + incorporated into related documents.) In order for GSS-API callers to + be portable across multiple mechanisms and achieve the full security + functionality available from each mechanism, it is strongly + recommended that GSS-API callers provide channel bindings consistent + + + +Linn [Page 10] + +RFC 1508 Generic Security Interface September 1993 + + + with these conventions and those of the networking environment in + which they operate. + +1.2. GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1. Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to + drive normal control flow within the caller in a generic fashion. + Table 1 summarizes the defined major_status return codes in tabular + fashion. + + Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_BAD_BINDINGS channel binding mismatch + GSS_BAD_MECH unsupported mechanism requested + GSS_BAD_NAME invalid name provided + GSS_BAD_NAMETYPE name of unsupported type provided + GSS_BAD_STATUS invalid input status selector + GSS_BAD_SIG token had invalid signature + GSS_CONTEXT_EXPIRED specified security context expired + GSS_CREDENTIALS_EXPIRED expired credentials detected + GSS_DEFECTIVE_CREDENTIAL defective credential detected + GSS_DEFECTIVE_TOKEN defective token detected + GSS_FAILURE failure, unspecified at GSS-API + level + GSS_NO_CONTEXT no valid security context specified + GSS_NO_CRED no valid credentials provided + + INFORMATORY STATUS CODES + + GSS_COMPLETE normal completion + GSS_CONTINUE_NEEDED continuation call to routine + required + GSS_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_OLD_TOKEN timed-out per-message token + detected + GSS_UNSEQ_TOKEN out-of-order per-message token + detected + + + +Linn [Page 11] + +RFC 1508 Generic Security Interface September 1993 + + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + GSS_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accomodated with + sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.2. Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should + check the values of these flags at context establishment time, and + must be aware that a returned FALSE value for integ_avail means + that invocation of GSS_Sign() or GSS_Seal() primitives on the + associated context will apply no cryptographic protection to user + data messages. + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Seal(), encapsulate the protected data unit. + + + +Linn [Page 12] + +RFC 1508 Generic Security Interface September 1993 + + + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3. Per-Message Replay Detection and Sequencing + + Certain underlying mech_types are expected to offer support for + replay detection and/or sequencing of messages transferred on the + contexts they support. These optionally-selectable protection + features are distinct from replay detection and sequencing features + applied to the context establishment operation itself; the presence + or absence of context-level replay or sequencing features is wholly a + function of the underlying mech_type's capabilities, and is not + selected or omitted as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of mech_type, without need + for bilateral negotiation with the target. When enabled, these + features provide recipients with indicators as a result of GSS-API + processing of incoming messages, identifying whether those messages + were detected as duplicates or out-of-sequence. Detection of such + events does not prevent a suspect message from being provided to a + recipient; the appropriate course of action on a suspect message is a + matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the message is too old to be checked + for duplication. + + + +Linn [Page 13] + +RFC 1508 Generic Security Interface September 1993 + + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + 2. GSS_DUPLICATE_TOKEN indicates that the signature on the + received message was correct, but that the message was recognized + as a duplicate of a previously-processed message. + + 3. GSS_OLD_TOKEN indicates that the signature on the received + message was correct, but that the token is too old to be checked + for duplication. + + 4. GSS_UNSEQ_TOKEN indicates that the signature on the received + message was correct, but that it is earlier in a sequenced stream + than a message already processed on the context. [Note: + Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_Sign() and GSS_Seal(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_Verify() and + + + +Linn [Page 14] + +RFC 1508 Generic Security Interface September 1993 + + + GSS_Unseal(). When this feature is active, exception status returns + (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when + GSS_Verify() or GSS_Unseal() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4. Quality of Protection + + Some mech_types will provide their users with fine granularity + control over the means used to provide per-message protection, + allowing callers to trade off security processing overhead + dynamically against the protection requirements of particular + messages. A per-message quality-of-protection parameter (analogous to + quality-of-service, or QOS) selects among different QOP options + supported by that mechanism. On context establishment for a multi-QOP + mech_type, context-level data provides the prerequisite data for a + range of protection qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. + +2. Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + + + + + + + + + + + + + + +Linn [Page 15] + +RFC 1508 Generic Security Interface September 1993 + + + Table 2: GSS-API Calls + + CREDENTIAL MANAGEMENT + + GSS_Acquire_cred acquire credentials for use + GSS_Release_cred release credentials after use + GSS_Inquire_cred display information about + credentials + + CONTEXT-LEVEL CALLS + + GSS_Init_sec_context initiate outbound security context + GSS_Accept_sec_context accept inbound security context + GSS_Delete_sec_context flush context when no longer needed + GSS_Process_context_token process received control token on + context + GSS_Context_time indicate validity time remaining on + context + + PER-MESSAGE CALLS + + GSS_Sign apply signature, receive as token + separate from message + GSS_Verify validate signature token along with + message + GSS_Seal sign, optionally encrypt, + encapsulate + GSS_Unseal decapsulate, decrypt if needed, + validate signature + + SUPPORT CALLS + + GSS_Display_status translate status codes to printable + form + GSS_Indicate_mechs indicate mech_types supported on + local system + GSS_Compare_name compare two names for equality + GSS_Display_name translate name to printable form + GSS_Import_name convert printable name to + normalized form + GSS_Release_name free storage of normalized-form + name + GSS_Release_buffer free storage of printable name + GSS_Release_oid_set free storage of OID set object + + + + + + + +Linn [Page 16] + +RFC 1508 Generic Security Interface September 1993 + + +2.1. Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. + +2.1.1. GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -NULL requests locally-determined + default + + o lifetime_req INTEGER,-in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests + system-selected default + + o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle OCTET STRING, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + + +Linn [Page 17] + +RFC 1508 Generic Security Interface September 1993 + + + Return major_status codes: + + o GSS_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in + lifetime_rec, suitable for the usage requested in cred_usage, for + the set of mech_types indicated in actual_mechs, and that those + credentials can be referenced for subsequent use with the handle + returned in output_cred_handle. + + o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API + implementation type was requested, causing the credential + establishment operation to fail. + + o GSS_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the supporting GSS-API + implementation, so no credentials could be established for the + accompanying desired_name. + + o GSS_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_FAILURE indicates that credential establishment failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish and use credentials associated with the + identity named in the input desired_name argument. + + GSS_Acquire_cred() is used to acquire credentials so that a + principal can (as a function of the input cred_usage parameter) + initiate and/or accept security contexts under the identity + represented by the desired_name input argument. On successful + completion, the returned output_cred_handle result provides a handle + for subsequent references to the acquired credentials. Typically, + single-user client processes using only default credentials for + context establishment purposes will have no need to invoke this call. + + A caller may provide the value NULL for desired_name, signifying a + request for credentials corresponding to a default principal + identity. The procedures used by GSS-API implementations to select + the appropriate principal identity in response to this form of + request are local matters. It is possible that multiple pre- + established credentials may exist for the same principal identity + (for example, as a result of multiple user login sessions) when + GSS_Acquire_cred() is called; the means used in such cases to select + a specific credential are local matters. The input lifetime_req + argument to GSS_Acquire_cred() may provide useful information for + local GSS-API implementations to employ in making this disambiguation + + + +Linn [Page 18] + +RFC 1508 Generic Security Interface September 1993 + + + in a manner which will best satisfy a caller's intent. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2. GSS_Release_cred call + + Input: + + o cred_handle OCTET STRING-NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent access + by the caller. The effect on other processes which may be + authorized shared access to such credentials is a local matter. + + + + + +Linn [Page 19] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no release operation was performed, + either because the input cred_handle was invalid or because the + caller lacks authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3. GSS_Inquire_cred call + + Input: + + o cred_handle OCTET STRING -NULL specifies default credentials + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output + cred_name, lifetime_rec, and cred_usage values represent, + respectively, the credentials' associated principal name, + remaining lifetime, suitable usage modes, and supported + mechanism types. + + + +Linn [Page 20] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + o GSS_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of + those callers which make use of default credentials rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + +2.2. Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). Either party to an established context may + invoke GSS_Delete_sec_context() to flush context information when a + context is no longer required. GSS_Process_context_token() is used + to process received tokens carrying context-level control + information. GSS_Context_time() allows a caller to determine the + length of time for which an established context will remain valid. + +2.2.1. GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle OCTET STRING, -NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "none assigned + yet" + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use + default" + + o deleg_req_flag BOOLEAN, + + + +Linn [Page 21] + +RFC 1508 Generic Security Interface September 1993 + + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o lifetime_req INTEGER,-0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING-NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_handle INTEGER, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + + + +Linn [Page 22] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token will + provide sufficient information for the target to perform per- + message processing on the newly-established context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a reply + must be received and passed as the input_token argument to a + continuation call to GSS_Init_sec_context(), before per-message + processing can be performed in conjunction with this context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context acceptor use only, or because + the caller lacks authorization to access the referenced + credentials. + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input claimant_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. (This result will be returned by + GSS_Init_sec_context only for contexts where mutual_state is + TRUE.) + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a + type uninterpretable or unsupported by the supporting GSS-API + implementation, so context establishment cannot be completed. + + + +Linn [Page 23] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided targ_name is inconsistent + in terms of internally-incorporated type specifier information, so + context establishment cannot be accomplished. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. Using information in the credentials structure + referenced by claimant_cred_handle, GSS_Init_sec_context() + initializes the data structures required to establish a security + context with target targ_name. The claimant_cred_handle must + correspond to the same valid credentials structure on the initial + call to GSS_Init_sec_context() and on any successor calls resulting + from GSS_CONTINUE_NEEDED status returns; different protocol sequences + modeled by the GSS_CONTINUE_NEEDED mechanism will require access to + credentials at different points in the context establishment + sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Init_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context. When continuation attempts to + GSS_Init_sec_context() are needed to perform context establishment, + the previously-returned non-zero handle value is entered into the + input_context_handle argument and will be echoed in the returned + output_context_handle argument. On such continuation attempts (and + only on continuation attempts) the input_token value is used, to + provide the token returned from the context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + + + +Linn [Page 24] + +RFC 1508 Generic Security Interface September 1993 + + + the first application-provided input message to be processed by + GSS_Sign() or GSS_Seal() in conjunction with a successfully- + established context. + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + 1.2.3 for more information on replay detection and sequencing + features.) + + Not all of the optionally-requestable features will be available in + all underlying mech_types; the corresponding return state values + (deleg_state, mutual_state, replay_det_state, sequence_state) + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. These state indicators' values are undefined + unless the routine's major_status indicates COMPLETE. Failure to + provide the precise set of features requested by the caller does not + cause context establishment to fail; it is the caller's prerogative + to delete the context if the feature set provided is unsuitable for + the caller's use. The returned mech_type value indicates the + specific mechanism employed on the context, and will never indicate + the value for "default". + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The values of conf_avail, + integ_avail, and lifetime_rec are undefined unless the routine's + major_status indicates COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + + + +Linn [Page 25] + +RFC 1508 Generic Security Interface September 1993 + + + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to achieve + mutual authentication. + +2.2.2. GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle OCTET STRING,-NULL specifies "use + default" + + o input_context_handle INTEGER, -0 specifies "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle INTEGER, + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle OCTET STRING, + + o output_token OCTET STRING -NULL or token to pass to context + + + +Linn [Page 26] + +RFC 1508 Generic Security Interface September 1993 + + + initiator + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_COMPLETE indicates that context-level data structures were + successfully initialized, and that per-message processing can now + be performed in conjunction with this context. + + o GSS_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that a + response must be received and passed as the input_token argument + to a continuation call to GSS_Accept_sec_context(), before per- + message processing can be performed in conjunction with this + context. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the input_token failed, preventing further processing from being + performed based on that token. + + o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_BAD_SIG indicates that the received input_token contains an + incorrect signature, so context setup cannot be accomplished. + + o GSS_DUPLICATE_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token was recognized + as a duplicate of an input_token already processed. No new context + is established. + + o GSS_OLD_TOKEN indicates that the signature on the received + input_token was correct, but that the input_token is too old to be + checked for duplication against previously-processed input_tokens. + No new context is established. + + o GSS_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the referenced + credentials are valid for context initiator use only, or because + the caller lacks authorization to access the referenced + credentials. + + + + +Linn [Page 27] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no longer + valid, so context establishment cannot be completed. + + o GSS_BAD_BINDINGS indicates that a mismatch between the caller- + provided chan_bindings and those extracted from the input_token + was detected, signifying a security-relevant event and preventing + context establishment. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided; this major status will be + returned only for successor calls following GSS_CONTINUE_NEEDED + status returns. + + o GSS_FAILURE indicates that context setup could not be accomplished + for reasons unspecified at the GSS-API level, and that no + interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The acceptor_cred_handle must correspond to the same valid + credentials structure on the initial call to GSS_Accept_sec_context() + and on any successor calls resulting from GSS_CONTINUE_NEEDED status + returns; different protocol sequences modeled by the + GSS_CONTINUE_NEEDED mechanism will require access to credentials at + different points in the context establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Accept_sec_context() call relating to a + given context. That call returns an output_context_handle for future + references to this context; when continuation attempts to + GSS_Accept_sec_context() are needed to perform context + establishment, that handle value will be entered into the + input_context_handle argument. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, and sequence_state) reflect the same context state + values as returned to GSS_Init_sec_context()'s caller at the + initiator system. + + + +Linn [Page 28] + +RFC 1508 Generic Security Interface September 1993 + + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Seal() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_Sign() or GSS_Seal()) on + the established context. + + The lifetime_rec return value indicates the length of time for which + the context will be valid, expressed as an offset from the present. + The values of deleg_state, mutual_state, replay_det_state, + sequence_state, conf_avail, integ_avail, and lifetime_rec are + undefined unless the accompanying major_status indicates COMPLETE. + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_Verify() or GSS_Unseal(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3. GSS_Delete_sec_context call + + Input: + + o context_handle INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_token OCTET STRING + + Return major_status codes: + + + + + +Linn [Page 29] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_COMPLETE indicates that the context was recognized, that + relevant context-specific information was flushed, and that the + returned output_context_token is ready for transfer to the + context's peer. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provide, so no deletion was performed. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Delete_sec_context() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call may block pending network interactions for mech_types in + which active notification must be made to a central server when a + security context is to be deleted. + + This call can be made by either peer in a security context, to flush + context-specific information and to return an output_context_token + which can be passed to the context's peer informing it that the + peer's corresponding context information can also be flushed. (Once a + context is established, the peers involved are expected to retain + cached credential and context-related information until the + information's expiration time is reached or until a + GSS_Delete_sec_context() call is made.) Attempts to perform per- + message processing on a deleted context will result in error returns. + +2.2.4. GSS_Process_context_token call + + Inputs: + + o context_handle INTEGER, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context referenced + by context_handle. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received context_token failed, preventing further processing + + + +Linn [Page 30] + +RFC 1508 Generic Security Interface September 1993 + + + from being performed with that token. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Process_context_token() operation could not be performed for + reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_COMPLETE status. + +2.2.5. GSS_Context_time call + + Input: + + o context_handle INTEGER, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_COMPLETE indicates that the referenced context is valid, and + will remain valid for the amount of time indicated in + lifetime_rec. + + o GSS_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + + +Linn [Page 31] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.3. Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_Sign() is properly input to GSS_Verify(), and the output from + GSS_Seal() is properly input to GSS_Unseal(). + + GSS_Sign() and GSS_Verify() support data origin authentication and + data integrity services. When GSS_Sign() is invoked on an input + message, it yields a per-message token containing data items which + allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_Verify(), which validates the message in + conjunction with the separate token. + + GSS_Seal() and GSS_Unseal() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs + a single data element, encapsulating optionally enciphered user data + as well as associated token data items. The data element output from + GSS_Seal() is passed to the remote peer and processed by + GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + +2.3.1. GSS_Sign call + + Inputs: + + o context_handle INTEGER, + + o qop_req INTEGER,-0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 32] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER, + + o per_msg_token OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a signature, suitable for an + established security context, was successfully applied and that + the message and corresponding per_msg_token are ready for + transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + requested operation could not be performed for reasons unspecified + at the GSS-API level. + + Using the security context referenced by context_handle, apply a + signature to the input message (along with timestamps and/or other + data included in support of mech_type-specific mechanisms) and return + the result in per_msg_token. The qop_req parameter allows quality- + of-protection control. The caller passes the message and the + per_msg_token to the target. + + The GSS_Sign() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_Sign() does not guarantee that a corresponding GSS_Verify() has + been (or can necessarily be) performed successfully when the message + arrives at the destination. + +2.3.2. GSS_Verify call + + Inputs: + + o context_handle INTEGER, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + + + +Linn [Page 33] + +RFC 1508 Generic Security Interface September 1993 + + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_COMPLETE indicates that the message was successfully verified. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the received per_msg_token failed, preventing further processing + from being performed with that token. + + o GSS_BAD_SIG indicates that the received per_msg_token contains an + incorrect signature for the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Verify() operation could not be performed for reasons + unspecified at the GSS-API level. + + Using the security context referenced by context_handle, verify that + the input per_msg_token contains an appropriate signature for the + input message, and apply any active replay detection or sequencing + features. Return an indication of the quality-of-protection applied + to the processed message in the qop_state result. + + + + + + + + +Linn [Page 34] + +RFC 1508 Generic Security Interface September 1993 + + +2.3.3. GSS_Seal call + + Inputs: + + o context_handle INTEGER, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER,-0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for transmission. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Seal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_Sign(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter allows + quality-of-protection control. + + + +Linn [Page 35] + +RFC 1508 Generic Security Interface September 1993 + + + In all cases, the GSS_Seal() call yields a single output_message + data element containing (optionally enciphered) user data as well as + control information. + +2.3.4. GSS_Unseal call + + Inputs: + + o context_handle INTEGER, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that the input_message was successfully + processed and that the resulting output_message is available. + + o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on + the per_msg_token extracted from the input_message failed, + preventing further processing from being performed. + + o GSS_BAD_SIG indicates that an incorrect signature was detected for + the message. + + o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values + appear in conjunction with the optional per-message replay + detection features described in Section 1.2.3; their semantics are + described in that section. + + o GSS_CONTEXT_EXPIRED indicates that context-related data items have + expired, so that the requested operation cannot be performed. + + o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so that the + requested operation cannot be performed. + + + + +Linn [Page 36] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_NO_CONTEXT indicates that no valid context was recognized for + the input context_handle provided. + + o GSS_FAILURE indicates that the context is recognized, but that the + GSS_Unseal() operation could not be performed for reasons + unspecified at the GSS-API level. + + Processes a data element generated (and optionally enciphered) by + GSS_Seal(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unseal() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Seal() performs the + data integrity and data origin authentication checking functions of + GSS_Verify() on the plaintext data. Plaintext data is returned in + output_message. + +2.4. Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + +2.4.1. GSS_Display_status call + + Inputs: + + o status_value INTEGER,-GSS-API major_status or minor_status + return value + + o status_type INTEGER,-1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ + status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + + + +Linn [Page 37] + +RFC 1508 Generic Security Interface September 1993 + + + encoded within the status_value) is available in the returned + status_string_set. + + o GSS_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not be + performed. + + o GSS_BAD_STATUS indicates that the input status_value was invalid, + or that the input status_type carried a value other than 1 or 2, + so translation could not be performed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. + +2.4.2. GSS_Indicate_mechs call + + Input: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + o GSS_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from + GSS_Acquire_cred(), and should not be needed by other callers. + +2.4.3. GSS_Compare_name call + + Inputs: + + + + +Linn [Page 38] + +RFC 1508 Generic Security Interface September 1993 + + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_COMPLETE indicates that name1 and name2 were comparable, and + that the name_equal result indicates whether name1 and name2 were + equal or unequal. + + o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 + contained internal type specifiers uninterpretable by the + supporting GSS-API implementation, or that the two names' types + are different and incomparable, so the equality comparison could + not be completed. + + o GSS_BAD_NAME indicates that one or both of the input names was + ill-formed in terms of its internal type specifier, so the + equality comparison could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations for + equality. + +2.4.4. GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, + + + + +Linn [Page 39] + +RFC 1508 Generic Security Interface September 1993 + + + o name_type OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid printable name representation + is available in the returned name_string. + + o GSS_BAD_NAMETYPE indicates that the provided name was of a type + uninterpretable by the supporting GSS-API implementation, so no + printable representation could be generated. + + o GSS_BAD_NAME indicates that the contents of the provided name were + inconsistent with the internally-indicated name type, so no + printable representation could be generated. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + +2.4.5. GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_COMPLETE indicates that a valid name representation is output + in output_name and described by the type value in + output_name_type. + + o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported + by the GSS-API implementation, so the import operation could not + be completed. + + + + +Linn [Page 40] + +RFC 1508 Generic Security Interface September 1993 + + + o GSS_BAD_NAME indicates that the provided input_name_string is + ill-formed in terms of the input_name_type, so the import + operation could not be completed. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a printable name representation, designate + the type of namespace in conjunction with which it should be parsed, + and convert that printable representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name is a local matter. + +2.4.6. GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + name was successfully released. + + o GSS_BAD_NAME indicates that the input name argument did not + contain a valid name. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. + +2.4.7. GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + + +Linn [Page 41] + +RFC 1508 Generic Security Interface September 1993 + + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + buffer was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. + +2.4.8. GSS_Release_oid_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_COMPLETE indicates that the storage associated with the input + object identifier set was successfully released. + + o GSS_FAILURE indicates that the requested operation could not be + performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. + +3. Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + + + + +Linn [Page 42] + +RFC 1508 Generic Security Interface September 1993 + + +3.1. Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), + GSS_Seal(), and GSS_Unseal() operations. + +3.2. Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_CONTINUE_NEEDED + + + +Linn [Page 43] + +RFC 1508 Generic Security Interface September 1993 + + + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, + and returns it in output_token along with GSS_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_COMPLETE. + + GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. + +3.3. X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable signatures + were applied by trusted authorities and that those certificates have + not expired. GSS_Init_sec_context() generates a secret key for use + in per-message protection operations on the context, and enciphers + that secret key under the service's public key. + + The enciphered secret key, along with an authenticator quantity + + + +Linn [Page 44] + +RFC 1508 Generic Security Interface September 1993 + + + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_Sign() or GSS_Seal() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_Verify() and GSS_Unseal() calls. + +4. Related Activities + + In order to implement the GSS-API atop existing, emerging, and future + security mechanisms: + + object identifiers must be assigned to candidate GSS-API + mechanisms and the name types which they support + + concrete data element formats must be defined for candidate + mechanisms + + Calling applications must implement formatting conventions which will + enable them to distinguish GSS-API tokens from other data carried in + their application protocols. + + Concrete language bindings are required for the programming + environments in which the GSS-API is to be employed; such bindings + for the C language are available in an associated RFC. + + + + + + + + +Linn [Page 45] + +RFC 1508 Generic Security Interface September 1993 + + +5. Acknowledgments + + This proposal is the result of a collaborative effort. + Acknowledgments are due to the many members of the IETF Security Area + Advisory Group (SAAG) and the Common Authentication Technology (CAT) + Working Group for their contributions at meetings and by electronic + mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, + Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard + Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, + and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of + MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, + Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, + provided inputs which helped to focus and clarify directions. + Precursor work by Richard Pitkin, presented to meetings of the + Trusted Systems Interoperability Group (TSIG), helped to demonstrate + the value of a generic, mechanism-independent security service API. + +6. Security Considerations + + Security issues are discussed throughout this memo. + +7. Author's Address + + John Linn + Geer Zolot Associates + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.3700 + Email: Linn@gza.com + + + + + + + + + + + + + + + + + + + + + +Linn [Page 46] + +RFC 1508 Generic Security Interface September 1993 + + +APPENDIX A + +PACS AND AUTHORIZATION SERVICES + + Consideration has been given to modifying the GSS-API service + interface to recognize and manipulate Privilege Attribute + Certificates (PACs) as in ECMA 138, carrying authorization data as a + side effect of establishing a security context, but no such + modifications have been incorporated at this time. This appendix + provides rationale for this decision and discusses compatibility + alternatives between PACs and the GSS-API which do not require that + PACs be made visible to GSS-API callers. + + Existing candidate mechanism types such as Kerberos and X.509 do not + incorporate PAC manipulation features, and exclusion of such + mechanisms from the set of candidates equipped to fully support the + GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a + feature supported by only a limited number of mechanisms could + encourage the development of ostensibly portable applications which + would in fact have only limited portability. + + The status quo, in which PACs are not visible across the GSS-API + interface, does not preclude implementations in which PACs are + carried transparently, within the tokens defined and used for certain + mech_types, and stored within peers' credentials and context-level + data structures. While invisible to API callers, such PACs could be + used by operating system or other local functions as inputs in the + course of mediating access requests made by callers. This course of + action allows dynamic selection of PAC contents, if such selection is + administratively-directed rather than caller-directed. + + In a distributed computing environment, authentication must span + different systems; the need for such authentication provides + motivation for GSS-API definition and usage. Heterogeneous systems in + a network can intercommunicate, with globally authenticated names + comprising the common bond between locally defined access control + policies. Access control policies to which authentication provides + inputs are often local, or specific to particular operating systems + or environments. If the GSS-API made particular authorization models + visible across its service interface, its scope of application would + become less general. The current GSS-API paradigm is consistent with + the precedent set by Kerberos, neither defining the interpretation of + authorization-related data nor enforcing access controls based on + such data. + + The GSS-API is a general interface, whose callers may reside inside + or outside any defined TCB or NTCB boundaries. Given this + characteristic, it appears more realistic to provide facilities which + + + +Linn [Page 47] + +RFC 1508 Generic Security Interface September 1993 + + + provide "value-added" security services to its callers than to offer + facilities which enforce restrictions on those callers. Authorization + decisions must often be mediated below the GSS-API level in a local + manner against (or in spite of) applications, and cannot be + selectively invoked or omitted at those applications' discretion. + Given that the GSS-API's placement prevents it from providing a + comprehensive solution to the authorization issue, the value of a + partial contribution specific to particular authorization models is + debatable. + +APPENDIX B + +MECHANISM-INDEPENDENT TOKEN FORMAT + + This appendix specifies a mechanism-independent level of + encapsulating representation for the initial token of a GSS-API + context establishment sequence, incorporating an identifier of the + mechanism type to be used on that context. Use of this format (with + ASN.1-encoded data elements represented in BER, constrained in the + interests of parsing simplicity to the Distinguished Encoding Rule + (DER) BER subset defined in X.509, clause 8.7) is recommended to the + designers of GSS-API implementations based on various mechanisms, so + that tokens can be interpreted unambiguously at GSS-API peers. There + is no requirement that the mechanism-specific innerContextToken, + innerMsgToken, and sealedUserData data elements be encoded in ASN.1 + BER. + + -- optional top-level token definitions to + -- frame different mechanisms + + GSS-API DEFINITIONS ::= + + BEGIN + + MechType ::= OBJECT IDENTIFIER + -- data structure definitions + + -- callers must be able to distinguish among + -- InitialContextToken, SubsequentContextToken, + -- PerMsgToken, and SealedMessage data elements + -- based on the usage in which they occur + + InitialContextToken ::= + -- option indication (delegation, etc.) indicated within + -- mechanism-specific token + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken ANY DEFINED BY thisMech + + + +Linn [Page 48] + +RFC 1508 Generic Security Interface September 1993 + + + -- contents mechanism-specific + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + + PerMsgToken ::= + -- as emitted by GSS_Sign and processed by GSS_Verify + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Seal and processed by GSS_Unseal + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + sealedUserData ANY + + END + +APPENDIX C + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + Use of the approach defined in Appendix B of this specification, + applying a mechanism type tag to the InitialContextToken, is + required. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + + + + + + + + + + + + + + +Linn [Page 49] +
\ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/rfc1509.txt b/crypto/heimdal/doc/standardisation/rfc1509.txt new file mode 100644 index 0000000..f36cd80 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1509.txt @@ -0,0 +1,2691 @@ + + + + + + +Network Working Group J. Wray +Request for Comments: 1509 Digital Equipment Corporation + September 1993 + + + Generic Security Service API : C-bindings + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document specifies C language bindings for the Generic Security + Service Application Program Interface (GSS-API), which is described + at a language-independent conceptual level in other documents. + + The Generic Security Service Application Programming Interface (GSS- + API) provides security services to its callers, and is intended for + implementation atop alternative underlying cryptographic mechanisms. + Typically, GSS-API callers will be application protocols into which + security enhancements are integrated through invocation of services + provided by the GSS-API. The GSS-API allows a caller application to + authenticate a principal identity associated with a peer application, + to delegate rights to a peer, and to apply security services such as + confidentiality and integrity on a per-message basis. + +1. INTRODUCTION + + The Generic Security Service Application Programming Interface [1] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and + to apply security services such as confidentiality and integrity on a + per-message basis. + + There are four stages to using the GSSAPI: + + (a) The application acquires a set of credentials with which it may + prove its identity to other processes. The application's + credentials vouch for its global identity, which may or may not + be related to the local username under which it is running. + + + + + +Wray [Page 1] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a + pair of GSSAPI data structures that contain shared state + information, which is required in order that per-message + security services may be provided. As part of the + establishment of a security context, the context initiator is + authenticated to the responder, and may require that the + responder is authenticated in turn. The initiator may + optionally give the responder the right to initiate further + security contexts. This transfer of rights is termed + delegation, and is achieved by creating a set of credentials, + similar to those used by the originating application, but which + may be used by the responder. To establish and maintain the + shared information that makes up the security context, certain + GSSAPI calls will return a token data structure, which is a + cryptographically protected opaque data type. The caller of + such a GSSAPI routine is responsible for transferring the token + to the peer application, which should then pass it to a + corresponding GSSAPI routine which will decode it and extract + the information. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + to application data, which are treated by GSSAPI as + arbitrary octet-strings. The application transmitting a + message that it wishes to protect will call the appropriate + GSSAPI routine (sign or seal) to apply protection, specifying + the appropriate security context, and send the result to the + receiving application. The receiver will pass the received + data to the corresponding decoding routine (verify or unseal) + to remove the protection and validate the data. + + (d) At the completion of a communications session (which may extend + across several connections), the peer applications call GSSAPI + routines to delete the security context. Multiple contexts may + also be used (either successively or simultaneously) within a + single communications association. + +2. GSSAPI Routines + + This section lists the functions performed by each of the GSSAPI + routines and discusses their major parameters, describing how they + are to be passed to the routines. The routines are listed in figure + 4-1. + + + + +Wray [Page 2] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Figure 4-1 GSSAPI Routines + + + Routine Function + + gss_acquire_cred Assume a global identity + + gss_release_cred Discard credentials + + gss_init_sec_context Initiate a security context + with a peer application + + gss_accept_sec_context Accept a security context + initiated by a peer + application + + gss_process_context_token Process a token on a security + context from a peer + application + + gss_delete_sec_context Discard a security context + + gss_context_time Determine for how long a + context will remain valid + + gss_sign Sign a message; integrity + service + + gss_verify Check signature on a message + + gss_seal Sign (optionally encrypt) a + message; confidentiality + service + + gss_unseal Verify (optionally decrypt) + message + + gss_display_status Convert an API status code + to text + + gss_indicate_mechs Determine underlying + authentication mechanism + + gss_compare_name Compare two internal-form + names + + gss_display_name Convert opaque name to text + + + + +Wray [Page 3] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + gss_import_name Convert a textual name to + internal-form + + gss_release_name Discard an internal-form + name + + gss_release_buffer Discard a buffer + + gss_release_oid_set Discard a set of object + identifiers + + gss_inquire_cred Determine information about + a credential + + Individual GSSAPI implementations may augment these routines by + providing additional mechanism-specific routines if required + functionality is not available from the generic forms. Applications + are encouraged to use the generic routines wherever possible on + portability grounds. + +2.1. Data Types and Calling Conventions + + The following conventions are used by the GSSAPI: + +2.1.1. Structured data types + + Wherever these GSSAPI C-bindings describe structured data, only + fields that must be provided by all GSSAPI implementation are + documented. Individual implementations may provide additional + fields, either for internal use within GSSAPI routines, or for use by + non-portable applications. + +2.1.2. Integer types + + GSSAPI defines the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data + type is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map + this type onto a built-in data type. + +2.1.3. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous multiple-byte data. All such data is passed + between the GSSAPI and the caller using the gss_buffer_t data type. + + + +Wray [Page 4] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + This data type is a pointer to a buffer descriptor, which consists of + a length field that contains the total number of bytes in the datum, + and a value field which contains a pointer to the actual datum: + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + Storage for data passed to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; Unused gss_buffer_desc objects + may be initialized to the value GSS_C_EMPTY_BUFFER. + +2.1.3.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at + the GSSAPI, because their internal structure has no significance + either to the GSSAPI or to the caller. Examples of such opaque data + types are the input_token parameter to gss_init_sec_context (which is + opaque to the caller), and the input_message parameter to gss_seal + (which is opaque to the GSSAPI). Opaque data is passed between the + GSSAPI and the application using the gss_buffer_t datatype. + +2.1.3.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO + Latin-1 character strings. An example of this is the + input_name_buffer parameter to gss_import_name. Some GSSAPI routines + also return character strings. Character strings are passed between + the application and the GSSAPI using the gss_buffer_t datatype, + defined earlier. + +2.1.4. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or + Object identifier. This is a type containing ISO-defined tree- + structured values, and is used by the GSSAPI caller to select an + underlying security mechanism. A value of type gss_OID has the + following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + +Wray [Page 5] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value of the + gss_OID. The length field contains the number of bytes in this + value. For example, the gss_OID value corresponding to {iso(1) + identified- oganization(3) icd-ecma(12) member-company(2) dec(1011) + cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 + authentication mechanism) has a length field of 7 and an elements + field pointing to seven octets containing the following octal values: + 53,14,2,207,163,7,5. GSSAPI implementations should provide constant + gss_OID values to allow callers to request any supported mechanism, + although applications are encouraged on portability grounds to accept + the default mechanism. gss_OID values should also be provided to + allow applications to specify particular name types (see section + 2.1.10). Applications should treat gss_OID_desc values returned by + GSSAPI routines as read-only. In particular, the application should + not attempt to deallocate them. The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype [2]. + +2.1.5. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. + This type represents one or more object identifiers (section 2.1.4). + A gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each + of which describes a single OID. gss_OID_set values are used to name + the available mechanisms supported by the GSSAPI, to request the use + of specific mechanisms, and to indicate which mechanisms a given + credential supports. Storage associated with gss_OID_set values + returned to the application by the GSSAPI may be deallocated by the + gss_release_oid_set routine. + +2.1.6. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which may be implemented as either an + arithmetic or a pointer type. Credentials describe a principal, and + they give their holder the ability to act as that principal. The + GSSAPI does not make the actual credentials available to + applications; instead the credential handle is used to identify a + particular credential, held internally by GSSAPI or underlying + + + +Wray [Page 6] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + mechanism. Thus the credential handle contains no security-relavent + information, and requires no special protection by the application. + Depending on the implementation, a given credential handle may refer + to different credentials when presented to the GSSAPI by different + callers. Individual GSSAPI implementations should define both the + scope of a credential handle and the scope of a credential itself + (which must be at least as wide as that of a handle). Possibilities + for credential handle scope include the process that acquired the + handle, the acquiring process and its children, or all processes + sharing some local identification information (e.g., UID). If no + handles exist by which a given credential may be reached, the GSSAPI + may delete the credential. + + Certain routines allow credential handle parameters to be omitted to + indicate the use of a default credential. The mechanism by which a + default credential is established and its scope should be defined by + the individual GSSAPI implementation. + +2.1.7. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It may be + implemented as either an arithmetic or a pointer type. Depending on + the implementation, a given gss_ctx_id_t value may refer to different + GSSAPI security contexts when presented to the GSSAPI by different + callers. The security context holds state information about each end + of a peer communication, including cryptographic state information. + Individual GSSAPI implementations should define the scope of a + context. Since no way is provided by which a new gss_ctx_id_t value + may be obtained for an existing context, the scope of a context + should be the same as the scope of a gss_ctx_id_t. + +2.1.8. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + bit-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other + end. Encapsulation (if required) and transfer of the token are the + responsibility of the peer applications. A token is passed between + the GSSAPI and the application using the gss_buffer_t conventions. + +2.1.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + + +Wray [Page 7] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism used to provide the security service. The + errors that can be indicated via a GSS status code are either generic + API routine errors (errors that are defined in the GSSAPI + specification) or calling errors (errors that are specific to these + bindings). + + A GSS status code can indicate a single fatal generic API error from + the routine and a single calling error. In addition, supplementary + status information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Hence if a GSSAPI routine returns a GSS status code whose upper 16 + bits contain a non-zero value, the call failed. If the calling error + field is non-zero, the invoking application's call of the routine was + erroneous. Calling errors are defined in table 5-1. If the routine + error field is non-zero, the routine failed for one of the routine- + specific reasons listed below in table 5-2. Whether or not the upper + 16 bits indicate a failure or a success, the routine may indicate + additional information by setting bits in the supplementary info + field of the status code. The meaning of individual bits is listed + below in table 5-3. + + Table 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + +Wray [Page 8] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + + GSS_S_BAD_SIG 6 A token had an invalid + signature + GSS_S_NO_CRED 7 No credentials were supplied + GSS_S_NO_CONTEXT 8 No context has been + established + GSS_S_DEFECTIVE_TOKEN 9 A token was invalid + GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid + GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials + have expired + GSS_S_CONTEXT_EXPIRED 12 The context has expired + GSS_S_FAILURE 13 Miscellaneous failure + (see text) + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its + function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + + The routine documentation also uses the name GSS_S_COMPLETE, which is + a zero value, to indicate an absence of any API errors or + supplementary information bits. + + + + + +Wray [Page 9] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + All GSS_S_xxx symbols equate to complete OM_uint32 status codes, + rather than to bitfield values. For example, the actual value of the + symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 + << 16. + + The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and + GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS + status code and removes all but the relevant field. For example, the + value obtained by applying GSS_ROUTINE_ERROR to a status code removes + the calling errors and supplementary info fields, leaving only the + routine errors field. The values delivered by these macros may be + directly compared with a GSS_S_xxx symbol of the appropriate type. + The macro GSS_ERROR() is also provided, which when applied to a GSS + status code returns a non-zero value if the status code indicated a + calling or routine error, and a zero value otherwise. + + A GSSAPI implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + +2.1.9.2. Mechanism-specific status codes + + GSSAPI routines return a minor_status parameter, which is used to + indicate specialized errors from the underlying security mechanism. + This parameter may contain a single mechanism-specific error, + indicated by a OM_uint32 value. + + The minor_status parameter will always be set by a GSSAPI routine, + even if it returns a calling error or one of the generic API errors + indicated above as fatal, although other output parameters may remain + unset in such cases. However, output parameters that are expected to + return pointers to storage allocated by a routine must always set set + by the routine, even in the event of an error, although in such cases + the GSSAPI routine may elect to set the returned parameter value to + NULL to indicate that no storage was actually allocated. Any length + field associated with such pointers (as in a gss_buffer_desc + structure) should also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS + status code is defined. The mechanism status code will provide more + details about the error. + +2.1.10. Names + + A name is used to identify a person or entity. GSSAPI authenticates + the relationship between a name and the entity claiming the name. + + + +Wray [Page 10] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Two distinct representations are defined for names: + + (a) A printable form, for presentation to a user + + (b) An internal form, for presentation at the API + + The syntax of a printable name is defined by the GSSAPI + implementation, and may be dependent on local system configuration, + or on individual user preference. The internal form provides a + canonical representation of the name that is independent of + configuration. + + A given GSSAPI implementation may support names drawn from multiple + namespaces. In such an implementation, the internal form of the name + must include fields that identify the namespace from which the name + is drawn. The namespace from which a printable name is drawn is + specified by an accompanying object identifier. + + Routines (gss_import_name and gss_display_name) are provided to + convert names between their printable representations and the + gss_name_t type. gss_import_name may support multiple syntaxes for + each supported namespace, allowing users the freedom to choose a + preferred name representation. gss_display_name should use an + implementation-chosen preferred syntax for each supported name-type. + + Comparison of internal-form names is accomplished via the + gss_compare_names routine. This removes the need for the application + program to understand the syntaxes of the various printable names + that a given GSSAPI implementation may support. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated + with a name. + +2.1.11. Channel Bindings + + GSSAPI supports the use of user-specified tags to identify a given + context to the peer application. These tags are used to identify the + particular communications channel that carries the context. Channel + bindings are communicated to the GSSAPI using the following + structure: + + + + + + + + + + +Wray [Page 11] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + The initiator_addrtype and acceptor_addrtype fields denote the type + of addresses contained in the initiator_address and acceptor_address + buffers. The address type should be one of the following: + + GSS_C_AF_UNSPEC Unspecified address type + GSS_C_AF_LOCAL Host-local address type + GSS_C_AF_INET DARPA Internet address type + GSS_C_AF_IMPLINK ARPAnet IMP address type (eg IP) + GSS_C_AF_PUP pup protocols (eg BSP) address type + GSS_C_AF_CHAOS MIT CHAOS protocol address type + GSS_C_AF_NS XEROX NS address type + GSS_C_AF_NBS nbs address type + GSS_C_AF_ECMA ECMA address type + GSS_C_AF_DATAKIT datakit protocols address type + GSS_C_AF_CCITT CCITT protocols (eg X.25) + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these name address families rather than specific addressing + formats. For address families that contain several alternative + address forms, the initiator_address and acceptor_address fields must + contain sufficient information to determine which address form is + used. When not otherwise specified, addresses should be specified in + network byte-order. + + Conceptually, the GSSAPI concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism signs this + octet string, and binds the signature to the context establishment + token emitted by gss_init_sec_context. The same bindings are + presented by the context acceptor to gss_accept_sec_context, and a + + + +Wray [Page 12] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + signature is calculated in the same way. The calculated signature is + compared with that found in the token, and if the signatures differ, + gss_accept_sec_context will return a GSS_S_BAD_BINDINGS error, and + the context will not be established. Some mechanisms may include the + actual channel binding data in the token (rather than just a + signature); applications should therefore not use confidential data + as channel-binding components. Individual mechanisms may impose + additional constraints on addresses and address types that may appear + in channel bindings. For example, a mechanism may verify that the + initiator_address field of the channel bindings presented to + gss_init_sec_context contains the correct network address of the host + system. + +2.1.12. Optional parameters + + Various parameters are described as optional. This means that they + follow a convention whereby a default value may be requested. The + following conventions are used for omitted parameters. These + conventions apply only to those parameters that are explicitly + documented as optional. + +2.1.12.1. gss_buffer_t types + + Specify GSS_C_NO_BUFFER as a value. For an input parameter this + signifies that default behavior is requested, while for an output + parameter it indicates that the information that would be returned + via the parameter is not required by the application. + +2.1.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to + indicate default actions. + +2.1.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + +2.1.12.4. Pointer types + + Specify NULL as the value. + +2.1.12.5. Object IDs + + Specify GSS_C_NULL_OID as the value. + +2.1.12.6. Object ID Sets + + Specify GSS_C_NULL_OID_SET as the value. + + + +Wray [Page 13] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.12.7. Credentials + + Specify GSS_C_NO_CREDENTIAL to use the default credential handle. + +2.1.12.8. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings + are not to be used. + +3. GSSAPI routine descriptions + +2.1. gss_acquire_cred + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + int cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_int32 * time_rec) + Purpose: + + Allows an application to acquire a handle for a pre-existing + credential by name. GSSAPI implementations must impose a local + access-control policy on callers of this routine to prevent + unauthorized callers from acquiring credentials to which they are not + entitled. This routine is not intended to provide a "login to the + network" function, as such a function would result in the creation of + new credentials rather than merely acquiring a handle to existing + credentials. Such functions, if required, should be defined in + implementation-specific extensions to the API. + + If credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g., by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call + of gss_inquire_cred immediately following the call of + gss_acquire_cred must return valid credential data, and may therefore + incur the overhead of a deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + + +Wray [Page 14] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + time_req integer, read + number of seconds that credentials + should remain valid + + desired_mechs Set of Object IDs, read + set of underlying security mechanisms that + may be used. GSS_C_NULL_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage integer, read + GSS_C_BOTH - Credentials may be used + either to initiate or accept + security contexts. + GSS_C_INITIATE - Credentials will only be + used to initiate security + contexts. + GSS_C_ACCEPT - Credentials will only be used to + accept security contexts. + + output_cred_handle gss_cred_id_t, modify + The returned credential handle. + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. Specify NULL + if not required. + + time_rec Integer, modify, optional + Actual number of seconds for which the + returned credentials will remain valid. If the + implementation does not support expiration of + credentials, the value GSS_C_INDEFINITE will + be returned. Specify NULL if not required + + minor_status Integer, modify + Mechanism specific status code. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Unavailable mechanism requested + + GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is + not supported + + GSS_S_BAD_NAME Value supplied for desired_name parameter is + + + +Wray [Page 15] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ill-formed. + + GSS_S_FAILURE Unspecified failure. The minor_status parameter + contains more detailed information + +3.2. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSSAPI that the specified credential handle is no longer + required by the process. When all processes have released a + credential, it will be deleted. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + buffer containing opaque credential + handle. If GSS_C_NO_CREDENTIAL is supplied, + the default credential will be released + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED Credentials could not be accessed. + + + + + + + + + + + + + + + + + +Wray [Page 16] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.3. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + gss_cred_id_t claimant_cred_handle, + gss_ctx_id_t * context_handle, + gss_name_t target_name, + gss_OID mech_type, + int req_flags, + int time_req, + gss_channel_bindings_t + input_chan_bindings, + gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified as GSS_C_NO_BUFFER. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_accept_sec_context. + If no token need be sent, gss_init_sec_context will indicate this by + setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_init_sec_context will + return a status indicating GSS_S_CONTINUE_NEEDED in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_init_sec_context via the + input_token parameters. + + The values returned via the ret_flags and time_rec parameters are not + defined unless the routine returns GSS_S_COMPLETE. + + Parameters: + + claimant_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to use default + credentials. + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned by first call in continuation calls. + + + +Wray [Page 17] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NULL_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains four independent flags, each of + which requests that the context support a + specific service option. Symbolic + names are provided for each flag, and the + symbolic names corresponding to the required + flags should be logically-ORed + together to form the bit-mask value. The + flags are: + + GSS_C_DELEG_FLAG + True - Delegate credentials to remote peer + False - Don't delegate + GSS_C_MUTUAL_FLAG + True - Request that remote peer + authenticate itself + False - Authenticate self to remote peer + only + GSS_C_REPLAY_FLAG + True - Enable replay detection for signed + or sealed messages + False - Don't attempt to detect + replayed messages + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + signed or sealed messages + False - Don't attempt to detect + out-of-sequence messages + + time_req integer, read + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + + + +Wray [Page 18] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER on initial call. + + actual_mech_type OID, modify + actual mechanism used. + + output_token buffer, opaque, modify + token to be sent to peer application. If + the length field of the returned buffer is + zero, no token need be sent to the peer + application. + + ret_flags bit-mask, modify + Contains six independent flags, each of which + indicates that the context supports a specific + service option. Symbolic names are provided + for each flag, and the symbolic names + corresponding to the required flags should be + logically-ANDed with the ret_flags value to test + whether a given option is supported by the + context. The flags are: + + GSS_C_DELEG_FLAG + True - Credentials were delegated to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will provide + message encapsulation, data-origin + + + +Wray [Page 19] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + authentication and integrity + services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_sign or gss_seal + routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete thecontext, and + that gss_init_sec_context must be called again with + that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on + the input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not + reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter + + GSS_S_BAD_SIG The input_token contains an invalid signature, or a + signature that could not be verified + + + +Wray [Page 20] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error + during context establishment + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of + a token already processed. This is a fatal error + during context establishment. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did not + refer to a valid context + + GSS_S_BAD_NAMETYPE The provided target_name parameter contained an + invalid or unsupported type of name + + GSS_S_BAD_NAME The provided target_name parameter was ill-formed. + + GSS_S_FAILURE Failure. See minor_status for more information + +3.4. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_cred_id_t verifier_cred_handle, + gss_buffer_t input_token_buffer + gss_channel_bindings_t + input_chan_bindings, + gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + Purpose: + + Allows a remotely initiated security context between the application + and a remote peer to be established. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_init_sec_context. + If no token need be sent, gss_accept_sec_context will indicate this + by setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_accept_sec_context + will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it + should be called again when the reply token is received from the peer + application, passing the token to gss_accept_sec_context via the + input_token parameters. + + + + +Wray [Page 21] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The values returned via the src_name, ret_flags, time_rec, and + delegated_cred_handle parameters are not defined unless the routine + returns GSS_S_COMPLETE. + + Parameters: + + context_handle gss_ctx_id_t, read/modify + context handle for new context. Supply + GSS_C_NO_CONTEXT for first call; use value + returned in subsequent calls. + + verifier_cred_handle gss_cred_id_t, read, optional + Credential handle claimed by context + acceptor. + Specify GSS_C_NO_CREDENTIAL to use default + credentials. If GSS_C_NO_CREDENTIAL is + specified, but the caller has no default + credentials established, an + implementation-defined default credential + may be used. + + input_token_buffer buffer, opaque, read + token obtained from remote application + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + src_name gss_name_t, modify, optional + Authenticated name of context initiator. + After use, this name should be deallocated by + passing it to gss_release_name. If not required, + specify NULL. + + mech_type Object ID, modify + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller. + + output_token buffer, opaque, modify + Token to be passed to peer application. If the + length field of the returned token buffer is 0, + then no token need be passed to the peer + application. + + + + +Wray [Page 22] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ret_flags bit-mask, modify + Contains six independent flags, each of + which indicates that the context supports a + specific service option. Symbolic names are + provided for each flag, and the symbolic names + corresponding to the required flags + should be logically-ANDed with the ret_flags + value to test whether a given option is + supported by the context. The flags are: + GSS_C_DELEG_FLAG + True - Delegated credentials are available + via the delegated_cred_handle + parameter + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer asked for mutual + authentication + False - Remote peer did not ask for mutual + authentication + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + messages will be detected + False - out-of-sequence messages will not + be detected + GSS_C_CONF_FLAG + True - Confidentiality service may be + invoked by calling seal routine + False - No confidentiality service (via + seal) available. seal will + provide message encapsulation, + data-origin authentication and + integrity services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked + by calling either gss_sign or + gss_seal routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + + + +Wray [Page 23] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + delegated_cred_handle + gss_cred_id_t, modify + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete the context, + and that gss_accept_sec_context must be called + again with that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for + context acceptance, or the credential handle + did not reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have + expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did + not refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid signature. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal + error during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a + duplicate of a token already processed. This + is a fatal error during context establishment. + + + +Wray [Page 24] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.5. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Usually, + tokens are associated either with context establishment (when they + would be passed to gss_init_sec_context or gss_accept_sec_context) or + with per-message security service (when they would be passed to + gss_verify or gss_unseal). Occasionally, tokens may be received at + other times, and gss_process_context_token allows such tokens to be + passed to the underlying security service for processing. At + present, such additional tokens may only be generated by + gss_delete_sec_context. GSSAPI implementation may use this service + to implement deletion of the security context. + + Parameters: + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + pointer to first byte of token to process + + minor_status integer, modify + Implementation specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the token failed + + GSS_S_FAILURE Failure. See minor_status for more information + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid + context + + + + +Wray [Page 25] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.6. gss_delete_sec_context + + OM_uint32 gss_delete_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_buffer_t output_token) + + Purpose: + + Delete a security context. gss_delete_sec_context will delete the + local data structures associated with the specified security context, + and generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. No + further security services may be obtained using the context specified + by context_handle. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + + output_token buffer, opaque, modify + token to be sent to remote application to + instruct it to also delete the context + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_FAILURE Failure, see minor_status for more information + + GSS_S_NO_CONTEXT No valid context was supplied + +3.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + + +Wray [Page 26] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + Identifies the context to be interrogated. + + time_rec integer, modify + Number of seconds that the context will remain + valid. If the context has already expired, + zero will be returned. + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + +3.8. gss_sign + + OM_uint32 gss_sign ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int qop_req, + gss_buffer_t message_buffer, + gss_buffer_t msg_token) + Purpose: + + Generates a cryptographic signature for the supplied message, and + places the signature in a token for transfer to the peer application. + The qop_req parameter allows a choice between several cryptographic + algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + + + +Wray [Page 27] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + will be sent + + qop_req integer, read, optional + Specifies requested quality of protection. + Callers are encouraged, on portability grounds, + to accept the default quality of protection + offered by the chosen mechanism, which may be + requested by specifying GSS_C_QOP_DEFAULT for + this parameter. If an unsupported protection + strength is requested, gss_sign will return a + major_status of GSS_S_FAILURE. + + message_buffer buffer, opaque, read + message to be signed + + msg_token buffer, opaque, modify + buffer to receive token + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.9. gss_verify + + OM_uint32 gss_verify ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t message_buffer, + gss_buffer_t token_buffer, + int * qop_state) + Purpose: + + Verifies that a cryptographic signature, contained in the token + parameter, fits the supplied message. The qop_state parameter allows + a message recipient to determine the strength of protection that was + applied to the message. + + + +Wray [Page 28] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + message_buffer buffer, opaque, read + message to be verified + + token_buffer buffer, opaque, read + token associated with message + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct + signature for the message, but it had already + been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 29] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.10. gss_seal + + OM_uint32 gss_seal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + int qop_req + gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer) + + Purpose: + + Cryptographically signs and optionally encrypts the specified + input_message. The output_message contains both the signature and + the message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + conf_req_flag boolean, read + True - Both confidentiality and integrity + services are requested + False - Only integrity service is requested + + qop_req integer, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_seal will return a major_status of + GSS_S_FAILURE. + + input_message_buffer buffer, opaque, read + message to be sealed + + + + +Wray [Page 30] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + conf_state boolean, modify + True - Confidentiality, data origin + authentication and integrity services + have been applied + False - Integrity and data origin services only + has been applied. + + output_message_buffer buffer, opaque, modify + buffer to receive sealed message + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.11. gss_unseal + + OM_uint32 gss_unseal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + int * qop_state) + + Purpose: + + Converts a previously sealed message back to a usable form, verifying + the embedded signature. The conf_state parameter indicates whether + the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality + and integrity services. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + + +Wray [Page 31] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + sealed message + + output_message_buffer buffer, opaque, modify + buffer to receive unsealed message + + conf_state boolean, modify + True - Confidentiality and integrity protection + were used + False - Inteegrity service only was used + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a + correct signature for the message, but it had + already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 32] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.12. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + int status_value, + int status_type, + gss_OID mech_type, + int * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSSAPI + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple errors, applications may + need to call gss_display_status multiple times, each call generating + a single text string. The message_context parameter is used to + indicate which error message should be extracted from a given + status_value; message_context should be initialized to 0, and + gss_display_status will return a non-zero value if there are further + messages to extract. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + status_value integer, read + Status value to be converted + + status_type integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NULL_OID to + obtain the system default. + + message_context integer, read/modify + Should be initialized to zero by caller + + + +Wray [Page 33] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + on first call. If further messages are + contained in the status_value parameter, + message_context will be non-zero on return, + and this value should be passed back to + subsequent calls, along with the same + status_value, status_type and mech_type + parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Indicates that translation in accordance with + an unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the + status type was neither GSS_C_GSS_CODE nor + GSS_C_MECH_CODE. + + +3.13. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security + mechanisms are available. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + pointer into static storage, and should be + treated as read-only by the caller. + + + + + +Wray [Page 34] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + +3.14. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + gss_name_t name1, + gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + True - names refer to same entity + False - names refer to different entities + (strictly, the names are not known to + refer to the same identity). + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type contained within either name1 or + name2 was unrecognized, or the names were of + incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + +Wray [Page 35] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.15. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSSAPI implementation. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string + + output_name_type Object ID, modify + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type of input_name was not recognized + + GSS_S_BAD_NAME input_name was ill-formed + +3.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + gss_buffer_t input_name_buffer, + gss_OID input_name_type, + gss_name_t * output_name) + + + + +Wray [Page 36] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Purpose: + + Convert a printable name to internal form. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + input_name_buffer buffer, character-string, read + buffer containing printable name to convert + + input_name_type Object ID, read, optional + Object Id specifying type of printable + name. Applications may specify either + GSS_C_NULL_OID to use a local system-specific + printable syntax, or an OID registered by the + GSSAPI implementation to name a particular + namespace. + + output_name gss_name_t, modify + returned name in internal form + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be + interpreted as a name of the specified type + +3.17. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage associated with an internal form name. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + + +Wray [Page 37] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + name gss_name_t, modify + The name to be deleted + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + +3.18. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer format name. The storage must + have been allocated by a GSSAPI routine. In addition to freeing the + associated storage, the routine will zero the length field in the + buffer parameter. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.19. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + + + +Wray [Page 38] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Free storage associated with a gss_OID_set object. The storage must + have been allocated by a GSSAPI routine. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.20. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + int * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default credential. + + name gss_name_t, modify + The name whose identity the credential asserts. + Specify NULL if not required. + + lifetime Integer, modify + + + +Wray [Page 39] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage Integer, modify + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify + Set of mechanisms supported by the credential. + Specify NULL if not required. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be + accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were + invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + If the lifetime parameter was not passed as + NULL, it will be set to 0. + + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + /* + * First, define the platform-dependent types. + */ + typedef <platform-specific> OM_uint32; + typedef <platform-specific> gss_ctx_id_t; + typedef <platform-specific> gss_cred_id_t; + typedef <platform-specific> gss_name_t; + + + + +Wray [Page 40] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Note that a platform supporting the xom.h X/Open header file + * may make use of that header for the definitions of OM_uint32 + * and the structure to which gss_OID_desc equates. + */ + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * Six independent flags each of which indicates that a context + * supports a specific service option. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + + +Wray [Page 41] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0; + #define GSS_C_AF_LOCAL 1; + #define GSS_C_AF_INET 2; + #define GSS_C_AF_IMPLINK 3; + #define GSS_C_AF_PUP 4; + #define GSS_C_AF_CHAOS 5; + #define GSS_C_AF_NS 6; + #define GSS_C_AF_NBS 7; + #define GSS_C_AF_ECMA 8; + #define GSS_C_AF_DATAKIT 9; + #define GSS_C_AF_CCITT 10; + #define GSS_C_AF_SNA 11; + #define GSS_C_AF_DECnet 12; + #define GSS_C_AF_DLI 13; + #define GSS_C_AF_LAT 14; + #define GSS_C_AF_HYLINK 15; + #define GSS_C_AF_APPLETALK 16; + #define GSS_C_AF_BSC 17; + #define GSS_C_AF_DSS 18; + #define GSS_C_AF_OSI 19; + #define GSS_C_AF_X25 21; + + #define GSS_C_AF_NULLADDR 255; + + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NULL_OID ((gss_OID) 0) + #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may either reserve a value (for example zero, + * as assumed here) to mean "default protection", or alternatively + * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP + * value. + + + +Wray [Page 42] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + + + +Wray [Page 43] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + + + /* + * Finally, function prototypes for the GSSAPI routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32*, /* minor_status */ + gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + gss_OID_set, /* desired_mechs */ + int, /* cred_usage */ + gss_cred_id_t*, /* output_cred_handle */ + gss_OID_set*, /* actual_mechs */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_release_cred, + (OM_uint32*, /* minor_status */ + gss_cred_id_t* /* cred_handle */ + ); + + + +Wray [Page 44] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_init_sec_context + (OM_uint32*, /* minor_status */ + gss_cred_id_t, /* claimant_cred_handle */ + gss_ctx_id_t*, /* context_handle */ + gss_name_t, /* target_name */ + gss_OID, /* mech_type */ + int, /* req_flags */ + OM_uint32, /* time_req */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_buffer_t, /* input_token */ + gss_OID*, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_cred_id_t, /* verifier_cred_handle */ + gss_buffer_t, /* input_token_buffer */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t*, /* src_name */ + gss_OID*, /* mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32*, /* time_rec */ + gss_cred_id_t* /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + + + + + + + +Wray [Page 45] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_context_time + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_sign + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + OM_uitn32 gss_verify + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int* /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int*, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + OM_uint32 gss_unseal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int*, /* conf_state */ + int* /* qop_state */ + ); + + + + + + + + + + + +Wray [Page 46] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_display_status + (OM_uint32*, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + gss_OID, /* mech_type */ + int*, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32*, /* minor_status */ + gss_OID_set* /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32*, /* minor_status */ + gss_name_t, /* name1 */ + gss_name_t, /* name2 */ + int* /* name_equal */ + ); + + OM_uint32 gss_display_name, + (OM_uint32*, /* minor_status */ + gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID* /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32*, /* minor_status */ + gss_buffer_t, /* input_name_buffer */ + gss_OID, /* input_name_type */ + gss_name_t* /* output_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32*, /* minor_status */ + gss_name_t* /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32*, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32*, /* minor_status */ + gss_OID_set* /* set */ + + + +Wray [Page 47] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + int *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + + + #endif /* GSSAPI_H_ */ + +References + + [1] Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, Geer Zolot Associate, September 1993. + + [2] "OSI Object Management API Specification, Version 2.0 t", X.400 + API Association & X/Open Company Limited, August 24, 1990. + Specification of datatypes and routines for manipulating + information objects. + +Security Considerations + + Security issues are discussed throughout this memo. + +Author's Address + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/AA6 + Littleton, MA 01460 + USA + + Phone: +1-508-486-5210 + EMail: Wray@tuxedo.enet.dec.com + + + + + + + + + + + + +Wray [Page 48] +
\ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/rfc1510.txt b/crypto/heimdal/doc/standardisation/rfc1510.txt new file mode 100644 index 0000000..bc810cc --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1510.txt @@ -0,0 +1,6275 @@ + + + + + + +Network Working Group J. Kohl +Request for Comments: 1510 Digital Equipment Corporation + C. Neuman + ISI + September 1993 + + + The Kerberos Network Authentication Service (V5) + +Status of this Memo + + This RFC specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document gives an overview and specification of Version 5 of the + protocol for the Kerberos network authentication system. Version 4, + described elsewhere [1,2], is presently in production use at MIT's + Project Athena, and at other Internet sites. + +Overview + + Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, + Moira, and Zephyr are trademarks of the Massachusetts Institute of + Technology (MIT). No commercial use of these trademarks may be made + without prior written permission of MIT. + + This RFC describes the concepts and model upon which the Kerberos + network authentication system is based. It also specifies Version 5 + of the Kerberos protocol. + + The motivations, goals, assumptions, and rationale behind most design + decisions are treated cursorily; for Version 4 they are fully + described in the Kerberos portion of the Athena Technical Plan [1]. + The protocols are under review, and are not being submitted for + consideration as an Internet standard at this time. Comments are + encouraged. Requests for addition to an electronic mailing list for + discussion of Kerberos, kerberos@MIT.EDU, may be addressed to + kerberos-request@MIT.EDU. This mailing list is gatewayed onto the + Usenet as the group comp.protocols.kerberos. Requests for further + information, including documents and code availability, may be sent + to info-kerberos@MIT.EDU. + + + + + +Kohl & Neuman [Page 1] + +RFC 1510 Kerberos September 1993 + + +Background + + The Kerberos model is based in part on Needham and Schroeder's + trusted third-party authentication protocol [3] and on modifications + suggested by Denning and Sacco [4]. The original design and + implementation of Kerberos Versions 1 through 4 was the work of two + former Project Athena staff members, Steve Miller of Digital + Equipment Corporation and Clifford Neuman (now at the Information + Sciences Institute of the University of Southern California), along + with Jerome Saltzer, Technical Director of Project Athena, and + Jeffrey Schiller, MIT Campus Network Manager. Many other members of + Project Athena have also contributed to the work on Kerberos. + Version 4 is publicly available, and has seen wide use across the + Internet. + + Version 5 (described in this document) has evolved from Version 4 + based on new requirements and desires for features not available in + Version 4. Details on the differences between Kerberos Versions 4 + and 5 can be found in [5]. + +Table of Contents + + 1. Introduction ....................................... 5 + 1.1. Cross-Realm Operation ............................ 7 + 1.2. Environmental assumptions ........................ 8 + 1.3. Glossary of terms ................................ 9 + 2. Ticket flag uses and requests ...................... 12 + 2.1. Initial and pre-authenticated tickets ............ 12 + 2.2. Invalid tickets .................................. 12 + 2.3. Renewable tickets ................................ 12 + 2.4. Postdated tickets ................................ 13 + 2.5. Proxiable and proxy tickets ...................... 14 + 2.6. Forwardable tickets .............................. 15 + 2.7. Other KDC options ................................ 15 + 3. Message Exchanges .................................. 16 + 3.1. The Authentication Service Exchange .............. 16 + 3.1.1. Generation of KRB_AS_REQ message ............... 17 + 3.1.2. Receipt of KRB_AS_REQ message .................. 17 + 3.1.3. Generation of KRB_AS_REP message ............... 17 + 3.1.4. Generation of KRB_ERROR message ................ 19 + 3.1.5. Receipt of KRB_AS_REP message .................. 19 + 3.1.6. Receipt of KRB_ERROR message ................... 20 + 3.2. The Client/Server Authentication Exchange ........ 20 + 3.2.1. The KRB_AP_REQ message ......................... 20 + 3.2.2. Generation of a KRB_AP_REQ message ............. 20 + 3.2.3. Receipt of KRB_AP_REQ message .................. 21 + 3.2.4. Generation of a KRB_AP_REP message ............. 23 + 3.2.5. Receipt of KRB_AP_REP message .................. 23 + + + +Kohl & Neuman [Page 2] + +RFC 1510 Kerberos September 1993 + + + 3.2.6. Using the encryption key ....................... 24 + 3.3. The Ticket-Granting Service (TGS) Exchange ....... 24 + 3.3.1. Generation of KRB_TGS_REQ message .............. 25 + 3.3.2. Receipt of KRB_TGS_REQ message ................. 26 + 3.3.3. Generation of KRB_TGS_REP message .............. 27 + 3.3.3.1. Encoding the transited field ................. 29 + 3.3.4. Receipt of KRB_TGS_REP message ................. 31 + 3.4. The KRB_SAFE Exchange ............................ 31 + 3.4.1. Generation of a KRB_SAFE message ............... 31 + 3.4.2. Receipt of KRB_SAFE message .................... 32 + 3.5. The KRB_PRIV Exchange ............................ 33 + 3.5.1. Generation of a KRB_PRIV message ............... 33 + 3.5.2. Receipt of KRB_PRIV message .................... 33 + 3.6. The KRB_CRED Exchange ............................ 34 + 3.6.1. Generation of a KRB_CRED message ............... 34 + 3.6.2. Receipt of KRB_CRED message .................... 34 + 4. The Kerberos Database .............................. 35 + 4.1. Database contents ................................ 35 + 4.2. Additional fields ................................ 36 + 4.3. Frequently Changing Fields ....................... 37 + 4.4. Site Constants ................................... 37 + 5. Message Specifications ............................. 38 + 5.1. ASN.1 Distinguished Encoding Representation ...... 38 + 5.2. ASN.1 Base Definitions ........................... 38 + 5.3. Tickets and Authenticators ....................... 42 + 5.3.1. Tickets ........................................ 42 + 5.3.2. Authenticators ................................. 47 + 5.4. Specifications for the AS and TGS exchanges ...... 49 + 5.4.1. KRB_KDC_REQ definition ......................... 49 + 5.4.2. KRB_KDC_REP definition ......................... 56 + 5.5. Client/Server (CS) message specifications ........ 58 + 5.5.1. KRB_AP_REQ definition .......................... 58 + 5.5.2. KRB_AP_REP definition .......................... 60 + 5.5.3. Error message reply ............................ 61 + 5.6. KRB_SAFE message specification ................... 61 + 5.6.1. KRB_SAFE definition ............................ 61 + 5.7. KRB_PRIV message specification ................... 62 + 5.7.1. KRB_PRIV definition ............................ 62 + 5.8. KRB_CRED message specification ................... 63 + 5.8.1. KRB_CRED definition ............................ 63 + 5.9. Error message specification ...................... 65 + 5.9.1. KRB_ERROR definition ........................... 66 + 6. Encryption and Checksum Specifications ............. 67 + 6.1. Encryption Specifications ........................ 68 + 6.2. Encryption Keys .................................. 71 + 6.3. Encryption Systems ............................... 71 + 6.3.1. The NULL Encryption System (null) .............. 71 + 6.3.2. DES in CBC mode with a CRC-32 checksum (descbc-crc)71 + + + +Kohl & Neuman [Page 3] + +RFC 1510 Kerberos September 1993 + + + 6.3.3. DES in CBC mode with an MD4 checksum (descbc-md4) 72 + 6.3.4. DES in CBC mode with an MD5 checksum (descbc-md5) 72 + 6.4. Checksums ........................................ 74 + 6.4.1. The CRC-32 Checksum (crc32) .................... 74 + 6.4.2. The RSA MD4 Checksum (rsa-md4) ................. 75 + 6.4.3. RSA MD4 Cryptographic Checksum Using DES + (rsa-md4-des) ......................................... 75 + 6.4.4. The RSA MD5 Checksum (rsa-md5) ................. 76 + 6.4.5. RSA MD5 Cryptographic Checksum Using DES + (rsa-md5-des) ......................................... 76 + 6.4.6. DES cipher-block chained checksum (des-mac) + 6.4.7. RSA MD4 Cryptographic Checksum Using DES + alternative (rsa-md4-des-k) ........................... 77 + 6.4.8. DES cipher-block chained checksum alternative + (des-mac-k) ........................................... 77 + 7. Naming Constraints ................................. 78 + 7.1. Realm Names ...................................... 77 + 7.2. Principal Names .................................. 79 + 7.2.1. Name of server principals ...................... 80 + 8. Constants and other defined values ................. 80 + 8.1. Host address types ............................... 80 + 8.2. KDC messages ..................................... 81 + 8.2.1. IP transport ................................... 81 + 8.2.2. OSI transport .................................. 82 + 8.2.3. Name of the TGS ................................ 82 + 8.3. Protocol constants and associated values ......... 82 + 9. Interoperability requirements ...................... 86 + 9.1. Specification 1 .................................. 86 + 9.2. Recommended KDC values ........................... 88 + 10. Acknowledgments ................................... 88 + 11. References ........................................ 89 + 12. Security Considerations ........................... 90 + 13. Authors' Addresses ................................ 90 + A. Pseudo-code for protocol processing ................ 91 + A.1. KRB_AS_REQ generation ............................ 91 + A.2. KRB_AS_REQ verification and KRB_AS_REP generation 92 + A.3. KRB_AS_REP verification .......................... 95 + A.4. KRB_AS_REP and KRB_TGS_REP common checks ......... 96 + A.5. KRB_TGS_REQ generation ........................... 97 + A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation 98 + A.7. KRB_TGS_REP verification ......................... 104 + A.8. Authenticator generation ......................... 104 + A.9. KRB_AP_REQ generation ............................ 105 + A.10. KRB_AP_REQ verification ......................... 105 + A.11. KRB_AP_REP generation ........................... 106 + A.12. KRB_AP_REP verification ......................... 107 + A.13. KRB_SAFE generation ............................. 107 + A.14. KRB_SAFE verification ........................... 108 + + + +Kohl & Neuman [Page 4] + +RFC 1510 Kerberos September 1993 + + + A.15. KRB_SAFE and KRB_PRIV common checks ............. 108 + A.16. KRB_PRIV generation ............................. 109 + A.17. KRB_PRIV verification ........................... 110 + A.18. KRB_CRED generation ............................. 110 + A.19. KRB_CRED verification ........................... 111 + A.20. KRB_ERROR generation ............................ 112 + +1. Introduction + + Kerberos provides a means of verifying the identities of principals, + (e.g., a workstation user or a network server) on an open + (unprotected) network. This is accomplished without relying on + authentication by the host operating system, without basing trust on + host addresses, without requiring physical security of all the hosts + on the network, and under the assumption that packets traveling along + the network can be read, modified, and inserted at will. (Note, + however, that many applications use Kerberos' functions only upon the + initiation of a stream-based network connection, and assume the + absence of any "hijackers" who might subvert such a connection. Such + use implicitly trusts the host addresses involved.) Kerberos + performs authentication under these conditions as a trusted third- + party authentication service by using conventional cryptography, + i.e., shared secret key. (shared secret key - Secret and private are + often used interchangeably in the literature. In our usage, it takes + two (or more) to share a secret, thus a shared DES key is a secret + key. Something is only private when no one but its owner knows it. + Thus, in public key cryptosystems, one has a public and a private + key.) + + The authentication process proceeds as follows: A client sends a + request to the authentication server (AS) requesting "credentials" + for a given server. The AS responds with these credentials, + encrypted in the client's key. The credentials consist of 1) a + "ticket" for the server and 2) a temporary encryption key (often + called a "session key"). The client transmits the ticket (which + contains the client's identity and a copy of the session key, all + encrypted in the server's key) to the server. The session key (now + shared by the client and server) is used to authenticate the client, + and may optionally be used to authenticate the server. It may also + be used to encrypt further communication between the two parties or + to exchange a separate sub-session key to be used to encrypt further + communication. + + The implementation consists of one or more authentication servers + running on physically secure hosts. The authentication servers + maintain a database of principals (i.e., users and servers) and their + secret keys. Code libraries provide encryption and implement the + Kerberos protocol. In order to add authentication to its + + + +Kohl & Neuman [Page 5] + +RFC 1510 Kerberos September 1993 + + + transactions, a typical network application adds one or two calls to + the Kerberos library, which results in the transmission of the + necessary messages to achieve authentication. + + The Kerberos protocol consists of several sub-protocols (or + exchanges). There are two methods by which a client can ask a + Kerberos server for credentials. In the first approach, the client + sends a cleartext request for a ticket for the desired server to the + AS. The reply is sent encrypted in the client's secret key. Usually + this request is for a ticket-granting ticket (TGT) which can later be + used with the ticket-granting server (TGS). In the second method, + the client sends a request to the TGS. The client sends the TGT to + the TGS in the same manner as if it were contacting any other + application server which requires Kerberos credentials. The reply is + encrypted in the session key from the TGT. + + Once obtained, credentials may be used to verify the identity of the + principals in a transaction, to ensure the integrity of messages + exchanged between them, or to preserve privacy of the messages. The + application is free to choose whatever protection may be necessary. + + To verify the identities of the principals in a transaction, the + client transmits the ticket to the server. Since the ticket is sent + "in the clear" (parts of it are encrypted, but this encryption + doesn't thwart replay) and might be intercepted and reused by an + attacker, additional information is sent to prove that the message + was originated by the principal to whom the ticket was issued. This + information (called the authenticator) is encrypted in the session + key, and includes a timestamp. The timestamp proves that the message + was recently generated and is not a replay. Encrypting the + authenticator in the session key proves that it was generated by a + party possessing the session key. Since no one except the requesting + principal and the server know the session key (it is never sent over + the network in the clear) this guarantees the identity of the client. + + The integrity of the messages exchanged between principals can also + be guaranteed using the session key (passed in the ticket and + contained in the credentials). This approach provides detection of + both replay attacks and message stream modification attacks. It is + accomplished by generating and transmitting a collision-proof + checksum (elsewhere called a hash or digest function) of the client's + message, keyed with the session key. Privacy and integrity of the + messages exchanged between principals can be secured by encrypting + the data to be passed using the session key passed in the ticket, and + contained in the credentials. + + The authentication exchanges mentioned above require read-only access + to the Kerberos database. Sometimes, however, the entries in the + + + +Kohl & Neuman [Page 6] + +RFC 1510 Kerberos September 1993 + + + database must be modified, such as when adding new principals or + changing a principal's key. This is done using a protocol between a + client and a third Kerberos server, the Kerberos Administration + Server (KADM). The administration protocol is not described in this + document. There is also a protocol for maintaining multiple copies of + the Kerberos database, but this can be considered an implementation + detail and may vary to support different database technologies. + +1.1. Cross-Realm Operation + + The Kerberos protocol is designed to operate across organizational + boundaries. A client in one organization can be authenticated to a + server in another. Each organization wishing to run a Kerberos + server establishes its own "realm". The name of the realm in which a + client is registered is part of the client's name, and can be used by + the end-service to decide whether to honor a request. + + By establishing "inter-realm" keys, the administrators of two realms + can allow a client authenticated in the local realm to use its + authentication remotely (Of course, with appropriate permission the + client could arrange registration of a separately-named principal in + a remote realm, and engage in normal exchanges with that realm's + services. However, for even small numbers of clients this becomes + cumbersome, and more automatic methods as described here are + necessary). The exchange of inter-realm keys (a separate key may be + used for each direction) registers the ticket-granting service of + each realm as a principal in the other realm. A client is then able + to obtain a ticket-granting ticket for the remote realm's ticket- + granting service from its local realm. When that ticket-granting + ticket is used, the remote ticket-granting service uses the inter- + realm key (which usually differs from its own normal TGS key) to + decrypt the ticket-granting ticket, and is thus certain that it was + issued by the client's own TGS. Tickets issued by the remote ticket- + granting service will indicate to the end-service that the client was + authenticated from another realm. + + A realm is said to communicate with another realm if the two realms + share an inter-realm key, or if the local realm shares an inter-realm + key with an intermediate realm that communicates with the remote + realm. An authentication path is the sequence of intermediate realms + that are transited in communicating from one realm to another. + + Realms are typically organized hierarchically. Each realm shares a + key with its parent and a different key with each child. If an + inter-realm key is not directly shared by two realms, the + hierarchical organization allows an authentication path to be easily + constructed. If a hierarchical organization is not used, it may be + necessary to consult some database in order to construct an + + + +Kohl & Neuman [Page 7] + +RFC 1510 Kerberos September 1993 + + + authentication path between realms. + + Although realms are typically hierarchical, intermediate realms may + be bypassed to achieve cross-realm authentication through alternate + authentication paths (these might be established to make + communication between two realms more efficient). It is important + for the end-service to know which realms were transited when deciding + how much faith to place in the authentication process. To facilitate + this decision, a field in each ticket contains the names of the + realms that were involved in authenticating the client. + +1.2. Environmental assumptions + + Kerberos imposes a few assumptions on the environment in which it can + properly function: + + + "Denial of service" attacks are not solved with Kerberos. There + are places in these protocols where an intruder intruder can + prevent an application from participating in the proper + authentication steps. Detection and solution of such attacks + (some of which can appear to be not-uncommon "normal" failure + modes for the system) is usually best left to the human + administrators and users. + + + Principals must keep their secret keys secret. If an intruder + somehow steals a principal's key, it will be able to masquerade + as that principal or impersonate any server to the legitimate + principal. + + + "Password guessing" attacks are not solved by Kerberos. If a + user chooses a poor password, it is possible for an attacker to + successfully mount an offline dictionary attack by repeatedly + attempting to decrypt, with successive entries from a + dictionary, messages obtained which are encrypted under a key + derived from the user's password. + + + Each host on the network must have a clock which is "loosely + synchronized" to the time of the other hosts; this + synchronization is used to reduce the bookkeeping needs of + application servers when they do replay detection. The degree + of "looseness" can be configured on a per-server basis. If the + clocks are synchronized over the network, the clock + synchronization protocol must itself be secured from network + attackers. + + + Principal identifiers are not recycled on a short-term basis. A + typical mode of access control will use access control lists + (ACLs) to grant permissions to particular principals. If a + + + +Kohl & Neuman [Page 8] + +RFC 1510 Kerberos September 1993 + + + stale ACL entry remains for a deleted principal and the + principal identifier is reused, the new principal will inherit + rights specified in the stale ACL entry. By not re-using + principal identifiers, the danger of inadvertent access is + removed. + +1.3. Glossary of terms + + Below is a list of terms used throughout this document. + + + Authentication Verifying the claimed identity of a + principal. + + + Authentication header A record containing a Ticket and an + Authenticator to be presented to a + server as part of the authentication + process. + + + Authentication path A sequence of intermediate realms transited + in the authentication process when + communicating from one realm to another. + + Authenticator A record containing information that can + be shown to have been recently generated + using the session key known only by the + client and server. + + + Authorization The process of determining whether a + client may use a service, which objects + the client is allowed to access, and the + type of access allowed for each. + + + Capability A token that grants the bearer permission + to access an object or service. In + Kerberos, this might be a ticket whose + use is restricted by the contents of the + authorization data field, but which + lists no network addresses, together + with the session key necessary to use + the ticket. + + + + + + +Kohl & Neuman [Page 9] + +RFC 1510 Kerberos September 1993 + + + Ciphertext The output of an encryption function. + Encryption transforms plaintext into + ciphertext. + + + Client A process that makes use of a network + service on behalf of a user. Note that + in some cases a Server may itself be a + client of some other server (e.g., a + print server may be a client of a file + server). + + + Credentials A ticket plus the secret session key + necessary to successfully use that + ticket in an authentication exchange. + + + KDC Key Distribution Center, a network service + that supplies tickets and temporary + session keys; or an instance of that + service or the host on which it runs. + The KDC services both initial ticket and + ticket-granting ticket requests. The + initial ticket portion is sometimes + referred to as the Authentication Server + (or service). The ticket-granting + ticket portion is sometimes referred to + as the ticket-granting server (or service). + + Kerberos Aside from the 3-headed dog guarding + Hades, the name given to Project + Athena's authentication service, the + protocol used by that service, or the + code used to implement the authentication + service. + + + Plaintext The input to an encryption function or + the output of a decryption function. + Decryption transforms ciphertext into + plaintext. + + + Principal A uniquely named client or server + instance that participates in a network + communication. + + + + +Kohl & Neuman [Page 10] + +RFC 1510 Kerberos September 1993 + + + Principal identifier The name used to uniquely identify each + different principal. + + + Seal To encipher a record containing several + fields in such a way that the fields + cannot be individually replaced without + either knowledge of the encryption key + or leaving evidence of tampering. + + + Secret key An encryption key shared by a principal + and the KDC, distributed outside the + bounds of the system, with a long lifetime. + In the case of a human user's + principal, the secret key is derived + from a password. + + + Server A particular Principal which provides a + resource to network clients. + + + Service A resource provided to network clients; + often provided by more than one server + (for example, remote file service). + + + Session key A temporary encryption key used between + two principals, with a lifetime limited + to the duration of a single login "session". + + + Sub-session key A temporary encryption key used between + two principals, selected and exchanged + by the principals using the session key, + and with a lifetime limited to the duration + of a single association. + + + Ticket A record that helps a client authenticate + itself to a server; it contains the + client's identity, a session key, a + timestamp, and other information, all + sealed using the server's secret key. + It only serves to authenticate a client + when presented along with a fresh + Authenticator. + + + +Kohl & Neuman [Page 11] + +RFC 1510 Kerberos September 1993 + + +2. Ticket flag uses and requests + + Each Kerberos ticket contains a set of flags which are used to + indicate various attributes of that ticket. Most flags may be + requested by a client when the ticket is obtained; some are + automatically turned on and off by a Kerberos server as required. + The following sections explain what the various flags mean, and gives + examples of reasons to use such a flag. + +2.1. Initial and pre-authenticated tickets + + The INITIAL flag indicates that a ticket was issued using the AS + protocol and not issued based on a ticket-granting ticket. + Application servers that want to require the knowledge of a client's + secret key (e.g., a passwordchanging program) can insist that this + flag be set in any tickets they accept, and thus be assured that the + client's key was recently presented to the application client. + + The PRE-AUTHENT and HW-AUTHENT flags provide addition information + about the initial authentication, regardless of whether the current + ticket was issued directly (in which case INITIAL will also be set) + or issued on the basis of a ticket-granting ticket (in which case the + INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags are + carried forward from the ticket-granting ticket). + +2.2. Invalid tickets + + The INVALID flag indicates that a ticket is invalid. Application + servers must reject tickets which have this flag set. A postdated + ticket will usually be issued in this form. Invalid tickets must be + validated by the KDC before use, by presenting them to the KDC in a + TGS request with the VALIDATE option specified. The KDC will only + validate tickets after their starttime has passed. The validation is + required so that postdated tickets which have been stolen before + their starttime can be rendered permanently invalid (through a hot- + list mechanism). + +2.3. Renewable tickets + + Applications may desire to hold tickets which can be valid for long + periods of time. However, this can expose their credentials to + potential theft for equally long periods, and those stolen + credentials would be valid until the expiration time of the + ticket(s). Simply using shortlived tickets and obtaining new ones + periodically would require the client to have long-term access to its + secret key, an even greater risk. Renewable tickets can be used to + mitigate the consequences of theft. Renewable tickets have two + "expiration times": the first is when the current instance of the + + + +Kohl & Neuman [Page 12] + +RFC 1510 Kerberos September 1993 + + + ticket expires, and the second is the latest permissible value for an + individual expiration time. An application client must periodically + (i.e., before it expires) present a renewable ticket to the KDC, with + the RENEW option set in the KDC request. The KDC will issue a new + ticket with a new session key and a later expiration time. All other + fields of the ticket are left unmodified by the renewal process. + When the latest permissible expiration time arrives, the ticket + expires permanently. At each renewal, the KDC may consult a hot-list + to determine if the ticket had been reported stolen since its last + renewal; it will refuse to renew such stolen tickets, and thus the + usable lifetime of stolen tickets is reduced. + + The RENEWABLE flag in a ticket is normally only interpreted by the + ticket-granting service (discussed below in section 3.3). It can + usually be ignored by application servers. However, some + particularly careful application servers may wish to disallow + renewable tickets. + + If a renewable ticket is not renewed by its expiration time, the KDC + will not renew the ticket. The RENEWABLE flag is reset by default, + but a client may request it be set by setting the RENEWABLE option + in the KRB_AS_REQ message. If it is set, then the renew-till field + in the ticket contains the time after which the ticket may not be + renewed. + +2.4. Postdated tickets + + Applications may occasionally need to obtain tickets for use much + later, e.g., a batch submission system would need tickets to be valid + at the time the batch job is serviced. However, it is dangerous to + hold valid tickets in a batch queue, since they will be on-line + longer and more prone to theft. Postdated tickets provide a way to + obtain these tickets from the KDC at job submission time, but to + leave them "dormant" until they are activated and validated by a + further request of the KDC. If a ticket theft were reported in the + interim, the KDC would refuse to validate the ticket, and the thief + would be foiled. + + The MAY-POSTDATE flag in a ticket is normally only interpreted by the + ticket-granting service. It can be ignored by application servers. + This flag must be set in a ticket-granting ticket in order to issue a + postdated ticket based on the presented ticket. It is reset by + default; it may be requested by a client by setting the ALLOW- + POSTDATE option in the KRB_AS_REQ message. This flag does not allow + a client to obtain a postdated ticket-granting ticket; postdated + ticket-granting tickets can only by obtained by requesting the + postdating in the KRB_AS_REQ message. The life (endtime-starttime) + of a postdated ticket will be the remaining life of the ticket- + + + +Kohl & Neuman [Page 13] + +RFC 1510 Kerberos September 1993 + + + granting ticket at the time of the request, unless the RENEWABLE + option is also set, in which case it can be the full life (endtime- + starttime) of the ticket-granting ticket. The KDC may limit how far + in the future a ticket may be postdated. + + The POSTDATED flag indicates that a ticket has been postdated. The + application server can check the authtime field in the ticket to see + when the original authentication occurred. Some services may choose + to reject postdated tickets, or they may only accept them within a + certain period after the original authentication. When the KDC issues + a POSTDATED ticket, it will also be marked as INVALID, so that the + application client must present the ticket to the KDC to be validated + before use. + +2.5. Proxiable and proxy tickets + + At times it may be necessary for a principal to allow a service to + perform an operation on its behalf. The service must be able to take + on the identity of the client, but only for a particular purpose. A + principal can allow a service to take on the principal's identity for + a particular purpose by granting it a proxy. + + The PROXIABLE flag in a ticket is normally only interpreted by the + ticket-granting service. It can be ignored by application servers. + When set, this flag tells the ticket-granting server that it is OK to + issue a new ticket (but not a ticket-granting ticket) with a + different network address based on this ticket. This flag is set by + default. + + This flag allows a client to pass a proxy to a server to perform a + remote request on its behalf, e.g., a print service client can give + the print server a proxy to access the client's files on a particular + file server in order to satisfy a print request. + + In order to complicate the use of stolen credentials, Kerberos + tickets are usually valid from only those network addresses + specifically included in the ticket (It is permissible to request or + issue tickets with no network addresses specified, but we do not + recommend it). For this reason, a client wishing to grant a proxy + must request a new ticket valid for the network address of the + service to be granted the proxy. + + The PROXY flag is set in a ticket by the TGS when it issues a + proxy ticket. Application servers may check this flag and require + additional authentication from the agent presenting the proxy in + order to provide an audit trail. + + + + + +Kohl & Neuman [Page 14] + +RFC 1510 Kerberos September 1993 + + +2.6. Forwardable tickets + + Authentication forwarding is an instance of the proxy case where the + service is granted complete use of the client's identity. An example + where it might be used is when a user logs in to a remote system and + wants authentication to work from that system as if the login were + local. + + The FORWARDABLE flag in a ticket is normally only interpreted by the + ticket-granting service. It can be ignored by application servers. + The FORWARDABLE flag has an interpretation similar to that of the + PROXIABLE flag, except ticket-granting tickets may also be issued + with different network addresses. This flag is reset by default, but + users may request that it be set by setting the FORWARDABLE option in + the AS request when they request their initial ticket-granting + ticket. + + This flag allows for authentication forwarding without requiring the + user to enter a password again. If the flag is not set, then + authentication forwarding is not permitted, but the same end result + can still be achieved if the user engages in the AS exchange with the + requested network addresses and supplies a password. + + The FORWARDED flag is set by the TGS when a client presents a ticket + with the FORWARDABLE flag set and requests it be set by specifying + the FORWARDED KDC option and supplying a set of addresses for the new + ticket. It is also set in all tickets issued based on tickets with + the FORWARDED flag set. Application servers may wish to process + FORWARDED tickets differently than non-FORWARDED tickets. + +2.7. Other KDC options + + There are two additional options which may be set in a client's + request of the KDC. The RENEWABLE-OK option indicates that the + client will accept a renewable ticket if a ticket with the requested + life cannot otherwise be provided. If a ticket with the requested + life cannot be provided, then the KDC may issue a renewable ticket + with a renew-till equal to the the requested endtime. The value of + the renew-till field may still be adjusted by site-determined limits + or limits imposed by the individual principal or server. + + The ENC-TKT-IN-SKEY option is honored only by the ticket-granting + service. It indicates that the to-be-issued ticket for the end + server is to be encrypted in the session key from the additional + ticket-granting ticket provided with the request. See section 3.3.3 + for specific details. + + + + + +Kohl & Neuman [Page 15] + +RFC 1510 Kerberos September 1993 + + +3. Message Exchanges + + The following sections describe the interactions between network + clients and servers and the messages involved in those exchanges. + +3.1. The Authentication Service Exchange + + Summary + + Message direction Message type Section + 1. Client to Kerberos KRB_AS_REQ 5.4.1 + 2. Kerberos to client KRB_AS_REP or 5.4.2 + KRB_ERROR 5.9.1 + + The Authentication Service (AS) Exchange between the client and the + Kerberos Authentication Server is usually initiated by a client when + it wishes to obtain authentication credentials for a given server but + currently holds no credentials. The client's secret key is used for + encryption and decryption. This exchange is typically used at the + initiation of a login session, to obtain credentials for a Ticket- + Granting Server, which will subsequently be used to obtain + credentials for other servers (see section 3.3) without requiring + further use of the client's secret key. This exchange is also used + to request credentials for services which must not be mediated + through the Ticket-Granting Service, but rather require a principal's + secret key, such as the password-changing service. (The password- + changing request must not be honored unless the requester can provide + the old password (the user's current secret key). Otherwise, it + would be possible for someone to walk up to an unattended session and + change another user's password.) This exchange does not by itself + provide any assurance of the the identity of the user. (To + authenticate a user logging on to a local system, the credentials + obtained in the AS exchange may first be used in a TGS exchange to + obtain credentials for a local server. Those credentials must then + be verified by the local server through successful completion of the + Client/Server exchange.) + + The exchange consists of two messages: KRB_AS_REQ from the client to + Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these + messages are described in sections 5.4.1, 5.4.2, and 5.9.1. + + In the request, the client sends (in cleartext) its own identity and + the identity of the server for which it is requesting credentials. + The response, KRB_AS_REP, contains a ticket for the client to present + to the server, and a session key that will be shared by the client + and the server. The session key and additional information are + encrypted in the client's secret key. The KRB_AS_REP message + contains information which can be used to detect replays, and to + + + +Kohl & Neuman [Page 16] + +RFC 1510 Kerberos September 1993 + + + associate it with the message to which it replies. Various errors + can occur; these are indicated by an error response (KRB_ERROR) + instead of the KRB_AS_REP response. The error message is not + encrypted. The KRB_ERROR message also contains information which can + be used to associate it with the message to which it replies. The + lack of encryption in the KRB_ERROR message precludes the ability to + detect replays or fabrications of such messages. + + In the normal case the authentication server does not know whether + the client is actually the principal named in the request. It simply + sends a reply without knowing or caring whether they are the same. + This is acceptable because nobody but the principal whose identity + was given in the request will be able to use the reply. Its critical + information is encrypted in that principal's key. The initial + request supports an optional field that can be used to pass + additional information that might be needed for the initial exchange. + This field may be used for preauthentication if desired, but the + mechanism is not currently specified. + +3.1.1. Generation of KRB_AS_REQ message + + The client may specify a number of options in the initial request. + Among these options are whether preauthentication is to be performed; + whether the requested ticket is to be renewable, proxiable, or + forwardable; whether it should be postdated or allow postdating of + derivative tickets; and whether a renewable ticket will be accepted + in lieu of a non-renewable ticket if the requested ticket expiration + date cannot be satisfied by a nonrenewable ticket (due to + configuration constraints; see section 4). See section A.1 for + pseudocode. + + The client prepares the KRB_AS_REQ message and sends it to the KDC. + +3.1.2. Receipt of KRB_AS_REQ message + + If all goes well, processing the KRB_AS_REQ message will result in + the creation of a ticket for the client to present to the server. + The format for the ticket is described in section 5.3.1. The + contents of the ticket are determined as follows. + +3.1.3. Generation of KRB_AS_REP message + + The authentication server looks up the client and server principals + named in the KRB_AS_REQ in its database, extracting their respective + keys. If required, the server pre-authenticates the request, and if + the pre-authentication check fails, an error message with the code + KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate + the requested encryption type, an error message with code + + + +Kohl & Neuman [Page 17] + +RFC 1510 Kerberos September 1993 + + + KDC_ERR_ETYPE_NOSUPP is returned. Otherwise it generates a "random" + session key ("Random" means that, among other things, it should be + impossible to guess the next session key based on knowledge of past + session keys. This can only be achieved in a pseudo-random number + generator if it is based on cryptographic principles. It would be + more desirable to use a truly random number generator, such as one + based on measurements of random physical phenomena.). + + If the requested start time is absent or indicates a time in the + past, then the start time of the ticket is set to the authentication + server's current time. If it indicates a time in the future, but the + POSTDATED option has not been specified, then the error + KDC_ERR_CANNOT_POSTDATE is returned. Otherwise the requested start + time is checked against the policy of the local realm (the + administrator might decide to prohibit certain types or ranges of + postdated tickets), and if acceptable, the ticket's start time is set + as requested and the INVALID flag is set in the new ticket. The + postdated ticket must be validated before use by presenting it to the + KDC after the start time has been reached. + + The expiration time of the ticket will be set to the minimum of the + following: + + +The expiration time (endtime) requested in the KRB_AS_REQ + message. + + +The ticket's start time plus the maximum allowable lifetime + associated with the client principal (the authentication + server's database includes a maximum ticket lifetime field + in each principal's record; see section 4). + + +The ticket's start time plus the maximum allowable lifetime + associated with the server principal. + + +The ticket's start time plus the maximum lifetime set by + the policy of the local realm. + + If the requested expiration time minus the start time (as determined + above) is less than a site-determined minimum lifetime, an error + message with code KDC_ERR_NEVER_VALID is returned. If the requested + expiration time for the ticket exceeds what was determined as above, + and if the "RENEWABLE-OK" option was requested, then the "RENEWABLE" + flag is set in the new ticket, and the renew-till value is set as if + the "RENEWABLE" option were requested (the field and option names are + described fully in section 5.4.1). If the RENEWABLE option has been + requested or if the RENEWABLE-OK option has been set and a renewable + ticket is to be issued, then the renew-till field is set to the + minimum of: + + + +Kohl & Neuman [Page 18] + +RFC 1510 Kerberos September 1993 + + + +Its requested value. + + +The start time of the ticket plus the minimum of the two + maximum renewable lifetimes associated with the principals' + database entries. + + +The start time of the ticket plus the maximum renewable + lifetime set by the policy of the local realm. + + The flags field of the new ticket will have the following options set + if they have been requested and if the policy of the local realm + allows: FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. + If the new ticket is postdated (the start time is in the future), its + INVALID flag will also be set. + + If all of the above succeed, the server formats a KRB_AS_REP message + (see section 5.4.2), copying the addresses in the request into the + caddr of the response, placing any required pre-authentication data + into the padata of the response, and encrypts the ciphertext part in + the client's key using the requested encryption method, and sends it + to the client. See section A.2 for pseudocode. + +3.1.4. Generation of KRB_ERROR message + + Several errors can occur, and the Authentication Server responds by + returning an error message, KRB_ERROR, to the client, with the + error-code and e-text fields set to appropriate values. The error + message contents and details are described in Section 5.9.1. + +3.1.5. Receipt of KRB_AS_REP message + + If the reply message type is KRB_AS_REP, then the client verifies + that the cname and crealm fields in the cleartext portion of the + reply match what it requested. If any padata fields are present, + they may be used to derive the proper secret key to decrypt the + message. The client decrypts the encrypted part of the response + using its secret key, verifies that the nonce in the encrypted part + matches the nonce it supplied in its request (to detect replays). It + also verifies that the sname and srealm in the response match those + in the request, and that the host address field is also correct. It + then stores the ticket, session key, start and expiration times, and + other information for later use. The key-expiration field from the + encrypted part of the response may be checked to notify the user of + impending key expiration (the client program could then suggest + remedial action, such as a password change). See section A.3 for + pseudocode. + + Proper decryption of the KRB_AS_REP message is not sufficient to + + + +Kohl & Neuman [Page 19] + +RFC 1510 Kerberos September 1993 + + + verify the identity of the user; the user and an attacker could + cooperate to generate a KRB_AS_REP format message which decrypts + properly but is not from the proper KDC. If the host wishes to + verify the identity of the user, it must require the user to present + application credentials which can be verified using a securely-stored + secret key. If those credentials can be verified, then the identity + of the user can be assured. + +3.1.6. Receipt of KRB_ERROR message + + If the reply message type is KRB_ERROR, then the client interprets it + as an error and performs whatever application-specific tasks are + necessary to recover. + +3.2. The Client/Server Authentication Exchange + + Summary + + Message direction Message type Section + Client to Application server KRB_AP_REQ 5.5.1 + [optional] Application server to client KRB_AP_REP or 5.5.2 + KRB_ERROR 5.9.1 + + The client/server authentication (CS) exchange is used by network + applications to authenticate the client to the server and vice versa. + The client must have already acquired credentials for the server + using the AS or TGS exchange. + +3.2.1. The KRB_AP_REQ message + + The KRB_AP_REQ contains authentication information which should be + part of the first message in an authenticated transaction. It + contains a ticket, an authenticator, and some additional bookkeeping + information (see section 5.5.1 for the exact format). The ticket by + itself is insufficient to authenticate a client, since tickets are + passed across the network in cleartext(Tickets contain both an + encrypted and unencrypted portion, so cleartext here refers to the + entire unit, which can be copied from one message and replayed in + another without any cryptographic skill.), so the authenticator is + used to prevent invalid replay of tickets by proving to the server + that the client knows the session key of the ticket and thus is + entitled to use it. The KRB_AP_REQ message is referred to elsewhere + as the "authentication header." + +3.2.2. Generation of a KRB_AP_REQ message + + When a client wishes to initiate authentication to a server, it + obtains (either through a credentials cache, the AS exchange, or the + + + +Kohl & Neuman [Page 20] + +RFC 1510 Kerberos September 1993 + + + TGS exchange) a ticket and session key for the desired service. The + client may re-use any tickets it holds until they expire. The client + then constructs a new Authenticator from the the system time, its + name, and optionally an application specific checksum, an initial + sequence number to be used in KRB_SAFE or KRB_PRIV messages, and/or a + session subkey to be used in negotiations for a session key unique to + this particular session. Authenticators may not be re-used and will + be rejected if replayed to a server (Note that this can make + applications based on unreliable transports difficult to code + correctly, if the transport might deliver duplicated messages. In + such cases, a new authenticator must be generated for each retry.). + If a sequence number is to be included, it should be randomly chosen + so that even after many messages have been exchanged it is not likely + to collide with other sequence numbers in use. + + The client may indicate a requirement of mutual authentication or the + use of a session-key based ticket by setting the appropriate flag(s) + in the ap-options field of the message. + + The Authenticator is encrypted in the session key and combined with + the ticket to form the KRB_AP_REQ message which is then sent to the + end server along with any additional application-specific + information. See section A.9 for pseudocode. + +3.2.3. Receipt of KRB_AP_REQ message + + Authentication is based on the server's current time of day (clocks + must be loosely synchronized), the authenticator, and the ticket. + Several errors are possible. If an error occurs, the server is + expected to reply to the client with a KRB_ERROR message. This + message may be encapsulated in the application protocol if its "raw" + form is not acceptable to the protocol. The format of error messages + is described in section 5.9.1. + + The algorithm for verifying authentication information is as follows. + If the message type is not KRB_AP_REQ, the server returns the + KRB_AP_ERR_MSG_TYPE error. If the key version indicated by the Ticket + in the KRB_AP_REQ is not one the server can use (e.g., it indicates + an old key, and the server no longer possesses a copy of the old + key), the KRB_AP_ERR_BADKEYVER error is returned. If the USE- + SESSION-KEY flag is set in the ap-options field, it indicates to the + server that the ticket is encrypted in the session key from the + server's ticket-granting ticket rather than its secret key (This is + used for user-to-user authentication as described in [6]). Since it + is possible for the server to be registered in multiple realms, with + different keys in each, the srealm field in the unencrypted portion + of the ticket in the KRB_AP_REQ is used to specify which secret key + the server should use to decrypt that ticket. The KRB_AP_ERR_NOKEY + + + +Kohl & Neuman [Page 21] + +RFC 1510 Kerberos September 1993 + + + error code is returned if the server doesn't have the proper key to + decipher the ticket. + + The ticket is decrypted using the version of the server's key + specified by the ticket. If the decryption routines detect a + modification of the ticket (each encryption system must provide + safeguards to detect modified ciphertext; see section 6), the + KRB_AP_ERR_BAD_INTEGRITY error is returned (chances are good that + different keys were used to encrypt and decrypt). + + The authenticator is decrypted using the session key extracted from + the decrypted ticket. If decryption shows it to have been modified, + the KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm + of the client from the ticket are compared against the same fields in + the authenticator. If they don't match, the KRB_AP_ERR_BADMATCH + error is returned (they might not match, for example, if the wrong + session key was used to encrypt the authenticator). The addresses in + the ticket (if any) are then searched for an address matching the + operating-system reported address of the client. If no match is + found or the server insists on ticket addresses but none are present + in the ticket, the KRB_AP_ERR_BADADDR error is returned. + + If the local (server) time and the client time in the authenticator + differ by more than the allowable clock skew (e.g., 5 minutes), the + KRB_AP_ERR_SKEW error is returned. If the server name, along with + the client name, time and microsecond fields from the Authenticator + match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is + returned (Note that the rejection here is restricted to + authenticators from the same principal to the same server. Other + client principals communicating with the same server principal should + not be have their authenticators rejected if the time and microsecond + fields happen to match some other client's authenticator.). The + server must remember any authenticator presented within the allowable + clock skew, so that a replay attempt is guaranteed to fail. If a + server loses track of any authenticator presented within the + allowable clock skew, it must reject all requests until the clock + skew interval has passed. This assures that any lost or re-played + authenticators will fall outside the allowable clock skew and can no + longer be successfully replayed (If this is not done, an attacker + could conceivably record the ticket and authenticator sent over the + network to a server, then disable the client's host, pose as the + disabled host, and replay the ticket and authenticator to subvert the + authentication.). If a sequence number is provided in the + authenticator, the server saves it for later use in processing + KRB_SAFE and/or KRB_PRIV messages. If a subkey is present, the + server either saves it for later use or uses it to help generate its + own choice for a subkey to be returned in a KRB_AP_REP message. + + + + +Kohl & Neuman [Page 22] + +RFC 1510 Kerberos September 1993 + + + The server computes the age of the ticket: local (server) time minus + the start time inside the Ticket. If the start time is later than + the current time by more than the allowable clock skew or if the + INVALID flag is set in the ticket, the KRB_AP_ERR_TKT_NYV error is + returned. Otherwise, if the current time is later than end time by + more than the allowable clock skew, the KRB_AP_ERR_TKT_EXPIRED error + is returned. + + If all these checks succeed without an error, the server is assured + that the client possesses the credentials of the principal named in + the ticket and thus, the client has been authenticated to the server. + See section A.10 for pseudocode. + +3.2.4. Generation of a KRB_AP_REP message + + Typically, a client's request will include both the authentication + information and its initial request in the same message, and the + server need not explicitly reply to the KRB_AP_REQ. However, if + mutual authentication (not only authenticating the client to the + server, but also the server to the client) is being performed, the + KRB_AP_REQ message will have MUTUAL-REQUIRED set in its ap-options + field, and a KRB_AP_REP message is required in response. As with the + error message, this message may be encapsulated in the application + protocol if its "raw" form is not acceptable to the application's + protocol. The timestamp and microsecond field used in the reply must + be the client's timestamp and microsecond field (as provided in the + authenticator). [Note: In the Kerberos version 4 protocol, the + timestamp in the reply was the client's timestamp plus one. This is + not necessary in version 5 because version 5 messages are formatted + in such a way that it is not possible to create the reply by + judicious message surgery (even in encrypted form) without knowledge + of the appropriate encryption keys.] If a sequence number is to be + included, it should be randomly chosen as described above for the + authenticator. A subkey may be included if the server desires to + negotiate a different subkey. The KRB_AP_REP message is encrypted in + the session key extracted from the ticket. See section A.11 for + pseudocode. + +3.2.5. Receipt of KRB_AP_REP message + + If a KRB_AP_REP message is returned, the client uses the session key + from the credentials obtained for the server (Note that for + encrypting the KRB_AP_REP message, the sub-session key is not used, + even if present in the Authenticator.) to decrypt the message, and + verifies that the timestamp and microsecond fields match those in the + Authenticator it sent to the server. If they match, then the client + is assured that the server is genuine. The sequence number and subkey + (if present) are retained for later use. See section A.12 for + + + +Kohl & Neuman [Page 23] + +RFC 1510 Kerberos September 1993 + + + pseudocode. + +3.2.6. Using the encryption key + + After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and + server share an encryption key which can be used by the application. + The "true session key" to be used for KRB_PRIV, KRB_SAFE, or other + application-specific uses may be chosen by the application based on + the subkeys in the KRB_AP_REP message and the authenticator + (Implementations of the protocol may wish to provide routines to + choose subkeys based on session keys and random numbers and to + orchestrate a negotiated key to be returned in the KRB_AP_REP + message.). In some cases, the use of this session key will be + implicit in the protocol; in others the method of use must be chosen + from a several alternatives. We leave the protocol negotiations of + how to use the key (e.g., selecting an encryption or checksum type) + to the application programmer; the Kerberos protocol does not + constrain the implementation options. + + With both the one-way and mutual authentication exchanges, the peers + should take care not to send sensitive information to each other + without proper assurances. In particular, applications that require + privacy or integrity should use the KRB_AP_REP or KRB_ERROR responses + from the server to client to assure both client and server of their + peer's identity. If an application protocol requires privacy of its + messages, it can use the KRB_PRIV message (section 3.5). The KRB_SAFE + message (section 3.4) can be used to assure integrity. + +3.3. The Ticket-Granting Service (TGS) Exchange + + Summary + + Message direction Message type Section + 1. Client to Kerberos KRB_TGS_REQ 5.4.1 + 2. Kerberos to client KRB_TGS_REP or 5.4.2 + KRB_ERROR 5.9.1 + + The TGS exchange between a client and the Kerberos Ticket-Granting + Server is initiated by a client when it wishes to obtain + authentication credentials for a given server (which might be + registered in a remote realm), when it wishes to renew or validate an + existing ticket, or when it wishes to obtain a proxy ticket. In the + first case, the client must already have acquired a ticket for the + Ticket-Granting Service using the AS exchange (the ticket-granting + ticket is usually obtained when a client initially authenticates to + the system, such as when a user logs in). The message format for the + TGS exchange is almost identical to that for the AS exchange. The + primary difference is that encryption and decryption in the TGS + + + +Kohl & Neuman [Page 24] + +RFC 1510 Kerberos September 1993 + + + exchange does not take place under the client's key. Instead, the + session key from the ticket-granting ticket or renewable ticket, or + sub-session key from an Authenticator is used. As is the case for + all application servers, expired tickets are not accepted by the TGS, + so once a renewable or ticket-granting ticket expires, the client + must use a separate exchange to obtain valid tickets. + + The TGS exchange consists of two messages: A request (KRB_TGS_REQ) + from the client to the Kerberos Ticket-Granting Server, and a reply + (KRB_TGS_REP or KRB_ERROR). The KRB_TGS_REQ message includes + information authenticating the client plus a request for credentials. + The authentication information consists of the authentication header + (KRB_AP_REQ) which includes the client's previously obtained ticket- + granting, renewable, or invalid ticket. In the ticket-granting + ticket and proxy cases, the request may include one or more of: a + list of network addresses, a collection of typed authorization data + to be sealed in the ticket for authorization use by the application + server, or additional tickets (the use of which are described later). + The TGS reply (KRB_TGS_REP) contains the requested credentials, + encrypted in the session key from the ticket-granting ticket or + renewable ticket, or if present, in the subsession key from the + Authenticator (part of the authentication header). The KRB_ERROR + message contains an error code and text explaining what went wrong. + The KRB_ERROR message is not encrypted. The KRB_TGS_REP message + contains information which can be used to detect replays, and to + associate it with the message to which it replies. The KRB_ERROR + message also contains information which can be used to associate it + with the message to which it replies, but the lack of encryption in + the KRB_ERROR message precludes the ability to detect replays or + fabrications of such messages. + +3.3.1. Generation of KRB_TGS_REQ message + + Before sending a request to the ticket-granting service, the client + must determine in which realm the application server is registered + [Note: This can be accomplished in several ways. It might be known + beforehand (since the realm is part of the principal identifier), or + it might be stored in a nameserver. Presently, however, this + information is obtained from a configuration file. If the realm to + be used is obtained from a nameserver, there is a danger of being + spoofed if the nameservice providing the realm name is not + authenticated. This might result in the use of a realm which has + been compromised, and would result in an attacker's ability to + compromise the authentication of the application server to the + client.]. If the client does not already possess a ticket-granting + ticket for the appropriate realm, then one must be obtained. This is + first attempted by requesting a ticket-granting ticket for the + destination realm from the local Kerberos server (using the + + + +Kohl & Neuman [Page 25] + +RFC 1510 Kerberos September 1993 + + + KRB_TGS_REQ message recursively). The Kerberos server may return a + TGT for the desired realm in which case one can proceed. + Alternatively, the Kerberos server may return a TGT for a realm which + is "closer" to the desired realm (further along the standard + hierarchical path), in which case this step must be repeated with a + Kerberos server in the realm specified in the returned TGT. If + neither are returned, then the request must be retried with a + Kerberos server for a realm higher in the hierarchy. This request + will itself require a ticket-granting ticket for the higher realm + which must be obtained by recursively applying these directions. + + Once the client obtains a ticket-granting ticket for the appropriate + realm, it determines which Kerberos servers serve that realm, and + contacts one. The list might be obtained through a configuration file + or network service; as long as the secret keys exchanged by realms + are kept secret, only denial of service results from a false Kerberos + server. + + As in the AS exchange, the client may specify a number of options in + the KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ + message, providing an authentication header as an element of the + padata field, and including the same fields as used in the KRB_AS_REQ + message along with several optional fields: the enc-authorization- + data field for application server use and additional tickets required + by some options. + + In preparing the authentication header, the client can select a sub- + session key under which the response from the Kerberos server will be + encrypted (If the client selects a sub-session key, care must be + taken to ensure the randomness of the selected subsession key. One + approach would be to generate a random number and XOR it with the + session key from the ticket-granting ticket.). If the sub-session key + is not specified, the session key from the ticket-granting ticket + will be used. If the enc-authorization-data is present, it must be + encrypted in the sub-session key, if present, from the authenticator + portion of the authentication header, or if not present in the + session key from the ticket-granting ticket. + + Once prepared, the message is sent to a Kerberos server for the + destination realm. See section A.5 for pseudocode. + +3.3.2. Receipt of KRB_TGS_REQ message + + The KRB_TGS_REQ message is processed in a manner similar to the + KRB_AS_REQ message, but there are many additional checks to be + performed. First, the Kerberos server must determine which server + the accompanying ticket is for and it must select the appropriate key + to decrypt it. For a normal KRB_TGS_REQ message, it will be for the + + + +Kohl & Neuman [Page 26] + +RFC 1510 Kerberos September 1993 + + + ticket granting service, and the TGS's key will be used. If the TGT + was issued by another realm, then the appropriate inter-realm key + must be used. If the accompanying ticket is not a ticket granting + ticket for the current realm, but is for an application server in the + current realm, the RENEW, VALIDATE, or PROXY options are specified in + the request, and the server for which a ticket is requested is the + server named in the accompanying ticket, then the KDC will decrypt + the ticket in the authentication header using the key of the server + for which it was issued. If no ticket can be found in the padata + field, the KDC_ERR_PADATA_TYPE_NOSUPP error is returned. + + Once the accompanying ticket has been decrypted, the user-supplied + checksum in the Authenticator must be verified against the contents + of the request, and the message rejected if the checksums do not + match (with an error code of KRB_AP_ERR_MODIFIED) or if the checksum + is not keyed or not collision-proof (with an error code of + KRB_AP_ERR_INAPP_CKSUM). If the checksum type is not supported, the + KDC_ERR_SUMTYPE_NOSUPP error is returned. If the authorization-data + are present, they are decrypted using the sub-session key from the + Authenticator. + + If any of the decryptions indicate failed integrity checks, the + KRB_AP_ERR_BAD_INTEGRITY error is returned. + +3.3.3. Generation of KRB_TGS_REP message + + The KRB_TGS_REP message shares its format with the KRB_AS_REP + (KRB_KDC_REP), but with its type field set to KRB_TGS_REP. The + detailed specification is in section 5.4.2. + + The response will include a ticket for the requested server. The + Kerberos database is queried to retrieve the record for the requested + server (including the key with which the ticket will be encrypted). + If the request is for a ticket granting ticket for a remote realm, + and if no key is shared with the requested realm, then the Kerberos + server will select the realm "closest" to the requested realm with + which it does share a key, and use that realm instead. This is the + only case where the response from the KDC will be for a different + server than that requested by the client. + + By default, the address field, the client's name and realm, the list + of transited realms, the time of initial authentication, the + expiration time, and the authorization data of the newly-issued + ticket will be copied from the ticket-granting ticket (TGT) or + renewable ticket. If the transited field needs to be updated, but + the transited type is not supported, the KDC_ERR_TRTYPE_NOSUPP error + is returned. + + + + +Kohl & Neuman [Page 27] + +RFC 1510 Kerberos September 1993 + + + If the request specifies an endtime, then the endtime of the new + ticket is set to the minimum of (a) that request, (b) the endtime + from the TGT, and (c) the starttime of the TGT plus the minimum of + the maximum life for the application server and the maximum life for + the local realm (the maximum life for the requesting principal was + already applied when the TGT was issued). If the new ticket is to be + a renewal, then the endtime above is replaced by the minimum of (a) + the value of the renew_till field of the ticket and (b) the starttime + for the new ticket plus the life (endtimestarttime) of the old + ticket. + + If the FORWARDED option has been requested, then the resulting ticket + will contain the addresses specified by the client. This option will + only be honored if the FORWARDABLE flag is set in the TGT. The PROXY + option is similar; the resulting ticket will contain the addresses + specified by the client. It will be honored only if the PROXIABLE + flag in the TGT is set. The PROXY option will not be honored on + requests for additional ticket-granting tickets. + + If the requested start time is absent or indicates a time in the + past, then the start time of the ticket is set to the authentication + server's current time. If it indicates a time in the future, but the + POSTDATED option has not been specified or the MAY-POSTDATE flag is + not set in the TGT, then the error KDC_ERR_CANNOT_POSTDATE is + returned. Otherwise, if the ticket-granting ticket has the + MAYPOSTDATE flag set, then the resulting ticket will be postdated and + the requested starttime is checked against the policy of the local + realm. If acceptable, the ticket's start time is set as requested, + and the INVALID flag is set. The postdated ticket must be validated + before use by presenting it to the KDC after the starttime has been + reached. However, in no case may the starttime, endtime, or renew- + till time of a newly-issued postdated ticket extend beyond the + renew-till time of the ticket-granting ticket. + + If the ENC-TKT-IN-SKEY option has been specified and an additional + ticket has been included in the request, the KDC will decrypt the + additional ticket using the key for the server to which the + additional ticket was issued and verify that it is a ticket-granting + ticket. If the name of the requested server is missing from the + request, the name of the client in the additional ticket will be + used. Otherwise the name of the requested server will be compared to + the name of the client in the additional ticket and if different, the + request will be rejected. If the request succeeds, the session key + from the additional ticket will be used to encrypt the new ticket + that is issued instead of using the key of the server for which the + new ticket will be used (This allows easy implementation of user-to- + user authentication [6], which uses ticket-granting ticket session + keys in lieu of secret server keys in situations where such secret + + + +Kohl & Neuman [Page 28] + +RFC 1510 Kerberos September 1993 + + + keys could be easily compromised.). + + If the name of the server in the ticket that is presented to the KDC + as part of the authentication header is not that of the ticket- + granting server itself, and the server is registered in the realm of + the KDC, If the RENEW option is requested, then the KDC will verify + that the RENEWABLE flag is set in the ticket and that the renew_till + time is still in the future. If the VALIDATE option is rqeuested, + the KDC will check that the starttime has passed and the INVALID flag + is set. If the PROXY option is requested, then the KDC will check + that the PROXIABLE flag is set in the ticket. If the tests succeed, + the KDC will issue the appropriate new ticket. + + Whenever a request is made to the ticket-granting server, the + presented ticket(s) is(are) checked against a hot-list of tickets + which have been canceled. This hot-list might be implemented by + storing a range of issue dates for "suspect tickets"; if a presented + ticket had an authtime in that range, it would be rejected. In this + way, a stolen ticket-granting ticket or renewable ticket cannot be + used to gain additional tickets (renewals or otherwise) once the + theft has been reported. Any normal ticket obtained before it was + reported stolen will still be valid (because they require no + interaction with the KDC), but only until their normal expiration + time. + + The ciphertext part of the response in the KRB_TGS_REP message is + encrypted in the sub-session key from the Authenticator, if present, + or the session key key from the ticket-granting ticket. It is not + encrypted using the client's secret key. Furthermore, the client's + key's expiration date and the key version number fields are left out + since these values are stored along with the client's database + record, and that record is not needed to satisfy a request based on a + ticket-granting ticket. See section A.6 for pseudocode. + +3.3.3.1. Encoding the transited field + + If the identity of the server in the TGT that is presented to the KDC + as part of the authentication header is that of the ticket-granting + service, but the TGT was issued from another realm, the KDC will look + up the inter-realm key shared with that realm and use that key to + decrypt the ticket. If the ticket is valid, then the KDC will honor + the request, subject to the constraints outlined above in the section + describing the AS exchange. The realm part of the client's identity + will be taken from the ticket-granting ticket. The name of the realm + that issued the ticket-granting ticket will be added to the transited + field of the ticket to be issued. This is accomplished by reading + the transited field from the ticket-granting ticket (which is treated + as an unordered set of realm names), adding the new realm to the set, + + + +Kohl & Neuman [Page 29] + +RFC 1510 Kerberos September 1993 + + + then constructing and writing out its encoded (shorthand) form (this + may involve a rearrangement of the existing encoding). + + Note that the ticket-granting service does not add the name of its + own realm. Instead, its responsibility is to add the name of the + previous realm. This prevents a malicious Kerberos server from + intentionally leaving out its own name (it could, however, omit other + realms' names). + + The names of neither the local realm nor the principal's realm are to + be included in the transited field. They appear elsewhere in the + ticket and both are known to have taken part in authenticating the + principal. Since the endpoints are not included, both local and + single-hop inter-realm authentication result in a transited field + that is empty. + + Because the name of each realm transited is added to this field, + it might potentially be very long. To decrease the length of this + field, its contents are encoded. The initially supported encoding is + optimized for the normal case of inter-realm communication: a + hierarchical arrangement of realms using either domain or X.500 style + realm names. This encoding (called DOMAIN-X500-COMPRESS) is now + described. + + Realm names in the transited field are separated by a ",". The ",", + "\", trailing "."s, and leading spaces (" ") are special characters, + and if they are part of a realm name, they must be quoted in the + transited field by preceding them with a "\". + + A realm name ending with a "." is interpreted as being prepended to + the previous realm. For example, we can encode traversal of EDU, + MIT.EDU, ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: + + "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". + + Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were endpoints, + that they would not be included in this field, and we would have: + + "EDU,MIT.,WASHINGTON.EDU" + + A realm name beginning with a "/" is interpreted as being appended to + the previous realm (For the purpose of appending, the realm preceding + the first listed realm is considered to be the null realm ("")). If + it is to stand by itself, then it should be preceded by a space (" + "). For example, we can encode traversal of /COM/HP/APOLLO, /COM/HP, + /COM, and /COM/DEC as: + + "/COM,/HP,/APOLLO, /COM/DEC". + + + +Kohl & Neuman [Page 30] + +RFC 1510 Kerberos September 1993 + + + Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, + they they would not be included in this field, and we would have: + + "/COM,/HP" + + A null subfield preceding or following a "," indicates that all + realms between the previous realm and the next realm have been + traversed (For the purpose of interpreting null subfields, the + client's realm is considered to precede those in the transited field, + and the server's realm is considered to follow them.). Thus, "," + means that all realms along the path between the client and the + server have been traversed. ",EDU, /COM," means that that all realms + from the client's realm up to EDU (in a domain style hierarchy) have + been traversed, and that everything from /COM down to the server's + realm in an X.500 style has also been traversed. This could occur if + the EDU realm in one hierarchy shares an inter-realm key directly + with the /COM realm in another hierarchy. + +3.3.4. Receipt of KRB_TGS_REP message + + When the KRB_TGS_REP is received by the client, it is processed in + the same manner as the KRB_AS_REP processing described above. The + primary difference is that the ciphertext part of the response must + be decrypted using the session key from the ticket-granting ticket + rather than the client's secret key. See section A.7 for pseudocode. + +3.4. The KRB_SAFE Exchange + + The KRB_SAFE message may be used by clients requiring the ability to + detect modifications of messages they exchange. It achieves this by + including a keyed collisionproof checksum of the user data and some + control information. The checksum is keyed with an encryption key + (usually the last key negotiated via subkeys, or the session key if + no negotiation has occured). + +3.4.1. Generation of a KRB_SAFE message + + When an application wishes to send a KRB_SAFE message, it collects + its data and the appropriate control information and computes a + checksum over them. The checksum algorithm should be some sort of + keyed one-way hash function (such as the RSA-MD5-DES checksum + algorithm specified in section 6.4.5, or the DES MAC), generated + using the sub-session key if present, or the session key. Different + algorithms may be selected by changing the checksum type in the + message. Unkeyed or non-collision-proof checksums are not suitable + for this use. + + The control information for the KRB_SAFE message includes both a + + + +Kohl & Neuman [Page 31] + +RFC 1510 Kerberos September 1993 + + + timestamp and a sequence number. The designer of an application + using the KRB_SAFE message must choose at least one of the two + mechanisms. This choice should be based on the needs of the + application protocol. + + Sequence numbers are useful when all messages sent will be received + by one's peer. Connection state is presently required to maintain + the session key, so maintaining the next sequence number should not + present an additional problem. + + If the application protocol is expected to tolerate lost messages + without them being resent, the use of the timestamp is the + appropriate replay detection mechanism. Using timestamps is also the + appropriate mechanism for multi-cast protocols where all of one's + peers share a common sub-session key, but some messages will be sent + to a subset of one's peers. + + After computing the checksum, the client then transmits the + information and checksum to the recipient in the message format + specified in section 5.6.1. + +3.4.2. Receipt of KRB_SAFE message + + When an application receives a KRB_SAFE message, it verifies it as + follows. If any error occurs, an error code is reported for use by + the application. + + The message is first checked by verifying that the protocol version + and type fields match the current version and KRB_SAFE, respectively. + A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE + error. The application verifies that the checksum used is a + collisionproof keyed checksum, and if it is not, a + KRB_AP_ERR_INAPP_CKSUM error is generated. The recipient verifies + that the operating system's report of the sender's address matches + the sender's address in the message, and (if a recipient address is + specified or the recipient requires an address) that one of the + recipient's addresses appears as the recipient's address in the + message. A failed match for either case generates a + KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the + sequence number fields are checked. If timestamp and usec are + expected and not present, or they are present but not current, the + KRB_AP_ERR_SKEW error is generated. If the server name, along with + the client name, time and microsecond fields from the Authenticator + match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is + generated. If an incorrect sequence number is included, or a + sequence number is expected but not present, the KRB_AP_ERR_BADORDER + error is generated. If neither a timestamp and usec or a sequence + number is present, a KRB_AP_ERR_MODIFIED error is generated. + + + +Kohl & Neuman [Page 32] + +RFC 1510 Kerberos September 1993 + + + Finally, the checksum is computed over the data and control + information, and if it doesn't match the received checksum, a + KRB_AP_ERR_MODIFIED error is generated. + + If all the checks succeed, the application is assured that the + message was generated by its peer and was not modified in transit. + +3.5. The KRB_PRIV Exchange + + The KRB_PRIV message may be used by clients requiring confidentiality + and the ability to detect modifications of exchanged messages. It + achieves this by encrypting the messages and adding control + information. + +3.5.1. Generation of a KRB_PRIV message + + When an application wishes to send a KRB_PRIV message, it collects + its data and the appropriate control information (specified in + section 5.7.1) and encrypts them under an encryption key (usually the + last key negotiated via subkeys, or the session key if no negotiation + has occured). As part of the control information, the client must + choose to use either a timestamp or a sequence number (or both); see + the discussion in section 3.4.1 for guidelines on which to use. + After the user data and control information are encrypted, the client + transmits the ciphertext and some "envelope" information to the + recipient. + +3.5.2. Receipt of KRB_PRIV message + + When an application receives a KRB_PRIV message, it verifies it as + follows. If any error occurs, an error code is reported for use by + the application. + + The message is first checked by verifying that the protocol version + and type fields match the current version and KRB_PRIV, respectively. + A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE + error. The application then decrypts the ciphertext and processes + the resultant plaintext. If decryption shows the data to have been + modified, a KRB_AP_ERR_BAD_INTEGRITY error is generated. The + recipient verifies that the operating system's report of the sender's + address matches the sender's address in the message, and (if a + recipient address is specified or the recipient requires an address) + that one of the recipient's addresses appears as the recipient's + address in the message. A failed match for either case generates a + KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the + sequence number fields are checked. If timestamp and usec are + expected and not present, or they are present but not current, the + KRB_AP_ERR_SKEW error is generated. If the server name, along with + + + +Kohl & Neuman [Page 33] + +RFC 1510 Kerberos September 1993 + + + the client name, time and microsecond fields from the Authenticator + match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is + generated. If an incorrect sequence number is included, or a + sequence number is expected but not present, the KRB_AP_ERR_BADORDER + error is generated. If neither a timestamp and usec or a sequence + number is present, a KRB_AP_ERR_MODIFIED error is generated. + + If all the checks succeed, the application can assume the message was + generated by its peer, and was securely transmitted (without + intruders able to see the unencrypted contents). + +3.6. The KRB_CRED Exchange + + The KRB_CRED message may be used by clients requiring the ability to + send Kerberos credentials from one host to another. It achieves this + by sending the tickets together with encrypted data containing the + session keys and other information associated with the tickets. + +3.6.1. Generation of a KRB_CRED message + + When an application wishes to send a KRB_CRED message it first (using + the KRB_TGS exchange) obtains credentials to be sent to the remote + host. It then constructs a KRB_CRED message using the ticket or + tickets so obtained, placing the session key needed to use each + ticket in the key field of the corresponding KrbCredInfo sequence of + the encrypted part of the the KRB_CRED message. + + Other information associated with each ticket and obtained during the + KRB_TGS exchange is also placed in the corresponding KrbCredInfo + sequence in the encrypted part of the KRB_CRED message. The current + time and, if specifically required by the application the nonce, s- + address, and raddress fields, are placed in the encrypted part of the + KRB_CRED message which is then encrypted under an encryption key + previosuly exchanged in the KRB_AP exchange (usually the last key + negotiated via subkeys, or the session key if no negotiation has + occured). + +3.6.2. Receipt of KRB_CRED message + + When an application receives a KRB_CRED message, it verifies it. If + any error occurs, an error code is reported for use by the + application. The message is verified by checking that the protocol + version and type fields match the current version and KRB_CRED, + respectively. A mismatch generates a KRB_AP_ERR_BADVERSION or + KRB_AP_ERR_MSG_TYPE error. The application then decrypts the + ciphertext and processes the resultant plaintext. If decryption shows + the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is + generated. + + + +Kohl & Neuman [Page 34] + +RFC 1510 Kerberos September 1993 + + + If present or required, the recipient verifies that the operating + system's report of the sender's address matches the sender's address + in the message, and that one of the recipient's addresses appears as + the recipient's address in the message. A failed match for either + case generates a KRB_AP_ERR_BADADDR error. The timestamp and usec + fields (and the nonce field if required) are checked next. If the + timestamp and usec are not present, or they are present but not + current, the KRB_AP_ERR_SKEW error is generated. + + If all the checks succeed, the application stores each of the new + tickets in its ticket cache together with the session key and other + information in the corresponding KrbCredInfo sequence from the + encrypted part of the KRB_CRED message. + +4. The Kerberos Database + + The Kerberos server must have access to a database containing the + principal identifiers and secret keys of principals to be + authenticated (The implementation of the Kerberos server need not + combine the database and the server on the same machine; it is + feasible to store the principal database in, say, a network name + service, as long as the entries stored therein are protected from + disclosure to and modification by unauthorized parties. However, we + recommend against such strategies, as they can make system management + and threat analysis quite complex.). + +4.1. Database contents + + A database entry should contain at least the following fields: + + Field Value + + name Principal's identifier + key Principal's secret key + p_kvno Principal's key version + max_life Maximum lifetime for Tickets + max_renewable_life Maximum total lifetime for renewable + Tickets + + The name field is an encoding of the principal's identifier. The key + field contains an encryption key. This key is the principal's secret + key. (The key can be encrypted before storage under a Kerberos + "master key" to protect it in case the database is compromised but + the master key is not. In that case, an extra field must be added to + indicate the master key version used, see below.) The p_kvno field is + the key version number of the principal's secret key. The max_life + field contains the maximum allowable lifetime (endtime - starttime) + for any Ticket issued for this principal. The max_renewable_life + + + +Kohl & Neuman [Page 35] + +RFC 1510 Kerberos September 1993 + + + field contains the maximum allowable total lifetime for any renewable + Ticket issued for this principal. (See section 3.1 for a description + of how these lifetimes are used in determining the lifetime of a + given Ticket.) + + A server may provide KDC service to several realms, as long as the + database representation provides a mechanism to distinguish between + principal records with identifiers which differ only in the realm + name. + + When an application server's key changes, if the change is routine + (i.e., not the result of disclosure of the old key), the old key + should be retained by the server until all tickets that had been + issued using that key have expired. Because of this, it is possible + for several keys to be active for a single principal. Ciphertext + encrypted in a principal's key is always tagged with the version of + the key that was used for encryption, to help the recipient find the + proper key for decryption. + + When more than one key is active for a particular principal, the + principal will have more than one record in the Kerberos database. + The keys and key version numbers will differ between the records (the + rest of the fields may or may not be the same). Whenever Kerberos + issues a ticket, or responds to a request for initial authentication, + the most recent key (known by the Kerberos server) will be used for + encryption. This is the key with the highest key version number. + +4.2. Additional fields + + Project Athena's KDC implementation uses additional fields in its + database: + + Field Value + + K_kvno Kerberos' key version + expiration Expiration date for entry + attributes Bit field of attributes + mod_date Timestamp of last modification + mod_name Modifying principal's identifier + + The K_kvno field indicates the key version of the Kerberos master key + under which the principal's secret key is encrypted. + + After an entry's expiration date has passed, the KDC will return an + error to any client attempting to gain tickets as or for the + principal. (A database may want to maintain two expiration dates: + one for the principal, and one for the principal's current key. This + allows password aging to work independently of the principal's + + + +Kohl & Neuman [Page 36] + +RFC 1510 Kerberos September 1993 + + + expiration date. However, due to the limited space in the responses, + the KDC must combine the key expiration and principal expiration date + into a single value called "key_exp", which is used as a hint to the + user to take administrative action.) + + The attributes field is a bitfield used to govern the operations + involving the principal. This field might be useful in conjunction + with user registration procedures, for site-specific policy + implementations (Project Athena currently uses it for their user + registration process controlled by the system-wide database service, + Moira [7]), or to identify the "string to key" conversion algorithm + used for a principal's key. (See the discussion of the padata field + in section 5.4.2 for details on why this can be useful.) Other bits + are used to indicate that certain ticket options should not be + allowed in tickets encrypted under a principal's key (one bit each): + Disallow issuing postdated tickets, disallow issuing forwardable + tickets, disallow issuing tickets based on TGT authentication, + disallow issuing renewable tickets, disallow issuing proxiable + tickets, and disallow issuing tickets for which the principal is the + server. + + The mod_date field contains the time of last modification of the + entry, and the mod_name field contains the name of the principal + which last modified the entry. + +4.3. Frequently Changing Fields + + Some KDC implementations may wish to maintain the last time that a + request was made by a particular principal. Information that might + be maintained includes the time of the last request, the time of the + last request for a ticket-granting ticket, the time of the last use + of a ticket-granting ticket, or other times. This information can + then be returned to the user in the last-req field (see section 5.2). + + Other frequently changing information that can be maintained is the + latest expiration time for any tickets that have been issued using + each key. This field would be used to indicate how long old keys + must remain valid to allow the continued use of outstanding tickets. + +4.4. Site Constants + + The KDC implementation should have the following configurable + constants or options, to allow an administrator to make and enforce + policy decisions: + + + The minimum supported lifetime (used to determine whether the + KDC_ERR_NEVER_VALID error should be returned). This constant + should reflect reasonable expectations of round-trip time to the + + + +Kohl & Neuman [Page 37] + +RFC 1510 Kerberos September 1993 + + + KDC, encryption/decryption time, and processing time by the client + and target server, and it should allow for a minimum "useful" + lifetime. + + + The maximum allowable total (renewable) lifetime of a ticket + (renew_till - starttime). + + + The maximum allowable lifetime of a ticket (endtime - starttime). + + + Whether to allow the issue of tickets with empty address fields + (including the ability to specify that such tickets may only be + issued if the request specifies some authorization_data). + + + Whether proxiable, forwardable, renewable or post-datable tickets + are to be issued. + +5. Message Specifications + + The following sections describe the exact contents and encoding of + protocol messages and objects. The ASN.1 base definitions are + presented in the first subsection. The remaining subsections specify + the protocol objects (tickets and authenticators) and messages. + Specification of encryption and checksum techniques, and the fields + related to them, appear in section 6. + +5.1. ASN.1 Distinguished Encoding Representation + + All uses of ASN.1 in Kerberos shall use the Distinguished Encoding + Representation of the data elements as described in the X.509 + specification, section 8.7 [8]. + +5.2. ASN.1 Base Definitions + + The following ASN.1 base definitions are used in the rest of this + section. Note that since the underscore character (_) is not + permitted in ASN.1 names, the hyphen (-) is used in its place for the + purposes of ASN.1 names. + + Realm ::= GeneralString + PrincipalName ::= SEQUENCE { + name-type[0] INTEGER, + name-string[1] SEQUENCE OF GeneralString + } + + Kerberos realms are encoded as GeneralStrings. Realms shall not + contain a character with the code 0 (the ASCII NUL). Most realms + will usually consist of several components separated by periods (.), + in the style of Internet Domain Names, or separated by slashes (/) in + + + +Kohl & Neuman [Page 38] + +RFC 1510 Kerberos September 1993 + + + the style of X.500 names. Acceptable forms for realm names are + specified in section 7. A PrincipalName is a typed sequence of + components consisting of the following sub-fields: + + name-type This field specifies the type of name that follows. + Pre-defined values for this field are + specified in section 7.2. The name-type should be + treated as a hint. Ignoring the name type, no two + names can be the same (i.e., at least one of the + components, or the realm, must be different). + This constraint may be eliminated in the future. + + name-string This field encodes a sequence of components that + form a name, each component encoded as a General + String. Taken together, a PrincipalName and a Realm + form a principal identifier. Most PrincipalNames + will have only a few components (typically one or two). + + KerberosTime ::= GeneralizedTime + -- Specifying UTC time zone (Z) + + The timestamps used in Kerberos are encoded as GeneralizedTimes. An + encoding shall specify the UTC time zone (Z) and shall not include + any fractional portions of the seconds. It further shall not include + any separators. Example: The only valid format for UTC time 6 + minutes, 27 seconds after 9 pm on 6 November 1985 is 19851106210627Z. + + HostAddress ::= SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING + } + + HostAddresses ::= SEQUENCE OF SEQUENCE { + addr-type[0] INTEGER, + address[1] OCTET STRING + } + + + The host adddress encodings consists of two fields: + + addr-type This field specifies the type of address that + follows. Pre-defined values for this field are + specified in section 8.1. + + + address This field encodes a single address of type addr-type. + + The two forms differ slightly. HostAddress contains exactly one + + + +Kohl & Neuman [Page 39] + +RFC 1510 Kerberos September 1993 + + + address; HostAddresses contains a sequence of possibly many + addresses. + + AuthorizationData ::= SEQUENCE OF SEQUENCE { + ad-type[0] INTEGER, + ad-data[1] OCTET STRING + } + + + ad-data This field contains authorization data to be + interpreted according to the value of the + corresponding ad-type field. + + ad-type This field specifies the format for the ad-data + subfield. All negative values are reserved for + local use. Non-negative values are reserved for + registered use. + + APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) + } + + + TicketFlags ::= BIT STRING { + reserved(0), + forwardable(1), + forwarded(2), + proxiable(3), + proxy(4), + may-postdate(5), + postdated(6), + invalid(7), + renewable(8), + initial(9), + pre-authent(10), + hw-authent(11) + } + + KDCOptions ::= BIT STRING { + reserved(0), + forwardable(1), + forwarded(2), + proxiable(3), + proxy(4), + allow-postdate(5), + postdated(6), + + + +Kohl & Neuman [Page 40] + +RFC 1510 Kerberos September 1993 + + + unused7(7), + renewable(8), + unused9(9), + unused10(10), + unused11(11), + renewable-ok(27), + enc-tkt-in-skey(28), + renew(30), + validate(31) + } + + + LastReq ::= SEQUENCE OF SEQUENCE { + lr-type[0] INTEGER, + lr-value[1] KerberosTime + } + + lr-type This field indicates how the following lr-value + field is to be interpreted. Negative values indicate + that the information pertains only to the + responding server. Non-negative values pertain to + all servers for the realm. + + If the lr-type field is zero (0), then no information + is conveyed by the lr-value subfield. If the + absolute value of the lr-type field is one (1), + then the lr-value subfield is the time of last + initial request for a TGT. If it is two (2), then + the lr-value subfield is the time of last initial + request. If it is three (3), then the lr-value + subfield is the time of issue for the newest + ticket-granting ticket used. If it is four (4), + then the lr-value subfield is the time of the last + renewal. If it is five (5), then the lr-value + subfield is the time of last request (of any + type). + + lr-value This field contains the time of the last request. + The time must be interpreted according to the contents + of the accompanying lr-type subfield. + + See section 6 for the definitions of Checksum, ChecksumType, + EncryptedData, EncryptionKey, EncryptionType, and KeyType. + + + + + + + + +Kohl & Neuman [Page 41] + +RFC 1510 Kerberos September 1993 + + +5.3. Tickets and Authenticators + + This section describes the format and encryption parameters for + tickets and authenticators. When a ticket or authenticator is + included in a protocol message it is treated as an opaque object. + +5.3.1. Tickets + + A ticket is a record that helps a client authenticate to a service. + A Ticket contains the following information: + +Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno[0] INTEGER, + realm[1] Realm, + sname[2] PrincipalName, + enc-part[3] EncryptedData +} +-- Encrypted part of ticket +EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL +} +-- encoded Transited field +TransitedEncoding ::= SEQUENCE { + tr-type[0] INTEGER, -- must be registered + contents[1] OCTET STRING +} + + The encoding of EncTicketPart is encrypted in the key shared by + Kerberos and the end server (the server's secret key). See section 6 + for the format of the ciphertext. + + tkt-vno This field specifies the version number for the ticket + format. This document describes version number 5. + + realm This field specifies the realm that issued a ticket. It + also serves to identify the realm part of the server's + principal identifier. Since a Kerberos server can only + issue tickets for servers within its realm, the two will + + + +Kohl & Neuman [Page 42] + +RFC 1510 Kerberos September 1993 + + + always be identical. + + sname This field specifies the name part of the server's + identity. + + enc-part This field holds the encrypted encoding of the + EncTicketPart sequence. + + flags This field indicates which of various options were used or + requested when the ticket was issued. It is a bit-field, + where the selected options are indicated by the bit being + set (1), and the unselected options and reserved fields + being reset (0). Bit 0 is the most significant bit. The + encoding of the bits is specified in section 5.2. The + flags are described in more detail above in section 2. The + meanings of the flags are: + + Bit(s) Name Description + + 0 RESERVED Reserved for future expansion of this + field. + + 1 FORWARDABLE The FORWARDABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. When set, + this flag tells the ticket-granting + server that it is OK to issue a new + ticket- granting ticket with a + different network address based on + the presented ticket. + + 2 FORWARDED When set, this flag indicates that + the ticket has either been forwarded + or was issued based on authentication + involving a forwarded ticket-granting + ticket. + + 3 PROXIABLE The PROXIABLE flag is normally only + interpreted by the TGS, and can be + ignored by end servers. The PROXIABLE + flag has an interpretation identical + to that of the FORWARDABLE flag, + except that the PROXIABLE flag tells + the ticket-granting server that only + non- ticket-granting tickets may be + issued with different network + addresses. + + + + +Kohl & Neuman [Page 43] + +RFC 1510 Kerberos September 1993 + + + 4 PROXY When set, this flag indicates that a + ticket is a proxy. + + 5 MAY-POSTDATE The MAY-POSTDATE flag is normally + only interpreted by the TGS, and can + be ignored by end servers. This flag + tells the ticket-granting server that + a post- dated ticket may be issued + based on this ticket-granting ticket. + + 6 POSTDATED This flag indicates that this ticket + has been postdated. The end-service + can check the authtime field to see + when the original authentication + occurred. + + 7 INVALID This flag indicates that a ticket is + invalid, and it must be validated by + the KDC before use. Application + servers must reject tickets which + have this flag set. + + 8 RENEWABLE The RENEWABLE flag is normally only + interpreted by the TGS, and can + usually be ignored by end servers + (some particularly careful servers + may wish to disallow renewable + tickets). A renewable ticket can be + used to obtain a replacement ticket + that expires at a later date. + + 9 INITIAL This flag indicates that this ticket + was issued using the AS protocol, and + not issued based on a ticket-granting + ticket. + + 10 PRE-AUTHENT This flag indicates that during + initial authentication, the client + was authenticated by the KDC before a + ticket was issued. The strength of + the preauthentication method is not + indicated, but is acceptable to the + KDC. + + 11 HW-AUTHENT This flag indicates that the protocol + employed for initial authentication + required the use of hardware expected + to be possessed solely by the named + + + +Kohl & Neuman [Page 44] + +RFC 1510 Kerberos September 1993 + + + client. The hardware authentication + method is selected by the KDC and the + strength of the method is not + indicated. + + 12-31 RESERVED Reserved for future use. + + key This field exists in the ticket and the KDC response and is + used to pass the session key from Kerberos to the + application server and the client. The field's encoding is + described in section 6.2. + + crealm This field contains the name of the realm in which the + client is registered and in which initial authentication + took place. + + cname This field contains the name part of the client's principal + identifier. + + transited This field lists the names of the Kerberos realms that took + part in authenticating the user to whom this ticket was + issued. It does not specify the order in which the realms + were transited. See section 3.3.3.1 for details on how + this field encodes the traversed realms. + + authtime This field indicates the time of initial authentication for + the named principal. It is the time of issue for the + original ticket on which this ticket is based. It is + included in the ticket to provide additional information to + the end service, and to provide the necessary information + for implementation of a `hot list' service at the KDC. An + end service that is particularly paranoid could refuse to + accept tickets for which the initial authentication + occurred "too far" in the past. + + This field is also returned as part of the response from + the KDC. When returned as part of the response to initial + authentication (KRB_AS_REP), this is the current time on + the Kerberos server (It is NOT recommended that this time + value be used to adjust the workstation's clock since the + workstation cannot reliably determine that such a + KRB_AS_REP actually came from the proper KDC in a timely + manner.). + + starttime This field in the ticket specifies the time after which the + ticket is valid. Together with endtime, this field + specifies the life of the ticket. If it is absent from + the ticket, its value should be treated as that of the + + + +Kohl & Neuman [Page 45] + +RFC 1510 Kerberos September 1993 + + + authtime field. + + endtime This field contains the time after which the ticket will + not be honored (its expiration time). Note that individual + services may place their own limits on the life of a ticket + and may reject tickets which have not yet expired. As + such, this is really an upper bound on the expiration time + for the ticket. + + renew-till This field is only present in tickets that have the + RENEWABLE flag set in the flags field. It indicates the + maximum endtime that may be included in a renewal. It can + be thought of as the absolute expiration time for the + ticket, including all renewals. + + caddr This field in a ticket contains zero (if omitted) or more + (if present) host addresses. These are the addresses from + which the ticket can be used. If there are no addresses, + the ticket can be used from any location. The decision + by the KDC to issue or by the end server to accept zero- + address tickets is a policy decision and is left to the + Kerberos and end-service administrators; they may refuse to + issue or accept such tickets. The suggested and default + policy, however, is that such tickets will only be issued + or accepted when additional information that can be used to + restrict the use of the ticket is included in the + authorization_data field. Such a ticket is a capability. + + Network addresses are included in the ticket to make it + harder for an attacker to use stolen credentials. Because + the session key is not sent over the network in cleartext, + credentials can't be stolen simply by listening to the + network; an attacker has to gain access to the session key + (perhaps through operating system security breaches or a + careless user's unattended session) to make use of stolen + tickets. + + It is important to note that the network address from which + a connection is received cannot be reliably determined. + Even if it could be, an attacker who has compromised the + client's workstation could use the credentials from there. + Including the network addresses only makes it more + difficult, not impossible, for an attacker to walk off with + stolen credentials and then use them from a "safe" + location. + + + + + + +Kohl & Neuman [Page 46] + +RFC 1510 Kerberos September 1993 + + + authorization-data The authorization-data field is used to pass + authorization data from the principal on whose behalf a + ticket was issued to the application service. If no + authorization data is included, this field will be left + out. The data in this field are specific to the end + service. It is expected that the field will contain the + names of service specific objects, and the rights to those + objects. The format for this field is described in section + 5.2. Although Kerberos is not concerned with the format of + the contents of the subfields, it does carry type + information (ad-type). + + By using the authorization_data field, a principal is able + to issue a proxy that is valid for a specific purpose. For + example, a client wishing to print a file can obtain a file + server proxy to be passed to the print server. By + specifying the name of the file in the authorization_data + field, the file server knows that the print server can only + use the client's rights when accessing the particular file + to be printed. + + It is interesting to note that if one specifies the + authorization-data field of a proxy and leaves the host + addresses blank, the resulting ticket and session key can + be treated as a capability. See [9] for some suggested + uses of this field. + + The authorization-data field is optional and does not have + to be included in a ticket. + +5.3.2. Authenticators + + An authenticator is a record sent with a ticket to a server to + certify the client's knowledge of the encryption key in the ticket, + to help the server detect replays, and to help choose a "true session + key" to use with the particular session. The encoding is encrypted + in the ticket's session key shared by the client and the server: + +-- Unencrypted authenticator +Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + + + +Kohl & Neuman [Page 47] + +RFC 1510 Kerberos September 1993 + + + authorization-data[8] AuthorizationData OPTIONAL + } + + authenticator-vno This field specifies the version number for the + format of the authenticator. This document specifies + version 5. + + crealm and cname These fields are the same as those described for the + ticket in section 5.3.1. + + cksum This field contains a checksum of the the application data + that accompanies the KRB_AP_REQ. + + cusec This field contains the microsecond part of the client's + timestamp. Its value (before encryption) ranges from 0 to + 999999. It often appears along with ctime. The two fields + are used together to specify a reasonably accurate + timestamp. + + ctime This field contains the current time on the client's host. + + subkey This field contains the client's choice for an encryption + key which is to be used to protect this specific + application session. Unless an application specifies + otherwise, if this field is left out the session key from + the ticket will be used. + + seq-number This optional field includes the initial sequence number + to be used by the KRB_PRIV or KRB_SAFE messages when + sequence numbers are used to detect replays (It may also be + used by application specific messages). When included in + the authenticator this field specifies the initial sequence + number for messages from the client to the server. When + included in the AP-REP message, the initial sequence number + is that for messages from the server to the client. When + used in KRB_PRIV or KRB_SAFE messages, it is incremented by + one after each message is sent. + + For sequence numbers to adequately support the detection of + replays they should be non-repeating, even across + connection boundaries. The initial sequence number should + be random and uniformly distributed across the full space + of possible sequence numbers, so that it cannot be guessed + by an attacker and so that it and the successive sequence + numbers do not repeat other sequences. + + + + + + +Kohl & Neuman [Page 48] + +RFC 1510 Kerberos September 1993 + + + authorization-data This field is the same as described for the ticket + in section 5.3.1. It is optional and will only appear when + additional restrictions are to be placed on the use of a + ticket, beyond those carried in the ticket itself. + +5.4. Specifications for the AS and TGS exchanges + + This section specifies the format of the messages used in exchange + between the client and the Kerberos server. The format of possible + error messages appears in section 5.9.1. + +5.4.1. KRB_KDC_REQ definition + + The KRB_KDC_REQ message has no type of its own. Instead, its type is + one of KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is + for an initial ticket or an additional ticket. In either case, the + message is sent from the client to the Authentication Server to + request credentials for a service. + +The message fields are: + +AS-REQ ::= [APPLICATION 10] KDC-REQ +TGS-REQ ::= [APPLICATION 12] KDC-REQ + +KDC-REQ ::= SEQUENCE { + pvno[1] INTEGER, + msg-type[2] INTEGER, + padata[3] SEQUENCE OF PA-DATA OPTIONAL, + req-body[4] KDC-REQ-BODY +} + +PA-DATA ::= SEQUENCE { + padata-type[1] INTEGER, + padata-value[2] OCTET STRING, + -- might be encoded AP-REQ +} + +KDC-REQ-BODY ::= SEQUENCE { + kdc-options[0] KDCOptions, + cname[1] PrincipalName OPTIONAL, + -- Used only in AS-REQ + realm[2] Realm, -- Server's realm + -- Also client's in AS-REQ + sname[3] PrincipalName OPTIONAL, + from[4] KerberosTime OPTIONAL, + till[5] KerberosTime, + rtime[6] KerberosTime OPTIONAL, + nonce[7] INTEGER, + + + +Kohl & Neuman [Page 49] + +RFC 1510 Kerberos September 1993 + + + etype[8] SEQUENCE OF INTEGER, -- EncryptionType, + -- in preference order + addresses[9] HostAddresses OPTIONAL, + enc-authorization-data[10] EncryptedData OPTIONAL, + -- Encrypted AuthorizationData encoding + additional-tickets[11] SEQUENCE OF Ticket OPTIONAL +} + + The fields in this message are: + + pvno This field is included in each message, and specifies the + protocol version number. This document specifies protocol + version 5. + + msg-type This field indicates the type of a protocol message. It + will almost always be the same as the application + identifier associated with a message. It is included to + make the identifier more readily accessible to the + application. For the KDC-REQ message, this type will be + KRB_AS_REQ or KRB_TGS_REQ. + + padata The padata (pre-authentication data) field contains a of + authentication information which may be needed before + credentials can be issued or decrypted. In the case of + requests for additional tickets (KRB_TGS_REQ), this field + will include an element with padata-type of PA-TGS-REQ and + data of an authentication header (ticket-granting ticket + and authenticator). The checksum in the authenticator + (which must be collisionproof) is to be computed over the + KDC-REQ-BODY encoding. In most requests for initial + authentication (KRB_AS_REQ) and most replies (KDC-REP), the + padata field will be left out. + + This field may also contain information needed by certain + extensions to the Kerberos protocol. For example, it might + be used to initially verify the identity of a client before + any response is returned. This is accomplished with a + padata field with padata-type equal to PA-ENC-TIMESTAMP and + padata-value defined as follows: + + padata-type ::= PA-ENC-TIMESTAMP + padata-value ::= EncryptedData -- PA-ENC-TS-ENC + + PA-ENC-TS-ENC ::= SEQUENCE { + patimestamp[0] KerberosTime, -- client's time + pausec[1] INTEGER OPTIONAL + } + + + + +Kohl & Neuman [Page 50] + +RFC 1510 Kerberos September 1993 + + + with patimestamp containing the client's time and pausec + containing the microseconds which may be omitted if a + client will not generate more than one request per second. + The ciphertext (padata-value) consists of the PA-ENC-TS-ENC + sequence, encrypted using the client's secret key. + + The padata field can also contain information needed to + help the KDC or the client select the key needed for + generating or decrypting the response. This form of the + padata is useful for supporting the use of certain + "smartcards" with Kerberos. The details of such extensions + are beyond the scope of this specification. See [10] for + additional uses of this field. + + padata-type The padata-type element of the padata field indicates the + way that the padata-value element is to be interpreted. + Negative values of padata-type are reserved for + unregistered use; non-negative values are used for a + registered interpretation of the element type. + + req-body This field is a placeholder delimiting the extent of the + remaining fields. If a checksum is to be calculated over + the request, it is calculated over an encoding of the KDC- + REQ-BODY sequence which is enclosed within the req-body + field. + + kdc-options This field appears in the KRB_AS_REQ and KRB_TGS_REQ + requests to the KDC and indicates the flags that the client + wants set on the tickets as well as other information that + is to modify the behavior of the KDC. Where appropriate, + the name of an option may be the same as the flag that is + set by that option. Although in most case, the bit in the + options field will be the same as that in the flags field, + this is not guaranteed, so it is not acceptable to simply + copy the options field to the flags field. There are + various checks that must be made before honoring an option + anyway. + + The kdc_options field is a bit-field, where the selected + options are indicated by the bit being set (1), and the + unselected options and reserved fields being reset (0). + The encoding of the bits is specified in section 5.2. The + options are described in more detail above in section 2. + The meanings of the options are: + + + + + + + +Kohl & Neuman [Page 51] + +RFC 1510 Kerberos September 1993 + + + Bit(s) Name Description + + 0 RESERVED Reserved for future expansion of this + field. + + 1 FORWARDABLE The FORWARDABLE option indicates that + the ticket to be issued is to have its + forwardable flag set. It may only be + set on the initial request, or in a + subsequent request if the ticket- + granting ticket on which it is based + is also forwardable. + + 2 FORWARDED The FORWARDED option is only specified + in a request to the ticket-granting + server and will only be honored if the + ticket-granting ticket in the request + has its FORWARDABLE bit set. This + option indicates that this is a + request for forwarding. The + address(es) of the host from which the + resulting ticket is to be valid are + included in the addresses field of the + request. + + + 3 PROXIABLE The PROXIABLE option indicates that + the ticket to be issued is to have its + proxiable flag set. It may only be set + on the initial request, or in a + subsequent request if the ticket- + granting ticket on which it is based + is also proxiable. + + 4 PROXY The PROXY option indicates that this + is a request for a proxy. This option + will only be honored if the ticket- + granting ticket in the request has its + PROXIABLE bit set. The address(es) of + the host from which the resulting + ticket is to be valid are included in + the addresses field of the request. + + 5 ALLOW-POSTDATE The ALLOW-POSTDATE option indicates + that the ticket to be issued is to + have its MAY-POSTDATE flag set. It + may only be set on the initial + request, or in a subsequent request if + + + +Kohl & Neuman [Page 52] + +RFC 1510 Kerberos September 1993 + + + the ticket-granting ticket on which it + is based also has its MAY-POSTDATE + flag set. + + 6 POSTDATED The POSTDATED option indicates that + this is a request for a postdated + ticket. This option will only be + honored if the ticket-granting ticket + on which it is based has its MAY- + POSTDATE flag set. The resulting + ticket will also have its INVALID flag + set, and that flag may be reset by a + subsequent request to the KDC after + the starttime in the ticket has been + reached. + + 7 UNUSED This option is presently unused. + + 8 RENEWABLE The RENEWABLE option indicates that + the ticket to be issued is to have its + RENEWABLE flag set. It may only be + set on the initial request, or when + the ticket-granting ticket on which + the request is based is also + renewable. If this option is + requested, then the rtime field in the + request contains the desired absolute + expiration time for the ticket. + + 9-26 RESERVED Reserved for future use. + + 27 RENEWABLE-OK The RENEWABLE-OK option indicates that + a renewable ticket will be acceptable + if a ticket with the requested life + cannot otherwise be provided. If a + ticket with the requested life cannot + be provided, then a renewable ticket + may be issued with a renew-till equal + to the the requested endtime. The + value of the renew-till field may + still be limited by local limits, or + limits selected by the individual + principal or server. + + 28 ENC-TKT-IN-SKEY This option is used only by the + ticket-granting service. The ENC- + TKT-IN-SKEY option indicates that the + ticket for the end server is to be + + + +Kohl & Neuman [Page 53] + +RFC 1510 Kerberos September 1993 + + + encrypted in the session key from the + additional ticket-granting ticket + provided. + + 29 RESERVED Reserved for future use. + + 30 RENEW This option is used only by the + ticket-granting service. The RENEW + option indicates that the present + request is for a renewal. The ticket + provided is encrypted in the secret + key for the server on which it is + valid. This option will only be + honored if the ticket to be renewed + has its RENEWABLE flag set and if the + time in its renew till field has not + passed. The ticket to be renewed is + passed in the padata field as part of + the authentication header. + + 31 VALIDATE This option is used only by the + ticket-granting service. The VALIDATE + option indicates that the request is + to validate a postdated ticket. It + will only be honored if the ticket + presented is postdated, presently has + its INVALID flag set, and would be + otherwise usable at this time. A + ticket cannot be validated before its + starttime. The ticket presented for + validation is encrypted in the key of + the server for which it is valid and + is passed in the padata field as part + of the authentication header. + + cname and sname These fields are the same as those described for the + ticket in section 5.3.1. sname may only be absent when the + ENC-TKT-IN-SKEY option is specified. If absent, the name + of the server is taken from the name of the client in the + ticket passed as additional-tickets. + + enc-authorization-data The enc-authorization-data, if present (and it + can only be present in the TGS_REQ form), is an encoding of + the desired authorization-data encrypted under the sub- + session key if present in the Authenticator, or + alternatively from the session key in the ticket-granting + ticket, both from the padata field in the KRB_AP_REQ. + + + + +Kohl & Neuman [Page 54] + +RFC 1510 Kerberos September 1993 + + + realm This field specifies the realm part of the server's + principal identifier. In the AS exchange, this is also the + realm part of the client's principal identifier. + + from This field is included in the KRB_AS_REQ and KRB_TGS_REQ + ticket requests when the requested ticket is to be + postdated. It specifies the desired start time for the + requested ticket. + + till This field contains the expiration date requested by the + client in a ticket request. + + rtime This field is the requested renew-till time sent from a + client to the KDC in a ticket request. It is optional. + + nonce This field is part of the KDC request and response. It it + intended to hold a random number generated by the client. + If the same number is included in the encrypted response + from the KDC, it provides evidence that the response is + fresh and has not been replayed by an attacker. Nonces + must never be re-used. Ideally, it should be gen erated + randomly, but if the correct time is known, it may suffice + (Note, however, that if the time is used as the nonce, one + must make sure that the workstation time is monotonically + increasing. If the time is ever reset backwards, there is + a small, but finite, probability that a nonce will be + reused.). + + etype This field specifies the desired encryption algorithm to be + used in the response. + + addresses This field is included in the initial request for tickets, + and optionally included in requests for additional tickets + from the ticket-granting server. It specifies the + addresses from which the requested ticket is to be valid. + Normally it includes the addresses for the client's host. + If a proxy is requested, this field will contain other + addresses. The contents of this field are usually copied + by the KDC into the caddr field of the resulting ticket. + + additional-tickets Additional tickets may be optionally included in a + request to the ticket-granting server. If the ENC-TKT-IN- + SKEY option has been specified, then the session key from + the additional ticket will be used in place of the server's + key to encrypt the new ticket. If more than one option + which requires additional tickets has been specified, then + the additional tickets are used in the order specified by + the ordering of the options bits (see kdc-options, above). + + + +Kohl & Neuman [Page 55] + +RFC 1510 Kerberos September 1993 + + + The application code will be either ten (10) or twelve (12) depending + on whether the request is for an initial ticket (AS-REQ) or for an + additional ticket (TGS-REQ). + + The optional fields (addresses, authorization-data and additional- + tickets) are only included if necessary to perform the operation + specified in the kdc-options field. + + It should be noted that in KRB_TGS_REQ, the protocol version number + appears twice and two different message types appear: the KRB_TGS_REQ + message contains these fields as does the authentication header + (KRB_AP_REQ) that is passed in the padata field. + +5.4.2. KRB_KDC_REP definition + + The KRB_KDC_REP message format is used for the reply from the KDC for + either an initial (AS) request or a subsequent (TGS) request. There + is no message type for KRB_KDC_REP. Instead, the type will be either + KRB_AS_REP or KRB_TGS_REP. The key used to encrypt the ciphertext + part of the reply depends on the message type. For KRB_AS_REP, the + ciphertext is encrypted in the client's secret key, and the client's + key version number is included in the key version number for the + encrypted data. For KRB_TGS_REP, the ciphertext is encrypted in the + sub-session key from the Authenticator, or if absent, the session key + from the ticket-granting ticket used in the request. In that case, + no version number will be present in the EncryptedData sequence. + + The KRB_KDC_REP message contains the following fields: + + AS-REP ::= [APPLICATION 11] KDC-REP + TGS-REP ::= [APPLICATION 13] KDC-REP + + KDC-REP ::= SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + padata[2] SEQUENCE OF PA-DATA OPTIONAL, + crealm[3] Realm, + cname[4] PrincipalName, + ticket[5] Ticket, + enc-part[6] EncryptedData + } + + EncASRepPart ::= [APPLICATION 25[25]] EncKDCRepPart + EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart + + EncKDCRepPart ::= SEQUENCE { + key[0] EncryptionKey, + last-req[1] LastReq, + + + +Kohl & Neuman [Page 56] + +RFC 1510 Kerberos September 1993 + + + nonce[2] INTEGER, + key-expiration[3] KerberosTime OPTIONAL, + flags[4] TicketFlags, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + srealm[9] Realm, + sname[10] PrincipalName, + caddr[11] HostAddresses OPTIONAL + } + + NOTE: In EncASRepPart, the application code in the encrypted + part of a message provides an additional check that + the message was decrypted properly. + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is either KRB_AS_REP or KRB_TGS_REP. + + padata This field is described in detail in section 5.4.1. One + possible use for this field is to encode an alternate + "mix-in" string to be used with a string-to-key algorithm + (such as is described in section 6.3.2). This ability is + useful to ease transitions if a realm name needs to change + (e.g., when a company is acquired); in such a case all + existing password-derived entries in the KDC database would + be flagged as needing a special mix-in string until the + next password change. + + crealm, cname, srealm and sname These fields are the same as those + described for the ticket in section 5.3.1. + + ticket The newly-issued ticket, from section 5.3.1. + + enc-part This field is a place holder for the ciphertext and related + information that forms the encrypted part of a message. + The description of the encrypted part of the message + follows each appearance of this field. The encrypted part + is encoded as described in section 6.1. + + key This field is the same as described for the ticket in + section 5.3.1. + + last-req This field is returned by the KDC and specifies the time(s) + of the last request by a principal. Depending on what + information is available, this might be the last time that + a request for a ticket-granting ticket was made, or the + last time that a request based on a ticket-granting ticket + + + +Kohl & Neuman [Page 57] + +RFC 1510 Kerberos September 1993 + + + was successful. It also might cover all servers for a + realm, or just the particular server. Some implementations + may display this information to the user to aid in + discovering unauthorized use of one's identity. It is + similar in spirit to the last login time displayed when + logging into timesharing systems. + + nonce This field is described above in section 5.4.1. + + key-expiration The key-expiration field is part of the response from + the KDC and specifies the time that the client's secret key + is due to expire. The expiration might be the result of + password aging or an account expiration. This field will + usually be left out of the TGS reply since the response to + the TGS request is encrypted in a session key and no client + information need be retrieved from the KDC database. It is + up to the application client (usually the login program) to + take appropriate action (such as notifying the user) if the + expira tion time is imminent. + + flags, authtime, starttime, endtime, renew-till and caddr These + fields are duplicates of those found in the encrypted + portion of the attached ticket (see section 5.3.1), + provided so the client may verify they match the intended + request and to assist in proper ticket caching. If the + message is of type KRB_TGS_REP, the caddr field will only + be filled in if the request was for a proxy or forwarded + ticket, or if the user is substituting a subset of the + addresses from the ticket granting ticket. If the client- + requested addresses are not present or not used, then the + addresses contained in the ticket will be the same as those + included in the ticket-granting ticket. + +5.5. Client/Server (CS) message specifications + + This section specifies the format of the messages used for the + authentication of the client to the application server. + +5.5.1. KRB_AP_REQ definition + + The KRB_AP_REQ message contains the Kerberos protocol version number, + the message type KRB_AP_REQ, an options field to indicate any options + in use, and the ticket and authenticator themselves. The KRB_AP_REQ + message is often referred to as the "authentication header". + + AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + + + +Kohl & Neuman [Page 58] + +RFC 1510 Kerberos September 1993 + + + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData + } + + APOptions ::= BIT STRING { + reserved(0), + use-session-key(1), + mutual-required(2) + } + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_AP_REQ. + + ap-options This field appears in the application request (KRB_AP_REQ) + and affects the way the request is processed. It is a + bit-field, where the selected options are indicated by the + bit being set (1), and the unselected options and reserved + fields being reset (0). The encoding of the bits is + specified in section 5.2. The meanings of the options are: + + Bit(s) Name Description + + 0 RESERVED Reserved for future expansion of + this field. + + 1 USE-SESSION-KEYThe USE-SESSION-KEY option indicates + that the ticket the client is + presenting to a server is encrypted in + the session key from the server's + ticket-granting ticket. When this + option is not specified, the ticket is + encrypted in the server's secret key. + + 2 MUTUAL-REQUIREDThe MUTUAL-REQUIRED option tells the + server that the client requires mutual + authentication, and that it must + respond with a KRB_AP_REP message. + + 3-31 RESERVED Reserved for future use. + + ticket This field is a ticket authenticating the client to the + server. + + authenticator This contains the authenticator, which includes the + client's choice of a subkey. Its encoding is described in + section 5.3.2. + + + + +Kohl & Neuman [Page 59] + +RFC 1510 Kerberos September 1993 + + +5.5.2. KRB_AP_REP definition + + The KRB_AP_REP message contains the Kerberos protocol version number, + the message type, and an encrypted timestamp. The message is sent in + in response to an application request (KRB_AP_REQ) where the mutual + authentication option has been selected in the ap-options field. + + AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[2] EncryptedData + } + + EncAPRepPart ::= [APPLICATION 27] SEQUENCE { + ctime[0] KerberosTime, + cusec[1] INTEGER, + subkey[2] EncryptionKey OPTIONAL, + seq-number[3] INTEGER OPTIONAL + } + + NOTE: in EncAPRepPart, the application code in the encrypted part of + a message provides an additional check that the message was decrypted + properly. + + The encoded EncAPRepPart is encrypted in the shared session key of + the ticket. The optional subkey field can be used in an + application-arranged negotiation to choose a per association session + key. + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_AP_REP. + + enc-part This field is described above in section 5.4.2. + + ctime This field contains the current time on the client's host. + + cusec This field contains the microsecond part of the client's + timestamp. + + subkey This field contains an encryption key which is to be used + to protect this specific application session. See section + 3.2.6 for specifics on how this field is used to negotiate + a key. Unless an application specifies otherwise, if this + field is left out, the sub-session key from the + authenticator, or if also left out, the session key from + the ticket will be used. + + + + + +Kohl & Neuman [Page 60] + +RFC 1510 Kerberos September 1993 + + +5.5.3. Error message reply + + If an error occurs while processing the application request, the + KRB_ERROR message will be sent in response. See section 5.9.1 for + the format of the error message. The cname and crealm fields may be + left out if the server cannot determine their appropriate values from + the corresponding KRB_AP_REQ message. If the authenticator was + decipherable, the ctime and cusec fields will contain the values from + it. + +5.6. KRB_SAFE message specification + + This section specifies the format of a message that can be used by + either side (client or server) of an application to send a tamper- + proof message to its peer. It presumes that a session key has + previously been exchanged (for example, by using the + KRB_AP_REQ/KRB_AP_REP messages). + +5.6.1. KRB_SAFE definition + + The KRB_SAFE message contains user data along with a collision-proof + checksum keyed with the session key. The message fields are: + + KRB-SAFE ::= [APPLICATION 20] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + safe-body[2] KRB-SAFE-BODY, + cksum[3] Checksum + } + + KRB-SAFE-BODY ::= SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress, + r-address[5] HostAddress OPTIONAL + } + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_SAFE. + + safe-body This field is a placeholder for the body of the KRB-SAFE + message. It is to be encoded separately and then have the + checksum computed over it, for use in the cksum field. + + cksum This field contains the checksum of the application data. + Checksum details are described in section 6.4. The + + + +Kohl & Neuman [Page 61] + +RFC 1510 Kerberos September 1993 + + + checksum is computed over the encoding of the KRB-SAFE-BODY + sequence. + + user-data This field is part of the KRB_SAFE and KRB_PRIV messages + and contain the application specific data that is being + passed from the sender to the recipient. + + timestamp This field is part of the KRB_SAFE and KRB_PRIV messages. + Its contents are the current time as known by the sender of + the message. By checking the timestamp, the recipient of + the message is able to make sure that it was recently + generated, and is not a replay. + + usec This field is part of the KRB_SAFE and KRB_PRIV headers. + It contains the microsecond part of the timestamp. + + seq-number This field is described above in section 5.3.2. + + s-address This field specifies the address in use by the sender of + the message. + + r-address This field specifies the address in use by the recipient of + the message. It may be omitted for some uses (such as + broadcast protocols), but the recipient may arbitrarily + reject such messages. This field along with s-address can + be used to help detect messages which have been incorrectly + or maliciously delivered to the wrong recipient. + +5.7. KRB_PRIV message specification + + This section specifies the format of a message that can be used by + either side (client or server) of an application to securely and + privately send a message to its peer. It presumes that a session key + has previously been exchanged (for example, by using the + KRB_AP_REQ/KRB_AP_REP messages). + +5.7.1. KRB_PRIV definition + + The KRB_PRIV message contains user data encrypted in the Session Key. + The message fields are: + + KRB-PRIV ::= [APPLICATION 21] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + enc-part[3] EncryptedData + } + + + + + +Kohl & Neuman [Page 62] + +RFC 1510 Kerberos September 1993 + + + EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE { + user-data[0] OCTET STRING, + timestamp[1] KerberosTime OPTIONAL, + usec[2] INTEGER OPTIONAL, + seq-number[3] INTEGER OPTIONAL, + s-address[4] HostAddress, -- sender's addr + r-address[5] HostAddress OPTIONAL + -- recip's addr + } + + NOTE: In EncKrbPrivPart, the application code in the encrypted part + of a message provides an additional check that the message was + decrypted properly. + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_PRIV. + + enc-part This field holds an encoding of the EncKrbPrivPart sequence + encrypted under the session key (If supported by the + encryption method in use, an initialization vector may be + passed to the encryption procedure, in order to achieve + proper cipher chaining. The initialization vector might + come from the last block of the ciphertext from the + previous KRB_PRIV message, but it is the application's + choice whether or not to use such an initialization vector. + If left out, the default initialization vector for the + encryption algorithm will be used.). This encrypted + encoding is used for the enc-part field of the KRB-PRIV + message. See section 6 for the format of the ciphertext. + + user-data, timestamp, usec, s-address and r-address These fields are + described above in section 5.6.1. + + seq-number This field is described above in section 5.3.2. + +5.8. KRB_CRED message specification + + This section specifies the format of a message that can be used to + send Kerberos credentials from one principal to another. It is + presented here to encourage a common mechanism to be used by + applications when forwarding tickets or providing proxies to + subordinate servers. It presumes that a session key has already been + exchanged perhaps by using the KRB_AP_REQ/KRB_AP_REP messages. + +5.8.1. KRB_CRED definition + + The KRB_CRED message contains a sequence of tickets to be sent and + information needed to use the tickets, including the session key from + + + +Kohl & Neuman [Page 63] + +RFC 1510 Kerberos September 1993 + + + each. The information needed to use the tickets is encryped under an + encryption key previously exchanged. The message fields are: + + KRB-CRED ::= [APPLICATION 22] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, -- KRB_CRED + tickets[2] SEQUENCE OF Ticket, + enc-part[3] EncryptedData + } + + EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { + ticket-info[0] SEQUENCE OF KrbCredInfo, + nonce[1] INTEGER OPTIONAL, + timestamp[2] KerberosTime OPTIONAL, + usec[3] INTEGER OPTIONAL, + s-address[4] HostAddress OPTIONAL, + r-address[5] HostAddress OPTIONAL + } + + KrbCredInfo ::= SEQUENCE { + key[0] EncryptionKey, + prealm[1] Realm OPTIONAL, + pname[2] PrincipalName OPTIONAL, + flags[3] TicketFlags OPTIONAL, + authtime[4] KerberosTime OPTIONAL, + starttime[5] KerberosTime OPTIONAL, + endtime[6] KerberosTime OPTIONAL + renew-till[7] KerberosTime OPTIONAL, + srealm[8] Realm OPTIONAL, + sname[9] PrincipalName OPTIONAL, + caddr[10] HostAddresses OPTIONAL + } + + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_CRED. + + tickets + These are the tickets obtained from the KDC specifically + for use by the intended recipient. Successive tickets are + paired with the corresponding KrbCredInfo sequence from the + enc-part of the KRB-CRED message. + + enc-part This field holds an encoding of the EncKrbCredPart sequence + encrypted under the session key shared between the sender + and the intended recipient. This encrypted encoding is + used for the enc-part field of the KRB-CRED message. See + section 6 for the format of the ciphertext. + + + +Kohl & Neuman [Page 64] + +RFC 1510 Kerberos September 1993 + + + nonce If practical, an application may require the inclusion of a + nonce generated by the recipient of the message. If the + same value is included as the nonce in the message, it + provides evidence that the message is fresh and has not + been replayed by an attacker. A nonce must never be re- + used; it should be generated randomly by the recipient of + the message and provided to the sender of the mes sage in + an application specific manner. + + timestamp and usec These fields specify the time that the KRB-CRED + message was generated. The time is used to provide + assurance that the message is fresh. + + s-address and r-address These fields are described above in section + 5.6.1. They are used optionally to provide additional + assurance of the integrity of the KRB-CRED message. + + key This field exists in the corresponding ticket passed by the + KRB-CRED message and is used to pass the session key from + the sender to the intended recipient. The field's encoding + is described in section 6.2. + + The following fields are optional. If present, they can be + associated with the credentials in the remote ticket file. If left + out, then it is assumed that the recipient of the credentials already + knows their value. + + prealm and pname The name and realm of the delegated principal + identity. + + flags, authtime, starttime, endtime, renew-till, srealm, sname, + and caddr These fields contain the values of the + corresponding fields from the ticket found in the ticket + field. Descriptions of the fields are identical to the + descriptions in the KDC-REP message. + +5.9. Error message specification + + This section specifies the format for the KRB_ERROR message. The + fields included in the message are intended to return as much + information as possible about an error. It is not expected that all + the information required by the fields will be available for all + types of errors. If the appropriate information is not available + when the message is composed, the corresponding field will be left + out of the message. + + Note that since the KRB_ERROR message is not protected by any + encryption, it is quite possible for an intruder to synthesize or + + + +Kohl & Neuman [Page 65] + +RFC 1510 Kerberos September 1993 + + + modify such a message. In particular, this means that the client + should not use any fields in this message for security-critical + purposes, such as setting a system clock or generating a fresh + authenticator. The message can be useful, however, for advising a + user on the reason for some failure. + +5.9.1. KRB_ERROR definition + + The KRB_ERROR message consists of the following fields: + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL + } + + pvno and msg-type These fields are described above in section 5.4.1. + msg-type is KRB_ERROR. + + ctime This field is described above in section 5.4.1. + + cusec This field is described above in section 5.5.2. + + stime This field contains the current time on the server. It is + of type KerberosTime. + + susec This field contains the microsecond part of the server's + timestamp. Its value ranges from 0 to 999. It appears + along with stime. The two fields are used in conjunction to + specify a reasonably accurate timestamp. + + error-code This field contains the error code returned by Kerberos or + the server when a request fails. To interpret the value of + this field see the list of error codes in section 8. + Implementations are encouraged to provide for national + language support in the display of error messages. + + crealm, cname, srealm and sname These fields are described above in + + + +Kohl & Neuman [Page 66] + +RFC 1510 Kerberos September 1993 + + + section 5.3.1. + + e-text This field contains additional text to help explain the + error code associated with the failed request (for example, + it might include a principal name which was unknown). + + e-data This field contains additional data about the error for use + by the application to help it recover from or handle the + error. If the errorcode is KDC_ERR_PREAUTH_REQUIRED, then + the e-data field will contain an encoding of a sequence of + padata fields, each corresponding to an acceptable pre- + authentication method and optionally containing data for + the method: + + METHOD-DATA ::= SEQUENCE of PA-DATA + + If the error-code is KRB_AP_ERR_METHOD, then the e-data field will + contain an encoding of the following sequence: + + METHOD-DATA ::= SEQUENCE { + method-type[0] INTEGER, + method-data[1] OCTET STRING OPTIONAL + } + + method-type will indicate the required alternate method; method-data + will contain any required additional information. + +6. Encryption and Checksum Specifications + + The Kerberos protocols described in this document are designed to use + stream encryption ciphers, which can be simulated using commonly + available block encryption ciphers, such as the Data Encryption + Standard [11], in conjunction with block chaining and checksum + methods [12]. Encryption is used to prove the identities of the + network entities participating in message exchanges. The Key + Distribution Center for each realm is trusted by all principals + registered in that realm to store a secret key in confidence. Proof + of knowledge of this secret key is used to verify the authenticity of + a principal. + + The KDC uses the principal's secret key (in the AS exchange) or a + shared session key (in the TGS exchange) to encrypt responses to + ticket requests; the ability to obtain the secret key or session key + implies the knowledge of the appropriate keys and the identity of the + KDC. The ability of a principal to decrypt the KDC response and + present a Ticket and a properly formed Authenticator (generated with + the session key from the KDC response) to a service verifies the + identity of the principal; likewise the ability of the service to + + + +Kohl & Neuman [Page 67] + +RFC 1510 Kerberos September 1993 + + + extract the session key from the Ticket and prove its knowledge + thereof in a response verifies the identity of the service. + + The Kerberos protocols generally assume that the encryption used is + secure from cryptanalysis; however, in some cases, the order of + fields in the encrypted portions of messages are arranged to minimize + the effects of poorly chosen keys. It is still important to choose + good keys. If keys are derived from user-typed passwords, those + passwords need to be well chosen to make brute force attacks more + difficult. Poorly chosen keys still make easy targets for intruders. + + The following sections specify the encryption and checksum mechanisms + currently defined for Kerberos. The encodings, chaining, and padding + requirements for each are described. For encryption methods, it is + often desirable to place random information (often referred to as a + confounder) at the start of the message. The requirements for a + confounder are specified with each encryption mechanism. + + Some encryption systems use a block-chaining method to improve the + the security characteristics of the ciphertext. However, these + chaining methods often don't provide an integrity check upon + decryption. Such systems (such as DES in CBC mode) must be augmented + with a checksum of the plaintext which can be verified at decryption + and used to detect any tampering or damage. Such checksums should be + good at detecting burst errors in the input. If any damage is + detected, the decryption routine is expected to return an error + indicating the failure of an integrity check. Each encryption type is + expected to provide and verify an appropriate checksum. The + specification of each encryption method sets out its checksum + requirements. + + Finally, where a key is to be derived from a user's password, an + algorithm for converting the password to a key of the appropriate + type is included. It is desirable for the string to key function to + be one-way, and for the mapping to be different in different realms. + This is important because users who are registered in more than one + realm will often use the same password in each, and it is desirable + that an attacker compromising the Kerberos server in one realm not + obtain or derive the user's key in another. + + For a discussion of the integrity characteristics of the candidate + encryption and checksum methods considered for Kerberos, the the + reader is referred to [13]. + +6.1. Encryption Specifications + + The following ASN.1 definition describes all encrypted messages. The + enc-part field which appears in the unencrypted part of messages in + + + +Kohl & Neuman [Page 68] + +RFC 1510 Kerberos September 1993 + + + section 5 is a sequence consisting of an encryption type, an optional + key version number, and the ciphertext. + + EncryptedData ::= SEQUENCE { + etype[0] INTEGER, -- EncryptionType + kvno[1] INTEGER OPTIONAL, + cipher[2] OCTET STRING -- ciphertext + } + + etype This field identifies which encryption algorithm was used + to encipher the cipher. Detailed specifications for + selected encryption types appear later in this section. + + kvno This field contains the version number of the key under + which data is encrypted. It is only present in messages + encrypted under long lasting keys, such as principals' + secret keys. + + cipher This field contains the enciphered text, encoded as an + OCTET STRING. + + The cipher field is generated by applying the specified encryption + algorithm to data composed of the message and algorithm-specific + inputs. Encryption mechanisms defined for use with Kerberos must + take sufficient measures to guarantee the integrity of the plaintext, + and we recommend they also take measures to protect against + precomputed dictionary attacks. If the encryption algorithm is not + itself capable of doing so, the protections can often be enhanced by + adding a checksum and a confounder. + + The suggested format for the data to be encrypted includes a + confounder, a checksum, the encoded plaintext, and any necessary + padding. The msg-seq field contains the part of the protocol message + described in section 5 which is to be encrypted. The confounder, + checksum, and padding are all untagged and untyped, and their length + is exactly sufficient to hold the appropriate item. The type and + length is implicit and specified by the particular encryption type + being used (etype). The format for the data to be encrypted is + described in the following diagram: + + +-----------+----------+-------------+-----+ + |confounder | check | msg-seq | pad | + +-----------+----------+-------------+-----+ + + The format cannot be described in ASN.1, but for those who prefer an + ASN.1-like notation: + + + + + +Kohl & Neuman [Page 69] + +RFC 1510 Kerberos September 1993 + + +CipherText ::= ENCRYPTED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(conf_length) OPTIONAL, + check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, + msg-seq[2] MsgSequence, + pad UNTAGGED OCTET STRING(pad_length) OPTIONAL +} + + In the above specification, UNTAGGED OCTET STRING(length) is the + notation for an octet string with its tag and length removed. It is + not a valid ASN.1 type. The tag bits and length must be removed from + the confounder since the purpose of the confounder is so that the + message starts with random data, but the tag and its length are + fixed. For other fields, the length and tag would be redundant if + they were included because they are specified by the encryption type. + + One generates a random confounder of the appropriate length, placing + it in confounder; zeroes out check; calculates the appropriate + checksum over confounder, check, and msg-seq, placing the result in + check; adds the necessary padding; then encrypts using the specified + encryption type and the appropriate key. + + Unless otherwise specified, a definition of an encryption algorithm + that specifies a checksum, a length for the confounder field, or an + octet boundary for padding uses this ciphertext format (The ordering + of the fields in the CipherText is important. Additionally, messages + encoded in this format must include a length as part of the msg-seq + field. This allows the recipient to verify that the message has not + been truncated. Without a length, an attacker could use a chosen + plaintext attack to generate a message which could be truncated, + while leaving the checksum intact. Note that if the msg-seq is an + encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length is + part of that encoding.). Those fields which are not specified will be + omitted. + + In the interest of allowing all implementations using a particular + encryption type to communicate with all others using that type, the + specification of an encryption type defines any checksum that is + needed as part of the encryption process. If an alternative checksum + is to be used, a new encryption type must be defined. + + Some cryptosystems require additional information beyond the key and + the data to be encrypted. For example, DES, when used in cipher- + block-chaining mode, requires an initialization vector. If required, + the description for each encryption type must specify the source of + such additional information. + + + + + + +Kohl & Neuman [Page 70] + +RFC 1510 Kerberos September 1993 + + +6.2. Encryption Keys + + The sequence below shows the encoding of an encryption key: + + EncryptionKey ::= SEQUENCE { + keytype[0] INTEGER, + keyvalue[1] OCTET STRING + } + + keytype This field specifies the type of encryption key that + follows in the keyvalue field. It will almost always + correspond to the encryption algorithm used to generate the + EncryptedData, though more than one algorithm may use the + same type of key (the mapping is many to one). This might + happen, for example, if the encryption algorithm uses an + alternate checksum algorithm for an integrity check, or a + different chaining mechanism. + + keyvalue This field contains the key itself, encoded as an octet + string. + + All negative values for the encryption key type are reserved for + local use. All non-negative values are reserved for officially + assigned type fields and interpretations. + +6.3. Encryption Systems + +6.3.1. The NULL Encryption System (null) + + If no encryption is in use, the encryption system is said to be the + NULL encryption system. In the NULL encryption system there is no + checksum, confounder or padding. The ciphertext is simply the + plaintext. The NULL Key is used by the null encryption system and is + zero octets in length, with keytype zero (0). + +6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) + + The des-cbc-crc encryption mode encrypts information under the Data + Encryption Standard [11] using the cipher block chaining mode [12]. + A CRC-32 checksum (described in ISO 3309 [14]) is applied to the + confounder and message sequence (msg-seq) and placed in the cksum + field. DES blocks are 8 bytes. As a result, the data to be + encrypted (the concatenation of confounder, checksum, and message) + must be padded to an 8 byte boundary before encryption. The details + of the encryption of this data are identical to those for the des- + cbc-md5 encryption mode. + + Note that, since the CRC-32 checksum is not collisionproof, an + + + +Kohl & Neuman [Page 71] + +RFC 1510 Kerberos September 1993 + + + attacker could use a probabilistic chosenplaintext attack to generate + a valid message even if a confounder is used [13]. The use of + collision-proof checksums is recommended for environments where such + attacks represent a significant threat. The use of the CRC-32 as the + checksum for ticket or authenticator is no longer mandated as an + interoperability requirement for Kerberos Version 5 Specification 1 + (See section 9.1 for specific details). + +6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) + + The des-cbc-md4 encryption mode encrypts information under the Data + Encryption Standard [11] using the cipher block chaining mode [12]. + An MD4 checksum (described in [15]) is applied to the confounder and + message sequence (msg-seq) and placed in the cksum field. DES blocks + are 8 bytes. As a result, the data to be encrypted (the + concatenation of confounder, checksum, and message) must be padded to + an 8 byte boundary before encryption. The details of the encryption + of this data are identical to those for the descbc-md5 encryption + mode. + +6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) + + The des-cbc-md5 encryption mode encrypts information under the Data + Encryption Standard [11] using the cipher block chaining mode [12]. + An MD5 checksum (described in [16]) is applied to the confounder and + message sequence (msg-seq) and placed in the cksum field. DES blocks + are 8 bytes. As a result, the data to be encrypted (the + concatenation of confounder, checksum, and message) must be padded to + an 8 byte boundary before encryption. + + Plaintext and DES ciphtertext are encoded as 8-octet blocks which are + concatenated to make the 64-bit inputs for the DES algorithms. The + first octet supplies the 8 most significant bits (with the octet's + MSbit used as the DES input block's MSbit, etc.), the second octet + the next 8 bits, ..., and the eighth octet supplies the 8 least + significant bits. + + Encryption under DES using cipher block chaining requires an + additional input in the form of an initialization vector. Unless + otherwise specified, zero should be used as the initialization + vector. Kerberos' use of DES requires an 8-octet confounder. + + The DES specifications identify some "weak" and "semiweak" keys; + those keys shall not be used for encrypting messages for use in + Kerberos. Additionally, because of the way that keys are derived for + the encryption of checksums, keys shall not be used that yield "weak" + or "semi-weak" keys when eXclusive-ORed with the constant + F0F0F0F0F0F0F0F0. + + + +Kohl & Neuman [Page 72] + +RFC 1510 Kerberos September 1993 + + + A DES key is 8 octets of data, with keytype one (1). This consists + of 56 bits of key, and 8 parity bits (one per octet). The key is + encoded as a series of 8 octets written in MSB-first order. The bits + within the key are also encoded in MSB order. For example, if the + encryption key is: + (B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where + B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the + parity bits, the first octet of the key would be B1,B2,...,B7,P1 + (with B1 as the MSbit). [See the FIPS 81 introduction for + reference.] + + To generate a DES key from a text string (password), the text string + normally must have the realm and each component of the principal's + name appended(In some cases, it may be necessary to use a different + "mix-in" string for compatibility reasons; see the discussion of + padata in section 5.4.2.), then padded with ASCII nulls to an 8 byte + boundary. This string is then fan-folded and eXclusive-ORed with + itself to form an 8 byte DES key. The parity is corrected on the + key, and it is used to generate a DES CBC checksum on the initial + string (with the realm and name appended). Next, parity is corrected + on the CBC checksum. If the result matches a "weak" or "semiweak" + key as described in the DES specification, it is eXclusive-ORed with + the constant 00000000000000F0. Finally, the result is returned as + the key. Pseudocode follows: + + string_to_key(string,realm,name) { + odd = 1; + s = string + realm; + for(each component in name) { + s = s + component; + } + tempkey = NULL; + pad(s); /* with nulls to 8 byte boundary */ + for(8byteblock in s) { + if(odd == 0) { + odd = 1; + reverse(8byteblock) + } + else odd = 0; + tempkey = tempkey XOR 8byteblock; + } + fixparity(tempkey); + key = DES-CBC-check(s,tempkey); + fixparity(key); + if(is_weak_key_key(key)) + key = key XOR 0xF0; + return(key); + } + + + +Kohl & Neuman [Page 73] + +RFC 1510 Kerberos September 1993 + + +6.4. Checksums + + The following is the ASN.1 definition used for a checksum: + + Checksum ::= SEQUENCE { + cksumtype[0] INTEGER, + checksum[1] OCTET STRING + } + + cksumtype This field indicates the algorithm used to generate the + accompanying checksum. + + checksum This field contains the checksum itself, encoded + as an octet string. + + Detailed specification of selected checksum types appear later in + this section. Negative values for the checksum type are reserved for + local use. All non-negative values are reserved for officially + assigned type fields and interpretations. + + Checksums used by Kerberos can be classified by two properties: + whether they are collision-proof, and whether they are keyed. It is + infeasible to find two plaintexts which generate the same checksum + value for a collision-proof checksum. A key is required to perturb + or initialize the algorithm in a keyed checksum. To prevent + message-stream modification by an active attacker, unkeyed checksums + should only be used when the checksum and message will be + subsequently encrypted (e.g., the checksums defined as part of the + encryption algorithms covered earlier in this section). Collision- + proof checksums can be made tamper-proof as well if the checksum + value is encrypted before inclusion in a message. In such cases, the + composition of the checksum and the encryption algorithm must be + considered a separate checksum algorithm (e.g., RSA-MD5 encrypted + using DES is a new checksum algorithm of type RSA-MD5-DES). For most + keyed checksums, as well as for the encrypted forms of collisionproof + checksums, Kerberos prepends a confounder before the checksum is + calculated. + +6.4.1. The CRC-32 Checksum (crc32) + + The CRC-32 checksum calculates a checksum based on a cyclic + redundancy check as described in ISO 3309 [14]. The resulting + checksum is four (4) octets in length. The CRC-32 is neither keyed + nor collision-proof. The use of this checksum is not recommended. + An attacker using a probabilistic chosen-plaintext attack as + described in [13] might be able to generate an alternative message + that satisfies the checksum. The use of collision-proof checksums is + recommended for environments where such attacks represent a + + + +Kohl & Neuman [Page 74] + +RFC 1510 Kerberos September 1993 + + + significant threat. + +6.4.2. The RSA MD4 Checksum (rsa-md4) + + The RSA-MD4 checksum calculates a checksum using the RSA MD4 + algorithm [15]. The algorithm takes as input an input message of + arbitrary length and produces as output a 128-bit (16 octet) + checksum. RSA-MD4 is believed to be collision-proof. + +6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4des) + + The RSA-MD4-DES checksum calculates a keyed collisionproof checksum + by prepending an 8 octet confounder before the text, applying the RSA + MD4 checksum algorithm, and encrypting the confounder and the + checksum using DES in cipher-block-chaining (CBC) mode using a + variant of the key, where the variant is computed by eXclusive-ORing + the key with the constant F0F0F0F0F0F0F0F0 (A variant of the key is + used to limit the use of a key to a particular function, separating + the functions of generating a checksum from other encryption + performed using the session key. The constant F0F0F0F0F0F0F0F0 was + chosen because it maintains key parity. The properties of DES + precluded the use of the complement. The same constant is used for + similar purpose in the Message Integrity Check in the Privacy + Enhanced Mail standard.). The initialization vector should be zero. + The resulting checksum is 24 octets long (8 octets of which are + redundant). This checksum is tamper-proof and believed to be + collision-proof. + + The DES specifications identify some "weak keys"; those keys shall + not be used for generating RSA-MD4 checksums for use in Kerberos. + + The format for the checksum is described in the following diagram: + + +--+--+--+--+--+--+--+-- + | des-cbc(confounder + +--+--+--+--+--+--+--+-- + + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + rsa-md4(confounder+msg),key=var(key),iv=0) | + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + The format cannot be described in ASN.1, but for those who prefer an + ASN.1-like notation: + + rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) + } + + + +Kohl & Neuman [Page 75] + +RFC 1510 Kerberos September 1993 + + +6.4.4. The RSA MD5 Checksum (rsa-md5) + + The RSA-MD5 checksum calculates a checksum using the RSA MD5 + algorithm [16]. The algorithm takes as input an input message of + arbitrary length and produces as output a 128-bit (16 octet) + checksum. RSA-MD5 is believed to be collision-proof. + +6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5des) + + The RSA-MD5-DES checksum calculates a keyed collisionproof checksum + by prepending an 8 octet confounder before the text, applying the RSA + MD5 checksum algorithm, and encrypting the confounder and the + checksum using DES in cipher-block-chaining (CBC) mode using a + variant of the key, where the variant is computed by eXclusive-ORing + the key with the constant F0F0F0F0F0F0F0F0. The initialization + vector should be zero. The resulting checksum is 24 octets long (8 + octets of which are redundant). This checksum is tamper-proof and + believed to be collision-proof. + + The DES specifications identify some "weak keys"; those keys shall + not be used for encrypting RSA-MD5 checksums for use in Kerberos. + + The format for the checksum is described in the following diagram: + + +--+--+--+--+--+--+--+-- + | des-cbc(confounder + +--+--+--+--+--+--+--+-- + + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + rsa-md5(confounder+msg),key=var(key),iv=0) | + +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ + + The format cannot be described in ASN.1, but for those who prefer an + ASN.1-like notation: + + rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(16) + } + +6.4.6. DES cipher-block chained checksum (des-mac) + + The DES-MAC checksum is computed by prepending an 8 octet confounder + to the plaintext, performing a DES CBC-mode encryption on the result + using the key and an initialization vector of zero, taking the last + block of the ciphertext, prepending the same confounder and + encrypting the pair using DES in cipher-block-chaining (CBC) mode + using a a variant of the key, where the variant is computed by + + + +Kohl & Neuman [Page 76] + +RFC 1510 Kerberos September 1993 + + + eXclusive-ORing the key with the constant F0F0F0F0F0F0F0F0. The + initialization vector should be zero. The resulting checksum is 128 + bits (16 octets) long, 64 bits of which are redundant. This checksum + is tamper-proof and collision-proof. + + The format for the checksum is described in the following diagram: + + +--+--+--+--+--+--+--+-- + | des-cbc(confounder + +--+--+--+--+--+--+--+-- + + +-----+-----+-----+-----+-----+-----+-----+-----+ + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | + +-----+-----+-----+-----+-----+-----+-----+-----+ + + The format cannot be described in ASN.1, but for those who prefer an + ASN.1-like notation: + + des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { + confounder[0] UNTAGGED OCTET STRING(8), + check[1] UNTAGGED OCTET STRING(8) + } + + The DES specifications identify some "weak" and "semiweak" keys; + those keys shall not be used for generating DES-MAC checksums for use + in Kerberos, nor shall a key be used whose veriant is "weak" or + "semi-weak". + +6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative + (rsa-md4-des-k) + + The RSA-MD4-DES-K checksum calculates a keyed collision-proof + checksum by applying the RSA MD4 checksum algorithm and encrypting + the results using DES in cipherblock-chaining (CBC) mode using a DES + key as both key and initialization vector. The resulting checksum is + 16 octets long. This checksum is tamper-proof and believed to be + collision-proof. Note that this checksum type is the old method for + encoding the RSA-MD4-DES checksum and it is no longer recommended. + +6.4.8. DES cipher-block chained checksum alternative (desmac-k) + + The DES-MAC-K checksum is computed by performing a DES CBC-mode + encryption of the plaintext, and using the last block of the + ciphertext as the checksum value. It is keyed with an encryption key + and an initialization vector; any uses which do not specify an + additional initialization vector will use the key as both key and + initialization vector. The resulting checksum is 64 bits (8 octets) + long. This checksum is tamper-proof and collision-proof. Note that + + + +Kohl & Neuman [Page 77] + +RFC 1510 Kerberos September 1993 + + + this checksum type is the old method for encoding the DESMAC checksum + and it is no longer recommended. + + The DES specifications identify some "weak keys"; those keys shall + not be used for generating DES-MAC checksums for use in Kerberos. + +7. Naming Constraints + +7.1. Realm Names + + Although realm names are encoded as GeneralStrings and although a + realm can technically select any name it chooses, interoperability + across realm boundaries requires agreement on how realm names are to + be assigned, and what information they imply. + + To enforce these conventions, each realm must conform to the + conventions itself, and it must require that any realms with which + inter-realm keys are shared also conform to the conventions and + require the same from its neighbors. + + There are presently four styles of realm names: domain, X500, other, + and reserved. Examples of each style follow: + + domain: host.subdomain.domain (example) + X500: C=US/O=OSF (example) + other: NAMETYPE:rest/of.name=without-restrictions (example) + reserved: reserved, but will not conflict with above + + Domain names must look like domain names: they consist of components + separated by periods (.) and they contain neither colons (:) nor + slashes (/). + + X.500 names contain an equal (=) and cannot contain a colon (:) + before the equal. The realm names for X.500 names will be string + representations of the names with components separated by slashes. + Leading and trailing slashes will not be included. + + Names that fall into the other category must begin with a prefix that + contains no equal (=) or period (.) and the prefix must be followed + by a colon (:) and the rest of the name. All prefixes must be + assigned before they may be used. Presently none are assigned. + + The reserved category includes strings which do not fall into the + first three categories. All names in this category are reserved. It + is unlikely that names will be assigned to this category unless there + is a very strong argument for not using the "other" category. + + These rules guarantee that there will be no conflicts between the + + + +Kohl & Neuman [Page 78] + +RFC 1510 Kerberos September 1993 + + + various name styles. The following additional constraints apply to + the assignment of realm names in the domain and X.500 categories: the + name of a realm for the domain or X.500 formats must either be used + by the organization owning (to whom it was assigned) an Internet + domain name or X.500 name, or in the case that no such names are + registered, authority to use a realm name may be derived from the + authority of the parent realm. For example, if there is no domain + name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can + authorize the creation of a realm with that name. + + This is acceptable because the organization to which the parent is + assigned is presumably the organization authorized to assign names to + its children in the X.500 and domain name systems as well. If the + parent assigns a realm name without also registering it in the domain + name or X.500 hierarchy, it is the parent's responsibility to make + sure that there will not in the future exists a name identical to the + realm name of the child unless it is assigned to the same entity as + the realm name. + +7.2. Principal Names + + As was the case for realm names, conventions are needed to ensure + that all agree on what information is implied by a principal name. + The name-type field that is part of the principal name indicates the + kind of information implied by the name. The name-type should be + treated as a hint. Ignoring the name type, no two names can be the + same (i.e., at least one of the components, or the realm, must be + different). This constraint may be eliminated in the future. The + following name types are defined: + + name-type value meaning + NT-UNKNOWN 0 Name type not known + NT-PRINCIPAL 1 Just the name of the principal as in + DCE, or for users + NT-SRV-INST 2 Service and other unique instance (krbtgt) + NT-SRV-HST 3 Service with host name as instance + (telnet, rcommands) + NT-SRV-XHST 4 Service with host as remaining components + NT-UID 5 Unique ID + + When a name implies no information other than its uniqueness at a + particular time the name type PRINCIPAL should be used. The + principal name type should be used for users, and it might also be + used for a unique server. If the name is a unique machine generated + ID that is guaranteed never to be reassigned then the name type of + UID should be used (note that it is generally a bad idea to reassign + names of any type since stale entries might remain in access control + lists). + + + +Kohl & Neuman [Page 79] + +RFC 1510 Kerberos September 1993 + + + If the first component of a name identifies a service and the + remaining components identify an instance of the service in a server + specified manner, then the name type of SRV-INST should be used. An + example of this name type is the Kerberos ticket-granting ticket + which has a first component of krbtgt and a second component + identifying the realm for which the ticket is valid. + + If instance is a single component following the service name and the + instance identifies the host on which the server is running, then the + name type SRV-HST should be used. This type is typically used for + Internet services such as telnet and the Berkeley R commands. If the + separate components of the host name appear as successive components + following the name of the service, then the name type SRVXHST should + be used. This type might be used to identify servers on hosts with + X.500 names where the slash (/) might otherwise be ambiguous. + + A name type of UNKNOWN should be used when the form of the name is + not known. When comparing names, a name of type UNKNOWN will match + principals authenticated with names of any type. A principal + authenticated with a name of type UNKNOWN, however, will only match + other names of type UNKNOWN. + + Names of any type with an initial component of "krbtgt" are reserved + for the Kerberos ticket granting service. See section 8.2.3 for the + form of such names. + +7.2.1. Name of server principals + + The principal identifier for a server on a host will generally be + composed of two parts: (1) the realm of the KDC with which the server + is registered, and (2) a two-component name of type NT-SRV-HST if the + host name is an Internet domain name or a multi-component name of + type NT-SRV-XHST if the name of the host is of a form such as X.500 + that allows slash (/) separators. The first component of the two- or + multi-component name will identify the service and the latter + components will identify the host. Where the name of the host is not + case sensitive (for example, with Internet domain names) the name of + the host must be lower case. For services such as telnet and the + Berkeley R commands which run with system privileges, the first + component will be the string "host" instead of a service specific + identifier. + +8. Constants and other defined values + +8.1. Host address types + + All negative values for the host address type are reserved for local + use. All non-negative values are reserved for officially assigned + + + +Kohl & Neuman [Page 80] + +RFC 1510 Kerberos September 1993 + + + type fields and interpretations. + + The values of the types for the following addresses are chosen to + match the defined address family constants in the Berkeley Standard + Distributions of Unix. They can be found in <sys/socket.h> with + symbolic names AF_xxx (where xxx is an abbreviation of the address + family name). + + + Internet addresses + + Internet addresses are 32-bit (4-octet) quantities, encoded in MSB + order. The type of internet addresses is two (2). + + CHAOSnet addresses + + CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB + order. The type of CHAOSnet addresses is five (5). + + ISO addresses + + ISO addresses are variable-length. The type of ISO addresses is + seven (7). + + Xerox Network Services (XNS) addresses + + XNS addresses are 48-bit (6-octet) quantities, encoded in MSB + order. The type of XNS addresses is six (6). + + AppleTalk Datagram Delivery Protocol (DDP) addresses + + AppleTalk DDP addresses consist of an 8-bit node number and a 16- + bit network number. The first octet of the address is the node + number; the remaining two octets encode the network number in MSB + order. The type of AppleTalk DDP addresses is sixteen (16). + + DECnet Phase IV addresses + + DECnet Phase IV addresses are 16-bit addresses, encoded in LSB + order. The type of DECnet Phase IV addresses is twelve (12). + +8.2. KDC messages + +8.2.1. IP transport + + When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request + using IP transport, the client shall send a UDP datagram containing + only an encoding of the request to port 88 (decimal) at the KDC's IP + + + +Kohl & Neuman [Page 81] + +RFC 1510 Kerberos September 1993 + + + address; the KDC will respond with a reply datagram containing only + an encoding of the reply message (either a KRB_ERROR or a + KRB_KDC_REP) to the sending port at the sender's IP address. + +8.2.2. OSI transport + + During authentication of an OSI client to and OSI server, the mutual + authentication of an OSI server to an OSI client, the transfer of + credentials from an OSI client to an OSI server, or during exchange + of private or integrity checked messages, Kerberos protocol messages + may be treated as opaque objects and the type of the authentication + mechanism will be: + + OBJECT IDENTIFIER ::= {iso (1), org(3), dod(5),internet(1), + security(5), kerberosv5(2)} + + Depending on the situation, the opaque object will be an + authentication header (KRB_AP_REQ), an authentication reply + (KRB_AP_REP), a safe message (KRB_SAFE), a private message + (KRB_PRIV), or a credentials message (KRB_CRED). The opaque data + contains an application code as specified in the ASN.1 description + for each message. The application code may be used by Kerberos to + determine the message type. + +8.2.3. Name of the TGS + + The principal identifier of the ticket-granting service shall be + composed of three parts: (1) the realm of the KDC issuing the TGS + ticket (2) a two-part name of type NT-SRVINST, with the first part + "krbtgt" and the second part the name of the realm which will accept + the ticket-granting ticket. For example, a ticket-granting ticket + issued by the ATHENA.MIT.EDU realm to be used to get tickets from the + ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU" + (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting + ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets + from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" + (realm), ("krbtgt", "MIT.EDU") (name). + +8.3. Protocol constants and associated values + + The following tables list constants used in the protocol and defines + their meanings. + + + + + + + + + +Kohl & Neuman [Page 82] + +RFC 1510 Kerberos September 1993 + + +---------------+-----------+----------+----------------+--------------- +Encryption type|etype value|block size|minimum pad size|confounder size +---------------+-----------+----------+----------------+--------------- +NULL 0 1 0 0 +des-cbc-crc 1 8 4 8 +des-cbc-md4 2 8 0 8 +des-cbc-md5 3 8 0 8 + +-------------------------------+-------------------+------------- +Checksum type |sumtype value |checksum size +-------------------------------+-------------------+------------- +CRC32 1 4 +rsa-md4 2 16 +rsa-md4-des 3 24 +des-mac 4 16 +des-mac-k 5 8 +rsa-md4-des-k 6 16 +rsa-md5 7 16 +rsa-md5-des 8 24 + +-------------------------------+----------------- +padata type |padata-type value +-------------------------------+----------------- +PA-TGS-REQ 1 +PA-ENC-TIMESTAMP 2 +PA-PW-SALT 3 + +-------------------------------+------------- +authorization data type |ad-type value +-------------------------------+------------- +reserved values 0-63 +OSF-DCE 64 +SESAME 65 + +-------------------------------+----------------- +alternate authentication type |method-type value +-------------------------------+----------------- +reserved values 0-63 +ATT-CHALLENGE-RESPONSE 64 + +-------------------------------+------------- +transited encoding type |tr-type value +-------------------------------+------------- +DOMAIN-X500-COMPRESS 1 +reserved values all others + + + + + + +Kohl & Neuman [Page 83] + +RFC 1510 Kerberos September 1993 + + +--------------+-------+----------------------------------------- +Label |Value |Meaning or MIT code +--------------+-------+----------------------------------------- + +pvno 5 current Kerberos protocol version number + +message types + +KRB_AS_REQ 10 Request for initial authentication +KRB_AS_REP 11 Response to KRB_AS_REQ request +KRB_TGS_REQ 12 Request for authentication based on TGT +KRB_TGS_REP 13 Response to KRB_TGS_REQ request +KRB_AP_REQ 14 application request to server +KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL +KRB_SAFE 20 Safe (checksummed) application message +KRB_PRIV 21 Private (encrypted) application message +KRB_CRED 22 Private (encrypted) message to forward + credentials +KRB_ERROR 30 Error response + +name types + +KRB_NT_UNKNOWN 0 Name type not known +KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or + for users +KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) +KRB_NT_SRV_HST 3 Service with host name as instance (telnet, + rcommands) +KRB_NT_SRV_XHST 4 Service with host as remaining components +KRB_NT_UID 5 Unique ID + +error codes + +KDC_ERR_NONE 0 No error +KDC_ERR_NAME_EXP 1 Client's entry in database has + expired +KDC_ERR_SERVICE_EXP 2 Server's entry in database has + expired +KDC_ERR_BAD_PVNO 3 Requested protocol version number + not supported +KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old + master key +KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old + master key +KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database +KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database +KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in + database + + + +Kohl & Neuman [Page 84] + +RFC 1510 Kerberos September 1993 + + +KDC_ERR_NULL_KEY 9 The client or server has a null key +KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating +KDC_ERR_NEVER_VALID 11 Requested start time is later than + end time +KDC_ERR_POLICY 12 KDC policy rejects request +KDC_ERR_BADOPTION 13 KDC cannot accommodate requested + option +KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption + type +KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type +KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type +KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type +KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked +KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been + revoked +KDC_ERR_TGT_REVOKED 20 TGT has been revoked +KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again + later +KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again + later +KDC_ERR_KEY_EXPIRED 23 Password has expired - change + password to reset +KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information + was invalid +KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authentication + required* +KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field + failed +KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired +KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid +KRB_AP_ERR_REPEAT 34 Request is a replay +KRB_AP_ERR_NOT_US 35 The ticket isn't for us +KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match +KRB_AP_ERR_SKEW 37 Clock skew too great +KRB_AP_ERR_BADADDR 38 Incorrect net address +KRB_AP_ERR_BADVERSION 39 Protocol version mismatch +KRB_AP_ERR_MSG_TYPE 40 Invalid msg type +KRB_AP_ERR_MODIFIED 41 Message stream modified +KRB_AP_ERR_BADORDER 42 Message out of order +KRB_AP_ERR_BADKEYVER 44 Specified version of key is not + available +KRB_AP_ERR_NOKEY 45 Service key not available +KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed +KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction +KRB_AP_ERR_METHOD 48 Alternative authentication method + required* +KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message +KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in + + + +Kohl & Neuman [Page 85] + +RFC 1510 Kerberos September 1993 + + + message +KRB_ERR_GENERIC 60 Generic error (description in e-text) +KRB_ERR_FIELD_TOOLONG 61 Field is too long for this + implementation + + *This error carries additional information in the e-data field. The + contents of the e-data field for this message is described in section + 5.9.1. + +9. Interoperability requirements + + Version 5 of the Kerberos protocol supports a myriad of options. + Among these are multiple encryption and checksum types, alternative + encoding schemes for the transited field, optional mechanisms for + pre-authentication, the handling of tickets with no addresses, + options for mutual authentication, user to user authentication, + support for proxies, forwarding, postdating, and renewing tickets, + the format of realm names, and the handling of authorization data. + + In order to ensure the interoperability of realms, it is necessary to + define a minimal configuration which must be supported by all + implementations. This minimal configuration is subject to change as + technology does. For example, if at some later date it is discovered + that one of the required encryption or checksum algorithms is not + secure, it will be replaced. + +9.1. Specification 1 + + This section defines the first specification of these options. + Implementations which are configured in this way can be said to + support Kerberos Version 5 Specification 1 (5.1). + + Encryption and checksum methods + + The following encryption and checksum mechanisms must be supported. + Implementations may support other mechanisms as well, but the + additional mechanisms may only be used when communicating with + principals known to also support them: Encryption: DES-CBC-MD5 + Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 + + Realm Names + + All implementations must understand hierarchical realms in both the + Internet Domain and the X.500 style. When a ticket granting ticket + for an unknown realm is requested, the KDC must be able to determine + the names of the intermediate realms between the KDCs realm and the + requested realm. + + + + +Kohl & Neuman [Page 86] + +RFC 1510 Kerberos September 1993 + + + Transited field encoding + + DOMAIN-X500-COMPRESS (described in section 3.3.3.1) must be + supported. Alternative encodings may be supported, but they may be + used only when that encoding is supported by ALL intermediate realms. + + Pre-authentication methods + + The TGS-REQ method must be supported. The TGS-REQ method is not used + on the initial request. The PA-ENC-TIMESTAMP method must be supported + by clients but whether it is enabled by default may be determined on + a realm by realm basis. If not used in the initial request and the + error KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENCTIMESTAMP + as an acceptable method, the client should retry the initial request + using the PA-ENC-TIMESTAMP preauthentication method. Servers need not + support the PAENC-TIMESTAMP method, but if not supported the server + should ignore the presence of PA-ENC-TIMESTAMP pre-authentication in + a request. + + Mutual authentication + + Mutual authentication (via the KRB_AP_REP message) must be supported. + + Ticket addresses and flags + + All KDC's must pass on tickets that carry no addresses (i.e., if a + TGT contains no addresses, the KDC will return derivative tickets), + but each realm may set its own policy for issuing such tickets, and + each application server will set its own policy with respect to + accepting them. By default, servers should not accept them. + + Proxies and forwarded tickets must be supported. Individual realms + and application servers can set their own policy on when such tickets + will be accepted. + + All implementations must recognize renewable and postdated tickets, + but need not actually implement them. If these options are not + supported, the starttime and endtime in the ticket shall specify a + ticket's entire useful life. When a postdated ticket is decoded by a + server, all implementations shall make the presence of the postdated + flag visible to the calling server. + + User-to-user authentication + + Support for user to user authentication (via the ENC-TKTIN-SKEY KDC + option) must be provided by implementations, but individual realms + may decide as a matter of policy to reject such requests on a per- + principal or realm-wide basis. + + + +Kohl & Neuman [Page 87] + +RFC 1510 Kerberos September 1993 + + + Authorization data + + Implementations must pass all authorization data subfields from + ticket-granting tickets to any derivative tickets unless directed to + suppress a subfield as part of the definition of that registered + subfield type (it is never incorrect to pass on a subfield, and no + registered subfield types presently specify suppression at the KDC). + + Implementations must make the contents of any authorization data + subfields available to the server when a ticket is used. + Implementations are not required to allow clients to specify the + contents of the authorization data fields. + +9.2. Recommended KDC values + + Following is a list of recommended values for a KDC implementation, + based on the list of suggested configuration constants (see section + 4.4). + + minimum lifetime 5 minutes + + maximum renewable lifetime 1 week + + maximum ticket lifetime 1 day + + empty addresses only when suitable restrictions appear + in authorization data + + proxiable, etc. Allowed. + +10. Acknowledgments + + Early versions of this document, describing version 4 of the + protocol, were written by Jennifer Steiner (formerly at Project + Athena); these drafts provided an excellent starting point for this + current version 5 specification. Many people in the Internet + community have contributed ideas and suggested protocol changes for + version 5. Notable contributions came from Ted Anderson, Steve + Bellovin and Michael Merritt [17], Daniel Bernstein, Mike Burrows, + Donald Davis, Ravi Ganesan, Morrie Gasser, Virgil Gligor, Bill + Griffeth, Mark Lillibridge, Mark Lomas, Steve Lunt, Piers McMahon, + Joe Pato, William Sommerfeld, Stuart Stubblebine, Ralph Swick, Ted + T'so, and Stanley Zanarotti. Many others commented and helped shape + this specification into its current form. + + + + + + + +Kohl & Neuman [Page 88] + +RFC 1510 Kerberos September 1993 + + +11. References + + [1] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section + E.2.1: Kerberos Authentication and Authorization System", + M.I.T. Project Athena, Cambridge, Massachusetts, December 21, + 1987. + + [2] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An + Authentication Service for Open Network Systems", pp. 191-202 in + Usenix Conference Proceedings, Dallas, Texas, February, 1988. + + [3] Needham, R., and M. Schroeder, "Using Encryption for + Authentication in Large Networks of Computers", Communications + of the ACM, Vol. 21 (12), pp. 993-999, December 1978. + + [4] Denning, D., and G. Sacco, "Time stamps in Key Distribution + Protocols", Communications of the ACM, Vol. 24 (8), pp. 533-536, + August 1981. + + [5] Kohl, J., Neuman, C., and T. Ts'o, "The Evolution of the + Kerberos Authentication Service", in an IEEE Computer Society + Text soon to be published, June 1992. + + [6] Davis, D., and R. Swick, "Workstation Services and Kerberos + Authentication at Project Athena", Technical Memorandum TM-424, + MIT Laboratory for Computer Science, February 1990. + + [7] Levine, P., Gretzinger, M, Diaz, J., Sommerfeld, W., and K. + Raeburn, "Section E.1: Service Management System, M.I.T. + Project Athena, Cambridge, Mas sachusetts (1987). + + [8] CCITT, Recommendation X.509: The Directory Authentication + Framework, December 1988. + + [9] Neuman, C., "Proxy-Based Authorization and Accounting for + Distributed Systems," in Proceedings of the 13th International + Conference on Distributed Computing Systems", Pittsburgh, PA, + May 1993. + + [10] Pato, J., "Using Pre-Authentication to Avoid Password Guessing + Attacks", Open Software Foundation DCE Request for Comments 26, + December 1992. + + [11] National Bureau of Standards, U.S. Department of Commerce, "Data + Encryption Standard", Federal Information Processing Standards + Publication 46, Washington, DC (1977). + + + + + +Kohl & Neuman [Page 89] + +RFC 1510 Kerberos September 1993 + + + [12] National Bureau of Standards, U.S. Department of Commerce, "DES + Modes of Operation", Federal Information Processing Standards + Publication 81, Springfield, VA, December 1980. + + [13] Stubblebine S., and V. Gligor, "On Message Integrity in + Cryptographic Protocols", in Proceedings of the IEEE Symposium + on Research in Security and Privacy, Oakland, California, May + 1992. + + [14] International Organization for Standardization, "ISO Information + Processing Systems - Data Communication High-Level Data Link + Control Procedure - Frame Structure", IS 3309, October 1984, 3rd + Edition. + + [15] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT + Laboratory for Computer Science, April 1992. + + [16] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, MIT + Laboratory for Computer Science, April 1992. + + [17] Bellovin S., and M. Merritt, "Limitations of the Kerberos + Authentication System", Computer Communications Review, Vol. + 20(5), pp. 119-132, October 1990. + +12. Security Considerations + + Security issues are discussed throughout this memo. + +13. Authors' Addresses + + John Kohl + Digital Equipment Corporation + 110 Spit Brook Road, M/S ZKO3-3/U14 + Nashua, NH 03062 + + Phone: 603-881-2481 + EMail: jtkohl@zk3.dec.com + + + B. Clifford Neuman + USC/Information Sciences Institute + 4676 Admiralty Way #1001 + Marina del Rey, CA 90292-6695 + + Phone: 310-822-1511 + EMail: bcn@isi.edu + + + + + +Kohl & Neuman [Page 90] + +RFC 1510 Kerberos September 1993 + + +A. Pseudo-code for protocol processing + + This appendix provides pseudo-code describing how the messages are to + be constructed and interpreted by clients and servers. + +A.1. KRB_AS_REQ generation + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_AS_REQ */ + + if(pa_enc_timestamp_required) then + request.padata.padata-type = PA-ENC-TIMESTAMP; + get system_time; + padata-body.patimestamp,pausec = system_time; + encrypt padata-body into request.padata.padata-value + using client.key; /* derived from password */ + endif + + body.kdc-options := users's preferences; + body.cname := user's name; + body.realm := user's realm; + body.sname := service's name; /* usually "krbtgt", + "localrealm" */ + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + omit body.enc-authorization-data; + request.req-body := body; + + kerberos := lookup(name of local kerberos server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + + + +Kohl & Neuman [Page 91] + +RFC 1510 Kerberos September 1993 + + +A.2. KRB_AS_REQ verification and KRB_AS_REP generation + decode message into req; + + client := lookup(req.cname,req.realm); + server := lookup(req.sname,req.realm); + get system_time; + kdc_time := system_time.seconds; + + if (!client) then + /* no client in Database */ + error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); + endif + if (!server) then + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + + if(client.pa_enc_timestamp_required and + pa_enc_timestamp not present) then + error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); + endif + + if(pa_enc_timestamp present) then + decrypt req.padata-value into decrypted_enc_timestamp + using client.key; + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + if(decrypted_enc_timestamp is not within allowable + skew) then error_out(KDC_ERR_PREAUTH_FAILED); + endif + if(decrypted_enc_timestamp and usec is replay) + error_out(KDC_ERR_PREAUTH_FAILED); + endif + add decrypted_enc_timestamp and usec to replay cache; + endif + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := req.srealm; + reset all flags in new_tkt.flags; + + + + +Kohl & Neuman [Page 92] + +RFC 1510 Kerberos September 1993 + + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + if (req.kdc-options.FORWARDABLE is set) then + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.PROXIABLE is set) then + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.ALLOW-POSTDATE is set) then + set new_tkt.flags.ALLOW-POSTDATE; + endif + if ((req.kdc-options.RENEW is set) or + (req.kdc-options.VALIDATE is set) or + (req.kdc-options.PROXY is set) or + (req.kdc-options.FORWARDED is set) or + (req.kdc-options.ENC-TKT-IN-SKEY is set)) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.session := random_session_key(); + new_tkt.cname := req.cname; + new_tkt.crealm := req.crealm; + new_tkt.transited := empty_transited_field(); + + new_tkt.authtime := kdc_time; + + if (req.kdc-options.POSTDATED is set) then + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + set new_tkt.flags.INVALID; + new_tkt.starttime := req.from; + else + omit new_tkt.starttime; /* treated as authtime when + omitted */ + endif + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm); + + + +Kohl & Neuman [Page 93] + +RFC 1510 Kerberos September 1993 + + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till)) then + /* we set the RENEWABLE option for later processing */ + set req.kdc-options.RENEWABLE; + req.rtime := req.till; + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if (req.kdc-options.RENEWABLE is set) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm); + else + omit new_tkt.renew-till; /* only present if RENEWABLE */ + endif + + if (req.addresses) then + new_tkt.caddr := req.addresses; + else + omit new_tkt.caddr; + endif + + new_tkt.authorization_data := empty_authorization_data(); + + encode to-be-encrypted part of ticket into OCTET STRING; + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, server.p_kvno; + + + /* Start processing the response */ + + resp.pvno := 5; + resp.msg-type := KRB_AS_REP; + resp.cname := req.cname; + resp.crealm := req.realm; + resp.ticket := new_tkt; + + resp.key := new_tkt.session; + resp.last-req := fetch_last_request_info(client); + resp.nonce := req.nonce; + resp.key-expiration := client.expiration; + + + +Kohl & Neuman [Page 94] + +RFC 1510 Kerberos September 1993 + + + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + resp.realm := new_tkt.realm; + resp.sname := new_tkt.sname; + + resp.caddr := new_tkt.caddr; + + encode body of reply into OCTET STRING; + + resp.enc-part := encrypt OCTET STRING + using use_etype, client.key, client.p_kvno; + send(resp); + +A.3. KRB_AS_REP verification + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) + then set pa_enc_timestamp_required; + goto KRB_AS_REQ; + endif + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key */ + /* from the response immediately */ + + key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, + resp.padata); + unencrypted part of resp := decode of decrypt of resp.enc-part + using resp.enc-part.etype and key; + zero(key); + + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + if near(resp.princ_exp) then + + + +Kohl & Neuman [Page 95] + +RFC 1510 Kerberos September 1993 + + + print(warning message); + endif + save_for_later(ticket,session,client,server,times,flags); + +A.4. KRB_AS_REP and KRB_TGS_REP common checks + if (decryption_error() or + (req.cname != resp.cname) or + (req.realm != resp.crealm) or + (req.sname != resp.sname) or + (req.realm != resp.realm) or + (req.nonce != resp.nonce) or + (req.addresses != resp.caddr)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + /* make sure no flags are set that shouldn't be, and that */ + /* all that should be are set */ + if (!check_flags_for_compatability(req.kdc-options,resp.flags)) + then destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.from = 0) and + (resp.starttime is not within allowable skew)) then + destroy resp.key; + return KRB_AP_ERR_SKEW; + endif + if ((req.from != 0) and (req.from != resp.starttime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.till != 0) and (resp.endtime > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (req.rtime != 0) and (resp.renew-till > req.rtime)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + endif + if ((req.kdc-options.RENEWABLE-OK is set) and + (resp.flags.RENEWABLE) and + (req.till != 0) and + (resp.renew-till > req.till)) then + destroy resp.key; + return KRB_AP_ERR_MODIFIED; + + + +Kohl & Neuman [Page 96] + +RFC 1510 Kerberos September 1993 + + + endif + +A.5. KRB_TGS_REQ generation + /* Note that make_application_request might have to */ + /* recursivly call this routine to get the appropriate */ + /* ticket-granting ticket */ + + request.pvno := protocol version; /* pvno = 5 */ + request.msg-type := message type; /* type = KRB_TGS_REQ */ + + body.kdc-options := users's preferences; + /* If the TGT is not for the realm of the end-server */ + /* then the sname will be for a TGT for the end-realm */ + /* and the realm of the requested ticket (body.realm) */ + /* will be that of the TGS to which the TGT we are */ + /* sending applies */ + body.sname := service's name; + body.realm := service's realm; + + if (body.kdc-options.POSTDATED is set) then + body.from := requested starting time; + else + omit body.from; + endif + body.till := requested end time; + if (body.kdc-options.RENEWABLE is set) then + body.rtime := requested final renewal time; + endif + body.nonce := random_nonce(); + body.etype := requested etypes; + if (user supplied addresses) then + body.addresses := user's addresses; + else + omit body.addresses; + endif + + body.enc-authorization-data := user-supplied data; + if (body.kdc-options.ENC-TKT-IN-SKEY) then + body.additional-tickets_ticket := second TGT; + endif + + request.req-body := body; + check := generate_checksum (req.body,checksumtype); + + request.padata[0].padata-type := PA-TGS-REQ; + request.padata[0].padata-value := create a KRB_AP_REQ using + the TGT and checksum + + + + +Kohl & Neuman [Page 97] + +RFC 1510 Kerberos September 1993 + + + /* add in any other padata as required/supplied */ + + kerberos := lookup(name of local kerberose server (or servers)); + send(packet,kerberos); + + wait(for response); + if (timed_out) then + retry or use alternate server; + endif + +A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation + /* note that reading the application request requires first + determining the server for which a ticket was issued, and + choosing the correct key for decryption. The name of the + server appears in the plaintext part of the ticket. */ + + if (no KRB_AP_REQ in req.padata) then + error_out(KDC_ERR_PADATA_TYPE_NOSUPP); + endif + verify KRB_AP_REQ in req.padata; + + /* Note that the realm in which the Kerberos server is + operating is determined by the instance from the + ticket-granting ticket. The realm in the ticket-granting + ticket is the realm under which the ticket granting ticket was + issued. It is possible for a single Kerberos server to + support more than one realm. */ + + auth_hdr := KRB_AP_REQ; + tgt := auth_hdr.ticket; + + if (tgt.sname is not a TGT for local realm and is not + req.sname) then error_out(KRB_AP_ERR_NOT_US); + + realm := realm_tgt_is_for(tgt); + + decode remainder of request; + + if (auth_hdr.authenticator.cksum is missing) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (auth_hdr.authenticator.cksum type is not supported) then + error_out(KDC_ERR_SUMTYPE_NOSUPP); + endif + if (auth_hdr.authenticator.cksum is not both collision-proof + and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + + + +Kohl & Neuman [Page 98] + +RFC 1510 Kerberos September 1993 + + + set computed_checksum := checksum(req); + if (computed_checksum != auth_hdr.authenticatory.cksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + server := lookup(req.sname,realm); + + if (!server) then + if (is_foreign_tgt_name(server)) then + server := best_intermediate_tgs(server); + else + /* no server in Database */ + error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); + endif + endif + + session := generate_random_session_key(); + + + use_etype := first supported etype in req.etypes; + + if (no support for req.etypes) then + error_out(KDC_ERR_ETYPE_NOSUPP); + endif + + new_tkt.vno := ticket version; /* = 5 */ + new_tkt.sname := req.sname; + new_tkt.srealm := realm; + reset all flags in new_tkt.flags; + + /* It should be noted that local policy may affect the */ + /* processing of any of these flags. For example, some */ + /* realms may refuse to issue renewable tickets */ + + new_tkt.caddr := tgt.caddr; + resp.caddr := NULL; /* We only include this if they change */ + if (req.kdc-options.FORWARDABLE is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDABLE; + endif + if (req.kdc-options.FORWARDED is set) then + if (tgt.flags.FORWARDABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.FORWARDED; + new_tkt.caddr := req.addresses; + + + +Kohl & Neuman [Page 99] + +RFC 1510 Kerberos September 1993 + + + resp.caddr := req.addresses; + endif + if (tgt.flags.FORWARDED is set) then + set new_tkt.flags.FORWARDED; + endif + + if (req.kdc-options.PROXIABLE is set) then + if (tgt.flags.PROXIABLE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXIABLE; + endif + if (req.kdc-options.PROXY is set) then + if (tgt.flags.PROXIABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.PROXY; + new_tkt.caddr := req.addresses; + resp.caddr := req.addresses; + endif + + if (req.kdc-options.POSTDATE is set) then + if (tgt.flags.POSTDATE is reset) + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATE; + endif + if (req.kdc-options.POSTDATED is set) then + if (tgt.flags.POSTDATE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + set new_tkt.flags.POSTDATED; + set new_tkt.flags.INVALID; + if (against_postdate_policy(req.from)) then + error_out(KDC_ERR_POLICY); + endif + new_tkt.starttime := req.from; + endif + + + if (req.kdc-options.VALIDATE is set) then + if (tgt.flags.INVALID is reset) then + error_out(KDC_ERR_POLICY); + endif + if (tgt.starttime > kdc_time) then + error_out(KRB_AP_ERR_NYV); + endif + if (check_hot_list(tgt)) then + + + +Kohl & Neuman [Page 100] + +RFC 1510 Kerberos September 1993 + + + error_out(KRB_AP_ERR_REPEAT); + endif + tkt := tgt; + reset new_tkt.flags.INVALID; + endif + + if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, + and those already processed) is set) then + error_out(KDC_ERR_BADOPTION); + endif + + new_tkt.authtime := tgt.authtime; + + if (req.kdc-options.RENEW is set) then + /* Note that if the endtime has already passed, the ticket */ + /* would have been rejected in the initial authentication */ + /* stage, so there is no need to check again here */ + if (tgt.flags.RENEWABLE is reset) then + error_out(KDC_ERR_BADOPTION); + endif + if (tgt.renew-till >= kdc_time) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + tkt := tgt; + new_tkt.starttime := kdc_time; + old_life := tgt.endttime - tgt.starttime; + new_tkt.endtime := min(tgt.renew-till, + new_tkt.starttime + old_life); + else + new_tkt.starttime := kdc_time; + if (req.till = 0) then + till := infinity; + else + till := req.till; + endif + new_tkt.endtime := min(till, + new_tkt.starttime+client.max_life, + new_tkt.starttime+server.max_life, + new_tkt.starttime+max_life_for_realm, + tgt.endtime); + + if ((req.kdc-options.RENEWABLE-OK is set) and + (new_tkt.endtime < req.till) and + (tgt.flags.RENEWABLE is set) then + /* we set the RENEWABLE option for later */ + /* processing */ + set req.kdc-options.RENEWABLE; + req.rtime := min(req.till, tgt.renew-till); + + + +Kohl & Neuman [Page 101] + +RFC 1510 Kerberos September 1993 + + + endif + endif + + if (req.rtime = 0) then + rtime := infinity; + else + rtime := req.rtime; + endif + + if ((req.kdc-options.RENEWABLE is set) and + (tgt.flags.RENEWABLE is set)) then + set new_tkt.flags.RENEWABLE; + new_tkt.renew-till := min(rtime, + new_tkt.starttime+client.max_rlife, + new_tkt.starttime+server.max_rlife, + new_tkt.starttime+max_rlife_for_realm, + tgt.renew-till); + else + new_tkt.renew-till := OMIT; + /* leave the renew-till field out */ + endif + if (req.enc-authorization-data is present) then + decrypt req.enc-authorization-data + into decrypted_authorization_data + using auth_hdr.authenticator.subkey; + if (decrypt_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + endif + new_tkt.authorization_data := + req.auth_hdr.ticket.authorization_data + + decrypted_authorization_data; + + new_tkt.key := session; + new_tkt.crealm := tgt.crealm; + new_tkt.cname := req.auth_hdr.ticket.cname; + + if (realm_tgt_is_for(tgt) := tgt.realm) then + /* tgt issued by local realm */ + new_tkt.transited := tgt.transited; + else + /* was issued for this realm by some other realm */ + if (tgt.transited.tr-type not supported) then + error_out(KDC_ERR_TRTYPE_NOSUPP); + endif + new_tkt.transited + := compress_transited(tgt.transited + tgt.realm) + endif + + + +Kohl & Neuman [Page 102] + +RFC 1510 Kerberos September 1993 + + + encode encrypted part of new_tkt into OCTET STRING; + if (req.kdc-options.ENC-TKT-IN-SKEY is set) then + if (server not specified) then + server = req.second_ticket.client; + endif + if ((req.second_ticket is not a TGT) or + (req.second_ticket.client != server)) then + error_out(KDC_ERR_POLICY); + endif + + new_tkt.enc-part := encrypt OCTET STRING using + using etype_for_key(second-ticket.key), + second-ticket.key; + else + new_tkt.enc-part := encrypt OCTET STRING + using etype_for_key(server.key), server.key, + server.p_kvno; + endif + + resp.pvno := 5; + resp.msg-type := KRB_TGS_REP; + resp.crealm := tgt.crealm; + resp.cname := tgt.cname; + resp.ticket := new_tkt; + + resp.key := session; + resp.nonce := req.nonce; + resp.last-req := fetch_last_request_info(client); + resp.flags := new_tkt.flags; + + resp.authtime := new_tkt.authtime; + resp.starttime := new_tkt.starttime; + resp.endtime := new_tkt.endtime; + + omit resp.key-expiration; + + resp.sname := new_tkt.sname; + resp.realm := new_tkt.realm; + + if (new_tkt.flags.RENEWABLE) then + resp.renew-till := new_tkt.renew-till; + endif + + + encode body of reply into OCTET STRING; + + if (req.padata.authenticator.subkey) + resp.enc-part := encrypt OCTET STRING using use_etype, + + + +Kohl & Neuman [Page 103] + +RFC 1510 Kerberos September 1993 + + + req.padata.authenticator.subkey; + else resp.enc-part := encrypt OCTET STRING + using use_etype, tgt.key; + + send(resp); + +A.7. KRB_TGS_REP verification + decode response into resp; + + if (resp.msg-type = KRB_ERROR) then + process_error(resp); + return; + endif + + /* On error, discard the response, and zero the session key from + the response immediately */ + + if (req.padata.authenticator.subkey) + unencrypted part of resp := + decode of decrypt of resp.enc-part + using resp.enc-part.etype and subkey; + else unencrypted part of resp := + decode of decrypt of resp.enc-part + using resp.enc-part.etype and tgt's session key; + if (common_as_rep_tgs_rep_checks fail) then + destroy resp.key; + return error; + endif + + check authorization_data as necessary; + save_for_later(ticket,session,client,server,times,flags); + +A.8. Authenticator generation + body.authenticator-vno := authenticator vno; /* = 5 */ + body.cname, body.crealm := client name; + if (supplying checksum) then + body.cksum := checksum; + endif + get system_time; + body.ctime, body.cusec := system_time; + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + + +Kohl & Neuman [Page 104] + +RFC 1510 Kerberos September 1993 + + +A.9. KRB_AP_REQ generation + obtain ticket and session_key from cache; + + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REQ */ + + if (desired(MUTUAL_AUTHENTICATION)) then + set packet.ap-options.MUTUAL-REQUIRED; + else + reset packet.ap-options.MUTUAL-REQUIRED; + endif + if (using session key for ticket) then + set packet.ap-options.USE-SESSION-KEY; + else + reset packet.ap-options.USE-SESSION-KEY; + endif + packet.ticket := ticket; /* ticket */ + generate authenticator; + encode authenticator into OCTET STRING; + encrypt OCTET STRING into packet.authenticator + using session_key; + +A.10. KRB_AP_REQ verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REQ) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.ticket.tkt_vno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.ap_options.USE-SESSION-KEY is set) then + retrieve session key from ticket-granting ticket for + packet.ticket.{sname,srealm,enc-part.etype}; + else + retrieve service key for + packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; + endif + if (no_key_available) then + if (cannot_find_specified_skvno) then + error_out(KRB_AP_ERR_BADKEYVER); + else + error_out(KRB_AP_ERR_NOKEY); + endif + + + +Kohl & Neuman [Page 105] + +RFC 1510 Kerberos September 1993 + + + endif + decrypt packet.ticket.enc-part into decr_ticket + using retrieved key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + decrypt packet.authenticator into decr_authenticator + using decr_ticket.key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (decr_authenticator.{cname,crealm} != + decr_ticket.{cname,crealm}) then + error_out(KRB_AP_ERR_BADMATCH); + endif + if (decr_ticket.caddr is present) then + if (sender_address(packet) is not in decr_ticket.caddr) + then error_out(KRB_AP_ERR_BADADDR); + endif + elseif (application requires addresses) then + error_out(KRB_AP_ERR_BADADDR); + endif + if (not in_clock_skew(decr_authenticator.ctime, + decr_authenticator.cusec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) + then error_out(KRB_AP_ERR_REPEAT); + endif + save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); + get system_time; + if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or + (decr_ticket.flags.INVALID is set)) then + /* it hasn't yet become valid */ + error_out(KRB_AP_ERR_TKT_NYV); + endif + if (system_time-decr_ticket.endtime > CLOCK_SKEW) then + error_out(KRB_AP_ERR_TKT_EXPIRED); + endif + /* caller must check decr_ticket.flags for any pertinent */ + /* details */ + return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); + +A.11. KRB_AP_REP generation + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_AP_REP */ + body.ctime := packet.ctime; + body.cusec := packet.cusec; + + + +Kohl & Neuman [Page 106] + +RFC 1510 Kerberos September 1993 + + + if (selecting sub-session key) then + select sub-session key; + body.subkey := sub-session key; + endif + if (using sequence numbers) then + select initial sequence number; + body.seq-number := initial sequence; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part; + +A.12. KRB_AP_REP verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_AP_REP) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + cleartext := decrypt(packet.enc-part) + using ticket's session key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if (cleartext.ctime != authenticator.ctime) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.cusec != authenticator.cusec) then + error_out(KRB_AP_ERR_MUT_FAIL); + endif + if (cleartext.subkey is present) then + save cleartext.subkey for future use; + endif + if (cleartext.seq-number is present) then + save cleartext.seq-number for future verifications; + endif + return(AUTHENTICATION_SUCCEEDED); + +A.13. KRB_SAFE generation + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_SAFE */ + + + +Kohl & Neuman [Page 107] + +RFC 1510 Kerberos September 1993 + + + body.user-data := buffer; /* DATA */ + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + checksum.cksumtype := checksum type; + compute checksum over body; + checksum.checksum := checksum value; /* checksum.checksum */ + packet.cksum := checksum; + packet.safe-body := body; + +A.14. KRB_SAFE verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_SAFE) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + if (packet.checksum.cksumtype is not both collision-proof + and keyed) then + error_out(KRB_AP_ERR_INAPP_CKSUM); + endif + if (safe_priv_common_checks_ok(packet)) then + set computed_checksum := checksum(packet.body); + if (computed_checksum != packet.checksum) then + error_out(KRB_AP_ERR_MODIFIED); + endif + return (packet, PACKET_IS_GENUINE); + else + return common_checks_error; + endif + +A.15. KRB_SAFE and KRB_PRIV common checks + if (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + + + +Kohl & Neuman [Page 108] + +RFC 1510 Kerberos September 1993 + + + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + endif + if (((packet.timestamp is present) and + (not in_clock_skew(packet.timestamp,packet.usec))) or + (packet.timestamp is not present and timestamp expected)) + then error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) + then error_out(KRB_AP_ERR_REPEAT); + endif + if (((packet.seq-number is present) and + ((not in_sequence(packet.seq-number)))) or + (packet.seq-number is not present and sequence expected)) + then error_out(KRB_AP_ERR_BADORDER); + endif + if (packet.timestamp not present and + packet.seq-number not present) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + save_identifier(packet.{timestamp,usec,s-address}, + sender_principal(packet)); + + return PACKET_IS_OK; + +A.16. KRB_PRIV generation + collect user data in buffer; + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_PRIV */ + + packet.enc-part.etype := encryption type; + + body.user-data := buffer; + if (using timestamp) then + get system_time; + body.timestamp, body.usec := system_time; + endif + if (using sequence numbers) then + body.seq-number := sequence number; + endif + body.s-address := sender host addresses; + if (only one recipient) then + body.r-address := recipient host address; + endif + + + + +Kohl & Neuman [Page 109] + +RFC 1510 Kerberos September 1993 + + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher; + +A.17. KRB_PRIV verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_PRIV) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + + if (safe_priv_common_checks_ok(cleartext)) then + return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); + else + return common_checks_error; + endif + +A.18. KRB_CRED generation + invoke KRB_TGS; /* obtain tickets to be provided to peer */ + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_CRED */ + + for (tickets[n] in tickets to be forwarded) do + packet.tickets[n] = tickets[n].ticket; + done + + packet.enc-part.etype := encryption type; + + for (ticket[n] in tickets to be forwarded) do + body.ticket-info[n].key = tickets[n].session; + body.ticket-info[n].prealm = tickets[n].crealm; + body.ticket-info[n].pname = tickets[n].cname; + body.ticket-info[n].flags = tickets[n].flags; + body.ticket-info[n].authtime = tickets[n].authtime; + body.ticket-info[n].starttime = tickets[n].starttime; + body.ticket-info[n].endtime = tickets[n].endtime; + body.ticket-info[n].renew-till = tickets[n].renew-till; + + + +Kohl & Neuman [Page 110] + +RFC 1510 Kerberos September 1993 + + + body.ticket-info[n].srealm = tickets[n].srealm; + body.ticket-info[n].sname = tickets[n].sname; + body.ticket-info[n].caddr = tickets[n].caddr; + done + + get system_time; + body.timestamp, body.usec := system_time; + + if (using nonce) then + body.nonce := nonce; + endif + + if (using s-address) then + body.s-address := sender host addresses; + endif + if (limited recipients) then + body.r-address := recipient host address; + endif + + encode body into OCTET STRING; + + select encryption type; + encrypt OCTET STRING into packet.enc-part.cipher + using negotiated encryption key; + +A.19. KRB_CRED verification + receive packet; + if (packet.pvno != 5) then + either process using other protocol spec + or error_out(KRB_AP_ERR_BADVERSION); + endif + if (packet.msg-type != KRB_CRED) then + error_out(KRB_AP_ERR_MSG_TYPE); + endif + + cleartext := decrypt(packet.enc-part) using negotiated key; + if (decryption_error()) then + error_out(KRB_AP_ERR_BAD_INTEGRITY); + endif + if ((packet.r-address is present or required) and + (packet.s-address != O/S_sender(packet)) then + /* O/S report of sender not who claims to have sent it */ + error_out(KRB_AP_ERR_BADADDR); + endif + if ((packet.r-address is present) and + (packet.r-address != local_host_address)) then + /* was not sent to proper place */ + error_out(KRB_AP_ERR_BADADDR); + + + +Kohl & Neuman [Page 111] + +RFC 1510 Kerberos September 1993 + + + endif + if (not in_clock_skew(packet.timestamp,packet.usec)) then + error_out(KRB_AP_ERR_SKEW); + endif + if (repeated(packet.timestamp,packet.usec,packet.s-address)) + then error_out(KRB_AP_ERR_REPEAT); + endif + if (packet.nonce is required or present) and + (packet.nonce != expected-nonce) then + error_out(KRB_AP_ERR_MODIFIED); + endif + + for (ticket[n] in tickets that were forwarded) do + save_for_later(ticket[n],key[n],principal[n], + server[n],times[n],flags[n]); + return + +A.20. KRB_ERROR generation + + /* assemble packet: */ + packet.pvno := protocol version; /* 5 */ + packet.msg-type := message type; /* KRB_ERROR */ + + get system_time; + packet.stime, packet.susec := system_time; + packet.realm, packet.sname := server name; + + if (client time available) then + packet.ctime, packet.cusec := client_time; + endif + packet.error-code := error code; + if (client name available) then + packet.cname, packet.crealm := client name; + endif + if (error text available) then + packet.e-text := error text; + endif + if (error data available) then + packet.e-data := error data; + endif + + + + + + + + + + + +Kohl & Neuman [Page 112] +
\ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/rfc1750.txt b/crypto/heimdal/doc/standardisation/rfc1750.txt new file mode 100644 index 0000000..56d478c --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1750.txt @@ -0,0 +1,1683 @@ + + + + + + +Network Working Group D. Eastlake, 3rd +Request for Comments: 1750 DEC +Category: Informational S. Crocker + Cybercash + J. Schiller + MIT + December 1994 + + + Randomness Recommendations for Security + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +Abstract + + Security systems today are built on increasingly strong cryptographic + algorithms that foil pattern analysis attempts. However, the security + of these systems is dependent on generating secret quantities for + passwords, cryptographic keys, and similar quantities. The use of + pseudo-random processes to generate secret quantities can result in + pseudo-security. The sophisticated attacker of these security + systems may find it easier to reproduce the environment that produced + the secret quantities, searching the resulting small set of + possibilities, than to locate the quantities in the whole of the + number space. + + Choosing random quantities to foil a resourceful and motivated + adversary is surprisingly difficult. This paper points out many + pitfalls in using traditional pseudo-random number generation + techniques for choosing such quantities. It recommends the use of + truly random hardware techniques and shows that the existing hardware + on many systems can be used for this purpose. It provides + suggestions to ameliorate the problem when a hardware solution is not + available. And it gives examples of how large such quantities need + to be for some particular applications. + + + + + + + + + + + + +Eastlake, Crocker & Schiller [Page 1] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +Acknowledgements + + Comments on this document that have been incorporated were received + from (in alphabetic order) the following: + + David M. Balenson (TIS) + Don Coppersmith (IBM) + Don T. Davis (consultant) + Carl Ellison (Stratus) + Marc Horowitz (MIT) + Christian Huitema (INRIA) + Charlie Kaufman (IRIS) + Steve Kent (BBN) + Hal Murray (DEC) + Neil Haller (Bellcore) + Richard Pitkin (DEC) + Tim Redmond (TIS) + Doug Tygar (CMU) + +Table of Contents + + 1. Introduction........................................... 3 + 2. Requirements........................................... 4 + 3. Traditional Pseudo-Random Sequences.................... 5 + 4. Unpredictability....................................... 7 + 4.1 Problems with Clocks and Serial Numbers............... 7 + 4.2 Timing and Content of External Events................ 8 + 4.3 The Fallacy of Complex Manipulation.................. 8 + 4.4 The Fallacy of Selection from a Large Database....... 9 + 5. Hardware for Randomness............................... 10 + 5.1 Volume Required...................................... 10 + 5.2 Sensitivity to Skew.................................. 10 + 5.2.1 Using Stream Parity to De-Skew..................... 11 + 5.2.2 Using Transition Mappings to De-Skew............... 12 + 5.2.3 Using FFT to De-Skew............................... 13 + 5.2.4 Using Compression to De-Skew....................... 13 + 5.3 Existing Hardware Can Be Used For Randomness......... 14 + 5.3.1 Using Existing Sound/Video Input................... 14 + 5.3.2 Using Existing Disk Drives......................... 14 + 6. Recommended Non-Hardware Strategy..................... 14 + 6.1 Mixing Functions..................................... 15 + 6.1.1 A Trivial Mixing Function.......................... 15 + 6.1.2 Stronger Mixing Functions.......................... 16 + 6.1.3 Diff-Hellman as a Mixing Function.................. 17 + 6.1.4 Using a Mixing Function to Stretch Random Bits..... 17 + 6.1.5 Other Factors in Choosing a Mixing Function........ 18 + 6.2 Non-Hardware Sources of Randomness................... 19 + 6.3 Cryptographically Strong Sequences................... 19 + + + +Eastlake, Crocker & Schiller [Page 2] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + 6.3.1 Traditional Strong Sequences....................... 20 + 6.3.2 The Blum Blum Shub Sequence Generator.............. 21 + 7. Key Generation Standards.............................. 22 + 7.1 US DoD Recommendations for Password Generation....... 23 + 7.2 X9.17 Key Generation................................. 23 + 8. Examples of Randomness Required....................... 24 + 8.1 Password Generation................................. 24 + 8.2 A Very High Security Cryptographic Key............... 25 + 8.2.1 Effort per Key Trial............................... 25 + 8.2.2 Meet in the Middle Attacks......................... 26 + 8.2.3 Other Considerations............................... 26 + 9. Conclusion............................................ 27 + 10. Security Considerations.............................. 27 + References............................................... 28 + Authors' Addresses....................................... 30 + +1. Introduction + + Software cryptography is coming into wider use. Systems like + Kerberos, PEM, PGP, etc. are maturing and becoming a part of the + network landscape [PEM]. These systems provide substantial + protection against snooping and spoofing. However, there is a + potential flaw. At the heart of all cryptographic systems is the + generation of secret, unguessable (i.e., random) numbers. + + For the present, the lack of generally available facilities for + generating such unpredictable numbers is an open wound in the design + of cryptographic software. For the software developer who wants to + build a key or password generation procedure that runs on a wide + range of hardware, the only safe strategy so far has been to force + the local installation to supply a suitable routine to generate + random numbers. To say the least, this is an awkward, error-prone + and unpalatable solution. + + It is important to keep in mind that the requirement is for data that + an adversary has a very low probability of guessing or determining. + This will fail if pseudo-random data is used which only meets + traditional statistical tests for randomness or which is based on + limited range sources, such as clocks. Frequently such random + quantities are determinable by an adversary searching through an + embarrassingly small space of possibilities. + + This informational document suggests techniques for producing random + quantities that will be resistant to such attack. It recommends that + future systems include hardware random number generation or provide + access to existing hardware that can be used for this purpose. It + suggests methods for use if such hardware is not available. And it + gives some estimates of the number of random bits required for sample + + + +Eastlake, Crocker & Schiller [Page 3] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + applications. + +2. Requirements + + Probably the most commonly encountered randomness requirement today + is the user password. This is usually a simple character string. + Obviously, if a password can be guessed, it does not provide + security. (For re-usable passwords, it is desirable that users be + able to remember the password. This may make it advisable to use + pronounceable character strings or phrases composed on ordinary + words. But this only affects the format of the password information, + not the requirement that the password be very hard to guess.) + + Many other requirements come from the cryptographic arena. + Cryptographic techniques can be used to provide a variety of services + including confidentiality and authentication. Such services are + based on quantities, traditionally called "keys", that are unknown to + and unguessable by an adversary. + + In some cases, such as the use of symmetric encryption with the one + time pads [CRYPTO*] or the US Data Encryption Standard [DES], the + parties who wish to communicate confidentially and/or with + authentication must all know the same secret key. In other cases, + using what are called asymmetric or "public key" cryptographic + techniques, keys come in pairs. One key of the pair is private and + must be kept secret by one party, the other is public and can be + published to the world. It is computationally infeasible to + determine the private key from the public key [ASYMMETRIC, CRYPTO*]. + + The frequency and volume of the requirement for random quantities + differs greatly for different cryptographic systems. Using pure RSA + [CRYPTO*], random quantities are required when the key pair is + generated, but thereafter any number of messages can be signed + without any further need for randomness. The public key Digital + Signature Algorithm that has been proposed by the US National + Institute of Standards and Technology (NIST) requires good random + numbers for each signature. And encrypting with a one time pad, in + principle the strongest possible encryption technique, requires a + volume of randomness equal to all the messages to be processed. + + In most of these cases, an adversary can try to determine the + "secret" key by trial and error. (This is possible as long as the + key is enough smaller than the message that the correct key can be + uniquely identified.) The probability of an adversary succeeding at + this must be made acceptably low, depending on the particular + application. The size of the space the adversary must search is + related to the amount of key "information" present in the information + theoretic sense [SHANNON]. This depends on the number of different + + + +Eastlake, Crocker & Schiller [Page 4] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + secret values possible and the probability of each value as follows: + + ----- + \ + Bits-of-info = \ - p * log ( p ) + / i 2 i + / + ----- + + where i varies from 1 to the number of possible secret values and p + sub i is the probability of the value numbered i. (Since p sub i is + less than one, the log will be negative so each term in the sum will + be non-negative.) + + If there are 2^n different values of equal probability, then n bits + of information are present and an adversary would, on the average, + have to try half of the values, or 2^(n-1) , before guessing the + secret quantity. If the probability of different values is unequal, + then there is less information present and fewer guesses will, on + average, be required by an adversary. In particular, any values that + the adversary can know are impossible, or are of low probability, can + be initially ignored by an adversary, who will search through the + more probable values first. + + For example, consider a cryptographic system that uses 56 bit keys. + If these 56 bit keys are derived by using a fixed pseudo-random + number generator that is seeded with an 8 bit seed, then an adversary + needs to search through only 256 keys (by running the pseudo-random + number generator with every possible seed), not the 2^56 keys that + may at first appear to be the case. Only 8 bits of "information" are + in these 56 bit keys. + +3. Traditional Pseudo-Random Sequences + + Most traditional sources of random numbers use deterministic sources + of "pseudo-random" numbers. These typically start with a "seed" + quantity and use numeric or logical operations to produce a sequence + of values. + + [KNUTH] has a classic exposition on pseudo-random numbers. + Applications he mentions are simulation of natural phenomena, + sampling, numerical analysis, testing computer programs, decision + making, and games. None of these have the same characteristics as + the sort of security uses we are talking about. Only in the last two + could there be an adversary trying to find the random quantity. + However, in these cases, the adversary normally has only a single + chance to use a guessed value. In guessing passwords or attempting + to break an encryption scheme, the adversary normally has many, + + + +Eastlake, Crocker & Schiller [Page 5] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + perhaps unlimited, chances at guessing the correct value and should + be assumed to be aided by a computer. + + For testing the "randomness" of numbers, Knuth suggests a variety of + measures including statistical and spectral. These tests check + things like autocorrelation between different parts of a "random" + sequence or distribution of its values. They could be met by a + constant stored random sequence, such as the "random" sequence + printed in the CRC Standard Mathematical Tables [CRC]. + + A typical pseudo-random number generation technique, known as a + linear congruence pseudo-random number generator, is modular + arithmetic where the N+1th value is calculated from the Nth value by + + V = ( V * a + b )(Mod c) + N+1 N + + The above technique has a strong relationship to linear shift + register pseudo-random number generators, which are well understood + cryptographically [SHIFT*]. In such generators bits are introduced + at one end of a shift register as the Exclusive Or (binary sum + without carry) of bits from selected fixed taps into the register. + + For example: + + +----+ +----+ +----+ +----+ + | B | <-- | B | <-- | B | <-- . . . . . . <-- | B | <-+ + | 0 | | 1 | | 2 | | n | | + +----+ +----+ +----+ +----+ | + | | | | + | | V +-----+ + | V +----------------> | | + V +-----------------------------> | XOR | + +---------------------------------------------------> | | + +-----+ + + + V = ( ( V * 2 ) + B .xor. B ... )(Mod 2^n) + N+1 N 0 2 + + The goodness of traditional pseudo-random number generator algorithms + is measured by statistical tests on such sequences. Carefully chosen + values of the initial V and a, b, and c or the placement of shift + register tap in the above simple processes can produce excellent + statistics. + + + + + + +Eastlake, Crocker & Schiller [Page 6] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + These sequences may be adequate in simulations (Monte Carlo + experiments) as long as the sequence is orthogonal to the structure + of the space being explored. Even there, subtle patterns may cause + problems. However, such sequences are clearly bad for use in + security applications. They are fully predictable if the initial + state is known. Depending on the form of the pseudo-random number + generator, the sequence may be determinable from observation of a + short portion of the sequence [CRYPTO*, STERN]. For example, with + the generators above, one can determine V(n+1) given knowledge of + V(n). In fact, it has been shown that with these techniques, even if + only one bit of the pseudo-random values is released, the seed can be + determined from short sequences. + + Not only have linear congruent generators been broken, but techniques + are now known for breaking all polynomial congruent generators + [KRAWCZYK]. + +4. Unpredictability + + Randomness in the traditional sense described in section 3 is NOT the + same as the unpredictability required for security use. + + For example, use of a widely available constant sequence, such as + that from the CRC tables, is very weak against an adversary. Once + they learn of or guess it, they can easily break all security, future + and past, based on the sequence [CRC]. Yet the statistical + properties of these tables are good. + + The following sections describe the limitations of some randomness + generation techniques and sources. + +4.1 Problems with Clocks and Serial Numbers + + Computer clocks, or similar operating system or hardware values, + provide significantly fewer real bits of unpredictability than might + appear from their specifications. + + Tests have been done on clocks on numerous systems and it was found + that their behavior can vary widely and in unexpected ways. One + version of an operating system running on one set of hardware may + actually provide, say, microsecond resolution in a clock while a + different configuration of the "same" system may always provide the + same lower bits and only count in the upper bits at much lower + resolution. This means that successive reads on the clock may + produce identical values even if enough time has passed that the + value "should" change based on the nominal clock resolution. There + are also cases where frequently reading a clock can produce + artificial sequential values because of extra code that checks for + + + +Eastlake, Crocker & Schiller [Page 7] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + the clock being unchanged between two reads and increases it by one! + Designing portable application code to generate unpredictable numbers + based on such system clocks is particularly challenging because the + system designer does not always know the properties of the system + clocks that the code will execute on. + + Use of a hardware serial number such as an Ethernet address may also + provide fewer bits of uniqueness than one would guess. Such + quantities are usually heavily structured and subfields may have only + a limited range of possible values or values easily guessable based + on approximate date of manufacture or other data. For example, it is + likely that most of the Ethernet cards installed on Digital Equipment + Corporation (DEC) hardware within DEC were manufactured by DEC + itself, which significantly limits the range of built in addresses. + + Problems such as those described above related to clocks and serial + numbers make code to produce unpredictable quantities difficult if + the code is to be ported across a variety of computer platforms and + systems. + +4.2 Timing and Content of External Events + + It is possible to measure the timing and content of mouse movement, + key strokes, and similar user events. This is a reasonable source of + unguessable data with some qualifications. On some machines, inputs + such as key strokes are buffered. Even though the user's inter- + keystroke timing may have sufficient variation and unpredictability, + there might not be an easy way to access that variation. Another + problem is that no standard method exists to sample timing details. + This makes it hard to build standard software intended for + distribution to a large range of machines based on this technique. + + The amount of mouse movement or the keys actually hit are usually + easier to access than timings but may yield less unpredictability as + the user may provide highly repetitive input. + + Other external events, such as network packet arrival times, can also + be used with care. In particular, the possibility of manipulation of + such times by an adversary must be considered. + +4.3 The Fallacy of Complex Manipulation + + One strategy which may give a misleading appearance of + unpredictability is to take a very complex algorithm (or an excellent + traditional pseudo-random number generator with good statistical + properties) and calculate a cryptographic key by starting with the + current value of a computer system clock as the seed. An adversary + who knew roughly when the generator was started would have a + + + +Eastlake, Crocker & Schiller [Page 8] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + relatively small number of seed values to test as they would know + likely values of the system clock. Large numbers of pseudo-random + bits could be generated but the search space an adversary would need + to check could be quite small. + + Thus very strong and/or complex manipulation of data will not help if + the adversary can learn what the manipulation is and there is not + enough unpredictability in the starting seed value. Even if they can + not learn what the manipulation is, they may be able to use the + limited number of results stemming from a limited number of seed + values to defeat security. + + Another serious strategy error is to assume that a very complex + pseudo-random number generation algorithm will produce strong random + numbers when there has been no theory behind or analysis of the + algorithm. There is a excellent example of this fallacy right near + the beginning of chapter 3 in [KNUTH] where the author describes a + complex algorithm. It was intended that the machine language program + corresponding to the algorithm would be so complicated that a person + trying to read the code without comments wouldn't know what the + program was doing. Unfortunately, actual use of this algorithm + showed that it almost immediately converged to a single repeated + value in one case and a small cycle of values in another case. + + Not only does complex manipulation not help you if you have a limited + range of seeds but blindly chosen complex manipulation can destroy + the randomness in a good seed! + +4.4 The Fallacy of Selection from a Large Database + + Another strategy that can give a misleading appearance of + unpredictability is selection of a quantity randomly from a database + and assume that its strength is related to the total number of bits + in the database. For example, typical USENET servers as of this date + process over 35 megabytes of information per day. Assume a random + quantity was selected by fetching 32 bytes of data from a random + starting point in this data. This does not yield 32*8 = 256 bits + worth of unguessability. Even after allowing that much of the data + is human language and probably has more like 2 or 3 bits of + information per byte, it doesn't yield 32*2.5 = 80 bits of + unguessability. For an adversary with access to the same 35 + megabytes the unguessability rests only on the starting point of the + selection. That is, at best, about 25 bits of unguessability in this + case. + + The same argument applies to selecting sequences from the data on a + CD ROM or Audio CD recording or any other large public database. If + the adversary has access to the same database, this "selection from a + + + +Eastlake, Crocker & Schiller [Page 9] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + large volume of data" step buys very little. However, if a selection + can be made from data to which the adversary has no access, such as + system buffers on an active multi-user system, it may be of some + help. + +5. Hardware for Randomness + + Is there any hope for strong portable randomness in the future? + There might be. All that's needed is a physical source of + unpredictable numbers. + + A thermal noise or radioactive decay source and a fast, free-running + oscillator would do the trick directly [GIFFORD]. This is a trivial + amount of hardware, and could easily be included as a standard part + of a computer system's architecture. Furthermore, any system with a + spinning disk or the like has an adequate source of randomness + [DAVIS]. All that's needed is the common perception among computer + vendors that this small additional hardware and the software to + access it is necessary and useful. + +5.1 Volume Required + + How much unpredictability is needed? Is it possible to quantify the + requirement in, say, number of random bits per second? + + The answer is not very much is needed. For DES, the key is 56 bits + and, as we show in an example in Section 8, even the highest security + system is unlikely to require a keying material of over 200 bits. If + a series of keys are needed, it can be generated from a strong random + seed using a cryptographically strong sequence as explained in + Section 6.3. A few hundred random bits generated once a day would be + enough using such techniques. Even if the random bits are generated + as slowly as one per second and it is not possible to overlap the + generation process, it should be tolerable in high security + applications to wait 200 seconds occasionally. + + These numbers are trivial to achieve. It could be done by a person + repeatedly tossing a coin. Almost any hardware process is likely to + be much faster. + +5.2 Sensitivity to Skew + + Is there any specific requirement on the shape of the distribution of + the random numbers? The good news is the distribution need not be + uniform. All that is needed is a conservative estimate of how non- + uniform it is to bound performance. Two simple techniques to de-skew + the bit stream are given below and stronger techniques are mentioned + in Section 6.1.2 below. + + + +Eastlake, Crocker & Schiller [Page 10] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +5.2.1 Using Stream Parity to De-Skew + + Consider taking a sufficiently long string of bits and map the string + to "zero" or "one". The mapping will not yield a perfectly uniform + distribution, but it can be as close as desired. One mapping that + serves the purpose is to take the parity of the string. This has the + advantages that it is robust across all degrees of skew up to the + estimated maximum skew and is absolutely trivial to implement in + hardware. + + The following analysis gives the number of bits that must be sampled: + + Suppose the ratio of ones to zeros is 0.5 + e : 0.5 - e, where e is + between 0 and 0.5 and is a measure of the "eccentricity" of the + distribution. Consider the distribution of the parity function of N + bit samples. The probabilities that the parity will be one or zero + will be the sum of the odd or even terms in the binomial expansion of + (p + q)^N, where p = 0.5 + e, the probability of a one, and q = 0.5 - + e, the probability of a zero. + + These sums can be computed easily as + + N N + 1/2 * ( ( p + q ) + ( p - q ) ) + and + N N + 1/2 * ( ( p + q ) - ( p - q ) ). + + (Which one corresponds to the probability the parity will be 1 + depends on whether N is odd or even.) + + Since p + q = 1 and p - q = 2e, these expressions reduce to + + N + 1/2 * [1 + (2e) ] + and + N + 1/2 * [1 - (2e) ]. + + Neither of these will ever be exactly 0.5 unless e is zero, but we + can bring them arbitrarily close to 0.5. If we want the + probabilities to be within some delta d of 0.5, i.e. then + + N + ( 0.5 + ( 0.5 * (2e) ) ) < 0.5 + d. + + + + + + +Eastlake, Crocker & Schiller [Page 11] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + Solving for N yields N > log(2d)/log(2e). (Note that 2e is less than + 1, so its log is negative. Division by a negative number reverses + the sense of an inequality.) + + The following table gives the length of the string which must be + sampled for various degrees of skew in order to come within 0.001 of + a 50/50 distribution. + + +---------+--------+-------+ + | Prob(1) | e | N | + +---------+--------+-------+ + | 0.5 | 0.00 | 1 | + | 0.6 | 0.10 | 4 | + | 0.7 | 0.20 | 7 | + | 0.8 | 0.30 | 13 | + | 0.9 | 0.40 | 28 | + | 0.95 | 0.45 | 59 | + | 0.99 | 0.49 | 308 | + +---------+--------+-------+ + + The last entry shows that even if the distribution is skewed 99% in + favor of ones, the parity of a string of 308 samples will be within + 0.001 of a 50/50 distribution. + +5.2.2 Using Transition Mappings to De-Skew + + Another technique, originally due to von Neumann [VON NEUMANN], is to + examine a bit stream as a sequence of non-overlapping pairs. You + could then discard any 00 or 11 pairs found, interpret 01 as a 0 and + 10 as a 1. Assume the probability of a 1 is 0.5+e and the + probability of a 0 is 0.5-e where e is the eccentricity of the source + and described in the previous section. Then the probability of each + pair is as follows: + + +------+-----------------------------------------+ + | pair | probability | + +------+-----------------------------------------+ + | 00 | (0.5 - e)^2 = 0.25 - e + e^2 | + | 01 | (0.5 - e)*(0.5 + e) = 0.25 - e^2 | + | 10 | (0.5 + e)*(0.5 - e) = 0.25 - e^2 | + | 11 | (0.5 + e)^2 = 0.25 + e + e^2 | + +------+-----------------------------------------+ + + This technique will completely eliminate any bias but at the expense + of taking an indeterminate number of input bits for any particular + desired number of output bits. The probability of any particular + pair being discarded is 0.5 + 2e^2 so the expected number of input + bits to produce X output bits is X/(0.25 - e^2). + + + +Eastlake, Crocker & Schiller [Page 12] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + This technique assumes that the bits are from a stream where each bit + has the same probability of being a 0 or 1 as any other bit in the + stream and that bits are not correlated, i.e., that the bits are + identical independent distributions. If alternate bits were from two + correlated sources, for example, the above analysis breaks down. + + The above technique also provides another illustration of how a + simple statistical analysis can mislead if one is not always on the + lookout for patterns that could be exploited by an adversary. If the + algorithm were mis-read slightly so that overlapping successive bits + pairs were used instead of non-overlapping pairs, the statistical + analysis given is the same; however, instead of provided an unbiased + uncorrelated series of random 1's and 0's, it instead produces a + totally predictable sequence of exactly alternating 1's and 0's. + +5.2.3 Using FFT to De-Skew + + When real world data consists of strongly biased or correlated bits, + it may still contain useful amounts of randomness. This randomness + can be extracted through use of the discrete Fourier transform or its + optimized variant, the FFT. + + Using the Fourier transform of the data, strong correlations can be + discarded. If adequate data is processed and remaining correlations + decay, spectral lines approaching statistical independence and + normally distributed randomness can be produced [BRILLINGER]. + +5.2.4 Using Compression to De-Skew + + Reversible compression techniques also provide a crude method of de- + skewing a skewed bit stream. This follows directly from the + definition of reversible compression and the formula in Section 2 + above for the amount of information in a sequence. Since the + compression is reversible, the same amount of information must be + present in the shorter output than was present in the longer input. + By the Shannon information equation, this is only possible if, on + average, the probabilities of the different shorter sequences are + more uniformly distributed than were the probabilities of the longer + sequences. Thus the shorter sequences are de-skewed relative to the + input. + + However, many compression techniques add a somewhat predicatable + preface to their output stream and may insert such a sequence again + periodically in their output or otherwise introduce subtle patterns + of their own. They should be considered only a rough technique + compared with those described above or in Section 6.1.2. At a + minimum, the beginning of the compressed sequence should be skipped + and only later bits used for applications requiring random bits. + + + +Eastlake, Crocker & Schiller [Page 13] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +5.3 Existing Hardware Can Be Used For Randomness + + As described below, many computers come with hardware that can, with + care, be used to generate truly random quantities. + +5.3.1 Using Existing Sound/Video Input + + Increasingly computers are being built with inputs that digitize some + real world analog source, such as sound from a microphone or video + input from a camera. Under appropriate circumstances, such input can + provide reasonably high quality random bits. The "input" from a + sound digitizer with no source plugged in or a camera with the lens + cap on, if the system has enough gain to detect anything, is + essentially thermal noise. + + For example, on a SPARCstation, one can read from the /dev/audio + device with nothing plugged into the microphone jack. Such data is + essentially random noise although it should not be trusted without + some checking in case of hardware failure. It will, in any case, + need to be de-skewed as described elsewhere. + + Combining this with compression to de-skew one can, in UNIXese, + generate a huge amount of medium quality random data by doing + + cat /dev/audio | compress - >random-bits-file + +5.3.2 Using Existing Disk Drives + + Disk drives have small random fluctuations in their rotational speed + due to chaotic air turbulence [DAVIS]. By adding low level disk seek + time instrumentation to a system, a series of measurements can be + obtained that include this randomness. Such data is usually highly + correlated so that significant processing is needed, including FFT + (see section 5.2.3). Nevertheless experimentation has shown that, + with such processing, disk drives easily produce 100 bits a minute or + more of excellent random data. + + Partly offsetting this need for processing is the fact that disk + drive failure will normally be rapidly noticed. Thus, problems with + this method of random number generation due to hardware failure are + very unlikely. + +6. Recommended Non-Hardware Strategy + + What is the best overall strategy for meeting the requirement for + unguessable random numbers in the absence of a reliable hardware + source? It is to obtain random input from a large number of + uncorrelated sources and to mix them with a strong mixing function. + + + +Eastlake, Crocker & Schiller [Page 14] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + Such a function will preserve the randomness present in any of the + sources even if other quantities being combined are fixed or easily + guessable. This may be advisable even with a good hardware source as + hardware can also fail, though this should be weighed against any + increase in the chance of overall failure due to added software + complexity. + +6.1 Mixing Functions + + A strong mixing function is one which combines two or more inputs and + produces an output where each output bit is a different complex non- + linear function of all the input bits. On average, changing any + input bit will change about half the output bits. But because the + relationship is complex and non-linear, no particular output bit is + guaranteed to change when any particular input bit is changed. + + Consider the problem of converting a stream of bits that is skewed + towards 0 or 1 to a shorter stream which is more random, as discussed + in Section 5.2 above. This is simply another case where a strong + mixing function is desired, mixing the input bits to produce a + smaller number of output bits. The technique given in Section 5.2.1 + of using the parity of a number of bits is simply the result of + successively Exclusive Or'ing them which is examined as a trivial + mixing function immediately below. Use of stronger mixing functions + to extract more of the randomness in a stream of skewed bits is + examined in Section 6.1.2. + +6.1.1 A Trivial Mixing Function + + A trivial example for single bit inputs is the Exclusive Or function, + which is equivalent to addition without carry, as show in the table + below. This is a degenerate case in which the one output bit always + changes for a change in either input bit. But, despite its + simplicity, it will still provide a useful illustration. + + +-----------+-----------+----------+ + | input 1 | input 2 | output | + +-----------+-----------+----------+ + | 0 | 0 | 0 | + | 0 | 1 | 1 | + | 1 | 0 | 1 | + | 1 | 1 | 0 | + +-----------+-----------+----------+ + + If inputs 1 and 2 are uncorrelated and combined in this fashion then + the output will be an even better (less skewed) random bit than the + inputs. If we assume an "eccentricity" e as defined in Section 5.2 + above, then the output eccentricity relates to the input eccentricity + + + +Eastlake, Crocker & Schiller [Page 15] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + as follows: + + e = 2 * e * e + output input 1 input 2 + + Since e is never greater than 1/2, the eccentricity is always + improved except in the case where at least one input is a totally + skewed constant. This is illustrated in the following table where + the top and left side values are the two input eccentricities and the + entries are the output eccentricity: + + +--------+--------+--------+--------+--------+--------+--------+ + | e | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | + +--------+--------+--------+--------+--------+--------+--------+ + | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | + | 0.10 | 0.00 | 0.02 | 0.04 | 0.06 | 0.08 | 0.10 | + | 0.20 | 0.00 | 0.04 | 0.08 | 0.12 | 0.16 | 0.20 | + | 0.30 | 0.00 | 0.06 | 0.12 | 0.18 | 0.24 | 0.30 | + | 0.40 | 0.00 | 0.08 | 0.16 | 0.24 | 0.32 | 0.40 | + | 0.50 | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | + +--------+--------+--------+--------+--------+--------+--------+ + + However, keep in mind that the above calculations assume that the + inputs are not correlated. If the inputs were, say, the parity of + the number of minutes from midnight on two clocks accurate to a few + seconds, then each might appear random if sampled at random intervals + much longer than a minute. Yet if they were both sampled and + combined with xor, the result would be zero most of the time. + +6.1.2 Stronger Mixing Functions + + The US Government Data Encryption Standard [DES] is an example of a + strong mixing function for multiple bit quantities. It takes up to + 120 bits of input (64 bits of "data" and 56 bits of "key") and + produces 64 bits of output each of which is dependent on a complex + non-linear function of all input bits. Other strong encryption + functions with this characteristic can also be used by considering + them to mix all of their key and data input bits. + + Another good family of mixing functions are the "message digest" or + hashing functions such as The US Government Secure Hash Standard + [SHS] and the MD2, MD4, MD5 [MD2, MD4, MD5] series. These functions + all take an arbitrary amount of input and produce an output mixing + all the input bits. The MD* series produce 128 bits of output and SHS + produces 160 bits. + + + + + + +Eastlake, Crocker & Schiller [Page 16] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + Although the message digest functions are designed for variable + amounts of input, DES and other encryption functions can also be used + to combine any number of inputs. If 64 bits of output is adequate, + the inputs can be packed into a 64 bit data quantity and successive + 56 bit keys, padding with zeros if needed, which are then used to + successively encrypt using DES in Electronic Codebook Mode [DES + MODES]. If more than 64 bits of output are needed, use more complex + mixing. For example, if inputs are packed into three quantities, A, + B, and C, use DES to encrypt A with B as a key and then with C as a + key to produce the 1st part of the output, then encrypt B with C and + then A for more output and, if necessary, encrypt C with A and then B + for yet more output. Still more output can be produced by reversing + the order of the keys given above to stretch things. The same can be + done with the hash functions by hashing various subsets of the input + data to produce multiple outputs. But keep in mind that it is + impossible to get more bits of "randomness" out than are put in. + + An example of using a strong mixing function would be to reconsider + the case of a string of 308 bits each of which is biased 99% towards + zero. The parity technique given in Section 5.2.1 above reduced this + to one bit with only a 1/1000 deviance from being equally likely a + zero or one. But, applying the equation for information given in + Section 2, this 308 bit sequence has 5 bits of information in it. + Thus hashing it with SHS or MD5 and taking the bottom 5 bits of the + result would yield 5 unbiased random bits as opposed to the single + bit given by calculating the parity of the string. + +6.1.3 Diffie-Hellman as a Mixing Function + + Diffie-Hellman exponential key exchange is a technique that yields a + shared secret between two parties that can be made computationally + infeasible for a third party to determine even if they can observe + all the messages between the two communicating parties. This shared + secret is a mixture of initial quantities generated by each of them + [D-H]. If these initial quantities are random, then the shared + secret contains the combined randomness of them both, assuming they + are uncorrelated. + +6.1.4 Using a Mixing Function to Stretch Random Bits + + While it is not necessary for a mixing function to produce the same + or fewer bits than its inputs, mixing bits cannot "stretch" the + amount of random unpredictability present in the inputs. Thus four + inputs of 32 bits each where there is 12 bits worth of + unpredicatability (such as 4,096 equally probable values) in each + input cannot produce more than 48 bits worth of unpredictable output. + The output can be expanded to hundreds or thousands of bits by, for + example, mixing with successive integers, but the clever adversary's + + + +Eastlake, Crocker & Schiller [Page 17] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + search space is still 2^48 possibilities. Furthermore, mixing to + fewer bits than are input will tend to strengthen the randomness of + the output the way using Exclusive Or to produce one bit from two did + above. + + The last table in Section 6.1.1 shows that mixing a random bit with a + constant bit with Exclusive Or will produce a random bit. While this + is true, it does not provide a way to "stretch" one random bit into + more than one. If, for example, a random bit is mixed with a 0 and + then with a 1, this produces a two bit sequence but it will always be + either 01 or 10. Since there are only two possible values, there is + still only the one bit of original randomness. + +6.1.5 Other Factors in Choosing a Mixing Function + + For local use, DES has the advantages that it has been widely tested + for flaws, is widely documented, and is widely implemented with + hardware and software implementations available all over the world + including source code available by anonymous FTP. The SHS and MD* + family are younger algorithms which have been less tested but there + is no particular reason to believe they are flawed. Both MD5 and SHS + were derived from the earlier MD4 algorithm. They all have source + code available by anonymous FTP [SHS, MD2, MD4, MD5]. + + DES and SHS have been vouched for the the US National Security Agency + (NSA) on the basis of criteria that primarily remain secret. While + this is the cause of much speculation and doubt, investigation of DES + over the years has indicated that NSA involvement in modifications to + its design, which originated with IBM, was primarily to strengthen + it. No concealed or special weakness has been found in DES. It is + almost certain that the NSA modification to MD4 to produce the SHS + similarly strengthened the algorithm, possibly against threats not + yet known in the public cryptographic community. + + DES, SHS, MD4, and MD5 are royalty free for all purposes. MD2 has + been freely licensed only for non-profit use in connection with + Privacy Enhanced Mail [PEM]. Between the MD* algorithms, some people + believe that, as with "Goldilocks and the Three Bears", MD2 is strong + but too slow, MD4 is fast but too weak, and MD5 is just right. + + Another advantage of the MD* or similar hashing algorithms over + encryption algorithms is that they are not subject to the same + regulations imposed by the US Government prohibiting the unlicensed + export or import of encryption/decryption software and hardware. The + same should be true of DES rigged to produce an irreversible hash + code but most DES packages are oriented to reversible encryption. + + + + + +Eastlake, Crocker & Schiller [Page 18] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +6.2 Non-Hardware Sources of Randomness + + The best source of input for mixing would be a hardware randomness + such as disk drive timing affected by air turbulence, audio input + with thermal noise, or radioactive decay. However, if that is not + available there are other possibilities. These include system + clocks, system or input/output buffers, user/system/hardware/network + serial numbers and/or addresses and timing, and user input. + Unfortunately, any of these sources can produce limited or + predicatable values under some circumstances. + + Some of the sources listed above would be quite strong on multi-user + systems where, in essence, each user of the system is a source of + randomness. However, on a small single user system, such as a + typical IBM PC or Apple Macintosh, it might be possible for an + adversary to assemble a similar configuration. This could give the + adversary inputs to the mixing process that were sufficiently + correlated to those used originally as to make exhaustive search + practical. + + The use of multiple random inputs with a strong mixing function is + recommended and can overcome weakness in any particular input. For + example, the timing and content of requested "random" user keystrokes + can yield hundreds of random bits but conservative assumptions need + to be made. For example, assuming a few bits of randomness if the + inter-keystroke interval is unique in the sequence up to that point + and a similar assumption if the key hit is unique but assuming that + no bits of randomness are present in the initial key value or if the + timing or key value duplicate previous values. The results of mixing + these timings and characters typed could be further combined with + clock values and other inputs. + + This strategy may make practical portable code to produce good random + numbers for security even if some of the inputs are very weak on some + of the target systems. However, it may still fail against a high + grade attack on small single user systems, especially if the + adversary has ever been able to observe the generation process in the + past. A hardware based random source is still preferable. + +6.3 Cryptographically Strong Sequences + + In cases where a series of random quantities must be generated, an + adversary may learn some values in the sequence. In general, they + should not be able to predict other values from the ones that they + know. + + + + + + +Eastlake, Crocker & Schiller [Page 19] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + The correct technique is to start with a strong random seed, take + cryptographically strong steps from that seed [CRYPTO2, CRYPTO3], and + do not reveal the complete state of the generator in the sequence + elements. If each value in the sequence can be calculated in a fixed + way from the previous value, then when any value is compromised, all + future values can be determined. This would be the case, for + example, if each value were a constant function of the previously + used values, even if the function were a very strong, non-invertible + message digest function. + + It should be noted that if your technique for generating a sequence + of key values is fast enough, it can trivially be used as the basis + for a confidentiality system. If two parties use the same sequence + generating technique and start with the same seed material, they will + generate identical sequences. These could, for example, be xor'ed at + one end with data being send, encrypting it, and xor'ed with this + data as received, decrypting it due to the reversible properties of + the xor operation. + +6.3.1 Traditional Strong Sequences + + A traditional way to achieve a strong sequence has been to have the + values be produced by hashing the quantities produced by + concatenating the seed with successive integers or the like and then + mask the values obtained so as to limit the amount of generator state + available to the adversary. + + It may also be possible to use an "encryption" algorithm with a + random key and seed value to encrypt and feedback some or all of the + output encrypted value into the value to be encrypted for the next + iteration. Appropriate feedback techniques will usually be + recommended with the encryption algorithm. An example is shown below + where shifting and masking are used to combine the cypher output + feedback. This type of feedback is recommended by the US Government + in connection with DES [DES MODES]. + + + + + + + + + + + + + + + + +Eastlake, Crocker & Schiller [Page 20] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + +---------------+ + | V | + | | n | + +--+------------+ + | | +---------+ + | +---------> | | +-----+ + +--+ | Encrypt | <--- | Key | + | +-------- | | +-----+ + | | +---------+ + V V + +------------+--+ + | V | | + | n+1 | + +---------------+ + + Note that if a shift of one is used, this is the same as the shift + register technique described in Section 3 above but with the all + important difference that the feedback is determined by a complex + non-linear function of all bits rather than a simple linear or + polynomial combination of output from a few bit position taps. + + It has been shown by Donald W. Davies that this sort of shifted + partial output feedback significantly weakens an algorithm compared + will feeding all of the output bits back as input. In particular, + for DES, repeated encrypting a full 64 bit quantity will give an + expected repeat in about 2^63 iterations. Feeding back anything less + than 64 (and more than 0) bits will give an expected repeat in + between 2**31 and 2**32 iterations! + + To predict values of a sequence from others when the sequence was + generated by these techniques is equivalent to breaking the + cryptosystem or inverting the "non-invertible" hashing involved with + only partial information available. The less information revealed + each iteration, the harder it will be for an adversary to predict the + sequence. Thus it is best to use only one bit from each value. It + has been shown that in some cases this makes it impossible to break a + system even when the cryptographic system is invertible and can be + broken if all of each generated value was revealed. + +6.3.2 The Blum Blum Shub Sequence Generator + + Currently the generator which has the strongest public proof of + strength is called the Blum Blum Shub generator after its inventors + [BBS]. It is also very simple and is based on quadratic residues. + It's only disadvantage is that is is computationally intensive + compared with the traditional techniques give in 6.3.1 above. This + is not a serious draw back if it is used for moderately infrequent + purposes, such as generating session keys. + + + +Eastlake, Crocker & Schiller [Page 21] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + Simply choose two large prime numbers, say p and q, which both have + the property that you get a remainder of 3 if you divide them by 4. + Let n = p * q. Then you choose a random number x relatively prime to + n. The initial seed for the generator and the method for calculating + subsequent values are then + + 2 + s = ( x )(Mod n) + 0 + + 2 + s = ( s )(Mod n) + i+1 i + + You must be careful to use only a few bits from the bottom of each s. + It is always safe to use only the lowest order bit. If you use no + more than the + + log ( log ( s ) ) + 2 2 i + + low order bits, then predicting any additional bits from a sequence + generated in this manner is provable as hard as factoring n. As long + as the initial x is secret, you can even make n public if you want. + + An intersting characteristic of this generator is that you can + directly calculate any of the s values. In particular + + i + ( ( 2 )(Mod (( p - 1 ) * ( q - 1 )) ) ) + s = ( s )(Mod n) + i 0 + + This means that in applications where many keys are generated in this + fashion, it is not necessary to save them all. Each key can be + effectively indexed and recovered from that small index and the + initial s and n. + +7. Key Generation Standards + + Several public standards are now in place for the generation of keys. + Two of these are described below. Both use DES but any equally + strong or stronger mixing function could be substituted. + + + + + + + + +Eastlake, Crocker & Schiller [Page 22] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +7.1 US DoD Recommendations for Password Generation + + The United States Department of Defense has specific recommendations + for password generation [DoD]. They suggest using the US Data + Encryption Standard [DES] in Output Feedback Mode [DES MODES] as + follows: + + use an initialization vector determined from + the system clock, + system ID, + user ID, and + date and time; + use a key determined from + system interrupt registers, + system status registers, and + system counters; and, + as plain text, use an external randomly generated 64 bit + quantity such as 8 characters typed in by a system + administrator. + + The password can then be calculated from the 64 bit "cipher text" + generated in 64-bit Output Feedback Mode. As many bits as are needed + can be taken from these 64 bits and expanded into a pronounceable + word, phrase, or other format if a human being needs to remember the + password. + +7.2 X9.17 Key Generation + + The American National Standards Institute has specified a method for + generating a sequence of keys as follows: + + s is the initial 64 bit seed + 0 + + g is the sequence of generated 64 bit key quantities + n + + k is a random key reserved for generating this key sequence + + t is the time at which a key is generated to as fine a resolution + as is available (up to 64 bits). + + DES ( K, Q ) is the DES encryption of quantity Q with key K + + + + + + + + +Eastlake, Crocker & Schiller [Page 23] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + g = DES ( k, DES ( k, t ) .xor. s ) + n n + + s = DES ( k, DES ( k, t ) .xor. g ) + n+1 n + + If g sub n is to be used as a DES key, then every eighth bit should + be adjusted for parity for that use but the entire 64 bit unmodified + g should be used in calculating the next s. + +8. Examples of Randomness Required + + Below are two examples showing rough calculations of needed + randomness for security. The first is for moderate security + passwords while the second assumes a need for a very high security + cryptographic key. + +8.1 Password Generation + + Assume that user passwords change once a year and it is desired that + the probability that an adversary could guess the password for a + particular account be less than one in a thousand. Further assume + that sending a password to the system is the only way to try a + password. Then the crucial question is how often an adversary can + try possibilities. Assume that delays have been introduced into a + system so that, at most, an adversary can make one password try every + six seconds. That's 600 per hour or about 15,000 per day or about + 5,000,000 tries in a year. Assuming any sort of monitoring, it is + unlikely someone could actually try continuously for a year. In + fact, even if log files are only checked monthly, 500,000 tries is + more plausible before the attack is noticed and steps taken to change + passwords and make it harder to try more passwords. + + To have a one in a thousand chance of guessing the password in + 500,000 tries implies a universe of at least 500,000,000 passwords or + about 2^29. Thus 29 bits of randomness are needed. This can probably + be achieved using the US DoD recommended inputs for password + generation as it has 8 inputs which probably average over 5 bits of + randomness each (see section 7.1). Using a list of 1000 words, the + password could be expressed as a three word phrase (1,000,000,000 + possibilities) or, using case insensitive letters and digits, six + would suffice ((26+10)^6 = 2,176,782,336 possibilities). + + For a higher security password, the number of bits required goes up. + To decrease the probability by 1,000 requires increasing the universe + of passwords by the same factor which adds about 10 bits. Thus to + have only a one in a million chance of a password being guessed under + the above scenario would require 39 bits of randomness and a password + + + +Eastlake, Crocker & Schiller [Page 24] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + that was a four word phrase from a 1000 word list or eight + letters/digits. To go to a one in 10^9 chance, 49 bits of randomness + are needed implying a five word phrase or ten letter/digit password. + + In a real system, of course, there are also other factors. For + example, the larger and harder to remember passwords are, the more + likely users are to write them down resulting in an additional risk + of compromise. + +8.2 A Very High Security Cryptographic Key + + Assume that a very high security key is needed for symmetric + encryption / decryption between two parties. Assume an adversary can + observe communications and knows the algorithm being used. Within + the field of random possibilities, the adversary can try key values + in hopes of finding the one in use. Assume further that brute force + trial of keys is the best the adversary can do. + +8.2.1 Effort per Key Trial + + How much effort will it take to try each key? For very high security + applications it is best to assume a low value of effort. Even if it + would clearly take tens of thousands of computer cycles or more to + try a single key, there may be some pattern that enables huge blocks + of key values to be tested with much less effort per key. Thus it is + probably best to assume no more than a couple hundred cycles per key. + (There is no clear lower bound on this as computers operate in + parallel on a number of bits and a poor encryption algorithm could + allow many keys or even groups of keys to be tested in parallel. + However, we need to assume some value and can hope that a reasonably + strong algorithm has been chosen for our hypothetical high security + task.) + + If the adversary can command a highly parallel processor or a large + network of work stations, 2*10^10 cycles per second is probably a + minimum assumption for availability today. Looking forward just a + couple years, there should be at least an order of magnitude + improvement. Thus assuming 10^9 keys could be checked per second or + 3.6*10^11 per hour or 6*10^13 per week or 2.4*10^14 per month is + reasonable. This implies a need for a minimum of 51 bits of + randomness in keys to be sure they cannot be found in a month. Even + then it is possible that, a few years from now, a highly determined + and resourceful adversary could break the key in 2 weeks (on average + they need try only half the keys). + + + + + + + +Eastlake, Crocker & Schiller [Page 25] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +8.2.2 Meet in the Middle Attacks + + If chosen or known plain text and the resulting encrypted text are + available, a "meet in the middle" attack is possible if the structure + of the encryption algorithm allows it. (In a known plain text + attack, the adversary knows all or part of the messages being + encrypted, possibly some standard header or trailer fields. In a + chosen plain text attack, the adversary can force some chosen plain + text to be encrypted, possibly by "leaking" an exciting text that + would then be sent by the adversary over an encrypted channel.) + + An oversimplified explanation of the meet in the middle attack is as + follows: the adversary can half-encrypt the known or chosen plain + text with all possible first half-keys, sort the output, then half- + decrypt the encoded text with all the second half-keys. If a match + is found, the full key can be assembled from the halves and used to + decrypt other parts of the message or other messages. At its best, + this type of attack can halve the exponent of the work required by + the adversary while adding a large but roughly constant factor of + effort. To be assured of safety against this, a doubling of the + amount of randomness in the key to a minimum of 102 bits is required. + + The meet in the middle attack assumes that the cryptographic + algorithm can be decomposed in this way but we can not rule that out + without a deep knowledge of the algorithm. Even if a basic algorithm + is not subject to a meet in the middle attack, an attempt to produce + a stronger algorithm by applying the basic algorithm twice (or two + different algorithms sequentially) with different keys may gain less + added security than would be expected. Such a composite algorithm + would be subject to a meet in the middle attack. + + Enormous resources may be required to mount a meet in the middle + attack but they are probably within the range of the national + security services of a major nation. Essentially all nations spy on + other nations government traffic and several nations are believed to + spy on commercial traffic for economic advantage. + +8.2.3 Other Considerations + + Since we have not even considered the possibilities of special + purpose code breaking hardware or just how much of a safety margin we + want beyond our assumptions above, probably a good minimum for a very + high security cryptographic key is 128 bits of randomness which + implies a minimum key length of 128 bits. If the two parties agree + on a key by Diffie-Hellman exchange [D-H], then in principle only + half of this randomness would have to be supplied by each party. + However, there is probably some correlation between their random + inputs so it is probably best to assume that each party needs to + + + +Eastlake, Crocker & Schiller [Page 26] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + provide at least 96 bits worth of randomness for very high security + if Diffie-Hellman is used. + + This amount of randomness is beyond the limit of that in the inputs + recommended by the US DoD for password generation and could require + user typing timing, hardware random number generation, or other + sources. + + It should be noted that key length calculations such at those above + are controversial and depend on various assumptions about the + cryptographic algorithms in use. In some cases, a professional with + a deep knowledge of code breaking techniques and of the strength of + the algorithm in use could be satisfied with less than half of the + key size derived above. + +9. Conclusion + + Generation of unguessable "random" secret quantities for security use + is an essential but difficult task. + + We have shown that hardware techniques to produce such randomness + would be relatively simple. In particular, the volume and quality + would not need to be high and existing computer hardware, such as + disk drives, can be used. Computational techniques are available to + process low quality random quantities from multiple sources or a + larger quantity of such low quality input from one source and produce + a smaller quantity of higher quality, less predictable key material. + In the absence of hardware sources of randomness, a variety of user + and software sources can frequently be used instead with care; + however, most modern systems already have hardware, such as disk + drives or audio input, that could be used to produce high quality + randomness. + + Once a sufficient quantity of high quality seed key material (a few + hundred bits) is available, strong computational techniques are + available to produce cryptographically strong sequences of + unpredicatable quantities from this seed material. + +10. Security Considerations + + The entirety of this document concerns techniques and recommendations + for generating unguessable "random" quantities for use as passwords, + cryptographic keys, and similar security uses. + + + + + + + + +Eastlake, Crocker & Schiller [Page 27] + +RFC 1750 Randomness Recommendations for Security December 1994 + + +References + + [ASYMMETRIC] - Secure Communications and Asymmetric Cryptosystems, + edited by Gustavus J. Simmons, AAAS Selected Symposium 69, Westview + Press, Inc. + + [BBS] - A Simple Unpredictable Pseudo-Random Number Generator, SIAM + Journal on Computing, v. 15, n. 2, 1986, L. Blum, M. Blum, & M. Shub. + + [BRILLINGER] - Time Series: Data Analysis and Theory, Holden-Day, + 1981, David Brillinger. + + [CRC] - C.R.C. Standard Mathematical Tables, Chemical Rubber + Publishing Company. + + [CRYPTO1] - Cryptography: A Primer, A Wiley-Interscience Publication, + John Wiley & Sons, 1981, Alan G. Konheim. + + [CRYPTO2] - Cryptography: A New Dimension in Computer Data Security, + A Wiley-Interscience Publication, John Wiley & Sons, 1982, Carl H. + Meyer & Stephen M. Matyas. + + [CRYPTO3] - Applied Cryptography: Protocols, Algorithms, and Source + Code in C, John Wiley & Sons, 1994, Bruce Schneier. + + [DAVIS] - Cryptographic Randomness from Air Turbulence in Disk + Drives, Advances in Cryptology - Crypto '94, Springer-Verlag Lecture + Notes in Computer Science #839, 1984, Don Davis, Ross Ihaka, and + Philip Fenstermacher. + + [DES] - Data Encryption Standard, United States of America, + Department of Commerce, National Institute of Standards and + Technology, Federal Information Processing Standard (FIPS) 46-1. + - Data Encryption Algorithm, American National Standards Institute, + ANSI X3.92-1981. + (See also FIPS 112, Password Usage, which includes FORTRAN code for + performing DES.) + + [DES MODES] - DES Modes of Operation, United States of America, + Department of Commerce, National Institute of Standards and + Technology, Federal Information Processing Standard (FIPS) 81. + - Data Encryption Algorithm - Modes of Operation, American National + Standards Institute, ANSI X3.106-1983. + + [D-H] - New Directions in Cryptography, IEEE Transactions on + Information Technology, November, 1976, Whitfield Diffie and Martin + E. Hellman. + + + + +Eastlake, Crocker & Schiller [Page 28] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + [DoD] - Password Management Guideline, United States of America, + Department of Defense, Computer Security Center, CSC-STD-002-85. + (See also FIPS 112, Password Usage, which incorporates CSC-STD-002-85 + as one of its appendices.) + + [GIFFORD] - Natural Random Number, MIT/LCS/TM-371, September 1988, + David K. Gifford + + [KNUTH] - The Art of Computer Programming, Volume 2: Seminumerical + Algorithms, Chapter 3: Random Numbers. Addison Wesley Publishing + Company, Second Edition 1982, Donald E. Knuth. + + [KRAWCZYK] - How to Predict Congruential Generators, Journal of + Algorithms, V. 13, N. 4, December 1992, H. Krawczyk + + [MD2] - The MD2 Message-Digest Algorithm, RFC1319, April 1992, B. + Kaliski + [MD4] - The MD4 Message-Digest Algorithm, RFC1320, April 1992, R. + Rivest + [MD5] - The MD5 Message-Digest Algorithm, RFC1321, April 1992, R. + Rivest + + [PEM] - RFCs 1421 through 1424: + - RFC 1424, Privacy Enhancement for Internet Electronic Mail: Part + IV: Key Certification and Related Services, 02/10/1993, B. Kaliski + - RFC 1423, Privacy Enhancement for Internet Electronic Mail: Part + III: Algorithms, Modes, and Identifiers, 02/10/1993, D. Balenson + - RFC 1422, Privacy Enhancement for Internet Electronic Mail: Part + II: Certificate-Based Key Management, 02/10/1993, S. Kent + - RFC 1421, Privacy Enhancement for Internet Electronic Mail: Part I: + Message Encryption and Authentication Procedures, 02/10/1993, J. Linn + + [SHANNON] - The Mathematical Theory of Communication, University of + Illinois Press, 1963, Claude E. Shannon. (originally from: Bell + System Technical Journal, July and October 1948) + + [SHIFT1] - Shift Register Sequences, Aegean Park Press, Revised + Edition 1982, Solomon W. Golomb. + + [SHIFT2] - Cryptanalysis of Shift-Register Generated Stream Cypher + Systems, Aegean Park Press, 1984, Wayne G. Barker. + + [SHS] - Secure Hash Standard, United States of American, National + Institute of Science and Technology, Federal Information Processing + Standard (FIPS) 180, April 1993. + + [STERN] - Secret Linear Congruential Generators are not + Cryptograhically Secure, Proceedings of IEEE STOC, 1987, J. Stern. + + + +Eastlake, Crocker & Schiller [Page 29] + +RFC 1750 Randomness Recommendations for Security December 1994 + + + [VON NEUMANN] - Various techniques used in connection with random + digits, von Neumann's Collected Works, Vol. 5, Pergamon Press, 1963, + J. von Neumann. + +Authors' Addresses + + Donald E. Eastlake 3rd + Digital Equipment Corporation + 550 King Street, LKG2-1/BB3 + Littleton, MA 01460 + + Phone: +1 508 486 6577(w) +1 508 287 4877(h) + EMail: dee@lkg.dec.com + + + Stephen D. Crocker + CyberCash Inc. + 2086 Hunters Crest Way + Vienna, VA 22181 + + Phone: +1 703-620-1222(w) +1 703-391-2651 (fax) + EMail: crocker@cybercash.com + + + Jeffrey I. Schiller + Massachusetts Institute of Technology + 77 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 253 0161(w) + EMail: jis@mit.edu + + + + + + + + + + + + + + + + + + + + +Eastlake, Crocker & Schiller [Page 30] + diff --git a/crypto/heimdal/doc/standardisation/rfc1831.txt b/crypto/heimdal/doc/standardisation/rfc1831.txt new file mode 100644 index 0000000..0556c9e --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1831.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group R. Srinivasan +Request for Comments: 1831 Sun Microsystems +Category: Standards Track August 1995 + + + RPC: Remote Procedure Call Protocol Specification Version 2 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This document describes the ONC Remote Procedure Call (ONC RPC + Version 2) protocol as it is currently deployed and accepted. "ONC" + stands for "Open Network Computing". + +TABLE OF CONTENTS + + 1. INTRODUCTION 2 + 2. TERMINOLOGY 2 + 3. THE RPC MODEL 2 + 4. TRANSPORTS AND SEMANTICS 4 + 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 + 6. AUTHENTICATION 5 + 7. RPC PROTOCOL REQUIREMENTS 5 + 7.1 RPC Programs and Procedures 6 + 7.2 Authentication 7 + 7.3 Program Number Assignment 8 + 7.4 Other Uses of the RPC Protocol 8 + 7.4.1 Batching 8 + 7.4.2 Broadcast Remote Procedure Calls 8 + 8. THE RPC MESSAGE PROTOCOL 9 + 9. AUTHENTICATION PROTOCOLS 12 + 9.1 Null Authentication 13 + 10. RECORD MARKING STANDARD 13 + 11. THE RPC LANGUAGE 13 + 11.1 An Example Service Described in the RPC Language 13 + 11.2 The RPC Language Specification 14 + 11.3 Syntax Notes 15 + APPENDIX A: SYSTEM AUTHENTICATION 16 + REFERENCES 17 + Security Considerations 18 + Author's Address 18 + + + +Srinivasan Standards Track [Page 1] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +1. INTRODUCTION + + This document specifies version two of the message protocol used in + ONC Remote Procedure Call (RPC). The message protocol is specified + with the eXternal Data Representation (XDR) language [9]. This + document assumes that the reader is familiar with XDR. It does not + attempt to justify remote procedure calls systems or describe their + use. The paper by Birrell and Nelson [1] is recommended as an + excellent background for the remote procedure call concept. + +2. TERMINOLOGY + + This document discusses clients, calls, servers, replies, services, + programs, procedures, and versions. Each remote procedure call has + two sides: an active client side that makes the call to a server, + which sends back a reply. A network service is a collection of one + or more remote programs. A remote program implements one or more + remote procedures; the procedures, their parameters, and results are + documented in the specific program's protocol specification. A + server may support more than one version of a remote program in order + to be compatible with changing protocols. + + For example, a network file service may be composed of two programs. + One program may deal with high-level applications such as file system + access control and locking. The other may deal with low-level file + input and output and have procedures like "read" and "write". A + client of the network file service would call the procedures + associated with the two programs of the service on behalf of the + client. + + The terms client and server only apply to a particular transaction; a + particular hardware entity (host) or software entity (process or + program) could operate in both roles at different times. For + example, a program that supplies remote execution service could also + be a client of a network file service. + +3. THE RPC MODEL + + The ONC RPC protocol is based on the remote procedure call model, + which is similar to the local procedure call model. In the local + case, the caller places arguments to a procedure in some well- + specified location (such as a register window). It then transfers + control to the procedure, and eventually regains control. At that + point, the results of the procedure are extracted from the well- + specified location, and the caller continues execution. + + + + + + +Srinivasan Standards Track [Page 2] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + The remote procedure call model is similar. One thread of control + logically winds through two processes: the caller's process, and a + server's process. The caller process first sends a call message to + the server process and waits (blocks) for a reply message. The call + message includes the procedure's parameters, and the reply message + includes the procedure's results. Once the reply message is + received, the results of the procedure are extracted, and caller's + execution is resumed. + + On the server side, a process is dormant awaiting the arrival of a + call message. When one arrives, the server process extracts the + procedure's parameters, computes the results, sends a reply message, + and then awaits the next call message. + + In this model, only one of the two processes is active at any given + time. However, this model is only given as an example. The ONC RPC + protocol makes no restrictions on the concurrency model implemented, + and others are possible. For example, an implementation may choose + to have RPC calls be asynchronous, so that the client may do useful + work while waiting for the reply from the server. Another + possibility is to have the server create a separate task to process + an incoming call, so that the original server can be free to receive + other requests. + + There are a few important ways in which remote procedure calls differ + from local procedure calls: + + 1. Error handling: failures of the remote server or network must + be handled when using remote procedure calls. + + 2. Global variables and side-effects: since the server does not + have access to the client's address space, hidden arguments cannot + be passed as global variables or returned as side effects. + + 3. Performance: remote procedures usually operate one or more + orders of magnitude slower than local procedure calls. + + 4. Authentication: since remote procedure calls can be transported + over unsecured networks, authentication may be necessary. + Authentication prevents one entity from masquerading as some other + entity. + + The conclusion is that even though there are tools to automatically + generate client and server libraries for a given service, protocols + must still be designed carefully. + + + + + + +Srinivasan Standards Track [Page 3] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +4. TRANSPORTS AND SEMANTICS + + The RPC protocol can be implemented on several different transport + protocols. The RPC protocol does not care how a message is passed + from one process to another, but only with specification and + interpretation of messages. However, the application may wish to + obtain information about (and perhaps control over) the transport + layer through an interface not specified in this document. For + example, the transport protocol may impose a restriction on the + maximum size of RPC messages, or it may be stream-oriented like TCP + with no size limit. The client and server must agree on their + transport protocol choices. + + It is important to point out that RPC does not try to implement any + kind of reliability and that the application may need to be aware of + the type of transport protocol underneath RPC. If it knows it is + running on top of a reliable transport such as TCP [6], then most of + the work is already done for it. On the other hand, if it is running + on top of an unreliable transport such as UDP [7], it must implement + its own time-out, retransmission, and duplicate detection policies as + the RPC protocol does not provide these services. + + Because of transport independence, the RPC protocol does not attach + specific semantics to the remote procedures or their execution + requirements. Semantics can be inferred from (but should be + explicitly specified by) the underlying transport protocol. For + example, consider RPC running on top of an unreliable transport such + as UDP. If an application retransmits RPC call messages after time- + outs, and does not receive a reply, it cannot infer anything about + the number of times the procedure was executed. If it does receive a + reply, then it can infer that the procedure was executed at least + once. + + A server may wish to remember previously granted requests from a + client and not regrant them in order to insure some degree of + execute-at-most-once semantics. A server can do this by taking + advantage of the transaction ID that is packaged with every RPC + message. The main use of this transaction ID is by the client RPC + entity in matching replies to calls. However, a client application + may choose to reuse its previous transaction ID when retransmitting a + call. The server may choose to remember this ID after executing a + call and not execute calls with the same ID in order to achieve some + degree of execute-at-most-once semantics. The server is not allowed + to examine this ID in any other way except as a test for equality. + + On the other hand, if using a "reliable" transport such as TCP, the + application can infer from a reply message that the procedure was + executed exactly once, but if it receives no reply message, it cannot + + + +Srinivasan Standards Track [Page 4] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + assume that the remote procedure was not executed. Note that even if + a connection-oriented protocol like TCP is used, an application still + needs time-outs and reconnection to handle server crashes. + + There are other possibilities for transports besides datagram- or + connection-oriented protocols. For example, a request-reply protocol + such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC + uses both TCP and UDP transport protocols. Section 10 (RECORD + MARKING STANDARD) describes the mechanism employed by ONC RPC to + utilize a connection-oriented, stream-oriented transport such as TCP. + +5. BINDING AND RENDEZVOUS INDEPENDENCE + + The act of binding a particular client to a particular service and + transport parameters is NOT part of this RPC protocol specification. + This important and necessary function is left up to some higher-level + software. + + Implementors could think of the RPC protocol as the jump-subroutine + instruction ("JSR") of a network; the loader (binder) makes JSR + useful, and the loader itself uses JSR to accomplish its task. + Likewise, the binding software makes RPC useful, possibly using RPC + to accomplish this task. + +6. AUTHENTICATION + + The RPC protocol provides the fields necessary for a client to + identify itself to a service, and vice-versa, in each call and reply + message. Security and access control mechanisms can be built on top + of this message authentication. Several different authentication + protocols can be supported. A field in the RPC header indicates + which protocol is being used. More information on specific + authentication protocols is in section 9: "Authentication Protocols". + +7. RPC PROTOCOL REQUIREMENTS + + The RPC protocol must provide for the following: + + (1) Unique specification of a procedure to be called. + (2) Provisions for matching response messages to request messages. + (3) Provisions for authenticating the caller to service and + vice-versa. + + + + + + + + + +Srinivasan Standards Track [Page 5] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + Besides these requirements, features that detect the following are + worth supporting because of protocol roll-over errors, implementation + bugs, user error, and network administration: + + (1) RPC protocol mismatches. + (2) Remote program protocol version mismatches. + (3) Protocol errors (such as misspecification of a procedure's + parameters). + (4) Reasons why remote authentication failed. + (5) Any other reasons why the desired procedure was not called. + +7.1 RPC Programs and Procedures + + The RPC call message has three unsigned integer fields -- remote + program number, remote program version number, and remote procedure + number -- which uniquely identify the procedure to be called. + Program numbers are administered by a central authority + (rpc@sun.com). Once implementors have a program number, they can + implement their remote program; the first implementation would most + likely have the version number 1. Because most new protocols evolve, + a version field of the call message identifies which version of the + protocol the caller is using. Version numbers enable support of both + old and new protocols through the same server process. + + The procedure number identifies the procedure to be called. These + numbers are documented in the specific program's protocol + specification. For example, a file service's protocol specification + may state that its procedure number 5 is "read" and procedure number + 12 is "write". + + Just as remote program protocols may change over several versions, + the actual RPC message protocol could also change. Therefore, the + call message also has in it the RPC version number, which is always + equal to two for the version of RPC described here. + + The reply message to a request message has enough information to + distinguish the following error conditions: + + (1) The remote implementation of RPC does not support protocol + version 2. The lowest and highest supported RPC version numbers + are returned. + + (2) The remote program is not available on the remote system. + + (3) The remote program does not support the requested version + number. The lowest and highest supported remote program version + numbers are returned. + + + + +Srinivasan Standards Track [Page 6] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + (4) The requested procedure number does not exist. (This is + usually a client side protocol or programming error.) + + (5) The parameters to the remote procedure appear to be garbage + from the server's point of view. (Again, this is usually caused + by a disagreement about the protocol between client and service.) + +7.2 Authentication + + Provisions for authentication of caller to service and vice-versa are + provided as a part of the RPC protocol. The call message has two + authentication fields, the credential and verifier. The reply + message has one authentication field, the response verifier. The RPC + protocol specification defines all three fields to be the following + opaque type (in the eXternal Data Representation (XDR) language [9]): + + enum auth_flavor { + AUTH_NONE = 0, + AUTH_SYS = 1, + AUTH_SHORT = 2 + /* and more to be defined */ + }; + + struct opaque_auth { + auth_flavor flavor; + opaque body<400>; + }; + + In other words, any "opaque_auth" structure is an "auth_flavor" + enumeration followed by up to 400 bytes which are opaque to + (uninterpreted by) the RPC protocol implementation. + + The interpretation and semantics of the data contained within the + authentication fields is specified by individual, independent + authentication protocol specifications. (Section 9 defines the + various authentication protocols.) + + If authentication parameters were rejected, the reply message + contains information stating why they were rejected. + + + + + + + + + + + + +Srinivasan Standards Track [Page 7] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +7.3 Program Number Assignment + + Program numbers are given out in groups of hexadecimal 20000000 + (decimal 536870912) according to the following chart: + + 0 - 1fffffff defined by rpc@sun.com + 20000000 - 3fffffff defined by user + 40000000 - 5fffffff transient + 60000000 - 7fffffff reserved + 80000000 - 9fffffff reserved + a0000000 - bfffffff reserved + c0000000 - dfffffff reserved + e0000000 - ffffffff reserved + + The first group is a range of numbers administered by rpc@sun.com and + should be identical for all sites. The second range is for + applications peculiar to a particular site. This range is intended + primarily for debugging new programs. When a site develops an + application that might be of general interest, that application + should be given an assigned number in the first range. Application + developers may apply for blocks of RPC program numbers in the first + range by sending electronic mail to "rpc@sun.com". The third group + is for applications that generate program numbers dynamically. The + final groups are reserved for future use, and should not be used. + +7.4 Other Uses of the RPC Protocol + + The intended use of this protocol is for calling remote procedures. + Normally, each call message is matched with a reply message. + However, the protocol itself is a message-passing protocol with which + other (non-procedure call) protocols can be implemented. + +7.4.1 Batching + + Batching is useful when a client wishes to send an arbitrarily large + sequence of call messages to a server. Batching typically uses + reliable byte stream protocols (like TCP) for its transport. In the + case of batching, the client never waits for a reply from the server, + and the server does not send replies to batch calls. A sequence of + batch calls is usually terminated by a legitimate remote procedure + call operation in order to flush the pipeline and get positive + acknowledgement. + +7.4.2 Broadcast Remote Procedure Calls + + In broadcast protocols, the client sends a broadcast call to the + network and waits for numerous replies. This requires the use of + packet-based protocols (like UDP) as its transport protocol. Servers + + + +Srinivasan Standards Track [Page 8] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + that support broadcast protocols usually respond only when the call + is successfully processed and are silent in the face of errors, but + this varies with the application. + + The principles of broadcast RPC also apply to multicasting - an RPC + request can be sent to a multicast address. + +8. THE RPC MESSAGE PROTOCOL + + This section defines the RPC message protocol in the XDR data + description language [9]. + + enum msg_type { + CALL = 0, + REPLY = 1 + }; + + A reply to a call message can take on two forms: The message was + either accepted or rejected. + + enum reply_stat { + MSG_ACCEPTED = 0, + MSG_DENIED = 1 + }; + + Given that a call message was accepted, the following is the status + of an attempt to call a remote procedure. + + enum accept_stat { + SUCCESS = 0, /* RPC executed successfully */ + PROG_UNAVAIL = 1, /* remote hasn't exported program */ + PROG_MISMATCH = 2, /* remote can't support version # */ + PROC_UNAVAIL = 3, /* program can't support procedure */ + GARBAGE_ARGS = 4, /* procedure can't decode params */ + SYSTEM_ERR = 5 /* errors like memory allocation failure */ + }; + + Reasons why a call message was rejected: + + enum reject_stat { + RPC_MISMATCH = 0, /* RPC version number != 2 */ + AUTH_ERROR = 1 /* remote can't authenticate caller */ + }; + + Why authentication failed: + + enum auth_stat { + AUTH_OK = 0, /* success */ + + + +Srinivasan Standards Track [Page 9] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * failed at remote end + */ + AUTH_BADCRED = 1, /* bad credential (seal broken) */ + AUTH_REJECTEDCRED = 2, /* client must begin new session */ + AUTH_BADVERF = 3, /* bad verifier (seal broken) */ + AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ + AUTH_TOOWEAK = 5, /* rejected for security reasons */ + /* + * failed locally + */ + AUTH_INVALIDRESP = 6, /* bogus response verifier */ + AUTH_FAILED = 7 /* reason unknown */ + }; + + The RPC message: + + All messages start with a transaction identifier, xid, followed by a + two-armed discriminated union. The union's discriminant is a + msg_type which switches to one of the two types of the message. The + xid of a REPLY message always matches that of the initiating CALL + message. NB: The xid field is only used for clients matching reply + messages with call messages or for servers detecting retransmissions; + the service side cannot treat this id as any type of sequence number. + + struct rpc_msg { + unsigned int xid; + union switch (msg_type mtype) { + case CALL: + call_body cbody; + case REPLY: + reply_body rbody; + } body; + }; + + Body of an RPC call: + + In version 2 of the RPC protocol specification, rpcvers must be equal + to 2. The fields prog, vers, and proc specify the remote program, + its version number, and the procedure within the remote program to be + called. After these fields are two authentication parameters: cred + (authentication credential) and verf (authentication verifier). The + two authentication parameters are followed by the parameters to the + remote procedure, which are specified by the specific program + protocol. + + The purpose of the authentication verifier is to validate the + authentication credential. Note that these two items are + + + +Srinivasan Standards Track [Page 10] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + historically separate, but are always used together as one logical + entity. + + struct call_body { + unsigned int rpcvers; /* must be equal to two (2) */ + unsigned int prog; + unsigned int vers; + unsigned int proc; + opaque_auth cred; + opaque_auth verf; + /* procedure specific parameters start here */ + }; + + Body of a reply to an RPC call: + + union reply_body switch (reply_stat stat) { + case MSG_ACCEPTED: + accepted_reply areply; + case MSG_DENIED: + rejected_reply rreply; + } reply; + + Reply to an RPC call that was accepted by the server: + + There could be an error even though the call was accepted. The first + field is an authentication verifier that the server generates in + order to validate itself to the client. It is followed by a union + whose discriminant is an enum accept_stat. The SUCCESS arm of the + union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, + GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The + PROG_MISMATCH arm specifies the lowest and highest version numbers of + the remote program supported by the server. + + struct accepted_reply { + opaque_auth verf; + union switch (accept_stat stat) { + case SUCCESS: + opaque results[0]; + /* + * procedure-specific results start here + */ + case PROG_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + default: + /* + + + +Srinivasan Standards Track [Page 11] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, + * GARBAGE_ARGS, and SYSTEM_ERR. + */ + void; + } reply_data; + }; + + Reply to an RPC call that was rejected by the server: + + The call can be rejected for two reasons: either the server is not + running a compatible version of the RPC protocol (RPC_MISMATCH), or + the server rejects the identity of the caller (AUTH_ERROR). In case + of an RPC version mismatch, the server returns the lowest and highest + supported RPC version numbers. In case of invalid authentication, + failure status is returned. + + union rejected_reply switch (reject_stat stat) { + case RPC_MISMATCH: + struct { + unsigned int low; + unsigned int high; + } mismatch_info; + case AUTH_ERROR: + auth_stat stat; + }; + +9. AUTHENTICATION PROTOCOLS + + As previously stated, authentication parameters are opaque, but + open-ended to the rest of the RPC protocol. This section defines two + standard "flavors" of authentication. Implementors are free to + invent new authentication types, with the same rules of flavor number + assignment as there is for program number assignment. The "flavor" + of a credential or verifier refers to the value of the "flavor" field + in the opaque_auth structure. Flavor numbers, like RPC program + numbers, are also administered centrally, and developers may assign + new flavor numbers by applying through electronic mail to + "rpc@sun.com". Credentials and verifiers are represented as variable + length opaque data (the "body" field in the opaque_auth structure). + + In this document, two flavors of authentication are described. Of + these, Null authentication (described in the next subsection) is + mandatory - it must be available in all implementations. System + authentication is described in Appendix A. It is strongly + recommended that implementors include System authentication in their + implementations. Many applications use this style of authentication, + and availability of this flavor in an implementation will enhance + interoperability. + + + +Srinivasan Standards Track [Page 12] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +9.1 Null Authentication + + Often calls must be made where the client does not care about its + identity or the server does not care who the client is. In this + case, the flavor of the RPC message's credential, verifier, and reply + verifier is "AUTH_NONE". Opaque data associated with "AUTH_NONE" is + undefined. It is recommended that the length of the opaque data be + zero. + +10. RECORD MARKING STANDARD + + When RPC messages are passed on top of a byte stream transport + protocol (like TCP), it is necessary to delimit one message from + another in order to detect and possibly recover from protocol errors. + This is called record marking (RM). One RPC message fits into one RM + record. + + A record is composed of one or more record fragments. A record + fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of + fragment data. The bytes encode an unsigned binary number; as with + XDR integers, the byte order is from highest to lowest. The number + encodes two values -- a boolean which indicates whether the fragment + is the last fragment of the record (bit value 1 implies the fragment + is the last fragment) and a 31-bit unsigned binary value which is the + length in bytes of the fragment's data. The boolean value is the + highest-order bit of the header; the length is the 31 low-order bits. + (Note that this record specification is NOT in XDR standard form!) + +11. THE RPC LANGUAGE + + Just as there was a need to describe the XDR data-types in a formal + language, there is also need to describe the procedures that operate + on these XDR data-types in a formal language as well. The RPC + Language is an extension to the XDR language, with the addition of + "program", "procedure", and "version" declarations. The following + example is used to describe the essence of the language. + +11.1 An Example Service Described in the RPC Language + + Here is an example of the specification of a simple ping program. + + program PING_PROG { + /* + * Latest and greatest version + */ + version PING_VERS_PINGBACK { + void + PINGPROC_NULL(void) = 0; + + + +Srinivasan Standards Track [Page 13] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + /* + * Ping the client, return the round-trip time + * (in microseconds). Returns -1 if the operation + * timed out. + */ + int + PINGPROC_PINGBACK(void) = 1; + } = 2; + + /* + * Original version + */ + version PING_VERS_ORIG { + void + PINGPROC_NULL(void) = 0; + } = 1; + } = 1; + + const PING_VERS = 2; /* latest version */ + + The first version described is PING_VERS_PINGBACK with two + procedures, PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes + no arguments and returns no results, but it is useful for computing + round-trip times from the client to the server and back again. By + convention, procedure 0 of any RPC protocol should have the same + semantics, and never require any kind of authentication. The second + procedure is used for the client to have the server do a reverse ping + operation back to the client, and it returns the amount of time (in + microseconds) that the operation used. The next version, + PING_VERS_ORIG, is the original version of the protocol and it does + not contain PINGPROC_PINGBACK procedure. It is useful for + compatibility with old client programs, and as this program matures + it may be dropped from the protocol entirely. + +11.2 The RPC Language Specification + + The RPC language is identical to the XDR language defined in RFC + 1014, except for the added definition of a "program-def" described + below. + + program-def: + "program" identifier "{" + version-def + version-def * + "}" "=" constant ";" + + version-def: + "version" identifier "{" + + + +Srinivasan Standards Track [Page 14] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + + procedure-def + procedure-def * + "}" "=" constant ";" + + procedure-def: + type-specifier identifier "(" type-specifier + ("," type-specifier )* ")" "=" constant ";" + +11.3 Syntax Notes + + (1) The following keywords are added and cannot be used as + identifiers: "program" and "version"; + + (2) A version name cannot occur more than once within the scope of a + program definition. Nor can a version number occur more than once + within the scope of a program definition. + + (3) A procedure name cannot occur more than once within the scope of + a version definition. Nor can a procedure number occur more than once + within the scope of version definition. + + (4) Program identifiers are in the same name space as constant and + type identifiers. + + (5) Only unsigned constants can be assigned to programs, versions and + procedures. + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 15] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +APPENDIX A: SYSTEM AUTHENTICATION + + The client may wish to identify itself, for example, as it is + identified on a UNIX(tm) system. The flavor of the client credential + is "AUTH_SYS". The opaque data constituting the credential encodes + the following structure: + + struct authsys_parms { + unsigned int stamp; + string machinename<255>; + unsigned int uid; + unsigned int gid; + unsigned int gids<16>; + }; + + The "stamp" is an arbitrary ID which the caller machine may generate. + The "machinename" is the name of the caller's machine (like + "krypton"). The "uid" is the caller's effective user ID. The "gid" + is the caller's effective group ID. The "gids" is a counted array of + groups which contain the caller as a member. The verifier + accompanying the credential should have "AUTH_NONE" flavor value + (defined above). Note this credential is only unique within a + particular domain of machine names, uids, and gids. + + The flavor value of the verifier received in the reply message from + the server may be "AUTH_NONE" or "AUTH_SHORT". In the case of + "AUTH_SHORT", the bytes of the reply verifier's string encode an + opaque structure. This new opaque structure may now be passed to the + server instead of the original "AUTH_SYS" flavor credential. The + server may keep a cache which maps shorthand opaque structures + (passed back by way of an "AUTH_SHORT" style reply verifier) to the + original credentials of the caller. The caller can save network + bandwidth and server cpu cycles by using the shorthand credential. + + The server may flush the shorthand opaque structure at any time. If + this happens, the remote procedure call message will be rejected due + to an authentication error. The reason for the failure will be + "AUTH_REJECTEDCRED". At this point, the client may wish to try the + original "AUTH_SYS" style of credential. + + It should be noted that use of this flavor of authentication does not + guarantee any security for the users or providers of a service, in + itself. The authentication provided by this scheme can be considered + legitimate only when applications using this scheme and the network + can be secured externally, and privileged transport addresses are + used for the communicating end-points (an example of this is the use + of privileged TCP/UDP ports in Unix systems - note that not all + systems enforce privileged transport address mechanisms). + + + +Srinivasan Standards Track [Page 16] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +REFERENCES + + [1] Birrell, A. D. & Nelson, B. J., "Implementing Remote Procedure + Calls", XEROX CSL-83-7, October 1983. + + [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol", + Preliminary Version 0.3, Stanford University, January 1987. + + [3] Diffie & Hellman, "New Directions in Cryptography", IEEE + Transactions on Information Theory IT-22, November 1976. + + [4] Mills, D., "Network Time Protocol", RFC 1305, UDEL, + March 1992. + + [5] National Bureau of Standards, "Data Encryption Standard", + Federal Information Processing Standards Publication 46, January + 1977. + + [6] Postel, J., "Transmission Control Protocol - DARPA Internet + Program Protocol Specification", STD 7, RFC 793, USC/Information + Sciences Institute, September 1981. + + [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, + USC/Information Sciences Institute, August 1980. + + [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, + RFC 1700, USC/Information Sciences Institute, October 1994. + + [9] Srinivasan, R., "XDR: External Data Representation Standard", + RFC 1832, Sun Microsystems, Inc., August 1995. + + [10] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section + E.2.1: Kerberos Authentication and Authorization System", + M.I.T. Project Athena, Cambridge, Massachusetts, December 21, + 1987. + + [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An + Authentication Service for Open Network Systems", pp. 191-202 in + Usenix Conference Proceedings, Dallas, Texas, February 1988. + + [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication + Service (V5)", RFC 1510, Digital Equipment Corporation, + USC/Information Sciences Institute, September 1993. + + + + + + + + +Srinivasan Standards Track [Page 17] + +RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 + + +Security Considerations + + Security issues are not discussed in this memo. + +Author's Address + + Raj Srinivasan + Sun Microsystems, Inc. + ONC Technologies + 2550 Garcia Avenue + M/S MTV-5-40 + Mountain View, CA 94043 + USA + + Phone: 415-336-2478 + Fax: 415-336-6015 + EMail: raj@eng.sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Srinivasan Standards Track [Page 18] + diff --git a/crypto/heimdal/doc/standardisation/rfc1964.txt b/crypto/heimdal/doc/standardisation/rfc1964.txt new file mode 100644 index 0000000..f2960b9 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1964.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 1964 OpenVision Technologies +Category: Standards Track June 1996 + + + The Kerberos Version 5 GSS-API Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +ABSTRACT + + This specification defines protocols, procedures, and conventions to + be employed by peers implementing the Generic Security Service + Application Program Interface (as specified in RFCs 1508 and 1509) + when using Kerberos Version 5 technology (as specified in RFC 1510). + +ACKNOWLEDGMENTS + + Much of the material in this memo is based on working documents + drafted by John Wray of Digital Equipment Corporation and on + discussions, implementation activities, and interoperability testing + involving Marc Horowitz, Ted Ts'o, and John Wray. Particular thanks + are due to each of these individuals for their contributions towards + development and availability of GSS-API support within the Kerberos + Version 5 code base. + +1. Token Formats + + This section discusses protocol-visible characteristics of the GSS- + API mechanism to be implemented atop Kerberos V5 security technology + per RFC-1508 and RFC-1510; it defines elements of protocol for + interoperability and is independent of language bindings per RFC- + 1509. + + Tokens transferred between GSS-API peers (for security context + management and per-message protection purposes) are defined. The + data elements exchanged between a GSS-API endpoint implementation and + the Kerberos KDC are not specific to GSS-API usage and are therefore + defined within RFC-1510 rather than within this specification. + + + + + + +Linn Standards Track [Page 1] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + To support ongoing experimentation, testing, and evolution of the + specification, the Kerberos V5 GSS-API mechanism as defined in this + and any successor memos will be identified with the following Object + Identifier, as defined in RFC-1510, until the specification is + advanced to the level of Proposed Standard RFC: + + {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} + + Upon advancement to the level of Proposed Standard RFC, the Kerberos + V5 GSS-API mechanism will be identified by an Object Identifier + having the value: + + {iso(1) member-body(2) United States(840) mit(113554) infosys(1) + gssapi(2) krb5(2)} + +1.1. Context Establishment Tokens + + Per RFC-1508, Appendix B, the initial context establishment token + will be enclosed within framing as follows: + + InitialContextToken ::= + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType + -- MechType is OBJECT IDENTIFIER + -- representing "Kerberos V5" + innerContextToken ANY DEFINED BY thisMech + -- contents mechanism-specific; + -- ASN.1 usage within innerContextToken + -- is not required + } + + The innerContextToken of the initial context token will consist of a + Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id + (TOK_ID) field, which shall contain the value 01 00. + + The above GSS-API framing shall be applied to all tokens emitted by + the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, + context-deletion, and per-message tokens, not just to the initial + token in a context establishment sequence. While not required by + RFC-1508, this enables implementations to perform enhanced error- + checking. The innerContextToken field of context establishment tokens + for the Kerberos V5 GSS-API mechanism will contain a Kerberos message + (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID + field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP + messages and 03 00 for KRB_ERROR messages. + + + + + + +Linn Standards Track [Page 2] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.1.1. Initial Token + + Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: + + AP-REQ ::= [APPLICATION 14] SEQUENCE { + pvno [0] INTEGER, -- indicates Version 5 + msg-type [1] INTEGER, -- indicates KRB_AP_REQ + ap-options[2] APOptions, + ticket[3] Ticket, + authenticator[4] EncryptedData + } + + APOptions ::= BIT STRING { + reserved (0), + use-session-key (1), + mutual-required (2) + } + + Ticket ::= [APPLICATION 1] SEQUENCE { + tkt-vno [0] INTEGER, -- indicates Version 5 + realm [1] Realm, + sname [2] PrincipalName, + enc-part [3] EncryptedData + } + + -- Encrypted part of ticket + EncTicketPart ::= [APPLICATION 3] SEQUENCE { + flags[0] TicketFlags, + key[1] EncryptionKey, + crealm[2] Realm, + cname[3] PrincipalName, + transited[4] TransitedEncoding, + authtime[5] KerberosTime, + starttime[6] KerberosTime OPTIONAL, + endtime[7] KerberosTime, + renew-till[8] KerberosTime OPTIONAL, + caddr[9] HostAddresses OPTIONAL, + authorization-data[10] AuthorizationData OPTIONAL + } + + -- Unencrypted authenticator + Authenticator ::= [APPLICATION 2] SEQUENCE { + authenticator-vno[0] INTEGER, + crealm[1] Realm, + cname[2] PrincipalName, + cksum[3] Checksum OPTIONAL, + cusec[4] INTEGER, + ctime[5] KerberosTime, + + + +Linn Standards Track [Page 3] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + subkey[6] EncryptionKey OPTIONAL, + seq-number[7] INTEGER OPTIONAL, + authorization-data[8] AuthorizationData OPTIONAL + } + + For purposes of this specification, the authenticator shall include + the optional sequence number, and the checksum field shall be used to + convey channel binding, service flags, and optional delegation + information. The checksum will have a type of 0x8003 (a value being + registered within the Kerberos protocol specification), and a value + field of at least 24 bytes in length. The length of the value field + is extended beyond 24 bytes if and only if an optional facility to + carry a Kerberos-defined KRB_CRED message for delegation purposes is + supported by an implementation and active on a context. When + delegation is active, a TGT with its FORWARDABLE flag set will be + transferred within the KRB_CRED message. + + The checksum value field's format is as follows: + + Byte Name Description + 0..3 Lgth Number of bytes in Bnd field; + Currently contains hex 10 00 00 00 + (16, represented in little-endian form) + 4..19 Bnd MD5 hash of channel bindings, taken over all non-null + components of bindings, in order of declaration. + Integer fields within channel bindings are represented + in little-endian order for the purposes of the MD5 + calculation. + 20..23 Flags Bit vector of context-establishment flags, + with values consistent with RFC-1509, p. 41: + GSS_C_DELEG_FLAG: 1 + GSS_C_MUTUAL_FLAG: 2 + GSS_C_REPLAY_FLAG: 4 + GSS_C_SEQUENCE_FLAG: 8 + GSS_C_CONF_FLAG: 16 + GSS_C_INTEG_FLAG: 32 + The resulting bit vector is encoded into bytes 20..23 + in little-endian form. + 24..25 DlgOpt The Delegation Option identifier (=1) [optional] + 26..27 Dlgth The length of the Deleg field. [optional] + 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] + + In computing the contents of the "Bnd" field, the following detailed + points apply: + + (1) Each integer field shall be formatted into four bytes, using + little-endian byte ordering, for purposes of MD5 hash + computation. + + + +Linn Standards Track [Page 4] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) All input length fields within gss_buffer_desc elements of a + gss_channel_bindings_struct, even those which are zero-valued, + shall be included in the hash calculation; the value elements of + gss_buffer_desc elements shall be dereferenced, and the + resulting data shall be included within the hash computation, + only for the case of gss_buffer_desc elements having non-zero + length specifiers. + + (3) If the caller passes the value GSS_C_NO_BINDINGS instead of + a valid channel bindings structure, the Bnd field shall be set + to 16 zero-valued bytes. + + In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) + from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, + GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set + as the logical AND of the initiator's corresponding request flag to + GSS_Init_sec_context() and a Boolean indicator of whether that + optional service is available to GSS_Init_sec_context()'s caller. + GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding + context-level input indicator flags to GSS_Init_sec_context() exist, + shall each be set to indicate whether their respective per-message + protection services are available for use on the context being + established. + + When input source address channel binding values are provided by a + caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the + source address specifier value within the input structure is + GSS_C_NULL_ADDRTYPE), and the corresponding token received from the + context's peer bears address restrictions, it is recommended that an + implementation of the Kerberos V5 GSS-API mechanism should check that + the source address as provided by the caller matches that in the + received token, and should return the GSS_S_BAD_BINDINGS major_status + value if a mismatch is detected. Note: discussion is ongoing about + the strength of recommendation to be made in this area, and on the + circumstances under which such a recommendation should be applicable; + implementors are therefore advised that changes on this matter may be + included in subsequent versions of this specification. + +1.1.2. Response Tokens + + A context establishment sequence based on the Kerberos V5 mechanism + will perform one-way authentication (without confirmation or any + return token from target to initiator in response to the initiator's + KRB_AP_REQ) if the mutual_req bit is not set in the application's + call to GSS_Init_sec_context(). Applications requiring confirmation + that their authentication was successful should request mutual + authentication, resulting in a "mutual-required" indication within + KRB_AP_REQ APoptions and the setting of the mutual_req bit in the + + + +Linn Standards Track [Page 5] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + flags field of the authenticator checksum. In response to such a + request, the context target will reply to the initiator with a token + containing either a KRB_AP_REP or KRB_ERROR, completing the mutual + context establishment exchange. + + Relevant KRB_AP_REP syntax is as follows: + + AP-REP ::= [APPLICATION 15] SEQUENCE { + pvno [0] INTEGER, -- represents Kerberos V5 + msg-type [1] INTEGER, -- represents KRB_AP_REP + enc-part [2] EncryptedData + } + + EncAPRepPart ::= [APPLICATION 27] SEQUENCE { + ctime [0] KerberosTime, + cusec [1] INTEGER, + subkey [2] EncryptionKey OPTIONAL, + seq-number [3] INTEGER OPTIONAL + } + + The optional seq-number element within the AP-REP's EncAPRepPart + shall be included. + + The syntax of KRB_ERROR is as follows: + + KRB-ERROR ::= [APPLICATION 30] SEQUENCE { + pvno[0] INTEGER, + msg-type[1] INTEGER, + ctime[2] KerberosTime OPTIONAL, + cusec[3] INTEGER OPTIONAL, + stime[4] KerberosTime, + susec[5] INTEGER, + error-code[6] INTEGER, + crealm[7] Realm OPTIONAL, + cname[8] PrincipalName OPTIONAL, + realm[9] Realm, -- Correct realm + sname[10] PrincipalName, -- Correct name + e-text[11] GeneralString OPTIONAL, + e-data[12] OCTET STRING OPTIONAL + } + + Values to be transferred in the error-code field of a KRB-ERROR + message are defined in [RFC-1510], not in this specification. + + + + + + + + +Linn Standards Track [Page 6] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +1.2. Per-Message and Context Deletion Tokens + + Three classes of tokens are defined in this section: "MIC" tokens, + emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed + by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, + emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by + calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion + tokens, emitted by calls to GSS_Delete_sec_context() and consumed by + calls to GSS_Process_context_token(). Note: References to GSS-API + per-message routines in the remainder of this specification will be + based on those routines' newer recommended names rather than those + names' predecessors. + + Several variants of cryptographic keys are used in generation and + processing of per-message tokens: + + (1) context key: uses Kerberos session key (or subkey, if + present in authenticator emitted by context initiator) directly + + (2) confidentiality key: forms variant of context key by + exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. + + (3) MD2.5 seed key: forms variant of context key by reversing + the bytes of the context key (i.e. if the original key is the + 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key + will be {hh, gg, ff, ee, dd, cc, bb, aa}). + +1.2.1. Per-message Tokens - MIC + +Use of the GSS_GetMIC() call yields a token, separate from the user +data being protected, which can be used to verify the integrity of +that data as received. The token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_GetMIC() contain + the hex value 01 01 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + + + + +Linn Standards Track [Page 7] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.1.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the data field, logically prepended by the first + 8 bytes of the plaintext packet header. The resulting value binds + the data to the packet type and signature algorithm identifier + fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + [RFC-1321] hash over the plaintext data, and then computing a DES-CBC + MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is + computed per [FIPS-PUB-113], employing the context key and a zero IV. + The 8-byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e. if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically prepended to the to-be-signed data. A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. Note 1: we refer to + this algorithm informally as "MD2.5" to connote the fact that it uses + half of the 128 bits generated by MD5; use of only a subset of the + MD5 bits is intended to protect against the prospect that data could + be postfixed to an existing message with corresponding modifications + being made to the checksum. Note 2: This algorithm is fairly novel + and has received more limited evaluation than that to which other + integrity algorithms have been subjected. An initial, limited + evaluation indicates that it may be significantly weaker than DES MAC + MD5. + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext data per [FIPS-PUB-113], employing the context key and a + zero IV. Padding procedures to accomodate plaintext data lengths + which may not be integral multiples of 8 bytes are defined in [FIPS- + PUB-113]. The result is an 8-byte value, which is stored in the + SGN_CKSUM field. Support for this algorithm may not be present in + all implementations. + +1.2.1.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + + + +Linn Standards Track [Page 8] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). The + field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the previously calculated SGN_CKSUM + field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence number is incremented by one. + + The receiver of the token will first verify the SGN_CKSUM field. If + valid, the sequence number field may be decrypted and compared to the + expected sequence number. The repetition of the (effectively 1-bit) + direction indicator within the sequence number field provides + redundancy so that the receiver may verify that the decryption + succeeded. + + Since the checksum computation is used as an IV to the sequence + number decryption, attempts to splice a checksum and sequence number + from different messages will be detected. The direction indicator + will detect packets that have been maliciously reflected. + + The sequence number provides a basis for detection of replayed + tokens. Replay detection can be performed using state information + retained on received sequence numbers, interpreted in conjunction + with the security context on which they arrive. + + Provision of per-message replay and out-of-sequence detection + services is optional for implementations of the Kerberos V5 GSS-API + mechanism. Further, it is recommended that implementations of the + Kerberos V5 GSS-API mechanism which offer these services should honor + a caller's request that the services be disabled on a context. + Specifically, if replay_det_req_flag is input FALSE, replay_det_state + should be returned FALSE and the GSS_DUPLICATE_TOKEN and + GSS_OLD_TOKEN stati should not be indicated as a result of duplicate + detection when tokens are processed; if sequence_req_flag is input + FALSE, sequence_state should be returned FALSE and + GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should + not be indicated as a result of out-of-sequence detection when tokens + are processed. + +1.2.2. Per-message Tokens - Wrap + + Use of the GSS_Wrap() call yields a token which encapsulates the + input user data (optionally encrypted) along with associated + integrity check quantities. The token emitted by GSS_Wrap() consists + of an integrity header whose format is identical to that emitted by + GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), + followed by a body portion that contains either the plaintext data + + + +Linn Standards Track [Page 9] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (if SEAL_ALG = ff ff) or encrypted data for any other supported value + of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and + means that DES-CBC encryption is being used to protect the data. + + The GSS_Wrap() token has the following format: + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by GSS_Wrap() contain + the hex value 02 01 in this field. + 2..3 SGN_ALG Checksum algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..5 SEAL_ALG ff ff - none + 00 00 - DES + 6..7 Filler Contains ff ff + 8..15 SND_SEQ Encrypted sequence number field. + 16..23 SGN_CKSUM Checksum of plaintext padded data, + calculated according to algorithm + specified in SGN_ALG field. + 24..last Data encrypted or plaintext padded data + + GSS-API tokens must be encapsulated within the higher-level protocol + by the application; no embedded length field is necessary. + +1.2.2.1. Checksum + + Checksum calculation procedure (common to all algorithms): Checksums + are calculated over the plaintext padded data field, logically + prepended by the first 8 bytes of the plaintext packet header. The + resulting signature binds the data to the packet type, protocol + version, and signature algorithm identifier fields. + + DES MAC MD5 algorithm: The checksum is formed by computing an MD5 + hash over the plaintext padded data, and then computing a DES-CBC MAC + on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed + per [FIPS-PUB-113], employing the context key and a zero IV. The 8- + byte result is stored in the SGN_CKSUM field. + + MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a + 16-byte zero-block, using a zero IV and a key formed by reversing the + bytes of the context key (i.e., if the original key is the 8-byte + sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be + {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is + logically pre-pended to the "to-be-signed data". A standard MD5 + checksum is calculated over the combined data, and the first 8 bytes + of the result are stored in the SGN_CKSUM field. + + + +Linn Standards Track [Page 10] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the + plaintext padded data per [FIPS-PUB-113], employing the context key + and a zero IV. The plaintext padded data is already assured to be an + integral multiple of 8 bytes; no additional padding is required or + applied in order to accomplish MAC calculation. The result is an 8- + byte value, which is stored in the SGN_CKSUM field. Support for this + lgorithm may not be present in all implementations. + +1.2.2.2. Sequence Number + + Sequence number field: The 8 byte plaintext sequence number field is + formed from the sender's four-byte sequence number as follows. If + the four bytes of the sender's sequence number are named s0, s1, s2 + and s3 (from least to most significant), the plaintext sequence + number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, + di), where 'di' is the direction-indicator (Hex 0 - sender is the + context initiator, Hex FF - sender is the context acceptor). + + The field is then DES-CBC encrypted using the context key and an IV + formed from the first 8 bytes of the SEAL_CKSUM field. + + After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's + sequence numbers are incremented by one. + +1.2.2.3. Padding + + Data padding: Before encryption and/or signature calculation, + plaintext data is padded to the next highest multiple of 8 bytes, by + appending between 1 and 8 bytes, the value of each such byte being + the total number of pad bytes. For example, given data of length 20 + bytes, four pad bytes will be appended, and each byte will contain + the hex value 04. An 8-byte random confounder is prepended to the + data, and signatures are calculated over the resulting padded + plaintext. + + After padding, the data is encrypted according to the algorithm + specified in the SEAL_ALG field. For SEAL_ALG=DES (the only non-null + algorithm currently supported), the data is encrypted using DES-CBC, + with an IV of zero. The key used is derived from the established + context key by XOR-ing the context key with the hexadecimal constant + f0f0f0f0f0f0f0f0. + +1.2.3. Context deletion token + + The token emitted by GSS_Delete_sec_context() is based on the packet + format for tokens emitted by GSS_GetMIC(). The context-deletion + token has the following format: + + + + +Linn Standards Track [Page 11] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Byte no Name Description + 0..1 TOK_ID Identification field. + Tokens emitted by + GSS_Delete_sec_context() contain + the hex value 01 02 in this field. + 2..3 SGN_ALG Integrity algorithm indicator. + 00 00 - DES MAC MD5 + 01 00 - MD2.5 + 02 00 - DES MAC + 4..7 Filler Contains ff ff ff ff + 8..15 SND_SEQ Sequence number field. + 16..23 SGN_CKSUM Checksum of "to-be-signed data", + calculated according to algorithm + specified in SGN_ALG field. + + SGN_ALG and SND_SEQ will be calculated as for tokens emitted by + GSS_GetMIC(). The SGN_CKSUM will be calculated as for tokens emitted + by GSS_GetMIC(), except that the user-data component of the "to-be- + signed" data will be a zero-length string. + +2. Name Types and Object Identifiers + + This section discusses the name types which may be passed as input to + the Kerberos V5 GSS-API mechanism's GSS_Import_name() call, and their + associated identifier values. It defines interface elements in + support of portability, and assumes use of C language bindings per + RFC-1509. In addition to specifying OID values for name type + identifiers, symbolic names are included and recommended to GSS-API + implementors in the interests of convenience to callers. It is + understood that not all implementations of the Kerberos V5 GSS-API + mechanism need support all name types in this list, and that + additional name forms will likely be added to this list over time. + Further, the definitions of some or all name types may later migrate + to other, mechanism-independent, specifications. The occurrence of a + name type in this specification is specifically not intended to + suggest that the type may be supported only by an implementation of + the Kerberos V5 mechanism. In particular, the occurrence of the + string "_KRB5_" in the symbolic name strings constitutes a means to + unambiguously register the name strings, avoiding collision with + other documents; it is not meant to limit the name types' usage or + applicability. + + For purposes of clarification to GSS-API implementors, this section's + discussion of some name forms describes means through which those + forms can be supported with existing Kerberos technology. These + discussions are not intended to preclude alternative implementation + strategies for support of the name forms within Kerberos mechanisms + or mechanisms based on other technologies. To enhance application + + + +Linn Standards Track [Page 12] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + portability, implementors of mechanisms are encouraged to support + name forms as defined in this section, even if their mechanisms are + independent of Kerberos V5. + +2.1. Mandatory Name Forms + + This section discusses name forms which are to be supported by all + conformant implementations of the Kerberos V5 GSS-API mechanism. + +2.1.1. Kerberos Principal Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + krb5(2) krb5_name(1)}. The recommended symbolic name for this type + is "GSS_KRB5_NT_PRINCIPAL_NAME". + + This name type corresponds to the single-string representation of a + Kerberos name. (Within the MIT Kerberos V5 implementation, such + names are parseable with the krb5_parse_name() function.) The + elements included within this name representation are as follows, + proceeding from the beginning of the string: + + (1) One or more principal name components; if more than one + principal name component is included, the components are + separated by `/`. Arbitrary octets may be included within + principal name components, with the following constraints and + special considerations: + + (1a) Any occurrence of the characters `@` or `/` within a + name component must be immediately preceded by the `\` + quoting character, to prevent interpretation as a component + or realm separator. + + (1b) The ASCII newline, tab, backspace, and null characters + may occur directly within the component or may be + represented, respectively, by `\n`, `\t`, `\b`, or `\0`. + + (1c) If the `\` quoting character occurs outside the contexts + described in (1a) and (1b) above, the following character is + interpreted literally. As a special case, this allows the + doubled representation `\\` to represent a single occurrence + of the quoting character. + + (1d) An occurrence of the `\` quoting character as the last + character of a component is illegal. + + + + + + +Linn Standards Track [Page 13] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + (2) Optionally, a `@` character, signifying that a realm name + immediately follows. If no realm name element is included, the + local realm name is assumed. The `/` , `:`, and null characters + may not occur within a realm name; the `@`, newline, tab, and + backspace characters may be included using the quoting + conventions described in (1a), (1b), and (1c) above. + +2.1.2. Host-Based Service Name Form + + This name form has been incorporated at the mechanism-independent + GSS-API level as of GSS-API, Version 2. This subsection retains the + Object Identifier and symbolic name assignments previously made at + the Kerberos V5 GSS-API mechanism level, and adopts the definition as + promoted to the mechanism-independent level. + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) service_name(4)}. The previously recommended symbolic + name for this type is "GSS_KRB5_NT_HOSTBASED_SERVICE_NAME". The + currently preferred symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + This name type is used to represent services associated with host + computers. This name form is constructed using two elements, + "service" and "hostname", as follows: + + service@hostname + + When a reference to a name of this type is resolved, the "hostname" + is canonicalized by attempting a DNS lookup and using the fully- + qualified domain name which is returned, or by using the "hostname" + as provided if the DNS lookup fails. The canonicalization operation + also maps the host's name into lower-case characters. + + The "hostname" element may be omitted. If no "@" separator is + included, the entire name is interpreted as the service specifier, + with the "hostname" defaulted to the canonicalized name of the local + host. + + Values for the "service" element will be registered with the IANA. + +2.1.3. Exported Name Object Form for Kerberos V5 Mechanism + + Support for this name form is not required for GSS-V1 + implementations, but will be required for use in conjunction with the + GSS_Export_name() call planned for GSS-API Version 2. Use of this + name form will be signified by a "GSS-API Exported Name Object" OID + value which will be defined at the mechanism-independent level for + + + +Linn Standards Track [Page 14] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + GSS-API Version 2. + + This name type represents a self-describing object, whose framing + structure will be defined at the mechanism-independent level for + GSS-API Version 2. When generated by the Kerberos V5 mechanism, the + Mechanism OID within the exportable name shall be that of the + Kerberos V5 mechanism. The name component within the exportable name + shall be a contiguous string with structure as defined for the + Kerberos Principal Name Form. + + In order to achieve a distinguished encoding for comparison purposes, + the following additional constraints are imposed on the export + operation: + + (1) all occurrences of the characters `@`, `/`, and `\` within + principal components or realm names shall be quoted with an + immediately-preceding `\`. + + (2) all occurrences of the null, backspace, tab, or newline + characters within principal components or realm names will be + represented, respectively, with `\0`, `\b`, `\t`, or `\n`. + + (3) the `\` quoting character shall not be emitted within an + exported name except to accomodate cases (1) and (2). + +2.2. Optional Name Forms + + This section discusses additional name forms which may optionally be + supported by implementations of the Kerberos V5 GSS-API mechanism. + It is recognized that some of the name forms cited here are derived + from UNIX(tm) operating system platforms; some listed forms may be + irrelevant to non-UNIX platforms, and definition of additional forms + corresponding to such platforms may also be appropriate. It is also + recognized that OS-specific functions outside GSS-API are likely to + exist in order to perform translations among these forms, and that + GSS-API implementations supporting these forms may themselves be + layered atop such OS-specific functions. Inclusion of this support + within GSS-API implementations is intended as a convenience to + applications. + +2.2.1. User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended symbolic name for this + type is "GSS_KRB5_NT_USER_NAME". + + This name type is used to indicate a named user on a local system. + + + +Linn Standards Track [Page 15] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + Its interpretation is OS-specific. This name form is constructed as: + + username + + Assuming that users' principal names are the same as their local + operating system names, an implementation of GSS_Import_name() based + on Kerberos V5 technology can process names of this form by + postfixing an "@" sign and the name of the local realm. + +2.2.2. Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_MACHINE_UID_NAME". + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant uid_t, represented in host byte + order. The GSS_Import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +2.2.3. String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_KRB5_NT_STRING_UID_NAME". + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the uid_t. + +3. Credentials Management + + The Kerberos V5 protocol uses different credentials (in the GSSAPI + sense) for initiating and accepting security contexts. Normal + clients receive a ticket-granting ticket (TGT) and an associated + session key at "login" time; the pair of a TGT and its corresponding + session key forms a credential which is suitable for initiating + security contexts. A ticket-granting ticket, its session key, and + any other (ticket, key) pairs obtained through use of the ticket- + granting-ticket, are typically stored in a Kerberos V5 credentials + cache, sometimes known as a ticket file. + + + + +Linn Standards Track [Page 16] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + The encryption key used by the Kerberos server to seal tickets for a + particular application service forms the credentials suitable for + accepting security contexts. These service keys are typically stored + in a Kerberos V5 key table, or srvtab file. In addition to their use + as accepting credentials, these service keys may also be used to + obtain initiating credentials for their service principal. + + The Kerberos V5 mechanism's credential handle may contain references + to either or both types of credentials. It is a local matter how the + Kerberos V5 mechanism implementation finds the appropriate Kerberos + V5 credentials cache or key table. + + However, when the Kerberos V5 mechanism attempts to obtain initiating + credentials for a service principal which are not available in a + credentials cache, and the key for that service principal is + available in a Kerberos V5 key table, the mechanism should use the + service key to obtain initiating credentials for that service. This + should be accomplished by requesting a ticket-granting-ticket from + the Kerberos Key Distribution Center (KDC), and decrypting the KDC's + reply using the service key. + +4. Parameter Definitions + + This section defines parameter values used by the Kerberos V5 GSS-API + mechanism. It defines interface elements in support of portability, + and assumes use of C language bindings per RFC-1509. + +4.1. Minor Status Codes + + This section recommends common symbolic names for minor_status values + to be returned by the Kerberos V5 GSS-API mechanism. Use of these + definitions will enable independent implementors to enhance + application portability across different implementations of the + mechanism defined in this specification. (In all cases, + implementations of GSS_Display_status() will enable callers to + convert minor_status indicators to text representations.) Each + implementation should make available, through include files or other + means, a facility to translate these symbolic names into the concrete + values which a particular GSS-API implementation uses to represent + the minor_status values specified in this section. + + It is recognized that this list may grow over time, and that the need + for additional minor_status codes specific to particular + implementations may arise. It is recommended, however, that + implementations should return a minor_status value as defined on a + mechanism-wide basis within this section when that code is accurately + representative of reportable status rather than using a separate, + implementation-defined code. + + + +Linn Standards Track [Page 17] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +4.1.1. Non-Kerberos-specific codes + + GSS_KRB5_S_G_BAD_SERVICE_NAME + /* "No @ in SERVICE-NAME name string" */ + GSS_KRB5_S_G_BAD_STRING_UID + /* "STRING-UID-NAME contains nondigits" */ + GSS_KRB5_S_G_NOUSER + /* "UID does not resolve to username" */ + GSS_KRB5_S_G_VALIDATE_FAILED + /* "Validation error" */ + GSS_KRB5_S_G_BUFFER_ALLOC + /* "Couldn't allocate gss_buffer_t data" */ + GSS_KRB5_S_G_BAD_MSG_CTX + /* "Message context invalid" */ + GSS_KRB5_S_G_WRONG_SIZE + /* "Buffer is the wrong size" */ + GSS_KRB5_S_G_BAD_USAGE + /* "Credential usage type is unknown" */ + GSS_KRB5_S_G_UNKNOWN_QOP + /* "Unknown quality of protection specified" */ + +4.1.2. Kerberos-specific-codes + + GSS_KRB5_S_KG_CCACHE_NOMATCH + /* "Principal in credential cache does not match desired name" */ + GSS_KRB5_S_KG_KEYTAB_NOMATCH + /* "No principal in keytab matches desired name" */ + GSS_KRB5_S_KG_TGT_MISSING + /* "Credential cache has no TGT" */ + GSS_KRB5_S_KG_NO_SUBKEY + /* "Authenticator has no subkey" */ + GSS_KRB5_S_KG_CONTEXT_ESTABLISHED + /* "Context is already fully established" */ + GSS_KRB5_S_KG_BAD_SIGN_TYPE + /* "Unknown signature type in token" */ + GSS_KRB5_S_KG_BAD_LENGTH + /* "Invalid field length in token" */ + GSS_KRB5_S_KG_CTX_INCOMPLETE + /* "Attempt to use incomplete security context" */ + +4.2. Quality of Protection Values + + This section defines Quality of Protection (QOP) values to be used + with the Kerberos V5 GSS-API mechanism as input to GSS_Wrap() and + GSS_GetMIC() routines in order to select among alternate integrity + and confidentiality algorithms. Additional QOP values may be added in + future versions of this specification. Non-overlapping bit positions + are and will be employed in order that both integrity and + + + +Linn Standards Track [Page 18] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + + confidentiality QOP may be selected within a single parameter, via + inclusive-OR of the specified integrity and confidentiality values. + +4.2.1. Integrity Algorithms + + The following Quality of Protection (QOP) values are currently + defined for the Kerberos V5 GSS-API mechanism, and are used to select + among alternate integrity checking algorithms. + + GSS_KRB5_INTEG_C_QOP_MD5 (numeric value: 1) + /* Integrity using partial MD5 ("MD2.5") of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MD5 (numeric value: 2) + /* Integrity using DES MAC of MD5 of plaintext */ + + GSS_KRB5_INTEG_C_QOP_DES_MAC (numeric value: 3) + /* Integrity using DES MAC of plaintext */ + +4.2.2. Confidentiality Algorithms + + Only one confidentiality QOP value is currently defined for the + Kerberos V5 GSS-API mechanism: + + GSS_KRB5_CONF_C_QOP_DES (numeric value: 0) + /* Confidentiality with DES */ + + Note: confidentiality QOP should be indicated only by GSS-API calls + capable of providing confidentiality services. If non-zero + confidentiality QOP values are defined in future to represent + different algorithms, therefore, the bit positions containing those + values should be cleared before being returned by implementations of + GSS_GetMIC() and GSS_VerifyMIC(). + +4.3. Buffer Sizes + + All implementations of this specification shall be capable of + accepting buffers of at least 16 Kbytes as input to GSS_GetMIC(), + GSS_VerifyMIC(), and GSS_Wrap(), and shall be capable of accepting + the output_token generated by GSS_Wrap() for a 16 Kbyte input buffer + as input to GSS_Unwrap(). Support for larger buffer sizes is optional + but recommended. + + + + + + + + + + +Linn Standards Track [Page 19] + +RFC 1964 Kerberos Version 5 GSS-API June 1996 + + +5. Security Considerations + + Security issues are discussed throughout this memo. + +6. References + + + [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC + 1321, April 1992. + + [RFC-1508]: Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, September 1993. + + [RFC-1509]: Wray, J., "Generic Security Service Application Program + Interface: C-bindings", RFC 1509, September 1993. + + [RFC-1510]: Kohl, J., and C. Neuman, "The Kerberos Network + Authentication Service (V5)", RFC 1510, September 1993. + + [FIPS-PUB-113]: National Bureau of Standards, Federal Information + Processing Standard 113, "Computer Data Authentication", May 1985. + +AUTHOR'S ADDRESS + + John Linn + OpenVision Technologies + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.2245 + EMail: John.Linn@ov.com + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 20] + diff --git a/crypto/heimdal/doc/standardisation/rfc2078.txt b/crypto/heimdal/doc/standardisation/rfc2078.txt new file mode 100644 index 0000000..1dd1e4a --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc2078.txt @@ -0,0 +1,4763 @@ + + + + + + +Network Working Group J. Linn +Request for Comments: 2078 OpenVision Technologies +Category: Standards Track January 1997 +Obsoletes: 1508 + + + Generic Security Service Application Program Interface, Version 2 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The Generic Security Service Application Program Interface (GSS-API), + as defined in RFC-1508, provides security services to callers in a + generic fashion, supportable with a range of underlying mechanisms + and technologies and hence allowing source-level portability of + applications to different environments. This specification defines + GSS-API services and primitives at a level independent of underlying + mechanism and programming language environment, and is to be + complemented by other, related specifications: + + documents defining specific parameter bindings for particular + language environments + + documents defining token formats, protocols, and procedures to be + implemented in order to realize GSS-API services atop particular + security mechanisms + + This memo revises RFC-1508, making specific, incremental changes in + response to implementation experience and liaison requests. It is + intended, therefore, that this memo or a successor version thereto + will become the basis for subsequent progression of the GSS-API + specification on the standards track. + +Table of Contents + + 1: GSS-API Characteristics and Concepts.......................... 3 + 1.1: GSS-API Constructs.......................................... 6 + 1.1.1: Credentials.............................................. 6 + 1.1.1.1: Credential Constructs and Concepts...................... 6 + 1.1.1.2: Credential Management................................... 7 + 1.1.1.3: Default Credential Resolution........................... 8 + + + +Linn Standards Track [Page 1] + +RFC 2078 GSS-API January 1997 + + + 1.1.2: Tokens.................................................... 9 + 1.1.3: Security Contexts........................................ 10 + 1.1.4: Mechanism Types.......................................... 11 + 1.1.5: Naming................................................... 12 + 1.1.6: Channel Bindings......................................... 14 + 1.2: GSS-API Features and Issues................................ 15 + 1.2.1: Status Reporting......................................... 15 + 1.2.2: Per-Message Security Service Availability................. 17 + 1.2.3: Per-Message Replay Detection and Sequencing............... 18 + 1.2.4: Quality of Protection.................................... 20 + 1.2.5: Anonymity Support......................................... 21 + 1.2.6: Initialization............................................ 22 + 1.2.7: Per-Message Protection During Context Establishment....... 22 + 1.2.8: Implementation Robustness................................. 23 + 2: Interface Descriptions....................................... 23 + 2.1: Credential management calls................................ 25 + 2.1.1: GSS_Acquire_cred call.................................... 26 + 2.1.2: GSS_Release_cred call.................................... 28 + 2.1.3: GSS_Inquire_cred call.................................... 29 + 2.1.4: GSS_Add_cred call........................................ 31 + 2.1.5: GSS_Inquire_cred_by_mech call............................ 33 + 2.2: Context-level calls........................................ 34 + 2.2.1: GSS_Init_sec_context call................................ 34 + 2.2.2: GSS_Accept_sec_context call.............................. 40 + 2.2.3: GSS_Delete_sec_context call.............................. 44 + 2.2.4: GSS_Process_context_token call........................... 46 + 2.2.5: GSS_Context_time call.................................... 47 + 2.2.6: GSS_Inquire_context call................................. 47 + 2.2.7: GSS_Wrap_size_limit call................................. 49 + 2.2.8: GSS_Export_sec_context call.............................. 50 + 2.2.9: GSS_Import_sec_context call.............................. 52 + 2.3: Per-message calls.......................................... 53 + 2.3.1: GSS_GetMIC call.......................................... 54 + 2.3.2: GSS_VerifyMIC call....................................... 55 + 2.3.3: GSS_Wrap call............................................ 56 + 2.3.4: GSS_Unwrap call.......................................... 58 + 2.4: Support calls.............................................. 59 + 2.4.1: GSS_Display_status call.................................. 60 + 2.4.2: GSS_Indicate_mechs call.................................. 60 + 2.4.3: GSS_Compare_name call.................................... 61 + 2.4.4: GSS_Display_name call.................................... 62 + 2.4.5: GSS_Import_name call..................................... 63 + 2.4.6: GSS_Release_name call.................................... 64 + 2.4.7: GSS_Release_buffer call.................................. 65 + 2.4.8: GSS_Release_OID_set call................................. 65 + 2.4.9: GSS_Create_empty_OID_set call............................ 66 + 2.4.10: GSS_Add_OID_set_member call.............................. 67 + 2.4.11: GSS_Test_OID_set_member call............................. 67 + + + +Linn Standards Track [Page 2] + +RFC 2078 GSS-API January 1997 + + + 2.4.12: GSS_Release_OID call..................................... 68 + 2.4.13: GSS_OID_to_str call...................................... 68 + 2.4.14: GSS_Str_to_OID call...................................... 69 + 2.4.15: GSS_Inquire_names_for_mech call.......................... 69 + 2.4.16: GSS_Inquire_mechs_for_name call.......................... 70 + 2.4.17: GSS_Canonicalize_name call............................... 71 + 2.4.18: GSS_Export_name call..................................... 72 + 2.4.19: GSS_Duplicate_name call.................................. 73 + 3: Data Structure Definitions for GSS-V2 Usage................... 73 + 3.1: Mechanism-Independent Token Format.......................... 74 + 3.2: Mechanism-Independent Exported Name Object Format........... 77 + 4: Name Type Definitions......................................... 77 + 4.1: Host-Based Service Name Form................................ 77 + 4.2: User Name Form.............................................. 78 + 4.3: Machine UID Form............................................ 78 + 4.4: String UID Form............................................. 79 + 5: Mechanism-Specific Example Scenarios......................... 79 + 5.1: Kerberos V5, single-TGT..................................... 79 + 5.2: Kerberos V5, double-TGT..................................... 80 + 5.3: X.509 Authentication Framework............................. 81 + 6: Security Considerations...................................... 82 + 7: Related Activities........................................... 82 + Appendix A: Mechanism Design Constraints......................... 83 + Appendix B: Compatibility with GSS-V1............................ 83 + +1: GSS-API Characteristics and Concepts + + GSS-API operates in the following paradigm. A typical GSS-API caller + is itself a communications protocol, calling on GSS-API in order to + protect its communications with authentication, integrity, and/or + confidentiality security services. A GSS-API caller accepts tokens + provided to it by its local GSS-API implementation and transfers the + tokens to a peer on a remote system; that peer passes the received + tokens to its local GSS-API implementation for processing. The + security services available through GSS-API in this fashion are + implementable (and have been implemented) over a range of underlying + mechanisms based on secret-key and public-key cryptographic + technologies. + + The GSS-API separates the operations of initializing a security + context between peers, achieving peer entity authentication (This + security service definition, and other definitions used in this + document, corresponds to that provided in International Standard ISO + 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and + GSS_Accept_sec_context() calls), from the operations of providing + per-message data origin authentication and data integrity protection + (GSS_GetMIC() and GSS_VerifyMIC() calls) for messages subsequently + transferred in conjunction with that context. When establishing a + + + +Linn Standards Track [Page 3] + +RFC 2078 GSS-API January 1997 + + + security context, the GSS-API enables a context initiator to + optionally permit its credentials to be delegated, meaning that the + context acceptor may initiate further security contexts on behalf of + the initiating caller. Per-message GSS_Wrap() and GSS_Unwrap() calls + provide the data origin authentication and data integrity services + which GSS_GetMIC() and GSS_VerifyMIC() offer, and also support + selection of confidentiality services as a caller option. Additional + calls provide supportive functions to the GSS-API's users. + + The following paragraphs provide an example illustrating the + dataflows involved in use of the GSS-API by a client and server in a + mechanism-independent fashion, establishing a security context and + transferring a protected message. The example assumes that credential + acquisition has already been completed. The example assumes that the + underlying authentication technology is capable of authenticating a + client to a server using elements carried within a single token, and + of authenticating the server to the client (mutual authentication) + with a single returned token; this assumption holds for presently- + documented CAT mechanisms but is not necessarily true for other + cryptographic technologies and associated protocols. + + The client calls GSS_Init_sec_context() to establish a security + context to the server identified by targ_name, and elects to set the + mutual_req_flag so that mutual authentication is performed in the + course of context establishment. GSS_Init_sec_context() returns an + output_token to be passed to the server, and indicates + GSS_S_CONTINUE_NEEDED status pending completion of the mutual + authentication sequence. Had mutual_req_flag not been set, the + initial call to GSS_Init_sec_context() would have returned + GSS_S_COMPLETE status. The client sends the output_token to the + server. + + The server passes the received token as the input_token parameter to + GSS_Accept_sec_context(). GSS_Accept_sec_context indicates + GSS_S_COMPLETE status, provides the client's authenticated identity + in the src_name result, and provides an output_token to be passed to + the client. The server sends the output_token to the client. + + The client passes the received token as the input_token parameter to + a successor call to GSS_Init_sec_context(), which processes data + included in the token in order to achieve mutual authentication from + the client's viewpoint. This call to GSS_Init_sec_context() returns + GSS_S_COMPLETE status, indicating successful mutual authentication + and the completion of context establishment for this example. + + The client generates a data message and passes it to GSS_Wrap(). + GSS_Wrap() performs data origin authentication, data integrity, and + (optionally) confidentiality processing on the message and + + + +Linn Standards Track [Page 4] + +RFC 2078 GSS-API January 1997 + + + encapsulates the result into output_message, indicating + GSS_S_COMPLETE status. The client sends the output_message to the + server. + + The server passes the received message to GSS_Unwrap(). GSS_Unwrap() + inverts the encapsulation performed by GSS_Wrap(), deciphers the + message if the optional confidentiality feature was applied, and + validates the data origin authentication and data integrity checking + quantities. GSS_Unwrap() indicates successful validation by + returning GSS_S_COMPLETE status along with the resultant + output_message. + + For purposes of this example, we assume that the server knows by + out-of-band means that this context will have no further use after + one protected message is transferred from client to server. Given + this premise, the server now calls GSS_Delete_sec_context() to flush + context-level information. Optionally, the server-side application + may provide a token buffer to GSS_Delete_sec_context(), to receive a + context_token to be transferred to the client in order to request + that client-side context-level information be deleted. + + If a context_token is transferred, the client passes the + context_token to GSS_Process_context_token(), which returns + GSS_S_COMPLETE status after deleting context-level information at the + client system. + + The GSS-API design assumes and addresses several basic goals, + including: + + Mechanism independence: The GSS-API defines an interface to + cryptographically implemented strong authentication and other + security services at a generic level which is independent of + particular underlying mechanisms. For example, GSS-API-provided + services can be implemented by secret-key technologies (e.g., + Kerberos) or public-key approaches (e.g., X.509). + + Protocol environment independence: The GSS-API is independent of + the communications protocol suites with which it is employed, + permitting use in a broad range of protocol environments. In + appropriate environments, an intermediate implementation "veneer" + which is oriented to a particular communication protocol (e.g., + Remote Procedure Call (RPC)) may be interposed between + applications which call that protocol and the GSS-API, thereby + invoking GSS-API facilities in conjunction with that protocol's + communications invocations. + + Protocol association independence: The GSS-API's security context + construct is independent of communications protocol association + + + +Linn Standards Track [Page 5] + +RFC 2078 GSS-API January 1997 + + + constructs. This characteristic allows a single GSS-API + implementation to be utilized by a variety of invoking protocol + modules on behalf of those modules' calling applications. GSS-API + services can also be invoked directly by applications, wholly + independent of protocol associations. + + Suitability to a range of implementation placements: GSS-API + clients are not constrained to reside within any Trusted Computing + Base (TCB) perimeter defined on a system where the GSS-API is + implemented; security services are specified in a manner suitable + to both intra-TCB and extra-TCB callers. + +1.1: GSS-API Constructs + + This section describes the basic elements comprising the GSS-API. + +1.1.1: Credentials + +1.1.1.1: Credential Constructs and Concepts + + Credentials provide the prerequisites which permit GSS-API peers to + establish security contexts with each other. A caller may designate + that the credential elements which are to be applied for context + initiation or acceptance be selected by default. Alternately, those + GSS-API callers which need to make explicit selection of particular + credentials structures may make references to those credentials + through GSS-API-provided credential handles ("cred_handles"). In all + cases, callers' credential references are indirect, mediated by GSS- + API implementations and not requiring callers to access the selected + credential elements. + + A single credential structure may be used to initiate outbound + contexts and to accept inbound contexts. Callers needing to operate + in only one of these modes may designate this fact when credentials + are acquired for use, allowing underlying mechanisms to optimize + their processing and storage requirements. The credential elements + defined by a particular mechanism may contain multiple cryptographic + keys, e.g., to enable authentication and message encryption to be + performed with different algorithms. + + A GSS-API credential structure may contain multiple credential + elements, each containing mechanism-specific information for a + particular underlying mechanism (mech_type), but the set of elements + within a given credential structure represent a common entity. A + credential structure's contents will vary depending on the set of + mech_types supported by a particular GSS-API implementation. Each + credential element identifies the data needed by its mechanism in + order to establish contexts on behalf of a particular principal, and + + + +Linn Standards Track [Page 6] + +RFC 2078 GSS-API January 1997 + + + may contain separate credential references for use in context + initiation and context acceptance. Multiple credential elements + within a given credential having overlapping combinations of + mechanism, usage mode, and validity period are not permitted. + + Commonly, a single mech_type will be used for all security contexts + established by a particular initiator to a particular target. A major + motivation for supporting credential sets representing multiple + mech_types is to allow initiators on systems which are equipped to + handle multiple types to initiate contexts to targets on other + systems which can accommodate only a subset of the set supported at + the initiator's system. + +1.1.1.2: Credential Management + + It is the responsibility of underlying system-specific mechanisms and + OS functions below the GSS-API to ensure that the ability to acquire + and use credentials associated with a given identity is constrained + to appropriate processes within a system. This responsibility should + be taken seriously by implementors, as the ability for an entity to + utilize a principal's credentials is equivalent to the entity's + ability to successfully assert that principal's identity. + + Once a set of GSS-API credentials is established, the transferability + of that credentials set to other processes or analogous constructs + within a system is a local matter, not defined by the GSS-API. An + example local policy would be one in which any credentials received + as a result of login to a given user account, or of delegation of + rights to that account, are accessible by, or transferable to, + processes running under that account. + + The credential establishment process (particularly when performed on + behalf of users rather than server processes) is likely to require + access to passwords or other quantities which should be protected + locally and exposed for the shortest time possible. As a result, it + will often be appropriate for preliminary credential establishment to + be performed through local means at user login time, with the + result(s) cached for subsequent reference. These preliminary + credentials would be set aside (in a system-specific fashion) for + subsequent use, either: + + to be accessed by an invocation of the GSS-API GSS_Acquire_cred() + call, returning an explicit handle to reference that credential + + to comprise default credential elements to be installed, and to be + used when default credential behavior is requested on behalf of a + process + + + + +Linn Standards Track [Page 7] + +RFC 2078 GSS-API January 1997 + + +1.1.1.3: Default Credential Resolution + + The gss_init_sec_context and gss_accept_sec_context routines allow + the value GSS_C_NO_CREDENTIAL to be specified as their credential + handle parameter. This special credential-handle indicates a desire + by the application to act as a default principal. While individual + GSS-API implementations are free to determine such default behavior + as appropriate to the mechanism, the following default behavior by + these routines is recommended for portability: + + GSS_Init_sec_context: + + (i) If there is only a single principal capable of initiating + security contexts that the application is authorized to act on + behalf of, then that principal shall be used, otherwise + + (ii) If the platform maintains a concept of a default network- + identity, and if the application is authorized to act on behalf of + that identity for the purpose of initiating security contexts, + then the principal corresponding to that identity shall be used, + otherwise + + (iii) If the platform maintains a concept of a default local + identity, and provides a means to map local identities into + network-identities, and if the application is authorized to act on + behalf of the network-identity image of the default local identity + for the purpose of initiating security contexts, then the + principal corresponding to that identity shall be used, otherwise + + (iv) A user-configurable default identity should be used. + + GSS_Accept_sec_context: + + (i) If there is only a single authorized principal identity + capable of accepting security contexts, then that principal shall + be used, otherwise + + (ii) If the mechanism can determine the identity of the target + principal by examining the context-establishment token, and if the + accepting application is authorized to act as that principal for + the purpose of accepting security contexts, then that principal + identity shall be used, otherwise + + (iii) If the mechanism supports context acceptance by any + principal, and mutual authentication was not requested, any + principal that the application is authorized to accept security + contexts under may be used, otherwise + + + + +Linn Standards Track [Page 8] + +RFC 2078 GSS-API January 1997 + + + (iv) A user-configurable default identity shall be used. + + The purpose of the above rules is to allow security contexts to be + established by both initiator and acceptor using the default behavior + wherever possible. Applications requesting default behavior are + likely to be more portable across mechanisms and platforms than ones + that use GSS_Acquire_cred to request a specific identity. + +1.1.2: Tokens + + Tokens are data elements transferred between GSS-API callers, and are + divided into two classes. Context-level tokens are exchanged in order + to establish and manage a security context between peers. Per-message + tokens relate to an established context and are exchanged to provide + protective security services (i.e., data origin authentication, + integrity, and optional confidentiality) for corresponding data + messages. + + The first context-level token obtained from GSS_Init_sec_context() is + required to indicate at its very beginning a globally-interpretable + mechanism identifier, i.e., an Object Identifier (OID) of the + security mechanism. The remaining part of this token as well as the + whole content of all other tokens are specific to the particular + underlying mechanism used to support the GSS-API. Section 3 of this + document provides, for designers of GSS-API support mechanisms, the + description of the header of the first context-level token which is + then followed by mechanism-specific information. + + Tokens' contents are opaque from the viewpoint of GSS-API callers. + They are generated within the GSS-API implementation at an end + system, provided to a GSS-API caller to be transferred to the peer + GSS-API caller at a remote end system, and processed by the GSS-API + implementation at that remote end system. Tokens may be output by + GSS-API calls (and should be transferred to GSS-API peers) whether or + not the calls' status indicators indicate successful completion. + Token transfer may take place in an in-band manner, integrated into + the same protocol stream used by the GSS-API callers for other data + transfers, or in an out-of-band manner across a logically separate + channel. + + Different GSS-API tokens are used for different purposes (e.g., + context initiation, context acceptance, protected message data on an + established context), and it is the responsibility of a GSS-API + caller receiving tokens to distinguish their types, associate them + with corresponding security contexts, and pass them to appropriate + GSS-API processing routines. Depending on the caller protocol + environment, this distinction may be accomplished in several ways. + + + + +Linn Standards Track [Page 9] + +RFC 2078 GSS-API January 1997 + + + The following examples illustrate means through which tokens' types + may be distinguished: + + - implicit tagging based on state information (e.g., all tokens on + a new association are considered to be context establishment + tokens until context establishment is completed, at which point + all tokens are considered to be wrapped data objects for that + context), + + - explicit tagging at the caller protocol level, + + - a hybrid of these approaches. + + Commonly, the encapsulated data within a token includes internal + mechanism-specific tagging information, enabling mechanism-level + processing modules to distinguish tokens used within the mechanism + for different purposes. Such internal mechanism-level tagging is + recommended to mechanism designers, and enables mechanisms to + determine whether a caller has passed a particular token for + processing by an inappropriate GSS-API routine. + + Development of GSS-API support primitives based on a particular + underlying cryptographic technique and protocol (i.e., conformant to + a specific GSS-API mechanism definition) does not necessarily imply + that GSS-API callers using that GSS-API mechanism will be able to + interoperate with peers invoking the same technique and protocol + outside the GSS-API paradigm, or with peers implementing a different + GSS-API mechanism based on the same underlying technology. The + format of GSS-API tokens defined in conjunction with a particular + mechanism, and the techniques used to integrate those tokens into + callers' protocols, may not be interoperable with the tokens used by + non-GSS-API callers of the same underlying technique. + +1.1.3: Security Contexts + + Security contexts are established between peers, using credentials + established locally in conjunction with each peer or received by + peers via delegation. Multiple contexts may exist simultaneously + between a pair of peers, using the same or different sets of + credentials. Coexistence of multiple contexts using different + credentials allows graceful rollover when credentials expire. + Distinction among multiple contexts based on the same credentials + serves applications by distinguishing different message streams in a + security sense. + + The GSS-API is independent of underlying protocols and addressing + structure, and depends on its callers to transport GSS-API-provided + data elements. As a result of these factors, it is a caller + + + +Linn Standards Track [Page 10] + +RFC 2078 GSS-API January 1997 + + + responsibility to parse communicated messages, separating GSS-API- + related data elements from caller-provided data. The GSS-API is + independent of connection vs. connectionless orientation of the + underlying communications service. + + No correlation between security context and communications protocol + association is dictated. (The optional channel binding facility, + discussed in Section 1.1.6 of this document, represents an + intentional exception to this rule, supporting additional protection + features within GSS-API supporting mechanisms.) This separation + allows the GSS-API to be used in a wide range of communications + environments, and also simplifies the calling sequences of the + individual calls. In many cases (depending on underlying security + protocol, associated mechanism, and availability of cached + information), the state information required for context setup can be + sent concurrently with initial signed user data, without interposing + additional message exchanges. + +1.1.4: Mechanism Types + + In order to successfully establish a security context with a target + peer, it is necessary to identify an appropriate underlying mechanism + type (mech_type) which both initiator and target peers support. The + definition of a mechanism embodies not only the use of a particular + cryptographic technology (or a hybrid or choice among alternative + cryptographic technologies), but also definition of the syntax and + semantics of data element exchanges which that mechanism will employ + in order to support security services. + + It is recommended that callers initiating contexts specify the + "default" mech_type value, allowing system-specific functions within + or invoked by the GSS-API implementation to select the appropriate + mech_type, but callers may direct that a particular mech_type be + employed when necessary. + + The means for identifying a shared mech_type to establish a security + context with a peer will vary in different environments and + circumstances; examples include (but are not limited to): + + use of a fixed mech_type, defined by configuration, within an + environment + + syntactic convention on a target-specific basis, through + examination of a target's name + + lookup of a target's name in a naming service or other database in + order to identify mech_types supported by that target + + + + +Linn Standards Track [Page 11] + +RFC 2078 GSS-API January 1997 + + + explicit negotiation between GSS-API callers in advance of + security context setup + + When transferred between GSS-API peers, mech_type specifiers (per + Section 3, represented as Object Identifiers (OIDs)) serve to qualify + the interpretation of associated tokens. (The structure and encoding + of Object Identifiers is defined in ISO/IEC 8824, "Specification of + Abstract Syntax Notation One (ASN.1)" and in ISO/IEC 8825, + "Specification of Basic Encoding Rules for Abstract Syntax Notation + One (ASN.1)".) Use of hierarchically structured OIDs serves to + preclude ambiguous interpretation of mech_type specifiers. The OID + representing the DASS MechType, for example, is 1.3.12.2.1011.7.5, + and that of the Kerberos V5 mechanism, once advanced to the level of + Proposed Standard, will be 1.2.840.113554.1.2.2. + +1.1.5: Naming + + The GSS-API avoids prescribing naming structures, treating the names + which are transferred across the interface in order to initiate and + accept security contexts as opaque objects. This approach supports + the GSS-API's goal of implementability atop a range of underlying + security mechanisms, recognizing the fact that different mechanisms + process and authenticate names which are presented in different + forms. Generalized services offering translation functions among + arbitrary sets of naming environments are outside the scope of the + GSS-API; availability and use of local conversion functions to + translate among the naming formats supported within a given end + system is anticipated. + + Different classes of name representations are used in conjunction + with different GSS-API parameters: + + - Internal form (denoted in this document by INTERNAL NAME), + opaque to callers and defined by individual GSS-API + implementations. GSS-API implementations supporting multiple + namespace types must maintain internal tags to disambiguate the + interpretation of particular names. A Mechanism Name (MN) is a + special case of INTERNAL NAME, guaranteed to contain elements + corresponding to one and only one mechanism; calls which are + guaranteed to emit MNs or which require MNs as input are so + identified within this specification. + + - Contiguous string ("flat") form (denoted in this document by + OCTET STRING); accompanied by OID tags identifying the namespace + to which they correspond. Depending on tag value, flat names may + or may not be printable strings for direct acceptance from and + presentation to users. Tagging of flat names allows GSS-API + callers and underlying GSS-API mechanisms to disambiguate name + + + +Linn Standards Track [Page 12] + +RFC 2078 GSS-API January 1997 + + + types and to determine whether an associated name's type is one + which they are capable of processing, avoiding aliasing problems + which could result from misinterpreting a name of one type as a + name of another type. + + - The GSS-API Exported Name Object, a special case of flat name + designated by a reserved OID value, carries a canonicalized form + of a name suitable for binary comparisons. + + In addition to providing means for names to be tagged with types, + this specification defines primitives to support a level of naming + environment independence for certain calling applications. To provide + basic services oriented towards the requirements of callers which + need not themselves interpret the internal syntax and semantics of + names, GSS-API calls for name comparison (GSS_Compare_name()), + human-readable display (GSS_Display_name()), input conversion + (GSS_Import_name()), internal name deallocation (GSS_Release_name()), + and internal name duplication (GSS_Duplicate_name()) functions are + defined. (It is anticipated that these proposed GSS-API calls will be + implemented in many end systems based on system-specific name + manipulation primitives already extant within those end systems; + inclusion within the GSS-API is intended to offer GSS-API callers a + portable means to perform specific operations, supportive of + authorization and audit requirements, on authenticated names.) + + GSS_Import_name() implementations can, where appropriate, support + more than one printable syntax corresponding to a given namespace + (e.g., alternative printable representations for X.500 Distinguished + Names), allowing flexibility for their callers to select among + alternative representations. GSS_Display_name() implementations + output a printable syntax selected as appropriate to their + operational environments; this selection is a local matter. Callers + desiring portability across alternative printable syntaxes should + refrain from implementing comparisons based on printable name forms + and should instead use the GSS_Compare_name() call to determine + whether or not one internal-format name matches another. + + The GSS_Canonicalize_name() and GSS_Export_name() calls enable + callers to acquire and process Exported Name Objects, canonicalized + and translated in accordance with the procedures of a particular + GSS-API mechanism. Exported Name Objects can, in turn, be input to + GSS_Import_name(), yielding equivalent MNs. These facilities are + designed specifically to enable efficient storage and comparison of + names (e.g., for use in access control lists). + + + + + + + +Linn Standards Track [Page 13] + +RFC 2078 GSS-API January 1997 + + + The following diagram illustrates the intended dataflow among name- + related GSS-API processing routines. + + GSS-API library defaults + | + | + V text, for + text --------------> internal_name (IN) -----------> display only + import_name() / display_name() + / + / + / + accept_sec_context() / + | / + | / + | / canonicalize_name() + | / + | / + | / + | / + | / + | | + V V <--------------------- + single mechanism import_name() exported name: flat + internal_name (MN) binary "blob" usable + ----------------------> for access control + export_name() + +1.1.6: Channel Bindings + + The GSS-API accommodates the concept of caller-provided channel + binding ("chan_binding") information. Channel bindings are used to + strengthen the quality with which peer entity authentication is + provided during context establishment, by limiting the scope within + which an intercepted context establishment token can be reused by an + attacker. Specifically, they enable GSS-API callers to bind the + establishment of a security context to relevant characteristics + (e.g., addresses, transformed representations of encryption keys) of + the underlying communications channel, of protection mechanisms + applied to that communications channel, and to application-specific + data. + + The caller initiating a security context must determine the + appropriate channel binding values to provide as input to the + GSS_Init_sec_context() call, and consistent values must be provided + to GSS_Accept_sec_context() by the context's target, in order for + both peers' GSS-API mechanisms to validate that received tokens + possess correct channel-related characteristics. Use or non-use of + + + +Linn Standards Track [Page 14] + +RFC 2078 GSS-API January 1997 + + + the GSS-API channel binding facility is a caller option. GSS-API + mechanisms can operate in an environment where NULL channel bindings + are presented; mechanism implementors are encouraged, but not + required, to make use of caller-provided channel binding data within + their mechanisms. Callers should not assume that underlying + mechanisms provide confidentiality protection for channel binding + information. + + When non-NULL channel bindings are provided by callers, certain + mechanisms can offer enhanced security value by interpreting the + bindings' content (rather than simply representing those bindings, or + integrity check values computed on them, within tokens) and will + therefore depend on presentation of specific data in a defined + format. To this end, agreements among mechanism implementors are + defining conventional interpretations for the contents of channel + binding arguments, including address specifiers (with content + dependent on communications protocol environment) for context + initiators and acceptors. (These conventions are being incorporated + in GSS-API mechanism specifications and into the GSS-API C language + bindings specification.) In order for GSS-API callers to be portable + across multiple mechanisms and achieve the full security + functionality which each mechanism can provide, it is strongly + recommended that GSS-API callers provide channel bindings consistent + with these conventions and those of the networking environment in + which they operate. + +1.2: GSS-API Features and Issues + + This section describes aspects of GSS-API operations, of the security + services which the GSS-API provides, and provides commentary on + design issues. + +1.2.1: Status Reporting + + Each GSS-API call provides two status return values. Major_status + values provide a mechanism-independent indication of call status + (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), + sufficient to drive normal control flow within the caller in a + generic fashion. Table 1 summarizes the defined major_status return + codes in tabular fashion. + + + + + + + + + + + +Linn Standards Track [Page 15] + +RFC 2078 GSS-API January 1997 + + +Table 1: GSS-API Major Status Codes + + FATAL ERROR CODES + + GSS_S_BAD_BINDINGS channel binding mismatch + GSS_S_BAD_MECH unsupported mechanism requested + GSS_S_BAD_NAME invalid name provided + GSS_S_BAD_NAMETYPE name of unsupported type provided + GSS_S_BAD_STATUS invalid input status selector + GSS_S_BAD_SIG token had invalid integrity check + GSS_S_CONTEXT_EXPIRED specified security context expired + GSS_S_CREDENTIALS_EXPIRED expired credentials detected + GSS_S_DEFECTIVE_CREDENTIAL defective credential detected + GSS_S_DEFECTIVE_TOKEN defective token detected + GSS_S_FAILURE failure, unspecified at GSS-API + level + GSS_S_NO_CONTEXT no valid security context specified + GSS_S_NO_CRED no valid credentials provided + GSS_S_BAD_QOP unsupported QOP value + GSS_S_UNAUTHORIZED operation unauthorized + GSS_S_UNAVAILABLE operation unavailable + GSS_S_DUPLICATE_ELEMENT duplicate credential element requested + GSS_S_NAME_NOT_MN name contains multi-mechanism elements + + INFORMATORY STATUS CODES + + GSS_S_COMPLETE normal completion + GSS_S_CONTINUE_NEEDED continuation call to routine + required + GSS_S_DUPLICATE_TOKEN duplicate per-message token + detected + GSS_S_OLD_TOKEN timed-out per-message token + detected + GSS_S_UNSEQ_TOKEN reordered (early) per-message token + detected + GSS_S_GAP_TOKEN skipped predecessor token(s) + detected + + Minor_status provides more detailed status information which may + include status codes specific to the underlying security mechanism. + Minor_status values are not specified in this document. + + GSS_S_CONTINUE_NEEDED major_status returns, and optional message + outputs, are provided in GSS_Init_sec_context() and + GSS_Accept_sec_context() calls so that different mechanisms' + employment of different numbers of messages within their + authentication sequences need not be reflected in separate code paths + within calling applications. Instead, such cases are accommodated + + + +Linn Standards Track [Page 16] + +RFC 2078 GSS-API January 1997 + + + with sequences of continuation calls to GSS_Init_sec_context() and + GSS_Accept_sec_context(). The same mechanism is used to encapsulate + mutual authentication within the GSS-API's context initiation calls. + + For mech_types which require interactions with third-party servers in + order to establish a security context, GSS-API context establishment + calls may block pending completion of such third-party interactions. + + On the other hand, no GSS-API calls pend on serialized interactions + with GSS-API peer entities. As a result, local GSS-API status + returns cannot reflect unpredictable or asynchronous exceptions + occurring at remote peers, and reflection of such status information + is a caller responsibility outside the GSS-API. + +1.2.2: Per-Message Security Service Availability + + When a context is established, two flags are returned to indicate the + set of per-message protection security services which will be + available on the context: + + the integ_avail flag indicates whether per-message integrity and + data origin authentication services are available + + the conf_avail flag indicates whether per-message confidentiality + services are available, and will never be returned TRUE unless the + integ_avail flag is also returned TRUE + + GSS-API callers desiring per-message security services should + check the values of these flags at context establishment time, and + must be aware that a returned FALSE value for integ_avail means + that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the + associated context will apply no cryptographic protection to user + data messages. + + The GSS-API per-message integrity and data origin authentication + services provide assurance to a receiving caller that protection was + applied to a message by the caller's peer on the security context, + corresponding to the entity named at context initiation. The GSS-API + per-message confidentiality service provides assurance to a sending + caller that the message's content is protected from access by + entities other than the context's named peer. + + + + + + + + + + +Linn Standards Track [Page 17] + +RFC 2078 GSS-API January 1997 + + + The GSS-API per-message protection service primitives, as the + category name implies, are oriented to operation at the granularity + of protocol data units. They perform cryptographic operations on the + data units, transfer cryptographic control information in tokens, + and, in the case of GSS_Wrap(), encapsulate the protected data unit. + As such, these primitives are not oriented to efficient data + protection for stream-paradigm protocols (e.g., Telnet) if + cryptography must be applied on an octet-by-octet basis. + +1.2.3: Per-Message Replay Detection and Sequencing + + Certain underlying mech_types offer support for replay detection + and/or sequencing of messages transferred on the contexts they + support. These optionally-selectable protection features are distinct + from replay detection and sequencing features applied to the context + establishment operation itself; the presence or absence of context- + level replay or sequencing features is wholly a function of the + underlying mech_type's capabilities, and is not selected or omitted + as a caller option. + + The caller initiating a context provides flags (replay_det_req_flag + and sequence_req_flag) to specify whether the use of per-message + replay detection and sequencing features is desired on the context + being established. The GSS-API implementation at the initiator system + can determine whether these features are supported (and whether they + are optionally selectable) as a function of mech_type, without need + for bilateral negotiation with the target. When enabled, these + features provide recipients with indicators as a result of GSS-API + processing of incoming messages, identifying whether those messages + were detected as duplicates or out-of-sequence. Detection of such + events does not prevent a suspect message from being provided to a + recipient; the appropriate course of action on a suspect message is a + matter of caller policy. + + The semantics of the replay detection and sequencing services applied + to received messages, as visible across the interface which the GSS- + API provides to its clients, are as follows: + + When replay_det_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_S_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + and that the message was not a replay of a previously-processed + message within that window. + + + + + + +Linn Standards Track [Page 18] + +RFC 2078 GSS-API January 1997 + + + 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic + checkvalue on the received message was correct, but that the + message was recognized as a duplicate of a previously-processed + message. + + 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on + the received message was correct, but that the message is too old + to be checked for duplication. + + When sequence_state is TRUE, the possible major_status returns for + well-formed and correctly signed messages are as follows: + + 1. GSS_S_COMPLETE indicates that the message was within the window + (of time or sequence space) allowing replay events to be detected, + that the message was not a replay of a previously-processed + message within that window, and that no predecessor sequenced + messages are missing relative to the last received message (if + any) processed on the context with a correct cryptographic + checkvalue. + + 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value + on the received message was correct, but that the message was + recognized as a duplicate of a previously-processed message. + + 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the + received message was correct, but that the token is too old to be + checked for duplication. + + 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue + on the received message was correct, but that it is earlier in a + sequenced stream than a message already processed on the context. + [Note: Mechanisms can be architected to provide a stricter form of + sequencing service, delivering particular messages to recipients + only after all predecessor messages in an ordered stream have been + delivered. This type of support is incompatible with the GSS-API + paradigm in which recipients receive all messages, whether in + order or not, and provide them (one at a time, without intra-GSS- + API message buffering) to GSS-API routines for validation. GSS- + API facilities provide supportive functions, aiding clients to + achieve strict message stream integrity in an efficient manner in + conjunction with sequencing provisions in communications + protocols, but the GSS-API does not offer this level of message + stream integrity service by itself.] + + + + + + + + +Linn Standards Track [Page 19] + +RFC 2078 GSS-API January 1997 + + + 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on + the received message was correct, but that one or more predecessor + sequenced messages have not been successfully processed relative + to the last received message (if any) processed on the context + with a correct cryptographic checkvalue. + + As the message stream integrity features (especially sequencing) may + interfere with certain applications' intended communications + paradigms, and since support for such features is likely to be + resource intensive, it is highly recommended that mech_types + supporting these features allow them to be activated selectively on + initiator request when a context is established. A context initiator + and target are provided with corresponding indicators + (replay_det_state and sequence_state), signifying whether these + features are active on a given context. + + An example mech_type supporting per-message replay detection could + (when replay_det_state is TRUE) implement the feature as follows: The + underlying mechanism would insert timestamps in data elements output + by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- + limited window) a cache (qualified by originator-recipient pair) + identifying received data elements processed by GSS_VerifyMIC() and + GSS_Unwrap(). When this feature is active, exception status returns + (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when + GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is + either a detected duplicate of a prior message or which is too old to + validate against a cache of recently received messages. + +1.2.4: Quality of Protection + + Some mech_types provide their users with fine granularity control + over the means used to provide per-message protection, allowing + callers to trade off security processing overhead dynamically against + the protection requirements of particular messages. A per-message + quality-of-protection parameter (analogous to quality-of-service, or + QOS) selects among different QOP options supported by that mechanism. + On context establishment for a multi-QOP mech_type, context-level + data provides the prerequisite data for a range of protection + qualities. + + It is expected that the majority of callers will not wish to exert + explicit mechanism-specific QOP control and will therefore request + selection of a default QOP. Definitions of, and choices among, non- + default QOP values are mechanism-specific, and no ordered sequences + of QOP values can be assumed equivalent across different mechanisms. + Meaningful use of non-default QOP values demands that callers be + familiar with the QOP definitions of an underlying mechanism or + mechanisms, and is therefore a non-portable construct. The + + + +Linn Standards Track [Page 20] + +RFC 2078 GSS-API January 1997 + + + GSS_S_BAD_QOP major_status value is defined in order to indicate that + a provided QOP value is unsupported for a security context, most + likely because that value is unrecognized by the underlying + mechanism. + +1.2.5: Anonymity Support + + In certain situations or environments, an application may wish to + authenticate a peer and/or protect communications using GSS-API per- + message services without revealing its own identity. For example, + consider an application which provides read access to a research + database, and which permits queries by arbitrary requestors. A + client of such a service might wish to authenticate the service, to + establish trust in the information received from it, but might not + wish to disclose its identity to the service for privacy reasons. + + In ordinary GSS-API usage, a context initiator's identity is made + available to the context acceptor as part of the context + establishment process. To provide for anonymity support, a facility + (input anon_req_flag to GSS_Init_sec_context()) is provided through + which context initiators may request that their identity not be + provided to the context acceptor. Mechanisms are not required to + honor this request, but a caller will be informed (via returned + anon_state indicator from GSS_Init_sec_context()) whether or not the + request is honored. Note that authentication as the anonymous + principal does not necessarily imply that credentials are not + required in order to establish a context. + + The following Object Identifier value is provided as a means to + identify anonymous names, and can be compared against in order to + determine, in a mechanism-independent fashion, whether a name refers + to an anonymous principal: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 3(gss-anonymous-name)} + + The recommended symbolic name corresponding to this definition is + GSS_C_NT_ANONYMOUS. + + Four possible combinations of anon_state and mutual_state are + possible, with the following results: + + anon_state == FALSE, mutual_state == FALSE: initiator + authenticated to target. + + anon_state == FALSE, mutual_state == TRUE: initiator authenticated + to target, target authenticated to initiator. + + + + +Linn Standards Track [Page 21] + +RFC 2078 GSS-API January 1997 + + + anon_state == TRUE, mutual_state == FALSE: initiator authenticated + as anonymous principal to target. + + anon_state == TRUE, mutual_state == TRUE: initiator authenticated + as anonymous principal to target, target authenticated to + initiator. + +1.2.6: Initialization + + No initialization calls (i.e., calls which must be invoked prior to + invocation of other facilities in the interface) are defined in GSS- + API. As an implication of this fact, GSS-API implementations must + themselves be self-initializing. + +1.2.7: Per-Message Protection During Context Establishment + + A facility is defined in GSS-V2 to enable protection and buffering of + data messages for later transfer while a security context's + establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases + where the caller side already possesses the necessary session key to + enable this processing. Specifically, a new state Boolean, called + prot_ready_state, is added to the set of information returned by + GSS_Init_sec_context(), GSS_Accept_sec_context(), and + GSS_Inquire_context(). + + For context establishment calls, this state Boolean is valid and + interpretable when the associated major_status is either + GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both + initiators and acceptors) can assume that per-message protection (via + GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is + available and ready for use if either: prot_ready_state == TRUE, or + major_status == GSS_S_COMPLETE, though mutual authentication (if + requested) cannot be guaranteed until GSS_S_COMPLETE is returned. + + This achieves full, transparent backward compatibility for GSS-API V1 + callers, who need not even know of the existence of prot_ready_state, + and who will get the expected behavior from GSS_S_COMPLETE, but who + will not be able to use per-message protection before GSS_S_COMPLETE + is returned. + + It is not a requirement that GSS-V2 mechanisms ever return TRUE + prot_ready_state before completion of context establishment (indeed, + some mechanisms will not evolve usable message protection keys, + especially at the context acceptor, before context establishment is + complete). It is expected but not required that GSS-V2 mechanisms + will return TRUE prot_ready_state upon completion of context + establishment if they support per-message protection at all (however + GSS-V2 applications should not assume that TRUE prot_ready_state will + + + +Linn Standards Track [Page 22] + +RFC 2078 GSS-API January 1997 + + + always be returned together with the GSS_S_COMPLETE major_status, + since GSS-V2 implementations may continue to support GSS-V1 mechanism + code, which will never return TRUE prot_ready_state). + + When prot_ready_state is returned TRUE, mechanisms shall also set + those context service indicator flags (deleg_state, mutual_state, + replay_det_state, sequence_state, anon_state, trans_state, + conf_avail, integ_avail) which represent facilities confirmed, at + that time, to be available on the context being established. In + situations where prot_ready_state is returned before GSS_S_COMPLETE, + it is possible that additional facilities may be confirmed and + subsequently indicated when GSS_S_COMPLETE is returned. + +1.2.8: Implementation Robustness + + This section recommends aspects of GSS-API implementation behavior in + the interests of overall robustness. + + If a token is presented for processing on a GSS-API security context + and that token is determined to be invalid for that context, the + context's state should not be disrupted for purposes of processing + subsequent valid tokens. + + Certain local conditions at a GSS-API implementation (e.g., + unavailability of memory) may preclude, temporarily or permanently, + the successful processing of tokens on a GSS-API security context, + typically generating GSS_S_FAILURE major_status returns along with + locally-significant minor_status. For robust operation under such + conditions, the following recommendations are made: + + Failing calls should free any memory they allocate, so that + callers may retry without causing further loss of resources. + + Failure of an individual call on an established context should not + preclude subsequent calls from succeeding on the same context. + + Whenever possible, it should be possible for + GSS_Delete_sec_context() calls to be successfully processed even + if other calls cannot succeed, thereby enabling context-related + resources to be released. + +2: Interface Descriptions + + This section describes the GSS-API's service interface, dividing the + set of calls offered into four groups. Credential management calls + are related to the acquisition and release of credentials by + principals. Context-level calls are related to the management of + security contexts between principals. Per-message calls are related + + + +Linn Standards Track [Page 23] + +RFC 2078 GSS-API January 1997 + + + to the protection of individual messages on established security + contexts. Support calls provide ancillary functions useful to GSS-API + callers. Table 2 groups and summarizes the calls in tabular fashion. + +Table 2: GSS-API Calls + + CREDENTIAL MANAGEMENT + + GSS_Acquire_cred acquire credentials for use + GSS_Release_cred release credentials after use + GSS_Inquire_cred display information about + credentials + GSS_Add_cred construct credentials incrementally + GSS_Inquire_cred_by_mech display per-mechanism credential + information + + CONTEXT-LEVEL CALLS + + GSS_Init_sec_context initiate outbound security context + GSS_Accept_sec_context accept inbound security context + GSS_Delete_sec_context flush context when no longer needed + GSS_Process_context_token process received control token on + context + GSS_Context_time indicate validity time remaining on + context + GSS_Inquire_context display information about context + GSS_Wrap_size_limit determine GSS_Wrap token size limit + GSS_Export_sec_context transfer context to other process + GSS_Import_sec_context import transferred context + + PER-MESSAGE CALLS + + GSS_GetMIC apply integrity check, receive as + token separate from message + GSS_VerifyMIC validate integrity check token + along with message + GSS_Wrap sign, optionally encrypt, + encapsulate + GSS_Unwrap decapsulate, decrypt if needed, + validate integrity check + + + + + + + + + + + +Linn Standards Track [Page 24] + +RFC 2078 GSS-API January 1997 + + + SUPPORT CALLS + + GSS_Display_status translate status codes to printable + form + GSS_Indicate_mechs indicate mech_types supported on + local system + GSS_Compare_name compare two names for equality + GSS_Display_name translate name to printable form + GSS_Import_name convert printable name to + normalized form + GSS_Release_name free storage of normalized-form + name + GSS_Release_buffer free storage of printable name + GSS_Release_OID free storage of OID object + GSS_Release_OID_set free storage of OID set object + GSS_Create_empty_OID_set create empty OID set + GSS_Add_OID_set_member add member to OID set + GSS_Test_OID_set_member test if OID is member of OID set + GSS_OID_to_str display OID as string + GSS_Str_to_OID construct OID from string + GSS_Inquire_names_for_mech indicate name types supported by + mechanism + GSS_Inquire_mechs_for_name indicates mechanisms supporting name + type + GSS_Canonicalize_name translate name to per-mechanism form + GSS_Export_name externalize per-mechanism name + GSS_Duplicate_name duplicate name object + +2.1: Credential management calls + + These GSS-API calls provide functions related to the management of + credentials. Their characterization with regard to whether or not + they may block pending exchanges with other network entities (e.g., + directories or authentication servers) depends in part on OS-specific + (extra-GSS-API) issues, so is not specified in this document. + + The GSS_Acquire_cred() call is defined within the GSS-API in support + of application portability, with a particular orientation towards + support of portable server applications. It is recognized that (for + certain systems and mechanisms) credentials for interactive users may + be managed differently from credentials for server processes; in such + environments, it is the GSS-API implementation's responsibility to + distinguish these cases and the procedures for making this + distinction are a local matter. The GSS_Release_cred() call provides + a means for callers to indicate to the GSS-API that use of a + credentials structure is no longer required. The GSS_Inquire_cred() + call allows callers to determine information about a credentials + structure. The GSS_Add_cred() call enables callers to append + + + +Linn Standards Track [Page 25] + +RFC 2078 GSS-API January 1997 + + + elements to an existing credential structure, allowing iterative + construction of a multi-mechanism credential. The + GSS_Inquire_cred_by_mech() call enables callers to extract per- + mechanism information describing a credentials structure. + +2.1.1: GSS_Acquire_cred call + + Inputs: + + o desired_name INTERNAL NAME, -NULL requests locally-determined + default + + o lifetime_req INTEGER,-in seconds; 0 requests default + + o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests + system-selected default + + o cred_usage INTEGER -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle CREDENTIAL HANDLE, + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_S_COMPLETE indicates that requested credentials were + successfully established, for the duration indicated in + lifetime_rec, suitable for the usage requested in cred_usage, + for the set of mech_types indicated in actual_mechs, and that + those credentials can be referenced for subsequent use with + the handle returned in output_cred_handle. + + o GSS_S_BAD_MECH indicates that a mech_type unsupported by the + GSS-API implementation type was requested, causing the + credential establishment operation to fail. + + + + + + +Linn Standards Track [Page 26] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is + uninterpretable or of a type unsupported by the applicable + underlying GSS-API mechanism(s), so no credentials could be + established for the accompanying desired_name. + + o GSS_S_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so no credentials could be established for the + accompanying desired_name. + + o GSS_S_FAILURE indicates that credential establishment failed + for reasons unspecified at the GSS-API level, including lack + of authorization to establish and use credentials associated + with the identity named in the input desired_name argument. + + GSS_Acquire_cred() is used to acquire credentials so that a + principal can (as a function of the input cred_usage parameter) + initiate and/or accept security contexts under the identity + represented by the desired_name input argument. On successful + completion, the returned output_cred_handle result provides a handle + for subsequent references to the acquired credentials. Typically, + single-user client processes requesting that default credential + behavior be applied for context establishment purposes will have no + need to invoke this call. + + A caller may provide the value NULL for desired_name, signifying a + request for credentials corresponding to a principal identity + selected by default for the caller. The procedures used by GSS-API + implementations to select the appropriate principal identity in + response to such a request are local matters. It is possible that + multiple pre-established credentials may exist for the same principal + identity (for example, as a result of multiple user login sessions) + when GSS_Acquire_cred() is called; the means used in such cases to + select a specific credential are local matters. The input + lifetime_req argument to GSS_Acquire_cred() may provide useful + information for local GSS-API implementations to employ in making + this disambiguation in a manner which will best satisfy a caller's + intent. + + The lifetime_rec result indicates the length of time for which the + acquired credentials will be valid, as an offset from the present. A + mechanism may return a reserved value indicating INDEFINITE if no + constraints on credential lifetime are imposed. A caller of + GSS_Acquire_cred() can request a length of time for which acquired + credentials are to be valid (lifetime_req argument), beginning at the + present, or can request credentials with a default validity interval. + (Requests for postdated credentials are not supported within the + GSS-API.) Certain mechanisms and implementations may bind in + + + +Linn Standards Track [Page 27] + +RFC 2078 GSS-API January 1997 + + + credential validity period specifiers at a point preliminary to + invocation of the GSS_Acquire_cred() call (e.g., in conjunction with + user login procedures). As a result, callers requesting non-default + values for lifetime_req must recognize that such requests cannot + always be honored and must be prepared to accommodate the use of + returned credentials with different lifetimes as indicated in + lifetime_rec. + + The caller of GSS_Acquire_cred() can explicitly specify a set of + mech_types which are to be accommodated in the returned credentials + (desired_mechs argument), or can request credentials for a system- + defined default set of mech_types. Selection of the system-specified + default set is recommended in the interests of application + portability. The actual_mechs return value may be interrogated by the + caller to determine the set of mechanisms with which the returned + credentials may be used. + +2.1.2: GSS_Release_cred call + + Input: + + o cred_handle CREDENTIAL HANDLE - NULL specifies that + the credential elements used when default credential behavior + is requested be released. + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle were released for purposes of subsequent + access by the caller. The effect on other processes which may + be authorized shared access to such credentials is a local + matter. + + o GSS_S_NO_CRED indicates that no release operation was + performed, either because the input cred_handle was invalid or + because the caller lacks authorization to access the + referenced credentials. + + o GSS_S_FAILURE indicates that the release operation failed for + reasons unspecified at the GSS-API level. + + + + + +Linn Standards Track [Page 28] + +RFC 2078 GSS-API January 1997 + + + Provides a means for a caller to explicitly request that credentials + be released when their use is no longer required. Note that system- + specific credential management functions are also likely to exist, + for example to assure that credentials shared among processes are + properly deleted when all affected processes terminate, even if no + explicit release requests are issued by those processes. Given the + fact that multiple callers are not precluded from gaining authorized + access to the same credentials, invocation of GSS_Release_cred() + cannot be assumed to delete a particular set of credentials on a + system-wide basis. + +2.1.3: GSS_Inquire_cred call + + Input: + + o cred_handle CREDENTIAL HANDLE -NULL specifies that the + credential elements used when default credential behavior is + requested are to be queried + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, + + o lifetime_rec INTEGER -in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, and that the output + cred_name, lifetime_rec, and cred_usage values represent, + respectively, the credentials' associated principal name, + remaining lifetime, suitable usage modes, and supported + mechanism types. + + o GSS_S_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + + +Linn Standards Track [Page 29] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced + credentials are invalid. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced + credentials have expired. + + o GSS_S_FAILURE indicates that the operation failed for + reasons unspecified at the GSS-API level. + + The GSS_Inquire_cred() call is defined primarily for the use of those + callers which request use of default credential behavior rather than + acquiring credentials explicitly with GSS_Acquire_cred(). It enables + callers to determine a credential structure's associated principal + name, remaining validity period, usability for security context + initiation and/or acceptance, and supported mechanisms. + + For a multi-mechanism credential, the returned "lifetime" specifier + indicates the shortest lifetime of any of the mechanisms' elements in + the credential (for either context initiation or acceptance + purposes). + + GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for + "cred_usage" if both of the following conditions hold: + + (1) there exists in the credential an element which allows context + initiation using some mechanism + + (2) there exists in the credential an element which allows context + acceptance using some mechanism (allowably, but not necessarily, + one of the same mechanism(s) qualifying for (1)). + + If condition (1) holds but not condition (2), GSS_Inquire_cred() + should indicate INITIATE-ONLY for "cred_usage". If condition (2) + holds but not condition (1), GSS_Inquire_cred() should indicate + ACCEPT-ONLY for "cred_usage". + + Callers requiring finer disambiguation among available combinations + of lifetimes, usage modes, and mechanisms should call the + GSS_Inquire_cred_by_mech() routine, passing that routine one of the + mech OIDs returned by GSS_Inquire_cred(). + + + + + + + + + + + +Linn Standards Track [Page 30] + +RFC 2078 GSS-API January 1997 + + +2.1.4: GSS_Add_cred call + + Inputs: + + o input_cred_handle CREDENTIAL HANDLE - handle to credential + structure created with prior GSS_Acquire_cred() or + GSS_Add_cred() call, or NULL to append elements to the set + which are applied for the caller when default credential + behavior is specified. + + o desired_name INTERNAL NAME - NULL requests locally-determined + default + + o initiator_time_req INTEGER - in seconds; 0 requests default + + o acceptor_time_req INTEGER - in seconds; 0 requests default + + o desired_mech OBJECT IDENTIFIER + + o cred_usage INTEGER - 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_cred_handle CREDENTIAL HANDLE, - NULL to request that + credential elements be added "in place" to the credential + structure identified by input_cred_handle, non-NULL pointer + to request that a new credential structure and handle be created. + + o actual_mechs SET OF OBJECT IDENTIFIER, + + o initiator_time_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + o acceptor_time_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms + supported by resulting credential. + + + + + +Linn Standards Track [Page 31] + +RFC 2078 GSS-API January 1997 + + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by + the input_cred_handle argument were valid, and that the + resulting credential from GSS_Add_cred() is valid for the + durations indicated in initiator_time_rec and acceptor_time_rec, + suitable for the usage requested in cred_usage, and for the + mechanisms indicated in actual_mechs. + + o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech + specified a mechanism for which the referenced credential + already contained a credential element with overlapping + cred_usage and validity time specifiers. + + o GSS_S_BAD_MECH indicates that the input desired_mech specified + a mechanism unsupported by the GSS-API implementation, causing + the GSS_Add_cred() operation to fail. + + o GSS_S_BAD_NAMETYPE indicates that the provided desired_name + is uninterpretable or of a type unsupported by the applicable + underlying GSS-API mechanism(s), so the GSS_Add_cred() operation + could not be performed for that name. + + o GSS_S_BAD_NAME indicates that the provided desired_name is + inconsistent in terms of internally-incorporated type specifier + information, so the GSS_Add_cred() operation could not be + performed for that name. + + o GSS_S_NO_CRED indicates that the input_cred_handle referenced + invalid or inaccessible credentials. + + o GSS_S_FAILURE indicates that the operation failed for + reasons unspecified at the GSS-API level, including lack of + authorization to establish or use credentials representing + the requested identity. + + GSS_Add_cred() enables callers to construct credentials iteratively + by adding credential elements in successive operations, corresponding + to different mechanisms. This offers particular value in multi- + mechanism environments, as the major_status and minor_status values + returned on each iteration are individually visible and can therefore + be interpreted unambiguously on a per-mechanism basis. + + The same input desired_name, or default reference, should be used on + all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a + particular credential. + + + + + +Linn Standards Track [Page 32] + +RFC 2078 GSS-API January 1997 + + +2.1.5: GSS_Inquire_cred_by_mech call + + Inputs: + + o cred_handle CREDENTIAL HANDLE -- NULL specifies that the + credential elements used when default credential behavior is + requested are to be queried + + o mech_type OBJECT IDENTIFIER -- specific mechanism for + which credentials are being queried + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o cred_name INTERNAL NAME, -- guaranteed to be MN + + o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for + INDEFINITE + + o lifetime_rec_accept INTEGER -- in seconds, or reserved value for + INDEFINITE + + o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, + 2=ACCEPT-ONLY + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the credentials referenced by the + input cred_handle argument were valid, that the mechanism + indicated by the input mech_type was represented with elements + within those credentials, and that the output cred_name, + lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values + represent, respectively, the credentials' associated principal + name, remaining lifetimes, and suitable usage modes. + + o GSS_S_NO_CRED indicates that no information could be returned + about the referenced credentials, either because the input + cred_handle was invalid or because the caller lacks + authorization to access the referenced credentials. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced + credentials are invalid. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced + credentials have expired. + + + +Linn Standards Track [Page 33] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_MECH indicates that the referenced credentials do not + contain elements for the requested mechanism. + + o GSS_S_FAILURE indicates that the operation failed for reasons + unspecified at the GSS-API level. + + The GSS_Inquire_cred_by_mech() call enables callers in multi- + mechanism environments to acquire specific data about available + combinations of lifetimes, usage modes, and mechanisms within a + credential structure. The lifetime_rec_initiate result indicates the + available lifetime for context initiation purposes; the + lifetime_rec_accept result indicates the available lifetime for + context acceptance purposes. + +2.2: Context-level calls + + This group of calls is devoted to the establishment and management of + security contexts between peers. A context's initiator calls + GSS_Init_sec_context(), resulting in generation of a token which the + caller passes to the target. At the target, that token is passed to + GSS_Accept_sec_context(). Depending on the underlying mech_type and + specified options, additional token exchanges may be performed in the + course of context establishment; such exchanges are accommodated by + GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and + GSS_Accept_sec_context(). + + Either party to an established context may invoke + GSS_Delete_sec_context() to flush context information when a context + is no longer required. GSS_Process_context_token() is used to + process received tokens carrying context-level control information. + GSS_Context_time() allows a caller to determine the length of time + for which an established context will remain valid. + GSS_Inquire_context() returns status information describing context + characteristics. GSS_Wrap_size_limit() allows a caller to determine + the size of a token which will be generated by a GSS_Wrap() + operation. GSS_Export_sec_context() and GSS_Import_sec_context() + enable transfer of active contexts between processes on an end + system. + +2.2.1: GSS_Init_sec_context call + + Inputs: + + o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use + default" + + o input_context_handle CONTEXT HANDLE, -0 specifies "none assigned + yet" + + + +Linn Standards Track [Page 34] + +RFC 2078 GSS-API January 1997 + + + o targ_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use + default" + + o deleg_req_flag BOOLEAN, + + o mutual_req_flag BOOLEAN, + + o replay_det_req_flag BOOLEAN, + + o sequence_req_flag BOOLEAN, + + o anon_req_flag BOOLEAN, + + o lifetime_req INTEGER,-0 specifies default lifetime + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING-NULL or token received from target + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_context_handle CONTEXT HANDLE, + + o mech_type OBJECT IDENTIFIER, -actual mechanism always + indicated, never NULL + + o output_token OCTET STRING, -NULL or token to pass to context + target + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, -- see Section 1.2.7 + + + +Linn Standards Track [Page 35] + +RFC 2078 GSS-API January 1997 + + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + This call may block pending network interactions for those mech_types + in which an authentication server or other network entity must be + consulted on behalf of a context initiator in order to generate an + output_token suitable for presentation to a specified target. + + Return major_status codes: + + o GSS_S_COMPLETE indicates that context-level information was + successfully initialized, and that the returned output_token + will provide sufficient information for the target to perform + per-message processing on the newly-established context. + + o GSS_S_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the target, and that a + reply must be received and passed as the input_token argument + to a continuation call to GSS_Init_sec_context(), before + per-message processing can be performed in conjunction with + this context. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks + performed on the input_token failed, preventing further + processing from being performed based on that token. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + claimant_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_S_BAD_SIG indicates that the received input_token + contains an incorrect integrity check, so context setup cannot + be accomplished. + + o GSS_S_NO_CRED indicates that no context was established, + either because the input cred_handle was invalid, because the + referenced credentials are valid for context acceptor use + only, or because the caller lacks authorization to access the + referenced credentials. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials + provided through the input claimant_cred_handle argument are no + longer valid, so context establishment cannot be completed. + + + +Linn Standards Track [Page 36] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_BINDINGS indicates that a mismatch between the + caller-provided chan_bindings and those extracted from the + input_token was detected, signifying a security-relevant + event and preventing context establishment. (This result will + be returned by GSS_Init_sec_context only for contexts where + mutual_state is TRUE.) + + o GSS_S_OLD_TOKEN indicates that the input_token is too old to + be checked for integrity. This is a fatal error during context + establishment. + + o GSS_S_DUPLICATE_TOKEN indicates that the input token has a + correct integrity check, but is a duplicate of a token already + processed. This is a fatal error during context establishment. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided; this major status will + be returned only for successor calls following GSS_S_CONTINUE_ + NEEDED status returns. + + o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is + of a type uninterpretable or unsupported by the applicable + underlying GSS-API mechanism(s), so context establishment + cannot be completed. + + o GSS_S_BAD_NAME indicates that the provided targ_name is + inconsistent in terms of internally-incorporated type specifier + information, so context establishment cannot be accomplished. + + o GSS_S_BAD_MECH indicates receipt of a context establishment token + or of a caller request specifying a mechanism unsupported by + the local system or with the caller's active credentials + + o GSS_S_FAILURE indicates that context setup could not be + accomplished for reasons unspecified at the GSS-API level, and + that no interface-defined recovery action is available. + + This routine is used by a context initiator, and ordinarily emits one + (or, for the case of a multi-step exchange, more than one) + output_token suitable for use by the target within the selected + mech_type's protocol. Using information in the credentials structure + referenced by claimant_cred_handle, GSS_Init_sec_context() + initializes the data structures required to establish a security + context with target targ_name. The targ_name may be any valid + INTERNAL NAME; it need not be an MN. The claimant_cred_handle must + correspond to the same valid credentials structure on the initial + call to GSS_Init_sec_context() and on any successor calls resulting + from GSS_S_CONTINUE_NEEDED status returns; different protocol + + + +Linn Standards Track [Page 37] + +RFC 2078 GSS-API January 1997 + + + sequences modeled by the GSS_S_CONTINUE_NEEDED facility will require + access to credentials at different points in the context + establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Init_sec_context() call relating to a + given context. If successful (i.e., if accompanied by major_status + GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the + initial GSS_Init_sec_context() call returns a non-zero + output_context_handle for use in future references to this context. + Once a non-zero output_context_handle has been returned, GSS-API + callers should call GSS_Delete_sec_context() to release context- + related resources if errors occur in later phases of context + establishment, or when an established context is no longer required. + + When continuation attempts to GSS_Init_sec_context() are needed to + perform context establishment, the previously-returned non-zero + handle value is entered into the input_context_handle argument and + will be echoed in the returned output_context_handle argument. On + such continuation attempts (and only on continuation attempts) the + input_token value is used, to provide the token returned from the + context's target. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The input_token argument contains a message received from the target, + and is significant only on a call to GSS_Init_sec_context() which + follows a previous return indicating GSS_S_CONTINUE_NEEDED + major_status. + + It is the caller's responsibility to establish a communications path + to the target, and to transmit any returned output_token (independent + of the accompanying returned major_status value) to the target over + that path. The output_token can, however, be transmitted along with + the first application-provided input message to be processed by + GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- + established context. + + The initiator may request various context-level functions through + input flags: the deleg_req_flag requests delegation of access rights, + the mutual_req_flag requests mutual authentication, the + replay_det_req_flag requests that replay detection features be + applied to messages transferred on the established context, and the + sequence_req_flag requests that sequencing be enforced. (See Section + + + +Linn Standards Track [Page 38] + +RFC 2078 GSS-API January 1997 + + + 1.2.3 for more information on replay detection and sequencing + features.) The anon_req_flag requests that the initiator's identity + not be transferred within tokens to be sent to the acceptor. + + Not all of the optionally-requestable features will be available in + all underlying mech_types. The corresponding return state values + deleg_state, mutual_state, replay_det_state, and sequence_state + indicate, as a function of mech_type processing capabilities and + initiator-provided input flags, the set of features which will be + active on the context. The returned trans_state value indicates + whether the context is transferable to other processes through use of + GSS_Export_sec_context(). These state indicators' values are + undefined unless either the routine's major_status indicates + GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with + GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is + possible that additional features, not confirmed or indicated along + with TRUE prot_ready_state, will be confirmed and indicated when + GSS_S_COMPLETE is subsequently returned. + + The returned anon_state and prot_ready_state values are significant + for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status + returns from GSS_Init_sec_context(). When anon_state is returned + TRUE, this indicates that neither the current token nor its + predecessors delivers or has delivered the initiator's identity. + Callers wishing to perform context establishment only if anonymity + support is provided should transfer a returned token from + GSS_Init_sec_context() to the peer only if it is accompanied by a + TRUE anon_state indicator. When prot_ready_state is returned TRUE in + conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates + that per-message protection operations may be applied on the context: + see Section 1.2.7 for further discussion of this facility. + + Failure to provide the precise set of features requested by the + caller does not cause context establishment to fail; it is the + caller's prerogative to delete the context if the feature set + provided is unsuitable for the caller's use. + + The returned mech_type value indicates the specific mechanism + employed on the context, is valid only along with major_status + GSS_S_COMPLETE, and will never indicate the value for "default". + Note that, for the case of certain mechanisms which themselves + perform negotiation, the returned mech_type result may indicate + selection of a mechanism identified by an OID different than that + passed in the input mech_type argument. + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + + + +Linn Standards Track [Page 39] + +RFC 2078 GSS-API January 1997 + + + input to GSS_Wrap() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_GetMIC() or GSS_Wrap()) on + the established context. These state indicators' values are undefined + unless either the routine's major_status indicates GSS_S_COMPLETE, or + TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED + major_status. + + The lifetime_req input specifies a desired upper bound for the + lifetime of the context to be established, with a value of 0 used to + request a default lifetime. The lifetime_rec return value indicates + the length of time for which the context will be valid, expressed as + an offset from the present; depending on mechanism capabilities, + credential lifetimes, and local policy, it may not correspond to the + value requested in lifetime_req. If no constraints on context + lifetime are imposed, this may be indicated by returning a reserved + value representing INDEFINITE lifetime_req. The value of lifetime_rec + is undefined unless the routine's major_status indicates + GSS_S_COMPLETE. + + If the mutual_state is TRUE, this fact will be reflected within the + output_token. A call to GSS_Accept_sec_context() at the target in + conjunction with such a context will return a token, to be processed + by a continuation call to GSS_Init_sec_context(), in order to + achieve mutual authentication. + +2.2.2: GSS_Accept_sec_context call + + Inputs: + + o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies + "use default" + + o input_context_handle CONTEXT HANDLE, -- 0 specifies + "not yet assigned" + + o chan_bindings OCTET STRING, + + o input_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o src_name INTERNAL NAME, -- guaranteed to be MN + + + + +Linn Standards Track [Page 40] + +RFC 2078 GSS-API January 1997 + + + o mech_type OBJECT IDENTIFIER, + + o output_context_handle CONTEXT HANDLE, + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o lifetime_rec INTEGER, - in seconds, or reserved value for + INDEFINITE + + o delegated_cred_handle CREDENTIAL HANDLE, + + o output_token OCTET STRING -NULL or token to pass to context + initiator + + This call may block pending network interactions for those mech_types + in which a directory service or other network entity must be + consulted on behalf of a context acceptor in order to validate a + received input_token. + + Return major_status codes: + + o GSS_S_COMPLETE indicates that context-level data structures + were successfully initialized, and that per-message processing + can now be performed in conjunction with this context. + + o GSS_S_CONTINUE_NEEDED indicates that control information in the + returned output_token must be sent to the initiator, and that + a response must be received and passed as the input_token + argument to a continuation call to GSS_Accept_sec_context(), + before per-message processing can be performed in conjunction + with this context. + + + + +Linn Standards Track [Page 41] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the input_token failed, preventing further processing from + being performed based on that token. + + o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks + performed on the credential structure referenced by + acceptor_cred_handle failed, preventing further processing from + being performed using that credential structure. + + o GSS_S_BAD_SIG indicates that the received input_token contains + an incorrect integrity check, so context setup cannot be + accomplished. + + o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the + received input_token was correct, but that the input_token + was recognized as a duplicate of an input_token already + processed. No new context is established. + + o GSS_S_OLD_TOKEN indicates that the integrity check on the received + input_token was correct, but that the input_token is too old + to be checked for duplication against previously-processed + input_tokens. No new context is established. + + o GSS_S_NO_CRED indicates that no context was established, either + because the input cred_handle was invalid, because the + referenced credentials are valid for context initiator use + only, or because the caller lacks authorization to access the + referenced credentials. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided + through the input acceptor_cred_handle argument are no + longer valid, so context establishment cannot be completed. + + o GSS_S_BAD_BINDINGS indicates that a mismatch between the + caller-provided chan_bindings and those extracted from the + input_token was detected, signifying a security-relevant + event and preventing context establishment. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided; this major status will + be returned only for successor calls following GSS_S_CONTINUE_ + NEEDED status returns. + + o GSS_S_BAD_MECH indicates receipt of a context establishment token + specifying a mechanism unsupported by the local system or with + the caller's active credentials. + + + + + +Linn Standards Track [Page 42] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that context setup could not be + accomplished for reasons unspecified at the GSS-API level, and + that no interface-defined recovery action is available. + + The GSS_Accept_sec_context() routine is used by a context target. + Using information in the credentials structure referenced by the + input acceptor_cred_handle, it verifies the incoming input_token and + (following the successful completion of a context establishment + sequence) returns the authenticated src_name and the mech_type used. + The returned src_name is guaranteed to be an MN, processed by the + mechanism under which the context was established. The + acceptor_cred_handle must correspond to the same valid credentials + structure on the initial call to GSS_Accept_sec_context() and on any + successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; + different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED + mechanism will require access to credentials at different points in + the context establishment sequence. + + The input_context_handle argument is 0, specifying "not yet + assigned", on the first GSS_Accept_sec_context() call relating to a + given context. If successful (i.e., if accompanied by major_status + GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the + initial GSS_Accept_sec_context() call returns a non-zero + output_context_handle for use in future references to this context. + Once a non-zero output_context_handle has been returned, GSS-API + callers should call GSS_Delete_sec_context() to release context- + related resources if errors occur in later phases of context + establishment, or when an established context is no longer required. + + The chan_bindings argument is used by the caller to provide + information binding the security context to security-related + characteristics (e.g., addresses, cryptographic keys) of the + underlying communications channel. See Section 1.1.6 of this document + for more discussion of this argument's usage. + + The returned state results (deleg_state, mutual_state, + replay_det_state, sequence_state, anon_state, trans_state, and + prot_ready_state) reflect the same information as described for + GSS_Init_sec_context(), and their values are significant under the + same return state conditions. + + + + + + + + + + + +Linn Standards Track [Page 43] + +RFC 2078 GSS-API January 1997 + + + The conf_avail return value indicates whether the context supports + per-message confidentiality services, and so informs the caller + whether or not a request for encryption through the conf_req_flag + input to GSS_Wrap() can be honored. In similar fashion, the + integ_avail return value indicates whether per-message integrity + services are available (through either GSS_GetMIC() or GSS_Wrap()) + on the established context. These values are significant under the + same return state conditions as described under + GSS_Init_sec_context(). + + The lifetime_rec return value is significant only in conjunction with + GSS_S_COMPLETE major_status, and indicates the length of time for + which the context will be valid, expressed as an offset from the + present. + + The mech_type return value indicates the specific mechanism employed + on the context, is valid only along with major_status GSS_S_COMPLETE, + and will never indicate the value for "default". + + The delegated_cred_handle result is significant only when deleg_state + is TRUE, and provides a means for the target to reference the + delegated credentials. The output_token result, when non-NULL, + provides a context-level token to be returned to the context + initiator to continue a multi-step context establishment sequence. As + noted with GSS_Init_sec_context(), any returned token should be + transferred to the context's peer (in this case, the context + initiator), independent of the value of the accompanying returned + major_status. + + Note: A target must be able to distinguish a context-level + input_token, which is passed to GSS_Accept_sec_context(), from the + per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). + These data elements may arrive in a single application message, and + GSS_Accept_sec_context() must be performed before per-message + processing can be performed successfully. + +2.2.3: GSS_Delete_sec_context call + + Input: + + o context_handle CONTEXT HANDLE + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + + +Linn Standards Track [Page 44] + +RFC 2078 GSS-API January 1997 + + + o output_context_token OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the context was recognized, and that + relevant context-specific information was flushed. If the caller + provides a non-null buffer to receive an output_context_token, and + the mechanism returns a non-NULL token into that buffer, the + returned output_context_token is ready for transfer to the + context's peer. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided, so no deletion was + performed. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the GSS_Delete_sec_context() operation could not be + performed for reasons unspecified at the GSS-API level. + + This call may block pending network interactions for mech_types in + which active notification must be made to a central server when a + security context is to be deleted. + + This call can be made by either peer in a security context, to flush + context-specific information. If a non-null output_context_token + parameter is provided by the caller, an output_context_token may be + returned to the caller. If an output_context_token is provided to + the caller, it can be passed to the context's peer to inform the + peer's GSS-API implementation that the peer's corresponding context + information can also be flushed. (Once a context is established, the + peers involved are expected to retain cached credential and context- + related information until the information's expiration time is + reached or until a GSS_Delete_sec_context() call is made.) + + The facility for context_token usage to signal context deletion is + retained for compatibility with GSS-API Version 1. For current + usage, it is recommended that both peers to a context invoke + GSS_Delete_sec_context() independently, passing a null + output_context_token buffer to indicate that no context_token is + required. Implementations of GSS_Delete_sec_context() should delete + relevant locally-stored context information. + + Attempts to perform per-message processing on a deleted context will + result in error returns. + + + + + + + +Linn Standards Track [Page 45] + +RFC 2078 GSS-API January 1997 + + +2.2.4: GSS_Process_context_token call + + Inputs: + + o context_handle CONTEXT HANDLE, + + o input_context_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_context_token was + successfully processed in conjunction with the context + referenced by context_handle. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks + performed on the received context_token failed, preventing + further processing from being performed with that token. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the GSS_Process_context_token() operation could not be + performed for reasons unspecified at the GSS-API level. + + This call is used to process context_tokens received from a peer once + a context has been established, with corresponding impact on + context-level state information. One use for this facility is + processing of the context_tokens generated by + GSS_Delete_sec_context(); GSS_Process_context_token() will not block + pending network interactions for that purpose. Another use is to + process tokens indicating remote-peer context establishment failures + after the point where the local GSS-API implementation has already + indicated GSS_S_COMPLETE status. + + + + + + + + + + + +Linn Standards Track [Page 46] + +RFC 2078 GSS-API January 1997 + + +2.2.5: GSS_Context_time call + + Input: + + o context_handle CONTEXT HANDLE, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o lifetime_rec INTEGER - in seconds, or reserved value for + INDEFINITE + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context is valid, + and will remain valid for the amount of time indicated in + lifetime_rec. + + o GSS_S_CONTEXT_EXPIRED indicates that data items related to the + referenced context have expired. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is + recognized, but that its associated credentials have expired. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. + + This call is used to determine the amount of time for which a + currently established context will remain valid. + +2.2.6: GSS_Inquire_context call + + Input: + + o context_handle CONTEXT HANDLE, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + + + +Linn Standards Track [Page 47] + +RFC 2078 GSS-API January 1997 + + + o src_name INTERNAL NAME, -- name of context initiator, + -- guaranteed to be MN + + o targ_name INTERNAL NAME, -- name of context target, + -- guaranteed to be MN + + + o lifetime_rec INTEGER -- in seconds, or reserved value for + INDEFINITE, + + o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this + security context + + o deleg_state BOOLEAN, + + o mutual_state BOOLEAN, + + o replay_det_state BOOLEAN, + + o sequence_state BOOLEAN, + + o anon_state BOOLEAN, + + o trans_state BOOLEAN, + + o prot_ready_state BOOLEAN, + + o conf_avail BOOLEAN, + + o integ_avail BOOLEAN, + + o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context is valid + and that src_name, targ_name, lifetime_rec, mech_type, deleg_state, + mutual_state, replay_det_state, sequence_state, anon_state, + trans_state, prot_ready_state, conf_avail, integ_avail, and + locally_initiated return values describe the corresponding + characteristics of the context. + + o GSS_S_CONTEXT_EXPIRED indicates that the provided input + context_handle is recognized, but that the referenced context + has expired. Return values other than major_status and + minor_status are undefined. + + + + + +Linn Standards Track [Page 48] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call is used to extract information describing characteristics + of a security context. + +2.2.7: GSS_Wrap_size_limit call + + Inputs: + + o context_handle CONTEXT HANDLE, + + o qop INTEGER, + + o output_size INTEGER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o max_input_size INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates a successful token size determination: + an input message with a length in octets equal to the + returned max_input_size value will, when passed to GSS_Wrap() + for processing on the context identified by the context_handle + parameter and with the quality of protection specifier provided + in the qop parameter, yield an output token no larger than the + value of the provided output_size parameter. + + o GSS_S_CONTEXT_EXPIRED indicates that the provided input + context_handle is recognized, but that the referenced context + has expired. Return values other than major_status and + minor_status are undefined. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + + + +Linn Standards Track [Page 49] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call is used to determine the largest input datum which may be + passed to GSS_Wrap() without yielding an output token larger than a + caller-specified value. + +2.2.8: GSS_Export_sec_context call + + Inputs: + + o context_handle CONTEXT HANDLE + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o interprocess_token OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the referenced context has been + successfully exported to a representation in the interprocess_token, + and is no longer available for use by the caller. + + o GSS_S_UNAVAILABLE indicates that the context export facility + is not available for use on the referenced context. (This status + should occur only for contexts for which the trans_state value is + FALSE.) Return values other than major_status and minor_status are + undefined. + + o GSS_S_CONTEXT_EXPIRED indicates that the provided input + context_handle is recognized, but that the referenced context has + expired. Return values other than major_status and minor_status are + undefined. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. Return values other than + major_status and minor_status are undefined. + + + + + + +Linn Standards Track [Page 50] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call generates an interprocess token for transfer to another + process within an end system, in order to transfer control of a + security context to that process. The recipient of the interprocess + token will call GSS_Import_sec_context() to accept the transfer. The + GSS_Export_sec_context() operation is defined for use only with + security contexts which are fully and successfully established (i.e., + those for which GSS_Init_sec_context() and GSS_Accept_sec_context() + have returned GSS_S_COMPLETE major_status). + + To ensure portability, a caller of GSS_Export_sec_context() must not + assume that a context may continue to be used once it has been + exported; following export, the context referenced by the + context_handle cannot be assumed to remain valid. Further, portable + callers must not assume that a given interprocess token can be + imported by GSS_Import_sec_context() more than once, thereby creating + multiple instantiations of a single context. GSS-API implementations + may detect and reject attempted multiple imports, but are not + required to do so. + + The internal representation contained within the interprocess token + is an implementation-defined local matter. Interprocess tokens + cannot be assumed to be transferable across different GSS-API + implementations. + + It is recommended that GSS-API implementations adopt policies suited + to their operational environments in order to define the set of + processes eligible to import a context, but specific constraints in + this area are local matters. Candidate examples include transfers + between processes operating on behalf of the same user identity, or + processes comprising a common job. However, it may be impossible to + enforce such policies in some implementations. + + In support of the above goals, implementations may protect the + transferred context data by using cryptography to protect data within + the interprocess token, or by using interprocess tokens as a means to + reference local interprocess communication facilities (protected by + other means) rather than storing the context data directly within the + tokens. + + Transfer of an open context may, for certain mechanisms and + implementations, reveal data about the credential which was used to + establish the context. Callers should, therefore, be cautious about + the trustworthiness of processes to which they transfer contexts. + Although the GSS-API implementation may provide its own set of + + + +Linn Standards Track [Page 51] + +RFC 2078 GSS-API January 1997 + + + protections over the exported context, the caller is responsible for + protecting the interprocess token from disclosure, and for taking + care that the context is transferred to an appropriate destination + process. + +2.2.9: GSS_Import_sec_context call + + Inputs: + + o interprocess_token OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o context_handle CONTEXT HANDLE + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the context represented by the + input interprocess_token has been successfully transferred to + the caller, and is available for future use via the output + context_handle. + + o GSS_S_CONTEXT_EXPIRED indicates that the context represented by + the input interprocess_token has expired. Return values other + than major_status and minor_status are undefined. + + o GSS_S_NO_CONTEXT indicates that the context represented by the + input interprocess_token was invalid. Return values other than + major_status and minor_status are undefined. + + o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token + was defective. Return values other than major_status and + minor_status are undefined. + + o GSS_S_UNAVAILABLE indicates that the context import facility + is not available for use on the referenced context. Return values + other than major_status and minor_status are undefined. + + o GSS_S_UNAUTHORIZED indicates that the context represented by + the input interprocess_token is unauthorized for transfer to the + caller. Return values other than major_status and minor_status + are undefined. + + + + + +Linn Standards Track [Page 52] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that the requested operation failed for + reasons unspecified at the GSS-API level. Return values other than + major_status and minor_status are undefined. + + This call processes an interprocess token generated by + GSS_Export_sec_context(), making the transferred context available + for use by the caller. After a successful GSS_Import_sec_context() + operation, the imported context is available for use by the importing + process. + + For further discussion of the security and authorization issues + regarding this call, please see the discussion in Section 2.2.8. + +2.3: Per-message calls + + This group of calls is used to perform per-message protection + processing on an established security context. None of these calls + block pending network interactions. These calls may be invoked by a + context's initiator or by the context's target. The four members of + this group should be considered as two pairs; the output from + GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output + from GSS_Wrap() is properly input to GSS_Unwrap(). + + GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication + and data integrity services. When GSS_GetMIC() is invoked on an + input message, it yields a per-message token containing data items + which allow underlying mechanisms to provide the specified security + services. The original message, along with the generated per-message + token, is passed to the remote peer; these two data elements are + processed by GSS_VerifyMIC(), which validates the message in + conjunction with the separate token. + + GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality + in addition to the data origin authentication and data integrity + services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() + outputs a single data element, encapsulating optionally enciphered + user data as well as associated token data items. The data element + output from GSS_Wrap() is passed to the remote peer and processed by + GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as + required) with validation of data items related to authentication and + integrity. + + + + + + + + + + +Linn Standards Track [Page 53] + +RFC 2078 GSS-API January 1997 + + +2.3.1: GSS_GetMIC call + + Note: This call is functionally equivalent to the GSS_Sign call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Sign are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o qop_req INTEGER,-0 specifies default QOP + + o message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o per_msg_token OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that an integrity check, suitable for an + established security context, was successfully applied and + that the message and corresponding per_msg_token are ready + for transmission. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data + items have expired, so that the requested operation cannot be + performed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the requested operation could not be performed for + reasons unspecified at the GSS-API level. + + + +Linn Standards Track [Page 54] + +RFC 2078 GSS-API January 1997 + + + Using the security context referenced by context_handle, apply an + integrity check to the input message (along with timestamps and/or + other data included in support of mech_type-specific mechanisms) and + return the result in per_msg_token. The qop_req parameter, + interpretation of which is discussed in Section 1.2.4, allows + quality-of-protection control. The caller passes the message and the + per_msg_token to the target. + + The GSS_GetMIC() function completes before the message and + per_msg_token is sent to the peer; successful application of + GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() + has been (or can necessarily be) performed successfully when the + message arrives at the destination. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.2: GSS_VerifyMIC call + + Note: This call is functionally equivalent to the GSS_Verify call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Verify are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o message OCTET STRING, + + o per_msg_token OCTET STRING + + Outputs: + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the message was successfully + verified. + + + + + + +Linn Standards Track [Page 55] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the received per_msg_token failed, preventing + further processing from being performed with that token. + + o GSS_S_BAD_SIG indicates that the received per_msg_token contains + an incorrect integrity check for the message. + + o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, + and GSS_S_GAP_TOKEN values appear in conjunction with the + optional per-message replay detection features described + in Section 1.2.3; their semantics are described in that section. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data + items have expired, so that the requested operation cannot be + performed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the GSS_VerifyMIC() operation could not be performed for + reasons unspecified at the GSS-API level. + + Using the security context referenced by context_handle, verify that + the input per_msg_token contains an appropriate integrity check for + the input message, and apply any active replay detection or + sequencing features. Return an indication of the quality-of- + protection applied to the processed message in the qop_state result. + Since the GSS_VerifyMIC() routine never provides a confidentiality + service, its implementations should not return non-zero values in the + confidentiality fields of the output qop_state. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.3: GSS_Wrap call + + Note: This call is functionally equivalent to the GSS_Seal call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Seal are deprecated. + + + + +Linn Standards Track [Page 56] + +RFC 2078 GSS-API January 1997 + + + Inputs: + + o context_handle CONTEXT HANDLE, + + o conf_req_flag BOOLEAN, + + o qop_req INTEGER,-0 specifies default QOP + + o input_message OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o conf_state BOOLEAN, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_message was successfully + processed and that the output_message is ready for + transmission. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data + items have expired, so that the requested operation cannot be + performed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_BAD_QOP indicates that the provided QOP value is not + recognized or supported for the context. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the GSS_Wrap() operation could not be performed for + reasons unspecified at the GSS-API level. + + Performs the data origin authentication and data integrity functions + of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that + confidentiality be applied to the input_message. Confidentiality may + + + +Linn Standards Track [Page 57] + +RFC 2078 GSS-API January 1997 + + + not be supported in all mech_types or by all implementations; the + returned conf_state flag indicates whether confidentiality was + provided for the input_message. The qop_req parameter, interpretation + of which is discussed in Section 1.2.4, allows quality-of-protection + control. + + In all cases, the GSS_Wrap() call yields a single output_message + data element containing (optionally enciphered) user data as well as + control information. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.3.4: GSS_Unwrap call + + Note: This call is functionally equivalent to the GSS_Unseal call as + defined in previous versions of this specification. In the interests + of backward compatibility, it is recommended that implementations + support this function under both names for the present; future + references to this function as GSS_Unseal are deprecated. + + Inputs: + + o context_handle CONTEXT HANDLE, + + o input_message OCTET STRING + + Outputs: + + o conf_state BOOLEAN, + + o qop_state INTEGER, + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_message OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the input_message was + successfully processed and that the resulting output_message is + available. + + o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed + on the per_msg_token extracted from the input_message + failed, preventing further processing from being performed. + + + +Linn Standards Track [Page 58] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_SIG indicates that an incorrect integrity check was + detected + for the message. + + o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, + and GSS_S_GAP_TOKEN values appear in conjunction with the + optional per-message replay detection features described + in Section 1.2.3; their semantics are described in that section. + + o GSS_S_CONTEXT_EXPIRED indicates that context-related data + items have expired, so that the requested operation cannot be + performed. + + o GSS_S_CREDENTIALS_EXPIRED indicates that the context is + recognized, + but that its associated credentials have expired, so + that the requested operation cannot be performed. + + o GSS_S_NO_CONTEXT indicates that no valid context was recognized + for the input context_handle provided. + + o GSS_S_FAILURE indicates that the context is recognized, but + that the GSS_Unwrap() operation could not be performed for + reasons unspecified at the GSS-API level. + + Processes a data element generated (and optionally enciphered) by + GSS_Wrap(), provided as input_message. The returned conf_state value + indicates whether confidentiality was applied to the input_message. + If conf_state is TRUE, GSS_Unwrap() deciphers the input_message. + Returns an indication of the quality-of-protection applied to the + processed message in the qop_state result. GSS_Wrap() performs the + data integrity and data origin authentication checking functions of + GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in + output_message. + + Mechanisms which do not support per-message protection services + should return GSS_S_FAILURE if this routine is called. + +2.4: Support calls + + This group of calls provides support functions useful to GSS-API + callers, independent of the state of established contexts. Their + characterization with regard to blocking or non-blocking status in + terms of network interactions is unspecified. + + + + + + + +Linn Standards Track [Page 59] + +RFC 2078 GSS-API January 1997 + + +2.4.1: GSS_Display_status call + + Inputs: + + o status_value INTEGER,-GSS-API major_status or minor_status + return value + + o status_type INTEGER,-1 if major_status, 2 if minor_status + + o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ + status translation + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o status_string_set SET OF OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid printable status + representation (possibly representing more than one status event + encoded within the status_value) is available in the returned + status_string_set. + + o GSS_S_BAD_MECH indicates that translation in accordance with an + unsupported mech_type was requested, so translation could not + be performed. + + o GSS_S_BAD_STATUS indicates that the input status_value was + invalid, or that the input status_type carried a value other + than 1 or 2, so translation could not be performed. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Provides a means for callers to translate GSS-API-returned major and + minor status codes into printable string representations. + +2.4.2: GSS_Indicate_mechs call + + Input: + + o (none) + + + + + +Linn Standards Track [Page 60] + +RFC 2078 GSS-API January 1997 + + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a set of available mechanisms has + been returned in mech_set. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of mechanism types available on + the local system. This call is intended for support of specialized + callers who need to request non-default mech_type sets from + GSS_Acquire_cred(), and should not be needed by other callers. + +2.4.3: GSS_Compare_name call + + Inputs: + + o name1 INTERNAL NAME, + + o name2 INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_equal BOOLEAN + + Return major_status codes: + + o GSS_S_COMPLETE indicates that name1 and name2 were comparable, + and that the name_equal result indicates whether name1 and + name2 represent the same entity. + + o GSS_S_BAD_NAMETYPE indicates that one or both of name1 and + name2 contained internal type specifiers uninterpretable + by the applicable underlying GSS-API mechanism(s), or that + the two names' types are different and incomparable, so that + the comparison operation could not be completed. + + + +Linn Standards Track [Page 61] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_BAD_NAME indicates that one or both of the input names + was ill-formed in terms of its internal type specifier, so + the comparison operation could not be completed. + + o GSS_S_FAILURE indicates that the call's operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to compare two internal name representations to + determine whether they refer to the same entity. If either name + presented to GSS_Compare_name() denotes an anonymous principal, + GSS_Compare_name() shall indicate FALSE. It is not required that + either or both inputs name1 and name2 be MNs; for some + implementations and cases, GSS_S_BAD_NAMETYPE may be returned, + indicating name incomparability, for the case where neither input + name is an MN. + +2.4.4: GSS_Display_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o name_string OCTET STRING, + + o name_type OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid printable name + representation is available in the returned name_string. + + o GSS_S_BAD_NAMETYPE indicates that the provided name was of a + type uninterpretable by the applicable underlying GSS-API + mechanism(s), so no printable representation could be generated. + + o GSS_S_BAD_NAME indicates that the contents of the provided name + were inconsistent with the internally-indicated name type, so + no printable representation could be generated. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + + + +Linn Standards Track [Page 62] + +RFC 2078 GSS-API January 1997 + + + Allows callers to translate an internal name representation into a + printable form with associated namespace type descriptor. The syntax + of the printable form is a local matter. + + If the input name represents an anonymous identity, a reserved value + (GSS_C_NT_ANONYMOUS) shall be returned for name_type. + +2.4.5: GSS_Import_name call + + Inputs: + + o input_name_string OCTET STRING, + + o input_name_type OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a valid name representation is + output in output_name and described by the type value in + output_name_type. + + o GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported + by the applicable underlying GSS-API mechanism(s), so the import + operation could not be completed. + + o GSS_S_BAD_NAME indicates that the provided input_name_string + is ill-formed in terms of the input_name_type, so the import + operation could not be completed. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to provide a name representation as a contiguous octet + string, designate the type of namespace in conjunction with which it + should be parsed, and convert that representation to an internal form + suitable for input to other GSS-API routines. The syntax of the + input_name_string is defined in conjunction with its associated name + type; depending on the input_name_type, the associated + input_name_string may or may not be a printable string. Note: The + input_name_type argument serves to describe and qualify the + + + +Linn Standards Track [Page 63] + +RFC 2078 GSS-API January 1997 + + + interpretation of the associated input_name_string; it does not + specify the data type of the returned output_name. + + If a mechanism claims support for a particular name type, its + GSS_Import_name() operation shall be able to accept all possible + values conformant to the external name syntax as defined for that + name type. These imported values may correspond to: + + (1) locally registered entities (for which credentials may be + acquired), + + (2) non-local entities (for which local credentials cannot be + acquired, but which may be referenced as targets of initiated + security contexts or initiators of accepted security contexts), or + to + + (3) neither of the above. + + Determination of whether a particular name belongs to class (1), (2), + or (3) as described above is not guaranteed to be performed by the + GSS_Import_name() function. + + The internal name generated by a GSS_Import_name() operation may be a + single-mechanism MN, and is likely to be an MN within a single- + mechanism implementation, but portable callers must not depend on + this property (and must not, therefore, assume that the output from + GSS_Import_name() can be passed directly to GSS_Export_name() without + first being processed through GSS_Canonicalize_name()). + +2.4.6: GSS_Release_name call + + Inputs: + + o name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input name was successfully released. + + o GSS_S_BAD_NAME indicates that the input name argument did not + contain a valid name. + + + +Linn Standards Track [Page 64] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an internal + name representation. This call's specific behavior depends on the + language and programming environment within which a GSS-API + implementation operates, and is therefore detailed within applicable + bindings specifications; in particular, this call may be superfluous + within bindings where memory management is automatic. + +2.4.7: GSS_Release_buffer call + + Inputs: + + o buffer OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input buffer was successfully released. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an OCTET STRING + buffer allocated by another GSS-API call. This call's specific + behavior depends on the language and programming environment within + which a GSS-API implementation operates, and is therefore detailed + within applicable bindings specifications; in particular, this call + may be superfluous within bindings where memory management is + automatic. + +2.4.8: GSS_Release_OID_set call + + Inputs: + + o buffer SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + + + +Linn Standards Track [Page 65] + +RFC 2078 GSS-API January 1997 + + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the storage associated with the + input object identifier set was successfully released. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to release the storage associated with an object + identifier set object allocated by another GSS-API call. This call's + specific behavior depends on the language and programming environment + within which a GSS-API implementation operates, and is therefore + detailed within applicable bindings specifications; in particular, + this call may be superfluous within bindings where memory management + is automatic. + +2.4.9: GSS_Create_empty_OID_set call + + Inputs: + + o (none) + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + Creates an object identifier set containing no object identifiers, to + which members may be subsequently added using the + GSS_Add_OID_set_member() routine. These routines are intended to be + used to construct sets of mechanism object identifiers, for input to + GSS_Acquire_cred(). + + + + + + + + +Linn Standards Track [Page 66] + +RFC 2078 GSS-API January 1997 + + +2.4.10: GSS_Add_OID_set_member call + + Inputs: + + o member_oid OBJECT IDENTIFIER, + + o oid_set SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + Adds an Object Identifier to an Object Identifier set. This routine + is intended for use in conjunction with GSS_Create_empty_OID_set() + when constructing a set of mechanism OIDs for input to + GSS_Acquire_cred(). + +2.4.11: GSS_Test_OID_set_member call + + Inputs: + + o member OBJECT IDENTIFIER, + + o set SET OF OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o present BOOLEAN + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + + + + +Linn Standards Track [Page 67] + +RFC 2078 GSS-API January 1997 + + + Interrogates an Object Identifier set to determine whether a + specified Object Identifier is a member. This routine is intended to + be used with OID sets returned by GSS_Indicate_mechs(), + GSS_Acquire_cred(), and GSS_Inquire_cred(). + +2.4.12: GSS_Release_OID call + + Inputs: + + o oid OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + Allows the caller to release the storage associated with an OBJECT + IDENTIFIER buffer allocated by another GSS-API call. This call's + specific behavior depends on the language and programming environment + within which a GSS-API implementation operates, and is therefore + detailed within applicable bindings specifications; in particular, + this call may be superfluous within bindings where memory management + is automatic. + +2.4.13: GSS_OID_to_str call + + Inputs: + + o oid OBJECT IDENTIFIER + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid_str OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + + +Linn Standards Track [Page 68] + +RFC 2078 GSS-API January 1997 + + + o GSS_S_FAILURE indicates that the operation failed + + The function GSS_OID_to_str() returns a string representing the input + OID in numeric ASN.1 syntax format (curly-brace enclosed, space- + delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is + releasable using GSS_Release_buffer(). If the input "oid" does not + represent a syntactically valid object identifier, GSS_S_FAILURE + status is returned and the returned oid_str result is NULL. + +2.4.14: GSS_Str_to_OID call + + Inputs: + + o oid_str OCTET STRING + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o oid OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates successful completion + + o GSS_S_FAILURE indicates that the operation failed + + The function GSS_Str_to_OID() constructs and returns an OID from its + printable form; implementations should be able to accept the numeric + ASN.1 syntax form as described for GSS_OID_to_str(), and this form + should be used for portability, but implementations of this routine + may also accept other formats (e.g., "1.2.3.3"). The OID is suitable + for release using the function GSS_Release_OID(). If the input + oid_str cannot be translated into an OID, GSS_S_FAILURE status is + returned and the "oid" result is NULL. + +2.4.15: GSS_Inquire_names_for_mech call + + Input: + + o input_mech_type OBJECT IDENTIFIER, -- mechanism type + + Outputs: + + o major_status INTEGER, + + + + +Linn Standards Track [Page 69] + +RFC 2078 GSS-API January 1997 + + + o minor_status INTEGER, + + o name_type_set SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that the output name_type_set contains + a list of name types which are supported by the locally available + mechanism identified by input_mech_type. + + o GSS_S_BAD_MECH indicates that the mechanism identified by + input_mech_type was unsupported within the local implementation, + causing the query to fail. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + Allows callers to determine the set of name types which are + supportable by a specific locally-available mechanism. + +2.4.16: GSS_Inquire_mechs_for_name call + + Inputs: + + o input_name INTERNAL NAME, + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o mech_types SET OF OBJECT IDENTIFIER + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a set of object identifiers, + corresponding to the set of mechanisms suitable for processing + the input_name, is available in mech_types. + + o GSS_S_BAD_NAME indicates that the input_name could not be + processed. + + o GSS_S_BAD_NAMETYPE indicates that the type of the input_name + is unsupported by the GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + + +Linn Standards Track [Page 70] + +RFC 2078 GSS-API January 1997 + + + This routine returns the mechanism set with which the input_name may + be processed. After use, the mech_types object should be freed by + the caller via the GSS_Release_OID_set() call. Note: it is + anticipated that implementations of GSS_Inquire_mechs_for_name() will + commonly operate based on type information describing the + capabilities of available mechanisms; it is not guaranteed that all + identified mechanisms will necessarily be able to canonicalize (via + GSS_Canonicalize_name()) a particular name. + +2.4.17: GSS_Canonicalize_name call + + Inputs: + + o input_name INTERNAL NAME, + + o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, + not "default" specifier + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name INTERNAL NAME + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a mechanism-specific reduction of + the input_name, as processed by the mechanism identified by + mech_type, is available in output_name. + + o GSS_S_BAD_MECH indicates that the identified mechanism is + unsupported. + + o GSS_S_BAD_NAMETYPE indicates that the input name does not + contain an element with suitable type for processing by the + identified mechanism. + + o GSS_S_BAD_NAME indicates that the input name contains an + element with suitable type for processing by the identified + mechanism, but that this element could not be processed + successfully. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + + + + +Linn Standards Track [Page 71] + +RFC 2078 GSS-API January 1997 + + + This routine reduces a GSS-API internal name, which may in general + contain elements corresponding to multiple mechanisms, to a + mechanism-specific Mechanism Name (MN) by applying the translations + corresponding to the mechanism identified by mech_type. + +2.4.18: GSS_Export_name call + + Inputs: + + o input_name INTERNAL NAME, -- required to be MN + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o output_name OCTET STRING + + Return major_status codes: + + o GSS_S_COMPLETE indicates that a flat representation of the + input name is available in output_name. + + o GSS_S_NAME_NOT_MN indicates that the input name contained + elements corresponding to multiple mechanisms, so cannot + be exported into a single-mechanism flat form. + + o GSS_S_BAD_NAME indicates that the input name was an MN, + but could not be processed. + + o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, + but that its type is unsupported by the GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + This routine creates a flat name representation, suitable for + bytewise comparison or for input to GSS_Import_name() in conjunction + with the reserved GSS-API Exported Name Object OID, from a internal- + form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() + or GSS_Accept_sec_context(). + + The emitted GSS-API Exported Name Object is self-describing; no + associated parameter-level OID need be emitted by this call. This + flat representation consists of a mechanism-independent wrapper + layer, defined in Section 3.2 of this document, enclosing a + mechanism-defined name representation. + + + +Linn Standards Track [Page 72] + +RFC 2078 GSS-API January 1997 + + + In all cases, the flat name output by GSS_Export_name() to correspond + to a particular input MN must be invariant over time within a + particular installation. + + The GSS_S_NAME_NOT_MN status code is provided to enable + implementations to reject input names which are not MNs. It is not, + however, required for purposes of conformance to this specification + that all non-MN input names must necessarily be rejected. + +2.4.19: GSS_Duplicate_name call + + Inputs: + + o src_name INTERNAL NAME + + Outputs: + + o major_status INTEGER, + + o minor_status INTEGER, + + o dest_name INTERNAL NAME + + Return major_status codes: + + o GSS_S_COMPLETE indicates that dest_name references an internal + name object containing the same name as passed to src_name. + + o GSS_S_BAD_NAME indicates that the input name was invalid. + + o GSS_S_BAD_NAMETYPE indicates that the input name's type + is unsupported by the GSS-API implementation. + + o GSS_S_FAILURE indicates that the requested operation could not + be performed for reasons unspecified at the GSS-API level. + + This routine takes input internal name src_name, and returns another + reference (dest_name) to that name which can be used even if src_name + is later freed. (Note: This may be implemented by copying or through + use of reference counts.) + +3: Data Structure Definitions for GSS-V2 Usage + + Subsections of this section define, for interoperability and + portability purposes, certain data structures for use with GSS-V2. + + + + + + +Linn Standards Track [Page 73] + +RFC 2078 GSS-API January 1997 + + +3.1: Mechanism-Independent Token Format + + This section specifies a mechanism-independent level of encapsulating + representation for the initial token of a GSS-API context + establishment sequence, incorporating an identifier of the mechanism + type to be used on that context and enabling tokens to be interpreted + unambiguously at GSS-API peers. Use of this format is required for + initial context establishment tokens of Internet standards-track + GSS-API mechanisms; use in non-initial tokens is optional. + + The encoding format for the token tag is derived from ASN.1 and DER + (per illustrative ASN.1 syntax included later within this + subsection), but its concrete representation is defined directly in + terms of octets rather than at the ASN.1 level in order to facilitate + interoperable implementation without use of general ASN.1 processing + code. The token tag consists of the following elements, in order: + + 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that + constructed form, definite length encoding follows. + + 2. Token length octets, specifying length of subsequent data + (i.e., the summed lengths of elements 3-5 in this list, and of the + mechanism-defined token object following the tag). This element + comprises a variable number of octets: + + 2a. If the indicated value is less than 128, it shall be + represented in a single octet with bit 8 (high order) set to "0" + and the remaining bits representing the value. + + 2b. If the indicated value is 128 or more, it shall be represented + in two or more octets, with bit 8 of the first octet set to "1" + and the remaining bits of the first octet specifying the number of + additional octets. The subsequent octets carry the value, 8 bits + per octet, most significant digit first. The minimum number of + octets shall be used to encode the length (i.e., no octets + representing leading zeros shall be included within the length + encoding). + + 3. 0x06 -- Tag for OBJECT IDENTIFIER + + 4. Object identifier length -- length (number of octets) of the + encoded object identifier contained in element 5, encoded per + rules as described in 2a. and 2b. above. + + 5. Object identifier octets -- variable number of octets, encoded + per ASN.1 BER rules: + + + + + +Linn Standards Track [Page 74] + +RFC 2078 GSS-API January 1997 + + + 5a. The first octet contains the sum of two values: (1) the top- + level object identifier component, multiplied by 40 (decimal), and + (2) the second-level object identifier component. This special + case is the only point within an object identifier encoding where + a single octet represents contents of more than one component. + + 5b. Subsequent octets, if required, encode successively-lower + components in the represented object identifier. A component's + encoding may span multiple octets, encoding 7 bits per octet (most + significant bits first) and with bit 8 set to "1" on all but the + final octet in the component's encoding. The minimum number of + octets shall be used to encode each component (i.e., no octets + representing leading zeros shall be included within a component's + encoding). + + (Note: In many implementations, elements 3-5 may be stored and + referenced as a contiguous string constant.) + + The token tag is immediately followed by a mechanism-defined token + object. Note that no independent size specifier intervenes following + the object identifier value to indicate the size of the mechanism- + defined token object. While ASN.1 usage within mechanism-defined + tokens is permitted, there is no requirement that the mechanism- + specific innerContextToken, innerMsgToken, and sealedUserData data + elements must employ ASN.1 BER/DER encoding conventions. + + + + + + + + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 75] + +RFC 2078 GSS-API January 1997 + + + The following ASN.1 syntax is included for descriptive purposes only, + to illustrate structural relationships among token and tag objects. + For interoperability purposes, token and tag encoding shall be + performed using the concrete encoding procedures described earlier in + this subsection. + + GSS-API DEFINITIONS ::= + + BEGIN + + MechType ::= OBJECT IDENTIFIER + -- data structure definitions + + -- callers must be able to distinguish among + -- InitialContextToken, SubsequentContextToken, + -- PerMsgToken, and SealedMessage data elements + -- based on the usage in which they occur + + InitialContextToken ::= + -- option indication (delegation, etc.) indicated within + -- mechanism-specific token + [APPLICATION 0] IMPLICIT SEQUENCE { + thisMech MechType, + innerContextToken ANY DEFINED BY thisMech + -- contents mechanism-specific + -- ASN.1 structure not required + } + + SubsequentContextToken ::= innerContextToken ANY + -- interpretation based on predecessor InitialContextToken + -- ASN.1 structure not required + + PerMsgToken ::= + -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC + -- ASN.1 structure not required + innerMsgToken ANY + + SealedMessage ::= + -- as emitted by GSS_Wrap and processed by GSS_Unwrap + -- includes internal, mechanism-defined indicator + -- of whether or not encrypted + -- ASN.1 structure not required + sealedUserData ANY + + END + + + + + + +Linn Standards Track [Page 76] + +RFC 2078 GSS-API January 1997 + + +3.2: Mechanism-Independent Exported Name Object Format + + This section specifies a mechanism-independent level of encapsulating + representation for names exported via the GSS_Export_name() call, + including an object identifier representing the exporting mechanism. + The format of names encapsulated via this representation shall be + defined within individual mechanism drafts. Name objects of this + type will be identified with the following Object Identifier: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 4(gss-api-exported-name)} + + No name type OID is included in this mechanism-independent level of + format definition, since (depending on individual mechanism + specifications) the enclosed name may be implicitly typed or may be + explicitly typed using a means other than OID encoding. + + Length Name Description + + 2 TOK_ID Token Identifier + For exported name objects, this + must be hex 04 01. + 2 MECH_OID_LEN Length of the Mechanism OID + MECH_OID_LEN MECH_OID Mechanism OID, in DER + 4 NAME_LEN Length of name + NAME_LEN NAME Exported name; format defined in + applicable mechanism draft. + +4: Name Type Definitions + + This section includes definitions for name types and associated + syntaxes which are defined in a mechanism-independent fashion at the + GSS-API level rather than being defined in individual mechanism + specifications. + +4.1: Host-Based Service Name Form + + The following Object Identifier value is provided as a means to + identify this name form: + + {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), + 2(gss-host-based-services)} + + The recommended symbolic name for this type is + "GSS_C_NT_HOSTBASED_SERVICE". + + + + + + +Linn Standards Track [Page 77] + +RFC 2078 GSS-API January 1997 + + + This name type is used to represent services associated with host + computers. This name form is constructed using two elements, + "service" and "hostname", as follows: + + service@hostname + + When a reference to a name of this type is resolved, the "hostname" + is canonicalized by attempting a DNS lookup and using the fully- + qualified domain name which is returned, or by using the "hostname" + as provided if the DNS lookup fails. The canonicalization operation + also maps the host's name into lower-case characters. + + The "hostname" element may be omitted. If no "@" separator is + included, the entire name is interpreted as the service specifier, + with the "hostname" defaulted to the canonicalized name of the local + host. + + Values for the "service" element are registered with the IANA. + +4.2: User Name Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) user_name(1)}. The recommended mechanism-independent + symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same + name form and OID is defined within the Kerberos V5 GSS-API + mechanism, but the symbolic name recommended there begins with a + "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a named user on a local system. + Its interpretation is OS-specific. This name form is constructed as: + + username + +4.3: Machine UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) machine_uid_name(2)}. The recommended mechanism- + independent symbolic name for this type is + "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is + defined within the Kerberos V5 GSS-API mechanism, but the symbolic + name recommended there begins with a "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a numeric user identifier + corresponding to a user on a local system. Its interpretation is + OS-specific. The gss_buffer_desc representing a name of this type + should contain a locally-significant uid_t, represented in host byte + + + +Linn Standards Track [Page 78] + +RFC 2078 GSS-API January 1997 + + + order. The GSS_Import_name() operation resolves this uid into a + username, which is then treated as the User Name Form. + +4.4: String UID Form + + This name form shall be represented by the Object Identifier {iso(1) + member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) + generic(1) string_uid_name(3)}. The recommended symbolic name for + this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form + and OID is defined within the Kerberos V5 GSS-API mechanism, but the + symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) + + This name type is used to indicate a string of digits representing + the numeric user identifier of a user on a local system. Its + interpretation is OS-specific. This name type is similar to the + Machine UID Form, except that the buffer contains a string + representing the uid_t. + +5: Mechanism-Specific Example Scenarios + + This section provides illustrative overviews of the use of various + candidate mechanism types to support the GSS-API. These discussions + are intended primarily for readers familiar with specific security + technologies, demonstrating how GSS-API functions can be used and + implemented by candidate underlying mechanisms. They should not be + regarded as constrictive to implementations or as defining the only + means through which GSS-API functions can be realized with a + particular underlying technology, and do not demonstrate all GSS-API + features with each technology. + +5.1: Kerberos V5, single-TGT + + OS-specific login functions yield a TGT to the local realm Kerberos + server; TGT is placed in a credentials structure for the client. + Client calls GSS_Acquire_cred() to acquire a cred_handle in order to + reference the credentials for use in establishing security contexts. + + Client calls GSS_Init_sec_context(). If the requested service is + located in a different realm, GSS_Init_sec_context() gets the + necessary TGT/key pairs needed to traverse the path from local to + target realm; these data are placed in the owner's TGT cache. After + any needed remote realm resolution, GSS_Init_sec_context() yields a + service ticket to the requested service with a corresponding session + key; these data are stored in conjunction with the context. GSS-API + code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP + response(s) (in the successful case) or KRB_ERROR. + + + + + +Linn Standards Track [Page 79] + +RFC 2078 GSS-API January 1997 + + + Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted + KRB_AP_REQ message, and returns it in output_token. The client sends + the output_token to the service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which verifies the authenticator, provides + the service with the client's authenticated name, and returns an + output_context_handle. + + Both parties now hold the session key associated with the service + ticket, and can use this key in subsequent GSS_GetMIC(), + GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. + +5.2: Kerberos V5, double-TGT + + TGT acquisition as above. + + Note: To avoid unnecessary frequent invocations of error paths when + implementing the GSS-API atop Kerberos V5, it seems appropriate to + represent "single-TGT K-V5" and "double-TGT K-V5" with separate + mech_types, and this discussion makes that assumption. + + Based on the (specified or defaulted) mech_type, + GSS_Init_sec_context() determines that the double-TGT protocol + should be employed for the specified target. GSS_Init_sec_context() + returns GSS_S_CONTINUE_NEEDED major_status, and its returned + output_token contains a request to the service for the service's TGT. + (If a service TGT with suitably long remaining lifetime already + exists in a cache, it may be usable, obviating the need for this + step.) The client passes the output_token to the service. Note: this + scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED + status return facility than for support of mutual authentication; + note that both uses can coexist as successive operations within a + single context establishment operation. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(), which recognizes it as a request for TGT. + (Note that current Kerberos V5 defines no intra-protocol mechanism to + represent such a request.) GSS_Accept_sec_context() returns + GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in + its output_token. The service sends the output_token to the client. + + The client passes the received token as the input_token argument to a + continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches + the received service TGT and uses it as part of a service ticket + request to the Kerberos authentication server, storing the returned + service ticket and session key in conjunction with the context. + GSS_Init_sec_context() builds a Kerberos-formatted authenticator, + + + +Linn Standards Track [Page 80] + +RFC 2078 GSS-API January 1997 + + + and returns it in output_token along with GSS_S_COMPLETE return + major_status. The client sends the output_token to the service. + + Service passes the received token as the input_token argument to a + continuation call to GSS_Accept_sec_context(). + GSS_Accept_sec_context() verifies the authenticator, provides the + service with the client's authenticated name, and returns + major_status GSS_S_COMPLETE. + + GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as + above. + +5.3: X.509 Authentication Framework + + This example illustrates use of the GSS-API in conjunction with + public-key mechanisms, consistent with the X.509 Directory + Authentication Framework. + + The GSS_Acquire_cred() call establishes a credentials structure, + making the client's private key accessible for use on behalf of the + client. + + The client calls GSS_Init_sec_context(), which interrogates the + Directory to acquire (and validate) a chain of public-key + certificates, thereby collecting the public key of the service. The + certificate validation operation determines that suitable integrity + checks were applied by trusted authorities and that those + certificates have not expired. GSS_Init_sec_context() generates a + secret key for use in per-message protection operations on the + context, and enciphers that secret key under the service's public + key. + + The enciphered secret key, along with an authenticator quantity + signed with the client's private key, is included in the output_token + from GSS_Init_sec_context(). The output_token also carries a + certification path, consisting of a certificate chain leading from + the service to the client; a variant approach would defer this path + resolution to be performed by the service instead of being asserted + by the client. The client application sends the output_token to the + service. + + The service passes the received token as the input_token argument to + GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the + certification path, and as a result determines a certified binding + between the client's distinguished name and the client's public key. + Given that public key, GSS_Accept_sec_context() can process the + input_token's authenticator quantity and verify that the client's + private key was used to sign the input_token. At this point, the + + + +Linn Standards Track [Page 81] + +RFC 2078 GSS-API January 1997 + + + client is authenticated to the service. The service uses its private + key to decipher the enciphered secret key provided to it for per- + message protection operations on the context. + + The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which + causes per-message authentication, integrity, and (optional) + confidentiality facilities to be applied to that message. The service + uses the context's shared secret key to perform corresponding + GSS_VerifyMIC() and GSS_Unwrap() calls. + +6: Security Considerations + + Security issues are discussed throughout this memo. + +7: Related Activities + + In order to implement the GSS-API atop existing, emerging, and future + security mechanisms: + + object identifiers must be assigned to candidate GSS-API + mechanisms and the name types which they support + + concrete data element formats and processing procedures must be + defined for candidate mechanisms + + Calling applications must implement formatting conventions which will + enable them to distinguish GSS-API tokens from other data carried in + their application protocols. + + Concrete language bindings are required for the programming + environments in which the GSS-API is to be employed, as RFC-1509 + defines for the C programming language and GSS-V1. + + + + + + + + + + + + + + + + + + + +Linn Standards Track [Page 82] + +RFC 2078 GSS-API January 1997 + + +APPENDIX A + +MECHANISM DESIGN CONSTRAINTS + + The following constraints on GSS-API mechanism designs are adopted in + response to observed caller protocol requirements, and adherence + thereto is anticipated in subsequent descriptions of GSS-API + mechanisms to be documented in standards-track Internet + specifications. + + It is strongly recommended that mechanisms offering per-message + protection services also offer at least one of the replay detection + and sequencing services, as mechanisms offering neither of the latter + will fail to satisfy recognized requirements of certain candidate + caller protocols. + +APPENDIX B + + COMPATIBILITY WITH GSS-V1 + + It is the intent of this document to define an interface and + procedures which preserve compatibility between GSS-V1 (RFC-1508) + callers and GSS- V2 providers. All calls defined in GSS-V1 are + preserved, and it has been a goal that GSS-V1 callers should be able + to operate atop GSS-V2 provider implementations. Certain detailed + changes, summarized in this section, have been made in order to + resolve omissions identified in GSS-V1. + + The following GSS-V1 constructs, while supported within GSS-V2, are + deprecated: + + Names for per-message processing routines: GSS_Seal() deprecated + in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of + GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); + GSS_Verify() deprecated in favor of GSS_VerifyMIC(). + + GSS_Delete_sec_context() facility for context_token usage, + allowing mechanisms to signal context deletion, is retained for + compatibility with GSS-V1. For current usage, it is recommended + that both peers to a context invoke GSS_Delete_sec_context() + independently, passing a null output_context_token buffer to + indicate that no context_token is required. Implementations of + GSS_Delete_sec_context() should delete relevant locally-stored + context information. + + + + + + + +Linn Standards Track [Page 83] + +RFC 2078 GSS-API January 1997 + + + This GSS-V2 specification adds the following calls which are not + present in GSS-V1: + + Credential management calls: GSS_Add_cred(), + GSS_Inquire_cred_by_mech(). + + Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), + GSS_Export_sec_context(), GSS_Import_sec_context(). + + Per-message calls: No new calls. Existing calls have been renamed. + + Support calls: GSS_Create_empty_OID_set(), + GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), + GSS_Release_OID(), GSS_OID_to_str(), GSS_Str_to_OID(), + GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), + GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). + + This GSS-V2 specification introduces three new facilities applicable + to security contexts, indicated using the following context state + values which are not present in GSS-V1: + + anon_state, set TRUE to indicate that a context's initiator is + anonymous from the viewpoint of the target; Section 1.2.5 of this + specification provides a summary description of the GSS-V2 + anonymity support facility, support and use of which is optional. + + prot_ready_state, set TRUE to indicate that a context may be used + for per-message protection before final completion of context + establishment; Section 1.2.7 of this specification provides a + summary description of the GSS-V2 facility enabling mechanisms to + selectively permit per-message protection during context + establishment, support and use of which is optional. + + trans_state, set TRUE to indicate that a context is transferable to + another process using the GSS-V2 GSS_Export_sec_context() facility. + + These state values are represented (at the C bindings level) in + positions within a bit vector which are unused in GSS-V1, and may be + safely ignored by GSS-V1 callers. + + Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API + implementors in the following areas: implementation robustness, + credential management, behavior in multi-mechanism configurations, + naming support, and inclusion of optional sequencing services. The + token tagging facility as defined in GSS-V2, Section 3.1, is now + described directly in terms of octets to facilitate interoperable + implementation without general ASN.1 processing code; the + corresponding ASN.1 syntax, included for descriptive purposes, is + + + +Linn Standards Track [Page 84] + +RFC 2078 GSS-API January 1997 + + + unchanged from that in GSS-V1. For use in conjunction with added + naming support facilities, a new Exported Name Object construct is + added. Additional name types are introduced in Section 4. + + This GSS-V2 specification adds the following major_status values + which are not defined in GSS-V1: + + GSS_S_BAD_QOP unsupported QOP value + GSS_S_UNAUTHORIZED operation unauthorized + GSS_S_UNAVAILABLE operation unavailable + GSS_S_DUPLICATE_ELEMENT duplicate credential element requested + GSS_S_NAME_NOT_MN name contains multi-mechanism elements + GSS_S_GAP_TOKEN skipped predecessor token(s) + detected + + Of these added status codes, only two values are defined to be + returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by + GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by + GSS_VerifyMIC() and GSS_Unwrap()). + + Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 + have been updated to allow return of additional major_status values + from the set as defined in GSS-V1: GSS_Inquire_cred() has + GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as + returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, + GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and + GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. + +Author's Address + + John Linn + OpenVision Technologies + One Main St. + Cambridge, MA 02142 USA + + Phone: +1 617.374.2245 + EMail: John.Linn@ov.com + + + + + + + + + + + + + + +Linn Standards Track [Page 85] + diff --git a/crypto/heimdal/doc/standardisation/rfc2203.txt b/crypto/heimdal/doc/standardisation/rfc2203.txt new file mode 100644 index 0000000..2f6a8a0 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc2203.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group M. Eisler +Request for Comments: 2203 A. Chiu +Category: Standards Track L. Ling + September 1997 + + + RPCSEC_GSS Protocol Specification + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This memo describes an ONC/RPC security flavor that allows RPC + protocols to access the Generic Security Services Application + Programming Interface (referred to henceforth as GSS-API). + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. The ONC RPC Message Protocol . . . . . . . . . . . . . . . . . 2 + 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 3 + 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 3 + 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 3 + 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 5 + 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 5 + 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 5 + 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 6 + 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 8 + 5.2.3.1. Context Creation Response - Successful Acceptance . . . 8 + 5.2.3.1.1. Client Processing of Successful Context Creation + Responses . . . . . . . . . . . . . . . . . . . . . . 9 + 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . . 9 + 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 10 + 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 10 + 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 11 + 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 11 + 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 11 + 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 12 + 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 12 + 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 12 + 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 + 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 15 + + + +Eisler, et. al. Standards Track [Page 1] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 16 + 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 + 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 16 + 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 16 + 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 17 + 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 + 7. Security Considerations . . . . . . . . . . . . . . . . . . 18 + 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 18 + 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 + 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 + 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 + 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 19 + Appendix A. GSS-API Major Status Codes . . . . . . . . . . . . . 20 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 + +1. Introduction + + This document describes the protocol used by the RPCSEC_GSS security + flavor. Security flavors have been called authentication flavors for + historical reasons. This memo recognizes that there are two other + security services besides authentication, integrity, and privacy, and + so defines a new RPCSEC_GSS security flavor. + + The protocol is described using the XDR language [Srinivasan-xdr]. + The reader is assumed to be familiar with ONC RPC and the security + flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be + familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security + flavor uses GSS-API interfaces to provide security services that are + independent of the underlying security mechanism. + +2. The ONC RPC Message Protocol + + This memo refers to the following XDR types of the ONC RPC protocol, + which are described in the document entitled Remote Procedure Call + Protocol Specification Version 2 [Srinivasan-rpc]: + + msg_type + reply_stat + auth_flavor + accept_stat + reject_stat + auth_stat + opaque_auth + rpc_msg + call_body + reply_body + + + +Eisler, et. al. Standards Track [Page 2] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + accepted_reply + rejected_reply + +3. Flavor Number Assignment + + The RPCSEC_GSS security flavor has been assigned the value of 6: + + enum auth_flavor { + ... + RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ + }; + +4. New auth_stat Values + + RPCSEC_GSS requires the addition of two new values to the auth_stat + enumerated type definition: + + enum auth_stat { + ... + /* + * RPCSEC_GSS errors + */ + RPCSEC_GSS_CREDPROBLEM = 13, + RPCSEC_GSS_CTXPROBLEM = 14 + }; + + The descriptions of these two new values are defined later in this + memo. + +5. Elements of the RPCSEC_GSS Security Protocol + + An RPC session based on the RPCSEC_GSS security flavor consists of + three phases: context creation, RPC data exchange, and context + destruction. In the following discussion, protocol elements for + these three phases are described. + + The following description of the RPCSEC_GSS protocol uses some of the + definitions within XDR language description of the RPC protocol. + + Context creation and destruction use control messages that are not + dispatched to service procedures registered by an RPC server. The + program and version numbers used in these control messages are the + same as the RPC service's program and version numbers. The procedure + number used is NULLPROC (zero). A field in the credential + information (the gss_proc field which is defined in the + rpc_gss_cred_t structure below) specifies whether a message is to be + interpreted as a control message or a regular RPC message. If this + field is set to RPCSEC_GSS_DATA, no control action is implied; in + + + +Eisler, et. al. Standards Track [Page 3] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + this case, it is a regular data message. If this field is set to any + other value, a control action is implied. This is described in the + following sections. + + Just as with normal RPC data exchange messages, the transaction + identifier (the xid field in struct rpc_msg), should be set to unique + values on each call for context creation and context destruction. + + The following definitions are used for describing the protocol. + + /* RPCSEC_GSS control procedures */ + + + enum rpc_gss_proc_t { + RPCSEC_GSS_DATA = 0, + RPCSEC_GSS_INIT = 1, + RPCSEC_GSS_CONTINUE_INIT = 2, + RPCSEC_GSS_DESTROY = 3 + }; + + /* RPCSEC_GSS services */ + + enum rpc_gss_service_t { + /* Note: the enumerated value for 0 is reserved. */ + rpc_gss_svc_none = 1, + rpc_gss_svc_integrity = 2, + rpc_gss_svc_privacy = 3 + }; + + /* Credential */ + + /* + * Note: version 0 is reserved for possible future + * definition of a version negotiation protocol + * + */ + #define RPCSEC_GSS_VERS_1 1 + + struct rpc_gss_cred_t { + union switch (unsigned int version) { /* version of + RPCSEC_GSS */ + case RPCSEC_GSS_VERS_1: + struct { + rpc_gss_proc_t gss_proc; /* control procedure */ + unsigned int seq_num; /* sequence number */ + rpc_gss_service_t service; /* service used */ + opaque handle<>; /* context handle */ + } rpc_gss_cred_vers_1_t; + + + +Eisler, et. al. Standards Track [Page 4] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + } + }; + + /* Maximum sequence number value */ + + #define MAXSEQ 0x80000000 + +5.1. Version Selection + + This document defines just one protocol version (RPCSEC_GSS_VERS_1). + The client should assume that the server supports RPCSEC_GSS_VERS_1 + and issue a Context Creation message (as described in the section + RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of + MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of + AUTH_REJECTED_CRED. + +5.2. Context Creation + + Before RPC data is exchanged on a session using the RPCSEC_GSS + flavor, a context must be set up between the client and the server. + Context creation may involve zero or more RPC exchanges. The number + of exchanges depends on the security mechanism. + +5.2.1. Mechanism and QOP Selection + + There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API + mechanism identifiers or QOP values. At minimum, it is expected that + implementations of the RPCSEC_GSS protocol provide a means to: + + * specify mechanism identifiers, QOP values, and RPCSEC_GSS + service values on the client side, and to + + * enforce mechanism identifiers, QOP values, and RPCSEC_GSS + service values on a per-request basis on the server side. + + It is necessary that above capabilities exist so that applications + have the means to conform the required set of required set of + <mechanism, QOP, service> tuples (See the section entitled Set of + GSS-API Mechanisms). An application may negotiate <mechanism, QOP, + service> selection within its protocol or via an out of band + protocol. Hence it may be necessary for RPCSEC_GSS implementations to + provide programming interfaces for the specification and enforcement + of <mechanism, QOP, service>. + + Additionally, implementations may depend on negotiation schemes + constructed as pseudo-mechanisms under the GSS-API. Because such + schemes are below the GSS-API layer, the RPCSEC_GSS protocol, as + specified in this document, can make use of them. + + + +Eisler, et. al. Standards Track [Page 5] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.2. Context Creation Requests + + The first RPC request from the client to the server initiates context + creation. Within the RPC message protocol's call_body structure, + rpcvers is set to 2. prog and vers are always those for the service + being accessed. The proc is always set to NULLPROC (zero). + + Within the RPC message protocol's cred structure, flavor is set to + RPCSEC_GSS (6). The opaque data of the cred structure (the body + field) constituting the credential encodes the rpc_gss_cred_t + structure defined previously. + + The values of the fields contained in the rpc_gss_cred_t structure + are set as follows. The version field is set to the version of the + RPCSEC_GSS protocol the client wants to use. The remainder of this + memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the + version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field + must be set to RPCSEC_GSS_INIT for the first creation request. In + subsequent creation requests, the gss_proc field must be set to + RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and + service fields are undefined and both must be ignored by the server. + In the first creation request, the handle field is NULL (opaque data + of zero length). In subsequent creation requests, handle must be + equal to the value returned by the server. The handle field serves + as the identifier for the context, and will not change for the + duration of the context, including responses to + RPCSEC_GSS_CONTINUE_INIT. + + The verifier field in the RPC message header is also described by the + opaque_auth structure. All creation requests have the NULL verifier + (AUTH_NONE flavor with zero length opaque data). + + Following the verifier are the call data (procedure specific + parameters). Note that the proc field of the call_body structure is + set to NULLPROC, and thus normally there would be zero octets + following the verifier. However, since there is no RPC data exchange + during a context creation, it is safe to transfer information + following the verifier. It is necessary to "overload" the call data + in this way, rather than pack the GSS-API token into the RPC header, + because RPC Version 2 restricts the amount of data that can be sent + in the header. The opaque body of the credential and verifier fields + can be each at most 400 octets long, and GSS tokens can be longer + than 800 octets. + + + + + + + + +Eisler, et. al. Standards Track [Page 6] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The call data for a context creation request is described by the + following structure for all creation requests: + + struct rpc_gss_init_arg { + opaque gss_token<>; + }; + + Here, gss_token is the token returned by the call to GSS-API's + GSS_Init_sec_context() routine, opaquely encoded. The value of this + field will likely be different in each creation request, if there is + more than one creation request. If no token is returned by the call + to GSS_Init_sec_context(), the context must have been created + (assuming no errors), and there will not be any more creation + requests. + + When GSS_Init_sec_context() is called, the parameters + replay_det_req_flag and sequence_req_flag must be turned off. The + reasons for this are: + + * ONC RPC can be used over unreliable transports and provides no + layer to reliably re-assemble messages. Thus it is possible for + gaps in message sequencing to occur, as well as out of order + messages. + + * RPC servers can be multi-threaded, and thus the order in which + GSS-API messages are signed or wrapped can be different from the + order in which the messages are verified or unwrapped, even if + the requests are sent on reliable transports. + + * To maximize convenience of implementation, the order in which an + ONC RPC entity will verify the header and verify/unwrap the body + of an RPC call or reply is left unspecified. + + The RPCSEC_GSS protocol provides for protection from replay attack, + yet tolerates out-of-order delivery or processing of messages and + tolerates dropped requests. + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 7] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.2.3. Context Creation Responses + +5.2.3.1. Context Creation Response - Successful Acceptance + + The response to a successful creation request has an MSG_ACCEPTED + response with a status of SUCCESS. The results field encodes a + response with the following structure: + + struct rpc_gss_init_res { + opaque handle<>; + unsigned int gss_major; + unsigned int gss_minor; + unsigned int seq_window; + opaque gss_token<>; + }; + + Here, handle is non-NULL opaque data that serves as the context + identifier. The client must use this value in all subsequent requests + whether control messages or otherwise). The gss_major and gss_minor + fields contain the results of the call to GSS_Accept_sec_context() + executed by the server. The values for the gss_major field are + defined in Appendix A of this document. The values for the gss_minor + field are GSS-API mechanism specific and are defined in the + mechanism's specification. If gss_major is not one of GSS_S_COMPLETE + or GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case + handle and gss_token must be set to NULL by the server. The value of + gss_minor is dependent on the value of gss_major and the security + mechanism used. The gss_token field contains any token returned by + the GSS_Accept_sec_context() call executed by the server. A token + may be returned for both successful values of gss_major. If the + value is GSS_S_COMPLETE, it indicates that the server is not + expecting any more tokens, and the RPC Data Exchange phase must begin + on the subsequent request from the client. If the value is + GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence + the client must send at least one more creation request (with + gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) + carrying the required token. + + In a successful response, the seq_window field is set to the sequence + window length supported by the server for this context. This window + specifies the maximum number of client requests that may be + outstanding for this context. The server will accept "seq_window" + requests at a time, and these may be out of order. The client may + use this number to determine the number of threads that can + simultaneously send requests on this context. + + + + + + +Eisler, et. al. Standards Track [Page 8] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in + the response) flavor field is set to RPCSEC_GSS, and the body field + set to the checksum of the seq_window (in network order). The QOP + used for this checksum is 0 (zero), which is the default QOP. For + all other values of gss_major, a NULL verifier (AUTH_NONE flavor with + zero-length opaque data) is used. + +5.2.3.1.1. Client Processing of Successful Context Creation Responses + + If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, + then the client, per the GSS-API specification, must invoke + GSS_Init_sec_context() using the token returned in gss_token in the + context creation response. The client must then generate a context + creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. + + If the value of gss_major in the response is GSS_S_COMPLETE, and if + the client's previous invocation of GSS_Init_sec_context() returned a + gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the + GSS-API specification, must invoke GSS_Init_sec_context() using the + token returned in gss_token in the context creation response. If + GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is + successfully set up, and the RPC data exchange phase must begin on + the subsequent request from the client. + +5.2.3.2. Context Creation Response - Unsuccessful Cases + + An MSG_ACCEPTED reply (to a creation request) with an acceptance + status of other than SUCCESS has a NULL verifier (flavor set to + AUTH_NONE, and zero length opaque data in the body field), and is + formulated as usual for different status values. + + An MSG_DENIED reply (to a creation request) is also formulated as + usual. Note that MSG_DENIED could be returned because the server's + RPC implementation does not recognize the RPCSEC_GSS security flavor. + RFC 1831 does not specify the appropriate reply status in this + instance, but common implementation practice appears to be to return + a rejection status of AUTH_ERROR with an auth_stat of + AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_CREDPROBLEM + and RPCSEC_GSS_CTXPROBLEM) have been defined for the auth_stat type, + neither of these two can be returned in responses to context creation + requests. The auth_stat new values can be used for responses to + normal (data) requests. This is described later. + + MSG_DENIED might also be returned if the RPCSEC_GSS version number in + the credential is not supported on the server. In that case, the + server returns a rejection status of AUTH_ERROR, with an auth_stat of + + AUTH_REJECTED_CRED. + + + +Eisler, et. al. Standards Track [Page 9] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3. RPC Data Exchange + + The data exchange phase is entered after a context has been + successfully set up. The format of the data exchanged depends on the + security service used for the request. Although clients can change + the security service and QOP used on a per-request basis, this may + not be acceptable to all RPC services; some RPC services may "lock" + the data exchange phase into using the QOP and service used on the + first data exchange message. For all three modes of service (no data + integrity, data integrity, data privacy), the RPC request header has + the same format. + +5.3.1. RPC Request Header + + The credential has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The credential body is created by + XDR encoding the rpc_gss_cred_t structure listed earlier into an + octet stream, and then opaquely encoding this octet stream as the + body field. + + Values of the fields contained in the rpc_gss_cred_t structure are + set as follows. The version field is set to same version value that + was used to create the context, which within the scope of this memo + will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to + RPCSEC_GSS_DATA. The service field is set to indicate the desired + service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or + rpc_gss_svc_privacy). The handle field is set to the context handle + value received from the RPC server during context creation. The + seq_num field can start at any value below MAXSEQ, and must be + incremented (by one or more) for successive requests. Use of + sequence numbers is described in detail when server processing of the + request is discussed. + + The verifier has the opaque_auth structure described earlier. The + flavor field is set to RPCSEC_GSS. The body field is set as follows. + The checksum of the RPC header (up to and including the credential) + is computed using the GSS_GetMIC() call with the desired QOP. This + returns the checksum as an opaque octet stream and its length. This + is encoded into the body field. Note that the QOP is not explicitly + specified anywhere in the request. It is implicit in the checksum or + encrypted data. The same QOP value as is used for the header + checksum must also be used for the data (for checksumming or + encrypting), unless the service used for the request is + rpc_gss_svc_none. + + + + + + + +Eisler, et. al. Standards Track [Page 10] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.2. RPC Request Data + +5.3.2.1. RPC Request Data - No Data Integrity + + If the service specified is rpc_gss_svc_none, the data (procedure + arguments) are not integrity or privacy protected. They are sent in + exactly the same way as they would be if the AUTH_NONE flavor were + used (following the verifier). Note, however, that since the RPC + header is integrity protected, the sender will still be authenticated + in this case. + +5.3.2.2. RPC Request Data - With Data Integrity + + When data integrity is used, the request data is represented as + follows: + + struct rpc_gss_integ_data { + opaque databody_integ<>; + opaque checksum<>; + }; + + The databody_integ field is created as follows. A structure + consisting of a sequence number followed by the procedure arguments + is constructed. This is shown below as the type rpc_gss_data_t: + + struct rpc_gss_data_t { + unsigned int seq_num; + proc_req_arg_t arg; + }; + + Here, seq_num must have the same value as in the credential. The + type proc_req_arg_t is the procedure specific XDR type describing the + procedure arguments (and so is not specified here). The octet stream + corresponding to the XDR encoded rpc_gss_data_t structure and its + length are placed in the databody_integ field. Note that because the + XDR type of databody_integ is opaque, the XDR encoding of + databody_integ will include an initial four octet length field, + followed by the XDR encoded octet stream of rpc_gss_data_t. + + The checksum field represents the checksum of the XDR encoded octet + stream corresponding to the XDR encoded rpc_gss_data_t structure + (note, this is not the checksum of the databody_integ field). This + is obtained using the GSS_GetMIC() call, with the same QOP as was + used to compute the header checksum (in the verifier). The + + + + + + + +Eisler, et. al. Standards Track [Page 11] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + GSS_GetMIC() call returns the checksum as an opaque octet stream and + its length. The checksum field of struct rpc_gss_integ_data has an + XDR type of opaque. Thus the checksum length from GSS_GetMIC() is + encoded as a four octet length field, followed by the checksum, + padded to a multiple of four octets. + +5.3.2.3. RPC Request Data - With Data Privacy + + When data privacy is used, the request data is represented as + follows: + + struct rpc_gss_priv_data { + opaque databody_priv<> + }; + + The databody_priv field is created as follows. The rpc_gss_data_t + structure described earlier is constructed again in the same way as + for the case of data integrity. Next, the GSS_Wrap() call is invoked + to encrypt the octet stream corresponding to the rpc_gss_data_t + structure, using the same value for QOP (argument qop_req to + GSS_Wrap()) as was used for the header checksum (in the verifier) and + conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() + call returns an opaque octet stream (representing the encrypted + rpc_gss_data_t structure) and its length, and this is encoded as the + databody_priv field. Since databody_priv has an XDR type of opaque, + the length returned by GSS_Wrap() is encoded as the four octet + length, followed by the encrypted octet stream (padded to a multiple + of four octets). + +5.3.3. Server Processing of RPC Data Requests + +5.3.3.1. Context Management + + When a request is received by the server, the following are verified + to be acceptable: + + * the version number in the credential + + * the service specified in the credential + + * the context handle specified in the credential + + * the header checksum in the verifier (via GSS_VerifyMIC()) + + * the sequence number (seq_num) specified in the credential (more + on this follows) + + + + + +Eisler, et. al. Standards Track [Page 12] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The gss_proc field in the credential must be set to RPCSEC_GSS_DATA + for data requests (otherwise, the message will be interpreted as a + control message). + + The server maintains a window of "seq_window" sequence numbers, + starting with the last sequence number seen and extending backwards. + If a sequence number higher than the last number seen is received + (AND if GSS_VerifyMIC() on the header checksum from the verifier + returns GSS_S_COMPLETE), the window is moved forward to the new + sequence number. If the last sequence number seen is N, the server + is prepared to receive requests with sequence numbers in the range N + through (N - seq_window + 1), both inclusive. If the sequence number + received falls below this range, it is silently discarded. If the + sequence number is within this range, and the server has not seen it, + the request is accepted, and the server turns on a bit to "remember" + that this sequence number has been seen. If the server determines + that it has already seen a sequence number within the window, the + request is silently discarded. The server should select a seq_window + value based on the number requests it expects to process + simultaneously. For example, in a threaded implementation seq_window + might be equal to the number of server threads. There are no known + security issues with selecting a large window. The primary issue is + how much space the server is willing to allocate to keep track of + requests received within the window. + + The reason for discarding requests silently is that the server is + unable to determine if the duplicate or out of range request was due + to a sequencing problem in the client, network, or the operating + system, or due to some quirk in routing, or a replay attack by an + intruder. Discarding the request allows the client to recover after + timing out, if indeed the duplication was unintentional or well + intended. Note that a consequence of the silent discard is that + clients may increment the seq_num by more than one. The effect of + this is that the window will move forward more quickly. It is not + believed that there is any benefit to doing this. + + Note that the sequence number algorithm requires that the client + increment the sequence number even if it is retrying a request with + the same RPC transaction identifier. It is not infrequent for + clients to get into a situation where they send two or more attempts + and a slow server sends the reply for the first attempt. With + RPCSEC_GSS, each request and reply will have a unique sequence + number. If the client wishes to improve turn around time on the RPC + call, it can cache the RPCSEC_GSS sequence number of each request it + sends. Then when it receives a response with a matching RPC + transaction identifier, it can compute the checksum of each sequence + number in the cache to try to match the checksum in the reply's + verifier. + + + +Eisler, et. al. Standards Track [Page 13] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + The data is decoded according to the service specified in the + credential. In the case of integrity or privacy, the server ensures + that the QOP value is acceptable, and that it is the same as that + used for the header checksum in the verifier. Also, in the case of + integrity or privacy, the server will reject the message (with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS) if the sequence number embedded in the request body is + different from the sequence number in the credential. + +5.3.3.2. Server Reply - Request Accepted + + An MSG_ACCEPTED reply to a request in the data exchange phase will + have the verifier's (the verf element in the response) flavor field + set to RPCSEC_GSS, and the body field set to the checksum (the output + of GSS_GetMIC()) of the sequence number (in network order) of the + corresponding request. The QOP used is the same as the QOP used for + the corresponding request. + + If the status of the reply is not SUCCESS, the rest of the message is + formatted as usual. + + If the status of the message is SUCCESS, the format of the rest of + the message depends on the service specified in the corresponding + request message. Basically, what follows the verifier in this case + are the procedure results, formatted in different ways depending on + the requested service. + + If no data integrity was requested, the procedure results are + formatted as for the AUTH_NONE security flavor. + + If data integrity was requested, the results are encoded in exactly + the same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Integrity.' + The only difference is that the structure representing the + procedure's result - proc_res_arg_t - must be substituted in place of + the request argument structure proc_req_arg_t. The QOP used for the + checksum must be the same as that used for constructing the reply + verifier. + + If data privacy was requested, the results are encoded in exactly the + same way as the procedure arguments were in the corresponding + request. See the section 'RPC Request Data - With Data Privacy.' The + QOP used for encryption must be the same as that used for + constructing the reply verifier. + + + + + + + +Eisler, et. al. Standards Track [Page 14] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +5.3.3.3. Server Reply - Request Denied + + An MSG_DENIED reply (to a data request) is formulated as usual. Two + new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have + been defined for the auth_stat type. When the reason for denial of + the request is a reject_stat of AUTH_ERROR, one of the two new + auth_stat values could be returned in addition to the existing + values. These two new values have special significance from the + existing reasons for denial of a request. + + The server maintains a list of contexts for the clients that are + currently in session with it. Normally, a context is destroyed when + the client ends the session corresponding to it. However, due to + resource constraints, the server may destroy a context prematurely + (on an LRU basis, or if the server machine is rebooted, for example). + In this case, when a client request comes in, there may not be a + context corresponding to its handle. The server rejects the request, + with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving + this error, the client must refresh the context - that is, + reestablish it after destroying the old one - and try the request + again. This error is also returned if the context handle matches + that of a different context that was allocated after the client's + context was destroyed (this will be detected by a failure in + verifying the header checksum). + + If the GSS_VerifyMIC() call on the header checksum (contained in the + verifier) fails to return GSS_S_COMPLETE, the server rejects the + request and returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. + + When the client's sequence number exceeds the maximum the server will + allow, the server will reject the request with the reason + RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale + while in use (due to ticket expiry in the case of the Kerberos V5 + mechanism, for example), the failures which result cause the + RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, + the client must refresh the context, and retry the request. + + For other errors, retrying will not rectify the problem and the + client must not refresh the context until the problem causing the + client request to be denied is rectified. + + If the version field in the credential does not match the version of + RPCSEC_GSS that was used when the context was created, the + AUTH_BADCRED value is returned. + + If there is a problem with the credential, such a bad length, illegal + control procedure, or an illegal service, the appropriate auth_stat + status is AUTH_BADCRED. + + + +Eisler, et. al. Standards Track [Page 15] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Other errors can be returned as appropriate. + +5.3.3.4. Mapping of GSS-API Errors to Server Responses + + During the data exchange phase, the server may invoke GSS_GetMIC(), + GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these + routines fail to return GSS_S_COMPLETE, then various unsuccessful + responses can be returned. The are described as follows for each of + the aforementioned four interfaces. + +5.3.3.4.1. GSS_GetMIC() Failure + + When GSS_GetMIC() is called to generate the verifier in the response, + a failure results in an RPC response with a reply status of + MSG_DENIED, reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CTXPROBLEM. + + When GSS_GetMIC() is called to sign the call results (service is + rpc_gss_svc_integrity), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + response is sent, the failure indication will be returned to the + server application and it can take appropriate action (such as + logging the error). + +5.3.3.4.2. GSS_VerifyMIC() Failure + + When GSS_VerifyMIC() is called to verify the verifier in request, a + failure results in an RPC response with a reply status of MSG_DENIED, + reject status of AUTH_ERROR and an auth status of + RPCSEC_GSS_CREDPROBLEM. + + When GSS_VerifyMIC() is called to verify the call arguments (service + is rpc_gss_svc_integrity), a failure results in an RPC response with + a reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.3. GSS_Unwrap() Failure + + When GSS_Unwrap() is called to decrypt the call arguments (service is + rpc_gss_svc_privacy), a failure results in an RPC response with a + reply status of MSG_ACCEPTED, and an acceptance status of + GARBAGE_ARGS. + +5.3.3.4.4. GSS_Wrap() Failure + + When GSS_Wrap() is called to encrypt the call results (service is + rpc_gss_svc_privacy), a failure results in no RPC response being + sent. Since ONC RPC server applications will typically control when a + + + +Eisler, et. al. Standards Track [Page 16] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + response is sent, the failure indication will be returned to the + application and it can take appropriate action (such as logging the + error). + +5.4. Context Destruction + + When the client is done using the session, it must send a control + message informing the server that it no longer requires the context. + This message is formulated just like a data request packet, with the + following differences: the credential has gss_proc set to + RPCSEC_GSS_DESTROY, the procedure specified in the header is + NULLPROC, and there are no procedure arguments. The sequence number + in the request must be valid, and the header checksum in the verifier + must be valid, for the server to accept the message. The server + sends a response as it would to a data request. The client and + server must then destroy the context for the session. + + If the request to destroy the context fails for some reason, the + client need not take any special action. The server must be prepared + to deal with situations where clients never inform the server that + they no longer are in session and so don't need the server to + maintain a context. An LRU mechanism or an aging mechanism should be + employed by the server to clean up in such cases. + +6. Set of GSS-API Mechanisms + + RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and + as such it is inappropriate for the RPCSEC_GSS specification to + enumerate a minimum set of required security mechanisms and/or + quality of protections. + + If an application protocol specification references RPCSEC_GSS, the + protocol specification must list a mandatory set of { mechanism, QOP, + service } triples, such that an implementation cannot claim + conformance to the protocol specification unless it implements the + set of triples. Within each triple, mechanism is a GSS-API security + mechanism, QOP is a valid quality-of-protection within the mechanism, + and service is either rpc_gss_svc_integrity or rpc_gss_svc_privacy. + + For example, a network filing protocol built on RPC that depends on + RPCSEC_GSS for security, might require that Kerberos V5 with the + default QOP using the rpc_gss_svc_integrity service be supported by + implementations conforming to the network filing protocol + specification. + + + + + + + +Eisler, et. al. Standards Track [Page 17] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +7. Security Considerations + +7.1. Privacy of Call Header + + The reader will note that for the privacy option, only the call + arguments and results are encrypted. Information about the + application in the form of RPC program number, program version + number, and program procedure number is transmitted in the clear. + Encrypting these fields in the RPC call header would have changed the + size and format of the call header. This would have required revising + the RPC protocol which was beyond the scope of this proposal. Storing + the encrypted numbers in the credential would have obviated a + protocol change, but would have introduced more overloading of fields + and would have made implementations of RPC more complex. Even if the + fields were encrypted somehow, in most cases an attacker can + determine the program number and version number by examining the + destination address of the request and querying the rpcbind service + on the destination host [Srinivasan-bind]. In any case, even by not + encrypting the three numbers, RPCSEC_GSS still improves the state of + security over what existing RPC services have had available + previously. Implementors of new RPC services that are concerned about + this risk may opt to design in a "sub-procedure" field that is + included in the service specific call arguments. + +7.2. Sequence Number Attacks + +7.2.1. Sequence Numbers Above the Window + + An attacker cannot coax the server into raising the sequence number + beyond the range the legitimate client is aware of (and thus engineer + a denial of server attack) without constructing an RPC request that + will pass the header checksum. If the cost of verifying the header + checksum is sufficiently large (depending on the speed of the + processor doing the checksum and the cost of checksum algorithm), it + is possible to envision a denial of service attack (vandalism, in the + form of wasting processing resources) whereby the attacker sends + requests that are above the window. The simplest method might be for + the attacker to monitor the network traffic and then choose a + sequence number that is far above the current sequence number. Then + the attacker can send bogus requests using the above window sequence + number. + +7.2.2. Sequence Numbers Within or Below the Window + + If the attacker sends requests that are within or below the window, + then even if the header checksum is successfully verified, the server + will silently discard the requests because the server assumes it has + already processed the request. In this case, a server can optimize by + + + +Eisler, et. al. Standards Track [Page 18] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + skipping the header checksum verification if the sequence number is + below the window, or if it is within the window, not attempt the + checksum verification if the sequence number has already been seen. + +7.3. Message Stealing Attacks + + This proposal does not address attacks where an attacker can block or + steal messages without being detected by the server. To implement + such protection would be tantamount to assuming a state in the RPC + service. RPCSEC_GSS does not worsen this situation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 19] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Appendix A. GSS-API Major Status Codes + + The GSS-API definition [Linn] does not include numerical values for + the various GSS-API major status codes. It is expected that this will + be addressed in future RFC. Until then, this appendix defines the + values for each GSS-API major status code listed in the GSS-API + definition. If in the future, the GSS-API definition defines values + for the codes that are different than what follows, then implementors + of RPCSEC_GSS will be obliged to map them into the values defined + below. If in the future, the GSS-API definition defines additional + status codes not defined below, then the RPCSEC_GSS definition will + subsume those additional values. + + Here are the definitions of each GSS_S_* major status that the + implementor of RPCSEC_GSS can expect in the gss_major major field of + rpc_gss_init_res. These definitions are not in RPC description + language form. The numbers are in base 16 (hexadecimal): + + GSS_S_COMPLETE 0x00000000 + GSS_S_CONTINUE_NEEDED 0x00000001 + GSS_S_DUPLICATE_TOKEN 0x00000002 + GSS_S_OLD_TOKEN 0x00000004 + GSS_S_UNSEQ_TOKEN 0x00000008 + GSS_S_GAP_TOKEN 0x00000010 + GSS_S_BAD_MECH 0x00010000 + GSS_S_BAD_NAME 0x00020000 + GSS_S_BAD_NAMETYPE 0x00030000 + GSS_S_BAD_BINDINGS 0x00040000 + GSS_S_BAD_STATUS 0x00050000 + GSS_S_BAD_MIC 0x00060000 + GSS_S_BAD_SIG 0x00060000 + GSS_S_NO_CRED 0x00070000 + GSS_S_NO_CONTEXT 0x00080000 + GSS_S_DEFECTIVE_TOKEN 0x00090000 + GSS_S_DEFECTIVE_CREDENTIAL 0x000a0000 + GSS_S_CREDENTIALS_EXPIRED 0x000b0000 + GSS_S_CONTEXT_EXPIRED 0x000c0000 + GSS_S_FAILURE 0x000d0000 + GSS_S_BAD_QOP 0x000e0000 + GSS_S_UNAUTHORIZED 0x000f0000 + GSS_S_UNAVAILABLE 0x00100000 + GSS_S_DUPLICATE_ELEMENT 0x00110000 + GSS_S_NAME_NOT_MN 0x00120000 + GSS_S_CALL_INACCESSIBLE_READ 0x01000000 + GSS_S_CALL_INACCESSIBLE_WRITE 0x02000000 + GSS_S_CALL_BAD_STRUCTURE 0x03000000 + + + + + +Eisler, et. al. Standards Track [Page 20] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + + Note that the GSS-API major status is split into three fields as + follows: + + Most Significant Bit Least Significant Bit + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Up to one status in the Calling Error field can be logically ORed + with up to one status in the Routine Error field which in turn can be + logically ORed with zero or more statuses in the Supplementary Info + field. If the resulting major status has a non-zero Calling Error + and/or a non-zero Routine Error, then the applicable GSS-API + operation has failed. For purposes of RPCSEC_GSS, this means that + the GSS_Accept_sec_context() call executed by the server has failed. + + If the major status is equal GSS_S_COMPLETE, then this indicates the + absence of any Errors or Supplementary Info. + + The meanings of most of the GSS_S_* status are defined in the GSS-API + definition, which the exceptions of: + + GSS_S_BAD_MIC This code has the same meaning as GSS_S_BAD_SIG. + + GSS_S_CALL_INACCESSIBLE_READ + A required input parameter could not be read. + + GSS_S_CALL_INACCESSIBLE_WRITE + A required input parameter could not be written. + + GSS_S_CALL_BAD_STRUCTURE + A parameter was malformed. + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 21] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Acknowledgements + + Much of the protocol was based on the AUTH_GSSAPI security flavor + developed by Open Vision Technologies [Jaspan]. In particular, we + acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen + McDermott. + + Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike + Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to + Sun Microsystems' implementation of RPCSEC_GSS. + + Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie + Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the + specification and gave valuable feedback. + + Steve Nahm and Kathy Slattery reviewed various drafts of this + specification. + + Much of content of Appendix A was excerpted from John Wray's Work in + Progress on GSS-API Version 2 C-bindings. + +References + + [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. + (1996). "Security Mechanism Independence in ONC + RPC," Proceedings of the Sixth Annual USENIX + Security Symposium, pp. 51-65. + + [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC + RPC," `95 Proceedings of The Internet Society + Symposium on Network and Distributed System + Security, pp. 144- 151. + + [Linn] Linn, J., "Generic Security Service Application + Program Interface, Version 2", RFC 2078, January + 1997. + + [Srinivasan-bind] Srinivasan, R., "Binding Protocols for + ONC RPC Version 2", RFC 1833, August 1995. + + [Srinivasan-rpc] Srinivasan, R., "RPC: Remote Procedure Call + Protocol Specification Version 2", RFC 1831, + August 1995. + + [Srinivasan-xdr] Srinivasan, R., "XDR: External Data + Representation Standard", RFC 1832, August 1995. + + + + + +Eisler, et. al. Standards Track [Page 22] + +RFC 2203 RPCSEC_GSS Protocol Specification September 1997 + + +Authors' Addresses + + Michael Eisler + Sun Microsystems, Inc. + M/S UCOS03 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (719) 599-9026 + EMail: mre@eng.sun.com + + + Alex Chiu + Sun Microsystems, Inc. + M/S UMPK17-203 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-6465 + EMail: hacker@eng.sun.com + + + Lin Ling + Sun Microsystems, Inc. + M/S UMPK17-201 + 2550 Garcia Avenue + Mountain View, CA 94043 + + Phone: +1 (415) 786-5084 + EMail: lling@eng.sun.com + + + + + + + + + + + + + + + + + + + + + +Eisler, et. al. Standards Track [Page 23] + diff --git a/crypto/heimdal/doc/standardisation/rfc2228.txt b/crypto/heimdal/doc/standardisation/rfc2228.txt new file mode 100644 index 0000000..1fbfcbf --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc2228.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group M. Horowitz +Request for Comments: 2228 Cygnus Solutions +Updates: 959 S. Lunt +Category: Standards Track Bellcore + October 1997 + + FTP Security Extensions + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +Abstract + + This document defines extensions to the FTP specification STD 9, RFC + 959, "FILE TRANSFER PROTOCOL (FTP)" (October 1985). These extensions + provide strong authentication, integrity, and confidentiality on both + the control and data channels with the introduction of new optional + commands, replies, and file transfer encodings. + + The following new optional commands are introduced in this + specification: + + AUTH (Authentication/Security Mechanism), + ADAT (Authentication/Security Data), + PROT (Data Channel Protection Level), + PBSZ (Protection Buffer Size), + CCC (Clear Command Channel), + MIC (Integrity Protected Command), + CONF (Confidentiality Protected Command), and + ENC (Privacy Protected Command). + + A new class of reply types (6yz) is also introduced for protected + replies. + + None of the above commands are required to be implemented, but + interdependencies exist. These dependencies are documented with the + commands. + + Note that this specification is compatible with STD 9, RFC 959. + + + +Horowitz & Lunt Standards Track [Page 1] + +RFC 2228 FTP Security Extensions October 1997 + + +1. Introduction + + The File Transfer Protocol (FTP) currently defined in STD 9, RFC 959 + and in place on the Internet uses usernames and passwords passed in + cleartext to authenticate clients to servers (via the USER and PASS + commands). Except for services such as "anonymous" FTP archives, + this represents a security risk whereby passwords can be stolen + through monitoring of local and wide-area networks. This either aids + potential attackers through password exposure and/or limits + accessibility of files by FTP servers who cannot or will not accept + the inherent security risks. + + Aside from the problem of authenticating users in a secure manner, + there is also the problem of authenticating servers, protecting + sensitive data and/or verifying its integrity. An attacker may be + able to access valuable or sensitive data merely by monitoring a + network, or through active means may be able to delete or modify the + data being transferred so as to corrupt its integrity. An active + attacker may also initiate spurious file transfers to and from a site + of the attacker's choice, and may invoke other commands on the + server. FTP does not currently have any provision for the encryption + or verification of the authenticity of commands, replies, or + transferred data. Note that these security services have value even + to anonymous file access. + + Current practice for sending files securely is generally either: + + 1. via FTP of files pre-encrypted under keys which are manually + distributed, + + 2. via electronic mail containing an encoding of a file encrypted + under keys which are manually distributed, + + 3. via a PEM message, or + + 4. via the rcp command enhanced to use Kerberos. + + None of these means could be considered even a de facto standard, and + none are truly interactive. A need exists to securely transfer files + using FTP in a secure manner which is supported within the FTP + protocol in a consistent manner and which takes advantage of existing + security infrastructure and technology. Extensions are necessary to + the FTP specification if these security services are to be introduced + into the protocol in an interoperable way. + + + + + + + +Horowitz & Lunt Standards Track [Page 2] + +RFC 2228 FTP Security Extensions October 1997 + + + Although the FTP control connection follows the Telnet protocol, and + Telnet has defined an authentication and encryption option [TELNET- + SEC], [RFC-1123] explicitly forbids the use of Telnet option + negotiation over the control connection (other than Synch and IP). + + Also, the Telnet authentication and encryption option does not + provide for integrity protection only (without confidentiality), and + does not address the protection of the data channel. + +2. FTP Security Overview + + At the highest level, the FTP security extensions seek to provide an + abstract mechanism for authenticating and/or authorizing connections, + and integrity and/or confidentiality protecting commands, replies, + and data transfers. + + In the context of FTP security, authentication is the establishment + of a client's identity and/or a server's identity in a secure way, + usually using cryptographic techniques. The basic FTP protocol does + not have a concept of authentication. + + Authorization is the process of validating a user for login. The + basic authorization process involves the USER, PASS, and ACCT + commands. With the FTP security extensions, authentication + established using a security mechanism may also be used to make the + authorization decision. + + Without the security extensions, authentication of the client, as + this term is usually understood, never happens. FTP authorization is + accomplished with a password, passed on the network in the clear as + the argument to the PASS command. The possessor of this password is + assumed to be authorized to transfer files as the user named in the + USER command, but the identity of the client is never securely + established. + + An FTP security interaction begins with a client telling the server + what security mechanism it wants to use with the AUTH command. The + server will either accept this mechanism, reject this mechanism, or, + in the case of a server which does not implement the security + extensions, reject the command completely. The client may try + multiple security mechanisms until it requests one which the server + accepts. This allows a rudimentary form of negotiation to take + place. (If more complex negotiation is desired, this may be + implemented as a security mechanism.) The server's reply will + indicate if the client must respond with additional data for the + + + + + + +Horowitz & Lunt Standards Track [Page 3] + +RFC 2228 FTP Security Extensions October 1997 + + + security mechanism to interpret. If none is needed, this will + usually mean that the mechanism is one where the password (specified + by the PASS command) is to be interpreted differently, such as with a + token or one-time password system. + + If the server requires additional security information, then the + client and server will enter into a security data exchange. The + client will send an ADAT command containing the first block of + security data. The server's reply will indicate if the data exchange + is complete, if there was an error, or if more data is needed. The + server's reply can optionally contain security data for the client to + interpret. If more data is needed, the client will send another ADAT + command containing the next block of data, and await the server's + reply. This exchange can continue as many times as necessary. Once + this exchange completes, the client and server have established a + security association. This security association may include + authentication (client, server, or mutual) and keying information for + integrity and/or confidentiality, depending on the mechanism in use. + + The term "security data" here is carefully chosen. The purpose of + the security data exchange is to establish a security association, + which might not actually include any authentication at all, between + the client and the server as described above. For instance, a + Diffie-Hellman exchange establishes a secret key, but no + authentication takes place. If an FTP server has an RSA key pair but + the client does not, then the client can authenticate the server, but + the server cannot authenticate the client. + + Once a security association is established, authentication which is a + part of this association may be used instead of or in addition to the + standard username/password exchange for authorizing a user to connect + to the server. A username specified by the USER command is always + required to specify the identity to be used on the server. + + In order to prevent an attacker from inserting or deleting commands + on the control stream, if the security association supports + integrity, then the server and client must use integrity protection + on the control stream, unless it first transmits a CCC command to + turn off this requirement. Integrity protection is performed with + the MIC and ENC commands, and the 63z reply codes. The CCC command + and its reply must be transmitted with integrity protection. + Commands and replies may be transmitted without integrity (that is, + in the clear or with confidentiality only) only if no security + association is established, the negotiated security association does + not support integrity, or the CCC command has succeeded. + + + + + + +Horowitz & Lunt Standards Track [Page 4] + +RFC 2228 FTP Security Extensions October 1997 + + + Once the client and server have negotiated with the PBSZ command an + acceptable buffer size for encapsulating protected data over the data + channel, the security mechanism may also be used to protect data + channel transfers. + + Policy is not specified by this document. In particular, client and + server implementations may choose to implement restrictions on what + operations can be performed depending on the security association + which exists. For example, a server may require that a client + authorize via a security mechanism rather than using a password, + require that the client provide a one-time password from a token, + require at least integrity protection on the command channel, or + require that certain files only be transmitted encrypted. An + anonymous ftp client might refuse to do file transfers without + integrity protection in order to insure the validity of files + downloaded. + + No particular set of functionality is required, except as + dependencies described in the next section. This means that none of + authentication, integrity, or confidentiality are required of an + implementation, although a mechanism which does none of these is not + of much use. For example, it is acceptable for a mechanism to + implement only integrity protection, one-way authentication and/or + encryption, encryption without any authentication or integrity + protection, or any other subset of functionality if policy or + technical considerations make this desirable. Of course, one peer + might require as a matter of policy stronger protection than the + other is able to provide, preventing perfect interoperability. + +3. New FTP Commands + + The following commands are optional, but dependent on each other. + They are extensions to the FTP Access Control Commands. + + The reply codes documented here are generally described as + recommended, rather than required. The intent is that reply codes + describing the full range of success and failure modes exist, but + that servers be allowed to limit information presented to the client. + For example, a server might implement a particular security + mechanism, but have a policy restriction against using it. The + server should respond with a 534 reply code in this case, but may + respond with a 504 reply code if it does not wish to divulge that the + disallowed mechanism is supported. If the server does choose to use + a different reply code than the recommended one, it should try to use + a reply code which only differs in the last digit. In all cases, the + server must use a reply code which is documented as returnable from + the command received, and this reply code must begin with the same + digit as the recommended reply code for the situation. + + + +Horowitz & Lunt Standards Track [Page 5] + +RFC 2228 FTP Security Extensions October 1997 + + + AUTHENTICATION/SECURITY MECHANISM (AUTH) + + The argument field is a Telnet string identifying a supported + mechanism. This string is case-insensitive. Values must be + registered with the IANA, except that values beginning with "X-" + are reserved for local use. + + If the server does not recognize the AUTH command, it must respond + with reply code 500. This is intended to encompass the large + deployed base of non-security-aware ftp servers, which will + respond with reply code 500 to any unrecognized command. If the + server does recognize the AUTH command but does not implement the + security extensions, it should respond with reply code 502. + + If the server does not understand the named security mechanism, it + should respond with reply code 504. + + If the server is not willing to accept the named security + mechanism, it should respond with reply code 534. + + If the server is not able to accept the named security mechanism, + such as if a required resource is unavailable, it should respond + with reply code 431. + + If the server is willing to accept the named security mechanism, + but requires security data, it must respond with reply code 334. + + If the server is willing to accept the named security mechanism, + and does not require any security data, it must respond with reply + code 234. + + If the server is responding with a 334 reply code, it may include + security data as described in the next section. + + Some servers will allow the AUTH command to be reissued in order + to establish new authentication. The AUTH command, if accepted, + removes any state associated with prior FTP Security commands. + The server must also require that the user reauthorize (that is, + reissue some or all of the USER, PASS, and ACCT commands) in this + case (see section 4 for an explanation of "authorize" in this + context). + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 6] + +RFC 2228 FTP Security Extensions October 1997 + + + AUTHENTICATION/SECURITY DATA (ADAT) + + The argument field is a Telnet string representing base 64 encoded + security data (see Section 9, "Base 64 Encoding"). If a reply + code indicating success is returned, the server may also use a + string of the form "ADAT=base64data" as the text part of the reply + if it wishes to convey security data back to the client. + + The data in both cases is specific to the security mechanism + specified by the previous AUTH command. The ADAT command, and the + associated replies, allow the client and server to conduct an + arbitrary security protocol. The security data exchange must + include enough information for both peers to be aware of which + optional features are available. For example, if the client does + not support data encryption, the server must be made aware of + this, so it will know not to send encrypted command channel + replies. It is strongly recommended that the security mechanism + provide sequencing on the command channel, to insure that commands + are not deleted, reordered, or replayed. + + The ADAT command must be preceded by a successful AUTH command, + and cannot be issued once a security data exchange completes + (successfully or unsuccessfully), unless it is preceded by an AUTH + command to reset the security state. + + If the server has not yet received an AUTH command, or if a prior + security data exchange completed, but the security state has not + been reset with an AUTH command, it should respond with reply code + 503. + + If the server cannot base 64 decode the argument, it should + respond with reply code 501. + + If the server rejects the security data (if a checksum fails, for + instance), it should respond with reply code 535. + + If the server accepts the security data, and requires additional + data, it should respond with reply code 335. + + If the server accepts the security data, but does not require any + additional data (i.e., the security data exchange has completed + successfully), it must respond with reply code 235. + + If the server is responding with a 235 or 335 reply code, then it + may include security data in the text part of the reply as + specified above. + + + + + +Horowitz & Lunt Standards Track [Page 7] + +RFC 2228 FTP Security Extensions October 1997 + + + If the ADAT command returns an error, the security data exchange + will fail, and the client must reset its internal security state. + If the client becomes unsynchronized with the server (for example, + the server sends a 234 reply code to an AUTH command, but the + client has more data to transmit), then the client must reset the + server's security state. + + PROTECTION BUFFER SIZE (PBSZ) + + The argument is a decimal integer representing the maximum size, + in bytes, of the encoded data blocks to be sent or received during + file transfer. This number shall be no greater than can be + represented in a 32-bit unsigned integer. + + This command allows the FTP client and server to negotiate a + maximum protected buffer size for the connection. There is no + default size; the client must issue a PBSZ command before it can + issue the first PROT command. + + The PBSZ command must be preceded by a successful security data + exchange. + + If the server cannot parse the argument, or if it will not fit in + 32 bits, it should respond with a 501 reply code. + + If the server has not completed a security data exchange with the + client, it should respond with a 503 reply code. + + Otherwise, the server must reply with a 200 reply code. If the + size provided by the client is too large for the server, it must + use a string of the form "PBSZ=number" in the text part of the + reply to indicate a smaller buffer size. The client and the + server must use the smaller of the two buffer sizes if both buffer + sizes are specified. + + DATA CHANNEL PROTECTION LEVEL (PROT) + + The argument is a single Telnet character code specifying the data + channel protection level. + + This command indicates to the server what type of data channel + protection the client and server will be using. The following + codes are assigned: + + C - Clear + S - Safe + E - Confidential + P - Private + + + +Horowitz & Lunt Standards Track [Page 8] + +RFC 2228 FTP Security Extensions October 1997 + + + The default protection level if no other level is specified is + Clear. The Clear protection level indicates that the data channel + will carry the raw data of the file transfer, with no security + applied. The Safe protection level indicates that the data will + be integrity protected. The Confidential protection level + indicates that the data will be confidentiality protected. The + Private protection level indicates that the data will be integrity + and confidentiality protected. + + It is reasonable for a security mechanism not to provide all data + channel protection levels. It is also reasonable for a mechanism + to provide more protection at a level than is required (for + instance, a mechanism might provide Confidential protection, but + include integrity-protection in that encoding, due to API or other + considerations). + + The PROT command must be preceded by a successful protection + buffer size negotiation. + + If the server does not understand the specified protection level, + it should respond with reply code 504. + + If the current security mechanism does not support the specified + protection level, the server should respond with reply code 536. + + If the server has not completed a protection buffer size + negotiation with the client, it should respond with a 503 reply + code. + + The PROT command will be rejected and the server should reply 503 + if no previous PBSZ command was issued. + + If the server is not willing to accept the specified protection + level, it should respond with reply code 534. + + If the server is not able to accept the specified protection + level, such as if a required resource is unavailable, it should + respond with reply code 431. + + Otherwise, the server must reply with a 200 reply code to indicate + that the specified protection level is accepted. + + CLEAR COMMAND CHANNEL (CCC) + + This command does not take an argument. + + + + + + +Horowitz & Lunt Standards Track [Page 9] + +RFC 2228 FTP Security Extensions October 1997 + + + It is desirable in some environments to use a security mechanism + to authenticate and/or authorize the client and server, but not to + perform any integrity checking on the subsequent commands. This + might be used in an environment where IP security is in place, + insuring that the hosts are authenticated and that TCP streams + cannot be tampered, but where user authentication is desired. + + If unprotected commands are allowed on any connection, then an + attacker could insert a command on the control stream, and the + server would have no way to know that it was invalid. In order to + prevent such attacks, once a security data exchange completes + successfully, if the security mechanism supports integrity, then + integrity (via the MIC or ENC command, and 631 or 632 reply) must + be used, until the CCC command is issued to enable non-integrity + protected control channel messages. The CCC command itself must + be integrity protected. + + Once the CCC command completes successfully, if a command is not + protected, then the reply to that command must also not be + protected. This is to support interoperability with clients which + do not support protection once the CCC command has been issued. + + This command must be preceded by a successful security data + exchange. + + If the command is not integrity-protected, the server must respond + with a 533 reply code. + + If the server is not willing to turn off the integrity + requirement, it should respond with a 534 reply code. + + Otherwise, the server must reply with a 200 reply code to indicate + that unprotected commands and replies may now be used on the + command channel. + + INTEGRITY PROTECTED COMMAND (MIC) and + CONFIDENTIALITY PROTECTED COMMAND (CONF) and + PRIVACY PROTECTED COMMAND (ENC) + + The argument field of MIC is a Telnet string consisting of a base + 64 encoded "safe" message produced by a security mechanism + specific message integrity procedure. The argument field of CONF + is a Telnet string consisting of a base 64 encoded "confidential" + message produced by a security mechanism specific confidentiality + procedure. The argument field of ENC is a Telnet string + consisting of a base 64 encoded "private" message produced by a + security mechanism specific message integrity and confidentiality + procedure. + + + +Horowitz & Lunt Standards Track [Page 10] + +RFC 2228 FTP Security Extensions October 1997 + + + The server will decode and/or verify the encoded message. + + This command must be preceded by a successful security data + exchange. + + A server may require that the first command after a successful + security data exchange be CCC, and not implement the protection + commands at all. In this case, the server should respond with a + 502 reply code. + + If the server cannot base 64 decode the argument, it should + respond with a 501 reply code. + + If the server has not completed a security data exchange with the + client, it should respond with a 503 reply code. + + If the server has completed a security data exchange with the + client using a mechanism which supports integrity, and requires a + CCC command due to policy or implementation limitations, it should + respond with a 503 reply code. + + If the server rejects the command because it is not supported by + the current security mechanism, the server should respond with + reply code 537. + + If the server rejects the command (if a checksum fails, for + instance), it should respond with reply code 535. + + If the server is not willing to accept the command (if privacy is + required by policy, for instance, or if a CONF command is received + before a CCC command), it should respond with reply code 533. + + Otherwise, the command will be interpreted as an FTP command. An + end-of-line code need not be included, but if one is included, it + must be a Telnet end-of-line code, not a local end-of-line code. + + The server may require that, under some or all circumstances, all + commands be protected. In this case, it should make a 533 reply + to commands other than MIC, CONF, and ENC. + +4. Login Authorization + + The security data exchange may, among other things, establish the + identity of the client in a secure way to the server. This identity + may be used as one input to the login authorization process. + + + + + + +Horowitz & Lunt Standards Track [Page 11] + +RFC 2228 FTP Security Extensions October 1997 + + + In response to the FTP login commands (AUTH, PASS, ACCT), the server + may choose to change the sequence of commands and replies specified + by RFC 959 as follows. There are also some new replies available. + + If the server is willing to allow the user named by the USER command + to log in based on the identity established by the security data + exchange, it should respond with reply code 232. + + If the security mechanism requires a challenge/response password, it + should respond to the USER command with reply code 336. The text + part of the reply should contain the challenge. The client must + display the challenge to the user before prompting for the password + in this case. This is particularly relevant to more sophisticated + clients or graphical user interfaces which provide dialog boxes or + other modal input. These clients should be careful not to prompt for + the password before the username has been sent to the server, in case + the user needs the challenge in the 336 reply to construct a valid + password. + +5. New FTP Replies + + The new reply codes are divided into two classes. The first class is + new replies made necessary by the new FTP Security commands. The + second class is a new reply type to indicate protected replies. + + 5.1. New individual reply codes + + 232 User logged in, authorized by security data exchange. + 234 Security data exchange complete. + 235 [ADAT=base64data] + ; This reply indicates that the security data exchange + ; completed successfully. The square brackets are not + ; to be included in the reply, but indicate that + ; security data in the reply is optional. + + 334 [ADAT=base64data] + ; This reply indicates that the requested security mechanism + ; is ok, and includes security data to be used by the client + ; to construct the next command. The square brackets are not + ; to be included in the reply, but indicate that + ; security data in the reply is optional. + 335 [ADAT=base64data] + ; This reply indicates that the security data is + ; acceptable, and more is required to complete the + ; security data exchange. The square brackets + ; are not to be included in the reply, but indicate + ; that security data in the reply is optional. + + + + +Horowitz & Lunt Standards Track [Page 12] + +RFC 2228 FTP Security Extensions October 1997 + + + 336 Username okay, need password. Challenge is "...." + ; The exact representation of the challenge should be chosen + ; by the mechanism to be sensible to the human user of the + ; system. + + 431 Need some unavailable resource to process security. + + 533 Command protection level denied for policy reasons. + 534 Request denied for policy reasons. + 535 Failed security check (hash, sequence, etc). + 536 Requested PROT level not supported by mechanism. + 537 Command protection level not supported by security mechanism. + + 5.2. Protected replies. + + One new reply type is introduced: + + 6yz Protected reply + + There are three reply codes of this type. The first, reply + code 631 indicates an integrity protected reply. The + second, reply code 632, indicates a confidentiality and + integrity protected reply. the third, reply code 633, + indicates a confidentiality protected reply. + + The text part of a 631 reply is a Telnet string consisting + of a base 64 encoded "safe" message produced by a security + mechanism specific message integrity procedure. The text + part of a 632 reply is a Telnet string consisting of a base + 64 encoded "private" message produced by a security + mechanism specific message confidentiality and integrity + procedure. The text part of a 633 reply is a Telnet string + consisting of a base 64 encoded "confidential" message + produced by a security mechanism specific message + confidentiality procedure. + + The client will decode and verify the encoded reply. How + failures decoding or verifying replies are handled is + implementation-specific. An end-of-line code need not be + included, but if one is included, it must be a Telnet end- + of-line code, not a local end-of-line code. + + A protected reply may only be sent if a security data + exchange has succeeded. + + The 63z reply may be a multiline reply. In this case, the + plaintext reply must be broken up into a number of + fragments. Each fragment must be protected, then base 64 + + + +Horowitz & Lunt Standards Track [Page 13] + +RFC 2228 FTP Security Extensions October 1997 + + + encoded in order into a separate line of the multiline + reply. There need not be any correspondence between the + line breaks in the plaintext reply and the encoded reply. + Telnet end-of-line codes must appear in the plaintext of the + encoded reply, except for the final end-of-line code, which + is optional. + + The multiline reply must be formatted more strictly than the + continuation specification in RFC 959. In particular, each + line before the last must be formed by the reply code, + followed immediately by a hyphen, followed by a base 64 + encoded fragment of the reply. + + For example, if the plaintext reply is + + 123-First line + Second line + 234 A line beginning with numbers + 123 The last line + + then the resulting protected reply could be any of the + following (the first example has a line break only to fit + within the margins): + + 631 base64(protect("123-First line\r\nSecond line\r\n 234 A line + 631-base64(protect("123-First line\r\n")) + 631-base64(protect("Second line\r\n")) + 631-base64(protect(" 234 A line beginning with numbers\r\n")) + 631 base64(protect("123 The last line")) + + 631-base64(protect("123-First line\r\nSecond line\r\n 234 A line b")) + 631 base64(protect("eginning with numbers\r\n123 The last line\r\n")) + +6. Data Channel Encapsulation + + When data transfers are protected between the client and server (in + either direction), certain transformations and encapsulations must be + performed so that the recipient can properly decode the transmitted + file. + + The sender must apply all protection services after transformations + associated with the representation type, file structure, and transfer + mode have been performed. The data sent over the data channel is, + for the purposes of protection, to be treated as a byte stream. + + When performing a data transfer in an authenticated manner, the + authentication checks are performed on individual blocks of the file, + rather than on the file as a whole. Consequently, it is possible for + + + +Horowitz & Lunt Standards Track [Page 14] + +RFC 2228 FTP Security Extensions October 1997 + + + insertion attacks to insert blocks into the data stream (i.e., + replays) that authenticate correctly, but result in a corrupted file + being undetected by the receiver. To guard against such attacks, the + specific security mechanism employed should include mechanisms to + protect against such attacks. Many GSS-API mechanisms usable with + the specification in Appendix I, and the Kerberos mechanism in + Appendix II do so. + + The sender must take the input byte stream, and break it up into + blocks such that each block, when encoded using a security mechanism + specific procedure, will be no larger than the buffer size negotiated + by the client with the PBSZ command. Each block must be encoded, + then transmitted with the length of the encoded block prepended as a + four byte unsigned integer, most significant byte first. + + When the end of the file is reached, the sender must encode a block + of zero bytes, and send this final block to the recipient before + closing the data connection. + + The recipient will read the four byte length, read a block of data + that many bytes long, then decode and verify this block with a + security mechanism specific procedure. This must be repeated until a + block encoding a buffer of zero bytes is received. This indicates + the end of the encoded byte stream. + + Any transformations associated with the representation type, file + structure, and transfer mode are to be performed by the recipient on + the byte stream resulting from the above process. + + When using block transfer mode, the sender's (cleartext) buffer size + is independent of the block size. + + The server will reply 534 to a STOR, STOU, RETR, LIST, NLST, or APPE + command if the current protection level is not at the level dictated + by the server's security requirements for the particular file + transfer. + + If any data protection services fail at any time during data transfer + at the server end (including an attempt to send a buffer size greater + than the negotiated maximum), the server will send a 535 reply to the + data transfer command (either STOR, STOU, RETR, LIST, NLST, or APPE). + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 15] + +RFC 2228 FTP Security Extensions October 1997 + + +7. Potential policy considerations + + While there are no restrictions on client and server policy, there + are a few recommendations which an implementation should implement. + + - Once a security data exchange takes place, a server should require + all commands be protected (with integrity and/or confidentiality), + and it should protect all replies. Replies should use the same + level of protection as the command which produced them. This + includes replies which indicate failure of the MIC, CONF, and ENC + commands. In particular, it is not meaningful to require that + AUTH and ADAT be protected; it is meaningful and useful to require + that PROT and PBSZ be protected. In particular, the use of CCC is + not recommended, but is defined in the interest of + interoperability between implementations which might desire such + functionality. + + - A client should encrypt the PASS command whenever possible. It is + reasonable for the server to refuse to accept a non-encrypted PASS + command if the server knows encryption is available. + + - Although no security commands are required to be implemented, it + is recommended that an implementation provide all commands which + can be implemented, given the mechanisms supported and the policy + considerations of the site (export controls, for instance). + +8. Declarative specifications + + These sections are modelled after sections 5.3 and 5.4 of RFC 959, + which describe the same information, except for the standard FTP + commands and replies. + + 8.1. FTP Security commands and arguments + + AUTH <SP> <mechanism-name> <CRLF> + ADAT <SP> <base64data> <CRLF> + PROT <SP> <prot-code> <CRLF> + PBSZ <SP> <decimal-integer> <CRLF> + MIC <SP> <base64data> <CRLF> + CONF <SP> <base64data> <CRLF> + ENC <SP> <base64data> <CRLF> + + <mechanism-name> ::= <string> + <base64data> ::= <string> + ; must be formatted as described in section 9 + <prot-code> ::= C | S | E | P + <decimal-integer> ::= any decimal integer from 1 to (2^32)-1 + + + + +Horowitz & Lunt Standards Track [Page 16] + +RFC 2228 FTP Security Extensions October 1997 + + + 8.2. Command-Reply sequences + + Security Association Setup + AUTH + 234 + 334 + 502, 504, 534, 431 + 500, 501, 421 + ADAT + 235 + 335 + 503, 501, 535 + 500, 501, 421 + Data protection negotiation commands + PBSZ + 200 + 503 + 500, 501, 421, 530 + PROT + 200 + 504, 536, 503, 534, 431 + 500, 501, 421, 530 + Command channel protection commands + MIC + 535, 533 + 500, 501, 421 + CONF + 535, 533 + 500, 501, 421 + ENC + 535, 533 + 500, 501, 421 + Security-Enhanced login commands (only new replies listed) + USER + 232 + 336 + Data channel commands (only new replies listed) + STOR + 534, 535 + STOU + 534, 535 + RETR + 534, 535 + + + + + + + + +Horowitz & Lunt Standards Track [Page 17] + +RFC 2228 FTP Security Extensions October 1997 + + + LIST + 534, 535 + NLST + 534, 535 + APPE + 534, 535 + + In addition to these reply codes, any security command can return + 500, 501, 502, 533, or 421. Any ftp command can return a reply + code encapsulated in a 631, 632, or 633 reply once a security data + exchange has completed successfully. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 18] + +RFC 2228 FTP Security Extensions October 1997 + + +9. State Diagrams + + This section includes a state diagram which demonstrates the flow of + authentication and authorization in a security enhanced FTP + implementation. The rectangular blocks show states where the client + must issue a command, and the diamond blocks show states where the + server must issue a response. + + + ,------------------, USER + __\| Unauthenticated |_________\ + | /| (new connection) | /| + | `------------------' | + | | | + | | AUTH | + | V | + | / \ | + | 4yz,5yz / \ 234 | + |<--------< >------------->. | + | \ / | | + | \_/ | | + | | | | + | | 334 | | + | V | | + | ,--------------------, | | + | | Need Security Data |<--. | | + | `--------------------' | | | + | | | | | + | | ADAT | | | + | V | | | + | / \ | | | + | 4yz,5yz / \ 335 | | | + `<--------< >-----------' | | + \ / | | + \_/ | | + | | | + | 235 | | + V | | + ,---------------. | | + ,--->| Authenticated |<--------' | After the client and server + | `---------------' | have completed authenti- + | | | cation, command must be + | | USER | integrity-protected if + | | | integrity is available. The + | |<-------------------' CCC command may be issued to + | V relax this restriction. + + + + + +Horowitz & Lunt Standards Track [Page 19] + +RFC 2228 FTP Security Extensions October 1997 + + + | / \ + | 4yz,5yz / \ 2yz + |<--------< >------------->. + | \ / | + | \_/ | + | | | + | | 3yz | + | V | + | ,---------------. | + | | Need Password | | + | `---------------' | + | | | + | | PASS | + | V | + | / \ | + | 4yz,5yz / \ 2yz | + |<--------< >------------->| + | \ / | + | \_/ | + | | | + | | 3yz | + | V | + | ,--------------. | + | | Need Account | | + | `--------------' | + | | | + | | ACCT | + | V | + | / \ | + | 4yz,5yz / \ 2yz | + `<--------< >------------->| + \ / | + \_/ | + | | + | 3yz | + V | + ,-------------. | + | Authorized |/________| + | (Logged in) |\ + `-------------' + + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 20] + +RFC 2228 FTP Security Extensions October 1997 + + +10. Base 64 Encoding + + Base 64 encoding is the same as the Printable Encoding described in + Section 4.3.2.4 of [RFC-1421], except that line breaks must not be + included. This encoding is defined as follows. + + Proceeding from left to right, the bit string resulting from the + mechanism specific protection routine is encoded into characters + which are universally representable at all sites, though not + necessarily with the same bit patterns (e.g., although the character + "E" is represented in an ASCII-based system as hexadecimal 45 and as + hexadecimal C5 in an EBCDIC-based system, the local significance of + the two representations is equivalent). + + A 64-character subset of International Alphabet IA5 is used, enabling + 6 bits to be represented per printable character. (The proposed + subset of characters is represented identically in IA5 and ASCII.) + The character "=" signifies a special processing function used for + padding within the printable encoding procedure. + + The encoding process represents 24-bit groups of input bits as output + strings of 4 encoded characters. Proceeding from left to right + across a 24-bit input group output from the security mechanism + specific message protection procedure, each 6-bit group is used as an + index into an array of 64 printable characters, namely "[A-Z][a- + z][0-9]+/". The character referenced by the index is placed in the + output string. These characters are selected so as to be universally + representable, and the set excludes characters with particular + significance to Telnet (e.g., "<CR>", "<LF>", IAC). + + Special processing is performed if fewer than 24 bits are available + in an input group at the end of a message. A full encoding quantum + is always completed at the end of a message. When fewer than 24 + input bits are available in an input group, zero bits are added (on + the right) to form an integral number of 6-bit groups. Output + character positions which are not required to represent actual input + data are set to the character "=". Since all canonically encoded + output is an integral number of octets, only the following cases can + arise: (1) the final quantum of encoding input is an integral + multiple of 24 bits; here, the final unit of encoded output will be + an integral multiple of 4 characters with no "=" padding, (2) the + final quantum of encoding input is exactly 8 bits; here, the final + unit of encoded output will be two characters followed by two "=" + padding characters, or (3) the final quantum of encoding input is + exactly 16 bits; here, the final unit of encoded output will be three + characters followed by one "=" padding character. + + + + + +Horowitz & Lunt Standards Track [Page 21] + +RFC 2228 FTP Security Extensions October 1997 + + + Implementors must keep in mind that the base 64 encodings in ADAT, + MIC, CONF, and ENC commands, and in 63z replies may be arbitrarily + long. Thus, the entire line must be read before it can be processed. + Several successive reads on the control channel may be necessary. It + is not appropriate to for a server to reject a command containing a + base 64 encoding simply because it is too long (assuming that the + decoding is otherwise well formed in the context in which it was + sent). + + Case must not be ignored when reading commands and replies containing + base 64 encodings. + +11. Security Considerations + + This entire document deals with security considerations related to + the File Transfer Protocol. + + Third party file transfers cannot be secured using these extensions, + since a security context cannot be established between two servers + using these facilities (no control connection exists between servers + over which to pass ADAT tokens). Further work in this area is + deferred. + +12. Acknowledgements + + I would like to thank the members of the CAT WG, as well as all + participants in discussions on the "cat-ietf@mit.edu" mailing list, + for their contributions to this document. I would especially like to + thank Sam Sjogren, John Linn, Ted Ts'o, Jordan Brown, Michael Kogut, + Derrick Brashear, John Gardiner Myers, Denis Pinkas, and Karri Balk + for their contributions to this work. Of course, without Steve Lunt, + the author of the first six revisions of this document, it would not + exist at all. + +13. References + + [TELNET-SEC] Borman, D., "Telnet Authentication and Encryption + Option", Work in Progress. + + [RFC-1123] Braden, R., "Requirements for Internet Hosts -- + Application and Support", STD 3, RFC 1123, October 1989. + + [RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic + Mail: Part I: Message Encryption and Authentication Procedures", + RFC 1421, February 1993. + + + + + + +Horowitz & Lunt Standards Track [Page 22] + +RFC 2228 FTP Security Extensions October 1997 + + +14. Author's Address + + Marc Horowitz + Cygnus Solutions + 955 Massachusetts Avenue + Cambridge, MA 02139 + + Phone: +1 617 354 7688 + EMail: marc@cygnus.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 23] + +RFC 2228 FTP Security Extensions October 1997 + + +Appendix I: Specification under the GSSAPI + + In order to maximise the utility of new security mechanisms, it is + desirable that new mechanisms be implemented as GSSAPI mechanisms + rather than as FTP security mechanisms. This will enable existing + ftp implementations to support the new mechanisms more easily, since + little or no code will need to be changed. In addition, the + mechanism will be usable by other protocols, such as IMAP, which are + built on top of the GSSAPI, with no additional specification or + implementation work needed by the mechanism designers. + + The security mechanism name (for the AUTH command) associated with + all mechanisms employing the GSSAPI is GSSAPI. If the server + supports a security mechanism employing the GSSAPI, it must respond + with a 334 reply code indicating that an ADAT command is expected + next. + + The client must begin the authentication exchange by calling + GSS_Init_Sec_Context, passing in 0 for input_context_handle + (initially), and a targ_name equal to output_name from + GSS_Import_Name called with input_name_type of Host-Based Service and + input_name_string of "ftp@hostname" where "hostname" is the fully + qualified host name of the server with all letters in lower case. + (Failing this, the client may try again using input_name_string of + "host@hostname".) The output_token must then be base 64 encoded and + sent to the server as the argument to an ADAT command. If + GSS_Init_Sec_Context returns GSS_S_CONTINUE_NEEDED, then the client + must expect a token to be returned in the reply to the ADAT command. + This token must subsequently be passed to another call to + GSS_Init_Sec_Context. In this case, if GSS_Init_Sec_Context returns + no output_token, then the reply code from the server for the previous + ADAT command must have been 235. If GSS_Init_Sec_Context returns + GSS_S_COMPLETE, then no further tokens are expected from the server, + and the client must consider the server authenticated. + + The server must base 64 decode the argument to the ADAT command and + pass the resultant token to GSS_Accept_Sec_Context as input_token, + setting acceptor_cred_handle to NULL (for "use default credentials"), + and 0 for input_context_handle (initially). If an output_token is + returned, it must be base 64 encoded and returned to the client by + including "ADAT=base64string" in the text of the reply. If + GSS_Accept_Sec_Context returns GSS_S_COMPLETE, the reply code must be + 235, and the server must consider the client authenticated. If + GSS_Accept_Sec_Context returns GSS_S_CONTINUE_NEEDED, the reply code + must be 335. Otherwise, the reply code should be 535, and the text + of the reply should contain a descriptive error message. + + + + + +Horowitz & Lunt Standards Track [Page 24] + +RFC 2228 FTP Security Extensions October 1997 + + + The chan_bindings input to GSS_Init_Sec_Context and + GSS_Accept_Sec_Context should use the client internet address and + server internet address as the initiator and acceptor addresses, + respectively. The address type for both should be GSS_C_AF_INET. No + application data should be specified. + + Since GSSAPI supports anonymous peers to security contexts, it is + possible that the client's authentication of the server does not + actually establish an identity. + + The procedure associated with MIC commands, 631 replies, and Safe + file transfers is: + + GSS_Wrap for the sender, with conf_flag == FALSE + + GSS_Unwrap for the receiver + + The procedure associated with ENC commands, 632 replies, and Private + file transfers is: + + GSS_Wrap for the sender, with conf_flag == TRUE + GSS_Unwrap for the receiver + + CONF commands and 633 replies are not supported. + + Both the client and server should inspect the value of conf_avail to + determine whether the peer supports confidentiality services. + + When the security state is reset (when AUTH is received a second + time, or when REIN is received), this should be done by calling the + GSS_Delete_sec_context function. + +Appendix II: Specification under Kerberos version 4 + + The security mechanism name (for the AUTH command) associated with + Kerberos Version 4 is KERBEROS_V4. If the server supports + KERBEROS_V4, it must respond with a 334 reply code indicating that an + ADAT command is expected next. + + The client must retrieve a ticket for the Kerberos principal + "ftp.hostname@realm" by calling krb_mk_req(3) with a principal name + of "ftp", an instance equal to the first part of the canonical host + name of the server with all letters in lower case (as returned by + krb_get_phost(3)), the server's realm name (as returned by + krb_realmofhost(3)), and an arbitrary checksum. The ticket must then + be base 64 encoded and sent as the argument to an ADAT command. + + + + + +Horowitz & Lunt Standards Track [Page 25] + +RFC 2228 FTP Security Extensions October 1997 + + + If the "ftp" principal name is not a registered principal in the + Kerberos database, then the client may fall back on the "rcmd" + principal name (same instance and realm). However, servers must + accept only one or the other of these principal names, and must not + be willing to accept either. Generally, if the server has a key for + the "ftp" principal in its srvtab, then that principal only must be + used, otherwise the "rcmd" principal only must be used. + + The server must base 64 decode the argument to the ADAT command and + pass the result to krb_rd_req(3). The server must add one to the + checksum from the authenticator, convert the result to network byte + order (most significant byte first), and sign it using + krb_mk_safe(3), and base 64 encode the result. Upon success, the + server must reply to the client with a 235 code and include + "ADAT=base64string" in the text of the reply. Upon failure, the + server should reply 535. + + Upon receipt of the 235 reply from the server, the client must parse + the text of the reply for the base 64 encoded data, decode it, + convert it from network byte order, and pass the result to + krb_rd_safe(3). The client must consider the server authenticated if + the resultant checksum is equal to one plus the value previously + sent. + + The procedure associated with MIC commands, 631 replies, and Safe + file transfers is: + + krb_mk_safe(3) for the sender + krb_rd_safe(3) for the receiver + + The procedure associated with ENC commands, 632 replies, and Private + file transfers is: + + krb_mk_priv(3) for the sender + krb_rd_priv(3) for the receiver + + CONF commands and 633 replies are not supported. + + Note that this specification for KERBEROS_V4 contains no provision + for negotiating alternate means for integrity and confidentiality + routines. Note also that the ADAT exchange does not convey whether + the peer supports confidentiality services. + + In order to stay within the allowed PBSZ, implementors must take note + that a cleartext buffer will grow by 31 bytes when processed by + krb_mk_safe(3) and will grow by 26 bytes when processed by + krb_mk_priv(3). + + + + +Horowitz & Lunt Standards Track [Page 26] + +RFC 2228 FTP Security Extensions October 1997 + + +Full Copyright Statement + + Copyright (C) The Internet Society (1997). 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 implmentation may be prepared, copied, published + andand 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. + + + + + + + + + + + + + + + + + + + + + + + + +Horowitz & Lunt Standards Track [Page 27] + diff --git a/crypto/heimdal/doc/whatis.texi b/crypto/heimdal/doc/whatis.texi new file mode 100644 index 0000000..97d4da2 --- /dev/null +++ b/crypto/heimdal/doc/whatis.texi @@ -0,0 +1,149 @@ +@node What is Kerberos?, Building and Installing, Introduction, Top +@chapter What is Kerberos? + +@quotation +@flushleft + Now this Cerberus had three heads of dogs, + the tail of a dragon, and on his back the + heads of all sorts of snakes. + --- Pseudo-Apollodorus Library 2.5.12 +@end flushleft +@end quotation + +Kerberos is a system for authenticating users and services on a network. +It is built upon the assumption that the network is ``unsafe''. For +example, data sent over the network can be eavesdropped and altered, and +addresses can also be faked. Therefore they cannot be used for +authentication purposes. +@cindex authentication + +Kerberos is a trusted third-party service. That means that there is a +third party (the kerberos server) that is trusted by all the entities on +the network (users and services, usually called @dfn{principals}). All +principals share a secret password (or key) with the kerberos server and +this enables principals to verify that the messages from the kerberos +server are authentic. Thus trusting the kerberos server, users and +services can authenticate each other. + +@section Basic mechanism + +@ifinfo +@macro sub{arg} +<\arg\> +@end macro +@end ifinfo + +@tex +@def@xsub#1{$_{#1}$} +@global@let@sub=@xsub +@end tex + +@ifhtml +@macro sub{arg} +<\arg\> +@end macro +@end ifhtml + +@quotation +@strong{Note:} This discussion is about Kerberos version 4, but version +5 works similarly. +@end quotation + +In Kerberos, principals use @dfn{tickets} to prove that they are who +they claim to be. In the following example, @var{A} is the initiator of +the authentication exchange, usually a user, and @var{B} is the service +that @var{A} wishes to use. + +To obtain a ticket for a specific service, @var{A} sends a ticket +request to the kerberos server. The request contains @var{A}'s and +@var{B}'s names (along with some other fields). The kerberos server +checks that both @var{A} and @var{B} are valid principals. + +Having verified the validity of the principals, it creates a packet +containing @var{A}'s and @var{B}'s names, @var{A}'s network address +(@var{A@sub{addr}}), the current time (@var{t@sub{issue}}), the lifetime +of the ticket (@var{life}), and a secret @dfn{session key} +@cindex session key +(@var{K@sub{AB}}). This packet is encrypted with @var{B}'s secret key +(@var{K@sub{B}}). The actual ticket (@var{T@sub{AB}}) looks like this: +(@{@var{A}, @var{B}, @var{A@sub{addr}}, @var{t@sub{issue}}, @var{life}, +@var{K@sub{AB}}@}@var{K@sub{B}}). + +The reply to @var{A} consists of the ticket (@var{T@sub{AB}}), @var{B}'s +name, the current time, the lifetime of the ticket, and the session key, all +encrypted in @var{A}'s secret key (@{@var{B}, @var{t@sub{issue}}, +@var{life}, @var{K@sub{AB}}, @var{T@sub{AB}}@}@var{K@sub{A}}). @var{A} +decrypts the reply and retains it for later use. + +@sp 1 + +Before sending a message to @var{B}, @var{A} creates an authenticator +consisting of @var{A}'s name, @var{A}'s address, the current time, and a +``checksum'' chosen by @var{A}, all encrypted with the secret session +key (@{@var{A}, @var{A@sub{addr}}, @var{t@sub{current}}, +@var{checksum}@}@var{K@sub{AB}}). This is sent together with the ticket +received from the kerberos server to @var{B}. Upon reception, @var{B} +decrypts the ticket using @var{B}'s secret key. Since the ticket +contains the session key that the authenticator was encrypted with, +@var{B} can now also decrypt the authenticator. To verify that @var{A} +really is @var{A}, @var{B} now has to compare the contents of the ticket +with that of the authenticator. If everything matches, @var{B} now +considers @var{A} as properly authenticated. + +@c (here we should have some more explanations) + +@section Different attacks + +@subheading Impersonating A + +An impostor, @var{C} could steal the authenticator and the ticket as it +is transmitted across the network, and use them to impersonate +@var{A}. The address in the ticket and the authenticator was added to +make it more difficult to perform this attack. To succeed @var{C} will +have to either use the same machine as @var{A} or fake the source +addresses of the packets. By including the time stamp in the +authenticator, @var{C} does not have much time in which to mount the +attack. + +@subheading Impersonating B + +@var{C} can hijack @var{B}'s network address, and when @var{A} sends +her credentials, @var{C} just pretend to verify them. @var{C} can't +be sure that she is talking to @var{A}. + +@section Defense strategies + +It would be possible to add a @dfn{replay cache} +@cindex replay cache +to the server side. The idea is to save the authenticators sent during +the last few minutes, so that @var{B} can detect when someone is trying +to retransmit an already used message. This is somewhat impractical +(mostly regarding efficiency), and is not part of Kerberos 4; MIT +Kerberos 5 contains it. + +To authenticate @var{B}, @var{A} might request that @var{B} sends +something back that proves that @var{B} has access to the session +key. An example of this is the checksum that @var{A} sent as part of the +authenticator. One typical procedure is to add one to the checksum, +encrypt it with the session key and send it back to @var{A}. This is +called @dfn{mutual authentication}. + +The session key can also be used to add cryptographic checksums to the +messages sent between @var{A} and @var{B} (known as @dfn{message +integrity}). Encryption can also be added (@dfn{message +confidentiality}). This is probably the best approach in all cases. +@cindex integrity +@cindex confidentiality + +@section Further reading + +The original paper on Kerberos from 1988 is @cite{Kerberos: An +Authentication Service for Open Network Systems}, by Jennifer Steiner, +Clifford Neuman and Jeffrey I. Schiller. + +A less technical description can be found in @cite{Designing an +Authentication System: a Dialogue in Four Scenes} by Bill Bryant, also +from 1988. + +These documents can be found on our web-page at +@url{http://www.pdc.kth.se/kth-krb/}. diff --git a/crypto/heimdal/doc/win2k.texi b/crypto/heimdal/doc/win2k.texi new file mode 100644 index 0000000..f5ec057 --- /dev/null +++ b/crypto/heimdal/doc/win2k.texi @@ -0,0 +1,57 @@ +@node Windows 2000 compatability, Acknowledgments, Kerberos 4 issues, Top +@comment node-name, next, previous, up +@chapter Windows 2000 compatability + +Windows 2000 (formerly known as Windows NT 5) from Microsoft implements +Kerberos 5. Their implementation, however, has some quirks, +peculiarities, and bugs. This chapter is a short summary of the things +that we have found out while trying to test Heimdal against Windows +2000. Another big problem with the Kerberos implementation in Windows +2000 is the almost complete lack of documentation. + +This information should apply to Heimdal @value{VERSION} and Windows +2000 RC1. It's of course subject all the time and mostly consists of +our not so inspired guesses. Hopefully it's still somewhat useful. + +@menu +* Encryption types:: +* Authorization data:: +@end menu + +@node Encryption types, Authorization data, Windows 2000 compatability, Windows 2000 compatability +@comment node-name, next, previous, up +@section Encryption types + +Windows 2000 supports both the standard DES encryptions (des-cbc-crc and +des-cbc-md5) and its own proprietary encryption that is based on md4 and +rc4 and which you cannot get hold of how it works with a NDA. To enable +a given principal to use DES, it needs to have DES keys in the database. +To do this, you need to enable DES keys for the particular principal +with the user administration tool and then change the password. + +@node Authorization data, , Encryption types, Windows 2000 compatability +@comment node-name, next, previous, up +@section Authorization data + +The Windows 2000 KDC also adds extra authorization data in tickets. +It is at this point unclear what triggers it to do this. The format of +this data is unknown and according to Microsoft, subject to change. A +simple way of getting hold of the data to be able to understand it +better is described here. + +@enumerate +@item Find the client example on using the SSPI in the SDK documentation. +@item Change ``AuthSamp'' in the source code to lowercase. +@item Build the program. +@item Add the ``authsamp'' principal with a known password to the +database. Make sure it has a DES key. +@item Run @kbd{ktutil add} to add the key for that principal to a +keytab. +@item Run @kbd{appl/test/nt_gss_server -p 2000 -s authsamp +--dump-auth=file} where file is an appropriate file. +@item It should authenticate and dump for you the authorization data in +the file. +@item The tool @kbd{lib/asn1/asn1_print} is somewhat useful for +analyzing the data. +@end enumerate + |
