Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

36 files changed, 7760 insertions, 0 deletions

diff --git a/third_party/heimdal/doc/Makefile.am b/third_party/heimdal/doc/Makefile.am
new file mode 100644
index 0000000..ed95c30
--- /dev/null
+++ b/third_party/heimdal/doc/Makefile.am
@@ -0,0 +1,163 @@
+# $Id$
+
+include $(top_srcdir)/Makefile.am.common
+
+AUTOMAKE_OPTIONS = no-texinfo.tex
+
+MAKEINFOFLAGS = --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'
+
+hcrypto.dxy: hcrypto.din Makefile
+	$(dxy_subst) < $(srcdir)/hcrypto.din > hcrypto.dxy.tmp
+	chmod +x hcrypto.dxy.tmp
+	mv hcrypto.dxy.tmp hcrypto.dxy
+
+hdb.dxy: hdb.din Makefile
+	$(dxy_subst) < $(srcdir)/hdb.din > hdb.dxy.tmp
+	chmod +x hdb.dxy.tmp
+	mv hdb.dxy.tmp hdb.dxy
+
+base.dxy: base.din Makefile
+	$(dxy_subst) < $(srcdir)/base.din > base.dxy.tmp
+	chmod +x base.dxy.tmp
+	mv base.dxy.tmp base.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
+
+gssapi.dxy: gssapi.din Makefile
+	$(dxy_subst) < $(srcdir)/gssapi.din > gssapi.dxy.tmp
+	chmod +x gssapi.dxy.tmp
+	mv gssapi.dxy.tmp gssapi.dxy
+
+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
+
+wind.dxy: wind.din Makefile
+	$(dxy_subst) < $(srcdir)/wind.din > wind.dxy.tmp
+	chmod +x wind.dxy.tmp
+	mv wind.dxy.tmp wind.dxy
+
+texi_subst = sed -e 's,[@]dbdir[@],$(localstatedir),g' \
+	-e 's,[@]dbtype[@],$(db_type),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
+
+PROJECTS = base hdb hx509 gssapi krb5 ntlm wind 
+
+PROJECTS += hcrypto
+
+doxyout doxygen: base.dxy hdb.dxy hx509.dxy hcrypto.dxy gssapi.dxy krb5.dxy ntlm.dxy wind.dxy
+	@test -d $(srcdir)/doxyout && \
+	find $(srcdir)/doxyout -type d ! -perm -200 -exec chmod u+w {} ';' ; \
+	rm -rf $(srcdir)/doxyout ; \
+	mkdir $(srcdir)/doxyout ; \
+	for a in $(PROJECTS) ; do \
+		echo $$a ; \
+		doxygen $$a.dxy; \
+		(cd $(srcdir)/doxyout && \
+		    find $$a/man -name '_*' -type f -print | \
+			perl -lne unlink && \
+		    find $$a/html -name 'dir_*.html' -type f -print | \
+			perl -lne unlink && \
+		 find $$a/man -type f > $$a/manpages ) ; \
+	done
+
+install-data-hook: install-doxygen-manpage
+uninstall-hook: uninstall-doxygen-manpage
+dist-hook: doxygen
+
+install-doxygen-manpage:
+	for a in $(PROJECTS) ; do \
+		f="$(srcdir)/doxyout/$$a/manpages" ; \
+		test -f $$f || continue ; \
+		echo "install $$a manual pages $$(wc -l < $$f)" ; \
+		while read x ; do \
+			section=`echo "$$x" | sed 's/.*\.\([0-9]\)/\1/'` ; \
+			$(mkinstalldirs) "$(DESTDIR)$(mandir)/man$$section" ; \
+			$(INSTALL_DATA) $(srcdir)/doxyout/$$x "$(DESTDIR)$(mandir)/man$$section" ; \
+		done < $$f ; \
+	done ; exit 0
+
+uninstall-doxygen-manpage:
+	@for a in $(PROJECTS) ; do \
+		f="$(srcdir)/doxyout/$$a/manpages" ; \
+		test -f $$f || continue ; \
+		echo "removing $$a manual pages" ; \
+		while read x ; do \
+			section=`echo "$$x" | sed 's/.*\.\([0-9]\)/\1/'` ; \
+			base=`basename $$x` ; \
+			rm "$(DESTDIR)$(mandir)/man$$section/$$base" ; \
+		done < $$f ; \
+	done
+
+
+heimdal_TEXINFOS = \
+	ack.texi \
+	apps.texi \
+	copyright.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 = \
+	NTMakefile \
+	doxyout \
+	footer.html \
+	gssapi.din \
+	hdb.din \
+	hcrypto.din \
+	header.html \
+	heimdal.css \
+	base.din \
+	hx509.din \
+	krb5.din \
+	ntlm.din \
+	init-creds \
+	latin1.tex \
+	layman.asc \
+	doxytmpl.dxy \
+	wind.din \
+	base.hhp \
+	heimdal.hhp \
+	hx509.hhp \
+	vars.tin
+
+CLEANFILES = \
+	hcrypto.dxy* \
+	base.dxy* \
+	hx509.dxy* \
+	hdb.dxy* \
+	gssapi.dxy* \
+	krb5.dxy* \
+	ntlm.dxy* \
+	wind.dxy* \
+	vars.texi*
diff --git a/third_party/heimdal/doc/NTMakefile b/third_party/heimdal/doc/NTMakefile
new file mode 100644
index 0000000..0299620
--- /dev/null
+++ b/third_party/heimdal/doc/NTMakefile
@@ -0,0 +1,126 @@
+########################################################################
+#
+# Copyright (c) 2009, Secure Endpoints Inc.
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 
+# - Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+# 
+# - 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 COPYRIGHT HOLDERS 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
+# COPYRIGHT HOLDER 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.
+# 
+
+RELDIR=doc 
+
+!include ../windows/NTMakefile.w32 
+
+heimdal_TEXINFOS = \
+	$(OBJ)\ack.texi \
+	$(OBJ)\apps.texi \
+	$(OBJ)\copyright.texi \
+	$(OBJ)\heimdal.texi \
+	$(OBJ)\install.texi \
+	$(OBJ)\intro.texi \
+	$(OBJ)\kerberos4.texi \
+	$(OBJ)\migration.texi \
+	$(OBJ)\misc.texi \
+	$(OBJ)\programming.texi \
+	$(OBJ)\setup.texi \
+	$(OBJ)\vars.texi \
+	$(OBJ)\whatis.texi \
+	$(OBJ)\win2k.texi
+
+hx509_TEXINFOS = \
+	$(OBJ)\hx509.texi
+
+{}.texi{$(OBJ)}.texi:
+	$(CP) $** $@
+
+{}.tin{$(OBJ)}.texi:
+	$(SED) -e "s,[@]dbdir[@],x,g"	\
+	-e "s,[@]dbtype[@],sqlite,g" < $** > $@ \
+	-e "s,[@]PACKAGE_VERSION[@],$(VER_PACKAGE_VERSION),g" < $** > $@
+
+MAKEINFOFLAGS = --css-include=$(SRCDIR)/heimdal.css
+
+!ifdef APPVEYOR
+MAKEINFO = $(PERL) C:\msys64\usr\bin\makeinfo
+!endif
+
+######################################################################
+# Build heimdal.chm
+
+# Copyrights-and-Licenses.html is where the table of contents ends up
+# when generating HTML output using makeinfo.  Same goes for
+# How-to-use-the-PKCS11-module.html below.
+
+$(OBJ)\heimdal\index.html $(OBJ)\heimdal\Copyrights-and-Licenses.html: $(heimdal_TEXINFOS)
+	cd $(OBJ)
+	$(MAKEINFO) $(MAKEINFOFLAGS) --html heimdal.texi
+	-$(MKDIR) heimdal
+	cd $(SRCDIR)
+
+$(OBJ)\heimdal\toc.hhc: $(OBJ)\heimdal\Copyrights-and-Licenses.html
+	$(PERL) $(SRC)\cf\w32-hh-toc-from-info.pl -o$@ $**
+
+$(OBJ)\heimdal\heimdal.hhp: heimdal.hhp
+	$(CP) $** $@
+
+$(DOCDIR)\heimdal.chm: $(OBJ)\heimdal\heimdal.hhp $(OBJ)\heimdal\toc.hhc
+	cd $(OBJ)\heimdal
+	-$(HHC) heimdal.hhp
+	$(CP) heimdal.chm $@
+	cd $(SRCDIR)
+
+######################################################################
+# Build hx509.chm
+
+$(OBJ)\hx509\index.html $(OBJ)\hx509\How-to-use-the-PKCS11-module.html: $(hx509_TEXINFOS)
+	cd $(OBJ)
+	$(MAKEINFO) $(MAKEINFOFLAGS) --html hx509.texi
+	-$(MKDIR) hx509
+	cd $(SRCDIR)
+
+$(OBJ)\hx509\toc.hhc: $(OBJ)\hx509\How-to-use-the-PKCS11-module.html
+	$(PERL) $(SRC)\cf\w32-hh-toc-from-info.pl -o$@ $**
+
+$(OBJ)\hx509\hx509.hhp: hx509.hhp
+	$(CP) $** $@
+
+$(DOCDIR)\hx509.chm: $(OBJ)\hx509\hx509.hhp $(OBJ)\hx509\toc.hhc
+	cd $(OBJ)\hx509
+	-$(HHC) hx509.hhp
+	$(CP) hx509.chm $@
+	cd $(SRCDIR)
+
+!ifndef NO_DOC
+all:: $(OBJ)\heimdal\index.html $(OBJ)\hx509\index.html \
+	$(DOCDIR)\heimdal.chm $(DOCDIR)\hx509.chm
+!endif
+
+clean::
+	-$(RM) $(OBJ)\heimdal\*.*
+	-$(RM) $(OBJ)\hx509\*.*
+	-$(RM) $(DOCDIR)\heimdal.chm
+	-$(RM) $(DOCDIR)\hx509.chm
+
+.SUFFIXES: .texi .tin
diff --git a/third_party/heimdal/doc/ack.texi b/third_party/heimdal/doc/ack.texi
new file mode 100644
index 0000000..89b83c1
--- /dev/null
+++ b/third_party/heimdal/doc/ack.texi
@@ -0,0 +1,124 @@
+@node  Acknowledgments, Copyrights and Licenses, 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 Allan McRae
+@item Andrew Bartlett
+@item Andrew Cobaugh
+@item Andrew Tridge
+@item Anton Lundin
+@item Asanka Herath
+@item Björn Grönvall
+@item Björn Sandell
+@item Björn Schlögl
+@item Brandon S. Allbery KF8NH
+@item Brian A May
+@item Buck Huppmann
+@item Cacdric Schieli
+@item Chaskiel M Grundman
+@item Christos Zoulas
+@item Cizzi Storm
+@item Daniel Kouril
+@item David Love
+@item David Markey
+@item David R Boldt
+@item Derrick J Brashear
+@item Donald Norwood
+@item Douglas E Engert
+@item Frank van der Linden
+@item Gabor Gombas
+@item Guido Günther
+@item Guillaume Rousse
+@item Harald Barth
+@item Ingo Schwarze
+@item Jacques A. Vidrine
+@item Jaideep Padhye
+@item Jan Rekorajski
+@item Jason McIntyre
+@item Jeffrey Altman
+@item Jelmer Vernooij
+@item Joerg Pulz
+@item Johan Danielsson
+@item Johan Gadsjö
+@item Johan Ihrén
+@item John Center
+@item Julian Ospald
+@item Jun-ichiro itojun Hagino
+@item KAMADA Ken'ichi
+@item Kamen Mazdrashki
+@item Karolin Seeger
+@item Ken Hornstein
+@item Love Hörnquist Åstrand
+@item Luke Howard
+@item Magnus Ahltorp
+@item Magnus Holmberg
+@item Marc Horowitz
+@item Mario Strasser
+@item Mark Eichin
+@item Martin von Gagern
+@item Matthias Dieter Wallnöfer
+@item Matthieu Patou
+@item Mattias Amnefelt
+@item Michael B Allen
+@item Michael Fromberger
+@item Michal Vocu
+@item Milosz Kmieciak
+@item Miroslav Ruda
+@item Mustafa A. Hashmi
+@item Nicolas Williams
+@item Patrik Lundin
+@item Petr Holub
+@item Phil Fisher
+@item Rafal Malinowski
+@item Ragnar Sundblad
+@item Rainer Toebbicke
+@item Richard Nyberg
+@item Roland C. Dowdeswell
+@item Roman Divacky
+@item Russ Allbery
+@item Sho Hosoda, 細田 将
+@item Simon Wilkinson
+@item Stefan Metzmacher
+@item Ted Percival
+@item Timothy Pearson
+@item Tom Payerle
+@item Victor Guerra
+@item Zeqing Xia
+@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/third_party/heimdal/doc/apps.texi b/third_party/heimdal/doc/apps.texi
new file mode 100644
index 0000000..98585c4
--- /dev/null
+++ b/third_party/heimdal/doc/apps.texi
@@ -0,0 +1,270 @@
+@c $Id$
+
+@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 kafs and afslog
+@cindex afslog
+
+@manpage{afslog,1} will obtains AFS tokens for a number of cells. What cells to get
+tokens for can either be specified as an explicit list, as file paths to
+get tokens for, or be left unspecified, in which case will use whatever
+magic @manpage{kafs,3} decides upon.
+
+If not told what cell to get credentials for, @manpage{kafs,3} will
+search for the files ThisCell and TheseCells in the locations
+specified in @manpage{kafs,3} and try to get tokens for these cells
+and the cells specified in $HOME/.TheseCells.
+
+More usefully it will look at and ~/.TheseCells in your home directory
+and for each line which is a cell get afs token for these cells.
+
+The TheseCells file defines the the cells to which applications on the
+local client machine should try to aquire tokens for. It must reside in
+the directories searched by @manpage{kafs,3} on every AFS client machine.
+
+The file is in ASCII format and contains one character string, the cell
+name, per line. Cell names are case sensitive, but most cell names
+are lower case.
+
+See manpage for @manpage{kafs,3} for search locations of ThisCell and TheseCells.
+
+@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/third_party/heimdal/doc/base.din b/third_party/heimdal/doc/base.din
new file mode 100644
index 0000000..3ef6d40
--- /dev/null
+++ b/third_party/heimdal/doc/base.din
@@ -0,0 +1,15 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal base library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/base
+INPUT                  = @srcdir@/../lib/base
+
+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/third_party/heimdal/doc/base.hhp b/third_party/heimdal/doc/base.hhp
new file mode 100644
index 0000000..e1a3d3c
--- /dev/null
+++ b/third_party/heimdal/doc/base.hhp
@@ -0,0 +1,8 @@
+[OPTIONS]
+Compatibility=1.1 or later
+Compiled file=heimbase.chm
+Contents file=toc.hhc
+Default topic=index.html
+Display compile progress=No
+Language=0x409 English (United States)
+Title=Heimdal Base
diff --git a/third_party/heimdal/doc/copyright.texi b/third_party/heimdal/doc/copyright.texi
new file mode 100644
index 0000000..d9f1a8c
--- /dev/null
+++ b/third_party/heimdal/doc/copyright.texi
@@ -0,0 +1,521 @@
+
+@macro copynext{} 
+@vskip 20pt plus 1fil
+@end macro
+
+@macro copyrightstart{}
+@end macro
+
+@macro copyrightend{}
+@end macro
+
+
+@node  Copyrights and Licenses, , Acknowledgments, Top
+@comment  node-name,  next,  previous,  up
+@appendix Copyrights and Licenses
+
+@heading Kungliga Tekniska Högskolan
+
+@copyrightstart
+@verbatim
+
+Copyright (c) 1997-2011 Kungliga Tekniska Högskolan 
+(Royal Institute of Technology, Stockholm, Sweden).
+All rights reserved.
+
+Portions Copyright (c) 2009 Apple Inc. 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.
+
+@end verbatim
+@copynext
+
+@heading Massachusetts Institute of Technology
+
+The parts of the libtelnet that handle Kerberos.
+
+@verbatim
+
+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.
+
+@end verbatim
+@copynext
+
+@heading The Regents of the University of California
+
+The parts of the libroken, most of libtelnet, telnet, ftp,
+and popper.
+
+@verbatim
+
+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.
+
+@end verbatim
+@copynext
+
+@heading The Regents of the University of California.
+
+libedit
+
+@verbatim
+
+Copyright (c) 1992, 1993
+ The Regents of the University of California.  All rights reserved.
+
+This code is derived from software contributed to Berkeley by
+Christos Zoulas of Cornell University.
+
+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.
+
+@end verbatim
+@copynext
+
+@heading TomsFastMath / LibTomMath
+
+Tom's fast math (bignum support) and LibTomMath
+
+@verbatim
+
+LibTomMath is hereby released into the Public Domain.  
+
+@end verbatim 
+
+@copynext
+
+@heading Doug Rabson
+
+GSS-API mechglue layer.
+
+@verbatim
+
+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.
+
+@end verbatim
+@copynext
+
+@heading PADL Software Pty Ltd
+
+@table @asis
+@item GSS-API CFX, SPNEGO, naming extensions, API extensions.
+@item KCM credential cache.
+@item HDB LDAP backend.
+@end table
+
+@verbatim
+
+Copyright (c) 2003-2011, PADL Software Pty Ltd.
+Copyright (c) 2004, Andrew Bartlett.
+Copyright (c) 2003 - 2008, Kungliga Tekniska Högskolan
+Copyright (c) 2015, Timothy Pearson.
+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 PADL Software 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 PADL SOFTWARE 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 PADL SOFTWARE 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.
+
+@end verbatim
+@copynext
+
+@heading Marko Kreen
+
+Fortuna in libhcrypto
+
+@verbatim
+
+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.
+
+@end verbatim
+@copynext
+
+@heading NTT (Nippon Telegraph and Telephone Corporation)
+
+Camellia in libhcrypto
+
+@verbatim
+
+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.
+
+@end verbatim
+@copynext
+
+@heading The NetBSD Foundation, Inc.
+
+vis.c in libroken
+
+@verbatim
+
+Copyright (c) 1999, 2005 The NetBSD Foundation, Inc.
+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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+
+@end verbatim
+@copynext
+
+@heading Vincent Rijmen, Antoon Bosselaers, Paulo Barreto
+
+AES in libhcrypto
+
+@verbatim
+
+rijndael-alg-fst.c
+
+@version 3.0 (December 2000)
+
+Optimised ANSI C code for the Rijndael cipher (now AES)
+
+@author Vincent Rijmen <vincent.rijmen@esat.kuleuven.ac.be>
+@author Antoon Bosselaers <antoon.bosselaers@esat.kuleuven.ac.be>
+@author Paulo Barreto <paulo.barreto@terra.com.br>
+
+This code is hereby placed in the public domain.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ''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 AUTHORS 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.
+
+@end verbatim
+@copynext
+
+@heading Apple, Inc
+
+kdc/announce.c
+
+@verbatim
+
+Copyright (c) 2008 Apple Inc.  All Rights Reserved.
+
+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 Apple Inc. not be used in advertising or publicity pertaining
+to distribution of the software without specific, written prior
+permission.  Apple Inc. makes no representations about the suitability of
+this software for any purpose.  It is provided "as is" without express
+or implied warranty.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+@end verbatim
+
+@copynext
+
+@heading Richard Outerbridge
+
+DES core in libhcrypto
+
+@verbatim
+
+D3DES (V5.09) - 
+
+A portable, public domain, version of the Data Encryption Standard.
+
+Written with Symantec's THINK (Lightspeed) C by Richard Outerbridge.
+Thanks to: Dan Hoey for his excellent Initial and Inverse permutation
+code;  Jim Gillogly & Phil Karn for the DES key schedule code; Dennis
+Ferguson, Eric Young and Dana How for comparing notes; and Ray Lau,
+for humouring me on. 
+
+Copyright (c) 1988,1989,1990,1991,1992 by Richard Outerbridge.
+(GEnie : OUTER; CIS : [71755,204]) Graven Imagery, 1992.
+
+
+@end verbatim
+
+@copynext
+
+@heading Secure Endpoints Inc
+
+Windows support
+
+@verbatim
+
+Copyright (c) 2009-2015, Secure Endpoints Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+- 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 COPYRIGHT HOLDERS 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
+COPYRIGHT HOLDER 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.
+
+@end verbatim
+
+@copynext
+
+@heading Novell, Inc
+
+lib/hcrypto/test_dh.c
+
+@verbatim
+
+Copyright (c) 2007, Novell, Inc.
+Author: Matthias Koenig <mkoenig@suse.de>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of the Novell 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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.
+
+
+@end verbatim
+
+@copyrightend
diff --git a/third_party/heimdal/doc/doxytmpl.dxy b/third_party/heimdal/doc/doxytmpl.dxy
new file mode 100644
index 0000000..1faab2f
--- /dev/null
+++ b/third_party/heimdal/doc/doxytmpl.dxy
@@ -0,0 +1,248 @@
+#---------------------------------------------------------------------------
+# 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
+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
+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
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = */.svn
+EXCLUDE_SYMBOLS        = 
+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        = 
+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_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             = DOXY
+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
+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
+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/third_party/heimdal/doc/footer.html b/third_party/heimdal/doc/footer.html
new file mode 100644
index 0000000..48990ae
--- /dev/null
+++ b/third_party/heimdal/doc/footer.html
@@ -0,0 +1,4 @@
+<hr size="1"><address style="text-align: right;"><small>
+Generated on $datetime for $projectname by&nbsp;<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> $doxygenversion</small></address>
+</body>
+</html>
diff --git a/third_party/heimdal/doc/gssapi.din b/third_party/heimdal/doc/gssapi.din
new file mode 100644
index 0000000..3dd8bb6
--- /dev/null
+++ b/third_party/heimdal/doc/gssapi.din
@@ -0,0 +1,16 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal GSS-API library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/gssapi
+INPUT                  = @srcdir@/../lib/gssapi
+
+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/third_party/heimdal/doc/hcrypto.din b/third_party/heimdal/doc/hcrypto.din
new file mode 100644
index 0000000..aeea179
--- /dev/null
+++ b/third_party/heimdal/doc/hcrypto.din
@@ -0,0 +1,16 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = "Heimdal crypto library"
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/hcrypto
+INPUT                  = @srcdir@/../lib/hcrypto
+EXAMPLE_PATH	       = @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/third_party/heimdal/doc/hdb.din b/third_party/heimdal/doc/hdb.din
new file mode 100644
index 0000000..1b100f4
--- /dev/null
+++ b/third_party/heimdal/doc/hdb.din
@@ -0,0 +1,15 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal hdb library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/hdb
+INPUT                  = @srcdir@/../lib/hdb
+
+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/third_party/heimdal/doc/header.html b/third_party/heimdal/doc/header.html
new file mode 100644
index 0000000..b3401c8
--- /dev/null
+++ b/third_party/heimdal/doc/header.html
@@ -0,0 +1,10 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
+<title>$title</title>
+<link href="$relpath$doxygen.css" rel="stylesheet" type="text/css">
+<link href="$relpath$tabs.css" rel="stylesheet" type="text/css">
+</head><body>
+<p>
+<a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a>
+</p>
+<!-- end of header marker -->
diff --git a/third_party/heimdal/doc/heimdal.css b/third_party/heimdal/doc/heimdal.css
new file mode 100644
index 0000000..2e5b374
--- /dev/null
+++ b/third_party/heimdal/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/third_party/heimdal/doc/heimdal.hhp b/third_party/heimdal/doc/heimdal.hhp
new file mode 100644
index 0000000..2996baa
--- /dev/null
+++ b/third_party/heimdal/doc/heimdal.hhp
@@ -0,0 +1,8 @@
+[OPTIONS]
+Compatibility=1.1 or later
+Compiled file=heimdal.chm
+Contents file=toc.hhc
+Default topic=index.html
+Display compile progress=No
+Language=0x409 English (United States)
+Title=Heimdal
\ No newline at end of file
diff --git a/third_party/heimdal/doc/heimdal.texi b/third_party/heimdal/doc/heimdal.texi
new file mode 100644
index 0000000..c8ef249
--- /dev/null
+++ b/third_party/heimdal/doc/heimdal.texi
@@ -0,0 +1,153 @@
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@c $Id$
+@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 VERSION @value{PACKAGE_VERSION}
+@set EDITION 1.0
+
+@ifinfo
+@dircategory Security
+@direntry
+* Heimdal: (heimdal).           The Kerberos 5 and PKIX distribution from KTH
+@end direntry
+@end ifinfo
+
+@c title page
+@titlepage
+@title Heimdal
+@subtitle Kerberos 5 and PKIX from KTH
+@subtitle Edition @value{EDITION}, for version @value{VERSION}
+@subtitle 2008
+@author Johan Danielsson
+@author Love Hörnquist Åstrand
+@author Assar Westerlund
+@author et al
+
+@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 for version @value{VERSION} of Heimdal.
+
+@menu
+* Introduction::                
+* What is Kerberos?::           
+* What is PKIX?::           
+* What is a Certification Authority (CA)?::           
+* What is kx509?::           
+* What is bx509?::           
+* Building and Installing::     
+* Setting up a realm::          
+* Applications::                
+* Things in search for a better place::  
+* Kerberos 4 issues::           
+* Windows compatibility::  
+* Programming with Kerberos::   
+* Migration::                   
+* Acknowledgments::             
+* Copyrights and Licenses::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Setting up a realm
+
+* Configuration file::          
+* Creating the database::       
+* Modifying the database::      
+* keytabs::                     
+* Remote administration::       
+* Password changing::           
+* Testing clients and servers::  
+* Slave Servers::               
+* Incremental propagation::     
+* Encryption types and salting::                     
+* Credential cache server - KCM::
+* Cross realm::                 
+* Transit policy::              
+* Setting up DNS::              
+* Using LDAP to store the database::  
+* Providing Kerberos credentials to servers and programs::  
+* Setting up PK-INIT::
+* Debugging Kerberos problems::
+
+Applications
+
+* Authentication modules::      
+* AFS::                         
+
+Authentication modules
+
+* Digital SIA::                 
+* IRIX::                        
+
+Kerberos 4 issues
+
+* Principal conversion issues::  
+* Converting a version 4 database::  
+
+Windows compatibility
+
+* Configuring Windows to use a Heimdal KDC::  
+* Inter-Realm keys (trust) between Windows and a Heimdal KDC::  
+* Create account mappings::     
+* Encryption types::            
+* Authorisation data::          
+* Quirks of Windows 2000 KDC::  
+* Useful links when reading about the Windows::  
+
+Programming with Kerberos
+
+@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
+@include copyright.texi
+
+@c @shortcontents
+@contents
+
+@bye
diff --git a/third_party/heimdal/doc/hx509.din b/third_party/heimdal/doc/hx509.din
new file mode 100644
index 0000000..c6d02b2
--- /dev/null
+++ b/third_party/heimdal/doc/hx509.din
@@ -0,0 +1,15 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal x509 library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/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/third_party/heimdal/doc/hx509.hhp b/third_party/heimdal/doc/hx509.hhp
new file mode 100644
index 0000000..bce680a
--- /dev/null
+++ b/third_party/heimdal/doc/hx509.hhp
@@ -0,0 +1,8 @@
+[OPTIONS]
+Compatibility=1.1 or later
+Compiled file=hx509.chm
+Contents file=toc.hhc
+Default topic=index.html
+Display compile progress=No
+Language=0x409 English (United States)
+Title=HX509
\ No newline at end of file
diff --git a/third_party/heimdal/doc/hx509.texi b/third_party/heimdal/doc/hx509.texi
new file mode 100644
index 0000000..0a90cb7
--- /dev/null
+++ b/third_party/heimdal/doc/hx509.texi
@@ -0,0 +1,786 @@
+\input texinfo @c -*- texinfo -*-
+@c %**start of header
+@c $Id$
+@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
+
+@include vars.texi
+
+@set VERSION @value{PACKAGE_VERSION}
+@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 2008
+@author Love Hörnquist Åstrand
+
+@iftex
+@def@copynext{@vskip 20pt plus 1fil}
+@def@copyrightstart{}
+@def@copyrightend{}
+@end iftex
+@macro copynext
+@end macro
+@macro copyrightstart
+@end macro
+@macro copyrightend
+@end macro
+
+@page
+@copyrightstart
+Copyright (c) 1994-2019 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) 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 for version @value{VERSION} of hx509.
+
+@menu
+* Introduction::
+* What are X.509 and PKIX ?::
+* Setting up a CA::
+* CMS signing and encryption::
+* Certificate matching::
+* Software PKCS 11 module::
+* Creating a CA certificate::
+* Issuing certificates::
+* Issuing CRLs::
+* Application requirements::
+* CMS background::
+* Matching syntax::
+* How to use the PKCS11 module::
+
+@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::
+
+Certificate matching
+
+* Matching syntax::
+
+Software PKCS 11 module
+
+* How to use the PKCS11 module::
+
+@end detailmenu
+@end menu
+
+@node Introduction, What are X.509 and PKIX ?, Top, Top
+@chapter Introduction
+
+A Public Key Infrastructure (PKI) is an authentication mechanism based on
+entities having certified cryptographic public keys and corresponding private
+(secret) keys.
+
+The ITU-T PKI specifications are designated "x.509", while the IETF PKI
+specifications (PKIX) are specified by a number of Internet RFCs and are based
+on x.509.
+
+The goals of a PKI (as stated in 
+<a href="http://www.ietf.org/rfc/rfc5280.txt">RFC 5280</a>) is to meet 
+@emph{the needs of deterministic, automated identification, authentication, access control, and authorization}.
+
+The administrator should be aware of certain terminologies as explained by the aforementioned
+RFC before attemping to put in place a PKI infrastructure. Briefly, these are: 
+
+@itemize @bullet
+@item CA
+Certificate Authority
+@item RA
+Registration Authority, i.e., an optional system to which a CA delegates certain management functions.
+@item Certificate
+A binary document that names an entity and its public key and which is signed
+by an issuing CA.
+@item CRL Issuer
+An optional system to which a CA delegates the publication of certificate revocation lists.
+@item Repository
+A system or collection of distributed systems that stores certificates and CRLs 
+and serves as a means of distributing these certificates and CRLs to end entities
+@end itemize
+
+hx509 (Heimdal x509 support) is a near complete X.509/PKIX 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, and/or DER encoded
+files.
+
+hx509 consists of a library (libhx509) and a command-line utility (hxtool), as
+well as a RESTful, HTTPS-based service that implements an online CA.
+
+@node What are X.509 and PKIX ?, Setting up a CA, Introduction, Top
+@chapter What are X.509 and PKIX, PKIX, PKCS7 and CMS ? 
+
+X.509 was created by CCITT (later ITU-T) for the X.500 directory
+service. Today, X.509 discussions and implementations commonly reference
+the 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 with the IETF in a 
+rather complicated dance.
+
+X.509 is a public key based security system that has associated data
+stored within a so called certificate. Initially, X.509 was a strict
+hierarchical system with one root. However, ever evolving requiments and
+technology advancements saw the inclusion of multiple policy roots,
+bridges and mesh solutions.
+
+x.509 can also be used as a peer to peer system, though often seen as a
+common scenario.
+
+@section Type of certificates
+
+There are several flavors of certificate in X.509.
+
+@itemize @bullet
+
+@item Trust anchors
+
+Trust anchors are strictly not certificates, but commonly stored in a
+certificate format as they become easier to manage. Trust anchors are
+the keys that an end entity would trust to validate other certificates.
+This is done by building a path from the certificate you want to
+validate to to any of the trust anchors you have.
+
+@item End Entity (EE) certificates
+
+End entity certificates are the most common types of certificates. End
+entity certificates cannot issue (sign) certificate themselves and are generally
+used to authenticate and authorize users and services.
+
+@item Certification Authority (CA) certificates
+
+Certificate authority certificates have the right to issue additional
+certificates (be it sub-ordinate CA certificates to build an trust anchors
+or end entity 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 the statement "End Entity certificates cannot issue
+certificates"?  Well that statement is not entirely true. 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 policies 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 when the
+print service initializes (without any user intervention), access to the files 
+for the print job is granted via the proxy certificate. As a result of (in-place) 
+policy limitations, the certificate cannot be used for any other purposes.
+
+@end itemize
+
+@section Building a path
+
+Before validating a certificate path (or chain), the path needs to 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.
+
+The process starts by looking at the issuing CA of the certificate, by
+Name or Key Identifier, and tries to find that certificate while at the
+same time evaluting any policies in-place.
+
+@node Setting up a CA, Creating a CA certificate, What are X.509 and PKIX ?, Top
+@chapter Setting up a CA
+
+Do not let information overload scare you off! If you are simply testing
+or getting started with a PKI infrastructure, skip all this and go to
+the next chapter (see: @pxref{Creating a CA certificate}).
+
+Creating a CA certificate should be more the just creating a
+certificate, CA's should define a policy. Again, if you are simply
+testing a PKI, policies do not matter so much. However, when 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 things simple, it's not very hard to run a
+Certificate authority and the process to get new certificates should be simple.
+
+You may find it helpful to answer the following policy questions for
+your organization at a later stage:
+
+@itemize @bullet
+@item How do you trust your CA.
+@item What is the CA responsibility.
+@item Review of CA activity.
+@item How much process should it be to issue certificate.
+@item Who is allowed to issue certificates.
+@item Who is allowed to requests certificates.
+@item How to handle certificate revocation, issuing CRLs and maintain OCSP services.
+@end itemize
+
+@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 very minimum. This is because you don't want to push out the
+certificate (as a trust anchor) to all you users again when the old
+CA certificate expires. Although a trust anchor can't really expire, not all
+software works in accordance with published standards.
+
+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 can be used to generate a self-signed CA certificate.
+
+@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 the lifetime of a CA certificate
+
+You just realised that your CA certificate is going to expire soon and
+that you need replace it with a new CA. The easiest way to do that
+is to extend the lifetime of your existing CA certificate.
+
+The example below will extend the CA certificate's lifetime by 10 years. 
+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 below creates 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 certificates to them.
+
+@c I think this section needs a bit of clarity. Can I add a separate
+@c section which explains CSRs as well?
+
+
+@itemize @bullet
+
+@item Do all the work themself
+
+Generate the key for the user. This has the problme that the the CA
+knows the private key of the user. For a paranoid user this might leave
+feeling of disconfort.
+
+@item Have the user do part of the work
+
+Receive PKCS10 certificate requests fromusers. PKCS10 is a request for a
+certificate.  The user may specify what DN they want as well as provide
+a certificate signing request (CSR).  To prove the user have the key,
+the whole request is signed by the private key of the user.
+
+@end itemize
+
+@subsection Name space management
+
+@c The explanation given below is slightly unclear. I will re-read the
+@c RFC and document accordingly
+
+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
+
+Certificates that a CA issues may need to be revoked at some stage. As
+an example, an employee leaves the organization and does not bother
+handing in his smart card (or even if the smart card is handed back --
+the certificate on it must no longer be acceptable to services; the
+employee has left).
+
+You may also want to revoke a certificate for a service which is no
+longer being offered on your network. Overlooking these scenarios can
+lead to security holes which will quickly become a nightmare to deal
+with.
+
+There are two primary protocols for dealing with certificate
+revokation. Namely:
+
+@itemize @bullet
+@item Certificate Revocation List (CRL)
+@item Online Certificate Status Protocol (OCSP)
+@end itemize
+
+If however the certificate in qeustion has been destroyed, there is no
+need to revoke the certificate because it can not be used by someone
+else. This matter since for each certificate you add to CRL, the
+download time and processing time for clients are longer.
+
+CRLs and OCSP responders however greatly help manage compatible services
+which may authenticate and authorize users (or services) on an on-going
+basis. As an example, VPN connectivity established via certificates for
+connecting clients would require your VPN software to make use of a CRL
+or an OCSP service to ensure revoked certificates belonging to former
+clients are not allowed access to (formerly subscribed) network
+services.
+
+
+@node Issuing CRLs, Application requirements, Issuing certificates, Top
+@section Issuing CRLs
+
+Create an empty CRL with no 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 place 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
+way is in the subject distinguished name, @emph{this should not be used}. The
+new way is using a Subject Alternative Name (SAN).
+
+Even though the email address is stored in certificates, they don't need
+to be, email reader programs are required to accept certificates that
+doesn't have either of the two methods of storing email in certificates
+-- in which case, the email client will 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
+
+A PK-INIT infrastructure allows users and services to pick up kerberos
+credentials (tickets) based on their certificate. This, for example,
+allows users to authenticate to their desktops using smartcards while
+acquiring kerberos tickets in the process.
+
+As an example, an office network which offers centrally controlled
+desktop logins, mail, messaging (xmpp) and openafs would give users
+single sign-on facilities via smartcard based logins.  Once the kerberos
+ticket has been acquired, all kerberized services would immediately
+become accessible based on deployed security policies.
+
+Let's go over the process of initializing a demo PK-INIT framework:
+
+@example
+hxtool issue-certificate \
+        --type="pkinit-kdc" \
+        --pk-init-principal="krbtgt/TEST.H5L.SE@@TEST.H5L.SE" \
+        --hostname=kerberos.test.h5l.se \
+        --ca-certificate="FILE:ca.pem,ca.key" \
+        --generate-key=rsa \
+        --certificate="FILE:kdc.pem" \
+        --subject="cn=kdc"
+@end example
+
+How to create a certificate for a user.
+
+@example
+hxtool issue-certificate \
+        --type="pkinit-client" \
+        --pk-init-principal="user@@TEST.H5L.SE" \
+        --ca-certificate="FILE:ca.pem,ca.key" \
+        --generate-key=rsa \
+        --subject="cn=Test User" \
+        --certificate="FILE:user.pem"
+@end example
+
+The --type field can be specified multiple times. The same certificate
+can hence house extensions for both pkinit-client as well as S/MIME.
+
+To use the PKCS11 module, please see the section:
+@pxref{How to use the PKCS11 module}.
+
+More about how to configure the KDC, see the documentation in the
+Heimdal manual to set up the KDC.
+
+@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, Certificate matching, CMS signing and encryption, Top
+@section CMS background
+
+
+@node Certificate matching, Matching syntax, CMS background, Top
+@chapter Certificate matching
+
+To match certificates hx509 have a special query language to match
+certifictes in queries and ACLs.
+
+@node Matching syntax, Software PKCS 11 module, Certificate matching, Top
+@section Matching syntax
+
+This is the language definitions somewhat slopply descriped:
+
+@example
+
+expr = TRUE, 
+     FALSE,
+     ! expr,
+     expr AND expr,
+     expr OR expr,
+     ( expr )
+     compare
+
+compare =
+     word == word,
+     word != word,
+     word IN ( word [, word ...])
+     word IN %@{variable.subvariable@}
+
+word =
+     STRING,
+     %@{variable@}
+
+@end example
+
+@node Software PKCS 11 module, How to use the PKCS11 module, Matching syntax, Top
+@chapter Software PKCS 11 module
+
+PKCS11 is a standard created by RSA, Inc to support hardware and
+software encryption modules. It can be used by smartcard to expose the
+crypto primitives inside without exposing the crypto keys.
+
+Hx509 includes a software implementation of PKCS11 that runs within the
+memory space of the process and thus exposes the keys to the
+application.
+
+@node How to use the PKCS11 module, , Software PKCS 11 module, Top
+@section How to use the PKCS11 module
+
+@example
+$ cat > ~/.soft-pkcs11.rc <<EOF
+mycert	cert	User certificate	FILE:/Users/lha/Private/pkinit.pem
+app-fatal	true
+EOF
+$ kinit -C PKCS11:/usr/heimdal/lib/hx509.so lha@@EXAMPLE.ORG
+@end example
+
+
+@c @shortcontents
+@contents
+
+@bye
diff --git a/third_party/heimdal/doc/init-creds b/third_party/heimdal/doc/init-creds
new file mode 100644
index 0000000..8892d29
--- /dev/null
+++ b/third_party/heimdal/doc/init-creds
@@ -0,0 +1,374 @@
+Currently, getting an initial ticket for a user involves many function
+calls, especially when a full set of features including password
+expiration and challenge preauthentication is desired.  In order to
+solve this problem, a new api is proposed.
+
+typedef struct _krb5_prompt {
+    char *prompt;
+    int hidden;
+    krb5_data *reply;
+} krb5_prompt;
+
+typedef int (*krb5_prompter_fct)(krb5_context context,
+				 void *data,
+				 const char *banner,
+				 int num_prompts,
+				 krb5_prompt prompts[]);
+
+typedef struct _krb5_get_init_creds_opt {
+    krb5_flags flags;
+    krb5_deltat tkt_life;
+    krb5_deltat renew_life;
+    int forwardable;
+    int proxiable;
+    krb5_enctype *etype_list;
+    int etype_list_length;
+    krb5_address **address_list;
+	/* XXX the next three should not be used, as they may be
+	removed later */
+    krb5_preauthtype *preauth_list;
+    int preauth_list_length;
+    krb5_data *salt;
+} krb5_get_init_creds_opt;
+
+#define KRB5_GET_INIT_CREDS_OPT_TKT_LIFE	0x0001
+#define KRB5_GET_INIT_CREDS_OPT_RENEW_LIFE	0x0002
+#define KRB5_GET_INIT_CREDS_OPT_FORWARDABLE	0x0004
+#define KRB5_GET_INIT_CREDS_OPT_PROXIABLE	0x0008
+#define KRB5_GET_INIT_CREDS_OPT_ETYPE_LIST	0x0010
+#define KRB5_GET_INIT_CREDS_OPT_ADDRESS_LIST	0x0020
+#define KRB5_GET_INIT_CREDS_OPT_PREAUTH_LIST	0x0040
+#define KRB5_GET_INIT_CREDS_OPT_SALT		0x0080
+
+void krb5_get_init_creds_opt_init(krb5_get_init_creds_opt *opt);
+
+void krb5_get_init_creds_opt_set_tkt_life(krb5_get_init_creds_opt *opt,
+					  krb5_deltat tkt_life);
+void krb5_get_init_creds_opt_set_renew_life(krb5_get_init_creds_opt *opt,
+					    krb5_deltat renew_life);
+void krb5_get_init_creds_opt_set_forwardable(krb5_get_init_creds_opt *opt,
+					     int forwardable);
+void krb5_get_init_creds_opt_set_proxiable(krb5_get_init_creds_opt *opt,
+					   int proxiable);
+void krb5_get_init_creds_opt_set_etype_list(krb5_get_init_creds_opt *opt,
+					    krb5_enctype *etype_list,
+					    int etype_list_length);
+void krb5_get_init_creds_opt_set_address_list(krb5_get_init_creds_opt *opt,
+					      krb5_address **addresses);
+void krb5_get_init_creds_opt_set_preauth_list(krb5_get_init_creds_opt *opt,
+					      krb5_preauthtype *preauth_list,
+					      int preauth_list_length);
+void krb5_get_init_creds_opt_set_salt(krb5_get_init_creds_opt *opt,
+				      krb5_data *salt);
+
+krb5_error_code
+krb5_get_init_creds_password(krb5_context context,
+			     krb5_creds *creds,
+			     krb5_principal client,
+			     char *password,
+			     krb5_prompter_fct prompter,
+			     void *data,
+			     krb5_deltat start_time,
+			     char *in_tkt_service,
+			     krb5_get_init_creds_opt *options);
+
+This function will attempt to acquire an initial ticket.  The function
+will perform whatever tasks are necessary to do so.  This may include
+changing an expired password, preauthentication.
+
+The arguments divide into two types.  Some arguments are basically
+invariant and arbitrary across all initial tickets, and if not
+specified are determined by configuration or library defaults.  Some
+arguments are different for each execution or application, and if not
+specified can be determined correctly from system configuration or
+environment.  The former arguments are contained in a structure whose
+pointer is passed to the function.  A bitmask specifies which elements
+of the structure should be used.  In most cases, a NULL pointer can be
+used.  The latter arguments are specified as individual arguments to
+the function.
+
+If a pointer to a credential is specified, the initial credential is
+filled in.  If the caller only wishes to do a simple password check
+and will not be doing any other kerberos functions, then a NULL
+pointer may be specified, and the credential will be destroyed.
+
+If the client name is non-NULL, the initial ticket requested will be
+for that principal.  Otherwise, the principal will be the 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/third_party/heimdal/doc/install.texi b/third_party/heimdal/doc/install.texi
new file mode 100644
index 0000000..26008fc
--- /dev/null
+++ b/third_party/heimdal/doc/install.texi
@@ -0,0 +1,8 @@
+@node Building and Installing, Setting up a realm,  What is bx509?, Top
+@comment  node-name,  next,  previous,  up
+@chapter Building and Installing
+
+Build and install instructions are located here:
+
+@url{https://github.com/heimdal/heimdal/wiki}
+
diff --git a/third_party/heimdal/doc/intro.texi b/third_party/heimdal/doc/intro.texi
new file mode 100644
index 0000000..c51eba0
--- /dev/null
+++ b/third_party/heimdal/doc/intro.texi
@@ -0,0 +1,98 @@
+@c $Id$
+
+@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,
+@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/third_party/heimdal/doc/kerberos4.texi b/third_party/heimdal/doc/kerberos4.texi
new file mode 100644
index 0000000..41a6508
--- /dev/null
+++ b/third_party/heimdal/doc/kerberos4.texi
@@ -0,0 +1,173 @@
+@c $Id$
+
+@node Kerberos 4 issues, Windows compatibility, Things in search for a better place, Top
+@comment  node-name,  next,  previous,  up
+@chapter Kerberos 4 issues
+
+Kerberos 4 KDC and KA server have been moved.
+
+For more about AFS, see the section @xref{AFS}.
+
+@menu
+* Principal conversion issues::  
+* Converting a version 4 database::  
+@end menu
+
+@node Principal conversion issues, Converting a version 4 database, Kerberos 4 issues, Kerberos 4 issues
+@section Principal conversion issues
+
+First, Kerberos 4 and Kerberos 5 principals are different. A version 4
+principal consists of a name, an instance, and a realm. A version 5
+principal has one or more components, and a realm (the terms ``name''
+and ``instance'' are still used, for the first and second component,
+respectively).    Also, in some cases the name of a version 4 principal
+differs from the first component of the corresponding version 5
+principal. One notable example is the ``host'' type principals, where
+the version 4 name is @samp{rcmd} (for ``remote command''), and the
+version 5 name is @samp{host}. For the class of principals that has a
+hostname as instance, there is an other major difference, Kerberos 4
+uses only the first component of the hostname, whereas Kerberos 5 uses
+the fully qualified hostname.
+
+Because of this it can be hard or impossible to correctly convert a
+version 4 principal to a version 5 principal @footnote{the other way is
+not always trivial either, but usually easier}. The biggest problem is
+to know if the conversion resulted in a valid principal. To give an
+example, suppose you want to convert the principal @samp{rcmd.foo}.
+
+The @samp{rcmd} name suggests that the instance is a hostname (even if
+there are exceptions to this rule). To correctly convert the instance
+@samp{foo} to a hostname, you have to know which host it is referring
+to. You can to this by either guessing (from the realm) which domain
+name to append, or you have to have a list of possible hostnames. In the
+simplest cases you can cover most principals with the first rule. If you
+have several domains sharing a single realm this will not usually
+work. If the exceptions are few you can probably come by with a lookup
+table for the exceptions.
+
+In a complex scenario you will need some kind of host lookup mechanism.
+Using DNS for this is tempting, but DNS is error prone, slow and unsafe
+@footnote{at least until secure DNS is commonly available}.
+
+Fortunately, the KDC has a trump on hand: it can easily tell if a
+principal exists in the database. The KDC will use
+@code{krb5_425_conv_principal_ext} to convert principals when handling
+to version 4 requests.
+
+@node Converting a version 4 database, , Principal conversion issues, Kerberos 4 issues
+@section Converting a version 4 database
+
+If you want to convert an existing version 4 database, the principal
+conversion issue arises too.
+
+If you decide to convert your database once and for all, you will only
+have to do this conversion once. It is also possible to run a version 5
+KDC as a slave to a version 4 KDC. In this case this conversion will
+happen every time the database is propagated.  When doing this
+conversion, there are a few things to look out for. If you have stale
+entries in the database, these entries will not be converted. This might
+be because these principals are not used anymore, or it might be just
+because the principal couldn't be converted.
+
+You might also see problems with a many-to-one mapping of
+principals. For instance, if you are using DNS lookups and you have two
+principals @samp{rcmd.foo} and @samp{rcmd.bar}, where `foo' is a CNAME
+for `bar', the resulting principals will be the same. Since the
+conversion function can't tell which is correct, these conflicts will
+have to be resolved manually.
+
+@subsection Conversion example
+
+Given the following set of hosts and services:
+
+@example
+foo.se          rcmd
+mail.foo.se     rcmd, pop
+ftp.bar.se      rcmd, ftp
+@end example
+
+you have a database that consists of the following principals:
+
+@samp{rcmd.foo}, @samp{rcmd.mail}, @samp{pop.mail}, @samp{rcmd.ftp}, and
+@samp{ftp.ftp}.
+
+lets say you also got these extra principals: @samp{rcmd.gone},
+@samp{rcmd.old-mail}, where @samp{gone.foo.se} was a machine that has
+now passed away, and @samp{old-mail.foo.se} was an old mail machine that
+is now a CNAME for @samp{mail.foo.se}.
+
+When you convert this database you want the following conversions to be
+done:
+@example
+rcmd.foo         host/foo.se
+rcmd.mail        host/mail.foo.se
+pop.mail         pop/mail.foo.se
+rcmd.ftp         host/ftp.bar.se
+ftp.ftp          ftp/ftp.bar.se
+rcmd.gone        @i{removed}
+rcmd.old-mail    @i{removed}
+@end example
+
+A @file{krb5.conf} that does this looks like:
+
+@example
+[realms]
+        FOO.SE = @{
+                v4_name_convert = @{
+                        host = @{
+                                ftp = ftp
+                                pop = pop
+                                rcmd = host
+                        @}
+                @}
+                v4_instance_convert = @{
+                        foo = foo.se
+                        ftp = ftp.bar.se
+                @}
+                default_domain = foo.se
+        @}
+@end example
+
+The @samp{v4_name_convert} section says which names should be considered
+having an instance consisting of a hostname, and it also says how the
+names should be converted (for instance @samp{rcmd} should be converted
+to @samp{host}). The @samp{v4_instance_convert} section says how a
+hostname should be qualified (this is just a hosts-file in
+disguise). Host-instances that aren't covered by
+@samp{v4_instance_convert} are qualified by appending the contents of
+the @samp{default_domain}.
+
+Actually, this example doesn't work. Or rather, it works to well. Since
+it has no way of knowing which hostnames are valid and which are not, it
+will happily convert @samp{rcmd.gone} to @samp{host/gone.foo.se}. This
+isn't a big problem, but if you have run your kerberos realm for a few
+years, chances are big that you have quite a few `junk' principals.
+
+If you don't want this you can remove the @samp{default_domain}
+statement, but then you will have to add entries for @emph{all} your hosts
+in the @samp{v4_instance_convert} section.
+
+Instead of doing this you can use DNS to convert instances. This is not
+a solution without problems, but it is probably easier than adding lots
+of static host entries. 
+
+To enable DNS lookup you should turn on @samp{v4_instance_resolve} in
+the @samp{[libdefaults]} section.
+
+@subsection Converting a database
+
+The database conversion is done with @samp{hprop}. 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
+
diff --git a/third_party/heimdal/doc/krb5.din b/third_party/heimdal/doc/krb5.din
new file mode 100644
index 0000000..047319b
--- /dev/null
+++ b/third_party/heimdal/doc/krb5.din
@@ -0,0 +1,16 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal Kerberos 5 library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/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/third_party/heimdal/doc/latin1.tex b/third_party/heimdal/doc/latin1.tex
new file mode 100644
index 0000000..e683dd2
--- /dev/null
+++ b/third_party/heimdal/doc/latin1.tex
@@ -0,0 +1,95 @@
+% ISO Latin 1 (ISO 8859/1) encoding for Computer Modern fonts.
+% Jan Michael Rynning <jmr@nada.kth.se> 1990-10-12
+\def\inmathmode#1{\relax\ifmmode#1\else$#1$\fi}
+\global\catcode`\^^a0=\active \global\let^^a0=~		% no-break space
+\global\catcode`\^^a1=\active \global\def^^a1{!`}		% inverted exclamation mark
+\global\catcode`\^^a2=\active \global\def^^a2{{\rm\rlap/c}}	% cent sign
+\global\catcode`\^^a3=\active \global\def^^a3{{\it\$}}	% pound sign
+% currency sign, yen sign, broken bar
+\global\catcode`\^^a7=\active \global\let^^a7=\S		% section sign
+\global\catcode`\^^a8=\active \global\def^^a8{\"{}}		% diaeresis
+\global\catcode`\^^a9=\active \global\let^^a9=\copyright	% copyright sign
+% feminine ordinal indicator, left angle quotation mark
+\global\catcode`\^^ac=\active \global\def^^ac{\inmathmode\neg}% not sign
+\global\catcode`\^^ad=\active \global\let^^ad=\-		% soft hyphen
+% registered trade mark sign
+\global\catcode`\^^af=\active \global\def^^af{\={}}		% macron
+% ...
+\global\catcode`\^^b1=\active \global\def^^b1{\inmathmode\pm}	% plus minus
+\global\catcode`\^^b2=\active \global\def^^b2{\inmathmode{{^2}}}
+\global\catcode`\^^b3=\active \global\def^^b3{\inmathmode{{^3}}}
+\global\catcode`\^^b4=\active \global\def^^b4{\'{}}		% acute accent
+\global\catcode`\^^b5=\active \global\def^^b5{\inmathmode\mu}	% mu
+\global\catcode`\^^b6=\active \global\let^^b6=\P		% pilcroy
+\global\catcode`\^^b7=\active \global\def^^b7{\inmathmode{{\cdot}}}
+\global\catcode`\^^b8=\active \global\def^^b8{\c{}}		% cedilla
+\global\catcode`\^^b9=\active \global\def^^b9{\inmathmode{{^1}}}
+% ...
+\global\catcode`\^^bc=\active \global\def^^bc{\inmathmode{{1\over4}}}
+\global\catcode`\^^bd=\active \global\def^^bd{\inmathmode{{1\over2}}}
+\global\catcode`\^^be=\active \global\def^^be{\inmathmode{{3\over4}}}
+\global\catcode`\^^bf=\active \global\def^^bf{?`}		% inverted question mark
+\global\catcode`\^^c0=\active \global\def^^c0{\`A}
+\global\catcode`\^^c1=\active \global\def^^c1{\'A}
+\global\catcode`\^^c2=\active \global\def^^c2{\^A}
+\global\catcode`\^^c3=\active \global\def^^c3{\~A}
+\global\catcode`\^^c4=\active \global\def^^c4{\"A}		% capital a with diaeresis
+\global\catcode`\^^c5=\active \global\let^^c5=\AA		% capital a with ring above
+\global\catcode`\^^c6=\active \global\let^^c6=\AE
+\global\catcode`\^^c7=\active \global\def^^c7{\c C}
+\global\catcode`\^^c8=\active \global\def^^c8{\`E}
+\global\catcode`\^^c9=\active \global\def^^c9{\'E}
+\global\catcode`\^^ca=\active \global\def^^ca{\^E}
+\global\catcode`\^^cb=\active \global\def^^cb{\"E}
+\global\catcode`\^^cc=\active \global\def^^cc{\`I}
+\global\catcode`\^^cd=\active \global\def^^cd{\'I}
+\global\catcode`\^^ce=\active \global\def^^ce{\^I}
+\global\catcode`\^^cf=\active \global\def^^cf{\"I}
+% capital eth
+\global\catcode`\^^d1=\active \global\def^^d1{\~N}
+\global\catcode`\^^d2=\active \global\def^^d2{\`O}
+\global\catcode`\^^d3=\active \global\def^^d3{\'O}
+\global\catcode`\^^d4=\active \global\def^^d4{\^O}
+\global\catcode`\^^d5=\active \global\def^^d5{\~O}
+\global\catcode`\^^d6=\active \global\def^^d6{\"O}		% capital o with diaeresis
+\global\catcode`\^^d7=\active \global\def^^d7{\inmathmode\times}% multiplication sign
+\global\catcode`\^^d8=\active \global\let^^d8=\O
+\global\catcode`\^^d9=\active \global\def^^d9{\`U}
+\global\catcode`\^^da=\active \global\def^^da{\'U}
+\global\catcode`\^^db=\active \global\def^^db{\^U}
+\global\catcode`\^^dc=\active \global\def^^dc{\"U}
+\global\catcode`\^^dd=\active \global\def^^dd{\'Y}
+% capital thorn
+\global\catcode`\^^df=\active \global\def^^df{\ss}
+\global\catcode`\^^e0=\active \global\def^^e0{\`a}
+\global\catcode`\^^e1=\active \global\def^^e1{\'a}
+\global\catcode`\^^e2=\active \global\def^^e2{\^a}
+\global\catcode`\^^e3=\active \global\def^^e3{\~a}
+\global\catcode`\^^e4=\active \global\def^^e4{\"a}		% small a with diaeresis
+\global\catcode`\^^e5=\active \global\let^^e5=\aa		% small a with ring above
+\global\catcode`\^^e6=\active \global\let^^e6=\ae
+\global\catcode`\^^e7=\active \global\def^^e7{\c c}
+\global\catcode`\^^e8=\active \global\def^^e8{\`e}
+\global\catcode`\^^e9=\active \global\def^^e9{\'e}
+\global\catcode`\^^ea=\active \global\def^^ea{\^e}
+\global\catcode`\^^eb=\active \global\def^^eb{\"e}
+\global\catcode`\^^ec=\active \global\def^^ec{\`\i}
+\global\catcode`\^^ed=\active \global\def^^ed{\'\i}
+\global\catcode`\^^ee=\active \global\def^^ee{\^\i}
+\global\catcode`\^^ef=\active \global\def^^ef{\"\i}
+% small eth
+\global\catcode`\^^f1=\active \global\def^^f1{\~n}
+\global\catcode`\^^f2=\active \global\def^^f2{\`o}
+\global\catcode`\^^f3=\active \global\def^^f3{\'o}
+\global\catcode`\^^f4=\active \global\def^^f4{\^o}
+\global\catcode`\^^f5=\active \global\def^^f5{\~o}
+\global\catcode`\^^f6=\active \global\def^^f6{\"o}		% small o with diaeresis
+\global\catcode`\^^f7=\active \global\def^^f7{\inmathmode\div}% division sign
+\global\catcode`\^^f8=\active \global\let^^f8=\o
+\global\catcode`\^^f9=\active \global\def^^f9{\`u}
+\global\catcode`\^^fa=\active \global\def^^fa{\'u}
+\global\catcode`\^^fb=\active \global\def^^fb{\^u}
+\global\catcode`\^^fc=\active \global\def^^fc{\"u}
+\global\catcode`\^^fd=\active \global\def^^fd{\'y}
+% capital thorn
+\global\catcode`\^^ff=\active \global\def^^ff{\"y}
diff --git a/third_party/heimdal/doc/layman.asc b/third_party/heimdal/doc/layman.asc
new file mode 100644
index 0000000..d4fbe64
--- /dev/null
+++ b/third_party/heimdal/doc/layman.asc
@@ -0,0 +1,1855 @@
+A Layman's Guide to a Subset of ASN.1, BER, and DER
+
+An RSA Laboratories Technical Note
+Burton S. Kaliski Jr.
+Revised November 1, 1993
+
+
+Supersedes June 3, 1991 version, which was also published as
+NIST/OSI Implementors' Workshop document SEC-SIG-91-17.
+PKCS documents are available by electronic mail to
+<pkcs@rsa.com>.
+
+Copyright (C) 1991-1993 RSA Laboratories, a division of RSA
+Data Security, Inc. License to copy this document is granted
+provided that it is identified as "RSA Data Security, Inc.
+Public-Key Cryptography Standards (PKCS)" in all material
+mentioning or referencing this document.
+003-903015-110-000-000
+
+
+Abstract. This note gives a layman's introduction to a
+subset of OSI's Abstract Syntax Notation One (ASN.1), Basic
+Encoding Rules (BER), and Distinguished Encoding Rules
+(DER). The particular purpose of this note is to provide
+background material sufficient for understanding and
+implementing the PKCS family of standards.
+
+
+1. Introduction
+
+It is a generally accepted design principle that abstraction
+is a key to managing software development. With abstraction,
+a designer can specify a part of a system without concern
+for how the part is actually implemented or represented.
+Such a practice leaves the implementation open; it
+simplifies the specification; and it makes it possible to
+state "axioms" about the part that can be proved when the
+part is implemented, and assumed when the part is employed
+in another, higher-level part. Abstraction is the hallmark
+of most modern software specifications.
+
+One of the most complex systems today, and one that also
+involves a great deal of abstraction, is Open Systems
+Interconnection (OSI, described in X.200). OSI is an
+internationally standardized architecture that governs the
+interconnection of computers from the physical layer up to
+the user application layer. Objects at higher layers are
+defined abstractly and intended to be implemented with
+objects at lower layers. For instance, a service at one
+layer may require transfer of certain abstract objects
+between computers; a lower layer may provide transfer
+services for strings of ones and zeroes, using encoding
+rules to transform the abstract objects into such strings.
+OSI is called an open system because it supports many
+different implementations of the services at each layer.
+
+OSI's method of specifying abstract objects is called ASN.1
+(Abstract Syntax Notation One, defined in X.208), and one
+set of rules for representing such objects as strings of
+ones and zeros is called the BER (Basic Encoding Rules,
+defined in X.209). ASN.1 is a flexible notation that allows
+one to define a variety data types, from simple types such
+as integers and bit strings to structured types such as sets
+and sequences, as well as complex types defined in terms of
+others. BER describes how to represent or encode values of
+each ASN.1 type as a string of eight-bit octets. There is
+generally more than one way to BER-encode a given value.
+Another set of rules, called the Distinguished Encoding
+Rules (DER), which is a subset of BER, gives a unique
+encoding to each ASN.1 value.
+
+The purpose of this note is to describe a subset of ASN.1,
+BER and DER sufficient to understand and implement one OSI-
+based application, RSA Data Security, Inc.'s Public-Key
+Cryptography Standards. The features described include an
+overview of ASN.1, BER, and DER and an abridged list of
+ASN.1 types and their BER and DER encodings. Sections 2-4
+give an overview of ASN.1, BER, and DER, in that order.
+Section 5 lists some ASN.1 types, giving their notation,
+specific encoding rules, examples, and comments about their
+application to PKCS. Section 6 concludes with an example,
+X.500 distinguished names.
+
+Advanced features of ASN.1, such as macros, are not
+described in this note, as they are not needed to implement
+PKCS. For information on the other features, and for more
+detail generally, the reader is referred to CCITT
+Recommendations X.208 and X.209, which define ASN.1 and BER.
+
+Terminology and notation. In this note, an octet is an eight-
+bit unsigned integer. Bit 8 of the octet is the most
+significant and bit 1 is the least significant.
+
+The following meta-syntax is used for in describing ASN.1
+notation:
+
+     BIT  monospace denotes literal characters in the type
+          and value notation; in examples, it generally
+          denotes an octet value in hexadecimal
+
+     n1   bold italics denotes a variable
+
+     []   bold square brackets indicate that a term is
+          optional
+
+     {}   bold braces group related terms
+
+     |    bold vertical bar delimits alternatives with a
+          group
+
+     ...  bold ellipsis indicates repeated occurrences
+
+     =    bold equals sign expresses terms as subterms
+
+
+2. Abstract Syntax Notation One
+
+Abstract Syntax Notation One, abbreviated ASN.1, is a
+notation for describing abstract types and values.
+
+In ASN.1, a type is a set of values. For some types, there
+are a finite number of values, and for other types there are
+an infinite number. A value of a given ASN.1 type is an
+element of the type's set. ASN.1 has four kinds of type:
+simple types, which are "atomic" and have no components;
+structured types, which have components; tagged types, which
+are derived from other types; and other types, which include
+the CHOICE type and the ANY type. Types and values can be
+given names with the ASN.1 assignment operator (::=) , and
+those names can be used in defining other types and values.
+
+Every ASN.1 type other than CHOICE and ANY has a tag, which
+consists of a class and a nonnegative tag number. ASN.1
+types are abstractly the same if and only if their tag
+numbers are the same. In other words, the name of an ASN.1
+type does not affect its abstract meaning, only the tag
+does. There are four classes of tag:
+
+     Universal, for types whose meaning is the same in all
+          applications; these types are only defined in
+          X.208.
+
+     Application, for types whose meaning is specific to an
+          application, such as X.500 directory services;
+          types in two different applications may have the
+          same application-specific tag and different
+          meanings.
+
+     Private, for types whose meaning is specific to a given
+          enterprise.
+
+     Context-specific, for types whose meaning is specific
+          to a given structured type; context-specific tags
+          are used to distinguish between component types
+          with the same underlying tag within the context of
+          a given structured type, and component types in
+          two different structured types may have the same
+          tag and different meanings.
+
+The types with universal tags are defined in X.208, which
+also gives the types' universal tag numbers. Types with
+other tags are defined in many places, and are always
+obtained by implicit or explicit tagging (see Section 2.3).
+Table 1 lists some ASN.1 types and their universal-class
+tags.
+
+    Type                     Tag number     Tag number
+                             (decimal)      (hexadecimal)
+    INTEGER                  2              02
+    BIT STRING               3              03
+    OCTET STRING             4              04
+    NULL                     5              05
+    OBJECT IDENTIFIER        6              06
+    SEQUENCE and SEQUENCE OF 16             10
+    SET and SET OF           17             11
+    PrintableString          19             13
+    T61String                20             14
+    IA5String                22             16
+    UTCTime                  23             17
+
+     Table 1. Some types and their universal-class tags.
+
+ASN.1 types and values are expressed in a flexible,
+programming-language-like notation, with the following
+special rules:
+
+     o    Layout is not significant; multiple spaces and
+          line breaks can be considered as a single space.
+
+     o    Comments are delimited by pairs of hyphens (--),
+          or a pair of hyphens and a line break.
+
+     o    Identifiers (names of values and fields) and type
+          references (names of types) consist of upper- and
+          lower-case letters, digits, hyphens, and spaces;
+          identifiers begin with lower-case letters; type
+          references begin with upper-case letters.
+
+The following four subsections give an overview of simple
+types, structured types, implicitly and explicitly tagged
+types, and other types. Section 5 describes specific types
+in more detail.
+
+
+2.1 Simple types
+
+Simple types are those not consisting of components; they
+are the "atomic" types. ASN.1 defines several; the types
+that are relevant to the PKCS standards are the following:
+
+     BIT STRING, an arbitrary string of bits (ones and
+          zeroes).
+
+     IA5String, an arbitrary string of IA5 (ASCII)
+          characters.
+
+     INTEGER, an arbitrary integer.
+
+     NULL, a null value.
+
+     OBJECT IDENTIFIER, an object identifier, which is a
+          sequence of integer components that identify an
+          object such as an algorithm or attribute type.
+
+     OCTET STRING, an arbitrary string of octets (eight-bit
+          values).
+
+     PrintableString, an arbitrary string of printable
+          characters.
+
+     T61String, an arbitrary string of T.61 (eight-bit)
+          characters.
+
+     UTCTime, a "coordinated universal time" or Greenwich
+          Mean Time (GMT) value.
+
+Simple types fall into two categories: string types and non-
+string types. BIT STRING, IA5String, OCTET STRING,
+PrintableString, T61String, and UTCTime are string types.
+
+String types can be viewed, for the purposes of encoding, as
+consisting of components, where the components are
+substrings. This view allows one to encode a value whose
+length is not known in advance (e.g., an octet string value
+input from a file stream) with a constructed, indefinite-
+length encoding (see Section 3).
+
+The string types can be given size constraints limiting the
+length of values.
+
+
+2.2 Structured types
+
+Structured types are those consisting of components. ASN.1
+defines four, all of which are relevant to the PKCS
+standards:
+
+     SEQUENCE, an ordered collection of one or more types.
+
+     SEQUENCE OF, an ordered collection of zero or more
+          occurrences of a given type.
+
+     SET, an unordered collection of one or more types.
+
+     SET OF, an unordered collection of zero or more
+          occurrences of a given type.
+
+The structured types can have optional components, possibly
+with default values.
+
+
+2.3 Implicitly and explicitly tagged types
+
+Tagging is useful to distinguish types within an
+application; it is also commonly used to distinguish
+component types within a structured type. For instance,
+optional components of a SET or SEQUENCE type are typically
+given distinct context-specific tags to avoid ambiguity.
+
+There are two ways to tag a type: implicitly and explicitly.
+
+Implicitly tagged types are derived from other types by
+changing the tag of the underlying type. Implicit tagging is
+denoted by the ASN.1 keywords [class number] IMPLICIT (see
+Section 5.1).
+
+Explicitly tagged types are derived from other types by
+adding an outer tag to the underlying type. In effect,
+explicitly tagged types are structured types consisting of
+one component, the underlying type. Explicit tagging is
+denoted by the ASN.1 keywords [class number] EXPLICIT (see
+Section 5.2).
+
+The keyword [class number] alone is the same as explicit
+tagging, except when the "module" in which the ASN.1 type is
+defined has implicit tagging by default. ("Modules" are
+among the advanced features not described in this note.)
+
+For purposes of encoding, an implicitly tagged type is
+considered the same as the underlying type, except that the
+tag is different. An explicitly tagged type is considered
+like a structured type with one component, the underlying
+type. Implicit tags result in shorter encodings, but
+explicit tags may be necessary to avoid ambiguity if the tag
+of the underlying type is indeterminate (e.g., the
+underlying type is CHOICE or ANY).
+
+
+2.4 Other types
+
+Other types in ASN.1 include the CHOICE and ANY types. The
+CHOICE type denotes a union of one or more alternatives; the
+ANY type denotes an arbitrary value of an arbitrary type,
+where the arbitrary type is possibly defined in the
+registration of an object identifier or integer value.
+
+
+3. Basic Encoding Rules
+
+The Basic Encoding Rules for ASN.1, abbreviated BER, give
+one or more ways to represent any ASN.1 value as an octet
+string. (There are certainly other ways to represent ASN.1
+values, but BER is the standard for interchanging such
+values in OSI.)
+
+There are three methods to encode an ASN.1 value under BER,
+the choice of which depends on the type of value and whether
+the length of the value is known. The three methods are
+primitive, definite-length encoding; constructed, definite-
+length encoding; and constructed, indefinite-length
+encoding. Simple non-string types employ the primitive,
+definite-length method; structured types employ either of
+the constructed methods; and simple string types employ any
+of the methods, depending on whether the length of the value
+is known. Types derived by implicit tagging employ the
+method of the underlying type and types derived by explicit
+tagging employ the constructed methods.
+
+In each method, the BER encoding has three or four parts:
+
+     Identifier octets. These identify the class and tag
+          number of the ASN.1 value, and indicate whether
+          the method is primitive or constructed.
+
+     Length octets. For the definite-length methods, these
+          give the number of contents octets. For the
+          constructed, indefinite-length method, these
+          indicate that the length is indefinite.
+
+     Contents octets. For the primitive, definite-length
+          method, these give a concrete representation of
+          the  value. For the constructed methods, these
+          give the concatenation of the BER encodings of the
+          components of the value.
+
+     End-of-contents octets. For the constructed, indefinite-
+          length method, these denote the end of the
+          contents. For the other methods, these are absent.
+
+The three methods of encoding are described in the following
+sections.
+
+
+3.1 Primitive, definite-length method
+
+This method applies to simple types and types derived from
+simple types by implicit tagging. It requires that the
+length of the value be known in advance. The parts of the
+BER encoding are as follows:
+
+Identifier octets. There are two forms: low tag number (for
+tag numbers between 0 and 30) and high tag number (for tag
+numbers 31 and greater).
+
+     Low-tag-number form. One octet. Bits 8 and 7 specify
+          the class (see Table 2), bit 6 has value "0,"
+          indicating that the encoding is primitive, and
+          bits 5-1 give the tag number.
+
+                  Class            Bit  Bit
+                                   8    7
+                  universal        0    0
+                  application      0    1
+                  context-specific 1    0
+                  private          1    1
+
+        Table 2. Class encoding in identifier octets.
+
+     High-tag-number form. Two or more octets. First octet
+          is as in low-tag-number form, except that bits 5-1
+          all have value "1." Second and following octets
+          give the tag number, base 128, most significant
+          digit first, with as few digits as possible, and
+          with the bit 8 of each octet except the last set
+          to "1."
+
+Length octets. There are two forms: short (for lengths
+between 0 and 127), and long definite (for lengths between 0
+and 21008-1).
+
+     Short form. One octet. Bit 8 has value "0" and bits 7-1
+          give the length.
+
+     Long form. Two to 127 octets. Bit 8 of first octet has
+          value "1" and bits 7-1 give the number of
+          additional length octets. Second and following
+          octets give the length, base 256, most significant
+          digit first.
+
+Contents octets. These give a concrete representation of the
+value (or the value of the underlying type, if the type is
+derived by implicit tagging). Details for particular types
+are given in Section 5.
+
+
+3.2 Constructed, definite-length method
+
+This method applies to simple string types, structured
+types, types derived simple string types and structured
+types by implicit tagging, and types derived from anything
+by explicit tagging. It requires that the length of the
+value be known in advance. The parts of the BER encoding are
+as follows:
+
+Identifier octets. As described in Section 3.1, except that
+bit 6 has value "1," indicating that the encoding is
+constructed.
+
+Length octets. As described in Section 3.1.
+
+Contents octets. The concatenation of the BER encodings of
+the components of the value:
+
+     o    For simple string types and types derived from
+          them by implicit tagging, the concatenation of the
+          BER encodings of consecutive substrings of the
+          value (underlying value for implicit tagging).
+
+     o    For structured types and types derived from them
+          by implicit tagging, the concatenation of the BER
+          encodings of components of the value (underlying
+          value for implicit tagging).
+
+     o    For types derived from anything by explicit
+          tagging, the BER encoding of the underlying value.
+
+Details for particular types are given in Section 5.
+
+
+3.3 Constructed, indefinite-length method
+
+This method applies to simple string types, structured
+types, types derived simple string types and structured
+types by implicit tagging, and types derived from anything
+by explicit tagging. It does not require that the length of
+the value be known in advance. The parts of the BER encoding
+are as follows:
+
+Identifier octets. As described in Section 3.2.
+
+Length octets. One octet, 80.
+
+Contents octets. As described in Section 3.2.
+
+End-of-contents octets. Two octets, 00 00.
+
+Since the end-of-contents octets appear where an ordinary
+BER encoding might be expected (e.g., in the contents octets
+of a sequence value), the 00 and 00 appear as identifier and
+length octets, respectively. Thus the end-of-contents octets
+is really the primitive, definite-length encoding of a value
+with universal class, tag number 0, and length 0.
+
+
+4. Distinguished Encoding Rules
+
+The Distinguished Encoding Rules for ASN.1, abbreviated DER,
+are a subset of BER, and give exactly one way to represent
+any ASN.1 value as an octet string. DER is intended for
+applications in which a unique octet string encoding is
+needed, as is the case when a digital signature is computed
+on an ASN.1 value. DER is defined in Section 8.7 of X.509.
+
+DER adds the following restrictions to the rules given in
+Section 3:
+
+     1.   When the length is between 0 and 127, the short
+          form of length must be used
+
+     2.   When the length is 128 or greater, the long form
+          of length must be used, and the length must be
+          encoded in the minimum number of octets.
+
+     3.   For simple string types and implicitly tagged
+          types derived from simple string types, the
+          primitive, definite-length method must be
+          employed.
+
+     4.   For structured types, implicitly tagged types
+          derived from structured types, and explicitly
+          tagged types derived from anything, the
+          constructed, definite-length method must be
+          employed.
+
+Other restrictions are defined for particular types (such as
+BIT STRING, SEQUENCE, SET, and SET OF), and can be found in
+Section 5.
+
+
+5. Notation and encodings for some types
+
+This section gives the notation for some ASN.1 types and
+describes how to encode values of those types under both BER
+and DER.
+
+The types described are those presented in Section 2. They
+are listed alphabetically here.
+
+Each description includes ASN.1 notation, BER encoding, and
+DER encoding. The focus of the encodings is primarily on the
+contents octets; the tag and length octets follow Sections 3
+and 4. The descriptions also explain where each type is used
+in PKCS and related standards. ASN.1 notation is generally
+only for types, although for the type OBJECT IDENTIFIER,
+value notation is given as well.
+
+
+5.1 Implicitly tagged types
+
+An implicitly tagged type is a type derived from another
+type by changing the tag of the underlying type.
+
+Implicit tagging is used for optional SEQUENCE components
+with underlying type other than ANY throughout PKCS, and for
+the extendedCertificate alternative of PKCS #7's
+ExtendedCertificateOrCertificate type.
+
+ASN.1 notation:
+
+[[class] number] IMPLICIT Type
+
+class = UNIVERSAL  |  APPLICATION  |  PRIVATE
+
+where Type is a type, class is an optional class name, and
+number is the tag number within the class, a nonnegative
+integer.
+
+In ASN.1 "modules" whose default tagging method is implicit
+tagging, the notation [[class] number] Type is also
+acceptable, and the keyword IMPLICIT is implied. (See
+Section 2.3.) For definitions stated outside a module, the
+explicit inclusion of the keyword IMPLICIT is preferable to
+prevent ambiguity.
+
+If the class name is absent, then the tag is context-
+specific. Context-specific tags can only appear in a
+component of a structured or CHOICE type.
+
+Example: PKCS #8's PrivateKeyInfo type has an optional
+attributes component with an implicit, context-specific tag:
+
+PrivateKeyInfo ::= SEQUENCE {
+  version Version,
+  privateKeyAlgorithm PrivateKeyAlgorithmIdentifier,
+  privateKey PrivateKey,
+  attributes [0] IMPLICIT Attributes OPTIONAL }
+
+Here the underlying type is Attributes, the class is absent
+(i.e., context-specific), and the tag number within the
+class is 0.
+
+BER encoding. Primitive or constructed, depending on the
+underlying type. Contents octets are as for the BER encoding
+of the underlying value.
+
+Example: The BER encoding of the attributes component of a
+PrivateKeyInfo value is as follows:
+
+     o    the identifier octets are 80 if the underlying
+          Attributes value has a primitive BER encoding and
+          a0 if the underlying Attributes value has a
+          constructed BER encoding
+
+     o    the length and contents octets are the same as the
+          length and contents octets of the BER encoding of
+          the underlying Attributes value
+
+DER encoding. Primitive or constructed, depending on the
+underlying type. Contents octets are as for the DER encoding
+of the underlying value.
+
+
+5.2 Explicitly tagged types
+
+Explicit tagging denotes a type derived from another type by
+adding an outer tag to the underlying type.
+
+Explicit tagging is used for optional SEQUENCE components
+with underlying type ANY throughout PKCS, and for the
+version component of X.509's Certificate type.
+
+ASN.1 notation:
+
+[[class] number] EXPLICIT Type
+
+class = UNIVERSAL  |  APPLICATION  |  PRIVATE
+
+where Type is a type, class is an optional class name, and
+number is the tag number within the class, a nonnegative
+integer.
+
+If the class name is absent, then the tag is context-
+specific. Context-specific tags can only appear in a
+component of a SEQUENCE, SET or CHOICE type.
+
+In ASN.1 "modules" whose default tagging method is explicit
+tagging, the notation [[class] number] Type is also
+acceptable, and the keyword EXPLICIT is implied. (See
+Section 2.3.) For definitions stated outside a module, the
+explicit inclusion of the keyword EXPLICIT is preferable to
+prevent ambiguity.
+
+Example 1: PKCS #7's ContentInfo type has an optional
+content component with an explicit, context-specific tag:
+
+ContentInfo ::= SEQUENCE {
+  contentType ContentType,
+  content
+    [0] EXPLICIT ANY DEFINED BY contentType OPTIONAL }
+
+Here the underlying type is ANY DEFINED BY contentType, the
+class is absent (i.e., context-specific), and the tag number
+within the class is 0.
+
+Example 2: X.509's Certificate type has a version component
+with an explicit, context-specific tag, where the EXPLICIT
+keyword is omitted:
+
+Certificate ::= ...
+  version [0] Version DEFAULT v1988,
+...
+
+The tag is explicit because the default tagging method for
+the ASN.1 "module" in X.509 that defines the Certificate
+type is explicit tagging.
+
+BER encoding. Constructed. Contents octets are the BER
+encoding of the underlying value.
+
+Example: the BER encoding of the content component of a
+ContentInfo value is as follows:
+
+     o    identifier octets are a0
+
+     o    length octets represent the length of the BER
+          encoding of the underlying ANY DEFINED BY
+          contentType value
+
+     o    contents octets are the BER encoding of the
+          underlying ANY DEFINED BY contentType value
+
+DER encoding. Constructed. Contents octets are the DER
+encoding of the underlying value.
+
+
+5.3 ANY
+
+The ANY type denotes an arbitrary value of an arbitrary
+type, where the arbitrary type is possibly defined in the
+registration of an object identifier or associated with an
+integer index.
+
+The ANY type is used for content of a particular content
+type in PKCS #7's ContentInfo type, for parameters of a
+particular algorithm in X.509's AlgorithmIdentifier type,
+and for attribute values in X.501's Attribute and
+AttributeValueAssertion types. The Attribute type is used by
+PKCS #6, #7, #8, #9 and #10, and the AttributeValueAssertion
+type is used in X.501 distinguished names.
+
+ASN.1 notation:
+
+ANY [DEFINED BY identifier]
+
+where identifier is an optional identifier.
+
+In the ANY form, the actual type is indeterminate.
+
+The ANY DEFINED BY identifier form can only appear in a
+component of a SEQUENCE or SET type for which identifier
+identifies some other component, and that other component
+has type INTEGER or OBJECT IDENTIFIER (or a type derived
+from either of those by tagging). In that form, the actual
+type is determined by the value of the other component,
+either in the registration of the object identifier value,
+or in a table of integer values.
+
+Example: X.509's AlgorithmIdentifier type has a component of
+type ANY:
+
+AlgorithmIdentifier ::= SEQUENCE {
+  algorithm OBJECT IDENTIFIER,
+  parameters ANY DEFINED BY algorithm OPTIONAL }
+
+Here the actual type of the parameter component depends on
+the value of the algorithm component. The actual type would
+be defined in the registration of object identifier values
+for the algorithm component.
+
+BER encoding. Same as the BER encoding of the actual value.
+
+Example: The BER encoding of the value of the parameter
+component is the BER encoding of the value of the actual
+type as defined in the registration of object identifier
+values for the algorithm component.
+
+DER encoding. Same as the DER encoding of the actual value.
+
+
+5.4 BIT STRING
+
+The BIT STRING type denotes an arbitrary string of bits
+(ones and zeroes). A BIT STRING value can have any length,
+including zero. This type is a string type.
+
+The BIT STRING type is used for digital signatures on
+extended certificates in PKCS #6's ExtendedCertificate type,
+for digital signatures on certificates in X.509's
+Certificate type, and for public keys in certificates in
+X.509's SubjectPublicKeyInfo type.
+
+ASN.1 notation:
+
+BIT STRING
+
+Example: X.509's SubjectPublicKeyInfo type has a component
+of type BIT STRING:
+
+SubjectPublicKeyInfo ::= SEQUENCE {
+  algorithm AlgorithmIdentifier,
+  publicKey BIT STRING }
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the first contents octet gives the number of bits
+by which the length of the bit string is less than the next
+multiple of eight (this is called the "number of unused
+bits"). The second and following contents octets give the
+value of the bit string, converted to an octet string. The
+conversion process is as follows:
+
+     1.   The bit string is padded after the last bit with
+          zero to seven bits of any value to make the length
+          of the bit string a multiple of eight. If the
+          length of the bit string is a multiple of eight
+          already, no padding is done.
+
+     2.   The padded bit string is divided into octets. The
+          first eight bits of the padded bit string become
+          the first octet, bit 8 to bit 1, and so on through
+          the last eight bits of the padded bit string.
+
+In a constructed encoding, the contents octets give the
+concatenation of the BER encodings of consecutive substrings
+of the bit string, where each substring except the last has
+a length that is a multiple of eight bits.
+
+Example: The BER encoding of the BIT STRING value
+"011011100101110111" can be any of the following, among
+others, depending on the choice of padding bits, the form of
+length octets, and whether the encoding is primitive or
+constructed:
+
+03 04 06 6e 5d c0                               DER encoding
+
+03 04 06 6e 5d e0                       padded with "100000"
+
+03 81 04 06 6e 5d c0              long form of length octets
+
+23 09        constructed encoding: "0110111001011101" + "11"
+   03 03 00 6e 5d
+   03 02 06 c0
+
+DER encoding. Primitive. The contents octects are as for a
+primitive BER encoding, except that the bit string is padded
+with zero-valued bits.
+
+Example: The DER encoding of the BIT STRING value
+"011011100101110111" is
+
+03 04 06 6e 5d c0
+
+
+5.5 CHOICE
+
+The CHOICE type denotes a union of one or more alternatives.
+
+The CHOICE type is used to represent the union of an
+extended certificate and an X.509 certificate in PKCS #7's
+ExtendedCertificateOrCertificate type.
+
+ASN.1 notation:
+
+CHOICE {
+  [identifier1] Type1,
+  ...,
+  [identifiern] Typen }
+
+where identifier1 , ..., identifiern are optional, distinct
+identifiers for the alternatives, and Type1, ..., Typen are
+the types of the alternatives. The identifiers are primarily
+for documentation; they do not affect values of the type or
+their encodings in any way.
+
+The types must have distinct tags. This requirement is
+typically satisfied with explicit or implicit tagging on
+some of the alternatives.
+
+Example: PKCS #7's ExtendedCertificateOrCertificate type is
+a CHOICE type:
+
+ExtendedCertificateOrCertificate ::= CHOICE {
+  certificate Certificate, -- X.509
+  extendedCertificate [0] IMPLICIT ExtendedCertificate
+}
+
+Here the identifiers for the alternatives are certificate
+and extendedCertificate, and the types of the alternatives
+are Certificate and [0] IMPLICIT ExtendedCertificate.
+
+BER encoding. Same as the BER encoding of the chosen
+alternative. The fact that the alternatives have distinct
+tags makes it possible to distinguish between their BER
+encodings.
+
+Example: The identifier octets for the BER encoding are 30
+if the chosen alternative is certificate, and a0 if the
+chosen alternative is extendedCertificate.
+
+DER encoding. Same as the DER encoding of the chosen
+alternative.
+
+
+5.6 IA5String
+
+The IA5String type denotes an arbtrary string of IA5
+characters. IA5 stands for International Alphabet 5, which
+is the same as ASCII. The character set includes non-
+printing control characters. An IA5String value can have any
+length, including zero. This type is a string type.
+
+The IA5String type is used in PKCS #9's electronic-mail
+address, unstructured-name, and unstructured-address
+attributes.
+
+ASN.1 notation:
+
+IA5String
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the contents octets give the characters in the IA5
+string, encoded in ASCII. In a constructed encoding, the
+contents octets give the concatenation of the BER encodings
+of consecutive substrings of the IA5 string.
+
+Example: The BER encoding of the IA5String value
+"test1@rsa.com" can be any of the following, among others,
+depending on the form of length octets and whether the
+encoding is primitive or constructed:
+
+16 0d 74 65 73 74 31 40 72 73 61 2e 63 6f 6d DER encoding
+
+16 81 0d                       long form of length octets
+   74 65 73 74 31 40 72 73 61 2e 63 6f 6d
+
+36 13     constructed encoding: "test1" + "@" + "rsa.com"
+   16 05 74 65 73 74 31
+   16 01 40
+   16 07 72 73 61 2e 63 6f 6d
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+Example: The DER encoding of the IA5String value
+"test1@rsa.com" is
+
+16 0d 74 65 73 74 31 40 72 73 61 2e 63 6f 6d
+
+
+5.7 INTEGER
+
+The INTEGER type denotes an arbitrary integer. INTEGER
+values can be positive, negative, or zero, and can have any
+magnitude.
+
+The INTEGER type is used for version numbers throughout
+PKCS, cryptographic values such as modulus, exponent, and
+primes in PKCS #1's RSAPublicKey and RSAPrivateKey types and
+PKCS #3's DHParameter type, a message-digest iteration count
+in PKCS #5's PBEParameter type, and version numbers and
+serial numbers in X.509's Certificate type.
+
+ASN.1 notation:
+
+INTEGER [{ identifier1(value1) ... identifiern(valuen) }]
+
+where identifier1, ..., identifiern are optional distinct
+identifiers and value1, ..., valuen are optional integer
+values. The identifiers, when present, are associated with
+values of the type.
+
+Example: X.509's Version type is an INTEGER type with
+identified values:
+
+Version ::= INTEGER { v1988(0) }
+
+The identifier v1988 is associated with the value 0. X.509's
+Certificate type uses the identifier v1988 to give a default
+value of 0 for the version component:
+
+Certificate ::= ...
+  version Version DEFAULT v1988,
+...
+
+BER encoding. Primitive. Contents octets give the value of
+the integer, base 256, in two's complement form, most
+significant digit first, with the minimum number of octets.
+The value 0 is encoded as a single 00 octet.
+
+Some example BER encodings (which also happen to be DER
+encodings) are given in Table 3.
+
+                    Integer   BER encoding
+                    value
+                    0         02 01 00
+                    127       02 01 7F
+                    128       02 02 00 80
+                    256       02 02 01 00
+                    -128      02 01 80
+                    -129      02 02 FF 7F
+
+      Table 3. Example BER encodings of INTEGER values.
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+
+5.8 NULL
+
+The NULL type denotes a null value.
+
+The NULL type is used for algorithm parameters in several
+places in PKCS.
+
+ASN.1 notation:
+
+NULL
+
+BER encoding. Primitive. Contents octets are empty.
+
+Example: The BER encoding of a NULL value can be either of
+the following, as well as others, depending on the form of
+the length octets:
+
+05 00
+
+05 81 00
+
+DER encoding. Primitive. Contents octets are empty; the DER
+encoding of a NULL value is always 05 00.
+
+
+5.9 OBJECT IDENTIFIER
+
+The OBJECT IDENTIFIER type denotes an object identifier, a
+sequence of integer components that identifies an object
+such as an algorithm, an attribute type, or perhaps a
+registration authority that defines other object
+identifiers. An OBJECT IDENTIFIER value can have any number
+of components, and components can generally have any
+nonnegative value. This type is a non-string type.
+
+OBJECT IDENTIFIER values are given meanings by registration
+authorities. Each registration authority is responsible for
+all sequences of components beginning with a given sequence.
+A registration authority typically delegates responsibility
+for subsets of the sequences in its domain to other
+registration authorities, or for particular types of object.
+There are always at least two components.
+
+The OBJECT IDENTIFIER type is used to identify content in
+PKCS #7's ContentInfo type, to identify algorithms in
+X.509's AlgorithmIdentifier type, and to identify attributes
+in X.501's Attribute and AttributeValueAssertion types. The
+Attribute type is used by PKCS #6, #7, #8, #9, and #10, and
+the AttributeValueAssertion type is used in X.501
+distinguished names. OBJECT IDENTIFIER values are defined
+throughout PKCS.
+
+ASN.1 notation:
+
+OBJECT IDENTIFIER
+
+The ASN.1 notation for values of the OBJECT IDENTIFIER type
+is
+
+{ [identifier] component1 ... componentn }
+
+componenti = identifieri | identifieri (valuei) | valuei
+
+where identifier, identifier1, ..., identifiern are
+identifiers, and value1, ..., valuen are optional integer
+values.
+
+The form without identifier is the "complete" value with all
+its components; the form with identifier abbreviates the
+beginning components with another object identifier value.
+The identifiers identifier1, ..., identifiern are intended
+primarily for documentation, but they must correspond to the
+integer value when both are present. These identifiers can
+appear without integer values only if they are among a small
+set of identifiers defined in X.208.
+
+Example: The following values both refer to the object
+identifier assigned to RSA Data Security, Inc.:
+
+{ iso(1) member-body(2) 840 113549 }
+{ 1 2 840 113549 }
+
+(In this example, which gives ASN.1 value notation, the
+object identifier values are decimal, not hexadecimal.)
+Table 4 gives some other object identifier values and their
+meanings.
+
+ Object identifier value       Meaning
+ { 1 2 }                       ISO member bodies
+ { 1 2 840 }                   US (ANSI)
+ { 1 2 840 113549 }            RSA Data Security, Inc.
+ { 1 2 840 113549 1 }          RSA Data Security, Inc. PKCS
+ { 2 5 }                       directory services (X.500)
+ { 2 5 8 }                     directory services-algorithms
+
+ Table 4. Some object identifier values and their meanings.
+
+BER encoding. Primitive. Contents octets are as follows,
+where value1, ..., valuen denote the integer values of the
+components in the complete object identifier:
+
+     1.   The first octet has value 40 * value1 + value2.
+          (This is unambiguous, since value1 is limited to
+          values 0, 1, and 2; value2 is limited to the range
+          0 to 39 when value1 is 0 or 1; and, according to
+          X.208, n is always at least 2.)
+
+     2.   The following octets, if any, encode value3, ...,
+          valuen. Each value is encoded base 128, most
+          significant digit first, with as few digits as
+          possible, and the most significant bit of each
+          octet except the last in the value's encoding set
+          to "1."
+
+Example: The first octet of the BER encoding of RSA Data
+Security, Inc.'s object identifier is 40 * 1 + 2 = 42 =
+2a16. The encoding of 840 = 6 * 128 + 4816 is 86 48 and the
+encoding of 113549 = 6 * 1282 + 7716 * 128 + d16 is 86 f7
+0d. This leads to the following BER encoding:
+
+06 06 2a 86 48 86 f7 0d
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+
+5.10 OCTET STRING
+
+The OCTET STRING type denotes an arbitrary string of octets
+(eight-bit values). An OCTET STRING value can have any
+length, including zero. This type is a string type.
+
+The OCTET STRING type is used for salt values in PKCS #5's
+PBEParameter type, for message digests, encrypted message
+digests, and encrypted content in PKCS #7, and for private
+keys and encrypted private keys in PKCS #8.
+
+ASN.1 notation:
+
+OCTET STRING [SIZE ({size | size1..size2})]
+
+where size, size1, and size2 are optional size constraints.
+In the OCTET STRING SIZE (size) form, the octet string must
+have size octets. In the OCTET STRING SIZE (size1..size2)
+form, the octet string must have between size1 and size2
+octets. In the OCTET STRING form, the octet string can have
+any size.
+
+Example: PKCS #5's PBEParameter type has a component of type
+OCTET STRING:
+
+PBEParameter ::= SEQUENCE {
+  salt OCTET STRING SIZE(8),
+  iterationCount INTEGER }
+
+Here the size of the salt component is always eight octets.
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the contents octets give the value of the octet
+string, first octet to last octet. In a constructed
+encoding, the contents octets give the concatenation of the
+BER encodings of substrings of the OCTET STRING value.
+
+Example: The BER encoding of the OCTET STRING value 01 23 45
+67 89 ab cd ef can be any of the following, among others,
+depending on the form of length octets and whether the
+encoding is primitive or constructed:
+
+04 08 01 23 45 67 89 ab cd ef                   DER encoding
+
+04 81 08 01 23 45 67 89 ab cd ef  long form of length octets
+
+24 0c            constructed encoding: 01 ... 67 + 89 ... ef
+   04 04 01 23 45 67
+   04 04 89 ab cd ef
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+Example: The BER encoding of the OCTET STRING value 01 23 45
+67 89 ab cd ef is
+
+04 08 01 23 45 67 89 ab cd ef
+
+
+5.11 PrintableString
+
+The PrintableString type denotes an arbitrary string of
+printable characters from the following character set:
+
+                         A, B, ..., Z
+                         a, b, ..., z
+                         0, 1, ..., 9
+               (space) ' ( ) + , - . / : = ?
+
+This type is a string type.
+
+The PrintableString type is used in PKCS #9's challenge-
+password and unstructuerd-address attributes, and in several
+X.521 distinguished names attributes.
+
+ASN.1 notation:
+
+PrintableString
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the contents octets give the characters in the
+printable string, encoded in ASCII. In a constructed
+encoding, the contents octets give the concatenation of the
+BER encodings of consecutive substrings of the string.
+
+Example: The BER encoding of the PrintableString value "Test
+User 1" can be any of the following, among others, depending
+on the form of length octets and whether the encoding is
+primitive or constructed:
+
+13 0b 54 65 73 74 20 55 73 65 72 20 31          DER encoding
+
+13 81 0b                          long form of length octets
+   54 65 73 74 20 55 73 65 72 20 31
+
+33 0f               constructed encoding: "Test " + "User 1"
+   13 05 54 65 73 74 20
+   13 06 55 73 65 72 20 31
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+Example: The DER encoding of the PrintableString value "Test
+User 1" is
+
+13 0b 54 65 73 74 20 55 73 65 72 20 31
+
+
+5.12 SEQUENCE
+
+The SEQUENCE type denotes an ordered collection of one or
+more types.
+
+The SEQUENCE type is used throughout PKCS and related
+standards.
+
+ASN.1 notation:
+
+SEQUENCE {
+  [identifier1] Type1 [{OPTIONAL | DEFAULT value1}],
+  ...,
+  [identifiern] Typen [{OPTIONAL | DEFAULT valuen}]}
+
+where identifier1 , ..., identifiern are optional, distinct
+identifiers for the components, Type1, ..., Typen are the
+types of the components, and value1, ..., valuen are optional
+default values for the components. The identifiers are
+primarily for documentation; they do not affect values of
+the type or their encodings in any way.
+
+The OPTIONAL qualifier indicates that the value of a
+component is optional and need not be present in the
+sequence. The DEFAULT qualifier also indicates that the
+value of a component is optional, and assigns a default
+value to the component when the component is absent.
+
+The types of any consecutive series of components with the
+OPTIONAL or DEFAULT qualifier, as well as of any component
+immediately following that series, must have distinct tags.
+This requirement is typically satisfied with explicit or
+implicit tagging on some of the components.
+
+Example: X.509's Validity type is a SEQUENCE type with two
+components:
+
+Validity ::= SEQUENCE {
+  start UTCTime,
+  end UTCTime }
+
+Here the identifiers for the components are start and end,
+and the types of the components are both UTCTime.
+
+BER encoding. Constructed. Contents octets are the
+concatenation of the BER encodings of the values of the
+components of the sequence, in order of definition, with the
+following rules for components with the OPTIONAL and DEFAULT
+qualifiers:
+
+     o    if the value of a component with the OPTIONAL or
+          DEFAULT qualifier is absent from the sequence,
+          then the encoding of that component is not
+          included in the contents octets
+
+     o    if the value of a component with the DEFAULT
+          qualifier is the default value, then the encoding
+          of that component may or may not be included in
+          the contents octets
+
+DER encoding. Constructed. Contents octets are the same as
+the BER encoding, except that if the value of a component
+with the DEFAULT qualifier is the default value, the
+encoding of that component is not included in the contents
+octets.
+
+
+5.13 SEQUENCE OF
+
+The SEQUENCE OF type denotes an ordered collection of zero
+or more occurrences of a given type.
+
+The SEQUENCE OF type is used in X.501 distinguished names.
+
+ASN.1 notation:
+
+SEQUENCE OF Type
+
+where Type is a type.
+
+Example: X.501's RDNSequence type consists of zero or more
+occurences of the RelativeDistinguishedName type, most
+significant occurrence first:
+
+RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
+
+BER encoding. Constructed. Contents octets are the
+concatenation of the BER encodings of the values of the
+occurrences in the collection, in order of occurence.
+
+DER encoding. Constructed. Contents octets are the
+concatenation of the DER encodings of the values of the
+occurrences in the collection, in order of occurence.
+
+
+5.14 SET
+
+The SET type denotes an unordered collection of one or more
+types.
+
+The SET type is not used in PKCS.
+
+ASN.1 notation:
+
+SET {
+  [identifier1] Type1 [{OPTIONAL | DEFAULT value1}],
+  ...,
+  [identifiern] Typen [{OPTIONAL | DEFAULT valuen}]}
+
+where identifier1, ..., identifiern are optional, distinct
+identifiers for the components, Type1, ..., Typen are the
+types of the components, and value1, ..., valuen are
+optional default values for the components. The identifiers
+are primarily for documentation; they do not affect values
+of the type or their encodings in any way.
+
+The OPTIONAL qualifier indicates that the value of a
+component is optional and need not be present in the set.
+The DEFAULT qualifier also indicates that the value of a
+component is optional, and assigns a default value to the
+component when the component is absent.
+
+The types must have distinct tags. This requirement is
+typically satisfied with explicit or implicit tagging on
+some of the components.
+
+BER encoding. Constructed. Contents octets are the
+concatenation of the BER encodings of the values of the
+components of the set, in any order, with the following
+rules for components with the OPTIONAL and DEFAULT
+qualifiers:
+
+     o    if the value of a component with the OPTIONAL or
+          DEFAULT qualifier is absent from the set, then the
+          encoding of that component is not included in the
+          contents octets
+
+     o    if the value of a component with the DEFAULT
+          qualifier is the default value, then the encoding
+          of that component may or may not be included in
+          the contents octets
+
+DER encoding. Constructed. Contents octets are the same as
+for the BER encoding, except that:
+
+     1.   If the value of a component with the DEFAULT
+          qualifier is the default value, the encoding of
+          that component is not included.
+
+     2.   There is an order to the components, namely
+          ascending order by tag.
+
+
+5.15 SET OF
+
+The SET OF type denotes an unordered collection of zero or
+more occurrences of a given type.
+
+The SET OF type is used for sets of attributes in PKCS #6,
+#7, #8, #9 and #10, for sets of message-digest algorithm
+identifiers, signer information, and recipient information
+in PKCS #7, and in X.501 distinguished names.
+
+ASN.1 notation:
+
+SET OF Type
+
+where Type is a type.
+
+Example: X.501's RelativeDistinguishedName type consists of
+zero or more occurrences of the AttributeValueAssertion
+type, where the order is unimportant:
+
+RelativeDistinguishedName ::=
+  SET OF AttributeValueAssertion
+
+BER encoding. Constructed. Contents octets are the
+concatenation of the BER encodings of the values of the
+occurrences in the collection, in any order.
+
+DER encoding. Constructed. Contents octets are the same as
+for the BER encoding, except that there is an order, namely
+ascending lexicographic order of BER encoding. Lexicographic
+comparison of two different BER encodings is done as
+follows: Logically pad the shorter BER encoding after the
+last octet with dummy octets that are smaller in value than
+any normal octet. Scan the BER encodings from left to right
+until a difference is found. The smaller-valued BER encoding
+is the one with the smaller-valued octet at the point of
+difference.
+
+
+5.16 T61String
+
+The T61String type denotes an arbtrary string of T.61
+characters. T.61 is an eight-bit extension to the ASCII
+character set. Special "escape" sequences specify the
+interpretation of subsequent character values as, for
+example, Japanese; the initial interpretation is Latin. The
+character set includes non-printing control characters. The
+T61String type allows only the Latin and Japanese character
+interepretations, and implementors' agreements for directory
+names exclude control characters [NIST92]. A T61String value
+can have any length, including zero. This type is a string
+type.
+
+The T61String type is used in PKCS #9's unstructured-address
+and challenge-password attributes, and in several X.521
+attributes.
+
+ASN.1 notation:
+
+T61String
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the contents octets give the characters in the
+T.61 string, encoded in ASCII. In a constructed encoding,
+the contents octets give the concatenation of the BER
+encodings of consecutive substrings of the T.61 string.
+
+Example: The BER encoding of the T61String value "cl'es
+publiques" (French for "public keys") can be any of the
+following, among others, depending on the form of length
+octets and whether the encoding is primitive or constructed:
+
+14 0f                                           DER encoding
+   63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73
+
+14 81 0f                          long form of length octets
+   63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73
+
+34 15      constructed encoding: "cl'es" + " " + "publiques"
+   14 05 63 6c c2 65 73
+   14 01 20
+   14 09 70 75 62 6c 69 71 75 65 73
+
+The eight-bit character c2 is a T.61 prefix that adds an
+acute accent (') to the next character.
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+Example: The DER encoding of the T61String value "cl'es
+publiques" is
+
+14 0f 63 6c c2 65 73 20 70 75 62 6c 69 71 75 65 73
+
+
+5.17 UTCTime
+
+The UTCTime type denotes a "coordinated universal time" or
+Greenwich Mean Time (GMT) value. A UTCTime value includes
+the local time precise to either minutes or seconds, and an
+offset from GMT in hours and minutes. It takes any of the
+following forms:
+
+YYMMDDhhmmZ
+YYMMDDhhmm+hh'mm'
+YYMMDDhhmm-hh'mm'
+YYMMDDhhmmssZ
+YYMMDDhhmmss+hh'mm'
+YYMMDDhhmmss-hh'mm'
+
+where:
+
+     YY is the least significant two digits of the year
+
+     MM is the month (01 to 12)
+
+     DD is the day (01 to 31)
+
+     hh is the hour (00 to 23)
+
+     mm are the minutes (00 to 59)
+
+     ss are the seconds (00 to 59)
+
+     Z indicates that local time is GMT, + indicates that
+          local time is later than GMT, and - indicates that
+          local time is earlier than GMT
+
+     hh' is the absolute value of the offset from GMT in
+          hours
+
+     mm' is the absolute value of the offset from GMT in
+          minutes
+
+This type is a string type.
+
+The UTCTime type is used for signing times in PKCS #9's
+signing-time attribute and for certificate validity periods
+in X.509's Validity type.
+
+ASN.1 notation:
+
+UTCTime
+
+BER encoding. Primitive or constructed. In a primitive
+encoding, the contents octets give the characters in the
+string, encoded in ASCII. In a constructed encoding, the
+contents octets give the concatenation of the BER encodings
+of consecutive substrings of the string. (The constructed
+encoding is not particularly interesting, since UTCTime
+values are so short, but the constructed encoding is
+permitted.)
+
+Example: The time this sentence was originally written was
+4:45:40 p.m. Pacific Daylight Time on May 6, 1991, which can
+be represented with either of the following UTCTime values,
+among others:
+
+"910506164540-0700"
+
+"910506234540Z"
+
+These values have the following BER encodings, among others:
+
+17 0d 39 31 30 35 30 36 32 33 34 35 34 30 5a
+
+17 11 39 31 30 35 30 36 31 36 34 35 34 30 2D 30 37 30
+      30
+
+DER encoding. Primitive. Contents octets are as for a
+primitive BER encoding.
+
+
+6. An example
+
+This section gives an example of ASN.1 notation and DER
+encoding: the X.501 type Name.
+
+
+6.1 Abstract notation
+
+This section gives the ASN.1 notation for the X.501 type
+Name.
+
+Name ::= CHOICE {
+  RDNSequence }
+
+RDNSequence ::= SEQUENCE OF RelativeDistinguishedName
+
+RelativeDistinguishedName ::=
+  SET OF AttributeValueAssertion
+
+AttributeValueAssertion ::= SEQUENCE {
+   AttributeType,
+   AttributeValue }
+
+AttributeType ::= OBJECT IDENTIFIER
+
+AttributeValue ::= ANY
+
+The Name type identifies an object in an X.500 directory.
+Name is a CHOICE type consisting of one alternative:
+RDNSequence. (Future revisions of X.500 may have other
+alternatives.)
+
+The RDNSequence type gives a path through an X.500 directory
+tree starting at the root. RDNSequence is a SEQUENCE OF type
+consisting of zero or more occurences of
+RelativeDistinguishedName.
+
+The RelativeDistinguishedName type gives a unique name to an
+object relative to the object superior to it in the
+directory tree. RelativeDistinguishedName is a SET OF type
+consisting of zero or more occurrences of
+AttributeValueAssertion.
+
+The AttributeValueAssertion type assigns a value to some
+attribute of a relative distinguished name, such as country
+name or common name. AttributeValueAssertion is a SEQUENCE
+type consisting of two components, an AttributeType type and
+an AttributeValue type.
+
+The AttributeType type identifies an attribute by object
+identifier. The AttributeValue type gives an arbitrary
+attribute value. The actual type of the attribute value is
+determined by the attribute type.
+
+
+6.2 DER encoding
+
+This section gives an example of a DER encoding of a value
+of type Name, working from the bottom up.
+
+The name is that of the Test User 1 from the PKCS examples
+[Kal93]. The name is represented by the following path:
+
+                           (root)
+                              |
+                     countryName = "US"
+                              |
+          organizationName = "Example Organization"
+                              |
+                 commonName = "Test User 1"
+
+Each level corresponds to one RelativeDistinguishedName
+value, each of which happens for this name to consist of one
+AttributeValueAssertion value. The AttributeType value is
+before the equals sign, and the AttributeValue value (a
+printable string for the given attribute types) is after the
+equals sign.
+
+The countryName, organizationName, and commonUnitName are
+attribute types defined in X.520 as:
+
+attributeType OBJECT IDENTIFIER ::=
+  { joint-iso-ccitt(2) ds(5) 4 }
+
+countryName OBJECT IDENTIFIER ::= { attributeType 6 }
+organizationName OBJECT IDENTIFIER ::=
+  { attributeType 10 }
+commonUnitName OBJECT IDENTIFIER ::=
+  { attributeType 3 }
+
+
+6.2.1 AttributeType
+
+The three AttributeType values are OCTET STRING values, so
+their DER encoding follows the primitive, definite-length
+method:
+
+06 03 55 04 06                                   countryName
+
+06 03 55 04 0a                              organizationName
+
+06 03 55 04 03                                    commonName
+
+The identifier octets follow the low-tag form, since the tag
+is 6 for OBJECT IDENTIFIER. Bits 8 and 7 have value "0,"
+indicating universal class, and bit 6 has value "0,"
+indicating that the encoding is primitive. The length octets
+follow the short form. The contents octets are the
+concatenation of three octet strings derived from
+subidentifiers (in decimal): 40 * 2 + 5 = 85 = 5516; 4; and
+6, 10, or 3.
+
+
+6.2.2 AttributeValue
+
+The three AttributeValue values are PrintableString values,
+so their encodings follow the primitive, definite-length
+method:
+
+13 02 55 53                                             "US"
+
+13 14                                 "Example Organization"
+   45 78 61 6d 70 6c 65 20 4f 72 67 61 6e 69 7a 61
+   74 69 6f 6e
+
+13 0b                                          "Test User 1"
+   54 65 73 74 20 55 73 65 72 20 31
+
+The identifier octets follow the low-tag-number form, since
+the tag for PrintableString, 19 (decimal), is between 0 and
+30. Bits 8 and 7 have value "0" since PrintableString is in
+the universal class. Bit 6 has value "0" since the encoding
+is primitive. The length octets follow the short form, and
+the contents octets are the ASCII representation of the
+attribute value.
+
+
+6.2.3 AttributeValueAssertion
+
+The three AttributeValueAssertion values are SEQUENCE
+values, so their DER encodings follow the constructed,
+definite-length method:
+
+30 09                                     countryName = "US"
+   06 03 55 04 06
+   13 02 55 53
+
+30 1b              organizationName = "Example Organizaiton"
+   06 03 55 04 0a
+   13 14 ... 6f 6e
+
+30 12                             commonName = "Test User 1"
+   06 03 55 04 0b
+   13 0b ... 20 31
+
+The identifier octets follow the low-tag-number form, since
+the tag for SEQUENCE, 16 (decimal), is between 0 and 30.
+Bits 8 and 7 have value "0" since SEQUENCE is in the
+universal class. Bit 6 has value "1" since the encoding is
+constructed. The length octets follow the short form, and
+the contents octets are the concatenation of the DER
+encodings of the attributeType and attributeValue
+components.
+
+
+6.2.4 RelativeDistinguishedName
+
+The three RelativeDistinguishedName values are SET OF
+values, so their DER encodings follow the constructed,
+definite-length method:
+
+31 0b
+   30 09 ... 55 53
+
+31 1d
+   30 1b ... 6f 6e
+
+31 14
+   30 12 ... 20 31
+
+The identifier octets follow the low-tag-number form, since
+the tag for SET OF, 17 (decimal), is between 0 and 30. Bits
+8 and 7 have value "0" since SET OF is in the universal
+class Bit 6 has value "1" since the encoding is constructed.
+The lengths octets follow the short form, and the contents
+octets are the DER encodings of the respective
+AttributeValueAssertion values, since there is only one
+value in each set.
+
+
+6.2.5 RDNSequence
+
+The RDNSequence value is a SEQUENCE OF value, so its DER
+encoding follows the constructed, definite-length method:
+
+30 42
+   31 0b ... 55 53
+   31 1d ... 6f 6e
+   31 14 ... 20 31
+
+The identifier octets follow the low-tag-number form, since
+the tag for SEQUENCE OF, 16 (decimal), is between 0 and 30.
+Bits 8 and 7 have value "0" since SEQUENCE OF is in the
+universal class. Bit 6 has value "1" since the encoding is
+constructed. The lengths octets follow the short form, and
+the contents octets are the concatenation of the DER
+encodings of the three RelativeDistinguishedName values, in
+order of occurrence.
+
+
+6.2.6 Name
+
+The Name value is a CHOICE value, so its DER encoding is the
+same as that of the RDNSequence value:
+
+30 42
+   31 0b
+      30 09
+         06 03 55 04 06          attributeType = countryName
+         13 02 55 53                   attributeValue = "US"
+   31 1d
+      30 1b
+         06 03 55 04 0a     attributeType = organizationName
+         13 14       attributeValue = "Example Organization"
+            45 78 61 6d 70 6c 65 20 4f 72 67 61 6e 69 7a 61
+            74 69 6f 6e
+
+   31 14
+      30 12
+         06 03 55 04 03           attributeType = commonName
+         13 0b                attributeValue = "Test User 1"
+            54 65 73 74 20 55 73 65 72 20 31
+
+
+References
+
+PKCS #1   RSA Laboratories. PKCS #1: RSA Encryption
+          Standard. Version 1.5, November 1993.
+
+PKCS #3   RSA Laboratories. PKCS #3: Diffie-Hellman Key-
+          Agreement Standard. Version 1.4, November 1993.
+
+PKCS #5   RSA Laboratories. PKCS #5: Password-Based
+          Encryption Standard. Version 1.5, November 1993.
+
+PKCS #6   RSA Laboratories. PKCS #6: Extended-Certificate
+          Syntax Standard. Version 1.5, November 1993.
+
+PKCS #7   RSA Laboratories. PKCS #7: Cryptographic Message
+          Syntax Standard. Version 1.5, November 1993.
+
+PKCS #8   RSA Laboratories. PKCS #8: Private-Key Information
+          Syntax Standard. Version 1.2, November 1993.
+
+PKCS #9   RSA Laboratories. PKCS #9: Selected Attribute
+          Types. Version 1.1, November 1993.
+
+PKCS #10  RSA Laboratories. PKCS #10: Certification Request
+          Syntax Standard. Version 1.0, November 1993.
+
+X.200     CCITT. Recommendation X.200: Reference Model of
+          Open Systems Interconnection for CCITT
+          Applications. 1984.
+
+X.208     CCITT. Recommendation X.208: Specification of
+          Abstract Syntax Notation One (ASN.1). 1988.
+
+X.209     CCITT. Recommendation X.209: Specification of
+          Basic Encoding Rules for Abstract Syntax Notation
+          One (ASN.1). 1988.
+
+X.500     CCITT. Recommendation X.500: The
+          Directory--Overview of Concepts, Models and
+          Services. 1988.
+
+X.501     CCITT. Recommendation X.501: The Directory--
+          Models. 1988.
+
+X.509     CCITT. Recommendation X.509: The Directory--
+          Authentication Framework. 1988.
+
+X.520     CCITT. Recommendation X.520: The Directory--
+          Selected Attribute Types. 1988.
+
+[Kal93]   Burton S. Kaliski Jr. Some Examples of the PKCS
+          Standards. RSA Laboratories, November 1993.
+
+[NIST92]  NIST. Special Publication 500-202: Stable
+          Implementation Agreements for Open Systems
+          Interconnection Protocols. Part 11 (Directory
+          Services Protocols). December 1992.
+
+
+Revision history
+
+
+June 3, 1991 version
+
+The June 3, 1991 version is part of the initial public
+release of PKCS. It was published as NIST/OSI Implementors'
+Workshop document SEC-SIG-91-17.
+
+
+November 1, 1993 version
+
+The November 1, 1993 version incorporates several editorial
+changes, including the addition of a revision history. It is
+updated to be consistent with the following versions of the
+PKCS documents:
+
+     PKCS #1: RSA Encryption Standard. Version 1.5, November
+          1993.
+
+     PKCS #3: Diffie-Hellman Key-Agreement Standard. Version
+          1.4, November 1993.
+
+     PKCS #5: Password-Based Encryption Standard. Version
+          1.5, November 1993.
+
+     PKCS #6: Extended-Certificate Syntax Standard. Version
+          1.5, November 1993.
+
+     PKCS #7: Cryptographic Message Syntax Standard. Version
+          1.5, November 1993.
+
+     PKCS #8: Private-Key Information Syntax Standard.
+          Version 1.2, November 1993.
+
+     PKCS #9: Selected Attribute Types. Version 1.1,
+          November 1993.
+
+     PKCS #10: Certification Request Syntax Standard.
+          Version 1.0, November 1993.
+
+The following substantive changes were made:
+
+     Section 5: Description of T61String type is added.
+
+     Section 6: Names are changed, consistent with other
+          PKCS examples.
+
+
+Author's address
+
+Burton S. Kaliski Jr., Ph.D.
+Chief Scientist
+RSA Laboratories              (415) 595-7703
+100 Marine Parkway            (415) 595-4126 (fax)
+Redwood City, CA  94065  USA  burt@rsa.com
diff --git a/third_party/heimdal/doc/mdate-sh b/third_party/heimdal/doc/mdate-sh
new file mode 100644
index 0000000..37171f2
--- /dev/null
+++ b/third_party/heimdal/doc/mdate-sh
@@ -0,0 +1,92 @@
+#!/bin/sh
+# Get modification time of a file or directory and pretty-print it.
+# Copyright (C) 1995, 1996, 1997 Free Software Foundation, Inc.
+# written by Ulrich Drepper <drepper@gnu.ai.mit.edu>, June 1995
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+# Prevent date giving response in another language.
+LANG=C
+export LANG
+LC_ALL=C
+export LC_ALL
+LC_TIME=C
+export LC_TIME
+
+# Get the extended ls output of the file or directory.
+# On HPUX /bin/sh, "set" interprets "-rw-r--r--" as options, so the "x" below.
+if ls -L /dev/null 1>/dev/null 2>&1; then
+  set - x`ls -L -l -d $1`
+else
+  set - x`ls -l -d $1`
+fi
+# The month is at least the fourth argument
+# (3 shifts here, the next inside the loop).
+shift
+shift
+shift
+
+# Find the month.  Next argument is day, followed by the year or time.
+month=
+until test $month
+do
+  shift
+  case $1 in
+    Jan) month=January; nummonth=1;;
+    Feb) month=February; nummonth=2;;
+    Mar) month=March; nummonth=3;;
+    Apr) month=April; nummonth=4;;
+    May) month=May; nummonth=5;;
+    Jun) month=June; nummonth=6;;
+    Jul) month=July; nummonth=7;;
+    Aug) month=August; nummonth=8;;
+    Sep) month=September; nummonth=9;;
+    Oct) month=October; nummonth=10;;
+    Nov) month=November; nummonth=11;;
+    Dec) month=December; nummonth=12;;
+  esac
+done
+
+day=$2
+
+# Here we have to deal with the problem that the ls output gives either
+# the time of day or the year.
+case $3 in
+  *:*) set `date`; eval year=\$$#
+       case $2 in
+	 Jan) nummonthtod=1;;
+	 Feb) nummonthtod=2;;
+	 Mar) nummonthtod=3;;
+	 Apr) nummonthtod=4;;
+	 May) nummonthtod=5;;
+	 Jun) nummonthtod=6;;
+	 Jul) nummonthtod=7;;
+	 Aug) nummonthtod=8;;
+	 Sep) nummonthtod=9;;
+	 Oct) nummonthtod=10;;
+	 Nov) nummonthtod=11;;
+	 Dec) nummonthtod=12;;
+       esac
+       # For the first six month of the year the time notation can also
+       # be used for files modified in the last year.
+       if (expr $nummonth \> $nummonthtod) > /dev/null;
+       then
+	 year=`expr $year - 1`
+       fi;;
+  *) year=$3;;
+esac
+
+# The result.
+echo $day $month $year
diff --git a/third_party/heimdal/doc/migration.texi b/third_party/heimdal/doc/migration.texi
new file mode 100644
index 0000000..2fa7ede
--- /dev/null
+++ b/third_party/heimdal/doc/migration.texi
@@ -0,0 +1,73 @@
+@c $Id$
+
+@node Migration, Acknowledgments, Programming with Kerberos, Top
+@chapter Migration
+
+@section Migration from MIT Kerberos to Heimdal
+
+hpropd can read MIT Kerberos dump in "kdb5_util load_dump version 5" or
+version 6 format.  Simply run:
+@samp{kdb5_util dump}.
+
+To load the MIT Kerberos dump file, use the following command:
+
+@samp{/usr/heimdal/libexec/hprop --database=dump-file --master-key=/var/db/krb5kdc/mit_stash --source=mit-dump --decrypt --stdout | /usr/heimdal/libexec/hpropd --stdin}
+
+kadmin can dump in MIT Kerberos format.  Simply run:
+@samp{kadmin -l dump -f MIT}.
+
+The Heimdal KDC and kadmind, as well as kadmin -l and the libkadm5srv
+library can read and write MIT KDBs, and can read MIT stash files.  To
+build with KDB support requires having a standalone libdb from MIT
+Kerberos and associated headers, then you can configure Heildal as
+follows:
+
+@samp{./configure ... CPPFLAGS=-I/path-to-mit-db-headers LDFLAGS="-L/path-to-mit-db-object -Wl,-rpath -Wl,/path-to-mit-db-object" LDLIBS=-ldb}
+
+At this time support for MIT Kerberos KDB dump/load format and direct
+KDB access does not include support for PKINIT, or K/M key history,
+constrained delegation, and other advanced features.
+
+Heimdal supports using multiple HDBs at once, with all write going to
+just one HDB.  This allows for entries to be moved to a native HDB from
+an MIT KDB over time as those entries are changed.  Or you can use hprop
+and hpropd.
+
+@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/third_party/heimdal/doc/misc.texi b/third_party/heimdal/doc/misc.texi
new file mode 100644
index 0000000..1ad6aaa
--- /dev/null
+++ b/third_party/heimdal/doc/misc.texi
@@ -0,0 +1,58 @@
+@c $Id$
+
+@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/third_party/heimdal/doc/ntlm.din b/third_party/heimdal/doc/ntlm.din
new file mode 100644
index 0000000..71dd5ff
--- /dev/null
+++ b/third_party/heimdal/doc/ntlm.din
@@ -0,0 +1,16 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal ntlm library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/ntlm
+INPUT                  = @srcdir@/../lib/ntlm
+EXAMPLE_PATH	       = @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/third_party/heimdal/doc/programming.texi b/third_party/heimdal/doc/programming.texi
new file mode 100644
index 0000000..543e425
--- /dev/null
+++ b/third_party/heimdal/doc/programming.texi
@@ -0,0 +1,7 @@
+@c $Id$
+
+@node Programming with Kerberos, Migration, Windows compatibility, Top
+@chapter Programming with Kerberos
+
+See the Kerberos 5 API introduction and documentation on the Heimdal
+webpage.
diff --git a/third_party/heimdal/doc/setup.texi b/third_party/heimdal/doc/setup.texi
new file mode 100644
index 0000000..0b3a860
--- /dev/null
+++ b/third_party/heimdal/doc/setup.texi
@@ -0,0 +1,1784 @@
+@c $Id$
+
+@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::
+* Remote administration::
+* Password changing::
+* Testing clients and servers::
+* Slave Servers::
+* Incremental propagation::
+* Encryption types and salting::
+* Credential cache server - KCM::
+* Cross realm::
+* Transit policy::
+* Setting up DNS::
+* Using LDAP to store the database::
+* Providing Kerberos credentials to servers and programs::
+* Setting up PK-INIT::
+* Debugging Kerberos problems::
+@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.
+
+Configuration files can also include other files, or all files in a
+directory.  Use absolute paths in include directives.  When including a
+directoty, only files whose names consist of alphanumeric, hyphen, or
+underscore characters are allowed, though they may end in '.conf'.
+
+@example
+include /some/config/file
+includedir /some/config/directory
+[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
+                kdc = 130.237.237.17
+                kdc = [2001:6b0:1:ea::100]:88
+        @}
+[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.
+
+@cindex KRB5_CONFIG
+If you want to use a different configuration file then the default you
+can point a file with the environment variable @samp{KRB5_CONFIG}.
+
+@example
+env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM
+@end example
+
+@cindex GSS_MECH_CONFIG
+The GSS-API mechanism configuration file can also be changed from the
+default with the enviornment variable @samp{GSS_MECH_CONFIG}. Note that
+this file only configures additional plugin mechanisms: Kerberos, NTLM
+and SPNEGO are built in to the Heimdal GSS-API library.
+
+@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
+# chmod og-rwx /var/heimdal
+@end example
+
+Heimdal supports various database backends: lmdb (LMDB), db3 (Berkeley
+DB 3.x, 4.x, or 5.x), db1 (Berkeley DB 2.x), sqlite (SQLite3), and ldap
+(LDAP).  The default is @value{dbtype}, and is selected at build time
+from one of lmdb, db3, or db1.
+
+These defaults can be overriden in the 'database' key in the @samp{kdc}
+section of the configuration.
+
+@example
+[kdc]
+        database = @{
+                dbname = lmdb:/path/to/db-file
+                realm = REALM
+                acl_file = /path/to/kadmind.acl
+                mkey_file = /path/to/mkey
+                log_file = /path/to/iprop-log-file
+        @}
+@end example
+
+To use LDAP, see @xref{Using LDAP to store the database}.
+
+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 -l check REALM.EXAMPLE.ORG
+@end example
+
+@node keytabs, Remote administration, 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{add}
+(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 Remote administration, Password changing, keytabs, 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}.  If your realm is not setup to use DNS, you might also
+need to add a @samp{kpasswd_server} entry to the realm configuration
+in @file{/etc/krb5.conf} on client machines:
+
+@example
+[realms]
+        MY.REALM = @{
+                kdc = my.kdc my.slave.kdc
+                kpasswd_server = my.kdc
+        @}
+@end example
+
+@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 modulename: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}).  All built-in policies can be qualified with
+a module name of @samp{builtin} to unambiguously specify the built-in
+policy and not a policy by the same name from a loaded module.
+
+The built-in policies 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.
+
+@item enforce_on_admin_set
+
+The enforce_on_admin_set check subjects administrative password updates to the
+password policy. An administrative password update is a create principal or
+change password request via @command{kadmind}, or a set password request via
+@command{kpasswdd}. (A set password request is one where the authenticating
+principal differs from the principal whose password is being changed.) Password
+policies are always ignored if the authenticating principal is the kadmin
+service itself, for example when running @command{kadmin} in local mode. The
+default value for enforce_on_admin_set if not given is true.
+
+@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{verify-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 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.
+
+In addition on listening on the network to get connection from new
+slaves, the ipropd-master also listens on a status unix
+socket. kadmind and kpasswdd both open that socket when a transation
+is done and written a notification to the socket. That cause
+ipropd-master to check for new version in the log file. As a fallback in
+case a notification is lost by the unix socket, the log file is
+checked after 30 seconds of no event.
+
+@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
+
+@example
+slave# /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.
+
+@subsection Status of iprop master and slave
+
+Both the master and slave provides status of the world as they see it.
+
+The master write outs the current status of the slaves, last seen and
+their version number in @file{/var/heimdal/slaves-stats}.
+
+The slave write out the current status in @file{/var/heimdal/ipropd-slave-status}.
+
+These locations can be changed with command line options, and in the
+case of @command{ipropd_master}, the configuration file.
+
+@node Encryption types and salting, Credential cache server - KCM, 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 Credential cache server - KCM, Cross realm, Encryption types and salting, Setting up a realm
+@section Credential cache server - KCM
+@cindex KCM
+@cindex Credential cache server
+
+When KCM running is easy for users to switch between different
+kerberos principals using @file{kswitch} or built in support in
+application, like OpenSSH's GSSAPIClientIdentity.
+
+Other advantages are that there is the long term credentials are not
+written to disk and on reboot the credential is removed when kcm
+process stopps running.
+
+Configure the system startup script to start the kcm process,
+@file{/usr/heimdal/libexec/kcm} and then configure the system to use kcm in @file{krb5.conf}.
+
+@example
+[libdefaults]
+	default_cc_type = KCM
+@end example
+
+Now when you run @command{kinit} it doesn't overwrite your existing
+credentials but rather just add them to the set of
+credentials. @command{klist -l} lists the credentials and the star
+marks the default credential.
+
+@example
+$ kinit lha@@KTH.SE
+lha@@KTH.SE's Password: 
+$ klist -l
+  Name         Cache name               Expires         
+lha@@KTH.SE   0                        Nov 22 23:09:40   *
+lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   
+@end example
+
+When switching between credentials you can use @command{kswitch}.
+
+@example
+$ kswitch -i
+     Principal
+1    lha@@KTH.SE
+2    lha@@SU.SE
+Select number: 2
+@end example
+
+After switching, a new set of credentials are used as default.
+
+@example
+$ klist -l
+  Name         Cache name               Expires         
+lha@@SU.SE    Initial default ccache   Nov 22 14:14:24   *
+lha@@KTH.SE   0                        Nov 22 23:09:40   
+@end example
+
+Som applications, like openssh with Simon Wilkinsons patch applied,
+support specifiying that credential to use.  The example below will
+login to the host computer.kth.se using lha@@KTH.SE (not the current
+default credential).
+
+@example
+$ ssh \
+   -o GSSAPIAuthentication=yes \
+   -o GSSAPIKeyExchange=yes \
+   -o GSSAPIClientIdentity=lha@@KTH.SE \
+   computer.kth.se
+@end example
+
+
+
+@node Cross realm, Transit policy, Credential cache server - KCM, 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
+
+Under some circumstances, you may not wish to set up direct
+cross-realm trust with every realm to which you wish to authenticate
+or from which you wish to accept authentications. Kerberos supports
+multi-hop cross-realm trust where a client principal in realm A
+authenticates to a service in realm C through a realm B with which
+both A and C have cross-realm trust relationships. In this situation,
+A and C need not set up cross-realm principals between each other.
+
+If you want to use cross-realm authentication through an intermediate
+realm, it must be explicitly allowed by either the KDCs for the realm
+to which the client is authenticating (in this case, realm C), or the
+server receiving the request. This is done in @file{krb5.conf} in the
+@code{[capaths]} section.
+
+In addition, the client in realm A need to be configured to know how
+to reach realm C via realm B. This can be done either on the client or
+via KDC configuration in the KDC for realm A.
+
+@subsection Allowing cross-realm transits
+
+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. For the
+authentication to be accepted by the final destination realm, all of
+the transited realms must be listed as trusted in the @code{[capaths]}
+configuration, either in the KDC for the destination realm or on the
+server receiving the authentication.
+
+The syntax for @code{[capaths]} section is:
+
+@example
+[capaths]
+        CLIENT-REALM = @{
+                SERVER-REALM = PERMITTED-CROSS-REALMS ...
+        @}
+@end example
+
+In the following example, the realm @code{STACKEN.KTH.SE} only has
+direct cross-realm set up with @code{KTH.SE}.  @code{KTH.SE} has
+direct cross-realm set up with @code{STACKEN.KTH.SE} and @code{SU.SE}.
+@code{DSV.SU.SE} only has direct cross-realm set up with @code{SU.SE}.
+The goal is to allow principals in the @code{DSV.SU.SE} or
+@code{SU.SE} realms to authenticate to services in
+@code{STACKEN.KTH.SE}.  This is done with the following
+@code{[capaths]} entry on either the server accepting authentication
+or on the KDC for @code{STACKEN.KTH.SE}.
+
+@example
+[capaths]
+	SU.SE = @{
+                    STACKEN.KTH.SE = KTH.SE
+	@}
+	DSV.SU.SE = @{
+                    STACKEN.KTH.SE = SU.SE KTH.SE
+	@}
+@end example
+
+The first entry allows cross-realm authentication from clients in
+@code{SU.SE} transiting through @code{KTH.SE} to
+@code{STACKEN.KTH.SE}.  The second entry allows cross-realm
+authentication from clients in @code{DSV.SU.SE} transiting through
+both @code{SU.SE} and @code{KTH.SE} to @code{STACKEN.KTH.SE}.
+
+Be careful of which realm goes where; it's easy to put realms in the
+wrong place.  The block is tagged with the client realm (the realm of
+the principal authenticating), and the realm before the equal sign is
+the final destination realm: the realm to which the client is
+authenticating.  After the equal sign go all the realms that the
+client transits through.
+
+The order of the @code{PERMITTED-CROSS-REALMS} is not important when
+doing transit cross realm verification.
+
+@subsection Configuring client cross-realm transits
+
+The @code{[capaths]} section is also used for another purpose: to tell
+clients which realm to transit through to reach a realm with which
+their local realm does not have cross-realm trust.  This can be done
+by either putting a @code{[capaths]} entry in the configuration of the
+client or by putting the entry in the configuration of the KDC for the
+client's local realm.  In the latter case, the KDC will then hand back
+a referral to the client when the client requests a cross-realm ticket
+to the destination realm, telling the client to try to go through an
+intermediate realm.
+
+For client configuration, the order of @code{PERMITTED-CROSS-REALMS}
+is significant, since only the first realm in this section (after the
+equal sign) is used by the client.
+
+For example, again consider the @code{[capaths]} entry above for the
+case of a client in the @code{SU.SE} realm, and assume that the client
+or the @code{SU.SE} KDC has that @code{[capaths]} entry.  If the
+client attempts to authenticate to a service in the
+@code{STACKEN.KTH.SE} realm, that entry says to first authenticate
+cross-realm to the @code{KTH.SE} realm (the first realm listed in the
+@code{PERMITTED-CROSS-REALMS} section), and then from there to
+@code{STACKEN.KTH.SE}.
+
+Each entry in @code{[capaths]} can only give the next hop, since only
+the first realm in @code{PERMITTED-CROSS-REALMS} is used.  If, for
+instance, a client in @code{DSV.SU.SE} had a @code{[capaths]}
+configuration as above but without the first block for @code{SU.SE},
+they would not be able to reach @code{STACKEN.KTH.SE}.  They would get
+as far as @code{SU.SE} based on the @code{DSV.SU.SE} entry in
+@code{[capaths]} and then attempt to go directly from there to
+@code{STACKEN.KTH.SE} and get stuck (unless, of course, the
+@code{SU.SE} KDC had the additional entry required to tell the client
+to go through @code{KTH.SE}).
+
+@subsection Active Directory forest example
+
+One common place where a @code{[capaths]} configuration is desirable
+is with Windows Active Directory forests.  One common Active Directory
+configuration is to have one top-level Active Directory realm but then
+divide systems, services, and users into child realms (perhaps based
+on organizational unit).  One generally establishes cross-realm trust
+only with the top-level realm, and then uses transit policy to permit
+authentications to and from the child realms.
+
+For example, suppose an organization has a Heimdal realm
+@code{EXAMPLE.COM}, a Windows Active Directory realm
+@code{WIN.EXAMPLE.COM}, and then child Active Directory realms
+@code{ENGR.WIN.EXAMPLE.COM} and @code{SALES.WIN.EXAMPLE.COM}.  The
+goal is to allow users in any of these realms to authenticate to
+services in any of these realms.  The @code{EXAMPLE.COM} KDC (and
+possibly client) configuration should therefore contain a
+@code{[capaths]} section as follows:
+
+@example
+[capaths]
+	ENGR.WIN.EXAMPLE.COM = @{
+		EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+	SALES.WIN.EXAMPLE.COM = @{
+		EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+	EXAMPLE.COM = @{
+		ENGR.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
+		SALES.WIN.EXAMPLE.COM = WIN.EXAMPLE.COM
+	@}
+@end example
+
+The first two blocks allow clients in the @code{ENGR.WIN.EXAMPLE.COM}
+and @code{SALES.WIN.EXAMPLE.COM} realms to authenticate to services in
+the @code{EXAMPLE.COM} realm.  The third block tells the client (or
+tells the KDC to tell the client via referrals) to transit through
+@code{WIN.EXAMPLE.COM} to reach these realms.  Both sides of the
+configuration are needed for bi-directional transited cross-realm
+authentication.
+
+@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.
+
+This assumes, OpenLDAP 2.3 or later.
+
+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
+Optionally configure OpenLDAP with @kbd{--enable-local} to enable the
+local transport.
+
+@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. For
+example:
+
+@example
+access to *
+        by dn.exact="uid=heimdal,dc=services,dc=example,dc=com" write
+        ...
+
+authz-regexp "gidNumber=.*\\\+uidNumber=0,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.
+
+If a non-local LDAP connection is used, the authz-regexp is not
+needed as Heimdal will bind to LDAP over the network using
+provided credentials.
+
+Since Heimdal talks to the LDAP server over a UNIX domain socket when
+configured for ldapi:///, 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]
+	# Optional configuration
+	hdb-ldap-structural-object = inetOrgPerson
+	hdb-ldap-url = ldapi:/// (default), ldap://hostname or ldaps://hostname
+	hdb-ldap-secret-file = /path/to/file/containing/ldap/credentials
+	hdb-ldap-start-tls = false
+
+        database = @{
+                dbname = ldap:ou=KerberosPrincipals,dc=example,dc=com
+                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.
+
+If connecting to a server over a non-local transport, the @samp{hdb-ldap-url}
+and @samp{hdb-ldap-secret-file} options must be provided. The
+@samp{hdb-ldap-secret-file} must contain the bind credentials:
+
+@example
+[kdc]
+	hdb-ldap-bind-dn = uid=heimdal,dc=services,dc=example,dc=com
+	hdb-ldap-bind-password = secretBindPassword
+@end example
+
+The @samp{hdb-ldap-secret-file} and should be protected with appropriate
+file permissions
+
+@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> add 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 smbk5pwd overlay
+
+The smbk5pwd overlay, updates the krb5Key and krb5KeyVersionNumber
+appropriately when it receives an LDAP Password change Extended
+Operation:
+
+@url{http://www.openldap.org/devel/cvsweb.cgi/contrib/slapd-modules/smbk5pwd/README?hideattic=1&sortbydate=0}
+
+@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, Debugging Kerberos problems, Providing Kerberos credentials to servers and programs, Setting up a realm
+@section Setting up PK-INIT
+
+PK-INIT leverages an existing PKI (public key infrastructure), using
+certificates to get the initial ticket (usually the krbtgt
+ticket-granting ticket).
+
+To use PK-INIT you must first have a PKI. If you don't have one, it is
+time to create it. You should first read the whole current chapter of
+the document to see the requirements imposed on the CA software.
+
+A mapping between the PKI certificate and what principals that
+certificate is allowed to use must exist. There are several ways to do
+this. The administrator can use a configuration file, store the
+principal in the SubjectAltName extension of the certificate, or store
+the mapping in the principals entry in the kerberos database.
+
+@section Certificates
+
+This and following subsection documents the requirements on the KDC
+and client certificates and the format used in the id-pkinit-san
+OtherName extension.
+
+On how to create certificates, you should read @ref{Use OpenSSL to
+create certificates}.
+
+@subsection KDC certificate
+
+The certificate for the KDC has several 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.  Also, if the certificate has a
+nameConstraints extension with a Generalname with dNSName or iPAdress,
+it must match the hostname or adress of the KDC.
+
+The client is not required by the standard to check the server
+certificate for this information if the client has external
+information confirming which certificate the KDC is supposed to be
+using. However, adding this information to the KDC certificate removes
+the need to specially configure the client to recognize the KDC
+certificate.
+
+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
+a password or other private information) that it is supposed to keep
+secret.
+
+@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 configuration 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.
+
+This behavior is controlled by KDC configuration option:
+
+@example
+[kdc]
+	pkinit_principal_in_certificate = yes
+@end example
+
+@subsubsection Using KRB5PrincipalName in id-pkinit-san
+
+The OtherName extension in the GeneralName is used to do the mapping
+between certificate and principal.  For the KDC certificate, this
+stores the krbtgt principal name for that KDC.  For the client
+certificate, this stores the principal for which that certificate is
+allowed to get tickets.
+
+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 supports several different syntaxes for specifying
+certificate files or formats. Several formats may be used:  PEM,
+certificates embedded in PKCS#12 files, certificates embedded in
+PKCS#11 devices, and raw DER encoded certificates.
+
+Those formats may be specified as follows:
+
+@table @asis
+
+@item DIR:
+
+DIR specifies a directory which contains certificates in the DER or
+PEM format.
+
+The main feature of DIR is that the directory is read on demand when
+iterating over certificates. This allows applications, in some
+situations, to avoid having to store all certificates in memory.  It's
+very useful for tests that iterate over large numbers of certificates.
+
+The syntax is:
+
+@example
+DIR:/path/to/der/files
+@end example
+
+@item FILE:
+
+FILE: specifies a file that contains a certificate or 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. Multiple files may be specified, separated by
+commas.
+
+It's useful to have one PEM file that contains all the trust anchors.
+
+The syntax is:
+
+@example
+FILE:certificate.pem,private-key.key,other-cert.pem,....
+@end example
+
+@item PKCS11:
+
+PKCS11: is used to handle smartcards via PKCS#11 drivers, such as
+soft-token, opensc, or muscle. The argument specifies a shared object
+that implements the PKCS#11 API. The default is to use all slots on
+the device/token.
+
+The syntax is:
+
+@example
+PKCS11:shared-object.so
+@end example
+
+@item PKCS12:
+
+PKCS12: is used to handle PKCS#12 files. PKCS#12 files commonly have
+the extension pfx or p12.
+
+The 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 the subsections below for how to do that. Then, you can
+use kinit to get yourself tickets. For example:
+
+@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 PKCS#11 it can look like this instead:
+
+@example
+$ kinit -C PKCS11:/usr/heimdal/lib/hx509.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
+
+@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
+
+Configuration options for the KDC.
+
+@table @asis
+@item enable-pkinit = bool
+
+Enable PKINIT for this KDC.
+
+@item pkinit_identity = string
+
+Identity that the KDC will use when talking to clients. Mandatory.
+
+@item pkinit_anchors = string
+
+Trust anchors that the KDC will use when evaluating the trust of the
+client certificate. Mandatory.
+
+@item pkinit_pool = strings ...
+
+Extra certificate the KDC will use when building trust chains if it
+can't find enough certificates in the request from the client.
+
+@item pkinit_allow_proxy_certificate = bool
+
+Allow clients to use proxy certificates. The root certificate
+of the client's End Entity certificate is used for authorisation.
+
+@item pkinit_win2k_require_binding = bool
+
+Require windows clients up be upgrade to not allow cut and paste
+attack on encrypted data, applies to Windows XP and windows 2000
+servers.
+
+@item pkinit_principal_in_certificate = bool
+
+Enable the KDC to use id-pkinit-san to determine to determine the
+mapping between a certificate and principal.
+
+@end table
+
+@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 = no
+	pkinit_win2k_require_binding = yes
+	pkinit_principal_in_certificate = no
+@end example
+
+@subsection Using pki-mapping file
+
+Note that the file contents are 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
+
+You can also store the subject of the certificate in the principal
+entry in the kerberos database.
+
+@example
+kadmin modify --pkinit-acl="CN=baz,DC=test,DC=h5l,DC=se" user@@REALM
+@end example
+
+@section Use hxtool to create certificates
+
+@subsection Generate certificates
+
+First, you need to generate a CA certificate. This example creates a
+CA certificate that will be valid for 10 years.
+
+You need to change --subject in the command below to something
+appropriate for your site.
+
+@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 to something appropriate for your site.
+
+@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 certificates. For your first client,
+generate a certificate of 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 to something appropriate for your site. You can omit
+--pk-init-principal if you're going to use the ACL file instead.
+
+@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
+they provide a good test of whether 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
+@anchor{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 an
+@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 could 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 has 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 so that it
+includes all the information required to 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''.
+
+@node Debugging Kerberos problems, , Setting up PK-INIT, Setting up a realm
+@section Debugging Kerberos problems
+
+To debug Kerberos client and server problems you can enable debug
+tracing by adding the following to @file{/etc/krb5.conf}. Note that the
+trace logging is sparse at the moment, but will continue to improve.
+
+@example
+[logging]
+        libkrb5 = 0-/SYSLOG:
+@end example
+
+
+
+
diff --git a/third_party/heimdal/doc/vars.tin b/third_party/heimdal/doc/vars.tin
new file mode 100644
index 0000000..0907397
--- /dev/null
+++ b/third_party/heimdal/doc/vars.tin
@@ -0,0 +1,8 @@
+
+@c
+@c Variables depending on installation
+@c
+
+@set dbdir @dbdir@
+@set dbtype @dbtype@
+@set PACKAGE_VERSION @PACKAGE_VERSION@
diff --git a/third_party/heimdal/doc/whatis.texi b/third_party/heimdal/doc/whatis.texi
new file mode 100644
index 0000000..902344b
--- /dev/null
+++ b/third_party/heimdal/doc/whatis.texi
@@ -0,0 +1,214 @@
+@c $Id$
+
+@node What is Kerberos?, What is PKIX?, 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
+
+@iftex
+@macro sub{arg}
+@textsubscript{\arg\}
+@end macro
+@end iftex
+
+@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/}.
+
+@node What is PKIX?, What is a Certification Authority (CA)?, What is Kerberos?, Top
+@chapter What is PKIX?
+
+PKIX is the set of Internet standards for Public Key Infrastructure (PKI),
+based on the ITU-T's x.509 standads.  PKI is an authentication mechanism based
+on public keys (the 'PK' in 'PKI').
+
+In PKIX we have public keys "certified" by certification authorities (CAs).  A
+"relying party" is software that validates an entity's certificate and, if
+valid, trusts the certified public key to "speak for" the entity identified by
+the certificate.
+
+In a PKI every entity has one (or more) certified public/private key pairs.
+
+@node What is a Certification Authority (CA)?, What is kx509?, What is PKIX?, Top
+@chapter What is a Certification Authority (CA)?
+
+A Certification Authority (CA) is an entity in a PKI that issues certificates
+to other entities -- a CA certifies that a public key speaks for a particular,
+named entity.
+
+There are two types of CAs: off-line and online.  Typically PKI hierarchies are
+organized such that the most security-critical private keys are only used by
+off-line CAs to certify the less security-critical public keys of online CAs.
+
+Heimdal has support for off-line CAs using its Hx509 library and hxtool
+command.
+
+Heimdal also has an online CA with a RESTful, HTTPS-based protocol.
+
+@node What is kx509?, What is bx509?, What is a Certification Authority (CA)?, Top
+@chapter What is kx509?
+
+kx509 is a kerberized certification authority (CA).  Heimdal implements this
+protocol in its KDC.  The protocol is specified by <a
+href="http://www.ietf.org/rfc/rfc6717.txt">RFC 6717</a>, though Heimdal has
+implemented a number of extensions as well.  A client is implemented by the
+heimtools command's kx509 sub-command.
+
+@node What is bx509?, Building and Installing, What is kx509?, Top
+@chapter What is kx509?
+
+bx509 is an online CA, like kx509, but the protocol is based on HTTPS.
+
+Heimdal's bx509d implementation of bx509 implements two authentication bridges:
+a "/bx509" end-point that allows clients to trade bearer tokens (including
+Negotiate/Kerberos) and CSRs for certificates, and a "/bnegotiate" end-point
+allowing clients to trade bearer tokens (including Negotiate/Kerberos) for
+Negotiate tokens to HTTP servers.
diff --git a/third_party/heimdal/doc/win2k.texi b/third_party/heimdal/doc/win2k.texi
new file mode 100644
index 0000000..0fefeee
--- /dev/null
+++ b/third_party/heimdal/doc/win2k.texi
@@ -0,0 +1,315 @@
+@c $Id$
+
+
+@node Windows compatibility, Programming with Kerberos, Kerberos 4 issues, Top
+@comment  node-name,  next,  previous,  up
+@chapter Windows compatibility
+
+Microsoft Windows, starting from version 2000 (formerly known as Windows NT 5), implements Kerberos 5. Their implementation, however, has some quirks,
+peculiarities, and bugs. This chapter is a short summary of the compatibility
+issues between Heimdal and various Windows versions.
+
+The big problem with the Kerberos implementation in Windows
+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. 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 to use a Heimdal KDC::  
+* Inter-Realm keys (trust) between Windows and a Heimdal KDC::  
+* Create account mappings::     
+* Encryption types::            
+* Authorisation data::          
+* Quirks of Windows 2000 KDC::  
+* Useful links when reading about the Windows::  
+@end menu
+
+@node Configuring Windows to use a Heimdal KDC, Inter-Realm keys (trust) between Windows and a Heimdal KDC, Windows compatibility, Windows compatibility
+@comment node-name, next, precious, up
+@section Configuring Windows to use a Heimdal KDC
+
+You need the command line program called @command{ksetup.exe}. This program comes with the Windows Support Tools, available from either the installation CD-ROM (@file{SUPPORT/TOOLS/SUPPORT.CAB}), or from Microsoft web site. Starting from Windows 2008, it is already installed. 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 and a Heimdal KDC, Create account mappings, Configuring Windows to use a Heimdal KDC, Windows compatibility
+@comment node-name, next, precious, up
+@section Inter-Realm keys (trust) between Windows and a Heimdal KDC
+
+See also the Step-by-Step guide from Microsoft, referenced below.
+
+Install Windows, 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 on what hosts to find the KDCs for the
+non-Windows realm with @command{ksetup}, see @xref{Configuring Windows 
+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. But take
+care to the encryption types and salting used for those keys. There should be
+no encryption type stronger than the one configured on Windows side for this
+relationship, itself limited to the ones supported by this specific version of
+Windows, nor any Kerberos 4 salted hashes, as Windows does not seem to
+understand them. Otherwise, the trust will not works.
+
+Here are the version-specific needed information:
+@enumerate
+@item Windows 2000: maximum encryption type is DES
+@item Windows 2003: maximum encryption type is DES
+@item Windows 2003RC2: maximum encryption type is RC4, relationship defaults to DES
+@item Windows 2008: maximum encryption type is AES, relationship defaults to RC4
+@end enumerate
+
+For Windows 2003RC2, to change the trust encryption type, you have to use the
+@command{ktpass}, from the Windows 2003 Resource kit *service pack2*, available
+from Microsoft web site.
+
+@example
+C:> ktpass /MITRealmName UNIX.EXAMPLE.COM /TrustEncryp RC4 
+@end example
+
+For Windows 2008, the same operation can be done with the @command{ksetup}, installed by default.
+
+@example
+C:> ksetup /SetEncTypeAttre EXAMPLE.COM AES256-SHA1 
+@end example
+
+Once the relationship is correctly configured, you can add the required
+inter-realm keys, using heimdal default encryption types:
+
+@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.
+
+And if needed, to remove unsupported encryptions, such as the following ones for a Windows 2003RC2 server.
+
+@example
+kadmin del_enctype krbtgt/REALM.EXAMPLE.COM@@NT.EXAMPLE.COM aes256-cts-hmac-sha1-96
+kadmin del_enctype krbtgt/REALM.EXAMPLE.COM@@NT.EXAMPLE.COM des3-cbc-sha1
+kadmin del_enctype krbtgt/NT.EXAMPLE.COM@@EXAMPLE.COM aes256-cts-hmac-sha1-96
+kadmin del_enctype krbtgt/NT.EXAMPLE.COM@@EXAMPLE.COM des3-cbc-sha1
+@end example
+
+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 and a Heimdal KDC, Windows compatibility
+@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 compatibility
+@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 compatibility
+@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, Authorisation data, Windows compatibility
+@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,  , Quirks of Windows 2000 KDC, Windows compatibility
+@comment  node-name,  next,  previous,  up
+@section Useful links when reading about the Windows
+
+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
+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
diff --git a/third_party/heimdal/doc/wind.din b/third_party/heimdal/doc/wind.din
new file mode 100644
index 0000000..da36dd1
--- /dev/null
+++ b/third_party/heimdal/doc/wind.din
@@ -0,0 +1,15 @@
+# Doxyfile 1.5.3
+
+PROJECT_NAME           = Heimdal wind library
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+OUTPUT_DIRECTORY       = @srcdir@/doxyout/wind
+INPUT                  = @srcdir@/../lib/wind
+
+WARN_IF_UNDOCUMENTED   = YES
+
+PERL_PATH              = /usr/bin/perl
+
+HTML_HEADER = "@srcdir@/header.html"
+HTML_FOOTER = "@srcdir@/footer.html"
+
+@INCLUDE = "@srcdir@/doxytmpl.dxy"