diff options
author | Stanislav Sedov <stas@FreeBSD.org> | 2011-09-29 05:23:57 +0000 |
---|---|---|
committer | Stanislav Sedov <stas@FreeBSD.org> | 2011-09-29 05:23:57 +0000 |
commit | 31f1e9c17ffae440059e8cc532fa26b92d534f7b (patch) | |
tree | cf5b65423910d126fddaaf04b885d0de3507d692 /doc | |
parent | c19800e8cd5640693f36f2040db4ab5e8d738146 (diff) | |
download | src-31f1e9c17ffae440059e8cc532fa26b92d534f7b.tar.gz src-31f1e9c17ffae440059e8cc532fa26b92d534f7b.zip |
- Flatten the vendor heimdal tree.
Notes
Notes:
svn path=/vendor-crypto/heimdal/dist/; revision=225864
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Makefile.am | 85 | ||||
-rw-r--r-- | doc/Makefile.in | 982 | ||||
-rw-r--r-- | doc/ack.texi | 72 | ||||
-rw-r--r-- | doc/apps.texi | 244 | ||||
-rw-r--r-- | doc/doxytmpl.dxy | 257 | ||||
-rw-r--r-- | doc/hcrypto.din | 15 | ||||
-rw-r--r-- | doc/heimdal.css | 53 | ||||
-rw-r--r-- | doc/heimdal.texi | 370 | ||||
-rw-r--r-- | doc/hx509.din | 15 | ||||
-rw-r--r-- | doc/hx509.texi | 633 | ||||
-rw-r--r-- | doc/init-creds | 374 | ||||
-rw-r--r-- | doc/install.texi | 107 | ||||
-rw-r--r-- | doc/intro.texi | 99 | ||||
-rw-r--r-- | doc/kerberos4.texi | 226 | ||||
-rw-r--r-- | doc/krb5.din | 16 | ||||
-rw-r--r-- | doc/latin1.tex | 95 | ||||
-rw-r--r-- | doc/layman.asc | 1855 | ||||
-rwxr-xr-x | doc/mdate-sh | 92 | ||||
-rw-r--r-- | doc/migration.texi | 43 | ||||
-rw-r--r-- | doc/misc.texi | 58 | ||||
-rw-r--r-- | doc/ntlm.din | 15 | ||||
-rw-r--r-- | doc/programming.texi | 642 | ||||
-rw-r--r-- | doc/setup.texi | 1455 | ||||
-rwxr-xr-x | doc/vars.texi | 7 | ||||
-rw-r--r-- | doc/vars.tin | 7 | ||||
-rw-r--r-- | doc/whatis.texi | 161 | ||||
-rw-r--r-- | doc/win2k.texi | 306 |
27 files changed, 8284 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000000..87473fe0a3d6 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,85 @@ +# $Id: Makefile.am 22284 2007-12-13 20:39:37Z lha $ + +include $(top_srcdir)/Makefile.am.common + +AUTOMAKE_OPTIONS = no-texinfo.tex + +MAKEINFOFLAGS = --no-split --css-include=$(srcdir)/heimdal.css + +TEXI2DVI = true # ARGH, make distcheck can't be disabled to not build dvifiles + +info_TEXINFOS = heimdal.texi hx509.texi + +dxy_subst = sed -e 's,[@]srcdir[@],$(srcdir),g' \ + -e 's,[@]objdir[@],.,g' \ + -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' + +krb5.dxy: krb5.din Makefile + $(dxy_subst) < $(srcdir)/krb5.din > krb5.dxy.tmp + chmod +x krb5.dxy.tmp + mv krb5.dxy.tmp krb5.dxy + +ntlm.dxy: ntlm.din Makefile + $(dxy_subst) < $(srcdir)/ntlm.din > ntlm.dxy.tmp + chmod +x ntlm.dxy.tmp + mv ntlm.dxy.tmp ntlm.dxy + +hx509.dxy: hx509.din Makefile + $(dxy_subst) < $(srcdir)/hx509.din > hx509.dxy.tmp + chmod +x hx509.dxy.tmp + mv hx509.dxy.tmp hx509.dxy + +hcrypto.dxy: hcrypto.din Makefile + $(dxy_subst) < $(srcdir)/hcrypto.din > hcrypto.dxy.tmp + chmod +x hcrypto.dxy.tmp + mv hcrypto.dxy.tmp hcrypto.dxy + + +texi_subst = sed -e 's,[@]dbdir[@],$(localstatedir),g' \ + -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' + +vars.texi: vars.tin Makefile + $(texi_subst) < $(srcdir)/vars.tin > vars.texi.tmp + chmod +x vars.texi.tmp + mv vars.texi.tmp vars.texi + +doxygen: krb5.dxy ntlm.dxy hx509.dxy hcrypto.dxy + doxygen krb5.dxy + doxygen ntlm.dxy + doxygen hx509.dxy + doxygen hcrypto.dxy + +heimdal_TEXINFOS = \ + ack.texi \ + apps.texi \ + heimdal.texi \ + install.texi \ + intro.texi \ + kerberos4.texi \ + migration.texi \ + misc.texi \ + programming.texi \ + setup.texi \ + vars.texi \ + whatis.texi \ + win2k.texi + +EXTRA_DIST = \ + krb5.din \ + ntlm.din \ + hx509.din \ + hcrypto.din \ + heimdal.css \ + init-creds \ + latin1.tex \ + layman.asc \ + doxytmpl.dxy \ + vars.tin + +CLEANFILES = \ + krb5.dxy* \ + ntlm.dxy* \ + hx509.dxy* \ + hcrypto.dxy* \ + vars.texi* + diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 000000000000..b79a7e33ece5 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,982 @@ +# Makefile.in generated by automake 1.10 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006 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. + +@SET_MAKE@ + +# $Id: Makefile.am 22284 2007-12-13 20:39:37Z lha $ + +# $Id: Makefile.am.common 10998 2002-05-19 18:35:37Z joda $ + +# $Id: Makefile.am.common 22488 2008-01-21 11:47:22Z lha $ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(heimdal_TEXINFOS) $(srcdir)/Makefile.am \ + $(srcdir)/Makefile.in $(top_srcdir)/Makefile.am.common \ + $(top_srcdir)/cf/Makefile.am.common mdate-sh +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/cf/aix.m4 \ + $(top_srcdir)/cf/auth-modules.m4 $(top_srcdir)/cf/autobuild.m4 \ + $(top_srcdir)/cf/broken-getaddrinfo.m4 \ + $(top_srcdir)/cf/broken-glob.m4 \ + $(top_srcdir)/cf/broken-realloc.m4 \ + $(top_srcdir)/cf/broken-snprintf.m4 $(top_srcdir)/cf/broken.m4 \ + $(top_srcdir)/cf/broken2.m4 $(top_srcdir)/cf/c-attribute.m4 \ + $(top_srcdir)/cf/capabilities.m4 \ + $(top_srcdir)/cf/check-compile-et.m4 \ + $(top_srcdir)/cf/check-getpwnam_r-posix.m4 \ + $(top_srcdir)/cf/check-man.m4 \ + $(top_srcdir)/cf/check-netinet-ip-and-tcp.m4 \ + $(top_srcdir)/cf/check-type-extra.m4 \ + $(top_srcdir)/cf/check-var.m4 $(top_srcdir)/cf/check-x.m4 \ + $(top_srcdir)/cf/check-xau.m4 $(top_srcdir)/cf/crypto.m4 \ + $(top_srcdir)/cf/db.m4 $(top_srcdir)/cf/destdirs.m4 \ + $(top_srcdir)/cf/dlopen.m4 \ + $(top_srcdir)/cf/find-func-no-libs.m4 \ + $(top_srcdir)/cf/find-func-no-libs2.m4 \ + $(top_srcdir)/cf/find-func.m4 \ + $(top_srcdir)/cf/find-if-not-broken.m4 \ + $(top_srcdir)/cf/framework-security.m4 \ + $(top_srcdir)/cf/have-struct-field.m4 \ + $(top_srcdir)/cf/have-type.m4 $(top_srcdir)/cf/irix.m4 \ + $(top_srcdir)/cf/krb-bigendian.m4 \ + $(top_srcdir)/cf/krb-func-getlogin.m4 \ + $(top_srcdir)/cf/krb-ipv6.m4 $(top_srcdir)/cf/krb-prog-ln-s.m4 \ + $(top_srcdir)/cf/krb-readline.m4 \ + $(top_srcdir)/cf/krb-struct-spwd.m4 \ + $(top_srcdir)/cf/krb-struct-winsize.m4 \ + $(top_srcdir)/cf/largefile.m4 $(top_srcdir)/cf/mips-abi.m4 \ + $(top_srcdir)/cf/misc.m4 $(top_srcdir)/cf/need-proto.m4 \ + $(top_srcdir)/cf/osfc2.m4 $(top_srcdir)/cf/otp.m4 \ + $(top_srcdir)/cf/proto-compat.m4 $(top_srcdir)/cf/pthreads.m4 \ + $(top_srcdir)/cf/resolv.m4 $(top_srcdir)/cf/retsigtype.m4 \ + $(top_srcdir)/cf/roken-frag.m4 \ + $(top_srcdir)/cf/socket-wrapper.m4 $(top_srcdir)/cf/sunos.m4 \ + $(top_srcdir)/cf/telnet.m4 $(top_srcdir)/cf/test-package.m4 \ + $(top_srcdir)/cf/version-script.m4 $(top_srcdir)/cf/wflags.m4 \ + $(top_srcdir)/cf/win32.m4 $(top_srcdir)/cf/with-all.m4 \ + $(top_srcdir)/acinclude.m4 $(top_srcdir)/configure.in +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/include/config.h +CONFIG_CLEAN_FILES = +depcomp = +am__depfiles_maybe = +SOURCES = +DIST_SOURCES = +INFO_DEPS = $(srcdir)/heimdal.info $(srcdir)/hx509.info +am__TEXINFO_TEX_DIR = $(srcdir) +DVIS = heimdal.dvi hx509.dvi +PDFS = heimdal.pdf hx509.pdf +PSS = heimdal.ps hx509.ps +HTMLS = heimdal.html hx509.html +TEXINFOS = heimdal.texi hx509.texi +TEXI2PDF = $(TEXI2DVI) --pdf --batch +MAKEINFOHTML = $(MAKEINFO) --html +AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS) +DVIPS = dvips +am__installdirs = "$(DESTDIR)$(infodir)" +am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; +am__vpath_adj = case $$p in \ + $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ + *) f=$$p;; \ + esac; +am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AIX_EXTRA_KAFS = @AIX_EXTRA_KAFS@ +AMTAR = @AMTAR@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CANONICAL_HOST = @CANONICAL_HOST@ +CATMAN = @CATMAN@ +CATMANEXT = @CATMANEXT@ +CC = @CC@ +CFLAGS = @CFLAGS@ +COMPILE_ET = @COMPILE_ET@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DBLIB = @DBLIB@ +DEFS = @DEFS@ +DIR_com_err = @DIR_com_err@ +DIR_hcrypto = @DIR_hcrypto@ +DIR_hdbdir = @DIR_hdbdir@ +DIR_roken = @DIR_roken@ +ECHO = @ECHO@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +F77 = @F77@ +FFLAGS = @FFLAGS@ +GREP = @GREP@ +GROFF = @GROFF@ +INCLUDES_roken = @INCLUDES_roken@ +INCLUDE_hcrypto = @INCLUDE_hcrypto@ +INCLUDE_hesiod = @INCLUDE_hesiod@ +INCLUDE_krb4 = @INCLUDE_krb4@ +INCLUDE_openldap = @INCLUDE_openldap@ +INCLUDE_readline = @INCLUDE_readline@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LDFLAGS_VERSION_SCRIPT = @LDFLAGS_VERSION_SCRIPT@ +LEX = @LEX@ +LEXLIB = @LEXLIB@ +LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ +LIBADD_roken = @LIBADD_roken@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIB_AUTH_SUBDIRS = @LIB_AUTH_SUBDIRS@ +LIB_NDBM = @LIB_NDBM@ +LIB_XauFileName = @LIB_XauFileName@ +LIB_XauReadAuth = @LIB_XauReadAuth@ +LIB_XauWriteAuth = @LIB_XauWriteAuth@ +LIB_bswap16 = @LIB_bswap16@ +LIB_bswap32 = @LIB_bswap32@ +LIB_com_err = @LIB_com_err@ +LIB_com_err_a = @LIB_com_err_a@ +LIB_com_err_so = @LIB_com_err_so@ +LIB_crypt = @LIB_crypt@ +LIB_db_create = @LIB_db_create@ +LIB_dbm_firstkey = @LIB_dbm_firstkey@ +LIB_dbopen = @LIB_dbopen@ +LIB_dlopen = @LIB_dlopen@ +LIB_dn_expand = @LIB_dn_expand@ +LIB_door_create = @LIB_door_create@ +LIB_el_init = @LIB_el_init@ +LIB_freeaddrinfo = @LIB_freeaddrinfo@ +LIB_gai_strerror = @LIB_gai_strerror@ +LIB_getaddrinfo = @LIB_getaddrinfo@ +LIB_gethostbyname = @LIB_gethostbyname@ +LIB_gethostbyname2 = @LIB_gethostbyname2@ +LIB_getnameinfo = @LIB_getnameinfo@ +LIB_getpwnam_r = @LIB_getpwnam_r@ +LIB_getsockopt = @LIB_getsockopt@ +LIB_hcrypto = @LIB_hcrypto@ +LIB_hcrypto_a = @LIB_hcrypto_a@ +LIB_hcrypto_appl = @LIB_hcrypto_appl@ +LIB_hcrypto_so = @LIB_hcrypto_so@ +LIB_hesiod = @LIB_hesiod@ +LIB_hstrerror = @LIB_hstrerror@ +LIB_kdb = @LIB_kdb@ +LIB_krb4 = @LIB_krb4@ +LIB_loadquery = @LIB_loadquery@ +LIB_logout = @LIB_logout@ +LIB_logwtmp = @LIB_logwtmp@ +LIB_openldap = @LIB_openldap@ +LIB_openpty = @LIB_openpty@ +LIB_otp = @LIB_otp@ +LIB_pidfile = @LIB_pidfile@ +LIB_readline = @LIB_readline@ +LIB_res_ndestroy = @LIB_res_ndestroy@ +LIB_res_nsearch = @LIB_res_nsearch@ +LIB_res_search = @LIB_res_search@ +LIB_roken = @LIB_roken@ +LIB_security = @LIB_security@ +LIB_setsockopt = @LIB_setsockopt@ +LIB_socket = @LIB_socket@ +LIB_syslog = @LIB_syslog@ +LIB_tgetent = @LIB_tgetent@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +NROFF = @NROFF@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PTHREADS_CFLAGS = @PTHREADS_CFLAGS@ +PTHREADS_LIBS = @PTHREADS_LIBS@ +RANLIB = @RANLIB@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +VERSION = @VERSION@ +VERSIONING = @VERSIONING@ +VOID_RETSIGTYPE = @VOID_RETSIGTYPE@ +WFLAGS = @WFLAGS@ +WFLAGS_NOIMPLICITINT = @WFLAGS_NOIMPLICITINT@ +WFLAGS_NOUNUSED = @WFLAGS_NOUNUSED@ +XMKMF = @XMKMF@ +X_CFLAGS = @X_CFLAGS@ +X_EXTRA_LIBS = @X_EXTRA_LIBS@ +X_LIBS = @X_LIBS@ +X_PRE_LIBS = @X_PRE_LIBS@ +YACC = @YACC@ +YFLAGS = @YFLAGS@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_F77 = @ac_ct_F77@ +am__leading_dot = @am__leading_dot@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dpagaix_cflags = @dpagaix_cflags@ +dpagaix_ldadd = @dpagaix_ldadd@ +dpagaix_ldflags = @dpagaix_ldflags@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +SUFFIXES = .et .h .x .z .1 .3 .5 .8 .cat1 .cat3 .cat5 .cat8 +AM_CPPFLAGS = -I$(top_builddir)/include $(INCLUDES_roken) +@do_roken_rename_TRUE@ROKEN_RENAME = -DROKEN_RENAME +AM_CFLAGS = $(WFLAGS) +CP = cp +buildinclude = $(top_builddir)/include +LIB_getattr = @LIB_getattr@ +LIB_getpwent_r = @LIB_getpwent_r@ +LIB_odm_initialize = @LIB_odm_initialize@ +LIB_setpcred = @LIB_setpcred@ +HESIODLIB = @HESIODLIB@ +HESIODINCLUDE = @HESIODINCLUDE@ +NROFF_MAN = groff -mandoc -Tascii +LIB_kafs = $(top_builddir)/lib/kafs/libkafs.la $(AIX_EXTRA_KAFS) +@KRB5_TRUE@LIB_krb5 = $(top_builddir)/lib/krb5/libkrb5.la \ +@KRB5_TRUE@ $(top_builddir)/lib/asn1/libasn1.la + +@KRB5_TRUE@LIB_gssapi = $(top_builddir)/lib/gssapi/libgssapi.la +@KRB5_TRUE@LIB_tsasl = $(top_builddir)/lib/tsasl/libtsasl.la +@DCE_TRUE@LIB_kdfs = $(top_builddir)/lib/kdfs/libkdfs.la +AUTOMAKE_OPTIONS = no-texinfo.tex +MAKEINFOFLAGS = --no-split --css-include=$(srcdir)/heimdal.css +TEXI2DVI = true # ARGH, make distcheck can't be disabled to not build dvifiles +info_TEXINFOS = heimdal.texi hx509.texi +dxy_subst = sed -e 's,[@]srcdir[@],$(srcdir),g' \ + -e 's,[@]objdir[@],.,g' \ + -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' + +texi_subst = sed -e 's,[@]dbdir[@],$(localstatedir),g' \ + -e 's,[@]PACKAGE_VERSION[@],$(PACKAGE_VERSION),g' + +heimdal_TEXINFOS = \ + ack.texi \ + apps.texi \ + heimdal.texi \ + install.texi \ + intro.texi \ + kerberos4.texi \ + migration.texi \ + misc.texi \ + programming.texi \ + setup.texi \ + vars.texi \ + whatis.texi \ + win2k.texi + +EXTRA_DIST = \ + krb5.din \ + ntlm.din \ + hx509.din \ + hcrypto.din \ + heimdal.css \ + init-creds \ + latin1.tex \ + layman.asc \ + doxytmpl.dxy \ + vars.tin + +CLEANFILES = \ + krb5.dxy* \ + ntlm.dxy* \ + hx509.dxy* \ + hcrypto.dxy* \ + vars.texi* + +all: all-am + +.SUFFIXES: +.SUFFIXES: .et .h .x .z .1 .3 .5 .8 .cat1 .cat3 .cat5 .cat8 .c .dvi .html .info .pdf .ps .texi +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(top_srcdir)/Makefile.am.common $(top_srcdir)/cf/Makefile.am.common $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign --ignore-deps doc/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --foreign --ignore-deps doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs + +.texi.info: + restore=: && backupdir="$(am__leading_dot)am$$$$" && \ + am__cwd=`pwd` && cd $(srcdir) && \ + rm -rf $$backupdir && mkdir $$backupdir && \ + if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ + for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ + if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \ + done; \ + else :; fi && \ + cd "$$am__cwd"; \ + if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -rf $$backupdir; exit $$rc + +.texi.dvi: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2DVI) $< + +.texi.pdf: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \ + $(TEXI2PDF) $< + +.texi.html: + rm -rf $(@:.html=.htp) + if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \ + -o $(@:.html=.htp) $<; \ + then \ + rm -rf $@; \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + mv $(@:.html=) $@; else mv $(@:.html=.htp) $@; fi; \ + else \ + if test ! -d $(@:.html=.htp) && test -d $(@:.html=); then \ + rm -rf $(@:.html=); else rm -Rf $(@:.html=.htp) $@; fi; \ + exit 1; \ + fi +$(srcdir)/heimdal.info: heimdal.texi $(heimdal_TEXINFOS) +heimdal.dvi: heimdal.texi $(heimdal_TEXINFOS) +heimdal.pdf: heimdal.texi $(heimdal_TEXINFOS) +heimdal.html: heimdal.texi $(heimdal_TEXINFOS) +$(srcdir)/hx509.info: hx509.texi +hx509.dvi: hx509.texi +hx509.pdf: hx509.texi +hx509.html: hx509.texi +.dvi.ps: + TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \ + $(DVIPS) -o $@ $< + +uninstall-dvi-am: + @$(NORMAL_UNINSTALL) + @list='$(DVIS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ + rm -f "$(DESTDIR)$(dvidir)/$$f"; \ + done + +uninstall-html-am: + @$(NORMAL_UNINSTALL) + @list='$(HTMLS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ + rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ + done + +uninstall-info-am: + @$(PRE_UNINSTALL) + @if test -d '$(DESTDIR)$(infodir)' && \ + (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ + install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + done; \ + else :; fi + @$(NORMAL_UNINSTALL) + @list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \ + (if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \ + echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \ + rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \ + else :; fi); \ + done + +uninstall-pdf-am: + @$(NORMAL_UNINSTALL) + @list='$(PDFS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ + rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ + done + +uninstall-ps-am: + @$(NORMAL_UNINSTALL) + @list='$(PSS)'; for p in $$list; do \ + f=$(am__strip_dir) \ + echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ + rm -f "$(DESTDIR)$(psdir)/$$f"; \ + done + +dist-info: $(INFO_DEPS) + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for base in $$list; do \ + case $$base in \ + $(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$base; then d=.; else d=$(srcdir); fi; \ + base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \ + for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ + if test -f $$file; then \ + relfile=`expr "$$file" : "$$d/\(.*\)"`; \ + test -f $(distdir)/$$relfile || \ + cp -p $$file $(distdir)/$$relfile; \ + else :; fi; \ + done; \ + done + +mostlyclean-aminfo: + -rm -rf heimdal.aux heimdal.cp heimdal.cps heimdal.fn heimdal.fns heimdal.ky \ + heimdal.kys heimdal.log heimdal.pg heimdal.tmp heimdal.toc \ + heimdal.tp heimdal.tps heimdal.vr heimdal.vrs heimdal.dvi \ + heimdal.pdf heimdal.ps heimdal.html hx509.aux hx509.cp \ + hx509.cps hx509.fn hx509.fns hx509.ky hx509.kys hx509.log \ + hx509.pg hx509.tmp hx509.toc hx509.tp hx509.tps hx509.vr \ + hx509.vrs hx509.dvi hx509.pdf hx509.ps hx509.html + +maintainer-clean-aminfo: + @list='$(INFO_DEPS)'; for i in $$list; do \ + i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \ + echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \ + rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \ + done +tags: TAGS +TAGS: + +ctags: CTAGS +CTAGS: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$(top_distdir)" distdir="$(distdir)" \ + dist-info dist-hook +check-am: all-am + $(MAKE) $(AM_MAKEFLAGS) check-local +check: check-am +all-am: Makefile $(INFO_DEPS) all-local +installdirs: + for dir in "$(DESTDIR)$(infodir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: $(DVIS) + +html: html-am + +html-am: $(HTMLS) + +info: info-am + +info-am: $(INFO_DEPS) + +install-data-am: install-info-am + @$(NORMAL_INSTALL) + $(MAKE) $(AM_MAKEFLAGS) install-data-hook + +install-dvi: install-dvi-am + +install-dvi-am: $(DVIS) + @$(NORMAL_INSTALL) + test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" + @list='$(DVIS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ + done +install-exec-am: + @$(NORMAL_INSTALL) + $(MAKE) $(AM_MAKEFLAGS) install-exec-hook + +install-html: install-html-am + +install-html-am: $(HTMLS) + @$(NORMAL_INSTALL) + test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" + @list='$(HTMLS)'; for p in $$list; do \ + if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + if test -d "$$d$$p"; then \ + echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ + $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ + echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + else \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + fi; \ + done +install-info: install-info-am + +install-info-am: $(INFO_DEPS) + @$(NORMAL_INSTALL) + test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" + @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + case $$file in \ + $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ + esac; \ + if test -f $$file; then d=.; else d=$(srcdir); fi; \ + file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ + for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + if test -f $$ifile; then \ + relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ + echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ + $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + else : ; fi; \ + done; \ + done + @$(POST_INSTALL) + @if (install-info --version && \ + install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ + list='$(INFO_DEPS)'; \ + for file in $$list; do \ + relfile=`echo "$$file" | sed 's|^.*/||'`; \ + echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ + install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\ + done; \ + else : ; fi +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: $(PDFS) + @$(NORMAL_INSTALL) + test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" + @list='$(PDFS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ + done +install-ps: install-ps-am + +install-ps-am: $(PSS) + @$(NORMAL_INSTALL) + test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" + @list='$(PSS)'; for p in $$list; do \ + if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ + f=$(am__strip_dir) \ + echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ + $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ + done +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-aminfo \ + maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \ + mostlyclean-libtool + +pdf: pdf-am + +pdf-am: $(PDFS) + +ps: ps-am + +ps-am: $(PSS) + +uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ + uninstall-pdf-am uninstall-ps-am + @$(NORMAL_INSTALL) + $(MAKE) $(AM_MAKEFLAGS) uninstall-hook + +.MAKE: install-am install-data-am install-exec-am install-strip \ + uninstall-am + +.PHONY: all all-am all-local check check-am check-local clean \ + clean-generic clean-libtool dist-hook dist-info distclean \ + distclean-generic distclean-libtool distdir dvi dvi-am html \ + html-am info info-am install install-am install-data \ + install-data-am install-data-hook install-dvi install-dvi-am \ + install-exec install-exec-am install-exec-hook install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-aminfo \ + maintainer-clean-generic mostlyclean mostlyclean-aminfo \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + uninstall uninstall-am uninstall-dvi-am uninstall-hook \ + uninstall-html-am uninstall-info-am uninstall-pdf-am \ + uninstall-ps-am + + +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 \ + echo "*"; \ + echo "* Failed to install $$x setuid root"; \ + echo "*"; \ + fi; done + +install-exec-hook: install-suid-programs + +install-build-headers:: $(include_HEADERS) $(dist_include_HEADERS) $(nodist_include_HEADERS) $(build_HEADERZ) $(nobase_include_HEADERS) + @foo='$(include_HEADERS) $(dist_include_HEADERS) $(nodist_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 ; \ + foo='$(nobase_include_HEADERS)'; \ + for f in $$foo; do \ + if test -f "$(srcdir)/$$f"; then file="$(srcdir)/$$f"; \ + else file="$$f"; fi; \ + $(mkdir_p) $(buildinclude)/`dirname $$f` ; \ + 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 + +check-local:: + @if test '$(CHECK_LOCAL)' = "no-check-local"; then \ + foo=''; elif test '$(CHECK_LOCAL)'; then \ + foo='$(CHECK_LOCAL)'; else \ + foo='$(PROGRAMS)'; fi; \ + if test "$$foo"; then \ + failed=0; all=0; \ + for i in $$foo; do \ + all=`expr $$all + 1`; \ + if (./$$i --version && ./$$i --help) > /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 || exit 1; \ + fi + +.x.c: + @cmp -s $< $@ 2> /dev/null || cp $< $@ +#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-cat-mans: + $(SHELL) $(top_srcdir)/cf/install-catman.sh install "$(INSTALL_DATA)" "$(mkinstalldirs)" "$(srcdir)" "$(DESTDIR)$(mandir)" '$(CATMANEXT)' $(man_MANS) $(man1_MANS) $(man3_MANS) $(man5_MANS) $(man8_MANS) + +uninstall-cat-mans: + $(SHELL) $(top_srcdir)/cf/install-catman.sh uninstall "$(INSTALL_DATA)" "$(mkinstalldirs)" "$(srcdir)" "$(DESTDIR)$(mandir)" '$(CATMANEXT)' $(man_MANS) $(man1_MANS) $(man3_MANS) $(man5_MANS) $(man8_MANS) + +install-data-hook: install-cat-mans +uninstall-hook: uninstall-cat-mans + +.et.h: + $(COMPILE_ET) $< +.et.c: + $(COMPILE_ET) $< + +# +# Useful target for debugging +# + +check-valgrind: + tobjdir=`cd $(top_builddir) && pwd` ; \ + tsrcdir=`cd $(top_srcdir) && pwd` ; \ + env TESTS_ENVIRONMENT="$${tobjdir}/libtool --mode execute valgrind --leak-check=full --trace-children=yes --quiet -q --num-callers=30 --suppressions=$${tsrcdir}/cf/valgrind-suppressions" make check + +# +# Target to please samba build farm, builds distfiles in-tree. +# Will break when automake changes... +# + +distdir-in-tree: $(DISTFILES) $(INFO_DEPS) + list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" != .; then \ + (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) distdir-in-tree) ; \ + fi ; \ + done + +krb5.dxy: krb5.din Makefile + $(dxy_subst) < $(srcdir)/krb5.din > krb5.dxy.tmp + chmod +x krb5.dxy.tmp + mv krb5.dxy.tmp krb5.dxy + +ntlm.dxy: ntlm.din Makefile + $(dxy_subst) < $(srcdir)/ntlm.din > ntlm.dxy.tmp + chmod +x ntlm.dxy.tmp + mv ntlm.dxy.tmp ntlm.dxy + +hx509.dxy: hx509.din Makefile + $(dxy_subst) < $(srcdir)/hx509.din > hx509.dxy.tmp + chmod +x hx509.dxy.tmp + mv hx509.dxy.tmp hx509.dxy + +hcrypto.dxy: hcrypto.din Makefile + $(dxy_subst) < $(srcdir)/hcrypto.din > hcrypto.dxy.tmp + chmod +x hcrypto.dxy.tmp + mv hcrypto.dxy.tmp hcrypto.dxy + +vars.texi: vars.tin Makefile + $(texi_subst) < $(srcdir)/vars.tin > vars.texi.tmp + chmod +x vars.texi.tmp + mv vars.texi.tmp vars.texi + +doxygen: krb5.dxy ntlm.dxy hx509.dxy hcrypto.dxy + doxygen krb5.dxy + doxygen ntlm.dxy + doxygen hx509.dxy + doxygen hcrypto.dxy +# 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/doc/ack.texi b/doc/ack.texi new file mode 100644 index 000000000000..3c41f5000bc2 --- /dev/null +++ b/doc/ack.texi @@ -0,0 +1,72 @@ +@c $Id: ack.texi 21228 2007-06-20 10:18:03Z lha $ + +@node Acknowledgments, , Migration, Top +@comment node-name, next, previous, up +@appendix Acknowledgments + +Eric Young wrote ``libdes''. Heimdal used to use libdes, without it +kth-krb would never have existed. Since there are no longer any Eric +Young code left in the library, we renamed it to libhcrypto. + +All functions in libhcrypto have been re-implemented or used available +public domain code. The core AES function where written by Vincent +Rijmen, Antoon Bosselaers and Paulo Barreto. The core DES SBOX +transformation was written by Richard Outerbridge. @code{imath} that +is used for public key crypto support is written by Michael +J. Fromberger. + +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. + +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. Heimdal +contains a modifed copy. + +The @code{getifaddrs} implementation for Linux was written by Hideaki +YOSHIFUJI for the Usagi project. + +The @code{pkcs11.h} headerfile was written by the Scute project. + +Bugfixes, documentation, encouragement, and code has been contributed by: +@table @asis +@item Alexander Boström +@item Andreaw Bartlett +@item Björn Sandell +@item Brandon S. Allbery KF8NH +@item Brian A May +@item Chaskiel M Grundman +@item Cizzi Storm +@item Daniel Kouril +@item David Love +@item Derrick J Brashear +@item Douglas E Engert +@item Frank van der Linden +@item Jason McIntyre +@item Johan Ihrén +@item Jun-ichiro itojun Hagino +@item Ken Hornstein +@item Magnus Ahltorp +@item Marc Horowitz +@item Mario Strasser +@item Mark Eichin +@item Mattias Amnefelt +@item Michael B Allen +@item Michael Fromberger +@item Michal Vocu +@item Miroslav Ruda +@item Petr Holub +@item Phil Fisher +@item Rafal Malinowski +@item Richard Nyberg +@item Åke Sandgren +@item and we hope that those not mentioned here will forgive us. +@end table + +All bugs were introduced by ourselves. diff --git a/doc/apps.texi b/doc/apps.texi new file mode 100644 index 000000000000..9d451b60cd75 --- /dev/null +++ b/doc/apps.texi @@ -0,0 +1,244 @@ +@c $Id: apps.texi 22071 2007-11-14 20:04:50Z lha $ + +@node Applications, Things in search for a better place, Setting up a realm, Top + +@chapter Applications + +@menu +* Authentication modules:: +* AFS:: +@end menu + +@node Authentication modules, AFS, Applications, Applications +@section Authentication modules + +The problem of having different authentication mechanisms has been +recognised by several vendors, and several solutions have appeared. In +most cases these solutions involve some kind of shared modules that are +loaded at run-time. Modules for some of these systems can be found in +@file{lib/auth}. Presently there are modules for Digital's SIA, +and IRIX' @code{login} and @code{xdm} (in +@file{lib/auth/afskauthlib}). + +@menu +* Digital SIA:: +* IRIX:: +@end menu + +@node Digital SIA, IRIX, Authentication modules, Authentication modules +@subsection Digital SIA + +How to install the SIA module depends on which OS version you're +running. Tru64 5.0 has a new command, @file{siacfg}, which makes this +process quite simple. If you have this program, you should just be able +to run: +@example +siacfg -a KRB5 /usr/athena/lib/libsia_krb5.so +@end example + +On older versions, or if you want to do it by hand, you have to do the +following (not tested by us on Tru64 5.0): + +@itemize @bullet + +@item +Make sure @file{libsia_krb5.so} is available in +@file{/usr/athena/lib}. If @file{/usr/athena} is not on local disk, you +might want to put it in @file{/usr/shlib} or someplace else. If you do, +you'll have to edit @file{krb5_matrix.conf} to reflect the new location +(you will also have to do this if you installed in some other directory +than @file{/usr/athena}). If you built with shared libraries, you will +have to copy the shared @file{libkrb.so}, @file{libdes.so}, +@file{libkadm.so}, and @file{libkafs.so} to a place where the loader can +find them (such as @file{/usr/shlib}). +@item +Copy (your possibly edited) @file{krb5_matrix.conf} to @file{/etc/sia}. +@item +Apply @file{security.patch} to @file{/sbin/init.d/security}. +@item +Turn on KRB5 security by issuing @kbd{rcmgr set SECURITY KRB5} and +@kbd{rcmgr set KRB5_MATRIX_CONF krb5_matrix.conf}. +@item +Digital thinks you should reboot your machine, but that really shouldn't +be necessary. It's usually sufficient just to run +@kbd{/sbin/init.d/security start} (and restart any applications that use +SIA, like @code{xdm}.) +@end itemize + +Users with local passwords (like @samp{root}) should be able to login +safely. + +When using Digital's xdm the @samp{KRB5CCNAME} environment variable isn't +passed along as it should (since xdm zaps the environment). Instead you +have to set @samp{KRB5CCNAME} to the correct value in +@file{/usr/lib/X11/xdm/Xsession}. Add a line similar to +@example +KRB5CCNAME=FILE:/tmp/krb5cc`id -u`_`ps -o ppid= -p $$`; export KRB5CCNAME +@end example +If you use CDE, @code{dtlogin} allows you to specify which additional +environment variables it should export. To add @samp{KRB5CCNAME} to this +list, edit @file{/usr/dt/config/Xconfig}, and look for the definition of +@samp{exportList}. You want to add something like: +@example +Dtlogin.exportList: KRB5CCNAME +@end example + +@subsubheading Notes to users with Enhanced security + +Digital's @samp{ENHANCED} (C2) security, and Kerberos solve two +different problems. C2 deals with local security, adds better control of +who can do what, auditing, and similar things. Kerberos deals with +network security. + +To make C2 security work with Kerberos you will have to do the +following. + +@itemize @bullet +@item +Replace all occurrences of @file{krb5_matrix.conf} with +@file{krb5+c2_matrix.conf} in the directions above. +@item +You must enable ``vouching'' in the @samp{default} database. This will +make the OSFC2 module trust other SIA modules, so you can login without +giving your C2 password. To do this use @samp{edauth} to edit the +default entry @kbd{/usr/tcb/bin/edauth -dd default}, and add a +@samp{d_accept_alternate_vouching} capability, if not already present. +@item +For each user who does @emph{not} have a local C2 password, you should +set the password expiration field to zero. You can do this for each +user, or in the @samp{default} table. To do this use @samp{edauth} to +set (or change) the @samp{u_exp} capability to @samp{u_exp#0}. +@item +You also need to be aware that the shipped @file{login}, @file{rcp}, and +@file{rshd}, don't do any particular C2 magic (such as checking for +various forms of disabled accounts), so if you rely on those features, +you shouldn't use those programs. If you configure with +@samp{--enable-osfc2}, these programs will, however, set the login +UID. Still: use at your own risk. +@end itemize + +At present @samp{su} does not accept the vouching flag, so it will not +work as expected. + +Also, kerberised ftp will not work with C2 passwords. You can solve this +by using both Digital's ftpd and our on different ports. + +@strong{Remember}, if you do these changes you will get a system that +most certainly does @emph{not} fulfil the requirements of a C2 +system. If C2 is what you want, for instance if someone else is forcing +you to use it, you're out of luck. If you use enhanced security because +you want a system that is more secure than it would otherwise be, you +probably got an even more secure system. Passwords will not be sent in +the clear, for instance. + +@node IRIX, , Digital SIA, Authentication modules +@subsection IRIX + +The IRIX support is a module that is compatible with Transarc's +@file{afskauthlib.so}. It should work with all programs that use this +library. This should include @command{login} and @command{xdm}. + +The interface is not very documented but it seems that you have to copy +@file{libkafs.so}, @file{libkrb.so}, and @file{libdes.so} to +@file{/usr/lib}, or build your @file{afskauthlib.so} statically. + +The @file{afskauthlib.so} itself is able to reside in +@file{/usr/vice/etc}, @file{/usr/afsws/lib}, or the current directory +(wherever that is). + +IRIX 6.4 and newer seem to have all programs (including @command{xdm} and +@command{login}) in the N32 object format, whereas in older versions they +were O32. For it to work, the @file{afskauthlib.so} library has to be in +the same object format as the program that tries to load it. This might +require that you have to configure and build for O32 in addition to the +default N32. + +Apart from this it should ``just work''; there are no configuration +files. + +Note that recent Irix 6.5 versions (at least 6.5.22) have PAM, +including a @file{pam_krb5.so} module. Not all relevant programs use +PAM, though, e.g.@: @command{ssh}. In particular, for console +graphical login you need to turn off @samp{visuallogin} and turn on +@samp{xdm} with @command{chkconfig}. + +@node AFS, , Authentication modules, Applications +@section AFS + +@cindex AFS +AFS is a distributed filesystem that uses Kerberos for authentication. + +@cindex OpenAFS +@cindex Arla +For more information about AFS see OpenAFS +@url{http://www.openafs.org/} and Arla +@url{http://www.stacken.kth.se/projekt/arla/}. + +@subsection How to get a KeyFile + +@file{ktutil -k AFSKEYFILE:KeyFile get afs@@MY.REALM} + +or you can extract it with kadmin + +@example +kadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@@My.CELL.NAME +@end example + +You have to make sure you have a @code{des-cbc-md5} encryption type since that +is the enctype that will be converted. + +@subsection How to convert a srvtab to a KeyFile + +You need a @file{/usr/vice/etc/ThisCell} containing the cellname of your +AFS-cell. + +@file{ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile}. + +If keyfile already exists, this will add the new key in afs-srvtab to +KeyFile. + +@section Using 2b tokens with AFS + +@subsection What is 2b ? + +2b is the name of the proposal that was implemented to give basic +Kerberos 5 support to AFS in rxkad. It's not real Kerberos 5 support +since it still uses fcrypt for data encryption and not Kerberos +encryption types. + +Its only possible (in all cases) to do this for DES encryption types +because only then the token (the AFS equivalent of a ticket) will be +smaller than the maximum size that can fit in the token cache in the +OpenAFS/Transarc client. It is a so tight fit that some extra wrapping +on the ASN1/DER encoding is removed from the Kerberos ticket. + +2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for +the part of the ticket that is encrypted with the service's key. The +client doesn't know what's inside the encrypted data so to the client +it doesn't matter. + +To differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b +uses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens. + +Its a requirement that all AFS servers that support 2b also support +native Kerberos 5 in rxkad. + +@subsection Configuring a Heimdal kdc to use 2b tokens + +Support for 2b tokens in the kdc are turned on for specific principals +by adding them to the string list option @code{[kdc]use_2b} in the +kdc's @file{krb5.conf} file. + +@example +[kdc] + use_2b = @{ + afs@@SU.SE = yes + afs/it.su.se@@SU.SE = yes + @} +@end example + +@subsection Configuring AFS clients for 2b support + +There is no need to configure AFS clients for 2b support. The only +software that needs to be installed/upgrade is a Kerberos 5 enabled +@file{afslog}. diff --git a/doc/doxytmpl.dxy b/doc/doxytmpl.dxy new file mode 100644 index 000000000000..bb7f25cb85e1 --- /dev/null +++ b/doc/doxytmpl.dxy @@ -0,0 +1,257 @@ +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class " \ + "The $name widget " \ + "The $name file " \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = /Applications/ +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_FORMAT = "$file:$line: $text " +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = */.svn +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +USE_HTAGS = NO +VERBATIM_HEADERS = NO +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = NO +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = YES +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +MSCGEN_PATH = /Applications/Doxygen.app/Contents/Resources/ +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = YES +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = /Applications/Doxygen.app/Contents/Resources/ +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 1000 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/hcrypto.din b/doc/hcrypto.din new file mode 100644 index 000000000000..55f1ed7c6ae3 --- /dev/null +++ b/doc/hcrypto.din @@ -0,0 +1,15 @@ +# Doxyfile 1.5.3 + +PROJECT_NAME = "Heimdal crypto library" +PROJECT_NUMBER = @PACKAGE_VERSION@ +OUTPUT_DIRECTORY = @objdir@/hcrypto +INPUT = @srcdir@/../lib/hcrypto + +WARN_IF_UNDOCUMENTED = YES + +PERL_PATH = /usr/bin/perl + +HTML_HEADER = "@srcdir@/header.html" +HTML_FOOTER = "@srcdir@/footer.html" + +@INCLUDE = "@srcdir@/doxytmpl.dxy" diff --git a/doc/heimdal.css b/doc/heimdal.css new file mode 100644 index 000000000000..2e5b374f1f87 --- /dev/null +++ b/doc/heimdal.css @@ -0,0 +1,53 @@ +body { + color: black; + background-color: #fdfdfd; + font-family: serif; + max-width: 40em; +} +h1, h2, h3 { + font-family: sans-serif; + font-weight: bold; +} +h1 { + padding: 0.5em 0 0.5em 5%; + color: white; + background: #3366cc; + border-bottom: solid 1px black; +} +h1 { + font-size: 200%; +} +h2 { + font-size: 150%; +} +h3 { + font-size: 120%; +} +h4 { + font-weight: bold; +} +pre.example { + margin-left: 2em; + padding: 1em 0em; + border: 2px dashed #c0c0c0; + background: #f0f0f0; +} +a:link { + color: blue; + text-decoration: none; +} +a:visited { + color: red; + text-decoration: none +} +a:hover { + text-decoration: underline +} +span.literal { + font-family: monospace; +} +hr { + border-style: none; + background-color: black; + height: 1px; +} diff --git a/doc/heimdal.texi b/doc/heimdal.texi new file mode 100644 index 000000000000..1b999d30108f --- /dev/null +++ b/doc/heimdal.texi @@ -0,0 +1,370 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@c $Id: heimdal.texi 22191 2007-12-06 17:26:30Z lha $ +@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 + +@include vars.texi + +@set UPDATED $Date: 2007-12-06 09:26:30 -0800 (Tor, 06 Dec 2007) $ +@set VERSION @value{PACKAGE_VERSION} +@set EDITION 1.0 + +@ifinfo +@dircategory Security +@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 2007 +@author Johan Danielsson +@author Love Hörnquist Åstrand +@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-2007 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) 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. 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. + +@copynext + +IMath is Copyright 2002-2005 Michael J. Fromberger +You may use it subject to the following Licensing Terms: + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +@copynext + +Copyright (c) 2005 Doug Rabson +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. + +THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 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) 2005 Marko Kreen +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. + +THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 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) 2006,2007 +NTT (Nippon Telegraph and Telephone Corporation) . 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 as + the first lines of this file unmodified. +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. + +THIS SOFTWARE IS PROVIDED BY NTT ``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 NTT 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. + +@copyrightend +@end titlepage + +@macro manpage{man, section} +@cite{\man\(\section\)} +@end macro + +@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 + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Heimdal +@end ifnottex + +This manual is last updated @value{UPDATED} for version +@value{VERSION} of Heimdal. + +@menu +* Introduction:: +* What is Kerberos?:: +* Building and Installing:: +* Setting up a realm:: +* Applications:: +* Things in search for a better place:: +* Kerberos 4 issues:: +* Windows 2000 compatability:: +* Programming with Kerberos:: +* Migration:: +* Acknowledgments:: + +@detailmenu + --- The Detailed Node Listing --- + +Setting up a realm + +* Configuration file:: +* Creating the database:: +* Modifying the database:: +* keytabs:: +* Serving Kerberos 4/524/kaserver:: +* Remote administration:: +* Password changing:: +* Testing clients and servers:: +* Slave Servers:: +* Incremental propagation:: +* Encryption types and salting:: +* Cross realm:: +* Transit policy:: +* Setting up DNS:: +* Using LDAP to store the database:: +* Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: + +Applications + +* Authentication modules:: +* AFS:: + +Authentication modules + +* Digital SIA:: +* IRIX:: + +Kerberos 4 issues + +* Principal conversion issues:: +* Converting a version 4 database:: +* kaserver:: + +Windows 2000 compatability + +* Configuring Windows 2000 to use a Heimdal KDC:: +* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: +* Create account mappings:: +* Encryption types:: +* Authorisation data:: +* Quirks of Windows 2000 KDC:: +* Useful links when reading about the Windows 2000:: + +Programming with Kerberos + +* Kerberos 5 API Overview:: +* Walkthrough of a sample Kerberos 5 client:: +* Validating a password in a server application:: +* API differences to MIT Kerberos:: +* File formats:: + +@end detailmenu +@end menu + +@include intro.texi +@include whatis.texi +@include install.texi +@include setup.texi +@include apps.texi +@include misc.texi +@include kerberos4.texi +@include win2k.texi +@include programming.texi +@include migration.texi +@include ack.texi + +@c @shortcontents +@contents + +@bye diff --git a/doc/hx509.din b/doc/hx509.din new file mode 100644 index 000000000000..e28429f383bd --- /dev/null +++ b/doc/hx509.din @@ -0,0 +1,15 @@ +# Doxyfile 1.5.3 + +PROJECT_NAME = Heimdal x509 library +PROJECT_NUMBER = @PACKAGE_VERSION@ +OUTPUT_DIRECTORY = @objdir@/hx509 +INPUT = @srcdir@/../lib/hx509 + +WARN_IF_UNDOCUMENTED = YES + +PERL_PATH = /usr/bin/perl + +HTML_HEADER = "@srcdir@/header.html" +HTML_FOOTER = "@srcdir@/footer.html" + +@INCLUDE = "@srcdir@/doxytmpl.dxy" diff --git a/doc/hx509.texi b/doc/hx509.texi new file mode 100644 index 000000000000..dbb5261ef938 --- /dev/null +++ b/doc/hx509.texi @@ -0,0 +1,633 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@c $Id: hx509.texi 22071 2007-11-14 20:04:50Z lha $ +@setfilename hx509.info +@settitle HX509 +@iftex +@afourpaper +@end iftex +@c some sensible characters, please? +@tex +\input latin1.tex +@end tex +@setchapternewpage on +@syncodeindex pg cp +@c %**end of header + +@set UPDATED $Date: 2007-11-14 12:04:50 -0800 (Ons, 14 Nov 2007) $ +@set VERSION 1.0 +@set EDITION 1.0 + +@ifinfo +@dircategory Security +@direntry +* hx509: (hx509). The X.509 distribution from KTH +@end direntry +@end ifinfo + +@c title page +@titlepage +@title HX509 +@subtitle X.509 distribution from KTH +@subtitle Edition @value{EDITION}, for version @value{VERSION} +@subtitle 2007 +@author Love Hörnquist Åstrand +@author last updated @value{UPDATED} + +@def@copynext{@vskip 20pt plus 1fil@penalty-1000} +@def@copyrightstart{} +@def@copyrightend{} +@page +@copyrightstart +Copyright (c) 1994-2007 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) 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. 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. + +@copynext + +IMath is Copyright 2002-2005 Michael J. Fromberger +You may use it subject to the following Licensing Terms: + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +@copyrightend +@end titlepage + +@macro manpage{man, section} +@cite{\man\(\section\)} +@end macro + +@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 + +@ifnottex +@node Top, Introduction, (dir), (dir) +@top Heimdal +@end ifnottex + +This manual is last updated @value{UPDATED} for version +@value{VERSION} of hx509. + +@menu +* Introduction:: +* What is X.509 ?:: +* Setting up a CA:: +* CMS signing and encryption:: + +@detailmenu + --- The Detailed Node Listing --- + +Setting up a CA + +@c * Issuing certificates:: +* Creating a CA certificate:: +* Issuing certificates:: +* Issuing CRLs:: +@c * Issuing a proxy certificate:: +@c * Creating a user certificate:: +@c * Validating a certificate:: +@c * Validating a certificate path:: +* Application requirements:: + +CMS signing and encryption + +* CMS background:: + +@end detailmenu +@end menu + +@node Introduction, What is X.509 ?, Top, Top +@chapter Introduction + +hx509 is a somewhat complete X.509 stack that can handle CMS messages +(crypto system used in S/MIME and Kerberos PK-INIT) and basic +certificate processing tasks, path construction, path validation, OCSP +and CRL validation, PKCS10 message construction, CMS Encrypted (shared +secret encrypted), CMS SignedData (certificate signed), and CMS +EnvelopedData (certificate encrypted). + +hx509 can use PKCS11 tokens, PKCS12 files, PEM files, DER encoded files. + +@node What is X.509 ?, Setting up a CA, Introduction, Top +@chapter What is X.509, PKIX, PKCS7 and CMS ? + +X.509 is from the beginning created by CCITT (later ITU) for the X.500 +directory service. But today when people are talking about X.509 they +are commonly referring to IETF's PKIX Certificate and CRL Profile of the +X.509 v3 certificate standard, as specified in RFC 3280. + +ITU continues to develop the X.509 standard together in a complicated +dance with IETF. + +X.509 is public key based security system that have associated data +stored within a so called certificate. From the beginning X.509 was a +strict hierarchical system with one root. This didn't not work so over +time X.509 got support for multiple policy roots, bridges, and mesh +solutions. You can even use it as a peer to peer system, but this is not +very common. + +@section Type of certificates + +There are several flavors of certificate in X.509. + +@itemize @bullet + +@item Trust anchors + +Trust anchors are strictly not certificate, but commonly stored in +certificate since they are easier to handle then. Trust anchor are the +keys that you trust to validate other certificate. This is done by +building a path from the certificate you wan to validate to to any of +the trust anchors you have. + +@item End Entity (EE) certificates + +End entity certificates is the most common type of certificate. End +entity certificates can't issue certificate them-self and is used to +authenticate and authorize user and services. + +@item Certification Authority (CA) certificates + +Certificate authority are certificates that have the right to issue +other certificate, they may be End entity certificates or Certificate +Authority certificates. There is no limit to how many certificates a CA +may issue, but there might other restrictions, like the maximum path +depth. + +@item Proxy certificates + +Remember that End Entity can't issue certificates by them own, it's not +really true. There there is an extension called proxy certificates, +defined in RFC3820, that allows certificates to be issued by end entity +certificates. The service that receives the proxy certificates must have +explicitly turned on support for proxy certificates, so their use is +somewhat limited. + +Proxy certificates can be limited by policy stored in the certificate to +what they can be used for. This allows users to delegate the proxy +certificate to services (by sending over the certificate and private +key) so the service can access services on behalf of the user. + +One example of this would be a print service. The user wants to print a +large job in the middle of the night when the printer isn't used that +much, so the user creates a proxy certificate with the policy that it +can only be used to access files related to this print job, creates the +print job description and send both the description and proxy +certificate with key over to print service. Later at night will the +print service, without the help of the user, access the files for the +the print job using the proxy certificate and print the job. Because of +the policy (limitation) in the proxy certificate, it can't be used for +any other purposes. + +@end itemize + +@section Building a path + +Before validating a path the path must be constructed. Given a +certificate (EE, CA, Proxy, or any other type), the path construction +algorithm will try to find a path to one of the trust anchors. + +It start with looking at whom issued the certificate, by name or Key +Identifier, and tries to find that certificate while at the same time +evaluates the policy. + +@node Setting up a CA, Creating a CA certificate, What is X.509 ?, Top +@chapter Setting up a CA + +Do not let this chapter scare you off, it's just to give you an idea how +to complicated setting up a CA can be. If you are just playing around, +skip all this and go to the next chapter, @pxref{Creating a CA +certificate}. + +Creating a CA certificate should be more the just creating a +certificate, there is the policy of the CA. If it's just you and your +friend that is playing around then it probably doesn't matter what the +policy is. But then it comes to trust in an organisation, it will +probably matter more whom your users and sysadmins will find it +acceptable to trust. + +At the same time, try to keep thing simple, it's not very hard to run a +Certificate authority and the process to get new certificates should +simple. + +Fill all this in later. + +How do you trust your CA. + +What is the CA responsibility. + +Review of CA activity. + +How much process should it be to issue certificate. + +Who is allowed to issue certificates. + +Who is allowed to requests certificates. + +How to handle certificate revocation, issuing CRLs and maintain OCSP +services. + +@node Creating a CA certificate, Issuing certificates, Setting up a CA, Top +@section Creating a CA certificate + +This section describes how to create a CA certificate and what to think +about. + +@subsection Lifetime CA certificate + +You probably want to create a CA certificate with a long lifetime, 10 +years at the shortest. This because you don't want to push out the +certificate (as a trust anchor) to all you users once again when the old +one just expired. A trust anchor can't really expire, but not all +software works that way. + +Keep in mind the security requirements might be different 10-20 years +into the future. For example, SHA1 is going to be withdrawn in 2010, so +make sure you have enough buffering in your choice of digest/hash +algorithms, signature algorithms and key lengths. + +@subsection Create a CA certificate + +This command below will create a CA certificate in the file ca.pem. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CertificateAuthority,DC=test,DC=h5l,DC=se" \ + --lifetime=10years \ + --certificate="FILE:ca.pem" +@end example + +@subsection Extending lifetime of a CA certificate + +You just realised that your CA certificate is going to expire soon and +that you need replace it with something else, the easiest way to do that +is to extend the lifetime of your CA certificate. + +The example below will extend the CA certificate 10 years into the +future. You should compare this new certificate if it contains all the +special tweaks as the old certificate had. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --lifetime="10years" \ + --template-certificate="FILE:ca.pem" \ + --template-fields="serialNumber,notBefore,subject,SPKI" \ + --ca-private-key=FILE:ca.pem \ + --certificate="FILE:new-ca.pem" +@end example + +@subsection Subordinate CA + +This example create a new subordinate certificate authority. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CertificateAuthority,DC=dev,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:dev-ca.pem" +@end example + + +@node Issuing certificates, Issuing CRLs, Creating a CA certificate, Top +@section Issuing certificates + +First you'll create a CA certificate, after that you have to deal with +your users and servers and issue certificate to them. + +CA can generate the key for the user. + +Can receive PKCS10 certificate requests from the users. PKCS10 is a +request for a certificate. The user can specified what DN the user wants +and what public key. To prove the user have the key, the whole request +is signed by the private key of the user. + +@subsection Name space management + +What people might want to see. + +Re-issue certificates just because people moved within the organization. + +Expose privacy information. + +Using Sub-component name (+ notation). + +@subsection Certificate Revocation, CRL and OCSP + +Sonetimes people loose smartcard or computers and certificates have to +be make not valid any more, this is called revoking certificates. There +are two main protocols for doing this Certificate Revocations Lists +(CRL) and Online Certificate Status Protocol (OCSP). + +If you know that the certificate is destroyed then there is no need to +revoke the certificate because it can not be used by someone else. + +The main reason you as a CA administrator have to deal with CRLs however +will be that some software require there to be CRLs. Example of this is +Windows, so you have to deal with this somehow. + +@node Issuing CRLs, Application requirements, Issuing certificates, Top +@section Issuing CRLs + +Create an empty CRL with not certificates revoked. Default expiration +value is one year from now. + +@example +hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem +@end example + +Create a CRL with all certificates in the directory +@file{/path/to/revoked/dir} included in the CRL as revoked. Also make +it expire one month from now. + +@example +hxtool crl-sign \ + --crl-file=crl.der \ + --signer=FILE:ca.pem \ + --lifetime='1 month' \ + DIR:/path/to/revoked/dir +@end example + +@node Application requirements, CMS signing and encryption, Issuing CRLs, Top +@section Application requirements + +Application have different requirements on certificates. This section +tries to expand what they are and how to use hxtool to generate +certificates for those services. + +@subsection HTTPS - server + +@example +hxtool issue-certificate \ + --subject="CN=www.test.h5l.se,DC=test,DC=h5l,DC=se" \ + --type="https-server" \ + --hostname="www.test.h5l.se" \ + --hostname="www2.test.h5l.se" \ + ... +@end example + +@subsection HTTPS - client + +@example +hxtool issue-certificate \ + --subject="UID=testus,DC=test,DC=h5l,DC=se" \ + --type="https-client" \ + ... +@end example + +@subsection S/MIME - email + +There are two things that should be set in S/MIME certificates, one or +more email addresses and an extended eku usage (EKU), emailProtection. + +The email address format used in S/MIME certificates is defined in +RFC2822, section 3.4.1 and it should be an ``addr-spec''. + +There are two ways to specifify email address in certificates. The old +ways is in the subject distinguished name, this should not be used. The +new way is using a Subject Alternative Name (SAN). + +But even though email address is stored in certificates, they don't need +to, email reader programs are required to accept certificates that +doesn't have either of the two methods of storing email in certificates. +In that case, they try to protect the user by printing the name of the +certificate instead. + +S/MIME certificate can be used in another special way. They can be +issued with a NULL subject distinguished name plus the email in SAN, +this is a valid certificate. This is used when you wont want to share +more information then you need to. + +hx509 issue-certificate supports adding the email SAN to certificate by +using the --email option, --email also gives an implicit emailProtection +eku. If you want to create an certificate without an email address, the +option --type=email will add the emailProtection EKU. + +@example +hxtool issue-certificate \ + --subject="UID=testus-email,DC=test,DC=h5l,DC=se" \ + --type=email \ + --email="testus@@test.h5l.se" \ + ... +@end example + +An example of an certificate without and subject distinguished name with +an email address in a SAN. + +@example +hxtool issue-certificate \ + --subject="" \ + --type=email \ + --email="testus@@test.h5l.se" \ + ... +@end example + +@subsection PK-INIT + +How to create a certificate for a KDC. + +@example +hxtool issue-certificate \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ + --hostname kerberos.test.h5l.se \ + --hostname pal.test.h5l.se \ + ... +@end example + +How to create a certificate for a user. + +@example +hxtool issue-certificate \ + --type="pkinit-client" \ + --pk-init-principal="user@@TEST.H5L.SE" \ + ... +@end example + +@subsection XMPP/Jabber + +The jabber server certificate should have a dNSname that is the same as +the user entered into the application, not the same as the host name of +the machine. + +@example +hxtool issue-certificate \ + --subject="CN=xmpp1.test.h5l.se,DC=test,DC=h5l,DC=se" \ + --hostname="xmpp1.test.h5l.se" \ + --hostname="test.h5l.se" \ + ... +@end example + +The certificate may also contain a jabber identifier (JID) that, if the +receiver allows it, authorises the server or client to use that JID. + +When storing a JID inside the certificate, both for server and client, +it's stored inside a UTF8String within an otherName entity inside the +subjectAltName, using the OID id-on-xmppAddr (1.3.6.1.5.5.7.8.5). + +To read more about the requirements, see RFC3920, Extensible Messaging +and Presence Protocol (XMPP): Core. + +hxtool issue-certificate have support to add jid to the certificate +using the option @kbd{--jid}. + +@example +hxtool issue-certificate \ + --subject="CN=Love,DC=test,DC=h5l,DC=se" \ + --jid="lha@@test.h5l.se" \ + ... +@end example + + +@node CMS signing and encryption, CMS background, Application requirements, Top +@chapter CMS signing and encryption + +CMS is the Cryptographic Message System that among other, is used by +S/MIME (secure email) and Kerberos PK-INIT. It's an extended version of +the RSA, Inc standard PKCS7. + +@node CMS background, , CMS signing and encryption, Top +@section CMS background + + +@c @shortcontents +@contents + +@bye diff --git a/doc/init-creds b/doc/init-creds new file mode 100644 index 000000000000..8892d29ff40e --- /dev/null +++ b/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 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/doc/install.texi b/doc/install.texi new file mode 100644 index 000000000000..3d4b78d1c4ea --- /dev/null +++ b/doc/install.texi @@ -0,0 +1,107 @@ +@c $Id: install.texi 16768 2006-02-27 12:26:49Z joda $ + +@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 behaviour, 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 found if present under +@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-dce} +Enables support for getting DCE credentials and tokens. See the README +files in @file{appl/dceutils} for more information. + +@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. + +@item @kbd{--with-openldap} +Compile Heimdal with support for storing the database in LDAP. Requires +OpenLDAP @url{http://www.openldap.org}. See +@url{http://www.padl.com/Research/Heimdal.html} for more information. + +@item @kbd{--enable-bigendian} +@item @kbd{--enable-littleendian} +Normally, the build process will figure out by itself if the machine is +big or little endian. It might fail in some cases when +cross-compiling. If it does fail to figure it out, use the relevant of +these two options. + +@item @kbd{--with-mips-abi=@var{abi}} +On Irix there are three different ABIs that can be used (@samp{32}, +@samp{n32}, or @samp{64}). This option allows you to override the +automatic selection. + +@item @kbd{--disable-mmap} +Do not use the mmap system call. Normally, configure detects if there +is a working mmap and it is only used if there is one. Only try this +option if it fails to work anyhow. + +@end table diff --git a/doc/intro.texi b/doc/intro.texi new file mode 100644 index 000000000000..e1a96e12057a --- /dev/null +++ b/doc/intro.texi @@ -0,0 +1,99 @@ +@c $Id: intro.texi 22509 2008-01-23 18:28:01Z lha $ + +@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 4120 (and any future updated RFC). RFC 4120 +replaced RFC 1510. +@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 +@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@@h5l.org}. 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. + +@heading Heimdal source code, binaries and the manual + +The source code for heimdal, links to binaries and the manual (this +document) can be found on our web-page at +@url{http://www.pdc.kth.se/heimdal/}. diff --git a/doc/kerberos4.texi b/doc/kerberos4.texi new file mode 100644 index 000000000000..fb490f372e86 --- /dev/null +++ b/doc/kerberos4.texi @@ -0,0 +1,226 @@ +@c $Id: kerberos4.texi 16370 2005-12-12 12:11:51Z lha $ + +@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 + +The KDC has built-in version 4 support. It is not enabled by default, +see setup how to set it up. + +The KDC will also have kaserver emulation and be able to handle +AFS-clients that use @code{klog}. + +@menu +* Principal conversion issues:: +* Converting a version 4 database:: +* kaserver:: +@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, kaserver , 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}. 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 --source=krb4-db --master-key=/.m slave-server +@end example + +This command can also be to use for converting the v4 database on the +server: + +@example +hprop -n --source=krb4-db -d /var/kerberos/principal --master-key=/.m | hpropd -n +@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 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.} + +@node kaserver, , Converting a version 4 database, Kerberos 4 issues +@section kaserver + +@subsection kaserver emulation + +The Heimdal kdc can emulate a kaserver. The kaserver is a Kerberos 4 +server with pre-authentication using Rx as the on-wire protocol. The kdc +contains a minimalistic Rx implementation. + +There are three parts of the kaserver; KAA (Authentication), KAT (Ticket +Granting), and KAM (Maintenance). The KAA interface and KAT interface +both passes over DES encrypted data-blobs (just like the +Kerberos-protocol) and thus do not need any other protection. The KAM +interface uses @code{rxkad} (Kerberos authentication layer for Rx) for +security and data protection, and is used for example for changing +passwords. This part is not implemented in the kdc. + +Another difference between the ka-protocol and the Kerberos 4 protocol +is that the pass-phrase is salted with the cellname in the @code{string to +key} function in the ka-protocol, while in the Kerberos 4 protocol there +is no salting of the password at all. To make sure AFS-compatible keys +are added to each principals when they are created or their password are +changed, @samp{afs3-salt} should be added to +@samp{[kadmin]default_keys}. + +@subsection Transarc AFS Windows client + +The Transarc Windows client uses Kerberos 4 to obtain tokens, and thus +does not need a kaserver. The Windows client assumes that the Kerberos +server is on the same machine as the AFS-database server. If you do not +like to do that you can add a small program that runs on the database +servers that forward all kerberos requests to the real kerberos +server. A program that does this is @code{krb-forward} +(@url{ftp://ftp.stacken.kth.se/pub/projekts/krb-forward}). diff --git a/doc/krb5.din b/doc/krb5.din new file mode 100644 index 000000000000..2af99473ebb3 --- /dev/null +++ b/doc/krb5.din @@ -0,0 +1,16 @@ +# Doxyfile 1.5.3 + +PROJECT_NAME = Heimdal Kerberos 5 library +PROJECT_NUMBER = @PACKAGE_VERSION@ +OUTPUT_DIRECTORY = @objdir@/krb5 +INPUT = @srcdir@/../lib/krb5 + +WARN_IF_UNDOCUMENTED = NO + +PERL_PATH = /usr/bin/perl + +HTML_HEADER = "@srcdir@/header.html" +HTML_FOOTER = "@srcdir@/footer.html" + +@INCLUDE = "@srcdir@/doxytmpl.dxy" + diff --git a/doc/latin1.tex b/doc/latin1.tex new file mode 100644 index 000000000000..e683dd271dc1 --- /dev/null +++ b/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/doc/layman.asc b/doc/layman.asc new file mode 100644 index 000000000000..d4fbe64be99d --- /dev/null +++ b/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/doc/mdate-sh b/doc/mdate-sh new file mode 100755 index 000000000000..37171f21fbd9 --- /dev/null +++ b/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/doc/migration.texi b/doc/migration.texi new file mode 100644 index 000000000000..586d48814939 --- /dev/null +++ b/doc/migration.texi @@ -0,0 +1,43 @@ +@c $Id: migration.texi 9718 2001-02-24 05:09:24Z assar $ + +@node Migration, Acknowledgments, Programming with Kerberos, Top +@chapter Migration + +@section General issues + +When migrating from a Kerberos 4 KDC. + +@section Order in what to do things: + +@itemize @bullet + +@item Convert the database, check all principals that hprop complains +about. + +@samp{hprop -n --source=<NNN>| hpropd -n} + +Replace <NNN> with whatever source you have, like krb4-db or krb4-dump. + +@item Run a Kerberos 5 slave for a while. + +@c XXX Add you slave first to your kdc list in you kdc. + +@item Figure out if it does everything you want it to. + +Make sure that all things that you use works for you. + +@item Let a small number of controlled users use Kerberos 5 tools. + +Find a sample population of your users and check what programs they use, +you can also check the kdc-log to check what ticket are checked out. + +@item Burn the bridge and change the master. +@item Let all users use the Kerberos 5 tools by default. +@item Turn off services that do not need Kerberos 4 authentication. + +Things that might be hard to get away is old programs with support for +Kerberos 4. Example applications are old Eudora installations using +KPOP, and Zephyr. Eudora can use the Kerberos 4 kerberos in the Heimdal +kdc. + +@end itemize diff --git a/doc/misc.texi b/doc/misc.texi new file mode 100644 index 000000000000..ea2260996b3c --- /dev/null +++ b/doc/misc.texi @@ -0,0 +1,58 @@ +@c $Id: misc.texi 12197 2003-05-04 13:32:37Z lha $ + +@node Things in search for a better place, Kerberos 4 issues, Applications, 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 by having the router get a ticket when +you login (boring), and by using 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 when logging in, the router +should try to authenticate with kerberised telnet, and if that fails try +to verify a plain text password via a Kerberos ticket exchange (as +opposed to a local database, 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 at all. The `instance map' and `authorization exec' lines +says that people with `admin' instances should be given `enabled' shells +when logging in. + +The numbers after the principal on the `srvtab' line are principal type, +time stamp (in seconds since 1970), key version number (4), keytype (1 == +des), key length (always 8 with des), and then the key. + +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}. This can be done with the @samp{del_enctype} +command of @samp{kadmin}. + +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/doc/ntlm.din b/doc/ntlm.din new file mode 100644 index 000000000000..bbf1087a5db8 --- /dev/null +++ b/doc/ntlm.din @@ -0,0 +1,15 @@ +# Doxyfile 1.5.3 + +PROJECT_NAME = Heimdal ntlm library +PROJECT_NUMBER = @PACKAGE_VERSION@ +OUTPUT_DIRECTORY = @objdir@/ntlm +INPUT = @srcdir@/../lib/ntlm + +WARN_IF_UNDOCUMENTED = YES + +PERL_PATH = /usr/bin/perl + +HTML_HEADER = "@srcdir@/header.html" +HTML_FOOTER = "@srcdir@/footer.html" + +@INCLUDE = "@srcdir@/doxytmpl.dxy" diff --git a/doc/programming.texi b/doc/programming.texi new file mode 100644 index 000000000000..528348bdaaa6 --- /dev/null +++ b/doc/programming.texi @@ -0,0 +1,642 @@ +@c $Id: programming.texi 22071 2007-11-14 20:04:50Z lha $ + +@node Programming with Kerberos, Migration, Windows 2000 compatability, Top +@chapter Programming with Kerberos + +First you need to know how the Kerberos model works, go read the +introduction text (@pxref{What is Kerberos?}). + +@menu +* Kerberos 5 API Overview:: +* Walkthrough of a sample Kerberos 5 client:: +* Validating a password in a server application:: +* API differences to MIT Kerberos:: +* File formats:: +@end menu + +@node Kerberos 5 API Overview, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos +@section Kerberos 5 API Overview + +All functions are documented in manual pages. This section tries to +give an overview of the major components used in Kerberos library, and +point to where to look for a specific function. + +@subsection Kerberos context + +A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that +are context specific are stored in this structure, including default +encryption types, credential cache (for example, a ticket file), and default realms. + +See the manual pages for @manpage{krb5_context,3} and +@manpage{krb5_init_context,3}. + +@subsection Kerberos authentication context + +Kerberos authentication context (@code{krb5_auth_context}) holds all +context related to an authenticated connection, in a similar way to the +kerberos context that holds the context for the thread or process. + +The @code{krb5_auth_context} is used by various functions that are +directly related to authentication between the server/client. Example of +data that this structure contains are various flags, addresses of client +and server, port numbers, keyblocks (and subkeys), sequence numbers, +replay cache, and checksum types. + +See the manual page for @manpage{krb5_auth_context,3}. + +@subsection Kerberos principal + +The Kerberos principal is the structure that identifies a user or +service in Kerberos. The structure that holds the principal is the +@code{krb5_principal}. There are function to extract the realm and +elements of the principal, but most applications have no reason to +inspect the content of the structure. + +The are several ways to create a principal (with different degree of +portability), and one way to free it. + +See manual page for @manpage{krb5_principal,3} for more information +about the functions. + +@subsection Credential cache + +A credential cache holds the tickets for a user. A given user can have +several credential caches, one for each realm where the user have the +initial tickets (the first krbtgt). + +The credential cache data can be stored internally in different way, each of them for +different proposes. File credential (FILE) caches and processes based +(KCM) caches are for permanent storage. While memory caches (MEMORY) +are local caches to the local process. + +Caches are opened with @manpage{krb5_cc_resolve,3} or created with +@manpage{krb5_cc_gen_unique,3}. + +If the cache needs to be opened again (using +@manpage{krb5_cc_resolve,3}) @manpage{krb5_cc_close,3} will close the +handle, but not the remove the cache. @manpage{krb5_cc_destroy,3} will +zero out the cache, remove the cache so it can no longer be +referenced. + +See also manual page for @manpage{krb5_ccache,3} + +@subsection Kerberos errors + +Kerberos errors are based on the com_err library. All error codes are +32-bit signed numbers, the first 24 bits define what subsystem the +error originates from, and last 8 bits are 255 error codes within the +library. Each error code have fixed string associated with it. For +example, the error-code -1765328383 have the symbolic name +KRB5KDC_ERR_NAME_EXP, and associated error string ``Client's entry in +database has expired''. + +This is a great improvement compared to just getting one of the unix +error-codes back. However, Heimdal have an extention to pass back +customised errors messages. Instead of getting ``Key table entry not +found'', the user might back ``failed to find +host/host.example.com@@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab +(des-cbc-crc)''. This improves the chance that the user find the +cause of the error so you should use the customised error message +whenever it's available. + +See also manual page for @manpage{krb5_get_error_string,3} and +@manpage{krb5_get_err_text,3}. + +@subsection Keytab management + +A keytab is a storage for locally stored keys. Heimdal includes keytab +support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's, +and for storing keys in memory. + +Keytabs are used for servers and long-running services. + +See also manual page for @manpage{krb5_keytab,3} + +@subsection Kerberos crypto + +Heimdal includes a implementation of the Kerberos crypto framework, +all crypto operations. + +See also manual page for @manpage{krb5_crypto_init,3}, +@manpage{krb5_keyblock,3}, @manpage{krb5_create_checksum,3}, +and @manpage{krb5_encrypt,3}. + +@node Walkthrough of a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos +@section Walkthrough of a sample Kerberos 5 client + +This example contains parts of a sample TCP Kerberos 5 clients, if you +want a real working client, please look in @file{appl/test} directory in +the Heimdal distribution. + +All Kerberos error-codes that are returned from kerberos functions in +this program are passed to @code{krb5_err}, that will print a +descriptive text of the error code and exit. Graphical programs can +convert error-code to a human readable error-string with the +@manpage{krb5_get_err_text,3} function. + +Note that you should not use any Kerberos function before +@code{krb5_init_context()} have completed successfully. That is the +reason @code{err()} is used when @code{krb5_init_context()} fails. + +First the client needs to call @code{krb5_init_context} to initialise +the Kerberos 5 library. This is only needed once per thread +in the program. If the function returns a non-zero value it indicates +that either the Kerberos implementation is failing or it's disabled on +this host. + +@example +#include <krb5.h> + +int +main(int argc, char **argv) +@{ + krb5_context context; + + if (krb5_context(&context)) + errx (1, "krb5_context"); +@end example + +Now the client wants to connect to the host at the other end. The +preferred way of doing this is using @manpage{getaddrinfo,3} (for +operating system that have this function implemented), since getaddrinfo +is neutral to the address type and can use any protocol that is available. + +@example + struct addrinfo *ai, *a; + struct addrinfo hints; + int error; + + memset (&hints, 0, sizeof(hints)); + hints.ai_socktype = SOCK_STREAM; + hints.ai_protocol = IPPROTO_TCP; + + error = getaddrinfo (hostname, "pop3", &hints, &ai); + if (error) + errx (1, "%s: %s", hostname, gai_strerror(error)); + + for (a = ai; a != NULL; a = a->ai_next) @{ + int s; + + s = socket (a->ai_family, a->ai_socktype, a->ai_protocol); + if (s < 0) + continue; + if (connect (s, a->ai_addr, a->ai_addrlen) < 0) @{ + warn ("connect(%s)", hostname); + close (s); + continue; + @} + freeaddrinfo (ai); + ai = NULL; + @} + if (ai) @{ + freeaddrinfo (ai); + errx ("failed to contact %s", hostname); + @} +@end example + +Before authenticating, an authentication context needs to be +created. This context keeps all information for one (to be) authenticated +connection (see @manpage{krb5_auth_context,3}). + +@example + status = krb5_auth_con_init (context, &auth_context); + if (status) + krb5_err (context, 1, status, "krb5_auth_con_init"); +@end example + +For setting the address in the authentication there is a help function +@code{krb5_auth_con_setaddrs_from_fd} that does everything that is needed +when given a connected file descriptor to the socket. + +@example + status = krb5_auth_con_setaddrs_from_fd (context, + auth_context, + &sock); + if (status) + krb5_err (context, 1, status, + "krb5_auth_con_setaddrs_from_fd"); +@end example + +The next step is to build a server principal for the service we want +to connect to. (See also @manpage{krb5_sname_to_principal,3}.) + +@example + status = krb5_sname_to_principal (context, + hostname, + service, + KRB5_NT_SRV_HST, + &server); + if (status) + krb5_err (context, 1, status, "krb5_sname_to_principal"); +@end example + +The client principal is not passed to @manpage{krb5_sendauth,3} +function, this causes the @code{krb5_sendauth} function to try to figure it +out itself. + +The server program is using the function @manpage{krb5_recvauth,3} to +receive the Kerberos 5 authenticator. + +In this case, mutual authentication will be tried. That means that the server +will authenticate to the client. Using mutual authentication +is good since it enables the user to verify that they are talking to the +right server (a server that knows the key). + +If you are using a non-blocking socket you will need to do all work of +@code{krb5_sendauth} yourself. Basically you need to send over the +authenticator from @manpage{krb5_mk_req,3} and, in case of mutual +authentication, verifying the result from the server with +@manpage{krb5_rd_rep,3}. + +@example + status = krb5_sendauth (context, + &auth_context, + &sock, + VERSION, + NULL, + server, + AP_OPTS_MUTUAL_REQUIRED, + NULL, + NULL, + NULL, + NULL, + NULL, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_sendauth"); +@end example + +Once authentication has been performed, it is time to send some +data. First we create a krb5_data structure, then we sign it with +@manpage{krb5_mk_safe,3} using the @code{auth_context} that contains the +session-key that was exchanged in the +@manpage{krb5_sendauth,3}/@manpage{krb5_recvauth,3} authentication +sequence. + +@example + data.data = "hej"; + data.length = 3; + + krb5_data_zero (&packet); + + status = krb5_mk_safe (context, + auth_context, + &data, + &packet, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_mk_safe"); +@end example + +And send it over the network. + +@example + len = packet.length; + net_len = htonl(len); + + if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); + if (krb5_net_write (context, &sock, packet.data, len) != len) + err (1, "krb5_net_write"); +@end example + +To send encrypted (and signed) data @manpage{krb5_mk_priv,3} should be +used instead. @manpage{krb5_mk_priv,3} works the same way as +@manpage{krb5_mk_safe,3}, with the exception that it encrypts the data +in addition to signing it. + +@example + data.data = "hemligt"; + data.length = 7; + + krb5_data_free (&packet); + + status = krb5_mk_priv (context, + auth_context, + &data, + &packet, + NULL); + if (status) + krb5_err (context, 1, status, "krb5_mk_priv"); +@end example + +And send it over the network. + +@example + len = packet.length; + net_len = htonl(len); + + if (krb5_net_write (context, &sock, &net_len, 4) != 4) + err (1, "krb5_net_write"); + if (krb5_net_write (context, &sock, packet.data, len) != len) + err (1, "krb5_net_write"); + +@end example + +The server is using @manpage{krb5_rd_safe,3} and +@manpage{krb5_rd_priv,3} to verify the signature and decrypt the packet. + +@node Validating a password in a server application, API differences to MIT Kerberos, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos +@section Validating a password in an application + +See the manual page for @manpage{krb5_verify_user,3}. + +@node API differences to MIT Kerberos, File formats, Validating a password in a server application, Programming with Kerberos +@section API differences to MIT Kerberos + +This section is somewhat disorganised, but so far there is no overall +structure to the differences, though some of the have their root in +that Heimdal uses an ASN.1 compiler and MIT doesn't. + +@subsection Principal and realms + +Heimdal stores the realm as a @code{krb5_realm}, that is a @code{char *}. +MIT Kerberos uses a @code{krb5_data} to store a realm. + +In Heimdal @code{krb5_principal} doesn't contain the component +@code{name_type}; it's instead stored in component +@code{name.name_type}. To get and set the nametype in Heimdal, use +@manpage{krb5_principal_get_type,3} and +@manpage{krb5_principal_set_type,3}. + +For more information about principal and realms, see +@manpage{krb5_principal,3}. + +@subsection Error messages + +To get the error string, Heimdal uses +@manpage{krb5_get_error_string,3} or, if @code{NULL} is returned, +@manpage{krb5_get_err_text,3}. This is to return custom error messages +(like ``Can't find host/datan.example.com@@EXAMPLE.COM in +/etc/krb5.conf.'' instead of a ``Key table entry not found'' that +@manpage{error_message,3} returns. + +Heimdal uses a threadsafe(r) version of the com_err interface; the +global @code{com_err} table isn't initialised. Then +@manpage{error_message,3} returns quite a boring error string (just +the error code itself). + + +@c @node Why you should use GSS-API for new applications, Walkthrough of a sample GSS-API client, Validating a password in a server application, Programming with Kerberos +@c @section Why you should use GSS-API for new applications +@c +@c SSPI, bah, bah, microsoft, bah, bah, almost GSS-API. +@c +@c It would also be possible for other mechanisms then Kerberos, but that +@c doesn't exist any other GSS-API implementations today. +@c +@c @node Walkthrough of a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos +@c @section Walkthrough of a sample GSS-API client +@c +@c Write about how gssapi_clent.c works. + +@node File formats, , API differences to MIT Kerberos, Programming with Kerberos +@section File formats + +This section documents the diffrent file formats that are used in +Heimdal and other Kerberos implementations. + +@subsection keytab + +The keytab binary format is not a standard format. The format has +evolved and may continue to. It is however understood by several +Kerberos implementations including Heimdal, MIT, Sun's Java ktab and +are created by the ktpass.exe utility from Windows. So it has +established itself as the defacto format for storing Kerberos keys. + +The following C-like structure definitions illustrate the MIT keytab +file format. All values are in network byte order. All text is ASCII. + +@example + keytab @{ + uint16_t file_format_version; /* 0x502 */ + keytab_entry entries[*]; + @}; + + keytab_entry @{ + int32_t size; + uint16_t num_components; /* subtract 1 if version 0x501 */ + counted_octet_string realm; + counted_octet_string components[num_components]; + uint32_t name_type; /* not present if version 0x501 */ + uint32_t timestamp; + uint8_t vno8; + keyblock key; + uint32_t vno; /* only present if >= 4 bytes left in entry */ + @}; + + counted_octet_string @{ + uint16_t length; + uint8_t data[length]; + @}; + + keyblock @{ + uint16_t type; + counted_octet_string; + @}; +@end example + +All numbers are stored in network byteorder (big endian) format. + +The keytab file format begins with the 16 bit file_format_version which +at the time this document was authored is 0x502. The format of older +keytabs is described at the end of this document. + +The file_format_version is immediately followed by an array of +keytab_entry structures which are prefixed with a 32 bit size indicating +the number of bytes that follow in the entry. Note that the size should be +evaluated as signed. This is because a negative value indicates that the +entry is in fact empty (e.g. it has been deleted) and that the negative +value of that negative value (which is of course a positive value) is +the offset to the next keytab_entry. Based on these size values alone +the entire keytab file can be traversed. + +The size is followed by a 16 bit num_components field indicating the +number of counted_octet_string components in the components array. + +The num_components field is followed by a counted_octet_string +representing the realm of the principal. + +A counted_octet_string is simply an array of bytes prefixed with a 16 +bit length. For the realm and name components, the counted_octet_string +bytes are ASCII encoded text with no zero terminator. + +Following the realm is the components array that represents the name of +the principal. The text of these components may be joined with slashs +to construct the typical SPN representation. For example, the service +principal HTTP/www.foo.net@@FOO.NET would consist of name components +"HTTP" followed by "www.foo.net". + +Following the components array is the 32 bit name_type (e.g. 1 is +KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In +practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL. + +The 32 bit timestamp indicates the time the key was established for that +principal. The value represents the number of seconds since Jan 1, 1970. + +The 8 bit vno8 field is the version number of the key. This value is +overridden by the 32 bit vno field if it is present. The vno8 field is +filled with the lower 8 bits of the 32 bit protocol kvno field. + +The keyblock structure consists of a 16 bit value indicating the +encryption type and is a counted_octet_string containing the key. The +encryption type is the same as the Kerberos standard (e.g. 3 is +des-cbc-md5, 23 is arcfour-hmac-md5, etc). + +The last field of the keytab_entry structure is optional. If the size of +the keytab_entry indicates that there are at least 4 bytes remaining, +a 32 bit value representing the key version number is present. This +value supersedes the 8 bit vno8 value preceeding the keyblock. + +Older keytabs with a file_format_version of 0x501 are different in +three ways: + +@table @asis +@item All integers are in host byte order [1]. +@item The num_components field is 1 too large (i.e. after decoding, decrement by 1). +@item The 32 bit name_type field is not present. +@end table + +[1] The file_format_version field should really be treated as two +separate 8 bit quantities representing the major and minor version +number respectively. + +@subsection Heimdal database dump file + +Format of the Heimdal text dump file as of Heimdal 0.6.3: + +Each line in the dump file is one entry in the database. + +Each field of a line is separated by one or more spaces, with the +exception of fields consisting of principals containing spaces, where +space can be quoted with \ and \ is quoted by \. + +Fields and their types are: + +@example + Quoted princial (quote character is \) [string] + Keys [keys] + Created by [event] + Modified by [event optional] + Valid start time [time optional] + Valid end time [time optional] + Password end valid time [time optional] + Max lifetime of ticket [time optional] + Max renew time of ticket [integer optional] + Flags [hdb flags] + Generation number [generation optional] + Extensions [extentions optional] +@end example + +Fields following these silently are ignored. + +All optional fields will be skipped if they fail to parse (or comprise +the optional field marker of "-", w/o quotes). + +Example: + +@example +fred@@EXAMPLE.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin@@EXAMPLE.COM 20041221112428:fred@@EXAMPLE.COM - - - 86400 604800 126 20020415130120:793707:28 - +@end example + +Encoding of types are as follows: + +@table @asis +@item keys + +@example +kvno:[masterkvno:keytype:keydata:salt]@{zero or more separated by :@} +@end example + +kvno is the key version number. + +keydata is hex-encoded + +masterkvno is the kvno of the database master key. If this field is +empty, the kadmin load and merge operations will encrypt the key data +with the master key if there is one. Otherwise the key data will be +imported asis. + +salt is encoded as "-" (no/default salt) or + +@example +salt-type / +salt-type / "string" +salt-type / hex-encoded-data +@end example + +keytype is the protocol enctype number; see enum ENCTYPE in +include/krb5_asn1.h for values. + +Example: +@example +27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- +@end example + + +@example +kvno=27,@{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., default salt@}... +@end example + +@item time + +Format of the time is: YYYYmmddHHMMSS, corresponding to strftime +format "%Y%m%d%k%M%S". + +Time is expressed in UTC. + +Time can be optional (using -), when the time 0 is used. + +Example: + +@example +20041221112428 +@end example + +@item event + +@example + time:principal +@end example + +time is as given in format time + +principal is a string. Not quoting it may not work in earlier +versions of Heimdal. + +Example: +@example +20041221112428:bloggs@@EXAMPLE.COM +@end example + +@item hdb flags + +Integer encoding of HDB flags, see HDBFlags in lib/hdb/hdb.asn1. Each +bit in the integer is the same as the bit in the specification. + +@item generation: + +@example +time:usec:gen +@end example + + +usec is a the microsecond, integer. +gen is generation number, integer. + +The generation can be defaulted (using '-') or the empty string + +@item extensions: + +@example +first-hex-encoded-HDB-Extension[:second-...] +@end example + +HDB-extension is encoded the DER encoded HDB-Extension from +lib/hdb/hdb.asn1. Consumers HDB extensions should be aware that +unknown entires needs to be preserved even thought the ASN.1 data +content might be unknown. There is a critical flag in the data to show +to the KDC that the entry MUST be understod if the entry is to be +used. + +@end table diff --git a/doc/setup.texi b/doc/setup.texi new file mode 100644 index 000000000000..02e7972c1dfe --- /dev/null +++ b/doc/setup.texi @@ -0,0 +1,1455 @@ +@c $Id: setup.texi 22191 2007-12-06 17:26:30Z lha $ + +@node Setting up a realm, Applications, 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. + +@menu +* Configuration file:: +* Creating the database:: +* Modifying the database:: +* Checking the setup:: +* keytabs:: +* Serving Kerberos 4/524/kaserver:: +* Remote administration:: +* Password changing:: +* Testing clients and servers:: +* Slave Servers:: +* Incremental propagation:: +* Encryption types and salting:: +* Cross realm:: +* Transit policy:: +* Setting up DNS:: +* Using LDAP to store the database:: +* Providing Kerberos credentials to servers and programs:: +* Setting up PK-INIT:: +@end menu + +@node Configuration file, Creating the database, Setting up a realm, Setting up a realm +@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{[@samp{section-name}]}. A binding consists of a left hand side, an equal sign +(@samp{=}) and a right hand side (the left hand side tag must be +separated from the equal sign with some whitespace). Subsections have a +@samp{@{} as the first non-whitespace character after the equal sign. 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 configuration 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 configuration file, +with contents similar to the following. + +@example +[libdefaults] + default_realm = MY.REALM +[realms] + MY.REALM = @{ + kdc = my.kdc my.slave.kdc + kdc = my.third.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 DNS +SRV-record for your realm, or your Kerberos server has DNS CNAME +@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. + +@node Creating the database, Modifying the database, Configuration file, Setting up a realm +@section Creating the database + +The database library will look for the database in the directory +@file{@value{dbdir}}, so you should probably create that directory. +Make sure the directory has restrictive permissions. + +@example +# mkdir /var/heimdal +@end example + +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 + +If you want to generate a random master key you can use the +@kbd{--random-key} flag to kstash. This will make sure you have a good key +on which attackers can't do a dictionary attack. + +If you have a master key, make sure you make a backup of your master +key file; without it backups of the database are of no use. + +To initialise the database use the @command{kadmin} program, with the +@kbd{-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 maximum 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 set up +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 + +@node Modifying the database, Checking the setup, Creating the database, Setting up a realm +@section Modifying the database + +All modifications of principals are done with with kadmin. + +A principal has several attributes and lifetimes associated with it. + +Principals are added, renamed, modified, and deleted with the kadmin +commands @samp{add}, @samp{rename}, @samp{modify}, @samp{delete}. +Both interactive editing and command line flags can be used (use --help +to list the available options). + +There are different kinds of types for the fields in the database; +attributes, absolute time times and relative times. + +@subsection Attributes + +When doing interactive editing, attributes are listed with @samp{?}. + +The attributes are given in a comma (@samp{,}) separated list. +Attributes are removed from the list by prefixing them with @samp{-}. + +@smallexample +kadmin> modify me +Max ticket life [1 day]: +Max renewable life [1 week]: +Principal expiration time [never]: +Password expiration time [never]: +Attributes [disallow-renewable]: requires-pre-auth,-disallow-renewable +kadmin> get me + Principal: me@@MY.REALM +[...] + Attributes: requires-pre-auth +@end smallexample + +@subsection Absolute times + +The format for absolute times are any of the following: + +@smallexample +never +now +YYYY-mm-dd +YYYY-mm-dd HH:MM:SS +@end smallexample + + +@subsection Relative times + +The format for relative times are any of the following combined: + +@smallexample +N year +M month +O day +P hour +Q minute +R second +@end smallexample + +@c Describe more of kadmin commands here... + +@node Checking the setup, keytabs, Modifying the database, Setting up a realm +@section Checking the setup + +There are two tools that can check the consistency of the Kerberos +configuration file and the Kerberos database. + +The Kerberos configuration file is checked using +@command{verify_krb5_conf}. The tool checks for common errors, but +commonly there are several uncommon configuration entries that are +never added to the tool and thus generates ``unknown entry'' warnings. +This is usually nothing to worry about. + +The database check is built into the kadmin tool. It will check for +common configuration error that will cause problems later. Common +check are for existence and flags on important principals. The +database check by run by the following command : + +@example +kadmin check REALM.EXAMPLE.ORG +@end example + +@node keytabs, Serving Kerberos 4/524/kaserver, Checking the setup, Setting up a realm +@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-key} flag to get a random key) and then +extract it with @samp{ext_keytab}. + +@example +kadmin> add --random-key host/my.host.name +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin> ext host/my.host.name +kadmin> exit +# 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 + +@node Serving Kerberos 4/524/kaserver, Remote administration, keytabs, Setting up a realm +@section Serving Kerberos 4/524/kaserver + +Heimdal can be configured to support 524, Kerberos 4 or kaserver. All +these services are turned off by default. Kerberos 4 is always +supported by the KDC, but the Kerberos 4 client support also depends +on Kerberos 4 support having been included at compile-time, using +@kbd{--with-krb4=dir}. + +@subsection 524 + +524 is a service that allows the KDC to convert Kerberos 5 tickets to +Kerberos 4 tickets for backward compatibility. See also Using 2b +tokens with AFS in @xref{Things in search for a better place}. + +524 can be turned on by adding this to the configuration file + +@example +[kdc] + enable-524 = yes +@end example + +@subsection Kerberos 4 + +Kerberos 4 is the predecessor to to Kerberos 5. It only supports +single DES@. You should only enable Kerberos 4 support if you have +needs for compatibility with an installed base of Kerberos 4 +clients/servers. + +Kerberos 4 can be turned on by adding this to the configuration file + +@example +[kdc] + enable-kerberos4 = yes +@end example + +@subsection kaserver + +Kaserver is a Kerberos 4 that is used in AFS@. The protocol has some +extra features over plain Kerberos 4, but like Kerberos 4, only uses +single DES@. + +You should only enable Kaserver support if you have needs for +compatibility with an installed base of AFS machines. + +Kaserver can be turned on by adding this to the configuration file + +@example +[kdc] + enable-kaserver = yes +@end example + +@node Remote administration, Password changing, Serving Kerberos 4/524/kaserver, Setting up a realm +@section Remote administration + +The administration server, @command{kadmind}, can be started by +@command{inetd} (which isn't recommended) or run as a normal daemon. If you +want to start it from @command{inetd} 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 @samp{749/tcp}. + +Access to the administration server is controlled by an ACL file, +(default @file{/var/heimdal/kadmind.acl}.) The file has the following +syntax: +@smallexample +principal [priv1,priv2,...] [glob-pattern] +@end smallexample + +The matching is from top to bottom for matching principals (and if given, +glob-pattern). When there is a match, the access rights of that line are +applied. + +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 correspond to the different commands +in @command{kadmin}. + +If a @var{glob-pattern} is given on a line, it restricts the access +rights for the principal to only apply for subjects that match the +pattern. The patterns are of the same type as those used in shell +globbing, see @url{none,,fnmatch(3)}. + +In the example below @samp{lha/admin} can change every principal in the +database. @samp{jimmy/admin} can only modify principals that belong to +the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the +help desk, so he should only be able to change the passwords for single +component principals (ordinary users). He will not be able to change any +@samp{/admin} principal. + +@example +lha/admin@@E.KTH.SE all +jimmy/admin@@E.KTH.SE all *@@E.KTH.SE +jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE +mille/admin@@E.KTH.SE change-password *@@E.KTH.SE +@end example + +@node Password changing, Testing clients and servers, Remote administration, Setting up a realm +@section Password changing + +To allow users to change their passwords, you should run @command{kpasswdd}. +It is not run from @command{inetd}. + +You might need to add @samp{kpasswd} to your @file{/etc/services} as +@samp{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 (although +pre-authentication provides some defence against off-line attacks). +To ensure that the users choose good passwords, you can enable +password quality controls in @command{kpasswdd} and @command{kadmind}. +The controls themselves are done in a shared library or an external +program that is used by @command{kpasswdd}. To configure in these +controls, add lines similar to the following to your +@file{/etc/krb5.conf}: + +@example +[password_quality] + policies = external-check builtin:minimum-length module:policyname + external_program = /bin/false + policy_libraries = @var{library1.so} @var{library2.so} +@end example + +In @samp{[password_quality]policies} the module name is optional if +the policy name is unique in all modules (members of +@samp{policy_libraries}). + +The built-in polices are + +@itemize @bullet + +@item external-check + +Executes the program specified by @samp{[password_quality]external_program}. + +A number of key/value pairs are passed as input to the program, one per +line, ending with the string @samp{end}. The key/value lines are of +the form +@example +principal: @var{principal} +new-password: @var{password} +@end example +where @var{password} is the password to check for the previous +@var{principal}. + +If the external application approves the password, it should return +@samp{APPROVED} on standard out and exit with exit code 0. If it +doesn't approve the password, an one line error message explaining the +problem should be returned on standard error and the application +should exit with exit code 0. In case of a fatal error, the +application should, if possible, print an error message on standard +error and exit with a non-zero error code. + +@item minimum-length + +The minimum length password quality check reads the configuration file +stanza @samp{[password_quality]min_length} and requires the password +to be at least this length. + +@item character-class + +The character-class password quality check reads the configuration +file stanza @samp{[password_quality]min_classes}. The policy requires +the password to have characters from at least that many character +classes. Default value if not given is 3. + +The four different characters classes are, uppercase, lowercase, +number, special characters. + +@end itemize + +If you want to write your own shared object to check password +policies, see the manual page @manpage{kadm5_pwcheck,3}. + +Code for a password quality checking function that uses the cracklib +library can be found in @file{lib/kadm5/sample_password_check.c} in +the source code distribution. It requires that the cracklib library +be built with the patch available at +@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. + +A sample policy external program is included in +@file{lib/kadm5/check-cracklib.pl}. + +If no password quality checking function is configured, the only check +performed is that the password is at least six characters long. + +To check the password policy settings, use the command +@command{password-quality} in @command{kadmin} program. The password +verification is only performed locally, on the client. It may be +convenient to set the environment variable @samp{KRB5_CONFIG} to point +to a test version of @file{krb5.conf} while you're testing the +@samp{[password_quality]} stanza that way. + +@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm +@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. + +@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm +@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm + +It is desirable to have at least one backup (slave) server in case the +master server fails. It is possible to have any number of such slave +servers but more than three usually doesn't buy much more redundancy. + +All Kerberos servers for a realm must have the same database so that +they present the same service to the users. The +@pindex hprop +@command{hprop} program, running on the master, will propagate the database +to the slaves, running +@pindex hpropd +@command{hpropd} processes. + +Every slave needs a database directory, the master key (if it was used +for the database) and a keytab with the principal +@samp{hprop/@var{hostname}}. Add the principal with the +@pindex ktutil +@command{ktutil} command and start +@pindex hpropd +@command{hpropd}, as follows: + +@example +slave# ktutil get -p foo/admin hprop/`hostname` +slave# mkdir /var/heimdal +slave# hpropd +@end example + +The master will use the principal @samp{kadmin/hprop} to authenticate to +the slaves. This principal should be added when running @kbd{kadmin -l +init} but if you do not have it in your database for whatever reason, +please add it with @kbd{kadmin -l add}. + +Then run +@pindex hprop +@code{hprop} on the master: + +@example +master# hprop slave +@end example + +This was just an hands-on example to make sure that everything was +working properly. Doing it manually is of course the wrong way, and to +automate this you will want to start +@pindex hpropd +@command{hpropd} from @command{inetd} on the slave(s) and regularly run +@pindex hprop +@command{hprop} on the master to regularly propagate the database. +Starting the propagation once an hour from @command{cron} is probably a +good idea. + +@node Incremental propagation, Encryption types and salting, Slave Servers, Setting up a realm +@section Incremental propagation + +There is also a newer, and still somewhat experimental, mechanism for +doing incremental propagation in Heimdal. Instead of sending the whole +database regularly, it sends the changes as they happen on the master to +the slaves. The master keeps track of all the changes by assigning a +version number to every change to the database. The slaves know which +was the latest version they saw and in this way it can be determined if +they are in sync or not. A log of all the changes is kept on the master, +and when a slave is at an older version than the oldest one in the +log, the whole database has to be sent. + +Protocol-wise, all the slaves connect to the master and as a greeting +tell it the latest version that they have (@samp{IHAVE} message). The +master then responds by sending all the changes between that version and +the current version at the master (a series of @samp{FORYOU} messages) +or the whole database in a @samp{TELLYOUEVERYTHING} message. There is +also a keep-alive protocol that makes sure all slaves are up and running. + +@subsection Configuring incremental propagation + +The program that runs on the master is @command{ipropd-master} and all +clients run @command{ipropd-slave}. + +Create the file @file{/var/heimdal/slaves} on the master containing all +the slaves that the database should be propagated to. Each line contains +the full name of the principal (for example +@samp{iprop/hemligare.foo.se@@FOO.SE}). + +You should already have @samp{iprop/tcp} defined as 2121, in your +@file{/etc/services}. Otherwise, or if you need to use a different port +for some peculiar reason, you can use the @kbd{--port} option. This is +useful when you have multiple realms to distribute from one server. + +Then you need to create those principals that you added in the +configuration file. Create one @samp{iprop/hostname} for the master and +for every slave. + + +@example +master# /usr/heimdal/sbin/ktutil get iprop/`hostname` +@end example + +The next step is to start the @command{ipropd-master} process on the master +server. The @command{ipropd-master} listens on the UNIX domain socket +@file{/var/heimdal/signal} to know when changes have been made to the +database so they can be propagated to the slaves. There is also a +safety feature of testing the version number regularly (every 30 +seconds) to see if it has been modified by some means that do not raise +this signal. Then, start @command{ipropd-slave} on all the slaves: + +@example +master# /usr/heimdal/libexec/ipropd-master & +slave# /usr/heimdal/libexec/ipropd-slave master & +@end example + +To manage the iprop log file you should use the @command{iprop-log} +command. With it you can dump, truncate and replay the logfile. + +@node Encryption types and salting, Cross realm, Incremental propagation, Setting up a realm +@section Encryption types and salting +@cindex Salting +@cindex Encryption types + +The encryption types that the KDC is going to assign by default is +possible to change. Since the keys used for user authentication is +salted the encryption types are described together with the salt +strings. + +Salting is used to make it harder to pre-calculate all possible +keys. Using a salt increases the search space to make it almost +impossible to pre-calculate all keys. Salting is the process of mixing a +public string (the salt) with the password, then sending it through an +encryption type specific string-to-key function that will output the +fixed size encryption key. + +In Kerberos 5 the salt is determined by the encryption type, except in +some special cases. + +In @code{des} there is the Kerberos 4 salt +(none at all) or the afs-salt (using the cell (realm in +AFS lingo)). + +In @code{arcfour} (the encryption type that Microsoft Windows 2000 uses) +there is no salt. This is to be compatible with NTLM keys in Windows +NT 4. + +@code{[kadmin]default_keys} in @file{krb5.conf} controls +what salting to use. + +The syntax of @code{[kadmin]default_keys} is +@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption +type (des-cbc-crc, arcfour-hmac-md5, aes256-cts-hmac-sha1-96), +@code{salt-type} is the type of salt (pw-salt or afs3-salt), and the +salt-string is the string that will be used as salt (remember that if +the salt is appended/prepended, the empty salt "" is the same thing as +no salt at all). + +Common types of salting include + +@itemize @bullet +@item @code{v4} (or @code{des:pw-salt:}) + +The Kerberos 4 salting is using no salt at all. Reason there is colon +at the end of the salt string is that it makes the salt the empty +string (same as no salt). + +@item @code{v5} (or @code{pw-salt}) + +@code{pw-salt} uses the default salt for each encryption type is +specified for. If the encryption type @samp{etype} isn't given, all +default encryption will be used. + +@item @code{afs3-salt} + +@code{afs3-salt} is the salt that is used with Transarc kaserver. It's +the cell name appended to the password. + +@end itemize + +@node Cross realm, Transit policy, Encryption types and salting, Setting up a realm +@section Cross realm +@cindex Cross realm + +Suppose you reside in the realm @samp{MY.REALM}, how do you +authenticate to a server in @samp{OTHER.REALM}? Having valid tickets in +@samp{MY.REALM} allows you to communicate with Kerberised services in that +realm. However, the computer in the other realm does not have a secret +key shared with the Kerberos server in your realm. + +It is possible to share keys between two realms that trust each +other. When a client program, such as @command{telnet} or @command{ssh}, +finds that the other computer is in a different realm, it will try to +get a ticket granting ticket for that other realm, but from the local +Kerberos server. With that ticket granting ticket, it will then obtain +service tickets from the Kerberos server in the other realm. + +For a two way trust between @samp{MY.REALM} and @samp{OTHER.REALM} +add the following principals to each realm. The principals should be +@samp{krbtgt/OTHER.REALM@@MY.REALM} and +@samp{krbtgt/MY.REALM@@OTHER.REALM} in @samp{MY.REALM}, and +@samp{krbtgt/MY.REALM@@OTHER.REALM} and +@samp{krbtgt/OTHER.REALM@@MY.REALM}in @samp{OTHER.REALM}. + +In Kerberos 5 the trust can be configured to be one way. So that +users from @samp{MY.REALM} can authenticate to services in +@samp{OTHER.REALM}, but not the opposite. In the example above, the +@samp{krbtgt/MY.REALM@@OTHER.REALM} then should be removed. + +The two principals must have the same key, key version number, and the +same set of encryption types. Remember to transfer the two keys in a +safe manner. + +@example +vr$ klist +Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@@E.KTH.SE + + Issued Expires Principal +May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE + +vr$ telnet -l lha hummel.it.su.se +Trying 2001:6b0:5:1095:250:fcff:fe24:dbf... +Connected to hummel.it.su.se. +Escape character is '^]'. +Waiting for encryption to be negotiated... +[ Trying mutual KERBEROS5 (host/hummel.it.su.se@@SU.SE)... ] +[ Kerberos V5 accepts you as ``lha@@E.KTH.SE'' ] +Encryption negotiated. +Last login: Sat May 3 14:11:47 from vr.l.nxs.se +hummel$ exit + +vr$ klist +Credentials cache: FILE:/tmp/krb5cc_913.console + Principal: lha@@E.KTH.SE + + Issued Expires Principal +May 3 13:55:52 May 3 23:55:54 krbtgt/E.KTH.SE@@E.KTH.SE +May 3 13:55:56 May 3 23:55:54 krbtgt/SU.SE@@E.KTH.SE +May 3 14:10:54 May 3 23:55:54 host/hummel.it.su.se@@SU.SE + +@end example + +@node Transit policy, Setting up DNS, Cross realm, Setting up a realm +@section Transit policy +@cindex Transit policy + +If you want to use cross realm authentication through an intermediate +realm, it must be explicitly allowed by either the KDCs or the server +receiving the request. This is done in @file{krb5.conf} in the +@code{[capaths]} section. + +When the ticket transits through a realm to another realm, the +destination realm adds its peer to the "transited-realms" field in the +ticket. The field is unordered, since there is no way to know if +know if one of the transited-realms changed the order of the list. + +The syntax for @code{[capaths]} section: + +@example +[capaths] + CLIENT-REALM = @{ + SERVER-REALM = PERMITTED-CROSS-REALMS ... + @} +@end example + +The realm @code{STACKEN.KTH.SE} allows clients from @code{SU.SE} and +@code{DSV.SU.SE} to cross it. Since @code{STACKEN.KTH.SE} only has +direct cross realm setup with @code{KTH.SE}, and @code{DSV.SU.SE} only +has direct cross realm setup with @code{SU.SE} they need to use both +@code{SU.SE} and @code{KTH.SE} as transit realms. + +@example +[capaths] + SU.SE = @{ + STACKEN.KTH.SE = KTH.SE + @} + DSV.SU.SE = @{ + STACKEN.KTH.SE = SU.SE KTH.SE + @} + +@end example + +The order of the @code{PERMITTED-CROSS-REALMS} is not important when +doing transit cross realm verification. + +However, the order is important when the @code{[capaths]} section is used +to figure out the intermediate realm to go to when doing multi-realm +transit. When figuring out the next realm, the first realm of the list +of @code{PERMITTED-CROSS-REALMS} is chosen. This is done in both the +client kerberos library and the KDC. + +@c To test the cross realm configuration, use: +@c kmumble transit-check client server transit-realms ... + +@node Setting up DNS, Using LDAP to store the database, Transit policy, Setting up a realm +@section Setting up DNS +@cindex Setting up DNS + +@subsection Using DNS to find KDC + +If there is information about where to find the KDC or kadmind for a +realm in the @file{krb5.conf} for a realm, that information will be +preferred, and DNS will not be queried. + +Heimdal will try to use DNS to find the KDCs for a realm. First it +will try to find a @code{SRV} resource record (RR) for the realm. If no +SRV RRs are found, it will fall back to looking for an @code{A} RR for +a machine named kerberos.REALM, and then kerberos-1.REALM, etc + +Adding this information to DNS minimises the client configuration (in +the common case, resulting in no configuration needed) and allows the +system administrator to change the number of KDCs and on what machines +they are running without caring about clients. + +The downside of using DNS is that the client might be fooled to use the +wrong server if someone fakes DNS replies/data, but storing the IP +addresses of the KDC on all the clients makes it very hard to change +the infrastructure. + +An example of the configuration for the realm @code{EXAMPLE.COM}: + +@example + +$ORIGIN example.com. +_kerberos._tcp SRV 10 1 88 kerberos.example.com. +_kerberos._udp SRV 10 1 88 kerberos.example.com. +_kerberos._tcp SRV 10 1 88 kerberos-1.example.com. +_kerberos._udp SRV 10 1 88 kerberos-1.example.com. +_kpasswd._udp SRV 10 1 464 kerberos.example.com. +_kerberos-adm._tcp SRV 10 1 749 kerberos.example.com. + +@end example + +More information about DNS SRV resource records can be found in +RFC-2782 (A DNS RR for specifying the location of services (DNS SRV)). + +@subsection Using DNS to map hostname to Kerberos realm + +Heimdal also supports a way to lookup a realm from a hostname. This to +minimise configuration needed on clients. Using this has the drawback +that clients can be redirected by an attacker to realms within the +same cross realm trust and made to believe they are talking to the +right server (since Kerberos authentication will succeed). + +An example configuration that informs clients that for the realms +it.example.com and srv.example.com, they should use the realm +EXAMPLE.COM: + +@example + +$ORIGIN example.com. +_kerberos.it TXT "EXAMPLE.COM" +_kerberos.srv TXT "EXAMPLE.COM" + +@end example + +@node Using LDAP to store the database, Providing Kerberos credentials to servers and programs, Setting up DNS, Setting up a realm +@section Using LDAP to store the database +@cindex Using the LDAP backend + +This document describes how to install the LDAP backend for +Heimdal. Note that before attempting to configure such an +installation, you should be aware of the implications of storing +private information (such as users' keys) in a directory service +primarily designed for public information. Nonetheless, with a +suitable authorisation policy, it is possible to set this up in a +secure fashion. A knowledge of LDAP, Kerberos, and C is necessary to +install this backend. The HDB schema was devised by Leif Johansson. + +Requirements: + +@itemize @bullet + +@item +A current release of Heimdal, configured with +@code{--with-openldap=/usr/local} (adjust according to where you have +installed OpenLDAP). + +You can verify that you manage to configure LDAP support by running +@file{kdc --builtin-hdb}, and checking that @samp{ldap:} is one entry +in the list. + +Its also possible to configure the ldap backend as a shared module, +see option --hdb-openldap-module to configure. + +@item +OpenLDAP 2.0.x. Configure OpenLDAP with @kbd{--enable-local} to enable the +local transport. (A patch to support SASL EXTERNAL authentication is +necessary in order to use OpenLDAP 2.1.x.) + +@item +Add the hdb schema to the LDAP server, it's included in the source-tree +in @file{lib/hdb/hdb.schema}. Example from slapd.conf: + +@example +include /usr/local/etc/openldap/schema/hdb.schema +@end example + +@item +Configure the LDAP server ACLs to accept writes from clients over the +local transport. For example: + +@example +access to * + by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write + ... + +sasl-regexp "uidNumber=0\\\+gidNumber=.*,cn=peercred,cn=external,cn=auth" + "uid=heimdal,dc=services,dc=example,dc=com" + +@end example + +The sasl-regexp is for mapping between the SASL/EXTERNAL and a user in +a tree. The user that the key is mapped to should be have a +krb5Principal aux object with krb5PrincipalName set so that the +``creator'' and ``modifier'' is right in @file{kadmin}. + +Another option is to create an admins group and add the dn to that +group. + +Since Heimdal talks to the LDAP server over a UNIX domain socket, and +uses external sasl authentication, it's not possible to require +security layer quality (ssf in cyrus-sasl lingo). So that requirement +has to be turned off in OpenLDAP @command{slapd} configuration file +@file{slapd.conf}. + +@example +sasl-secprops minssf=0 +@end example + +@item + +Start @command{slapd} with the local listener (as well as the default TCP/IP +listener on port 389) as follows: + +@example + slapd -h "ldapi:/// ldap:///" +@end example + +Note: These is a bug in @command{slapd} where it appears to corrupt the krb5Key +binary attribute on shutdown. This may be related to our use of the V3 +schema definition syntax instead of the old UMich-style, V2 syntax. + +@item +You should specify the distinguished name under which your +principals will be stored in @file{krb5.conf}. Also you need to +enter the path to the kadmin acl file: + + +@example +[kdc] + database = @{ + dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com + hdb-ldap-structural-object = inetOrgPerson + acl_file = /path/to/kadmind.acl + mkey_file = /path/to/mkey + @} +@end example + +@samp{mkey_file} can be excluded if you feel that you trust your ldap +directory to have the raw keys inside it. The +hdb-ldap-structural-object is not necessary if you do not need Samba +comatibility. + + + +@item +Once you have built Heimdal and started the LDAP server, run kadmin +(as usual) to initialise the database. Note that the instructions for +stashing a master key are as per any Heimdal installation. + +@example +kdc# kadmin -l +kadmin> init EXAMPLE.COM +Realm max ticket life [unlimited]: +Realm max renewable ticket life [unlimited]: +kadmin> ank lukeh +Max ticket life [1 day]: +Max renewable life [1 week]: +Principal expiration time [never]: +Password expiration time [never]: +Attributes []: +lukeh@@EXAMPLE.COM's Password: +Verifying password - lukeh@@EXAMPLE.COM's Password: +kadmin> exit +@end example + +Verify that the principal database has indeed been stored in the +directory with the following command: + +@example +kdc# ldapsearch -L -h localhost -D cn=manager \ + -w secret -b ou=KerberosPrincipals,dc=example,dc=com \ + 'objectclass=krb5KDCEntry' +@end example + +@item +Now consider adding indexes to the database to speed up the access, at +least theses should be added to slapd.conf. + +@example +index objectClass eq +index cn eq,sub,pres +index uid eq,sub,pres +index displayName eq,sub,pres +index krb5PrincipalName eq +@end example + +@end itemize + +@subsection Troubleshooting guide + +@url{https://sec.miljovern.no/bin/view/Info/TroubleshootingGuide} + + +@subsection Using Samba LDAP password database +@cindex Samba + +@c @node Using Samba LDAP password database, Providing Kerberos credentials to servers and programs, Using LDAP to store the database, Setting up a realm +@c @section Using Samba LDAP password database + +The Samba domain and the Kerberos realm can have different names since +arcfour's string to key functions principal/realm independent. So now +will be your first and only chance name your Kerberos realm without +needing to deal with old configuration files. + +First, you should set up Samba and get that working with LDAP backend. + +Now you can proceed as in @xref{Using LDAP to store the database}. +Heimdal will pick up the Samba LDAP entries if they are in the same +search space as the Kerberos entries. + +@node Providing Kerberos credentials to servers and programs, Setting up PK-INIT, Using LDAP to store the database, Setting up a realm +@section Providing Kerberos credentials to servers and programs + +Some services require Kerberos credentials when they start to make +connections to other services or need to use them when they have started. + +The easiest way to get tickets for a service is to store the key in a +keytab. Both ktutil get and kadmin ext can be used to get a +keytab. ktutil get is better in that way it changes the key/password +for the user. This is also the problem with ktutil. If ktutil is used +for the same service principal on several hosts, they keytab will only +be useful on the last host. In that case, run the extract command on +one host and then securely copy the keytab around to all other hosts +that need it. + +@example +host# ktutil -k /etc/krb5-service.keytab \ + get -p lha/admin@@EXAMPLE.ORG service-principal@@EXAMPLE.ORG +lha/admin@@EXAMPLE.ORG's Password: +@end example + +To get a Kerberos credential file for the service, use kinit in the +@kbd{--keytab} mode. This will not ask for a password but instead fetch the +key from the keytab. + +@example +service@@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@@EXAMPLE.ORG +@end example + +Long running services might need credentials longer then the +expiration time of the tickets. kinit can run in a mode that refreshes +the tickets before they expire. This is useful for services that write +into AFS and other distributed file systems using Kerberos. To run the +long running script, just append the program and arguments (if any) +after the principal. kinit will stop refreshing credentials and remove +the credentials when the script-to-start-service exits. + +@example +service@@host$ kinit --cache=/var/run/service_krb5_cache \ + --keytab=/etc/krb5-service.keytab \ + service-principal@@EXAMPLE.ORG \ + script-to-start-service argument1 argument2 +@end example + + +@node Setting up PK-INIT, , Providing Kerberos credentials to servers and programs, Setting up a realm +@section Setting up PK-INIT + +PK-INIT is levering the existing PKI infrastructure to use +certificates to get the initial ticket, that is usually the krbtgt. + +To use PK-INIT you must first have a PKI, so if you don't have one, +it is time to create it. Note that you should read the whole chapter +of the document to see the requirements on the CA software. + +There needs to exist a mapping between the certificate and what +principals that certificate is allowed to use. There are several ways +to do this. The administrator can use a configuration file, storing +the principal in the SubjectAltName extension of the certificate, or store the +mapping in the principals entry in the kerberos database. + +@section Certificates + +This section documents the requirements on the KDC and client +certificates and the format used in the id-pkinit-san OtherName +extention. + +@subsection KDC certificate + +The certificate for the KDC have serveral requirements. + +First the certificate should have an Extended Key Usage (EKU) +id-pkkdcekuoid (1.3.6.1.5.2.3.5) set. Second there must be a +subjectAltName otherName using oid id-pkinit-san (1.3.6.1.5.2.2) in +the type field and a DER encoded KRB5PrincipalName that matches the +name of the TGS of the target realm. + +Both of these two requirements are not required by the standard to be +checked by the client if it have external information what the +certificate the KDC is supposed to be used. So it's in the interest of +minimum amount of configuration on the clients they should be included. + +Remember that if the client would accept any certificate as the KDC's +certificate, the client could be fooled into trusting something that +isn't a KDC and thus expose the user to giving away information (like +password or other private information) that it is supposed to secret. + +Also, if the certificate has a nameConstraints extention with a +Generalname with dNSName or iPAdress it must match the hostname or +adress of the KDC. + +@subsection Client certificate + +The client certificate may need to have a EKU id-pkekuoid +(1.3.6.1.5.2.3.4) set depending on the certifiate on the KDC. + +It possible to store the principal (if allowed by the KDC) in the +certificate and thus delegate responsibility to do the mapping between +certificates and principals to the CA. + +@subsubsection Using KRB5PrincipalName in id-pkinit-san + +OtherName extention in the GeneralName is used to do the +mapping between certifiate and principal in the certifiate or storing +the krbtgt principal in the KDC certificate. + +The principal is stored in a SubjectAltName in the certificate using +OtherName. The oid in the type is id-pkinit-san. + +@example +id-pkinit-san OBJECT IDENTIFIER ::= @{ iso (1) org (3) dod (6) +internet (1) security (5) kerberosv5 (2) 2 @} +@end example + +The data part of the OtherName is filled with the following DER +encoded ASN.1 structure: + +@example +KRB5PrincipalName ::= SEQUENCE @{ + realm [0] Realm, + principalName [1] PrincipalName +@} +@end example + +where Realm and PrincipalName is defined by the Kerberos ASN.1 specification. + +@section Naming certificate using hx509 + +hx509 is the X.509 software used in Heimdal to handle +certificates. hx509 uses different syntaxes to specify the different +formats the certificates are stored in and what formats they exist in. + +There are several formats that can be used, PEM, embedded into PKCS12 +files, embedded into PKCS11 devices and raw DER encoded certificates. +Below is a list of types to use. + + +@table @asis + +@item DIR: + +DIR is reading all certificates in a directory that is DER or PEM +formatted. + +The main feature of DIR is that the directory is read on demand when +iterating over certificates, that way applictions can for some cases +avoid to store all certificates in memory. It's very useful for tests +that iterate over larger amount of certificates. + +Syntax is: + +@example +DIR:/path/to/der/files +@end example + +@item FILE: + +FILE: is used to have the lib pick up a certificate chain and a +private key. The file can be either a PEM (openssl) file or a raw DER +encoded certificate. If it's a PEM file it can contain several keys and +certificates and the code will try to match the private key and +certificate together. + +Its useful to have one PEM file that contains all the trust anchors. + +Syntax is: + +@example +FILE:certificate.pem,private-key.key,other-cert.pem,.... +@end example + +@item PKCS11: + +PKCS11: is used to handle smartcards via PKCS11 drivers, for example +soft-token, opensc, or muscle. The default is to use all slots on the +device/token. + +Syntax is: + +@example +PKCS11:shared-object.so +@end example + +@item PKCS12: + +PKCS12: is used to handle PKCS12 files. PKCS12 files commonly have the +extension pfx or p12. + +Syntax is: + +@example +PKCS12:/path/to/file.pfx +@end example + +@end table + +@section Configure the Kerberos software + +First configure the client's trust anchors and what parameters to +verify, see subsection below how to do that. Now you can use kinit to +get yourself tickets. One example how that can look like is: + +@example +$ kinit -C FILE:$HOME/.certs/lha.crt,$HOME/.certs/lha.key lha@@EXAMPLE.ORG +Enter your private key passphrase: +: lha@@nutcracker ; klist +Credentials cache: FILE:/tmp/krb5cc_19100a + Principal: lha@@EXAMPLE.ORG + + Issued Expires Principal +Apr 20 02:08:08 Apr 20 12:08:08 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG +@end example + +Using PKCS11 it can look like this instead: + +@example +$ kinit -C PKCS11:/tmp/pkcs11/lib/soft-pkcs11.so lha@@EXAMPLE.ORG +PIN code for SoftToken (slot): +$ klist +Credentials cache: API:4 + Principal: lha@@EXAMPLE.ORG + + Issued Expires Principal +Mar 26 23:40:10 Mar 27 09:40:10 krbtgt/EXAMPLE.ORG@@EXAMPLE.ORG +@end example + + +Write about the kdc. + +@section Configure the client + +@example +[appdefaults] + pkinit_anchors = FILE:/path/to/trust-anchors.pem + +[realms] + EXAMPLE.COM = @{ + pkinit_require_eku = true + pkinit_require_krbtgt_otherName = true + pkinit_win2k = no + pkinit_win2k_require_binding = yes + @} + +@end example + +@section Configure the KDC + +@example +[kdc] + enable-pkinit = yes + pkinit_identity = FILE:/secure/kdc.crt,/secure/kdc.key + pkinit_anchors = FILE:/path/to/trust-anchors.pem + pkinit_pool = PKCS12:/path/to/useful-intermediate-certs.pfx + pkinit_pool = FILE:/path/to/other-useful-intermediate-certs.pem + pkinit_allow_proxy_certificate = false + pkinit_win2k_require_binding = yes +@end example + +@subsection Using pki-mapping file + +Note that the file name is space sensitive. + +@example +# cat /var/heimdal/pki-mapping +# comments starts with # +lha@@EXAMPLE.ORG:C=SE,O=Stockholm universitet,CN=Love,UID=lha +lha@@EXAMPLE.ORG:CN=Love,UID=lha +@end example + +@subsection Using the Kerberos database + +@section Use hxtool to create certificates + +@subsection Generate certificates + +First you need to generate a CA certificate, change the --subject to +something appropriate, the CA certificate will be valid for 10 years. + +You need to change --subject in the command below. + +@example +hxtool issue-certificate \ + --self-signed \ + --issue-ca \ + --generate-key=rsa \ + --subject="CN=CA,DC=test,DC=h5l,DC=se" \ + --lifetime=10years \ + --certificate="FILE:ca.pem" +@end example + +The KDC needs to have a certificate, so generate a certificate of the +type ``pkinit-kdc'' and set the PK-INIT specifial SubjectAltName to the +name of the krbtgt of the realm. + +You need to change --subject and --pk-init-principal in the command below. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-kdc" \ + --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \ + --subject="uid=kdc,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:kdc.pem" +@end example + +The users also needs to have a certificate, so generate a certificate +of the type ``pkinit-client''. The client doesn't need to have the PK-INIT +SubjectAltName set, you can have the Subject DN in the ACL file +(pki-mapping) instead. + +You need to change --subject and --pk-init-principal in the command below. + +@example +hxtool issue-certificate \ + --ca-certificate=FILE:ca.pem \ + --generate-key=rsa \ + --type="pkinit-client" \ + --pk-init-principal="lha@@TEST.H5L.SE" \ + --subject="uid=lha,DC=test,DC=h5l,DC=se" \ + --certificate="FILE:user.pem" +@end example + +@subsection Validate the certificate + +hxtool also contains a tool that will validate certificates according to +rules from the PKIX document. These checks are not complete, but a good test +to check if you got all of the basic bits right in your certificates. + +@example +hxtool validate FILE:user.pem +@end example + +@section Use OpenSSL to create certificates + +This section tries to give the CA owners hints how to create +certificates using OpenSSL (or CA software based on OpenSSL). + +@subsection Using OpenSSL to create certificates with krb5PrincipalName + +To make OpenSSL create certificates with krb5PrincipalName use +@file{openssl.cnf} as described below. To see a complete example of +creating client and KDC certificates, see the test-data generation +script @file{lib/hx509/data/gen-req.sh} in the source-tree. The +certicates it creates are used to test the PK-INIT functionality in +@file{tests/kdc/check-kdc.in}. + +To use this example you have to use OpenSSL 0.9.8a or later. + +@example + +[user_certificate] +subjectAltName=otherName:1.3.6.1.5.2.2;SEQUENCE:princ_name + +[princ_name] +realm = EXP:0, GeneralString:MY.REALM +principal_name = EXP:1, SEQUENCE:principal_seq + +[principal_seq] +name_type = EXP:0, INTEGER:1 +name_string = EXP:1, SEQUENCE:principals + +[principals] +princ1 = GeneralString:userid + +@end example + +Command usage + +@example +openssl x509 -extensions user_certificate +openssl ca -extensions user_certificate +@end example + + +@c --- ms certificate +@c +@c [ new_oids ] +@c msCertificateTemplateName = 1.3.6.1.4.1.311.20.2 +@c +@c +@c [ req_smartcard ] +@c keyUsage = digitalSignature, keyEncipherment +@c extendedKeyUsage = msSmartcardLogin, clientAuth +@c msCertificateTemplateName = ASN1:BMP:SmartcardLogon +@c subjectAltName = otherName:msUPN;UTF8:lukeh@dsg.padl.com +@c #subjectAltName = email:copy + + +@section Using PK-INIT with Windows + +@subsection Client configration + +Clients using a Windows KDC with PK-INIT need configuration since +windows uses pre-standard format and this can't be autodetected. + +The pkinit_win2k_require_binding option requires the reply for the KDC +to be of the new, secure, type that binds the request to reply. Before +clients should fake the reply from the KDC. To use this option you +have to apply a fix from Microsoft. + +@example +[realms] + MY.MS.REALM = @{ + pkinit_win2k = yes + pkinit_win2k_require_binding = no + @} +@end example + +@subsection Certificates + +The client certificates need to have the extended keyusage ``Microsoft +Smartcardlogin'' (openssl have the oid shortname msSmartcardLogin). + +See Microsoft Knowledge Base Article - 281245 ``Guidelines for Enabling +Smart Card Logon with Third-Party Certification Authorities'' for a +more extensive description of how set setup an external CA to it +includes all information that will make a Windows KDC happy. + +@subsection Configure Windows 2000 CA + +To enable Microsoft Smartcardlogin> for certificates in your Windows +2000 CA, you want to look at Microsoft Knowledge Base Article - +313274 ``HOW TO: Configure a Certification Authority to Issue +Smart Card Certificates in Windows''. diff --git a/doc/vars.texi b/doc/vars.texi new file mode 100755 index 000000000000..c2e6671a68eb --- /dev/null +++ b/doc/vars.texi @@ -0,0 +1,7 @@ + +@c +@c Variables depending on installation +@c + +@set dbdir /var/heimdal +@set PACKAGE_VERSION 1.1 diff --git a/doc/vars.tin b/doc/vars.tin new file mode 100644 index 000000000000..d3e67b7d4893 --- /dev/null +++ b/doc/vars.tin @@ -0,0 +1,7 @@ + +@c +@c Variables depending on installation +@c + +@set dbdir @dbdir@ +@set PACKAGE_VERSION @PACKAGE_VERSION@ diff --git a/doc/whatis.texi b/doc/whatis.texi new file mode 100644 index 000000000000..307c5a20877a --- /dev/null +++ b/doc/whatis.texi @@ -0,0 +1,161 @@ +@c $Id: whatis.texi 16769 2006-02-27 12:26:50Z joda $ + +@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} +@html +<sub>\arg\</sub> +@end html +@end macro +@end ifhtml + +@c ifdocbook +@c macro sub{arg} +@c docbook +@c <subscript>\arg\</subscript> +@c end docbook +@c end macro +@c end ifdocbook + +@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 Defence 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/doc/win2k.texi b/doc/win2k.texi new file mode 100644 index 000000000000..7bc9b2a30b81 --- /dev/null +++ b/doc/win2k.texi @@ -0,0 +1,306 @@ +@c $Id: win2k.texi 21991 2007-10-19 13:28:07Z lha $ + +@node Windows 2000 compatability, Programming with Kerberos, 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 that the available documentation is more focused on getting +things to work rather than how they work, and not that useful in figuring +out how things really work. + +This information should apply to Heimdal @value{VERSION} and Windows +2000 Professional. It's of course subject to change all the time and +mostly consists of our not so inspired guesses. Hopefully it's still +somewhat useful. + +@menu +* Configuring Windows 2000 to use a Heimdal KDC:: +* Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC:: +* Create account mappings:: +* Encryption types:: +* Authorisation data:: +* Quirks of Windows 2000 KDC:: +* Useful links when reading about the Windows 2000:: +@end menu + +@node Configuring Windows 2000 to use a Heimdal KDC, Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Windows 2000 compatability, Windows 2000 compatability +@comment node-name, next, precious, up +@section Configuring Windows 2000 to use a Heimdal KDC + +You need the command line program called @command{ksetup.exe} which is available +in the file @file{SUPPORT/TOOLS/SUPPORT.CAB} on the Windows 2000 Professional +CD-ROM. This program is used to configure the Kerberos settings on a +Workstation. + +@command{Ksetup} store the domain information under the registry key: +@code{HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\LSA\Kerberos\Domains}. + +Use the @command{kadmin} program in Heimdal to create a host principal in the +Kerberos realm. + +@example +unix% kadmin +kadmin> ank --password=password host/datan.example.com +@end example + +The name @samp{datan.example.com} should be replaced with DNS name of +the workstation. + +You must configure the workstation as a member of a workgroup, as opposed +to a member in an NT domain, and specify the KDC server of the realm +as follows: +@example +C:> ksetup /setdomain EXAMPLE.COM +C:> ksetup /addkdc EXAMPLE.COM kdc.example.com +@end example + +Set the machine password, i.e.@: create the local keytab: +@example +C:> ksetup /SetComputerPassword password +@end example + +The password used in @kbd{ksetup /setmachpassword} must be the same +as the password used in the @kbd{kadmin ank} command. + +The workstation must now be rebooted. + +A mapping between local NT users and Kerberos principals must be specified. +You have two choices. First: + +@example +C:> ksetup /mapuser user@@MY.REALM nt_user +@end example + +This will map a user to a specific principal; this allows you to have +other usernames in the realm than in your NT user database. (Don't ask +me why on earth you would want that@enddots{}) + +You can also say: +@example +C:> ksetup /mapuser * * +@end example +The Windows machine will now map any user to the corresponding principal, +for example @samp{nisse} to the principal @samp{nisse@@MY.REALM}. +(This is most likely what you want.) + +@node Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Create account mappings, Configuring Windows 2000 to use a Heimdal KDC, Windows 2000 compatability +@comment node-name, next, precious, up +@section Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC + +See also the Step-by-Step guide from Microsoft, referenced below. + +Install Windows 2000, and create a new controller (Active Directory +Server) for the domain. + +By default the trust will be non-transitive. This means that only users +directly from the trusted domain may authenticate. This can be changed +to transitive by using the @command{netdom.exe} tool. @command{netdom.exe} +can also be used to add the trust between two realms. + +You need to tell Windows 2000 on what hosts to find the KDCs for the +non-Windows realm with @command{ksetup}, see @xref{Configuring Windows 2000 +to use a Heimdal KDC}. + +This needs to be done on all computers that want enable cross-realm +login with @code{Mapped Names}. @c XXX probably shouldn't be @code + +Then you need to add the inter-realm keys on the Windows KDC@. Start the +Domain Tree Management tool (found in Programs, Administrative tools, +Active Directory Domains and Trusts). + +Right click on Properties of your domain, select the Trust tab. Press +Add on the appropriate trust windows and enter domain name and +password. When prompted if this is a non-Windows Kerberos realm, press +OK. + +Do not forget to add trusts in both directions (if that's what you want). + +If you want to use @command{netdom.exe} instead of the Domain Tree +Management tool, you do it like this: + +@example +netdom trust NT.REALM.EXAMPLE.COM /Domain:EXAMPLE.COM /add /realm /passwordt:TrustPassword +@end example + +You also need to add the inter-realm keys to the Heimdal KDC. Make sure +you have matching encryption types (DES, Arcfour and AES in case of Longhorn) + +Another issue is salting. Since Windows 2000 does not seem to +understand Kerberos 4 salted hashes you might need to turn off anything +similar to the following if you have it, at least while adding the +principals that are going to share keys with Windows 2000. + +@example +[kadmin] + default_keys = v5 v4 +@end example + +So remove v4 from default keys. + +What you probably want to use is this: + +@example +[kadmin] + default_keys = des-cbc-crc:pw-salt arcfour-hmac-md5:pw-salt +@end example + +@c XXX check this +@c It is definitely not supported in base 2003. I haven't been able to +@c get SP1 installed here, but it is supposed to work in that. + +Once that is also done, you can add the required inter-realm keys: + +@example +kadmin add krbtgt/NT.REALM.EXAMPLE.COM@@EXAMPLE.COM +kadmin add krbtgt/REALM.EXAMPLE.COM@@NT.EXAMPLE.COM +@end example + +Use the same passwords for both keys. + +Do not forget to reboot before trying the new realm-trust (after +running @command{ksetup}). It looks like it might work, but packets are +never sent to the non-Windows KDC. + +@node Create account mappings, Encryption types, Inter-Realm keys (trust) between Windows 2000 and a Heimdal KDC, Windows 2000 compatability +@comment node-name, next, precious, up +@section Create account mappings + +Start the @code{Active Directory Users and Computers} tool. Select the +View menu, that is in the left corner just below the real menu (or press +Alt-V), and select Advanced Features. Right click on the user that you +are going to do a name mapping for and choose Name mapping. + +Click on the Kerberos Names tab and add a new principal from the +non-Windows domain. + +@c XXX check entry name then I have network again +This adds @samp{authorizationNames} entry to the users LDAP entry to +the Active Directory LDAP catalog. When you create users by script you +can add this entry instead. + +@node Encryption types, Authorisation data, Create account mappings, Windows 2000 compatability +@comment node-name, next, previous, up +@section Encryption types + +Windows 2000 supports both the standard DES encryptions (@samp{des-cbc-crc} and +@samp{des-cbc-md5}) and its own proprietary encryption that is based on MD4 and +RC4 that is documented in and is supposed to be described in +@file{draft-brezak-win2k-krb-rc4-hmac-03.txt}. New users will get both +MD4 and DES keys. Users that are converted from a NT4 database, will +only have MD4 passwords and will need a password change to get a DES +key. + +@node Authorisation data, Quirks of Windows 2000 KDC, Encryption types, Windows 2000 compatability +@comment node-name, next, previous, up +@section Authorisation data + +The Windows 2000 KDC also adds extra authorisation data in tickets. +It is at this point unclear what triggers it to do this. The format of +this data is only available under a ``secret'' license from Microsoft, +which prohibits you implementing it. + +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 +@kbd{--dump-auth}=@var{file}} where @var{file} is an appropriate file. +@item It should authenticate and dump for you the authorisation data in +the file. +@item The tool @kbd{lib/asn1/asn1_print} is somewhat useful for +analysing the data. +@end enumerate + +@node Quirks of Windows 2000 KDC, Useful links when reading about the Windows 2000, Authorisation data, Windows 2000 compatability +@comment node-name, next, previous, up +@section Quirks of Windows 2000 KDC + +There are some issues with salts and Windows 2000. Using an empty salt---which is the only one that Kerberos 4 supported, and is therefore known +as a Kerberos 4 compatible salt---does not work, as far as we can tell +from out experiments and users' reports. Therefore, you have to make +sure you keep around keys with all the different types of salts that are +required. Microsoft have fixed this issue post Windows 2003. + +Microsoft seems also to have forgotten to implement the checksum +algorithms @samp{rsa-md4-des} and @samp{rsa-md5-des}. This can make Name +mapping (@pxref{Create account mappings}) fail if a @samp{des-cbc-md5} key +is used. To make the KDC return only @samp{des-cbc-crc} you must delete +the @samp{des-cbc-md5} key from the kdc using the @kbd{kadmin +del_enctype} command. + +@example +kadmin del_enctype lha des-cbc-md5 +@end example + +You should also add the following entries to the @file{krb5.conf} file: + +@example +[libdefaults] + default_etypes = des-cbc-crc + default_etypes_des = des-cbc-crc +@end example + +These configuration options will make sure that no checksums of the +unsupported types are generated. + +@node Useful links when reading about the Windows 2000, , Quirks of Windows 2000 KDC, Windows 2000 compatability +@comment node-name, next, previous, up +@section Useful links when reading about the Windows 2000 + +See also our paper presented at the 2001 Usenix Annual Technical +Conference, available in the proceedings or at +@uref{http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/westerlund.html}. + +There are lots of texts about Kerberos on Microsoft's web site, here is a +short list of the interesting documents that we have managed to find. + +@itemize @bullet + +@item Step-by-Step Guide to Kerberos 5 (krb5 1.0) Interoperability: +@uref{http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/kerbstep.mspx}. +Kerberos GSS-API (in Windows-eze SSPI), Windows as a client in a +non-Windows KDC realm, adding unix clients to a Windows 2000 KDC, and +adding cross-realm trust (@pxref{Inter-Realm keys (trust) between Windows 2000 +and a Heimdal KDC}). + +@item Windows 2000 Kerberos Authentication: +@uref{www.microsoft.com/technet/prodtechnol/windows2000serv/deploy/confeat/kerberos.mspx}. +White paper that describes how Kerberos is used in Windows 2000. + +@item Overview of Kerberos: +@uref{http://support.microsoft.com/support/kb/articles/Q248/7/58.ASP}. +Links to useful other links. + +@c @item Klist for Windows: +@c @uref{http://msdn.microsoft.com/library/periodic/period00/security0500.htm}. +@c Describes where to get a klist for Windows 2000. + +@item Event logging for Kerberos: +@uref{http://support.microsoft.com/support/kb/articles/Q262/1/77.ASP}. +Basically it say that you can add a registry key +@code{HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters\LogLevel} +with value DWORD equal to 1, and then you'll get logging in the Event +Logger. + +@c @item Access to the Active Directory through LDAP: +@c @uref{http://msdn.microsoft.com/library/techart/kerberossamp.htm} + +@end itemize + +Other useful programs include these: + +@itemize @bullet +@item pwdump2 +@uref{http://www.bindview.com/Support/RAZOR/Utilities/Windows/pwdump2_readme.cfm}@end itemize |