aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorStanislav Sedov <stas@FreeBSD.org>2011-09-29 05:23:57 +0000
committerStanislav Sedov <stas@FreeBSD.org>2011-09-29 05:23:57 +0000
commit31f1e9c17ffae440059e8cc532fa26b92d534f7b (patch)
treecf5b65423910d126fddaaf04b885d0de3507d692 /doc
parentc19800e8cd5640693f36f2040db4ab5e8d738146 (diff)
downloadsrc-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.am85
-rw-r--r--doc/Makefile.in982
-rw-r--r--doc/ack.texi72
-rw-r--r--doc/apps.texi244
-rw-r--r--doc/doxytmpl.dxy257
-rw-r--r--doc/hcrypto.din15
-rw-r--r--doc/heimdal.css53
-rw-r--r--doc/heimdal.texi370
-rw-r--r--doc/hx509.din15
-rw-r--r--doc/hx509.texi633
-rw-r--r--doc/init-creds374
-rw-r--r--doc/install.texi107
-rw-r--r--doc/intro.texi99
-rw-r--r--doc/kerberos4.texi226
-rw-r--r--doc/krb5.din16
-rw-r--r--doc/latin1.tex95
-rw-r--r--doc/layman.asc1855
-rwxr-xr-xdoc/mdate-sh92
-rw-r--r--doc/migration.texi43
-rw-r--r--doc/misc.texi58
-rw-r--r--doc/ntlm.din15
-rw-r--r--doc/programming.texi642
-rw-r--r--doc/setup.texi1455
-rwxr-xr-xdoc/vars.texi7
-rw-r--r--doc/vars.tin7
-rw-r--r--doc/whatis.texi161
-rw-r--r--doc/win2k.texi306
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