diff options
Diffstat (limited to 'third_party/heimdal/doc')
35 files changed, 7485 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..60c6a8c --- /dev/null +++ b/third_party/heimdal/doc/Makefile.am @@ -0,0 +1,166 @@ +# $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 + +BUILT_SOURCES = vars.texi + +#all: html pdf dvi ps info + +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 \ + 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..4769c91 --- /dev/null +++ b/third_party/heimdal/doc/NTMakefile @@ -0,0 +1,125 @@ +######################################################################## +# +# 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)\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..2b48eda --- /dev/null +++ b/third_party/heimdal/doc/apps.texi @@ -0,0 +1,71 @@ +@c $Id$ + +@node Applications, Things in search for a better place, Setting up a realm, Top + +@chapter Applications + +@menu +* AFS:: +@end menu + +@node AFS, , Applications, 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. + 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..886bf2c --- /dev/null +++ b/third_party/heimdal/doc/copyright.texi @@ -0,0 +1,519 @@ + +@macro copynext{} +@vskip 20pt plus 1fil +@end macro + +@macro copyrightstart{} +@end macro + +@macro copyrightend{} +@end macro + + +@comment node-name, next, previous, up + +@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 <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..00041ca --- /dev/null +++ b/third_party/heimdal/doc/heimdal.texi @@ -0,0 +1,140 @@ +\input texinfo @c -*- texinfo -*- + +@c %**start of header +@c $Id$ +@setfilename heimdal.info +@settitle HEIMDAL +@iftex +@afourpaper +@end iftex +@c some sensible characters, please? +@documentencoding UTF-8 +@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:: +* 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 + +* AFS:: + +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 win2k.texi +@include programming.texi +@include migration.texi +@include ack.texi +@node Copyrights and Licenses, , Acknowledgments, Top + @comment node-name, next, previous, up +@include copyright.texi + +@c @shortcontents + +@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..4d0f056 --- /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? +@documentencoding UTF-8 +@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 +@ifnottex +@macro copynext +@end macro +@macro copyrightstart +@end macro +@macro copyrightend +@end macro +@end ifnottex + +@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/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..7c3e1e7 --- /dev/null +++ b/third_party/heimdal/doc/migration.texi @@ -0,0 +1,69 @@ +@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}. + +There are some limitations in this functionality. Users should check +the input dump and a native dump after loading to check for +differences. + +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 + +@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. + +@end itemize diff --git a/third_party/heimdal/doc/misc.texi b/third_party/heimdal/doc/misc.texi new file mode 100644 index 0000000..2d976f4 --- /dev/null +++ b/third_party/heimdal/doc/misc.texi @@ -0,0 +1,58 @@ +@c $Id$ + +@node Things in search for a better place, Windows compatibility, 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..1df24d1 --- /dev/null +++ b/third_party/heimdal/doc/setup.texi @@ -0,0 +1,1897 @@ +@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 containing any number of Kerberos +principals and namespaces. The name of a Kerberos realm is +usually a domain name in uppercase. Call your realm the same +as your site's 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:: +* Using namespaces and synthetic principals to keep the database small:: +* Using hard aliases for realm migration:: +* Using soft aliases for configuring referrals:: +* 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, and +a page for it in section 5 of the system manual. + +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@. +Finally the @samp{domain_realm} section contains a list of +mappings from domains to realms. + +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 + +When realm names correspond to domain names, one can avoid having to +configure @samp{domain_realm} mappings, and one can avoid having to +configure a @samp{default_realm} in the @samp{libdefaults} section. +DNS SRV resource records can be used for KDC discovery, obviating the +need list KDCs in the @samp{realms} section of the @samp{krb5.conf} +file. + +@cindex KRB5_CONFIG +The Heimdal libraries and commands (and the MIT ones too), support the +use of the environment variable @samp{KRB5_CONFIG} for using an +alternative configuration. + +@example +env KRB5_CONFIG=$HOME/etc/krb5.conf kinit user@@REALM +@end example + +@cindex KRB5CCNAME +The Heimdal libraries and commands (and the MIT ones too), support the +use of the environment variable @samp{KRB5CCNAME} for specifying a +credentials cache to use. See the @manpage{kinit,1} for details. + +@cindex KRB5_KTNAME +The Heimdal libraries and commands (and the MIT ones too), support the +use of the environment variable @samp{KRB5_KTNAME} for specifying a +keytab file to use for server operations. See the @manpage{kinit,1} for +details. + +@cindex KRB5_CLIENT_KTNAME +The Heimdal libraries and commands (and the MIT ones too), support the +use of the environment variable @samp{KRB5_CLIENT_KTNAME} for specifying +a keytab file to use for client operations. See the @manpage{kinit,1} +for details. + +@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 can only configure 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 Heimdal database library, @code{libhdb}, 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 configure +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. + +Note that encryption of the keys in the database is only useful when +the database is stored on external storage media that is easy to +steal. Thus for the most part there is no need to encrypt the keys in +the database. + +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, Using namespaces and synthetic principals to keep the database small, 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 Using namespaces and synthetic principals to keep the database small, Checking the setup, Modifying the database, Setting up a realm +@section Using namespaces and synthetic principals to keep the database small + +Keeping a Kerberos database small is useful for several reasons: + +@itemize @bullet +@item to avoid low write transaction rates +@item to avoid replication latency +@item to keep re-keying costs down +@end itemize + +To avoid needing database entries for client principals, configure and +enable PKINIT and synthetic principals. Alternatively, configure and +enable the use of GSS-API pre-authentication, though this is currently +experimental. + +With synthetic client principals enabled, client principals will be +deemed to exist if they can pre-authenticate using a method that +yields an authenticated principal name, and if the client principal +does not already exist. + +To lock out or disable a specific synthetic client principal, create +it in the database with the desired attributes. + +To avoid needing database entries for host-based service principals, +create virtual host-based service principal namespaces using the +@command{add_ns} sub-command of the @command{kadmin} command. Virtual +host-based service principals will exist for every possible hostname +under a containing namespace, with keys derived from the namespace's +based keys and the current key rotation period. The long-term keys of +virtual host-based service principals rotate on a hard schedule as +configured for their namespaces, so hosts and applications using them +must keep re-fetching their @samp{keytabs}. See the manual pages for +@file{krb5.conf}, @command{kadmin}, and @command{httpkadmind} for more +details. + +Using these features one can end up with a database that contains just +@code{krbtgt} principals, principals for locked users, and principals +that are neither @code{krbtgt}, user, nor host-based services. + +@node Using hard aliases for realm migration, Using soft aliases for configuring referrals, Using namespaces and synthetic principals to keep the database small, Setting up a realm +@section Using hard aliases for realm migration + +The Heimdal @command{kadmin} command can be used to add aliases to +principal entries in the Heimdal database. Aliases of principals of +the form @samp{WELLKNOWN/REFERRALS/TARGET} or +@samp{WELLKNOWN/REFERRALS/TARGET/anything} are "soft" aliases. +Aliases of principals of other forms are "hard" aliases. + +When a client makes a request for a principal's alias, and it does not +use the KDC request "canonicalize" option flag, the Heimdal KDC will +treat the alias as a distinct principal that happens to share +attributes and long-term symmetric keys and salts with the principal +it is an alias of. + +This is useful for, for example, ensuring that host-based principals +can be referred to by any aliases. + +This can also be very useful for renaming realms: add new +@code{krbtgt} principals for the new realms, then add aliases to +existing principals in their new realms. For example, a user with a +principal @code{joe@@A} can be given an alias of +@code{joes@@B}, and +then they can @code{kinit joes@@B} and get Kerberos tickets for +@code{joes@@B}. Similarly, a service principal such as +@code{HTTP/foo.bar.baz.example@@BAZ.EXAMPLE} can be given an alias such as +@code{HTTP/foo.bar.baz.example@@BAR.BAZ.EXAMPLE}, or even +@code{HTTP/foobar.new-domain.example@@NEW-DOMAIN.EXAMPLE}, and +requesting tickets with those aliases as the service names will work. + +@node Using soft aliases for configuring referrals, Checking the setup, Using hard aliases for realm migration, Setting up a realm +@section Using soft aliases for configuring referrals + +Soft aliases, which are aliases of principals of the form +@code{WELLKNOWN/REFERRALS/TARGET} or +@code{WELLKNOWN/REFERRALS/TARGET/anything}, are used to generate +referrals to other realms. Specifically, the realm of a soft alias' +canonical name is the realm to issue referrals to. + +Soft aliases can be used to configure individual referrals, but also +of entire namespaces of hostnames. To configure the issuance of +referrals for entire namespaces, make a soft alias of the form +@code{WELLKNOWN/HOSTBASED-NAMESPACE/service/namespace-fqdn@@REALM} to +have the TGS for that @samp{REALM} issue referrals for all principals +of the form @code{service/hostname@@REALM} where the hostname component +is a sub-domain of the namespace component of the alias name. + +For example, a soft alias name +@code{WELLKNOWN/HOSTBASED-NAMESPACE/host/cloud.bar.example@@BAR.EXAMPLE} +to a realm @samp{B} will cause the KDC to issue referrals to @samp{B} +for any principals such as +@samp{host/foo.cloud.bar.example@@BAR.EXAMPLE}, and +@samp{host/baz.cloud.bar.example@@BAR.EXAMPLE}, and so on. + +@node Checking the setup, keytabs, Using namespaces and synthetic principals to keep the database small, 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{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{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..8c7770b --- /dev/null +++ b/third_party/heimdal/doc/whatis.texi @@ -0,0 +1,216 @@ +@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 + +@ifhtml +@macro sub{arg} + +@html +<sub>\arg\</sub> +@end html + +@end macro +@end ifhtml + +@ifdocbook +@macro sub{arg} +@docbook +@<subscript>\arg\</subscript> +@end docbook +@end macro +@end ifdocbook + +@c @iftex +@c @macro sub{arg} +@c @textsubscript{\arg\} +@c @end macro +@c @end iftex + +@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 performance); MIT Kerberos 5 has a replay cache, +while Heimdal does not. + +However, most GSS-API applicatons do not need a replay cache at all. + +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..d4ab2fe --- /dev/null +++ b/third_party/heimdal/doc/win2k.texi @@ -0,0 +1,314 @@ +@c $Id$ + + +@node Windows compatibility, Programming with Kerberos, Things in search for a better place, 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. 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 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" |