From f327dd518ec1dcac51a777772c05f4f523a93993 Mon Sep 17 00:00:00 2001 From: no author Date: Wed, 5 Oct 1994 03:49:38 +0000 Subject: [PATCH] This commit was manufactured by cvs2svn to create tag 'BETA_4_3' git-svn-id: svn://anonsvn.mit.edu/krb5/tags/BETA_4_3@4459 dc483132-0cff-0310-8789-dd5450dbe970 --- README | 81 - doc/HOW_TO_BUILD | 131 - doc/INCOMPATIBILITY | 19 - doc/SOURCE-TREE | 118 - doc/TREE-GRAPH | 95 - doc/api/Makefile | 29 - doc/api/ccache.tex | 206 - doc/api/changebar.sty | 155 - doc/api/errors.tex | 271 -- doc/api/fixunder.sty | 48 - doc/api/functions.sty | 70 - doc/api/intro.tex | 298 -- doc/api/keytab.tex | 195 - doc/api/krb5.tex | 1296 ------ doc/api/libdes.tex | 38 - doc/api/libos.tex | 382 -- doc/api/library.tex | 97 - doc/api/rcache.tex | 152 - doc/api/tables.tex | 79 - doc/implement/Makefile | 26 - doc/implement/ccache-i.tex | 224 -- doc/implement/changebar.sty | 155 - doc/implement/cksum-i.tex | 31 - doc/implement/crc-32-i.tex | 20 - doc/implement/encrypt-i.tex | 164 - doc/implement/fixunder.sty | 48 - doc/implement/functions.sty | 70 - doc/implement/implement.tex | 94 - doc/implement/kdb-i.tex | 242 -- doc/implement/keytab-i.tex | 204 - doc/implement/libos-i.tex | 34 - doc/implement/rcache-i.tex | 142 - doc/kadm5/api-funcspec.tex | 1640 -------- doc/kadm5/api-server-design.tex | 585 --- doc/kadm5/api-unit-test.tex | 2121 ---------- doc/kadmin/cli.func-spec | 388 -- doc/krb5-protocol/krb5.constants | 143 - doc/krb5-protocol/rfc1510.errata | 105 - doc/krb5-protocol/rfc1510.txt | 6275 ------------------------------ doc/old-V4-docs/README | 4 - doc/old-V4-docs/installation.PS | 2338 ----------- doc/old-V4-docs/installation.mss | 681 ---- doc/old-V4-docs/operation.PS | 2669 ------------- doc/old-V4-docs/operation.mss | 799 ---- src/appl/popper/Imakefile | 93 - 45 files changed, 23055 deletions(-) delete mode 100644 README delete mode 100644 doc/HOW_TO_BUILD delete mode 100644 doc/INCOMPATIBILITY delete mode 100644 doc/SOURCE-TREE delete mode 100644 doc/TREE-GRAPH delete mode 100644 doc/api/Makefile delete mode 100644 doc/api/ccache.tex delete mode 100644 doc/api/changebar.sty delete mode 100644 doc/api/errors.tex delete mode 100644 doc/api/fixunder.sty delete mode 100644 doc/api/functions.sty delete mode 100644 doc/api/intro.tex delete mode 100644 doc/api/keytab.tex delete mode 100644 doc/api/krb5.tex delete mode 100644 doc/api/libdes.tex delete mode 100644 doc/api/libos.tex delete mode 100644 doc/api/library.tex delete mode 100644 doc/api/rcache.tex delete mode 100644 doc/api/tables.tex delete mode 100644 doc/implement/Makefile delete mode 100644 doc/implement/ccache-i.tex delete mode 100644 doc/implement/changebar.sty delete mode 100644 doc/implement/cksum-i.tex delete mode 100644 doc/implement/crc-32-i.tex delete mode 100644 doc/implement/encrypt-i.tex delete mode 100644 doc/implement/fixunder.sty delete mode 100644 doc/implement/functions.sty delete mode 100644 doc/implement/implement.tex delete mode 100644 doc/implement/kdb-i.tex delete mode 100644 doc/implement/keytab-i.tex delete mode 100644 doc/implement/libos-i.tex delete mode 100644 doc/implement/rcache-i.tex delete mode 100644 doc/kadm5/api-funcspec.tex delete mode 100644 doc/kadm5/api-server-design.tex delete mode 100644 doc/kadm5/api-unit-test.tex delete mode 100644 doc/kadmin/cli.func-spec delete mode 100644 doc/krb5-protocol/krb5.constants delete mode 100644 doc/krb5-protocol/rfc1510.errata delete mode 100644 doc/krb5-protocol/rfc1510.txt delete mode 100644 doc/old-V4-docs/README delete mode 100644 doc/old-V4-docs/installation.PS delete mode 100644 doc/old-V4-docs/installation.mss delete mode 100644 doc/old-V4-docs/operation.PS delete mode 100644 doc/old-V4-docs/operation.mss delete mode 100644 src/appl/popper/Imakefile diff --git a/README b/README deleted file mode 100644 index e2fb07f14..000000000 --- a/README +++ /dev/null @@ -1,81 +0,0 @@ -Beta test distribution READ-ME file. ------------------------------------ - -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. - -Now, with that out of the way, let me point you to a few things: - -The file doc/TREE-GRAPH is a graphical representation of the source -directory tree you should receive with this distribution. - -The file doc/SOURCE-TREE describes what's in each directory. - -The file doc/HOW_TO_BUILD gives instructions on how to start build -Kerberos. - -We used the ISODE release 8.0 ASN.1 compiler for the code we have run -and tested here at MIT. If you are using ISODE 6.8, you will need to -apply the patches found in the file tools/pepsy-diffs to fix some bugs -in the PEPSY compiler which have caused us problems. I believe that -ISODE 8.0 should work without any problems. However, I have not had a -chance to try it out. - ->> << ->> Please report any problems/bugs/comments to 'krb5-bugs@athena.mit.edu' << ->> << - -Appreciation Time!!!! There are far too many people to try to thank -them all; many people have contributed to the development of Kerberos -V5. This is only a partial listing.... - -Thanks to Mark Eichin at Cygnus for writing the new autoconf -configuration system, for making the code much more portable, and for -serving as pre-release testers. - -Thanks to Marc Horowitz, Barry Jaspan, and Jonathan Kamens (and -others) at Openvision, Inc. for providing us with an GSS-API library, -for serving as pre-release testers, and for finding and fixing many -bugs (some of them at the last minute!). - -Thanks to Cybersafe for providing patches to fix bugs with inter-realm -authentication. - -Thanks to Ari Medivnsky and Cliff Neumann for writing a ksu client. - -Thanks to Jim Miller from Suite Software for contributing many detailed -bug reports, most of them by doing desk checks over the code! - -Thanks to Prasad Upasani from ISI for porting the Berkeley -rlogin/rsh/rcp suite and for testing out our distribution on the Sun. - -Thanks to Glenn Machin and Bill Wrahe from Sandia National Labs for -contributing the kadmin server, plus lots of bugfixes. - -Thanks to Bill Sommerfeld from HP for commenting on early Kerberos -interface drafts, suggesting improvements in later coding interfaces, -and finding and fixing many bugs. - -Thanks to Paul Borman from Cray for writing the Kerberos v4 to v5 glue -layer and the Kerberos v5 subroutines for telnet. - -Thanks to Dan Bernstein, for providing the replay cache code. - -Thanks to the members of the Kerberos V5 development team at MIT, both -past and present: Jay Berkenbilt, John Carr, Don Davis, Nancy Gilman, -Barry Jaspan, John Kohl, Cliff Neuman, Jon Rochlis, Jeff Schiller, Ted -Ts'o, Tom Yu. - - -Note: - -Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, Moira, and -Zephyr are trademarks of the Massachusetts Institute of Technology (MIT). No -commercial use of these trademarks may be made without prior written -permission of MIT. - -FYI, "commercial use" means use of a name in a product or other for-profit -manner. It does NOT prevent a commercial firm from referring to the MIT -trademarks in order to convey information (although in doing so, recognition -of their trademark status should be given). diff --git a/doc/HOW_TO_BUILD b/doc/HOW_TO_BUILD deleted file mode 100644 index 7a63ab66a..000000000 --- a/doc/HOW_TO_BUILD +++ /dev/null @@ -1,131 +0,0 @@ -In the Beta 4 distribution, we have included a new build system, which -was built using the Free Software Foundation's autoconf program. This -system will hopefully make Kerberos V5 much simpler to build for most -people, and reduce the amount of effort required in porting Kerberos V5 -to a new platform. - -The imake system has been removed from this patch release, as most of -the tree is now under autoconf control. - -HOW TO BUILD KERBEROS V5 -======================== - -A) Find about 65 meg free; untar the krb5 sources. For example, - we will assume that you've untar'ed the sources into /u1/krb5, - so that the top of the source tree is /u1/krb5/src. - -B) If you don't want separate build trees for each architecture, then -use the following abbreviated procedure. - 1) cd /u1/krb5/src - 2) ./configure - 3) make - -If you have a make that supports VPATH (GNU make, for example), you -can keep your source tree pure by making a build directory, e.g. -/u1/krb5/pmax. - - 1) cd /u1/krb5/pmax - 2) ../src/configure - 3) make - -That's all there is to it! - -It is possible to pass compiler flags to to configure by using, for -example, the "--with-ccopts=FLAGS" option. Please take note that if -you use the native Ultrix compiler on a DECstation you are likely to -lose if you pass no flags to cc; md4.c takes an estimated 33 million -years to compile if you provide neither the "-g" flag nor the "-O" -flag to cc. - -It is also possible to explicitly specify a compiler to configure, -e.g. "--with-cc=gcc". - -By default, Kerberos will expect its configuration files to be in -/krb5. This can be changed by passing the -"--with-krb5-root=/KRB5_ROOT_DIR" option to configure, where -/KRB5_ROOT_DIR should be replaced with the appropriate pathname. - -If you want Kerberos V4 backwards compatibility, pass the -"--with-krb4=/KRB4_DIRECTORY" option to configure. This requires that -the V4 include files be available in /KRB4_DIRECTORY/include, and that -the V4 Kerberos library be available in /KRB4_DIRECTORY/lib. - -If, for some reason, you want to build with isode-based ASN.1 encoders -and decoders rather than our hand-coded ones, use the "--enable-isode" -flag to configure. This has not been thoroughly tested, so beware. - -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= - -include/krb5/stock/osconf.h: ---------------------------- -There are several defaults you may wish to adjust in osconf.h: - -DEFAULT_CONFIG_FILENAME The pathname to the file which defines - the known realms and their KDCs. Same - format as V4 krb.conf -DEFAULT_TRANS_FILENAME The pathname to the file which a priori - assigns hosts to realms. Same format as - V4 krb.realms -DEFAULT_LNAME_FILENAME The pathname to the database mapping - authentication names to local account names. - See kdb5_anadd(8). -DEFAULT_KEYTAB_NAME The type and pathname to the default - server keytab file (the equivalent of v4 - /etc/srvtab). -DEFAULT_KDC_ETYPE The default encryption type for the KDC. -DEFAULT_KDC_KEYTYPE The default keytype for the KDC. -KDCRCACHE The name of the replay cache used by - the KDC. -RCTMPDIR The directory which stores replay - caches. - -include/krb5/stock/config.h ----------------------------- -You might wish to adjust these flags as well: - -KRBCONF_VAGUE_ERRORS If defined, give vague and unhelpful - error messages to the client... er, - attacker. (Needed to meet silly - government regulations; most other - sites will want to keep this - undefined.) - -KRBCONF_KDC_MODIFIES_KDB Define this if you want to allow the - KDC to modify the Kerberos database; - this allows the last request - information to be updated, as well as - the failure count information. - - Note that this doesn't work if you're - using slave servers!!! It also causes - the database to be modified (and thus - need to be locked) frequently. - - - -NOTE for building Kerberos for multiple platforms -================================================= - -This is how we build Kerberos for multiple platforms here at MIT: - -Use the synctree program to build a symlink tree. The .rconf files -included in the distribution are for use with synctree. You can find -the synctree program in the same directory as you found this release, -athena-dist.mit.edu. - -Assuming you have a directory hierarchy which looks something like this: - - - |-decmips- - |-hpux---- -|-krb5-|-linux--- - |-solaris- - |-src----- - -A typical build using synctree might be: - - cd XXX/krb5 - mkdir decmips; cd decmips - synctree -s ../src -d . - ./configure - make diff --git a/doc/INCOMPATIBILITY b/doc/INCOMPATIBILITY deleted file mode 100644 index fdb377e16..000000000 --- a/doc/INCOMPATIBILITY +++ /dev/null @@ -1,19 +0,0 @@ -Incompatibility notes: -====================== - -Currently, all of the MIT implementations of the Kerberos protocol are -not fully compliant with the Kerberos RFC --- specifically, we do not -implement the DES w/ MD5 checksum which is required by the RFC. This -includes the Beta 4 release, although I expect to have this fixed in a -patch release as soon as possible. I believe that we can fix this with -minimal compatibility impacts; vendors contemplating shipment of this -code as product should wait for the patch release or contact us for -futher details. - -MIT implementations release Beta 2 and earlier are buggy in that they -incorrectly generate the ASN.1 for a TGS request message. This was -fixed in Beta 3, but the fix causes Beta 2 KDC's to be unable to -respond to Beta 3 and more recent versions due to a checksum error. -The Beta 3 KDC contains backwards compatibility code so that Beta 2 -and earlier application programs can continue to work with a Beta 3 -and more recent KDC. diff --git a/doc/SOURCE-TREE b/doc/SOURCE-TREE deleted file mode 100644 index 944126d9a..000000000 --- a/doc/SOURCE-TREE +++ /dev/null @@ -1,118 +0,0 @@ -Source tree organization (15 Jun 1994): - -admin: administrative tools - aname: manipulate aname/lname translation database - convert: convert a V4 database to a V5 database - create: create database - destroy: destroy database - edit: edit database [the most useful of the bunch] - stash: store db key for unattended service - -autotools: Tools to allow rebuild the configure scripts; requires that - you have GNU autoconf installed. - -appl: applications - bsd: The Berkeley rlogin/rsh/rcp suite - movemail: Emacs 18.57 'movemail' program with Kerberos - hooks for POP support. - popper: Berkeley POP server, with Kerberos and other - athena mods - gss-sample: sample client & server using the GSSAPI library - sample: sample client & server (using byte stream sockets) - simple: another sample client & server (using datagrams) - telnet: telnet client (v4 & v5 kerberized, plus other goodies) - libtelnet: support for telnet/telnetd - telnet: the client-side - telnetd: BSD UNIX telnet daemon - login: a version of login(8) which has the '-f' flag - necessary for using authenticated telnet - connections without a password - user-user: sample client & server using the user-to-user - protocol features. (NOTE: the client and server - programs are somewhat "backwards" in terms of how - they call the Kerberos 5 routines. Don't let this - confuse you.) - -clients: base-level kerberos clients - kinit: get tickets using password - klist: list ticket cache - kdestroy: destroy ticket cache - ksu: kerberized su program - -config: configuration control for source - >>> look at site.def, vaxbsd.cf, ultrix.cf, ibm.cf in - >>> particular for hints on things you might want to modify. - >>> Ignore the comments on the X11 stuff for now. - -doc: documentation hierarchy - api: The Kerberos api - -include: include hierarchy - krb5: kerberos-specific includes - kerberosIV: copies of kerberos v4 include files (used - for some programs which support both) - -isode: isode hierarchy. A subset of ISODE 8.0. Used only for - the autoconf setup. - -kadmin: Remote kerberos administration tools - client: The client program - kpasswd: User-client which allos users to change their - passwords - server: The server daemon - v4server: A V4 kadmin server which updates a V5 database - -kdc: Kerberos Server/Key Distribution Center - -krb524: Program which issues krb4 tickets when handed a krb5 TGT - -lib: library hierarchy - crypto: The cryptographic routines - crc-32: CRC-32 function(s) - des: MIT DES library - md4: MD4 code from Internet RFC 1186B - md5: MD5 code from Internet - os: Operating-system or configuration-specific code - - kdb: database interface routines - - krb425: link-level compatibility library; lets you link - v4 applications with v5 back-end code - - krb5: The Kerberos library - asn.1: ASN.1 definitions & glue files - The current set-up assumes that you - have ISODE 7.0 (or later) installed. - A subset of ISODE can be found in the - same directory where you picked up the - Kerberos distribution. - - ccache: credentials cache - file: file descriptor-based ccache - stdio: STDIO-based ccache - error_tables: Common Error description files & headers - free: routines to free various allocated data - structures - gssapi: GSSAPI implementation for Kerberos V5 - keytab: server key table routines - file: STDIO-based keytab - krb: Main kerberos library functions - os: Operating-system or configuration-specific code - posix: POSIX routines provided for systems - that don't have them - rcache: authenticator replay-cache code - -slave: Routines to propagate the Kerberos database from the - master to the slave databases (kprop/kpropd) - -tests: various tests - create: create a bunch of principals in a KDC database - verify: verify that the principals have the right keys - hammer: "hammer" the KDC with requests to help assure - proper KDC operation - -util: Utilities - et: The com_err library - ss: The subsystem library - makedepend: Program to rebuild the makefile dependencies - unifdef: Removes #ifdef/#endif code diff --git a/doc/TREE-GRAPH b/doc/TREE-GRAPH deleted file mode 100644 index 4630ec2c9..000000000 --- a/doc/TREE-GRAPH +++ /dev/null @@ -1,95 +0,0 @@ - - |-aname------ - |-convert---- - |-admin--------|-create----- - | |-destroy---- - | |-edit------- - | |-stash------ - | - | |-bsd-------- - | |-gss-sample- - | |-movemail--- - | | - | |-popper-----|-orig-makefiles- - | | - | |-sample-----|-sclient-------- - | | |-sserver-------- - | | - |-appl---------|-simple-----|-client--------- - | | |-server--------- - | | - | | |-arpa----------- - | |-telnet-----|-libtelnet------ - | | |-telnet--------- - | | |-telnetd-------- - | |-user_user-- - |-autotools---- - | - | |-kdestroy--- - |-clients------|-kinit------ - | |-klist------ - | |-ksu-------- - | - |-config-------|-doc-------- - |-config-files- - | - | |-gssapi----- - | |-kerberosIV- - | | - |-include------|-krb5-------|-asn.1---------- - | | |-stock---------- - | |-sys-------- - | - | |-compat----- - | |-h---------- - | | - |-isode--------|-pepsy------|-doc------------ - | | - | |-psap-------|-test----------- - | |-support---- -|-src-| |-util------- - | - | |-client----- - |-kadmin-------|-kpasswd---- - | |-server----- - | |-v4server--- - |-kdc---------- - |-krb524------- - | - | |-crc32---------- - | | - | |-des------------|-doc--- - | |-crypto-----|-md4------------ - | | |-md5------------ - | | |-os------------- - | |-des425----- - | | - | | |-generic-------- - | |-gssapi-----|-krb5----------- - | | |-sample--------- - | |-kdb-------- - |-lib----------|-krb425----- - | | - | | |-asn.1---------- - | | | - | | |-ccache---------|-file-- - | | | |-stdio- - | | |-error_tables--- - | |-krb5-------|-free----------- - | | - | |-keytab---------|-file-- - | |-krb------------ - | |-os------------- - | |-posix---------- - | |-rcache--------- - |-prototype---- - |-slave-------- - | - | |-create----- - |-tests--------|-hammer----- - | |-verify----- - | - | |-et--------- - |-util---------|-makedepend- - |-ss--------- - |-unifdef---- diff --git a/doc/api/Makefile b/doc/api/Makefile deleted file mode 100644 index a826b6a7d..000000000 --- a/doc/api/Makefile +++ /dev/null @@ -1,29 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -STYLES=changebar.sty fixunder.sty functions.sty -LIBTEX= library.tex intro.tex tables.tex errors.tex krb5.tex ccache.tex \ - rcache.tex keytab.tex libos.tex library.ind - -DESTEX= libdes.tex - -all: library.ps libdes.ps - - -libdes.dvi: $(DESTEX) $(STYLES) - -library.ps: library.dvi - -# hard to capture two-pass semantics in Makefiles... -# library.ind: library.dvi -library.ind: library.idx - index library.idx - -library.dvi: $(LIBTEX) $(STYLES) - -.tex.dvi: - latex $* - - -.dvi.ps: - dvips $*.dvi -o - diff --git a/doc/api/ccache.tex b/doc/api/ccache.tex deleted file mode 100644 index e85a77444..000000000 --- a/doc/api/ccache.tex +++ /dev/null @@ -1,206 +0,0 @@ -The credentials cache functions (some of which are macros which call to -specific types of credentials caches) deal with storing credentials -(tickets, session keys, and other identifying information) in a -semi-permanent store for later use by different programs. - -\begin{funcdecl}{krb5_cc_resolve}{krb5_error_code}{\funcin} -\funcarg{char *}{string_name} -\funcout -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a ccache identifier which corresponds to -the name in \funcparam{string_name}. - -Requires that \funcparam{string_name} be of the form ``type:residual'' and -``type'' is a type known to the library. - -\begin{funcdecl}{krb5_cc_generate_new}{krb5_error_code}{\funcin} -\funcarg{krb5_cc_ops *}{ops} -\funcout -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - - -Fills in \funcparam{id} with a unique ccache identifier of a type defined by -\funcparam{ops}. The cache is left unopened. - -\begin{funcdecl}{krb5_cc_register}{krb5_error_code}{\funcin} -\funcarg{krb5_cc_ops *}{ops} -\funcarg{krb5_boolean}{override} -\end{funcdecl} - -Adds a new cache type identified and implemented by \funcparam{ops} to -the set recognized by \funcname{krb5_cc_resolve}. -If \funcparam{override} is FALSE, a ticket cache type named -\funcparam{ops{\ptsto}prefix} must not be known. - -\begin{funcdecl}{krb5_cc_get_name}{char *}{\funcin} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Returns the name of the ccache denoted by \funcparam{id}. - -\begin{funcdecl}{krb5_cc_default_name}{char *}{\funcvoid} -\end{funcdecl} - -Returns the name of the default credentials cache; this may be equivalent to -\funcnamenoparens{getenv}({\tt "KRB5CCACHE"}) with an appropriate fallback. - -\begin{funcdecl}{krb5_cc_default}{krb5_error_code}{\funcout} -\funcarg{krb5_ccache *}{ccache} -\end{funcdecl} - -Equivalent to -\funcnamenoparens{krb5_cc_resolve}(\funcname{krb5_cc_default_name}, -\funcparam{ccache}). - -\begin{funcdecl}{krb5_cc_initialize}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\funcin -\funcarg{krb5_principal}{primary_principal} -\end{funcdecl} - -Creates/refreshes a credentials cache identified by \funcparam{id} with -primary principal set to \funcparam{primary_principal}. -If the credentials cache already exists, its contents are destroyed. - -Errors: permission errors, system errors. - -Modifies: cache identified by \funcparam{id}. - -\begin{funcdecl}{krb5_cc_destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Destroys the credentials cache identified by \funcparam{id}, invalidates -\funcparam{id}, and releases any other resources acquired during use of -the credentials cache. Requires that \funcparam{id} identifies a valid -credentials cache. After return, \funcparam{id} must not be used unless -it is first reinitialized using \funcname{krb5_cc_resolve} or -\funcname{krb5_cc_generate_new}. - -Errors: permission errors. - -\begin{funcdecl}{krb5_cc_close}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \funcparam{id}, invalidates -\funcparam{id}, and releases \funcparam{id} and any other resources -acquired during use of the credentials cache. Requires that -\funcparam{id} identifies a valid credentials cache. After return, -\funcparam{id} must not be used unless it is first reinitialized using -\funcname{krb5_cc_resolve} or \funcname{krb5_cc_generate_new}. - - -\begin{funcdecl}{krb5_cc_store_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Stores \funcparam{creds} in the cache \funcparam{id}, tagged with -\funcparam{creds{\ptsto}client}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: permission errors, storage failure errors. - -\begin{funcdecl}{krb5_cc_retrieve_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -If at least one match is found, one of the matching credentials is -returned in \funcparam{*creds}. The credentials should be freed using -\funcname{krb5_free_credentials}. - -Errors: error code if no matches found. - -\begin{funcdecl}{krb5_cc_get_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Retrieves the primary principal of the credentials cache (as -set by the \funcname{krb5_cc_initialize} request) -The primary principal is filled into \funcparam{*principal}; the caller -should release this memory by calling \funcname{krb5_free_principal} on -\funcparam{*principal} when finished. - -Requires that \funcparam{id} identifies a valid credentials cache. - -\begin{funcdecl}{krb5_cc_start_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Prepares to sequentially read every set of cached credentials. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_cc_next_cred}. - -\begin{funcdecl}{krb5_cc_next_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Fetches the next entry from \funcparam{id}, returning its values in -\funcparam{*creds}, and updates \funcparam{*cursor} for the next request. -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: error code if no more cache entries. - -\begin{funcdecl}{krb5_cc_end_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{*cursor}. -\funcparam{*cursor} must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_cc_start_seq_get} or a subsequent call to -\funcname{krb5_cc_next_cred}. - -Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{krb5_cc_remove_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by -\funcparam{which}. -Requires that \funcparam{id} identifies a valid credentials cache. - -Errors: returns error code if nothing matches; returns error code if -couldn't delete. - -\begin{funcdecl}{krb5_cc_set_flags}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{flags} -\end{funcdecl} - -Sets the flags on the cache \funcparam{id} to \funcparam{flags}. Useful -flags are defined in {\tt }. - - diff --git a/doc/api/changebar.sty b/doc/api/changebar.sty deleted file mode 100644 index 61b7383f9..000000000 --- a/doc/api/changebar.sty +++ /dev/null @@ -1,155 +0,0 @@ -% Change bar document-style option for LaTeX. -% -% Copyright (C) 1990 by David B. Johnson. - -% These macros draw a solid bar down the right margin of the output, -% covering a range of the input file that has been declared to be changed. -% -% The beginning and end of a change bar in the text are marked with -% \chgbarbegin and \chgbarend, respectively. For example, -% -% Here is some sample text \chgbarbegin that was -% changed\chgbarend{} and some that wasn't changed. -% -% The change bar is drawn continuously between the line of output -% containing the \chgbarbegin and the line of output containing the -% \chgbarend. These lines can end up on separate pages, and the -% division at page boundaries is handled automatically. - -% Two dimensions control the size and placement of the change bars: -% \chgbarwidth The width of a change bar -% \chgbarsep The distance between the text and the change bar - -% Warning: it does not appear to be possible to do this completely -% correctly, due to the time at which the verticle glue on a page is -% finally set, and the way that page breaks are decided. With -% \raggedbottom, this normally works fine. It hasn't been tested with -% \flushbottom, but will probably behave worse. In strange rare -% situations, a change bar might be drawn from the first line of a page -% up off the top of a page; this can usually be fixed by slightly moving -% the \chngbarend around, or by breaking a single change bar range -% into two ranges. - -\newdimen\chgbarwidth \newdimen\chgbarsep -\chgbarwidth 4pt -\chgbarsep .25in - -\def\chgbarbegin{\ifhmode\@chgbar{-2}\else\@chgbar{-3}\fi} -\def\chgbarend{\@chgbar{-4}\relax} - -\marginparpush 0pt - -% The remainder of this is hacked up based on the LaTeX 2.09 latex.tex. - -% copied from \marginpar -\def\@chgbar#1{\ifhmode \@bsphack\@floatpenalty -\@Mii\else - \@floatpenalty-\@Miii\fi\ifinner - \@parmoderr\@floatpenalty\z@ - \else\@next\@currbox\@freelist{\global - \count\@currbox#1}{\@floatpenalty\z@ \@fltovf - \def\@currbox{\@tempboxa}}\fi - \setbox\@tempboxa\vbox - \bgroup\end@float\@esphack} - -\newdimen\@chgbarbegin -\newif\if@inchgbar \@inchgbarfalse - -\def\@addmarginpar{% -\ifnum\count\@currbox = -2 % change bar begin from hmode - \global\@chgbarbegin\@pageht \global\advance\@chgbarbegin -\baselineskip - \global\@inchgbartrue - \@cons\@freelist\@currbox -\else -\ifnum\count\@currbox = -3 % change bar begin not from hmode - \global\@chgbarbegin\@pageht - \global\@inchgbartrue - \@cons\@freelist\@currbox -\else -\ifnum\count\@currbox = -4 % change bar end - \if@inchgbar\else\@latexbug\fi - \@tempdima\@pageht \advance\@tempdima -\@chgbarbegin - \nointerlineskip - \@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\chgbarsep - \else \hskip -\chgbarsep \fi -\hbox{\vbox to 0pt{\vss - \hrule \@height\@tempdima \@width\chgbarwidth \@depth\z@ -}} -\hss} - \nointerlineskip - \global\@inchgbarfalse - \@cons\@freelist\@currbox -\else - \@next\@marbox\@currlist{\@cons\@freelist\@marbox - \@cons\@freelist\@currbox}\@latexbug\@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \ifnum\@tempcnta <\z@ \global\setbox\@marbox\box\@currbox \fi - \@tempdima\@mparbottom \advance\@tempdima -\@pageht - \advance\@tempdima\ht\@marbox \ifdim\@tempdima >\z@ - \@warning{Marginpar on page \thepage\space moved}\else\@tempdima\z@ \fi - \global\@mparbottom\@pageht \global\advance\@mparbottom\@tempdima - \global\advance\@mparbottom\dp\@marbox - \global\advance\@mparbottom\marginparpush - \advance\@tempdima -\ht\@marbox - \global\ht\@marbox\z@ \global\dp\@marbox\z@ - \vskip -\@pagedp \vskip\@tempdima\nointerlineskip - \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\marginparsep - \else \hskip -\marginparsep \hskip -\marginparwidth \fi - \box\@marbox \hss} - \vskip -\@tempdima - \nointerlineskip - \hbox{\vrule \@height\z@ \@width\z@ \@depth\@pagedp} -\fi\fi\fi} - -\def\@makecol{\setbox\@outputbox\box\@cclv - \if@inchgbar - \@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \@tempdima\ht\@outputbox \advance\@tempdima -\@chgbarbegin - \advance\@tempdima -\baselineskip - \setbox\@outputbox - \vbox{\boxmaxdepth \maxdepth - \unvbox\@outputbox \nointerlineskip \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\chgbarsep - \else \hskip -\chgbarsep \fi - \hbox{\vbox to 0pt{\vss - \hrule \@height\@tempdima \@width\chgbarwidth \@depth\z@}}\hss}} - \global\@chgbarbegin 0pt -\fi - \ifvoid\footins\else\setbox\@outputbox - \vbox{\boxmaxdepth \maxdepth - \unvbox\@outputbox\vskip\skip\footins\footnoterule\unvbox\footins}\fi - \xdef\@freelist{\@freelist\@midlist}\gdef\@midlist{}\@combinefloats - \setbox\@outputbox\vbox to\@colht{\boxmaxdepth\maxdepth - \@texttop\dimen128=\dp\@outputbox\unvbox\@outputbox - \vskip-\dimen128\@textbottom} - \global\maxdepth\@maxdepth} - -\newenvironment{changebar}{\chgbarbegin}{\chgbarend} diff --git a/doc/api/errors.tex b/doc/api/errors.tex deleted file mode 100644 index 1aa393e5d..000000000 --- a/doc/api/errors.tex +++ /dev/null @@ -1,271 +0,0 @@ -\subsection{error_table krb5} - -% $Source$ -% $Author$ - -The Kerberos v5 library error code table follows. -Protocol error codes are ERROR_TABLE_BASE_krb5 + the protocol error -code number. Other error codes start at ERROR_TABLE_BASE_krb5 + 128. - -\begin{small} -\begin{tabular}{ll} -{\sc krb5kdc_err_none }& No error \\ -{\sc krb5kdc_err_name_exp }& Client's entry in database has expired \\ -{\sc krb5kdc_err_service_exp }& Server's entry in database has expired \\ -{\sc krb5kdc_err_bad_pvno }& Requested protocol version not supported \\ -{\sc krb5kdc_err_c_old_mast_kvno }& Client's key is encrypted in an old master key \\ -{\sc krb5kdc_err_s_old_mast_kvno }& Server's key is encrypted in an old master key \\ -{\sc krb5kdc_err_c_principal_unknown }& Client not found in Kerberos database \\ -{\sc krb5kdc_err_s_principal_unknown }& Server not found in Kerberos database \\ -{\sc krb5kdc_err_principal_not_unique }& Principal has multiple entries in Kerberos database \\ -{\sc krb5kdc_err_null_key }& Client or server has a null key \\ -{\sc krb5kdc_err_cannot_postdate }& Ticket is ineligible for postdating \\ -{\sc krb5kdc_err_never_valid }& Requested effective lifetime is negative or too short \\ -{\sc krb5kdc_err_policy }& KDC policy rejects request \\ -{\sc krb5kdc_err_badoption }& KDC can't fulfill requested option \\ -{\sc krb5kdc_err_etype_nosupp }& KDC has no support for encryption type \\ -{\sc krb5kdc_err_sumtype_nosupp }& KDC has no support for checksum type \\ -{\sc krb5kdc_err_padata_type_nosupp }& KDC has no support for padata type \\ -{\sc krb5kdc_err_trtype_nosupp }& KDC has no support for transited type \\ -{\sc krb5kdc_err_client_revoked }& Clients credentials have been revoked \\ -{\sc krb5kdc_err_service_revoked }& Credentials for server have been revoked \\ -{\sc krb5kdc_err_tgt_revoked }& TGT has been revoked \\ -{\sc krb5kdc_err_client_notyet }& Client not yet valid - try again later \\ -{\sc krb5kdc_err_service_notyet }& Server not yet valid - try again later \\ -{\sc krb5kdc_err_key_exp }& Password has expired \\ -{\sc krb5kdc_preauth_failed }& Preauthentication failed \\ - - & \multicolumn{1}{c}{error codes 25-30 are currently placeholders} \\ -\end{tabular} - -\begin{tabular}{ll} -{\sc krb5krb_ap_err_bad_integrity }& Decrypt integrity check failed \\ -{\sc krb5krb_ap_err_tkt_expired }& Ticket expired \\ -{\sc krb5krb_ap_err_tkt_nyv }& Ticket not yet valid \\ -{\sc krb5krb_ap_err_repeat }& Request is a replay \\ -{\sc krb5krb_ap_err_not_us }& The ticket isn't for us \\ -{\sc krb5krb_ap_err_badmatch }& Ticket/authenticator don't match \\ -{\sc krb5krb_ap_err_skew }& Clock skew too great \\ -{\sc krb5krb_ap_err_badaddr }& Incorrect net address \\ -{\sc krb5krb_ap_err_badversion }& Protocol version mismatch \\ -{\sc krb5krb_ap_err_msg_type }& Invalid message type \\ -{\sc krb5krb_ap_err_modified }& Message stream modified \\ -{\sc krb5krb_ap_err_badorder }& Message out of order \\ -{\sc krb5placehold_43 }& KRB5 error code 43 \\ -{\sc krb5krb_ap_err_badkeyver }& Key version is not available \\ -{\sc krb5krb_ap_err_nokey }& Service key not available \\ -{\sc krb5krb_ap_err_mut_fail }& Mutual authentication failed \\ -{\sc krb5krb_ap_err_baddirection }& Incorrect message direction \\ -{\sc krb5krb_ap_err_method }& Alternative authentication method required \\ -{\sc krb5krb_ap_err_badseq }& Incorrect sequence number in message \\ -{\sc krb5krb_ap_err_inapp_cksum }& Inappropriate type of checksum in message \\ - - & \multicolumn{1}{c}{error codes 51-59 are currently placeholders} \\ - -{\sc krb5krb_err_generic }& Generic error (see e-text) \\ -{\sc krb5krb_err_field_toolong }& Field is too long for this implementation \\ - -& \multicolumn{1}{c}{error codes 62-127 are currently placeholders} \\ -\end{tabular} - -\begin{tabular}{ll} -{\sc krb5_libos_badlockflag }& Invalid flag for file lock mode \\ -{\sc krb5_libos_cantreadpwd }& Cannot read password \\ -{\sc krb5_libos_badpwdmatch }& Password mismatch \\ -{\sc krb5_libos_pwdintr }& Password read interrupted \\ -{\sc krb5_parse_illchar }& Illegal character in component name \\ -{\sc krb5_parse_malformed }& Malformed representation of principal \\ -{\sc krb5_config_cantopen }& Can't open/find configuration file \\ -{\sc krb5_config_badformat }& Improper format of configuration file \\ -{\sc krb5_config_notenufspace }& Insufficient space to return complete information \\ -{\sc krb5_badmsgtype }& Invalid message type specified for encoding \\ -{\sc krb5_cc_badname }& Credential cache name malformed \\ -{\sc krb5_cc_unknown_type }& Unknown credential cache type \\ -{\sc krb5_cc_notfound }& Matching credential not found \\ -{\sc krb5_cc_end }& End of credential cache reached \\ -{\sc krb5_no_tkt_supplied }& Request did not supply a ticket \\ -{\sc krb5krb_ap_wrong_princ }& Wrong principal in request \\ -{\sc krb5krb_ap_err_tkt_invalid }& Ticket has invalid flag set \\ -{\sc krb5_princ_nomatch }& Requested principal and ticket don't match \\ -{\sc krb5_kdcrep_modified }& KDC reply did not match expectations \\ -{\sc krb5_prog_etype_nosupp }& Program lacks support for encryption type \\ -{\sc krb5_prog_keytype_nosupp }& Program lacks support for key type \\ -{\sc krb5_wrong_etype }& Requested encryption type not used in message \\ -{\sc krb5_prog_sumtype_nosupp }& Program lacks support for checksum type \\ -{\sc krb5_realm_unknown }& Cannot find KDC for requested realm \\ -{\sc krb5_kdc_unreach }& Cannot contact any KDC for requested realm \\ -{\sc krb5_no_localname }& No local name found for principal name \\ - -%\multicolumn{1}{c}{some of these should be combined/supplanted by system codes} \\ -\end{tabular} - -\begin{tabular}{ll} -{\sc krb5_rc_type_exists }& Replay cache type is already registered \\ -{\sc krb5_rc_malloc }& No more memory to allocate (in replay cache code) \\ -{\sc krb5_rc_type_notfound }& Replay cache type is unknown \\ -{\sc krb5_rc_unknown }& Generic unknown RC error \\ -{\sc krb5_rc_replay }& Message is a replay \\ -{\sc krb5_rc_io }& Replay I/O operation failed XXX \\ -{\sc krb5_rc_noio }& Replay cache type does not support non-volatile storage \\ -{\sc krb5_rc_parse }& Replay cache name parse/format error \\ -{\sc krb5_rc_io_eof }& End-of-file on replay cache I/O \\ -{\sc krb5_rc_io_malloc }& No more memory to allocate (in replay cache I/O code)\\ -{\sc krb5_rc_io_perm }& Permission denied in replay cache code \\ -{\sc krb5_rc_io_io }& I/O error in replay cache i/o code \\ -{\sc krb5_rc_io_unknown }& Generic unknown RC/IO error \\ -{\sc krb5_rc_io_space }& Insufficient system space to store replay information \\ -{\sc krb5_trans_cantopen }& Can't open/find realm translation file \\ -{\sc krb5_trans_badformat }& Improper format of realm translation file \\ -{\sc krb5_lname_cantopen }& Can't open/find lname translation database \\ -{\sc krb5_lname_notrans }& No translation available for requested principal \\ -{\sc krb5_lname_badformat }& Improper format of translation database entry \\ -{\sc krb5_crypto_internal }& Cryptosystem internal error \\ -{\sc krb5_kt_badname }& Key table name malformed \\ -{\sc krb5_kt_unknown_type }& Unknown Key table type \\ -{\sc krb5_kt_notfound }& Key table entry not found \\ -{\sc krb5_kt_end }& End of key table reached \\ -{\sc krb5_kt_nowrite }& Cannot write to specified key table \\ -{\sc krb5_kt_ioerr }& Error writing to key table \\ -{\sc krb5_no_tkt_in_rlm }& Cannot find ticket for requested realm \\ -{\sc krb5des_bad_keypar }& DES key has bad parity \\ -{\sc krb5des_weak_key }& DES key is a weak key \\ -{\sc krb5_bad_keytype }& Keytype is incompatible with encryption type \\ -{\sc krb5_bad_keysize }& Key size is incompatible with encryption type \\ -{\sc krb5_bad_msize }& Message size is incompatible with encryption type \\ -{\sc krb5_cc_type_exists }& Credentials cache type is already registered. \\ -{\sc krb5_kt_type_exists }& Key table type is already registered. \\ -{\sc krb5_cc_io }& Credentials cache I/O operation failed XXX \\ -{\sc krb5_fcc_perm }& Credentials cache file permissions incorrect \\ -{\sc krb5_fcc_nofile }& No credentials cache file found \\ -{\sc krb5_fcc_internal }& Internal file credentials cache error \\ -{\sc krb5_cc_nomem }& No more memory to allocate (in credentials cache code) \\ - -\end{tabular} - -\begin{tabular}{ll} -& \multicolumn{1}{c}{errors for dual TGT library calls} \\ - -{\sc krb5_invalid_flags }& Invalid KDC option combination (library internal error) \\ -{\sc krb5_no_2nd_tkt }& Request missing second ticket \\ -{\sc krb5_nocreds_supplied }& No credentials supplied to library routine \\ - -\end{tabular} - -\begin{tabular}{ll} -& \multicolumn{1}{c}{errors for sendauth and recvauth} \\ - -{\sc krb5_sendauth_badauthvers }& Bad sendauth version was sent \\ -{\sc krb5_sendauth_badapplvers }& Bad application version was sent (via sendauth) \\ -{\sc krb5_sendauth_badresponse }& Bad response (during sendauth exchange) \\ -{\sc krb5_sendauth_rejected }& Server rejected authentication (during sendauth exchange) \\ -{\sc krb5_sendauth_mutual_failed }& Mutual authentication failed (during sendauth exchange) \\ - -\end{tabular} - -\begin{tabular}{ll} -&\multicolumn{1}{c}{errors for preauthentication} \\ - -{\sc krb5_preauth_bad_type }& Unsupported preauthentication type \\ -{\sc krb5_preauth_no_key }& Required preauthentication key not supplied \\ -{\sc krb5_preauth_failed }& Generic preauthentication failure \\ - -\end{tabular} - -\begin{tabular}{ll} -&\multicolumn{1}{c}{version number errors} \\ - -{\sc krb5_rcache_badvno }& Unsupported replay cache format version number \\ -{\sc krb5_ccache_badvno }& Unsupported credentials cache format version number \\ -{\sc krb5_keytab_badvno }& Unsupported key table format version number \\ - -\end{tabular} - -\begin{tabular}{ll} -&\multicolumn{1}{c}{other errors} \\ - -{\sc krb5_prog_atype_nosupp }& Program lacks support for address type \\ -{\sc krb5_rc_required }& Message replay detection requires rcache parameter \\ -{\sc krb5_err_bad_hostname }& Hostname cannot be canonicalized \\ -{\sc krb5_err_host_realm_unknown }& Cannot determine realm for host \\ -{\sc krb5_sname_unsupp_nametype }& Conversion to service principal undefined for name type \\ -\end{tabular} -\end{small} - -\subsection{error_table kdb5} - -% $Source$ -% $Author$ - -The Kerberos v5 database library error code table - -\begin{small} -\begin{tabular}{ll} -&\multicolumn{1}{c}{From the server side routines} \\ -{\sc krb5_kdb_inuse }& Entry already exists in database\\ -{\sc krb5_kdb_uk_serror }& Database store error\\ -{\sc krb5_kdb_uk_rerror }& Database read error\\ -{\sc krb5_kdb_unauth }& Insufficient access to perform requested operation\\ -{\sc krb5_kdb_noentry }& No such entry in the database\\ -{\sc krb5_kdb_ill_wildcard }& Illegal use of wildcard\\ -{\sc krb5_kdb_db_inuse }& Database is locked or in use--try again later\\ -{\sc krb5_kdb_db_changed }& Database was modified during read\\ -{\sc krb5_kdb_truncated_record }& Database record is incomplete or corrupted\\ -{\sc krb5_kdb_recursivelock }& Attempt to lock database twice\\ -{\sc krb5_kdb_notlocked }& Attempt to unlock database when not locked\\ -{\sc krb5_kdb_badlockmode }& Invalid kdb lock mode\\ -{\sc krb5_kdb_dbnotinited }& Database has not been initialized\\ -{\sc krb5_kdb_dbinited }& Database has already been initialized\\ -{\sc krb5_kdb_illdirection }& Bad direction for converting keys\\ -{\sc krb5_kdb_nomasterkey }& Cannot find master key record in database\\ -{\sc krb5_kdb_badmasterkey }& Master key does not match database\\ -{\sc krb5_kdb_invalidkeysize }& Key size in database is invalid\\ -{\sc krb5_kdb_cantread_stored }& Cannot find/read stored master key\\ -{\sc krb5_kdb_badstored_mkey }& Stored master key is corrupted\\ -{\sc krb5_kdb_cantlock_db }& Insufficient access to lock database \\ -{\sc krb5_kdb_db_corrupt }& Database format error\\ -{\sc krb5_kdb_bad_version }& Unsupported version in database entry \\ -\end{tabular} -\end{small} - -\subsection{error_table isod} - -% $Source$ -% $Author$ - - The Kerberos v5/ISODE 5.0 error table mappings --- see $<$isode/psap.h$>$ - -\begin{small} -\begin{tabular}{ll} -{\sc isode_50_ps_err_none}& isode (ps): No error \\ -{\sc isode_50_ps_err_overid}& isode (ps):Overflow in ID \\ -{\sc isode_50_ps_err_overlen}& isode (ps):Overflow in length \\ -{\sc isode_50_ps_err_nmem}& isode (ps):Out of memory \\ -{\sc isode_50_ps_err_eof}& isode (ps):End of file \\ -{\sc isode_50_ps_err_eofid}& isode (ps):End of file reading extended ID \\ -{\sc isode_50_ps_err_eoflen}& isode (ps):End of file reading extended length \\ -{\sc isode_50_ps_err_len}& isode (ps):Length mismatch \\ -{\sc isode_50_ps_err_trnc}& isode (ps):Truncated \\ -{\sc isode_50_ps_err_indf}& isode (ps):Indefinite length in primitive form \\ -{\sc isode_50_ps_err_io}& isode (ps):I/O error \\ -{\sc isode_50_ps_err_extra}& isode (ps): Extraneous octets \\ -{\sc isode_50_ps_err_xxx}& isode (ps):XXX \\ -{\sc isode_50_pe_err_none}& isode(pe):No error \\ -{\sc isode_50_pe_err_over}& isode(pe):Overflow \\ -{\sc isode_50_pe_err_nmem}& isode(pe):Out of memory \\ -{\sc isode_50_pe_err_bit}& isode(pe):No such bit \\ -{\sc isode_50_pe_err_utct}& isode(pe):Malformed universal timestring \\ -{\sc isode_50_pe_err_gent}& isode(pe):Malformed generalized timestring \\ -{\sc isode_50_pe_err_mber}& isode(pe):No such member \\ -{\sc isode_50_pe_err_prim}& isode(pe):Not a primitive form \\ -{\sc isode_50_pe_err_cons}& isode(pe):Not a constructor form \\ -{\sc isode_50_pe_err_type}& isode(pe):Class/ID mismatch in constructor \\ -{\sc isode_50_pe_err_oid}& isode(pe):Malformed object identifier \\ -{\sc isode_50_pe_err_bits}& isode(pe):Malformed bitstring \\ -{\sc isode_50_pe_err_nosupp}& isode(pe):Type not supported \\ -{\sc isode_50_pe_err_signed}& isode(pe):Signed integer not expected \\ -{\sc isode_50_local_err_baddecode}& isode: ASN.1 decode failed \\ -{\sc isode_50_local_err_badmsgtype}& isode: wrong message type after decoding \\ -{\sc isode_50_local_err_badcombo}& isode: unacceptable combination of options \\ -{\sc isode_local_err_missing_part}& isode: missing element during translation \\ -\end{tabular} -\end{small} diff --git a/doc/api/fixunder.sty b/doc/api/fixunder.sty deleted file mode 100644 index b7ae58dbf..000000000 --- a/doc/api/fixunder.sty +++ /dev/null @@ -1,48 +0,0 @@ -% fixunder.sty, 31 May 1990, John T. Kohl -% -% The contents of this file are in the public domain. -% -% -% play games with _ to make it active and to provide a reasonable _ -% character (from \tt in most cases), and a discretionary word-break point. - -% -% Some \makeunder... macros for convenience in setting catcodes. -% -\def\makeunderactive{\catcode`\_=\active\relax} -\def\makeunderother{\catcode`\_=12\relax} -\def\makeunderletter{\catcode`\_=11\relax} -\def\makeundernormal{\catcode`\_=8\relax} -\makeunderother -\def\cctwlunder{_} - -% -% The hair here is to allow things like \index to work reasonably with -% the new definition of underscore when the argument to index is part of -% a macro replacement and as such gets tokenized before \index is -% evaluated. -% [in the normal case at top-level, \index{foo_bar} works since \index -% does some hair to make _ into a reasonable character code, and \index -% does NOT use a macro expansion. If you have something like -% \def\foo#1#2{\index{#1} bar #2} -% then \foo{baz_quux}{frobnitz} will result in baz_quux getting -% tokenized BEFORE \foo is expanded, so that the catcode hair in \index -% is to no avail.] -% -% \underrealfalse declares that you want to replace with the \tt _; -% \underrealtrue declares that you want to replace with \char95 (ASCII _). -% -% for things like \index which write things out to files, set -% \underrealfalse before evaluating the \index macro, and what actually -% gets written to the file is an _, rather than something like -% {\leavemode \kern... } (the typical definition of \_). -% -% the above example would then be -% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2} -% - -\newif\ifunderreal -\underrealfalse -\makeunderactive -\def_{\ifunderreal\cctwlunder\else\leavevmode {\tt \cctwlunder}\discretionary{}{}{}\fi} -\let\_=_ diff --git a/doc/api/functions.sty b/doc/api/functions.sty deleted file mode 100644 index a3165f811..000000000 --- a/doc/api/functions.sty +++ /dev/null @@ -1,70 +0,0 @@ -% -% definitions related to function declarations/displays -% -\ifx\undefined\@psfonts -\def\argfont{\tt} -\else -\font\argfont = pcrb -\hyphenchar\argfont = -1 -\fi -\let\funcfont=\bf -\newcount\argc@ount -%\setlength{\marginparsep}{0.05in} -%\setlength{\marginparwidth}{1.45in} -% -% This function fixes up the function name to be displayed in the -% margin so that the krb5_, if any, is stripped. -% -% Note: this is a hack; what's really happening is that name beginning with -% krb5 will have its first five characters stripped from it. -% This means that 'Krb5abc' will get rewritten to be 'bc'. -% Unfortunately, we can't do better because of the underscore -% hacks that are going on elsewhere. -% -% WARNING: This is ugly; don't look at it too soon after lunch! -% [tytso:19900920.2231EDT] -\newif\if@krbfunc -\def\endkrb{} -\def\fix@parname#1{\expandafter\parse@krb#1\endkrb% -\endkrb\endkrb\endkrb\endkrb}% In case the argument is less -% than five letters, we don't want to -% lose on the argument parsing. -\def\parse@krb#1#2#3#4#5#6\endkrb{\@krbfuncfalse% -\if#1k\if#2r\if#3b\if#45\@krbfunctrue\fi\fi\fi\fi% -\if@krbfunc#6\else#1#2#3#4#5#6\fi} -% -% funcdecl is used as \begin{funcdecl}{funcname}{return type}{firstline} -% -% see fixunder.sty for comments on why the \underrealtrue & \underrealfalse -% stuff is here. -\newenvironment{funcdecl}[3]{\underrealtrue\index{#1}\underrealfalse% -\medbreak -\gdef\funcn@me{#1} -\argc@ount=0\noindent% -%the \mbox{} is to prevent the line/paragraph breaking from eating the -%fill space. -\marginpar[{{\sloppy \hfil\fix@parname{\funcn@me}\hfill\mbox{}}}]% -{{\sloppy \hfill\fix@parname{\funcn@me}\hfil\mbox{}}}% -\vbox\bgroup\begin{minipage}[t]{\textwidth}\begin{tabbing} -#2 \\ -{\bf #1}(\= \+ #3% -}{) -\end{tabbing}\vfil\end{minipage}\egroup\par\nopagebreak -} -\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi} -\newcommand{\funcvoid}{\argc@ount=0} -\newcommand{\funcin}{\docomm@\argc@ount=0{\sl /* IN */}\\} -\newcommand{\funcinout}{\docomm@\argc@ount=0{\sl /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/api/intro.tex b/doc/api/intro.tex deleted file mode 100644 index b0c8d731d..000000000 --- a/doc/api/intro.tex +++ /dev/null @@ -1,298 +0,0 @@ - This document describes the routines that make up the Kerberos -V5 application programming interface. It is geared towards -programmers who already have a basic familiarity with Kerberos and are -in the process of including Kerberos authentication as part of -applications being developed. - - The function descriptions included are up to date, even if the -description of the functions may be hard to understand for the novice -Kerberos programmer. - -\subsection{Acknoledgments} - - -The Kerberos model is based in part on Needham and Schroeder's trusted -third-party authentication protocol and on modifications suggested by -Denning and Sacco. The original design and implementation of Kerberos -Versions 1 through 4 was the work of Steve Miller of Digital Equipment -Corporation and Clifford Neuman (now at the Information Sciences -Institute of the University of Southern California), along with Jerome -Saltzer, Technical Director of Project Athena, and Jeffrey Schiller, -MIT Campus Network Manager. Many other members of Project Athena have -also contributed to the work on Kerberos. Version 4 is publicly -available, and has seen wide use across the Internet. - -Version 5 (described in this document) has evolved from Version 4 based -on new requirements and desires for features not available in Version 4. - -%nlg- a bunch more probably needs to be added here to credit all -%those that have contributed to V5 -nlg - -\subsection{Kerberos Basics} - -Kerberos performs authentication as a trusted third-party -authentication service by using conventional (shared secret -key\footnote{ {\em Secret} and {\em private} are often used -interchangeably in the literature. In our usage, it takes two (or -more) to share a secret, thus a shared DES key is a {\em secret} key. -Something is only private when no one but its owner knows it. Thus, -in public key cryptosystems, one has a public and a {\em private} key. -}) cryptography. Kerberos provides a means of verifying the -identities of principals, without relying on authentication by the -host operating system, without basing trust on host addresses, without -requiring physical security of all the hosts on the network, and under -the assumption that packets traveling along the network can be read, -modified, and inserted at will. - -When integrating Kerberos into an application it is important to -review how and when Kerberos functions are used to ensure that the -application's design does not compromise the authentication. For -instance, an application which uses Kerberos' functions only upon the -{\em initiation} of a stream-based network connection, and assumes the -absence of any active attackers who might be able to ``hijack'' the -stream connection. - -%{\Huge nlg- It would be nice to include more examples here of common -%mistakes one can make in deisgning kerberized systems -nlg} - -The Kerberos protocol code libraries, whose API is described in this -document, can be used to provide encryption to any application. In -order to add authentication to its transactions, a typical network -application adds one or two calls to the Kerberos library, which -results in the transmission of the necessary messages to achieve -authentication. - -The two methods for obtaining credentials, the inital ticket exchange -and the ticket granting ticket exchange, use slightly different -protocols and require different API routines. The basic difference an -API programmer will see is that the initial request does not require a -ticket granting ticket (TGT) but does require the client's secret key -because the reply is sent back encrypted in the client's secret key. -Usually this request is for a TGT and TGT based exchanges are used -from then on. In a TGT exchange the TGT is sent as part of the -request for tickets and the reply is encrypted in the session key from -the TGT. For example, once a user's password is used to obtain a TGT, -it is not required for subsequent TGT exchanges. - -The reply consists of a ticket and a session key, encrypted either in -the user's secret key (i.e., pasword), or the TGT session key. The -combination of a ticket and a session key is known as a set of {\em -credentials}.\footnote{In Kerberos V4, the ``ticket file'' was a bit of -a misnomer, since it contained both tickets and their associated session -keys. In Kerberos V5, the ``ticket file'' has been renamed to be the -{\em credentials cache}.} An application client can use these -credentials to authenticate to the application server by sending the -ticket and an {\em authenticator} to the server. The authenticator is -encrypted in the session key of the ticket, and contains the name of the -client, the name of the server, the time the authenticator was created. - -In order to verify the authentication, the application server decrypts -the ticket using its service key, which is only known by the application -server and the Kerberos server. Inside the ticket, the Kerberos server -had placed the name of the client, the name of the server, a DES key -assocuated with this ticket, and some additional information. The -application server then uses the ticket session key to decrypt the -authenticator, and verifies that the information in the authenticator -matches the information in the ticket, and that the timestamp in the -authenticator is recent (to prvent reply attacks). Since the session -key was generated randomly by the Kerberos server, and delivered only -encrypted in the service key, and in a key known only by the user, the -application server can be confident that user is really who he or she -claims to be, by virtue of the fact that the user was able to encrypt -the authenticator in the correct key. - -To provide detection of both replay -attacks and message stream modification attacks, the integrity of all -the messages exchanged between principals can also be -guaranteed\footnote{Using -\funcname{krb5_mk_safe} and \funcname{krb5_rd_safe} to create and -verify KRB5_SAFE messages} by generating and transmitting a -collision-proof checksum \footnote{aka cryptographic checksum, -elsewhere this is called a hash or digest function} of the client's -message, keyed with the session key. Privacy and integrity of the -messages exchanged between principals can be secured\footnote{Using -\funcname{krb5_mk_priv} and \funcname{krb5_rd_priv} to create and -verify KRB5_PRIV messages} by encrypting the data to be passed using -the session key. - -\subsubsection{The purpose of Realms} - -The Kerberos protocol is designed to operate across organizational -boundaries. Each organization wishing to run a Kerberos -server establishes its own {\em realm}. The name of the realm in which a -client is registered is part of the client's name, and can be used by the -end-service to decide whether to honor a request. - -By establishing {\em inter-realm} keys, the administrators of two -realms can allow a client authenticated in the local realm to use its -credentials remotely. The exchange of inter-realm keys (a separate -key may be used for each direction) registers the ticket-granting -service of each realm as a principal in the other realm. A client is -then able to obtain a ticket-granting ticket for the remote realm's -ticket-granting service from its local realm. When that -ticket-granting ticket is used, the remote ticket-granting service -uses the inter-realm key (which usually differs from its own normal -TGS key) to decrypt the ticket-granting ticket, and is thus certain -that it was issued by the client's own TGS. Tickets issued by the -remote ticket-granting service will indicate to the end-service that -the client was authenticated from another realm. - - -This method can be repeated to authenticate throughout an organization -accross multiple relms. To build a valid authentication -path\footnote{An {\em authentication path} is the sequence of -intermediate realms that are transited in communicating from one realm -to another.} to a distant relm, the local realm must share an -inter-realm key with an intermediate realm which -communicates\footnote{A realm is said to {\em communicate} with -another realm if the two realms share an inter-realm key} with either -the distant remote realm or yet another intermediate relm. - -Realms are typically organized hierarchically. Each realm shares a -key with its parent and a different key with each child. If an -inter-realm key is not directly shared by two realms, the hierarchical -organization allows an authentication path to be easily constructed. -If a hierarchical organization is not used, it may be necessary to -consult some database in order to construct an authentication path -between realms. - -Although realms are typically hierarchical, intermediate realms may be -bypassed to achieve cross-realm authentication through alternate -authentication paths\footnote{These might be established to make communication -between two realms more efficient}. It is important for the -end-service to know which realms were transited when deciding how much -faith to place in the authentication process. To facilitate this -decision, a field in each ticket contains the names of the realms that -were involved in authenticating the client. - -\subsubsection{Fundamental assumptions about the environment} - -Kerberos has certain limitations that should be kept in mind when -designing security measures: - -\begin{itemize} -\item -Kerberos does not address ``Denial of service'' attacks. There are -places in these protocols where an intruder can prevent an application -from participating in the proper authentication steps. Detection and -solution of such attacks (some of which can appear to be not-uncommon -``normal'' failure modes for the system) is usually best left to -the human administrators and users. - -\item -Principals must keep their secret keys secret. If an intruder somehow -steals a principal's key, it will be able to masquerade as that -principal or impersonate any server to the legitimate principal. - -\item -``Password guessing'' attacks are not solved by Kerberos. If a user -chooses a poor password, it is possible for an attacker to -successfully mount an offline dictionary attack by repeatedly -attempting to decrypt, with successive entries from a dictionary, -messages obtained which are encrypted under a key derived from the -user's password. - -\end{itemize} - -\subsection{Glossary of terms} - -Below is a list of terms used throughout this document. - -\begin{description} -\item [Authentication] -Verifying the claimed identity of a principal. - -\item [Authentication header] -A record containing a Ticket and an Authenticator to be presented to a -server as part of the authentication process. - -\item [Authentication path] -A sequence of intermediate realms transited in the authentication -process when communicating from one realm to another. - -\item [Authenticator] -A record containing information that can be shown to -have been recently generated using the session key known only by the -client and server. - -\item [Authorization] -The process of determining whether a client may use a -service, which objects the client is allowed to access, and the -type of access allowed for each. - -\item [Ciphertext] -The output of an encryption function. Encryption transforms plaintext -into ciphertext. - -\item [Client] -A process that makes use of a network service on behalf of a -user. Note that in some cases a {\em Server} may itself be a client of -some other server (e.g. a print server may be a client of a file server). - -\item [Credentials] -A ticket plus the secret session key necessary to -successfully use that ticket in an authentication exchange. - -\item [KDC] -Key Distribution Center, a network service that supplies -tickets and temporary session keys; or an -instance of that service or the host on which it runs. -The KDC services both initial ticket and ticket-granting ticket -requests. -The initial ticket portion is sometimes referred to as the -Authentication Server (or service). -The ticket-granting ticket portion is sometimes referred to as the -ticket-granting server (or service). - -\item [Kerberos] -Aside from the 3-headed dog guarding Hades, the name given -to Project Athena's authentication service, the protocol used by that -service, or the code used to implement the authentication service. - -\item [Plaintext] -The input to an encryption function or the output of a decryption -function. Decryption transforms ciphertext into plaintext. - -\item [Principal] -A uniquely named client or server instance that participates in -a network communication. - -\item [Principal identifier] -The name used to uniquely identify each different -principal. - -\item [Seal] -To encipher a record containing several fields in such a way -that the fields cannot be individually replaced without either -knowledge of the encryption key or leaving evidence of tampering. - -\item [Secret key] -An encryption key shared by a principal and the KDC, -distributed outside the bounds of the system, with a long lifetime. -In the case of a human user's principal, the secret key is derived from a -password. - -\item [Server] -A particular Principal which provides a resource to network clients. - -\item [Service] -A resource provided to network clients; often provided by more than one -server (for example, remote file service). - -\item [Session key] -A temporary encryption key used between two principals, -with a lifetime limited to the duration of a single login -{\em session}. - -\item [Sub-session key] -A temporary encryption key used between two -principals, selected and exchanged by the principals using the session -key, and with a lifetime limited to the duration of a single -association. - -\item [Ticket] -A record that helps a client authenticate itself to a server; it contains -the client's identity, a session key, a timestamp, and other -information, all sealed using the server's secret key. It only serves to -authenticate a client when presented along with a fresh Authenticator. -\end{description} diff --git a/doc/api/keytab.tex b/doc/api/keytab.tex deleted file mode 100644 index 70ed1c032..000000000 --- a/doc/api/keytab.tex +++ /dev/null @@ -1,195 +0,0 @@ -The key table functions deal with storing and retrieving service keys -for use by unattended services which participate in authentication exchanges. - -Keytab routines are all be atomic. Every routine that acquires -a non-sharable resource releases it before it returns. - -All keytab types support multiple concurrent sequential scans. - -The order of values returned from \funcname{krb5_kt_next_entry} is -unspecified. - -Although the ``right thing'' should happen if the program aborts -abnormally, a close routine, \funcname{krb5_kt_free_entry}, is provided -for freeing resources, etc. People should use the close routine when -they are finished. - -\begin{funcdecl}{krb5_kt_register}{krb5_error_code}{\funcin} -\funcarg{krb5_kt_ops *}{ops} -\end{funcdecl} - - -Adds a new ticket cache type to the set recognized by -\funcname{krb5_kt_resolve}. -Requires that a keytab type named \funcparam{ops{\ptsto}prefix} is not -yet known. - -An error is returned if \funcparam{ops{\ptsto}prefix} is already known. - -\begin{funcdecl}{krb5_kt_resolve}{krb5_error_code}{\funcin} -\funcarg{const char *}{string_name} -\funcout -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{*id} with a handle identifying the keytab with name -``string_name''. The keytab is not opened. -Requires that \funcparam{string_name} be of the form ``type:residual'' and -``type'' is a type known to the library. - -Errors: badly formatted name. - -\begin{funcdecl}{krb5_kt_default_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\funcarg{int}{namesize} -\end{funcdecl} - -\funcparam{name} is filled in with the first \funcparam{namesize} bytes of -the name of the default keytab. -If the name is shorter than \funcparam{namesize}, then the remainder of -\funcparam{name} will be zeroed. - - -\begin{funcdecl}{krb5_kt_default}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{id} with a handle identifying the default keytab. - -\begin{funcdecl}{krb5_kt_read_service_key}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keyblock **}{key} -\end{funcdecl} - -This function is suitable for use as a parameter to -\funcname{krb5_rd_req}. - -If \funcname{keyprocarg} is not NULL, it is taken to be a -\datatype{char *} denoting the name of a keytab. Otherwise, the default -keytab will be used. -The keytab is opened and searched for the entry identified by -\funcparam{principal} and \funcparam{vno}, returning the resulting key -in \funcparam{*key} or returning an error code if it is not found. - -\funcname{krb5_free_keyblock} should be called on \funcparam{*key} when -the caller is finished with the key. - -Returns an error code if the entry is not found. - -\begin{funcdecl}{krb5_kt_add_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Calls the keytab-specific add routine \funcname{krb5_kt_add_internal} -with the same function arguments. If this routine is not available, -then KRB5_KT_NOWRITE is returned. - -\begin{funcdecl}{krb5_kt_remove_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Calls the keytab-specific remove routine -\funcname{krb5_kt_remove_internal} with the same function arguments. -If this routine is not available, then KRB5_KT_NOWRITE is returned. - -\begin{funcdecl}{krb5_kt_get_name}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{char *}{name} -\funcin -\funcarg{int}{namesize} -\end{funcdecl} - -\funcarg{name} is filled in with the first \funcparam{namesize} bytes of -the name of the keytab identified by \funcname{id}. -If the name is shorter than \funcparam{namesize}, then \funcarg{name} -will be null-terminated. - -\begin{funcdecl}{krb5_kt_close}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\end{funcdecl} - -Closes the keytab identified by \funcparam{id} and invalidates -\funcparam{id}, and releases any other resources acquired during use of -the key table. - -Requires that \funcparam{id} identifies a valid credentials cache. - -\begin{funcdecl}{krb5_kt_get_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Searches the keytab identified by \funcparam{id} for an entry whose -principal matches \funcparam{principal} and -whose key version number matches \funcparam{vno}. If \funcparam{vno} is -zero, the first entry whose principal matches is returned. - -Returns an error code if no suitable entry is found. If an entry is -found, the entry is returned in \funcparam{*entry}; its contents should -be deallocated by calling \funcname{krb5_kt_free_entry} when no longer -needed. - -\begin{funcdecl}{krb5_kt_free_entry}{krb5_error_code}{\funcinout} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Releases all storage allocated for \funcparam{entry}, which must point -to a structure previously filled in by \funcname{krb5_kt_get_entry} or -\funcname{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_start_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Prepares to read sequentially every key in the keytab identified by -\funcparam{id}. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{krb5_kt_next_entry}. - -\begin{funcdecl}{krb5_kt_next_entry}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\funcinout -\funcarg{krb5_kt_cursor}{cursor} -\end{funcdecl} - -Fetches the ``next'' entry in the keytab, returning it in -\funcparam{*entry}, and updates \funcparam{*cursor} for the next -request. If the keytab changes during the sequential get, an error is -guaranteed. \funcparam{*entry} should be freed after use by calling -\funcname{krb5_kt_free_entry}. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{krb5_kt_end_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{cursor}, -which must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{krb5_kt_start_seq_get} or a subsequent call to -\funcname{krb5_kt_next_entry}. - -May return error code if \funcparam{cursor} is invalid. - diff --git a/doc/api/krb5.tex b/doc/api/krb5.tex deleted file mode 100644 index 64760a131..000000000 --- a/doc/api/krb5.tex +++ /dev/null @@ -1,1296 +0,0 @@ -The main functions deal with the nitty-gritty details: verifying -tickets, creating authenticators, and the like. - -\begin{funcdecl}{krb5_encode_kdc_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_msgtype}{type} -\funcarg{const krb5_enc_kdc_rep_part *}{encpart} -\funcarg{const krb5_keyblock *}{client_key} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\funcout -\funcarg{krb5_data **}{enc_rep} -\end{funcdecl} - -Takes KDC rep parts in \funcparam{*rep} and \funcparam{*encpart}, and -formats it into \funcparam{*enc_rep}, using message type \funcparam{type} -and encryption key \funcparam{client_key} and encryption type -\funcparam{dec_rep{\ptsto}etype}. - -\funcparam{enc_rep{\ptsto}data} will point to allocated storage upon -non-error return; the caller should free it when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_decode_kdc_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_data *}{enc_rep} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_enctype}{etype} -\funcout -\funcarg{krb5_kdc_rep **}{dec_rep} -\end{funcdecl} - -Takes a KDC_REP message and decrypts encrypted part using -\funcparam{etype} and \funcparam{*key}, putting result in \funcparam{*dec_rep}. -The pointers in \funcparam{dec_rep} -are all set to allocated storage which should be freed by the caller -when finished with the response (by using \funcname{krb5_free_kdc_rep}). - - -If the response isn't a KDC_REP (tgs or as), it returns an error from -the decoding routines (usually ISODE_50_LOCAL_ERR_BADDECODE). - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_kdc_rep_decrypt_proc}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key} -\funcarg{krb5_const_pointer}{decryptarg} -\funcinout -\funcarg{krb5_kdc_rep *}{dec_rep} -\end{funcdecl} - -Decrypt the encrypted portion of \funcparam{dec_rep}, using the -encryption key \funcparam{key}. \funcparam{decryptarg} is ignored. - -The result is in allocated storage pointed to by -\funcparam{dec_rep{\ptsto}enc_part2}, unless some error occurs. - -This function is suitable for use as the \funcparam{decrypt_proc} -argument to \funcname{krb5_get_in_tkt}. - -\begin{funcdecl}{krb5_encrypt_tkt_part}{krb5_error_code}{ \funcin} -\funcarg{const krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -Takes unencrypted \funcparam{dec_ticket} and -\funcparam{dec_ticket{\ptsto}enc_part2}, encrypts with -\funcparam{dec_ticket{\ptsto}etype} -using \funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part}. -The string \funcparam{dec_ticket{\ptsto}enc_part} will be allocated -before formatting. - -Returns errors from encryption routines, system errors - -\funcparam{enc_part{\ptsto}data} is allocated and filled in with -encrypted stuff. - -\begin{funcdecl}{krb5_decrypt_tkt_part}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{srv_key} -\funcinout -\funcarg{krb5_ticket *}{dec_ticket} -\end{funcdecl} - -Takes encrypted \funcparam{dec_ticket{\ptsto}enc_part}, encrypts with -\funcparam{dec_ticket{\ptsto}etype} -using \funcparam{srv_key}, and places result in -\funcparam{dec_ticket{\ptsto}enc_part2}. The storage of -\funcparam{dec_ticket{\ptsto}enc_part2} will be allocated before return. - -Returns errors from encryption routines, system errors - -\begin{funcdecl}{krb5_send_tgs}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} -\funcarg{const krb5_ticket_times *}{timestruct} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{krb5_const_principal}{sname} -\funcarg{krb5_address * const *}{addrs} -\funcarg{krb5_authdata * const *}{authorization_data} -\funcarg{krb5_pa_data * const *}{padata} -\funcarg{const krb5_data *}{second_ticket} -\funcinout -\funcarg{krb5_creds *}{usecred} -\funcout -\funcarg{krb5_response *}{rep} -\end{funcdecl} - -Sends a request to the TGS and waits for a response. -\funcparam{options} is used for the options in the KRB_TGS_REQ. -\funcparam{timestruct} values are used for from, till, and rtime in the -KRB_TGS_REQ. -\funcparam{etype} is used for etype in the KRB_TGS_REQ. -\funcparam{sumtype} is used for the checksum in the AP_REQ in the KRB_TGS_REQ. -\funcparam{sname} is used for sname in the KRB_TGS_REQ. -\funcparam{addrs}, if non-NULL, is used for addresses in the KRB_TGS_REQ. -\funcparam{authorization_data}, if non-NULL, is used for -\funcparam{authorization_data} in the KRB_TGS_REQ. -\funcparam{padata}, if non-NULL, is combined with any other supplied -pre-authentication data for the KRB_TGS_REQ. -\funcparam{second_ticket}, if required by options, is used for the 2nd -ticket in the KRB_TGS_REQ. -\funcparam{usecred} is used for the ticket and session key in the KRB_AP_REQ header in the KRB_TGS_REQ. - -The KDC realm is extracted from \funcparam{usecred{\ptsto}server}'s realm. - -The response is placed into \funcparam{*rep}. -\funcparam{rep{\ptsto}response.data} is set to point at allocated storage -which should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_get_cred_from_kdc}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcout -\funcarg{krb5_creds ***}{tgts } -\end{funcdecl} - -Retrieve credentials for principal \funcparam{creds{\ptsto}client}, -server \funcparam{creds{\ptsto}server}, -ticket flags \funcparam{creds{\ptsto}ticket_flags}, possibly -\funcparam{creds{\ptsto}second_ticket} if needed by the ticket flags. - -\funcparam{ccache} is used to fetch initial TGT's to start the authentication -path to the server. - -Credentials are requested from the KDC for the server's realm. Any -TGT credentials obtained in the process of contacting the KDC are -returned in an array of credentials; \funcparam{tgts} is filled in to -point to an array of pointers to credential structures (if no TGT's were -used, the pointer is zeroed). TGT's may be returned even if no useful -end ticket was obtained. - -The returned credentials are NOT cached. - -If credentials are obtained, \funcparam{creds} is filled in with the results; -\funcparam{creds{\ptsto}ticket} and -\funcparam{creds{\ptsto}keyblock{\ptsto}key} are set to allocated storage, -which should be freed by the caller when finished. - -Returns errors, system errors. - - -\begin{funcdecl}{krb5_free_tgt_creds}{void}{\funcin} -\funcarg{krb5_creds **}{tgts} -\end{funcdecl} - -Frees the TGT credentials \funcparam{tgts} returned by -\funcname{krb5_get_cred_from_kdc}. - -\begin{funcdecl}{krb5_get_credentials}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -This routine attempts to use the credentials cache \funcparam{ccache} or a TGS -exchange to get an additional ticket for the client identified by -\funcparam{creds{\ptsto}client}, with following information: -\begin{itemize} -\item {\bf The server} identified by \funcparam{creds{\ptsto}server} -\item {\bf The options} in \funcparam{options} -Valid options are KRB5_GC_USER_USER and KRB5_GC_GC_CACHED -\item {\bf The expiration date} specified in -\funcparam{creds{\ptsto}times.endtime} -\item {\bf The session key type} specified in -\funcparam{creds{\ptsto}keyblock.keytype} if it is non-zero. -\end{itemize} - -If \funcparam{options} specifies KRB5_GC_CACHED, -\funcname{krb5_get_credentials} will only search the credentials cache -for a ticket. - -If \funcparam{options} specifies KRB5_GC_USER_USER, then -\funcname{krb5_get_credentials} will get credentials for a user to user -authentication. In a user to user authentication, the secret key for -the server -is the session key from the server's ticket-granting-ticket -(TGT). The TGT is passed from the server to the client over the -network --- this is safe since the TGT is encrypted in a key -known only by the Kerberos server --- and the client must pass -this TGT to \funcname{krb5_get_credentials} in -\funcparam{creds{\ptsto}second_ticket}. The Kerberos server will use -this TGT to construct a user to user ticket which can be verified by -the server by using the session key from its TGT. - -The effective {\bf expiration date} is the minimen of the following: -\begin{itemize} -\item The expiration date as specified in -\funcparam{creds{\ptsto}times.endtime} -\item The requested start time plus the maximum lifetime of the -server as specified by the server's entry in the -Kerberos database. -\item The requested start time plus the maximum lifetime of tickets -allowed in the local site, as specified by the KDC. -This is currently a compile-time option, -KRB5_KDB_MAX_LIFE in config.h, and is by default 1 day. -\end{itemize} - -If any special authorization data needs to be included in the ticket, ---- for example, restrictions on how the ticket can be used --- -they should be specified in \funcparam{creds{\ptsto}authdata}. If there -is no special authorization data to be passed, -\funcparam{creds{\ptsto}authdata} should be NULL. - -Any returned ticket and intermediate ticket-granting tickets are -stored in \funcparam{ccache}. - -Returns errors from encryption routines, system errors. - -\begin{funcdecl}{krb5_get_in_tkt}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keytype}{keytype} -\funcfuncarg{krb5_error_code}{(*key_proc)} - \funcarg{const krb5_keytype}{type} - \funcarg{krb5_keyblock **}{key} - \funcarg{krb5_const_pointer}{keyseed} - \funcarg{krb5_pa_data **}{padata} -\funcendfuncarg -\funcarg{krb5_const_pointer}{keyseed} -\funcfuncarg{krb5_error_code}{(*decrypt_proc)} - \funcarg{const krb5_keyblock *}{key} - \funcarg{krb5_const_pointer}{decryptarg} - \funcarg{krb5_kdc_rep *}{dec_rep} -\funcendfuncarg -\funcarg{krb5_const_pointer}{decryptarg} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_ccache}{ccache} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -All-purpose initial ticket routine, usually called via -\funcname{krb5_get_in_tkt_with_password} or -\funcname{krb5_get_in_tkt_with_skey}. - - -Attempts to get an initial ticket for \funcparam{creds{\ptsto}client} -to use server \funcparam{creds{\ptsto}server}, using the following: -the realm from \funcparam{creds{\ptsto}client}; the options in -\funcparam{options} (listed in Table \ref{KDCOptions}); -and \funcparam{pre_auth_type}, the preauthentication -method (valid preauthentication methods are listed in Table -\ref{padata-types}). -\funcname{krb5_get_in_tkt} requests encryption type -\funcparam{etype} (valid encryption types are ETYPE_DES_CBC_CRC and -ETYPE_RAW_DES_CBC), -using \funcparam{creds{\ptsto}times.starttime}, -\funcparam{creds{\ptsto}times.endtime}, -\funcparam{creds{\ptsto}times.renew_till} -as from, till, and rtime. \funcparam{creds{\ptsto}times.renew_till} is -ignored unless the RENEWABLE option is requested. - -\funcparam{key_proc} is called, with \funcparam{keytype}, -\funcparam{keyseed} and\funcparam{padata} as arguments, to fill in \funcparam{key} to be used for -decryption. The valid key types for \funcparam{keytype} are -KEYTYPE_NULL,\footnote{See RFC section 6.3.1} and -KEYTYPE_DES.\footnote{See RFC section 6.3.4} However, KEYTYPE_DES is -the only key type supported by MIT kerberos. -The content of \funcparam{keyseed} -depends on the \funcparam{key_proc} being used. %nlg - need a ref here -The \funcparam{padata} passed -to \funcparam{key_proc} is the preauthentication data returned by the -KDC as part of the reply to the initial ticket request. It may -contain an element of type KRB5_PADATA_PW_SALT, which -\funcparam{key_proc} should use to determine what salt to use when -generating the key. \funcparam{key_proc} should fill in -\funcparam{key} with a key for the client, or return an error code. - -\funcparam{decrypt_proc} is called to perform the decryption of the -response (the encrypted part is in -\funcparam{dec_rep{\ptsto}enc_part}; the decrypted part should be -allocated and filled into -\funcparam{dec_rep{\ptsto}enc_part2}. -\funcparam{decryptarg} is passed on to \funcparam{decrypt_proc}, and -its content depends on the \funcparam{decrypt_proc} being used. - -If \funcparam{addrs} is non-NULL, it is used for the addresses -requested. If it is null, the system standard addresses are used. - -If \funcparam{ret_as_reply} is non-null, it is filled in with a -pointer to a structure containing the reply packet from the KDC. Some -programs may find it useful to have direct access to this information. -For example, it can be used to obtain the pre-authentication data -passed back from the KDC. The caller is responsible for freeing this -structure by using \funcname{krb5_free_kdc_rep}. - -A succesful call will place the ticket in the credentials cache -\funcparam{ccache} and fill in \funcparam{creds} with the ticket -information used/returned. - -Returns system errors, preauthentication errors, encryption errors. - -% XXX Right now, uses creds->addresses before it's copied into from -% the reply -- it's passed to krb5_obtain_padata. I think that's -% wrong, and it should be using either addrs or the result of -% krb5_os_localaddr instead. If I'm wrong, then this spec has to be -% updated to document that creds->addresses is used. On the other -% hand, if I'm right, then the bug in get_in_tkt needs to be fixed. -% See ov-cambridge PR 1525. - -\begin{funcdecl}{krb5_get_in_tkt_with_password}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keytype}{keytype} -\funcarg{const char *}{password} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -Attempts to get an initial ticket using the null-terminated string -\funcparam{password}. If \funcparam{password} is NULL, the password -is read from the terminal. - -The password is converted into a key using the appropriate -string-to-key conversion function for the specified -\funcparam{keytype}, and using any salt data returned by the KDC in -response to the authentication request. - -See \funcname{krb5_get_in_tkt} for documentation of the -\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type}, -\funcparam{etype}, \funcparam{keytype}, \funcparam{ccache}, -\funcparam{creds} and \funcparam{ret_as_reply} arguments. - -Returns system errors, preauthentication errors, encryption errors. - -\begin{funcdecl}{krb5_get_in_tkt_with_skey}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{options} -\funcarg{krb5_address * const *}{addrs} -\funcarg{const krb5_preauthtype}{pre_auth_type} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_kdc_rep **}{ret_as_reply} -\end{funcdecl} - -Attempts to get an initial ticket using \funcparam{key}. If -\funcparam{key} is NULL, an appropriate key is retrieved from the -system key store (e.g., \filename{/etc/v5srvtab}). - -See \funcname{krb5_get_in_tkt} for documentation of the -\funcparam{options}, \funcparam{addrs}, \funcparam{pre_auth_type}, -\funcparam{etype}, \funcparam{ccache}, \funcparam{creds} and -\funcparam{ret_as_reply} arguments. - -Returns system errors, preauthentication errors, encryption errors. - -\begin{funcdecl}{krb5_mk_req}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_flags}{ap_req_options} -\funcarg{const krb5_checksum *}{checksum} -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}. - -\funcparam{server} specifies the principal of the server to receive the -message; if credentials are not present in the credentials cache -\funcparam{ccache} for this server, the TGS request with default -parameters is used in an attempt to obtain such credentials, and they -are stored in \funcparam{ccache}. - -\funcparam{ap_req_options} specifies the KRB_AP_REQ options desired. -Valid options are -AP_OPTS_USE_SESSION_KEY and -AP_OPTS_MUTUAL_REQUIRED. - -\funcparam{checksum} specifies the checksum to be used in the -authenticator. If it is null, no checksum is included. - -% XXX Not sure if it's legal in the protocol for no checksum to be -% included, or if so, how the server reacts to a request with no -% checksum. - -\funcparam{outbuf} should point to an existing \datatype{krb5_data} -structure. \funcparam{outbuf{\ptsto}length} and -\funcparam{outbuf{\ptsto}data} will be filled in on success, and the latter -should be freed by the caller when it is no longer needed; if an error -is returned, however, no storage is allocated and {\tt -outbuf{\ptsto}data} does not need to be freed. - -Returns system errors, error getting credentials for -\funcparam{server}. - -\begin{funcdecl}{krb5_mk_req_extended}{krb5_error_code}{\funcin} -\funcarg{const krb5_flags}{ap_req_options} -\funcarg{const krb5_checksum *}{checksum} -\funcarg{const krb5_flags}{kdc_options} -\funcarg{krb5_int32}{sequence} -\funcarg{krb5_keyblock **}{newkey} -\funcarg{krb5_ccache}{ccache} -\funcinout -\funcarg{krb5_creds *}{creds} -\funcarg{krb5_authenticator *}{authentp} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_AP_REQ message into \funcparam{outbuf}, with more complete -options than \funcname{krb5_mk_req}. - -\funcparam{outbuf}, \funcparam{ap_req_options}, \funcparam{checksum}, -and \funcparam{ccache} are used in the same fashion as for -\funcname{krb5_mk_req}. - -\funcparam{creds} is used to supply the credentials (ticket and session -key) needed to form the request. - -If \funcparam{creds{\ptsto}ticket} has no data (length == 0), then a -ticket is obtained from either \funcparam{ccache} or the TGS, and the -resulting ticket is stored in the \funcparam{creds} structure. -\funcparam{kdc_options} specifies the options -for the ticket to be used. If a ticket with appropriate flags is not -found in -\funcparam{ccache}, then these options are passed on in a request to an -appropriate KDC. - -During this call, the structure elements in \funcparam{creds} may be -freed and reallocated. Hence all of the structure elements which are -pointers should point to allocated memory, and there should be no other -pointers aliased to the same memory, since it may be deallocated during -this procedure call. - -\funcparam{sequence}, if non-zero, specifies the initial sequence number -which the caller will use for KRB_SAFE or KRB_PRIV messages. - -\funcparam{newkey}, if non-NULL, will be filled in upon return with a -sub-session key that the caller can use to protect future KRB_SAFE or -KRB_PRIV messages. When the caller is finished with the key, it should -be freed with \funcname{krb5_free_keyblock}. \funcparam{newkey} will -not be filled in if an error is returned by -\funcname{krb5_mk_req_extended}. - -If \funcparam{ap_req_options} specifies AP_OPTS_USE_SESSION_KEY, then -\funcparam{creds{\ptsto}ticket} must contain the appropriate -ENC-TKT-IN-SKEY ticket. - -If \funcparam{authentp} is non-NULL, \funcname{krb5_mk_req_extended} -will store -a copy of the authenticator there, with the principal and checksum fields -nulled out, unless an error is returned. (This is to prevent pointer -sharing problems; the caller -shouldn't need these fields anyway, since the caller supplied them.) - -Returns system errors, errors contacting the KDC, KDC errors getting -a new ticket for the authenticator. - -\begin{funcdecl}{krb5_generate_subkey}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_keyblock **}{subkey} -\end{funcdecl} - -Generates a pseudo-random sub-session key using the encryption system's -random key functions, based on the input \funcparam{key}. - -\funcparam{subkey} is filled in to point to the generated subkey, unless -an error is returned. The returned key (i.e., \funcparam{*subkey}) is -allocated and should be freed by the caller with -\funcname{krb5_free_keyblock} when it is no longer needed. - -\begin{funcdecl}{krb5_rd_req}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const char *}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcinout -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Parses a KRB_AP_REQ message, returning its contents. Upon successful -return, -\funcparam{*authdat} will be modified to point to allocated storage -containing the ticket and authenticator information. The caller is -responsible for deallocating this space by using -\funcname{krb5_free_tkt_authent}. - -\funcparam{inbuf} should contain the KRB_AP_REQ message to be parsed. - -\funcparam{server} specifies the expected server's name for the ticket. -If \funcparam{server} is NULL, then any server name will be accepted if -the appropriate key can be found, and the caller should verify that the -server principal matches some trust criterion. - -\funcparam{sender_addr} specifies the address(es) expected to be present -in the ticket. - -\funcparam{keyproc} specifies a procedure to generate a decryption key for the -ticket. If \funcparam{keyproc} is non-NULL, \funcparam{keyprocarg} is -passed to it, and the result is used as a decryption key. If -\funcparam{keyproc} is NULL, then the decryption key is taken from a key store -\footnote{i.e., srvtab file in Kerberos V4 parlance} specified by -\funcparam{fetchfrom}. If \funcparam{fetchfrom} is NULL, then the -default key store is consulted; otherwise, \funcparam{fetchfrom} -specifies the name of the key store, using the format as specified by -\funcname{krb5_kt_resolve}. - - - - then \funcparam{fetchfrom} is checked; if -it is non-NULL, it specifies a the name of the key store from which to -retrieve the decription key. If \funcparam{fetchfrom} is NULL, then -the default key store is consulted. - -\funcparam{rcache} specifies a replay detection cache used to store -authenticators and server names. If \funcparam{rcache} is NULL, then no -replay detection is performed. - -Returns system errors, encryption errors, replay errors. - -\begin{funcdecl}{krb5_rd_req_simple}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Similar to \funcname{krb5_rd_req}, but with some arguments replaced by -defaults. - -The \funcparam{inbuf}, \funcparam{server}, \funcparam{sender_addr} and -\funcparam{authdat} arguments are as in \funcname{krb5_rd_req}, with -the exception that {\tt server} should be specified. If -\funcparam{server} is null, then any server name will be accepted as -long as a service key can be found for that service. It is then the -caller's responsibility to check the actual server that was -authenticated by looking in the \funcparam{authdat} structure. Also, -if -\funcparam{server} is null, replay cache protection is {\em not} -provided! - -A replay cache name derived from the first component of the service -name is used. - -The default key store is consulted to find the service key. - -Returns system errors, encryption errors, replay errors. - - -\begin{funcdecl}{krb5_rd_req_decoded}{krb5_error_code}{\funcin} -\funcarg{const krb5_ap_req *}{req} -\funcarg{krb5_const_principal}{server} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const char *}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_tkt_authent **}{authdat} -\end{funcdecl} - -Essentially the same as \funcname{krb5_rd_req}, but uses a decoded AP_REQ -as the input rather than an encoded input. - -\begin{funcdecl}{krb5_mk_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_ap_rep_enc_part *}{repl} -\funcarg{const krb5_keyblock *}{kblock} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats and encrypts an AP_REP message, including in it the data in -\funcparam{*repl}, encrypted using \funcparam{*kblock}. - -When successfull, \funcparam{outbuf{\ptsto}length} and -\funcparam{outbuf{\ptsto}data} are filled in with the length of the -AP_REQ message and allocated data holding it. -\funcparam{outbuf{\ptsto}data} should be freed by the -caller when it is no longer needed. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_rep}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{kblock} -\funcout -\funcarg{krb5_ap_rep_enc_part **}{repl} -\end{funcdecl} - -Parses and decrypts an AP_REP message from \funcparam{*inbuf}, filling in -\funcparam{*repl} with a pointer to allocated storage containing the -values from the message. The caller is responsible for freeing this -structure with \funcname{krb5_free_ap_rep_enc_part}. - -The key in \funcparam{*kblock} is used to decrypt the message. - -Returns system errors, encryption errors, replay errors. - -\begin{funcdecl}{krb5_mk_error}{krb5_error_code}{\funcin} -\funcarg{const krb5_error *}{dec_err} -\funcout -\funcarg{krb5_data *}{enc_err} -\end{funcdecl} - -Formats the error structure \funcparam{*dec_err} into an error buffer -\funcparam{*enc_err}. - -The error buffer storage (\funcparam{enc_err{\ptsto}data}) is -allocated, and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_rd_error}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{enc_errbuf} -\funcout -\funcarg{krb5_error **}{dec_error} -\end{funcdecl} - -Parses an error protocol message from \funcparam{enc_errbuf} and fills in -\funcparam{*dec_error} with a pointer to allocated storage containing -the error message. The caller is reponsible for free this structure by -using \funcname{krb5_free_error}. - -Returns system errors. - -\begin{funcdecl}{krb5_generate_seq_number}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key} -\funcout -\funcarg{krb5_int32 *}{seqno} -\end{funcdecl} - -Generates a pseudo-random sequence number suitable for use as an initial -sequence number for the KRB_SAFE and KRB_PRIV message processing -routines. - -\funcparam{key} parameterizes the choice of the random sequence number, -which is filled into \funcparam{*seqno} upon return. - -\begin{funcdecl}{krb5_sendauth}{krb5_error_code} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{client} -\funcarg{krb5_principal}{server} -\funcarg{krb5_flags}{ap_req_options} -\funcarg{krb5_checksum *}{checksump} -\funcinout -\funcarg{krb5_creds *}{credsp} -\funcarg{krb5_ccache}{ccache} -\funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_keyblock **}{newkey} -\funcarg{krb5_error **}{error} -\funcarg{krb5_ap_rep_enc_part **}{rep_result} -\end{funcdecl} - -\funcname{krb5_sendauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} sends an authenticated -ticket from the client program to the server program using the network -connection specified by \funcparam{fd}. In the MIT Unix implementation, -\funcparam{fd} should be a pointer to a file descriptor describing the -network socket. This can be changed in other implementations, however, -if the routines \funcname{krb5_read_message}, -\funcname{krb5_write_message}, \funcname{krb5_net_read}, and -\funcname{krb5_net_write} are changed. - -The paramter \funcparam{appl_version} is a string describing the -application protocol version which the client is expecting to use for -this exchange. If the server is using a different application protocol, -an error will be returned. - -The parameters \funcparam{client} and \funcparam{server} specify the -kerberos principals for the client and the server. They are -ignored if \funcparam{credsp} is non-null. Otherwise, -\funcparam{server} must be non-null, but \funcparam{client} may be -null, in which case the client principal used is the one in the -credential cache's default principal. - -The \funcparam{ap_req_options} parameters specifies the options which -should be passed to \funcname{krb5_mk_req}. Valid options are listed -in Table \ref{ap-req-options}. If \funcparam{ap_req_options} -specifies MUTUAL_REQUIRED, then \funcname{krb5_sendauth} will perform -a mutual authentication exchange, and if \funcparam{rep_result} is -non-null, it will be filled in with the result of the mutual -authentication exchange; the caller should free -\funcparam{*rep_result} with -\funcname{krb5_free_ap_rep_enc_part} when done with it. - -The \funcparam{checksump} parameter is optional; if it is non-null, -then the checksum structure will be sent to the server as part of the -authenticated ticket exchange. - -If \funcparam{credsp} is non-null, then \funcparam{credsp{\ptsto}client} and -\funcparam{credsp{\ptsto}server} must be filled in, and either -the other structure fields should be filled in with valid credentials, -or \funcparam{credsp{\ptsto}ticket.length} should be zero. If -\funcparam{credsp{\ptsto}ticket.length} is non-zero, then -\funcparam{credsp} will be used as-is as the credentials to send to -the server, and \funcparam{ccache} is ignored; otherwise, -\funcparam{ccache} is used as described below, and \funcparam{credsp} -is filled in with the retrieved credentials. - -\funcname{ccache} specifies the credential cache to use when one is -needed (i.e., when \funcname{credsp} is null or -\funcparam{credsp{\ptsto}ticket.length} is zero). When a credential -cache is not needed, \funcname{ccache} is ignored. When a credential -cache is needed and \funcname{ccache} is null, the default credential -cache is used. Note that if the credential cache is needed and does -not contain the needed credentials, they will be retrieved from the -KDC and stored in the credential cache. - -If non-null, \funcparam{sequence} is filled in with the sequence number -which the client should use for sending or receiving messages generated -using \funcname{krb5_mk_safe} and \funcname{krb5_mk_priv}. If mutual -authentication is used and \funcparam{rep_result} is non-null, the -sequence number for the server is available to the caller in -\funcparam{*rep_result->seq_number}. (If mutual authentication is not -used, there is no way to negotiate a sequence number for the server.) - -The \funcparam{newkey} parameter functions as described for -\funcname{krb5_mk_req_extended}. - -If an error occurs during the authenticated ticket exchange and -\funcparam{error} is non-null, the error packet (if any) that was sent -from the server will be placed in it. This error should be freed with -\funcname{krb5_free_error}. - -\begin{funcdecl}{krb5_recvauth}{krb5_error_code} -\funcin -\funcarg{krb5_pointer}{fd} -\funcarg{char *}{appl_version} -\funcarg{krb5_principal}{server} -\funcarg{krb5_address *}{sender_addr} -\funcarg{krb5_pointer}{fetchfrom} -\funcfuncarg{krb5_error_code}{(*keyproc)} - \funcarg{krb5_pointer}{keyprocarg} - \funcarg{krb5_principal}{principal} - \funcarg{krb5_kvno}{vno} - \funcarg{krb5_keyblock **}{key} -\funcendfuncarg -\funcarg{krb5_pointer}{keyprocarg} -\funcarg{char *}{rc_type} -\funcarg{krb5_int32}{flags} -\funcout -\funcarg{krb5_int32 *}{sequence} -\funcarg{krb5_principal *}{client} -\funcarg{krb5_ticket **}{ticket} -\funcarg{krb5_authenticator **}{authent} -\end{funcdecl} - -\funcname{krb5_recvauth} provides a convenient means for client and -server programs to send authenticated messages to one another through -network connections. \funcname{krb5_sendauth} is the matching routine -to \funcname{ krb5_recvauth} for the server. \funcname{krb5_recvauth} -will engage in an authentication dialogue with the -client program running \funcname{krb5_sendauth} to authenticate the -client to the server. In addition, if requested by the client, -\funcname{krb5_recvauth} will provide mutual authentication to -prove to the client that the server represented by -\funcname{krb5_recvauth} is legitimate. - -\funcparam{fd} is a pointer to the network connection. As in -\funcname{krb5_sendauth}, in the MIT Unix implementation -\funcparam{fd} is a pointer to a file descriptor. - -The parameter \funcparam{appl_version} is a string describing the -application protocol version which the server is expecting to use for -this exchange. If the client is using a different application protocol, -an error will be returned and the authentication exchange will be -aborted. - -If \funcparam{server} is non-null, then \funcname{krb5_recvauth} -verifies that the server principal requested by the client matches -\funcparam{server}. If not, an error will be returned and the -authentication exchange will be aborted. - -If \funcparam{sender_addr} is non-null, then \funcname{krb5_recvauth} -verifies that the address(es) specified is/are present in the -credentials sent by the client. If not, an error will be returned and -the authentication exchange will be aborted. - -The parameters \funcparam{fetchfrom}, \funcparam{keyproc}, and -\funcparam{keyprocarg} are used by \funcname{krb5_rd_req} to obtain the -server's private key. - -\funcparam{rc_type} is a string which determins which type of replay -cache \funcname{krb5_recvauth} should use. If it is null, the default -replay cache type will be used. \funcname{krb5_recvauth} uses a -standard convention for determining the name of the replay cache to be -used. - -The \funcparam{flags} argument allows the caller to modify the behavior of -\funcname{krb5_recvauth}. For non-library callers, \funcparam{flags} -should be 0. - -% XXX Note that if the bug I submitted entitled ``"flags" argument -% should not have been added to krb5_recvauth'' (OpenVision Cambridge -% bug number 1585) causes code changes, this will have to be updated. - -All of the output paramters are optional and they are only filled in -if they are non-null. \funcparam{sequence} is filled in with the -sequence number which the server should use (if desired) for sending -messages using \funcname{krb5_mk_safe} and -\funcname{krb5_mk_priv}. The client's sequence number is passed back -as part of the authenticator structure which is filled in if -\funcparam{authent} is non-null (\funcparam{authent} should be freed -with \funcname{krb5_free_authenticator} when it is no longer needed). - -\funcparam{client} is filled in with the client principal which -initiated the authenticated connection, and should be freed with -\funcname{krb5_free_principal} when it is no longer needed. - -\funcparam{ticket} is filled in with the data from the ticket sent by -the client, and should be freed with \funcname{krb5_free_ticket} when -it is no longer needed. - -\begin{funcdecl}{krb5_mk_safe}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{userdata} -\funcarg{const krb5_cksumtype}{sumtype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_fulladdr *}{sender_addr} -\funcarg{const krb5_fulladdr *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_SAFE message into \funcparam{outbuf}. - -\funcparam{userdata} is formatted as the user data in the message. -\funcparam{sumtype} specifies the checksum type; \funcparam{key} -specifies the key which might be used to seed the checksum; -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver. The host -portion of \funcparam{sender_addr} is used to form the addresses used -in the KRB_SAFE message. \funcparam{recv_addr} is optional; if the -receiver's address is not known, it may be replaced by NULL. -\funcparam{sender_addr}, however, is mandatory. - -\funcparam{safe_flags} selects whether sequence numbers or timestamps -should be used to identify the message. Valid flags are listed below. - -\begin{tabular}{ll} -\multicolumn{1}{c}{Symbol} & Meaning \\ -KRB5_SAFE_NOTIME & Don't use timestamps \\ -KRB5_SAFE_DOSEQUENCE & Use sequence numbers \\ -\end{tabular} - -If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in -\funcparam{safe_flags}), an entry -describing the message will be entered in the replay cache -\funcparam{rcache} so that the caller may detect if this message is sent -back to him by an attacker. If KRB5_SAFE_NOTIME is set, -\funcparam{rcache} is not used. - -If sequence numbers are to be used (i.e., if KRB5_SAFE_DOSEQUENCE is -set in \funcparam{safe_flags}), then \funcparam{seq_number} will be -placed in the protected message as its sequence number. Otherwise, -\funcparam{seq_number} is unused. - -The functions \funcname{krb5_gen_replay_name} and -\funcname{krb5_get_server_rcache} can be used to open a replay cache -appropriate to use as \funcparam{rcache}. - -The \funcparam{outbuf} buffer storage (i.e., -\funcparam{outbuf{\ptsto}data}) is allocated, and should be freed by -the caller when finished. - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_rd_safe}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{safe_flags} -\funcinout -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Parses a KRB_SAFE message from \funcparam{inbuf}, placing the -data in \funcparam{*outbuf} after verifying its integrity. - -\funcparam{key} specifies the key to be used for verifying the -integrity of the message. - -\funcparam{sender_addr} and \funcparam{recv_addr} specify the full -addresses (host and port) of the sender and receiver, and must be of -type \datatype{ADDRTYPE_ADDRPORT}. - -The \funcparam{sender_addr} parameter is mandatory; it -specifies the address of the sender. If the address of the sender in -the message does not match \funcparam{sender_addr}, the error -KRB5KRB_AP_ERR_BADADDR will be returned. - -If \funcparam{recv_addr} is non-NULL, then the address of the receiver -in the message much match it. If it is null, the receiver address in -the message will be checked against the list of local addresses as -returned by \funcname{krb5_os_localaddr}. - -The \funcparam{outbuf} buffer storage (i.e., -\funcparam{outbuf{\ptsto}data} is allocated storage which the caller -should free when it is no longer needed. - -If \funcparam{safe_flags} indicates that sequence numbers are to be -used (i.e., if KRB5_SAFE_DOSEQUENCE is set in it), -\funcparam{seq_number} is compared to the sequence number for the -message, and KRB5_KRB_AP_ERR_BADORDER is returned if it does not -match. Otherwise, \funcparam{seq_number} is not used. - -If timestamps are to be used (i.e., if KRB5_SAFE_NOTIME is not set in -\funcparam{safe_flags}), then four additional checks are performed: -\begin{itemize} -\item The timestamp in the message must be within the permitted clock - skew (which is usually five minutes), or KRB5KRB_AP_ERR_SKEW - is returned. -\item The address in the message must match \funcparam{sender_addr}, - or KRB5KRB_AP_ERR_BADADDR is returned. -\item If \funcparam{recv_addr} is supplied, then it must match - the receiver address in the message (if \funcparam{recv_addr} - is null, this check is not done), or KRB5KRB_AP_ERR_BADADDR is - returned. -\item The message must not be a replayed message, according to - \funcparam{rcache}. -\end{itemize} -If NOTIME is specified, then \funcparam{sender_addr}, -\funcparam{recv_addr} and \funcparam{rcache} are not used. - -% XXX The text above might change -- the address checks might move -% outside of the NOTIME restriction. See PR 1576. - -The function \funcname{krb5_get_server_rcache} and the service-name -portion of the server principal name can be used to open a -replay cache appropriate to use as \funcparam{rcache}. - -Returns system errors, integrity errors. - -\begin{funcdecl}{krb5_mk_priv}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{userdata} -\funcarg{const krb5_enctype}{etype} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcarg{krb5_rcache}{rcache} -\funcinout -\funcarg{krb5_pointer}{i_vector} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Formats a KRB_PRIV message into \funcparam{outbuf}. Behaves similarly -to \funcname{krb5_mk_safe}, but the message is encrypted and -integrity-protected rather than just integrity-protected. - -\funcparam{userdata}, \funcparam{server_addr}, \funcparam{recv_addr}, -\funcparam{seq_number}, \funcparam{priv_flags}, \funcparam{rcache} and -\funcparam{outbuf} function as in \funcname{krb5_mk_safe}. - -As in \funcname{krb5_mk_safe}, \funcparam{recv_addr} is optional; if -the receiver's address is not known, it may be replaced by NULL. -\funcparam{sender_addr}, however, is mandatory. - -\funcparam{etype} specifies the encryption type to use; -\funcparam{key} specifies the encryption key. If \funcparam{i_vector} -is non-null, it is used as an initialization vector for the encryption -(if encryption type \funcparam{etype} supports initialization vectors) -and its contents are replaced with the last block of encrypted data -upon return. - -\funcparam{priv_flags} selects whether sequence numbers or timestamps -should be used to identify the message. Valid flags are listed below. - -\begin{tabular}{ll} -\multicolumn{1}{c}{Symbol} & Meaning \\ -KRB5_PRIV_NOTIME & Don't use timestamps \\ -KRB5_PRIV_DOSEQUENCE & Use sequence numbers \\ -\end{tabular} - -Returns system errors, encryption errors. - -\begin{funcdecl}{krb5_rd_priv}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{inbuf} -\funcarg{const krb5_keyblock *}{key} -\funcarg{const krb5_address *}{sender_addr} -\funcarg{const krb5_address *}{recv_addr} -\funcarg{krb5_int32}{seq_number} -\funcarg{krb5_int32}{priv_flags} -\funcinout -\funcarg{krb5_pointer}{i_vector} -\funcarg{krb5_rcache}{rcache} -\funcout -\funcarg{krb5_data *}{outbuf} -\end{funcdecl} - -Parses a KRB_PRIV message from \funcparam{inbuf}, placing the data in -\funcparam{*outbuf} after decrypting it. Behaves similarly to -\funcname{krb5_rd_safe}, but the message is decrypted rather than -integrity-checked. - -\funcparam{inbuf}, \funcparam{sender_addr}, \funcparam{recv_addr}, -\funcparam{seq_number}, \funcparam{rcache} and \funcparam{outbuf} -function as in \funcname{krb5_rd_safe}. - - -The \funcparam{sender_addr} parameter is mandatory; it -specifies the address of the sender. If the address of the sender in -the message does not match \funcparam{sender_addr}, the error -KRB5KRB_AP_ERR_BADADDR will be returned. - -If \funcparam{recv_addr} is non-NULL, then the address of the receiver -in the message much match it. If it is null, the receiver address in -the message will be checked against the list of local addresses as -returned by \funcname{krb5_os_localaddr}. - -\funcparam{key} specifies the key to be used for decryption of the -message. If \funcparam{i_vector} is non-null, it is used as an -initialization vector for the decryption (if the encryption type of -the message supports initialization vectors) and its contents are -replaced with the last block of encrypted data in the message. - -\funcparam{priv_flags} specifies whether timestamps and sequence -numbers are to be used; it functions as the \funcparam{safe_flags} -argument of \funcname{krb5_rd_safe} (but expects KRB5_PRIV_ flags -rather than KRB5_SAFE_ flags). - -Returns system errors, integrity errors. - -\begin{funcdecl}{krb5_parse_name}{krb5_error_code}{\funcin} -\funcarg{const char *}{name} -\funcout -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Converts a single-string representation \funcparam{name} of the -principal name to the multi-part principal format used in the protocols. - -A single-string representation of a Kerberos name consists of one or -more principal name components, separated by slashes, optionally -followed by the ``@'' character and a realm name. If the realm name -is not specified, the local realm is used. - -The slash and ``@'' characters may be quoted (i.e., included as part -of a component rather than as a component separator or realm prefix) -by preceding them with a backslash (``$\backslash$'') character. -Similarly, newline, tab, backspace, and null characters may be -included in a component by using $\backslash{}n$, $\backslash{}t$, -$\backslash{}b$ or $\backslash{}0$, respectively. - -The realm in a Kerberos name may not contain the slash, colon or null -characters. - -\funcparam{*principal} will point to allocated storage which should be freed by -the caller (using \funcname{krb5_free_principal}) after use. - -\funcname{krb5_parse_name} returns KRB5_PARSE_MALFORMED if the string is - badly formatted, or ENOMEM if space for the return value can't be -allocated. - -\begin{funcdecl}{krb5_unparse_name}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{principal} -\funcout -\funcarg{char **}{name} -\end{funcdecl} - -Converts the multi-part principal name \funcparam{principal} from the -format used in the protocols to a single-string representation of the -name. The resulting single-string representation will use the format -and quoting conventions described for \funcname{krb5_parse_name} -above. - -\funcparam{*name} points to allocated storage and should be freed by the caller -when finished. - -\funcname{krb5_unparse_name} returns KRB_PARSE_MALFORMED if the principal -does not contain at least 2 components, and system errors (ENOMEM if -unable to allocate memory). - -\begin{funcdecl}{krb5_unparse_name_ext}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{principal} -\funcinout -\funcarg{char **}{name} -\funcarg{int *}{size} -\end{funcdecl} - -\funcname{krb5_unparse_name_ext} is designed for applications which -must unparse a large number of principals, and are concerned about the -speed impact of needing to do a lot of memory allocations and -deallocations. It functions similarly to \funcname{krb5_unparse_name} -except if \funcparam{*name} is non-null, in which case, it is assumed -to contain an allocated buffer of size \funcparam{*size} and this -buffer will be resized with \funcname{realloc} to hold the unparsed -name. Note that in this case, -\funcparam{size} must not be null. - -If \funcparam{size} is non-null (whether or not \funcparam{*name} is -null when the function is called), it will be filled in with the size -of the unparsed name upon successful return. - -\begin{funcdecl}{krb5_build_principal}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{char}{*s1, *s2, ..., 0} -\end{funcdecl} -\begin{funcdecl}{krb5_build_principal_va}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{va_list}{ap} -\end{funcdecl} - -\funcname{krb5_build_principal} and \funcname{krb5_build_principal_va} -perform the same function; the former takes variadic arguments, while -the latter takes a pre-computed varargs pointer. - -Both functions take a realm name \funcparam{realm}, realm name length -\funcparam{rlen}, and a list of null-terminated strings, and fill in a -pointer to a principal structure \funcparam{princ}, making it point to a -structure representing the named principal. -The last string must be followed in the argument list by a null pointer. - - -\begin{funcdecl}{krb5_build_principal_ext}{krb5_error_code}{\funcout} -\funcarg{krb5_principal *}{princ} -\funcin -\funcarg{int}{rlen} -\funcarg{const char *}{realm} -\funcarg{}{int len1, char *s1, int len2, char *s2, ..., 0} -\end{funcdecl} - -\funcname{krb5_build_principal_ext} is similar to -\funcname{krb5_build_principal} but it takes its components as a list of -(length, contents) pairs rather than a list of null-terminated strings. -A length of zero indicates the end of the list. - -\begin{funcdecl}{krb5_address_search}{krb5_boolean}{\funcin} -\funcarg{const krb5_address *}{addr} -\funcarg{krb5_address * const *}{addrlist} -\end{funcdecl} - -If \funcparam{addr} is listed in \funcparam{addrlist}, or -\funcparam{addrlist} is null, return TRUE. If not listed, return FALSE. - -\begin{funcdecl}{krb5_address_compare}{krb5_boolean}{\funcin} -\funcarg{const krb5_address *}{addr1} -\funcarg{const krb5_address *}{addr2} -\end{funcdecl} - -If the two addresses are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_principal_compare}{krb5_boolean}{\funcin} -\funcarg{krb5_const_principal}{p1} -\funcarg{krb5_const_principal}{p2} -\end{funcdecl} - -If the two principals are the same, return TRUE, else return FALSE. - -\begin{funcdecl}{krb5_fulladdr_order}{int}{\funcin} -\funcarg{const krb5_fulladdr *}{addr1} -\funcarg{const krb5_fulladdr *}{addr2} -\end{funcdecl} - -Return an ordering on the two full addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_address_order}{int}{\funcin} -\funcarg{const krb5_address *}{addr1} -\funcarg{const krb5_address *}{addr2} -\end{funcdecl} - -Return an ordering on the two addresses: 0 if the same, -$< 0$ if first is less than 2nd, $> 0$ if first is greater than 2nd. - -\begin{funcdecl}{krb5_copy_keyblock}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock **}{to} -\end{funcdecl} - -Copy a keyblock, filling in \funcparam{*to} to point to the newly -allocated copy, which should be freed with -\funcname{krb5_free_keyblock}. - -\begin{funcdecl}{krb5_copy_keyblock_contents}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{from} -\funcout -\funcarg{krb5_keyblock *}{to} -\end{funcdecl} - -Copy a keyblock from \funcparam{from} to \funcparam{to}, including -allocated storage. The allocated storage in \funcparam{to} should be -freed by using {\bf free}(\funcparam{to->contents}). - -\begin{funcdecl}{krb5_copy_creds}{krb5_error_code}{\funcin} -\funcarg{const krb5_creds *}{incred} -\funcout -\funcarg{krb5_creds **}{outcred} -\end{funcdecl} - -Copy a credentials structure, filling in \funcparam{*outcred} to point -to the newly allocated copy, which should be freed with -\funcname{krb5_free_creds}. - -\begin{funcdecl}{krb5_copy_data}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{indata} -\funcout -\funcarg{krb5_data **}{outdata} -\end{funcdecl} - -Copy a data structure, filling in \funcparam{*outdata} to point to the -newly allocated copy, which should be freed with \funcname{krb5_free_data}. - -\begin{funcdecl}{krb5_copy_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{inprinc} -\funcout -\funcarg{krb5_principal *}{outprinc} -\end{funcdecl} -Copy a principal structure, filling in \funcparam{*outprinc} to point to -the newly allocated copy, which should be freed with -\funcname{krb5_free_principal}. - -\begin{funcdecl}{krb5_auth_to_rep}{krb5_error_code}{\funcin} -\funcarg{krb5_tkt_authent *}{auth} -\funcout -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Extract the relevant parts of \funcparam{auth} and fill them into the -structure pointed to by \funcparam{rep}. \funcparam{rep{\ptsto}client} -and \funcparam{rep{\ptsto}server} are set to allocated storage and -should be freed when \funcparam{*rep} is no longer needed. - -\begin{funcdecl}{krb5_get_server_rcache}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{piece} -\funcout -\funcarg{krb5_rcache *}{ret_rcache} -\end{funcdecl} -Generate a replay cache name, allocate space for its handle, and open -it. \funcparam{piece} is used to distinguish this replay cache from -others currently in use on the system. Typically, \funcparam{piece} -is the first component of the principal name for the client or server -which is calling \funcname{krb5_get_server_rcache}. - -Upon successful return, \funcparam{ret_rcache} is filled in to contain a -handle to an open rcache, which should be closed with -\funcname{krb5_rc_close}. - - diff --git a/doc/api/libdes.tex b/doc/api/libdes.tex deleted file mode 100644 index c53c81350..000000000 --- a/doc/api/libdes.tex +++ /dev/null @@ -1,38 +0,0 @@ -\documentstyle[ncs,fixunder,functions,twoside]{article} -\setlength{\oddsidemargin}{0.25in} -\setlength{\evensidemargin}{-0.25in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\textwidth}{6.25in} - -\pagestyle{headings} -\begin{document} -\begin{center} -{\Huge Kerberos V5 Data Encryption Standard library} \\ -{\Large DRAFT} -\end{center} -\section{DES functions} -The DES functions conform to the encryption interface required by the -Kerberos version 5 library, and provide an encryption mechanism based on -the DES Cipher-block chaining mode (CBC), with the addition of a -cyclical redundancy check (CRC-32) for integrity checking upon -decryption. - -The functions have the same signatures as those described by the main -library document; the names are: -{\obeylines -\funcname{mit_des_encrypt_func} -\funcname{mit_des_decrypt_func} -\funcname{mit_des_process_key} -\funcname{mit_des_finish_key} -\funcname{mit_des_string_to_key} -\funcname{mit_des_init_random_key} -\funcname{mit_des_finish_random_key} -\funcname{mit_des_random_key} -} -The \datatype{krb5_cryptosystem_entry} for this cryptosystem is -\globalname{mit_des_cryptosystem_entry}. - -\end{document} diff --git a/doc/api/libos.tex b/doc/api/libos.tex deleted file mode 100644 index 901c74643..000000000 --- a/doc/api/libos.tex +++ /dev/null @@ -1,382 +0,0 @@ -The operating-system specific functions provide an interface between the -other parts of the \libname{libkrb5.a} libraries and the operating system. - -Beware! Any of the functions below are allowed to be implemented as -macros. Prototypes for functions can be found in {\tt -}; other definitions (including macros, if used) are -in {\tt }. - -The following global symbols are provided in \libname{libos.a}. If you -wish to substitute for any of them, you must substitute for all of them -(they are all declared and initialized in the same object file): -\begin{description} -% These come from src/lib/osconfig.c -\item[extern char *\globalname{krb5_config_file}:] name of configuration file -\item[extern char *\globalname{krb5_trans_file}:] name of hostname/realm -name translation file -\item[extern char *\globalname{krb5_defkeyname}:] default name of key -table file -\item[extern char *\globalname{krb5_lname_file}:] name of aname/lname -translation database -\item[extern int \globalname{krb5_max_dgram_size}:] maximum allowable -datagram size -\item[extern int \globalname{krb5_max_skdc_timeout}:] maximum -per-message KDC reply timeout -\item[extern int \globalname{krb5_skdc_timeout_shift}:] shift factor -(bits) to exponentially back-off the KDC timeouts -\item[extern int \globalname{krb5_skdc_timeout_1}:] initial KDC timeout -\item[extern char *\globalname{krb5_kdc_udp_portname}:] name of KDC UDP port -\item[extern char *\globalname{krb5_default_pwd_prompt1}:] first prompt -for password reading. -\item[extern char *\globalname{krb5_default_pwd_prompt2}:] second prompt - -\end{description} - -\begin{funcdecl}{krb5_read_password}{krb5_error_code}{\funcin} -\funcarg{char *}{prompt} -\funcarg{char *}{prompt2} -\funcout -\funcarg{char *}{return_pwd} -\funcinout -\funcarg{int *}{size_return} -\end{funcdecl} - -Read a password from the keyboard. The first \funcparam{*size_return} -bytes of the password entered are returned in \funcparam{return_pwd}. -If fewer than \funcparam{*size_return} bytes are typed as a password, -the remainder of \funcparam{return_pwd} is zeroed. Upon success, the -total number of bytes filled in is stored in \funcparam{*size_return}. - -\funcparam{prompt} is used as the prompt for the first reading of a password. -It is printed to the terminal, and then a password is read from the -keyboard. No newline or spaces are emitted between the prompt and the -cursor, unless the newline/space is included in the prompt. - -If \funcparam{prompt2} is a null pointer, then the password is read -once. If \funcparam{prompt2} is set, then it is used as a prompt to -read another password in the same manner as described for -\funcparam{prompt}. After the second password is read, the two -passwords are compared, and an error is returned if they are not -identical. - -Echoing is turned off when the password is read. - -If there is an error in reading or verifying the password, an error code -is returned; else zero is returned. - -\begin{funcdecl}{krb5_lock_file}{krb5_error_code}{\funcvoid} -\funcarg{FILE *}{filep} -\funcarg{char *}{pathname} -\funcarg{int}{mode} -\end{funcdecl} - -Attempts to lock the file in the given \funcparam{mode}; returns 0 for a -successful lock, or an error code otherwise. - -The caller should arrange that both \funcparam{filep} and -\funcparam{pathname} refer to the same -file. The implementation may use whichever is more convenient. - -Modes are given in {\tt } - - -\begin{funcdecl}{krb5_unlock_file}{krb5_error_code}{\funcvoid} -\funcarg{FILE *}{filep} -\funcarg{char *}{pathname} -\end{funcdecl} - -Attempts to (completely) unlock the file. Returns 0 if successful, -or an error code otherwise. - -The caller should arrange that both \funcparam{filep} and -\funcparam{pathname} refer to the same file. The implementation may -use whichever is more convenient. - -\begin{funcdecl}{krb5_create_secure_file}{krb5_error_code}{\funcin} -\funcarg{const char *}{pathname} -\end{funcdecl} - -Creates a file named pathname which can only be read by the current -user. - -\begin{funcdecl}{krb5_sync_disk_file}{krb5_error_code}{\funcin} -\funcarg{FILE *}{fp} -\end{funcdecl} - -Assures that the changes made to the file pointed to by the file -handle -fp are forced out to disk. - -\begin{funcdecl}{krb5_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{timeret} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -\begin{funcdecl}{krb5_us_timeofday}{krb5_error_code}{\funcout} -\funcarg{krb5_int32 *}{seconds} -\funcarg{krb5_int32 *}{microseconds} -\end{funcdecl} - -Retrieves the system time of day, in seconds since the local system's -epoch. -[The ASN.1 encoding routines must convert this to the standard ASN.1 -encoding as needed] - -The seconds portion is returned in \funcparam{*seconds}, the -microseconds portion in \funcparam{*microseconds}. - -\begin{funcdecl}{krb5_net_read}{int}{\funcin} -\funcarg{int}{fd} -\funcout -\funcarg{char *}{buf} -\funcin -\funcarg{int}{len} -\end{funcdecl} - -Like read(2), but guarantees that it reads as much as was requested -or returns -1 and sets errno. - -(make sure your sender will send all the stuff you are looking for!) -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_net_write}{int}{\funcin} -\funcarg{int}{fd} -\funcarg{const char *}{buf} -\funcarg{int}{len} -\end{funcdecl} - -Like write(2), but guarantees that it writes as much as was requested -or returns -1 and sets errno. - -Only useful on stream sockets and pipes. - -\begin{funcdecl}{krb5_write_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcarg{krb5_data *}{data} -\end{funcdecl} - - -\funcname{krb5_write_message} writes data to the network as a message, -using the network connection pointed to by \funcparam{fd}. - -\begin{funcdecl}{krb5_read_message}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{fd} -\funcout -\funcarg{krb5_data *}{data} -\end{funcdecl} - -Reads data from the network as a message, using the network connection -pointed to by fd. - -\begin{funcdecl}{krb5_os_localaddr}{krb5_error_code}{\funcout} -\funcarg{krb5_address ***}{addr} -\end{funcdecl} - -Return all the protocol addresses of this host. - -Compile-time configuration flags will indicate which protocol family -addresses might be returned. -\funcparam{*addr} is filled in to point to an array of address pointers, -terminated by a null pointer. All the storage pointed to is allocated -and should be freed by the caller with \funcname{krb5_free_address} -when no longer needed. - - -\begin{funcdecl}{krb5_sendto_kdc}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{send} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{krb5_data *}{receive} -\end{funcdecl} - -Send the message \funcparam{send} to a KDC for realm \funcparam{realm} and -return the response (if any) in \funcparam{receive}. - -If the message is sent and a response is received, 0 is returned, -otherwise an error code is returned. - -The storage for \funcparam{receive} is allocated and should be freed by -the caller when finished. - -\begin{funcdecl}{krb5_get_krbhst}{krb5_error_code}{\funcin} -\funcarg{const krb5_data *}{realm} -\funcout -\funcarg{char ***}{hostlist} -\end{funcdecl} - -Figures out the Kerberos server names for the given \funcparam{realm}, -filling in \funcparam{hostlist} with a null terminated array of -pointers to hostnames. - -If \funcparam{realm} is unknown, the filled-in pointer is set to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_krbhst}{krb5_error_code}{\funcin} -\funcarg{char * const *}{hostlist} -\end{funcdecl} - -Frees the storage taken by a host list returned by \funcname{krb5_get_krbhst}. - -\begin{funcdecl}{krb5_aname_to_localname}{krb5_error_code}{\funcin} -\funcarg{krb5_const_principal}{aname} -\funcarg{int}{lnsize} -\funcout -\funcarg{char *}{lname} -\end{funcdecl} - -Converts a principal name \funcparam{aname} to a local name suitable for use by -programs wishing a translation to an environment-specific name (e.g. -user account name). - -\funcparam{lnsize} specifies the maximum length name that is to be filled into -\funcparam{lname}. -The translation will be null terminated in all non-error returns. - -Returns system errors. - -\begin{funcdecl}{krb5_get_default_realm}{krb5_error_code} -\funcout -\funcarg{char **}{lrealm} -\end{funcdecl} - -Retrieves the default realm to be used if no user-specified realm is -available (e.g. to interpret a user-typed principal name with the -realm omitted for convenience), filling in \funcparam{lrealm} with a -pointer to the default realm in allocated storage. - -It is the caller's responsibility for freeing the allocated storage -pointed to be \funcparam{lream} when it is finished with it. - -Returns system errors. - -\begin{funcdecl}{krb5_get_host_realm}{krb5_error_code}{\funcin} -\funcarg{const char *}{host} -\funcout -\funcarg{char ***}{realmlist} -\end{funcdecl} - -Figures out the Kerberos realm names for \funcparam{host}, filling in -\funcparam{realmlist} with a -pointer to an argv[] style list of names, terminated with a null pointer. - -If \funcparam{host} is NULL, the local host's realms are determined. - -If there are no known realms for the host, the filled-in pointer is set -to NULL. - -The pointer array and strings pointed to are all in allocated storage, -and should be freed by the caller when finished. - -Returns system errors. - -\begin{funcdecl}{krb5_free_host_realm}{krb5_error_code}{\funcin} -\funcarg{char * const *}{realmlist} -\end{funcdecl} - -Frees the storage taken by a \funcparam{realmlist} returned by -\funcname{krb5_get_local_realm}. - -\begin{funcdecl}{krb5_kuserok}{krb5_boolean}{\funcin} -\funcarg{krb5_principal}{principal} -\funcarg{const char *}{luser} -\end{funcdecl} - -Given a Kerberos principal \funcparam{principal}, and a local username -\funcparam{luser}, -determine whether user is authorized to login to the account \funcparam{luser}. -Returns TRUE if authorized, FALSE if not authorized. - -\begin{funcdecl}{krb5_random_confounder}{krb5_error_code}{\funcin} -\funcarg{int}{size} -\funcout -\funcarg{krb5_pointer}{fillin} -\end{funcdecl} - -Given a length and a pointer, fills in the area pointed to by -\funcparam{fillin} with \funcparam{size} random octets suitable for use -in a confounder. - -\begin{funcdecl}{krb5_gen_portaddr}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{adr} -\funcarg{krb5_const_pointer}{ptr} -\funcout -\funcarg{krb5_address **}{outaddr} -\end{funcdecl} - -Given an address \funcparam{adr} and an additional address-type specific -portion pointed to by -\funcparam{port} this routine -combines them into a freshly-allocated -\datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} and fills in -\funcparam{*outaddr} to point to this address. For IP addresses, -\funcparam{ptr} should point to a network-byte-order TCP or UDP port -number. Upon success, \funcparam{*outaddr} will point to an allocated -address which should be freed with \funcname{krb5_free_address}. - -\begin{funcdecl}{krb5_gen_replay_name}{krb5_error_code}{\funcin} -\funcarg{const krb5_address *}{inaddr} -\funcarg{const char *}{uniq} -\funcout -\funcarg{char **}{string} -\end{funcdecl} - -Given a \datatype{krb5_address} with type \datatype{ADDRTYPE_ADDRPORT} -in \funcparam{inaddr}, this function unpacks its component address and -additional type, and uses them along with \funcparam{uniq} to allocate a -fresh string to represent the address and additional information. The -string is suitable for use as a replay cache tag. This string is -allocated and should be freed with \funcname{free} when the caller has -finished using it. When using IP addresses, the components in -\funcparam{inaddr{\ptsto}contents} must be of type -\datatype{ADDRTYPE_INET} and \datatype{ADDRTYPE_PORT}. - -% XXX Note that if the bug I sent in entitled ``krb5_gen_replay_name -% outputs char * when krb5_get_server_rcache expects krb5_data'' -% (OpenVision Cambridge bug number 1582) causes the code of this -% function to change, the documentation above will have to be updated. - -\begin{funcdecl}{krb5_sname_to_principal}{krb5_error_code}{\funcin} -\funcarg{const char *}{hostname} -\funcarg{const char *}{sname} -\funcarg{krb5_int32}{type} -\funcout -\funcarg{krb5_principal *}{ret_princ} -\end{funcdecl} - -Given a hostname \funcparam{hostname} and a generic service name -\funcparam{sname}, this function generates a full principal name to be -used when authenticating with the named service on the host. The full -prinicpal name is returned in \funcparam{ret_princ}. - -The realm of the -principal is determined internally by calling \funcname{krb5_get_host_realm}. - -The \funcparam{type} argument controls how -\funcname{krb5_sname_to_principal} generates the principal name, -\funcparam{ret_princ}, for the named service, \funcparam{sname}. -Currently, two values are supported: KRB5_NT_SRV_HOST, and -KRB5_NT_UNKNOWN. - -If \funcparam{type} is set to -KRB5_NT_SRV_HOST, the hostname will be -canonicalized, i.e. a fully qualified lowercase hostname using -the primary name and the domain name, before \funcparam{ret_princ} is -generated in the form -"sname/hostname@LOCAL.REALM." Most applications should use -KRB5_NT_SRV_HOST. - -However, if \funcparam{type} is set to KRB5_NT_UNKNOWN, -while the generated principal name will have the form -"sname/hostname@LOCAL.REALM" the hostname will not be canonicalized -first. It will appear exactly as it was passed in \funcparam{hostname}. - -The caller should release \funcparam{ret_princ}'s storage by calling -\funcname{krb5_free_principal} when it is finished with the principal. diff --git a/doc/api/library.tex b/doc/api/library.tex deleted file mode 100644 index 213ef0176..000000000 --- a/doc/api/library.tex +++ /dev/null @@ -1,97 +0,0 @@ -\documentstyle[fixunder,functions,changebar,twoside,fancyheadings]{article} -%\setlength{\oddsidemargin}{1in} -%\setlength{\evensidemargin}{1.00in} -%\setlength{\textwidth}{6.5in} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{1.50in} -\setlength{\textwidth}{5.25in} -\setlength{\marginparsep}{0.0in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse if not draft...)} -\ifdraft -\pagestyle{fancyplain} -\addtolength{\headwidth}{\marginparsep} -\addtolength{\headwidth}{\marginparwidth} -\makeatletter -\renewcommand{\sectionmark}[1]{\markboth {\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection\hskip 1em\relax \fi #1}}{}}% -\renewcommand{\subsectionmark}[1]{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi #1}} -\makeatother -\lhead[\thepage]{\fancyplain{}{\sl\rightmark}} -\rhead[\fancyplain{}{\sl\rightmark}]{\thepage} -\lfoot[]{{\bf DRAFT---DO NOT REDISTRIBUTE}} -\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{} -\cfoot{\thepage} -\else\pagestyle{headings}\fi - -%nlg- time to make this a real document - -\title{\Huge Kerberos V5 application programming library} -\date{\ifdraft \\ {\Large DRAFT---}\fi\today} -\author{MIT Information Systems} - -\begin{document} -\maketitle -\tableofcontents - -%\thispagestyle{empty} -%\begin{center} -%{\Huge Kerberos V5 application programming library} -%\ifdraft \\ {\Large DRAFT---\today}\fi -%\end{center} - -\section{Introduction} -\input{intro.tex} - -\section{Useful KDC parameters to know about} -\input{tables.tex} - -\section{Error tables} -\input{errors.tex} - -%\addtolength{\oddsidemargin}{-1in} -%\addtolength{\evensidemargin}{1.00in} -%\addtolength{\textwidth}{-1.75in} -\newpage - -\section{libkrb5.a functions} -This section describes the functions provided in the \libname{libkrb5.a} -library. The library is built from several pieces, mostly for convenience in -programming, maintenance, and porting. - -\ifdraft\sloppy\fi - -\subsection{Main functions} -\input{krb5.tex} - -\section{Credentials cache functions} -\input{ccache.tex} - -\section{Replay cache functions} -\input{rcache.tex} - -\section{Key table functions} -\input{keytab.tex} - -\section{Operating-system specific functions} -\input{libos.tex} - -\appendix -\cleardoublepage -\input{\jobname.ind} -\end{document} diff --git a/doc/api/rcache.tex b/doc/api/rcache.tex deleted file mode 100644 index b9ef1977a..000000000 --- a/doc/api/rcache.tex +++ /dev/null @@ -1,152 +0,0 @@ -The replay cache functions deal with verifying that AP_REQ's do not -contain duplicate authenticators; the storage must be non-volatile for -the site-determined validity period of authenticators. - -Each replay cache has a string ``name'' associated with it. The use of -this name is dependent on the underlying caching strategy (for -file-based things, it would be a cache file name). The -caching strategy uses non-volatile storage so that replay -integrity can be maintained across system failures. - -\begin{funcdecl}{krb5_rc_resolve_full}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache *}{id} -\funcin -\funcarg{char *}{string_name} -\end{funcdecl} - -\funcparam{id} is filled in to identify a replay cache which -corresponds to the name in \funcparam{string_name}. The cache is not opened. -Requires that \funcparam{string_name} be of the form ``type:residual'' -and that ``type'' is a type known to the library. - -Before the cache can be used \funcname{krb5_rc_initialize} or -\funcname{krb5_rc_recover} must be called. - -Errors: error if cannot resolve name. - -\begin{funcdecl}{krb5_rc_register_type}{krb5_error_code}{\funcin} -\funcarg{krb5_rc_ops *}{ops} -\end{funcdecl} -Adds a new replay cache type implemented and identified by -\funcparam{ops} to the set recognized by -\funcname{krb5_rc_resolve}. This function requires that a ticket -cache of the type named in -\funcparam{ops{\ptsto}prefix} has not been previously registered. - - -\begin{funcdecl}{krb5_rc_default_name}{char *}{\funcvoid} -\end{funcdecl} -Returns the name of the default replay cache; this may be equivalent to -\funcnamenoparens{getenv}({\tt "KRB5RCACHE"}) with an appropriate fallback. - -\begin{funcdecl}{krb5_rc_default_type}{char *}{\funcvoid} -\end{funcdecl} - -Returns the type of the default replay cache. - -\begin{funcdecl}{krb5_rc_default}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache *}{id} -\end{funcdecl} - -This function returns an unopened replay cache of the default type and -default name (as would be returned by \funcname{krb5_rc_default_type} -and \funcname{krb5_rc_default_name}). Before the cache can be used -\funcname{krb5_rc_initialize} or \funcname{krb5_rc_recover} must be -called. - - -\begin{funcdecl}{krb5_rc_initialize}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_deltat}{auth_lifespan} -\end{funcdecl} - -Creates/refreshes the replay cache identified by \funcparam{id} and sets its -authenticator lifespan to \funcparam{auth_lifespan}. If the -replay cache already exists, its contents are destroyed. - -Errors: permission errors, system errors - -\begin{funcdecl}{krb5_rc_recover}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Attempts to recover the replay cache \funcparam{id}, (presumably after a -system crash or server restart). - -Errors: error indicating that no cache was found to recover - -\begin{funcdecl}{krb5_rc_destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Destroys the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Errors: permission errors. - -\begin{funcdecl}{krb5_rc_close}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Closes the replay cache \funcparam{id}, invalidates \funcparam{id}, -and releases any other resources acquired during use of the replay cache. -Requires that \funcparam{id} identifies a valid replay cache. - -Errors: permission errors - -\begin{funcdecl}{krb5_rc_store}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the -cache. May also return permission errors, storage failure errors. - -\begin{funcdecl}{krb5_rc_expunge}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Removes all expired replay information (i.e. those entries which are -older than then authenticator lifespan of the cache) from the cache -\funcparam{id}. Requires that \funcparam{id} identifies a valid replay -cache. - -Errors: permission errors. - -\begin{funcdecl}{krb5_rc_get_lifespan}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcout -\funcarg{krb5_deltat *}{auth_lifespan} -\end{funcdecl} -Fills in \funcparam{auth_lifespan} with the lifespan of -the cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -\begin{funcdecl}{krb5_rc_resolve}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache}{id} -\funcin -\funcarg{char *}{name} -\end{funcdecl} - -Initializes private data attached to \funcparam{id}. This function MUST -be called before the other per-replay cache functions. - -Requires that \funcparam{id} points to allocated space, with an -initialized \funcparam{id{\ptsto}ops} field. - -Since \funcname{krb5_rc_resolve} allocates memory, -\funcname{krb5_rc_close} must be called to free the allocated memory, -even if neither \funcname{krb5_rc_initialize} or -\funcname{krb5_rc_recover} were successfully called by the application. - -Returns: allocation errors. - - -\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Returns the name (excluding the type) of the rcache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - - diff --git a/doc/api/tables.tex b/doc/api/tables.tex deleted file mode 100644 index 23e6c952a..000000000 --- a/doc/api/tables.tex +++ /dev/null @@ -1,79 +0,0 @@ -The following is a list of options which can be passed to the Kerberos -server (also known as the Key Distribution Center or KDC). These -options affect what sort of tickets the KDC will return to the -application program. The KDC options can be passed to -\funcname{krb5_get_in_tkt}, \funcname{krb5_get_in_tkt_with_password}, -\funcname{krb5_get_in_tkt_with_skey}, and \funcname{krb5_send_tgs}. - - -\begin{center} -\begin{tabular}{llc} -\multicolumn{1}{c}{Symbol}&\multicolumn{1}{c}{RFC}& Valid for \\ -&\multicolumn{1}{c}{section}&get_in_tkt? \\ \hline -KDC_OPT_FORWARDABLE & 2.6 & yes \\ -KDC_OPT_FORWARDED & 2.6 & \\ -KDC_OPT_PROXIABLE & 2.5 & yes \\ -KDC_OPT_PROXY & 2.5 & \\ -KDC_OPT_ALLOW_POSTDATE & 2.4 & yes \\ -KDC_OPT_POSTDATED & 2.4 & yes \\ -KDC_OPT_RENEWABLE & 2.3 & yes \\ -KDC_OPT_RENEWABLE_OK & 2.7 & yes \\ -KDC_OPT_ENC_TKT_IN_SKEY & 2.7 & \\ -KDC_OPT_RENEW & 2.3 & \\ -KDC_OPT_VALIDATE & 2.2 & \\ -\end{tabular} -\end{center} -\label{KDCOptions} - -The following is a list of preauthentication methods which are supported -by Kerberos. Most preauthentication methods are used by -krb5_get_in_tkt(), krb5_get_in_tkt_with_password(), and -krb5_get_in_tkt_with_skey(); at some sites, the Kerberos server can be -configured so that during the initial ticket transation, it will only -return encrypted tickets after the user has proven his or her identity -using a supported preauthentication mechanism. This is done to make -certain password guessing attacks more difficult to carry out. - - - -\begin{center} -\begin{tabular}{lcc} -\multicolumn{1}{c}{Symbol}&In & Valid for \\ -&RFC?&get_in_tkt? \\ \hline -KRB5_PADATA_NONE & yes & yes \\ -KRB5_PADATA_AP_REQ & yes & \\ -KRB5_PADATA_TGS_REQ & yes & \\ -KRB5_PADATA_PW_SALT & yes & \\ -KRB5_PADATA_ENC_TIMESTAMP & yes & yes \\ -KRB5_PADATA_ENC_SECURID & & yes \\ -\end{tabular} -\end{center} -\label{padata-types} - -KRB5_PADATA_TGS_REQ is rarely used by a programmer; it is used to pass -the ticket granting ticket to the Ticket Granting Service (TGS) during a -TGS transaction (as opposed to an initial ticket transaction). - -KRB5_PW_SALT is not really a preauthentication method at all. It is -passed back from the Kerberos server to application program, and it -contains a hint to the proper password salting algorithm which should be -used during the initial ticket exchange. - -%The encription type can also be specified in -%\funcname{krb5_get_in_tkt}, however normally only one keytype is used -%in any one database. -% -%\begin{center} -%\begin{tabular}{llc} -%\multicolumn{1}{c}{Symbol}&\multicolumn{1}{c}{RFC}& Supported? \\ -%& \multicolumn{1}{c}{section} & \\ \hline -%ETYPE_NULL & 6.3.1 & \\ -%ETYPE_DES_CBC_CRC & 6.3.2 & yes \\ -%ETYPE_DES_CBC_MD4 & 6.3.3 & \\ -%ETYPE_DES_CBC_MD5 & 6.3.4 & \\ -%ETYPE_RAW_DES_CBC & & yes \\ -%\end{tabular} -%\end{center} -%\label{etypes} - - diff --git a/doc/implement/Makefile b/doc/implement/Makefile deleted file mode 100644 index 50916ba5d..000000000 --- a/doc/implement/Makefile +++ /dev/null @@ -1,26 +0,0 @@ -.SUFFIXES: .tex .dvi .ps - -STYLES=changebar.sty fixunder.sty functions.sty -LIBTEX= implement.tex ccache-i.tex rcache-i.tex keytab-i.tex libos-i.tex \ - kdb-i.tex encrypt-i.tex cksum-i.tex crc-32-i.tex implement.ind - - -all: implement.ps - - -implement.ps: implement.dvi - -# hard to capture two-pass semantics in Makefiles... -# implement.ind: implement.dvi -implement.ind: implement.idx - index implement.idx - -implement.dvi: $(LIBTEX) $(STYLES) - -.tex.dvi: - latex $* - - -.dvi.ps: - dvips $*.dvi -o - diff --git a/doc/implement/ccache-i.tex b/doc/implement/ccache-i.tex deleted file mode 100644 index bff804f96..000000000 --- a/doc/implement/ccache-i.tex +++ /dev/null @@ -1,224 +0,0 @@ -The credentials cache functions (some of which are macros which call to -specific types of credentials caches) deal with storing credentials -(tickets, session keys, and other identifying information) in a -semi-permanent store for later use by different programs. - -\subsubsection{The krb5_cc_ops structure} -In order to implement a new credentials cache type, the programmer should -declare a {\bf krb5_cc_ops} structure, and fill in the elements of the -structure appropriately, by implementing each of the credential cache -functions for the new credentials cache type. - -The prefix element specifies the prefix name of the the new credential -cache type. For example, if the prefix name is ``FILE'', then if the -program calls \funcname{krb5_cc_resolve} with a credential cache name -such as ``FILE:/tmp/krb5_cc_15806'', then \funcname{krb5_cc_resolve} -will call the resolve function (as defined by the {\bf krb5_cc_ops} -structure where the prefix element is ``FILE'') and pass it the -argument ``/tmp/krb5_cc_15806''. - -Before a new credentials cache type can be recognized by -\funcname{krb5_cc_resolve}, it must be registered with the Kerberos -library by calling \funcname{krb5_cc_register}. - -\begin{verbatim} -typedef struct _krb5_cc_ops { - char *prefix; - char *(*get_name)((krb5_ccache)); - krb5_error_code (*resolve)((krb5_ccache *, char *)); - krb5_error_code (*gen_new)((krb5_ccache *)); - krb5_error_code (*init)((krb5_ccache, krb5_principal)); - krb5_error_code (*destroy)((krb5_ccache)); - krb5_error_code (*close)((krb5_ccache)); - krb5_error_code (*store)((krb5_ccache, krb5_creds *)); - krb5_error_code (*retrieve)((krb5_ccache, krb5_flags, - krb5_creds *, krb5_creds *)); - krb5_error_code (*get_princ)((krb5_ccache, - krb5_principal *)); - krb5_error_code (*get_first)((krb5_ccache, - krb5_cc_cursor *)); - krb5_error_code (*get_next)((krb5_ccache, krb5_cc_cursor *, - krb5_creds *)); - krb5_error_code (*end_get)((krb5_ccache, krb5_cc_cursor *)); - krb5_error_code (*remove_cred)((krb5_ccache, krb5_flags, - krb5_creds *)); - krb5_error_code (*set_flags)((krb5_ccache, krb5_flags)); -} krb5_cc_ops; -\end{verbatim} - - -\subsubsection{Per-type functions} -The following entry points must be implemented for each type of -credentials cache. However, \funcname{resolve} and -\funcname{gen_new} are only called by the credentials cache glue code. -They are not called directly by the application. - - -\begin{funcdecl}{resolve}{krb5_error_code}{\funcout} -\funcarg{krb5_ccache *}{id} -\funcin -\funcarg{char *}{residual} -\end{funcdecl} - -Creates a credentials cache named by \funcparam{residual} (which may be -interpreted differently by each type of ccache). The cache is not -opened, but the cache name is held in reserve. - -\begin{funcdecl}{gen_new}{krb5_error_code}{\funcout} -\funcarg{krb5_ccache *}{id} -\end{funcdecl} - -Creates a new credentials cache whose name is guaranteed to be -unique. The cache is not opened. \funcparam{*id} is -filled in with a \datatype{krb5_ccache} which may be used in subsequent -calls to ccache functions. - -\begin{funcdecl}{init}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\funcin -\funcarg{krb5_principal}{primary_principal} -\end{funcdecl} - -Creates/refreshes a credentials cache identified by \funcparam{id} with -primary principal set to \funcparam{primary_principal}. -If the credentials cache already exists, its contents are destroyed. - -%Errors: permission errors, system errors. - -Modifies: cache identified by \funcparam{id}. - -\begin{funcdecl}{destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Destroys the credentials cache identified by \funcparam{id}, invalidates -\funcparam{id}, and releases any other resources acquired during use of -the credentials cache. Requires that \funcparam{id} identifies a valid -credentials cache. After return, \funcparam{id} must not be used unless -it is first reinitialized. - -%Errors: permission errors. - -\begin{funcdecl}{close}{krb5_error_code}{\funcinout} -\funcarg{krb5_ccache}{id} -\end{funcdecl} - -Closes the credentials cache \funcparam{id}, invalidates -\funcparam{id}, and releases \funcparam{id} and any other resources -acquired during use of the credentials cache. Requires that -\funcparam{id} identifies a valid credentials cache. After return, -\funcparam{id} must not be used unless it is first reinitialized. - - -\begin{funcdecl}{store}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Stores \funcparam{creds} in the cache \funcparam{id}, tagged with -\funcparam{creds{\ptsto}client}. -Requires that \funcparam{id} identifies a valid credentials cache. - -%Errors: permission errors, storage failure errors. - -\begin{funcdecl}{retrieve}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{whichfields} -\funcarg{krb5_creds *}{mcreds} -\funcout -\funcarg{krb5_creds *}{creds} -\end{funcdecl} - -Searches the cache \funcparam{id} for credentials matching -\funcparam{mcreds}. The fields which are to be matched are specified by -set bits in \funcparam{whichfields}, and always include the principal -name \funcparam{mcreds{\ptsto}server}. -Requires that \funcparam{id} identifies a valid credentials cache. - -If at least one match is found, one of the matching credentials is -returned in \funcparam{*creds}. The credentials should be freed using -\funcname{krb5_free_credentials}. - -%Errors: error code if no matches found. - -\begin{funcdecl}{get_princ}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Retrieves the primary principal of the credentials cache (as -set by the \funcname{init} request) -The primary principal is filled into \funcparam{*principal}; the caller -should release this memory by calling \funcname{krb5_free_principal} on -\funcparam{*principal} when finished. - -Requires that \funcparam{id} identifies a valid credentials cache. - -\begin{funcdecl}{get_first}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Prepares to sequentially read every set of cached credentials. -Requires that \funcparam{id} identifies a valid credentials cache opened by -\funcname{krb5_cc_open}. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{get_next}. - -\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcout -\funcarg{krb5_creds *}{creds} -\funcinout -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Fetches the next entry from \funcparam{id}, returning its values in -\funcparam{*creds}, and updates \funcparam{*cursor} for the next request. -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{get_first} or a subsequent call to -\funcname{get_next}. - -%Errors: error code if no more cache entries. - -\begin{funcdecl}{end_get}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_cc_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{*cursor}. -\funcparam{*cursor} must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid credentials cache and -\funcparam{*cursor} be a cursor returned by -\funcname{get_first} or a subsequent call to -\funcname{get_next}. - -%Errors: may return error code if \funcparam{*cursor} is invalid. - - -\begin{funcdecl}{remove_cred}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{which} -\funcarg{krb5_creds *}{cred} -\end{funcdecl} - -Removes any credentials from \funcparam{id} which match the principal -name {cred{\ptsto}server} and the fields in \funcparam{cred} masked by -\funcparam{which}. -Requires that \funcparam{id} identifies a valid credentials cache. - -%Errors: returns error code if nothing matches; returns error code if -couldn't delete. - -\begin{funcdecl}{set_flags}{krb5_error_code}{\funcin} -\funcarg{krb5_ccache}{id} -\funcarg{krb5_flags}{flags} -\end{funcdecl} - -Sets the flags on the cache \funcparam{id} to \funcparam{flags}. Useful -flags are defined in {\tt }. - - diff --git a/doc/implement/changebar.sty b/doc/implement/changebar.sty deleted file mode 100644 index 61b7383f9..000000000 --- a/doc/implement/changebar.sty +++ /dev/null @@ -1,155 +0,0 @@ -% Change bar document-style option for LaTeX. -% -% Copyright (C) 1990 by David B. Johnson. - -% These macros draw a solid bar down the right margin of the output, -% covering a range of the input file that has been declared to be changed. -% -% The beginning and end of a change bar in the text are marked with -% \chgbarbegin and \chgbarend, respectively. For example, -% -% Here is some sample text \chgbarbegin that was -% changed\chgbarend{} and some that wasn't changed. -% -% The change bar is drawn continuously between the line of output -% containing the \chgbarbegin and the line of output containing the -% \chgbarend. These lines can end up on separate pages, and the -% division at page boundaries is handled automatically. - -% Two dimensions control the size and placement of the change bars: -% \chgbarwidth The width of a change bar -% \chgbarsep The distance between the text and the change bar - -% Warning: it does not appear to be possible to do this completely -% correctly, due to the time at which the verticle glue on a page is -% finally set, and the way that page breaks are decided. With -% \raggedbottom, this normally works fine. It hasn't been tested with -% \flushbottom, but will probably behave worse. In strange rare -% situations, a change bar might be drawn from the first line of a page -% up off the top of a page; this can usually be fixed by slightly moving -% the \chngbarend around, or by breaking a single change bar range -% into two ranges. - -\newdimen\chgbarwidth \newdimen\chgbarsep -\chgbarwidth 4pt -\chgbarsep .25in - -\def\chgbarbegin{\ifhmode\@chgbar{-2}\else\@chgbar{-3}\fi} -\def\chgbarend{\@chgbar{-4}\relax} - -\marginparpush 0pt - -% The remainder of this is hacked up based on the LaTeX 2.09 latex.tex. - -% copied from \marginpar -\def\@chgbar#1{\ifhmode \@bsphack\@floatpenalty -\@Mii\else - \@floatpenalty-\@Miii\fi\ifinner - \@parmoderr\@floatpenalty\z@ - \else\@next\@currbox\@freelist{\global - \count\@currbox#1}{\@floatpenalty\z@ \@fltovf - \def\@currbox{\@tempboxa}}\fi - \setbox\@tempboxa\vbox - \bgroup\end@float\@esphack} - -\newdimen\@chgbarbegin -\newif\if@inchgbar \@inchgbarfalse - -\def\@addmarginpar{% -\ifnum\count\@currbox = -2 % change bar begin from hmode - \global\@chgbarbegin\@pageht \global\advance\@chgbarbegin -\baselineskip - \global\@inchgbartrue - \@cons\@freelist\@currbox -\else -\ifnum\count\@currbox = -3 % change bar begin not from hmode - \global\@chgbarbegin\@pageht - \global\@inchgbartrue - \@cons\@freelist\@currbox -\else -\ifnum\count\@currbox = -4 % change bar end - \if@inchgbar\else\@latexbug\fi - \@tempdima\@pageht \advance\@tempdima -\@chgbarbegin - \nointerlineskip - \@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\chgbarsep - \else \hskip -\chgbarsep \fi -\hbox{\vbox to 0pt{\vss - \hrule \@height\@tempdima \@width\chgbarwidth \@depth\z@ -}} -\hss} - \nointerlineskip - \global\@inchgbarfalse - \@cons\@freelist\@currbox -\else - \@next\@marbox\@currlist{\@cons\@freelist\@marbox - \@cons\@freelist\@currbox}\@latexbug\@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \ifnum\@tempcnta <\z@ \global\setbox\@marbox\box\@currbox \fi - \@tempdima\@mparbottom \advance\@tempdima -\@pageht - \advance\@tempdima\ht\@marbox \ifdim\@tempdima >\z@ - \@warning{Marginpar on page \thepage\space moved}\else\@tempdima\z@ \fi - \global\@mparbottom\@pageht \global\advance\@mparbottom\@tempdima - \global\advance\@mparbottom\dp\@marbox - \global\advance\@mparbottom\marginparpush - \advance\@tempdima -\ht\@marbox - \global\ht\@marbox\z@ \global\dp\@marbox\z@ - \vskip -\@pagedp \vskip\@tempdima\nointerlineskip - \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\marginparsep - \else \hskip -\marginparsep \hskip -\marginparwidth \fi - \box\@marbox \hss} - \vskip -\@tempdima - \nointerlineskip - \hbox{\vrule \@height\z@ \@width\z@ \@depth\@pagedp} -\fi\fi\fi} - -\def\@makecol{\setbox\@outputbox\box\@cclv - \if@inchgbar - \@tempcnta\@ne - \if@twocolumn - \if@firstcolumn \@tempcnta\m@ne \fi - \else - \if@mparswitch - \ifodd\c@page \else\@tempcnta\m@ne \fi - \fi - \if@reversemargin \@tempcnta -\@tempcnta \fi - \fi - \@tempdima\ht\@outputbox \advance\@tempdima -\@chgbarbegin - \advance\@tempdima -\baselineskip - \setbox\@outputbox - \vbox{\boxmaxdepth \maxdepth - \unvbox\@outputbox \nointerlineskip \hbox to\columnwidth - {\ifnum \@tempcnta >\z@ - \hskip\columnwidth \hskip\chgbarsep - \else \hskip -\chgbarsep \fi - \hbox{\vbox to 0pt{\vss - \hrule \@height\@tempdima \@width\chgbarwidth \@depth\z@}}\hss}} - \global\@chgbarbegin 0pt -\fi - \ifvoid\footins\else\setbox\@outputbox - \vbox{\boxmaxdepth \maxdepth - \unvbox\@outputbox\vskip\skip\footins\footnoterule\unvbox\footins}\fi - \xdef\@freelist{\@freelist\@midlist}\gdef\@midlist{}\@combinefloats - \setbox\@outputbox\vbox to\@colht{\boxmaxdepth\maxdepth - \@texttop\dimen128=\dp\@outputbox\unvbox\@outputbox - \vskip-\dimen128\@textbottom} - \global\maxdepth\@maxdepth} - -\newenvironment{changebar}{\chgbarbegin}{\chgbarend} diff --git a/doc/implement/cksum-i.tex b/doc/implement/cksum-i.tex deleted file mode 100644 index c7f763738..000000000 --- a/doc/implement/cksum-i.tex +++ /dev/null @@ -1,31 +0,0 @@ -Kerberos v5 has the ability to use multiple checksum algorithms. Any -checksum implementation which desires to link with and be usable from the MIT -Kerberos v5 implementation must implement this interface: - -\subsection{Functional interface} - -\begin{funcdecl}{sum_func}{krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{in} -\funcarg{size_t}{in_length} -\funcarg{krb5_pointer}{seed} -\funcarg{size_t}{seed_length} -\funcout -\funcarg{krb5_checksum *}{outcksum} -\end{funcdecl} - -This routine computes the desired checksum over \funcparam{in_length} bytes -at \funcparam{in}. \funcparam{seed_length} bytes of a seed (usually an -encryption key) are pointed to by \funcparam{seed}. Some checksum -algorithms may choose to ignore \funcparam{seed}. If -\funcparam{seed_length} is zero, then there is no seed available. -The routine places the resulting value into \funcparam{outcksum{\ptsto}contents}. - -\funcparam{outcksum{\ptsto}contents} must be set by the caller to point -to enough storage to contain the checksum; the size necessary is an -element of the \datatype{krb5_checksum_entry} structure. - -\subsection{Other data elements} -In addition to the above listed function entry point, each checksum algorithm -should have an entry in \globalname{krb5_cksumarray} and a -\datatype{krb5_checksum_entry} structure describing the entry points -and checksum size for the algorithm. diff --git a/doc/implement/crc-32-i.tex b/doc/implement/crc-32-i.tex deleted file mode 100644 index c5d07a33d..000000000 --- a/doc/implement/crc-32-i.tex +++ /dev/null @@ -1,20 +0,0 @@ -The \libname{libcrc32.a} library provides an implementation of the -CRC-32 checksum algorithm which conforms to the interface required by -the Kerberos library. - -\begin{funcdecl}{crc32_sum_func}{static krb5_error_code}{\funcin} -\funcarg{krb5_pointer}{in} -\funcarg{size_t}{in_length} -\funcarg{krb5_pointer}{seed} -\funcarg{size_t}{seed_length} -\funcout -\funcarg{krb5_checksum *}{outcksum} -\end{funcdecl} - -This routine computes a CRC-32 checksum over \funcparam{in_length} bytes -at \funcparam{in}, and places the resulting value into -\funcparam{outcksum{\ptsto}contents}. \funcparam{seed} is ignored. - -\funcparam{outcksum{\ptsto}contents} must be set by the caller to point -to at least 4 bytes of storage. - diff --git a/doc/implement/encrypt-i.tex b/doc/implement/encrypt-i.tex deleted file mode 100644 index 6e4b0ab44..000000000 --- a/doc/implement/encrypt-i.tex +++ /dev/null @@ -1,164 +0,0 @@ -Kerberos v5 has the ability to use multiple encryption systems. Any -encryption system which desires to link with and be usable from the MIT -Kerberos v5 implementation must implement at least this interface: - -\subsection{Functional interface} - -\begin{funcdecl}{encrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Encrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. \funcparam{eblock} points to an encrypt block which -has been initialized by \funcname{process_key}. - -\funcparam{in} must include sufficient space beyond the \funcparam{size} -bytes of input data to hold pad and redundancy check bytes; the macro -\funcname{krb5_encrypt_size} can be used to compute this size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; the macro \funcname{krb5_encrypt_size} can -be used to compute this size. - -\funcparam{ivec} points to an initial vector/seed to be used in the encryption. -If null, the cryptosystem may choose an appropriate initialization vector. - -%Errors: Returns errors. - -\begin{funcdecl}{decrypt_func}{krb5_error_code}{\funcvoid} -\funcarg{krb5_const_pointer}{in} -\funcarg{krb5_pointer}{out} -\funcarg{const size_t}{size} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_pointer}{ivec} -\end{funcdecl} -Decrypts \funcparam{size} bytes at \funcparam{in}, storing result in -\funcparam{out}. -\funcparam{eblock} points to an encrypt block which has been initialized -by \funcname{process_key}. - -\funcparam{size} must be a multiple of the encryption block size. - -\funcparam{out} must be preallocated by the caller to contain sufficient -storage to hold the output; this is guaranteed to be no more than -the input size. - -\funcparam{ivec} points to an initial vector/seed to be used in the decryption. -If null, the cryptosystem may choose an appropriate ivec. - -%Errors: Returns errors. - -\begin{funcdecl}{process_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{keyblock} -\end{funcdecl} -Does any necessary key preprocessing (such as computing key -schedules for DES). -\funcparam{eblock{\ptsto}crypto_entry} must be set by the caller; the -other elements of \funcparam{eblock} are to be assigned by this function. -[In particular, \funcparam{eblock{\ptsto}key} must be set by this -function if the key is needed in raw form by the encryption routine.] - -The caller may not move or reallocate \funcparam{keyblock} before calling -\funcname{finish_key} on \funcparam{eblock}. - -%Errors: Returns errors. - -\begin{funcdecl}{finish_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_encrypt_block *}{eblock} -\end{funcdecl} -Does any necessary clean-up on \funcparam{eblock} (such as releasing -resources held by \funcparam{eblock{\ptsto}priv}. - -%Errors: Returns errors. - -\begin{funcdecl}{string_to_key}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_keytype}{keytype} -\funcarg{krb5_keyblock *}{keyblock} -\funcarg{const krb5_data *}{data} -\funcarg{const krb5_data}{salt} -\end{funcdecl} -Converts the string pointed to by \funcparam{data} into an encryption key -of type \funcparam{keytype}. \funcparam{*keyblock} is filled in with -the key info; in particular, \funcparam{keyblock{\ptsto}contents} is to -be set to allocated storage. It is the responsibility of the caller to -release this storage when the generated key no longer needed. - -The routine may use \funcparam{salt} to seed or alter the conversion -algorithm. - -If the particular function called does not know how to make a -key of type \funcparam{keytype}, an error may be returned. - -%Errors: Returns errors. - -\begin{funcdecl}{init_random_key}{krb5_error_code}{\funcvoid} -\funcarg{const krb5_keyblock *}{seedblock} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Initialize the random key generator using the encryption key -\funcparam{seedblock} and allocating private sequence information, filling -in \funcparam{*seed} with the address of such information. -\funcparam{*seed} is to be passed to \funcname{random_key} to provide -sequence information. - -\begin{funcdecl}{finish_random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\end{funcdecl} - -Free any resources held by \funcparam{seed} and assigned by -\funcname{init_random_key}. - -\begin{funcdecl}{random_key}{krb5_error_code}{\funcvoid} -\funcarg{krb5_pointer *}{seed} -\funcarg{krb5_keyblock **}{keyblock} -\end{funcdecl} - -Generate a random encryption key, allocating storage for it and -filling in the keyblock address in \funcparam{*keyblock}. -When the caller has finished using the keyblock, he should call -\funcname{krb5_free_keyblock} to release its storage. - -\begin{funcdecl}{combine_keys}{krb5_error_code}{\funcin} -\funcarg{const krb5_keyblock *}{key1} -\funcarg{const krb5_keyblock *}{key2} -\funcout -\funcarg{krb5_keyblock **}{outkey} -\end{funcdecl} -Combine the two encryption keys \funcparam{key1} and \funcparam{key2} to -generate a new output key \funcparam{outkey}. \funcparam{outkey} is -filled in to point to the freshly-allocated key. When the caller is -finished using the \funcparam{*outkey}, it should be freed with -\funcname{krb5_free_keyblock}. - -\subsection{Other data elements} -In addition to the above listed function entry points, each encryption -system should have an entry in \globalname{krb5_csarray} and a -\datatype{krb5_cryptosystem_entry} structure describing the entry points -and key and padding sizes for the encryption system. - -\subsection{DES functions} -The DES functions conform to the encryption interface required by the -Kerberos version 5 library, and provide an encryption mechanism based on -the DES Cipher-block chaining mode (CBC), with the addition of a -cyclical redundancy check (CRC-32) for integrity checking upon -decryption. - -The functions have the same signatures as those described by the main -library document; the names are: -{\obeylines -\funcname{mit_des_encrypt_func} -\funcname{mit_des_decrypt_func} -\funcname{mit_des_process_key} -\funcname{mit_des_finish_key} -\funcname{mit_des_string_to_key} -\funcname{mit_des_init_random_key} -\funcname{mit_des_finish_random_key} -\funcname{mit_des_random_key} -} -The \datatype{krb5_cryptosystem_entry} for this cryptosystem is -\globalname{mit_des_cryptosystem_entry}. diff --git a/doc/implement/fixunder.sty b/doc/implement/fixunder.sty deleted file mode 100644 index b7ae58dbf..000000000 --- a/doc/implement/fixunder.sty +++ /dev/null @@ -1,48 +0,0 @@ -% fixunder.sty, 31 May 1990, John T. Kohl -% -% The contents of this file are in the public domain. -% -% -% play games with _ to make it active and to provide a reasonable _ -% character (from \tt in most cases), and a discretionary word-break point. - -% -% Some \makeunder... macros for convenience in setting catcodes. -% -\def\makeunderactive{\catcode`\_=\active\relax} -\def\makeunderother{\catcode`\_=12\relax} -\def\makeunderletter{\catcode`\_=11\relax} -\def\makeundernormal{\catcode`\_=8\relax} -\makeunderother -\def\cctwlunder{_} - -% -% The hair here is to allow things like \index to work reasonably with -% the new definition of underscore when the argument to index is part of -% a macro replacement and as such gets tokenized before \index is -% evaluated. -% [in the normal case at top-level, \index{foo_bar} works since \index -% does some hair to make _ into a reasonable character code, and \index -% does NOT use a macro expansion. If you have something like -% \def\foo#1#2{\index{#1} bar #2} -% then \foo{baz_quux}{frobnitz} will result in baz_quux getting -% tokenized BEFORE \foo is expanded, so that the catcode hair in \index -% is to no avail.] -% -% \underrealfalse declares that you want to replace with the \tt _; -% \underrealtrue declares that you want to replace with \char95 (ASCII _). -% -% for things like \index which write things out to files, set -% \underrealfalse before evaluating the \index macro, and what actually -% gets written to the file is an _, rather than something like -% {\leavemode \kern... } (the typical definition of \_). -% -% the above example would then be -% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2} -% - -\newif\ifunderreal -\underrealfalse -\makeunderactive -\def_{\ifunderreal\cctwlunder\else\leavevmode {\tt \cctwlunder}\discretionary{}{}{}\fi} -\let\_=_ diff --git a/doc/implement/functions.sty b/doc/implement/functions.sty deleted file mode 100644 index a3165f811..000000000 --- a/doc/implement/functions.sty +++ /dev/null @@ -1,70 +0,0 @@ -% -% definitions related to function declarations/displays -% -\ifx\undefined\@psfonts -\def\argfont{\tt} -\else -\font\argfont = pcrb -\hyphenchar\argfont = -1 -\fi -\let\funcfont=\bf -\newcount\argc@ount -%\setlength{\marginparsep}{0.05in} -%\setlength{\marginparwidth}{1.45in} -% -% This function fixes up the function name to be displayed in the -% margin so that the krb5_, if any, is stripped. -% -% Note: this is a hack; what's really happening is that name beginning with -% krb5 will have its first five characters stripped from it. -% This means that 'Krb5abc' will get rewritten to be 'bc'. -% Unfortunately, we can't do better because of the underscore -% hacks that are going on elsewhere. -% -% WARNING: This is ugly; don't look at it too soon after lunch! -% [tytso:19900920.2231EDT] -\newif\if@krbfunc -\def\endkrb{} -\def\fix@parname#1{\expandafter\parse@krb#1\endkrb% -\endkrb\endkrb\endkrb\endkrb}% In case the argument is less -% than five letters, we don't want to -% lose on the argument parsing. -\def\parse@krb#1#2#3#4#5#6\endkrb{\@krbfuncfalse% -\if#1k\if#2r\if#3b\if#45\@krbfunctrue\fi\fi\fi\fi% -\if@krbfunc#6\else#1#2#3#4#5#6\fi} -% -% funcdecl is used as \begin{funcdecl}{funcname}{return type}{firstline} -% -% see fixunder.sty for comments on why the \underrealtrue & \underrealfalse -% stuff is here. -\newenvironment{funcdecl}[3]{\underrealtrue\index{#1}\underrealfalse% -\medbreak -\gdef\funcn@me{#1} -\argc@ount=0\noindent% -%the \mbox{} is to prevent the line/paragraph breaking from eating the -%fill space. -\marginpar[{{\sloppy \hfil\fix@parname{\funcn@me}\hfill\mbox{}}}]% -{{\sloppy \hfill\fix@parname{\funcn@me}\hfil\mbox{}}}% -\vbox\bgroup\begin{minipage}[t]{\textwidth}\begin{tabbing} -#2 \\ -{\bf #1}(\= \+ #3% -}{) -\end{tabbing}\vfil\end{minipage}\egroup\par\nopagebreak -} -\newcommand{\docomm@}{\ifnum\argc@ount >0, \\\fi} -\newcommand{\funcvoid}{\argc@ount=0} -\newcommand{\funcin}{\docomm@\argc@ount=0{\sl /* IN */}\\} -\newcommand{\funcinout}{\docomm@\argc@ount=0{\sl /* IN/OUT */}\\} -\newcommand{\funcout}{\docomm@\argc@ount=0{\sl /* OUT */}\\} -\newcommand{\funcarg}[2]{\docomm@#1 {\argfont #2}\advance\argc@ount by1} -\newcommand{\funcparam}[1]{{\argfont #1}} -\newcommand{\funcfuncarg}[2]{\docomm@#1 {\argfont #2}(\= \+ \argc@ount=0} -\newcommand{\funcendfuncarg}{), \- \\ \argc@ount=0} -\newcommand{\libname}[1]{{\argfont #1}} -\newcommand{\globalname}[1]{{\argfont #1}} -\newcommand{\ptsto}{->\discretionary{}{}{}} -\newcommand{\datatype}[1]{{\bf #1}} -\newcommand{\filename}[1]{{\sl #1\/}} - -\newcommand{\funcname}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}()} -\newcommand{\funcnamenoparens}[1]{\underrealtrue\index{#1}\underrealfalse{\funcfont #1}} diff --git a/doc/implement/implement.tex b/doc/implement/implement.tex deleted file mode 100644 index 9aa62579a..000000000 --- a/doc/implement/implement.tex +++ /dev/null @@ -1,94 +0,0 @@ -\documentstyle[fixunder,functions,changebar,twoside,fancyheadings]{article} -\setlength{\oddsidemargin}{0in} -\setlength{\evensidemargin}{2.00in} -\setlength{\marginparsep}{0.05in} -\setlength{\marginparwidth}{1.95 in} -\setlength{\textwidth}{4.75in} -\setlength{\topmargin}{-.5in} -\setlength{\textheight}{9in} -\setlength{\parskip}{.1in} -\setlength{\parindent}{2em} -\setlength{\footrulewidth}{0.4pt} -\setlength{\plainfootrulewidth}{0.4pt} -\setlength{\plainheadrulewidth}{0.4pt} -\makeindex -\newif\ifdraft -\draftfalse -% -% Far, far too inconvenient... it's still very draft-like anyway.... -% [tytso:19900921.0018EDT] -% -%\typein{Draft flag? (type \noexpand\draftfalse if not draft...)} -\ifdraft -\pagestyle{fancyplain} -\addtolength{\headwidth}{\marginparsep} -\addtolength{\headwidth}{\marginparwidth} -\makeatletter -\renewcommand{\sectionmark}[1]{\markboth {\uppercase{\ifnum \c@secnumdepth >\z@ - \thesection\hskip 1em\relax \fi #1}}{}}% -\renewcommand{\subsectionmark}[1]{\markright {\ifnum \c@secnumdepth >\@ne - \thesubsection\hskip 1em\relax \fi #1}} -\makeatother -\lhead[\thepage]{\fancyplain{}{\sl\rightmark}} -\rhead[\fancyplain{}{\sl\rightmark}]{\thepage} -\lfoot[]{{\bf DRAFT---DO NOT REDISTRIBUTE}} -\rfoot[{\bf DRAFT---DO NOT REDISTRIBUTE}]{} -\cfoot{\thepage} -\else\pagestyle{headings}\fi - -%nlg- time to make this a real document - -\title{\Huge Kerberos V5 Implementer's Guide} -\date{\ifdraft \\ {\Large DRAFT---}\fi\today} -\author{MIT Information Systems} - -\begin{document} -\maketitle -\tableofcontents - -\section{Introduction} - - This document is designed to aide the programmer who plans to -change MIT's implementation of Kerberos significantly. It is geared towards -programmers who are already familiar with Kerberos and how MIT's -implementation is structured. - - Some of the more basic information needed can be found in the -API document, although many functions have been repeated where -additional information has been included for the implementer. The -function descriptions included are up to date, even if the description -of the functions may not be very verbose. - -\ifdraft\sloppy\fi - -\section{Cache and Key table functions} - -\subsection{Credentials cache functions} -\input{ccache-i.tex} - -\subsection{Replay cache functions} -\input{rcache-i.tex} - -\subsection{Key table functions} -\input{keytab-i.tex} - -\section{Operating-system specific functions} -\input{libos-i.tex} - -\section{Principal database functions} - -\input{kdb-i.tex} - -\section{Encryption system interface} -\input{encrypt-i.tex} - -\section{Checksum interface} -\input{cksum-i.tex} - -\section{CRC-32 checksum functions} -\input{crc-32-i.tex} - -\appendix -\cleardoublepage -\input{\jobname.ind} -\end{document} diff --git a/doc/implement/kdb-i.tex b/doc/implement/kdb-i.tex deleted file mode 100644 index dc81971bb..000000000 --- a/doc/implement/kdb-i.tex +++ /dev/null @@ -1,242 +0,0 @@ -The \libname{libkdb.a} library provides a principal database interface -to be used by the Key Distribution center and other database -manipulation tools. - - -\begin{funcdecl}{krb5_db_set_name}{krb5_error_code}{\funcin} -\funcarg{char *}{name} -\end{funcdecl} - -Set the name of the database to \funcparam{name}. -%Errors: If it doesn't exist, an error code is returned. - -Must be called before \funcname{krb5_db_init} or after -\funcname{krb5_db_fini}; must not be called while db functions are active. - -\begin{funcdecl}{krb5_db_set_nonblocking}{krb5_error_code}{\funcin} -\funcarg{krb5_boolean}{newmode} -\funcout -\funcarg{krb5_boolean *}{oldmode} -\end{funcdecl} - -Changes the locking mode of the database functions, returning the previous -mode in \funcparam{*oldmode}. - -If \funcparam{newmode} is TRUE, then the database is put into -non-blocking mode, which may result in ``database busy'' error codes from -the get, put, and iterate routines. - -If \funcparam{newmode} is FALSE, then the database is put into blocking mode, -which may result in delays from the get, put and iterate routines. - -The default database mode is blocking mode. - -\begin{funcdecl}{krb5_db_init}{krb5_error_code}{\funcvoid} -\end{funcdecl} - -Called before using \funcname{krb5_db_get_principal}, -\funcname{krb5_db_put_principal}, \funcname{krb5_db_iterate}, and -\funcname{krb5_db_set_nonblocking}. - -Does any required initialization. - -%Errors: init errors, system errors. - -\begin{funcdecl}{krb5_db_fini}{krb5_error_code}{\funcvoid} -\end{funcdecl} - -Called after all database operations are complete, to perform any required -clean-up. - -%Errors: sysytem errors. - - -\begin{funcdecl}{krb5_db_get_age}{krb5_error_code}{\funcin} -\funcarg{char *}{db_name} -\funcout -\funcarg{time_t *}{age} -\end{funcdecl} - -Retrieves the age of the database \funcname{db_name} (or the current -default database if \funcname{db_name} is NULL). - -\funcparam{*age} is filled in in local system time units, and represents -the last modification time of the database. - -%Errors: system errors. - - -\begin{funcdecl}{krb5_db_create}{krb5_error_code}{\funcin} -\funcarg{char *}{db_name} -\end{funcdecl} - -Creates a new database named \funcname{db_name}. Will not create a -database by that name if it already exists. The database must be -populated by the caller by using \funcname{krb5_db_put_principal}. - -%Errors: db exists, system errors. - -\begin{funcdecl}{krb5_db_rename}{krb5_error_code}{\funcin} -\funcarg{char *}{source} -\funcarg{char *}{dest} -\end{funcdecl} -Renames the database \funcarg{source} to \funcarg{dest} - -Any database named \funcarg{dest} is destroyed. - -%Errors: system errors. - -\begin{funcdecl}{krb5_db_get_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{searchfor} -\funcout -\funcarg{krb5_db_entry *}{entries} -\funcinout -\funcarg{int *}{nentries} -\funcout -\funcarg{krb5_boolean *}{more} -\end{funcdecl} - -Retrieves the principal records named by \funcparam{searchfor}. - -\funcparam{entries} must point to an array of \funcparam{*nentries} -krb5_db_entry structures. -At most \funcparam{*nentries} structures are filled in, and -\funcparam{*nentries} is modified to reflect the number actually returned. - -\funcparam{*nentries} must be at least one (1) when this function is called. - -\funcparam{*more} is set to TRUE if there are more records that wouldn't fit -in the available space, and FALSE otherwise. - -The principal structures filled in have pointers to allocated storage; -\funcname{krb5_db_free_principal} should be called with -\funcparam{entries} and \funcparam{*nentries} -in order to free this storage when no longer needed. - - -\begin{funcdecl}{krb5_db_free_principal}{void}{\funcin} -\funcarg{krb5_db_entry *}{entries} -\funcarg{int}{nentries} -\end{funcdecl} - -Frees allocated storage held by \funcparam{entries} as filled in by -\funcname{krb5_db_get_principal}. - - -\begin{funcdecl}{krb5_db_put_principal}{krb5_error_code}{\funcin} -\funcarg{krb5_db_entry *}{entries} -\funcarg{int *}{nentries} -\end{funcdecl} - -Stores the \funcparam{*nentries} principal structures pointed to by -\funcparam{entries} in the database. - -\funcparam{*nentries} is updated upon return to reflect the number of records -acutally stored; the first \funcparam{*nentries} records will have been -stored in the database. - -%Errors: Returns error code if not all entries were stored. - -\begin{funcdecl}{krb5_db_iterate}{krb5_error_code}{\funcin} -\funcfuncarg{krb5_error_code}{(*func)} -\funcarg{krb5_pointer}{} -\funcarg{krb5_db_entry *}{} -\funcendfuncarg -\funcarg{krb5_pointer}{iterate_arg} -\end{funcdecl} - -Iterates over the database, fetching every entry in an unspecified order -and calling \funcparam{(*func)}(\funcparam{iterate_arg}, -\funcparam{principal}) where \funcparam{principal} points to a record from the -database. - -If \funcparam{(*func)}() ever returns an error code, the iteration -should be -aborted and that error code is returned by this function. - -\begin{funcdecl}{krb5_db_store_mkey}{krb5_error_code}{\funcin} -\funcarg{char *}{keyfile} -\funcarg{krb5_principal}{mname} -\funcarg{krb5_keyblock *}{key} -\end{funcdecl} - -Put the KDC database master key into the file \funcparam{keyfile}. If -\funcparam{keyfile} is NULL, then a default file name derived from the -principal name \funcparam{mname} is used. - -\begin{funcdecl}{krb5_db_fetch_mkey}{krb5_error_code}{\funcin} -\funcarg{krb5_principal}{mname} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{krb5_boolean}{fromkeyboard} -\funcarg{krb5_boolean}{twice} -\funcarg{krb5_data }{salt} -\funcinout -\funcarg{krb5_keyblock *}{key} -\end{funcdecl} - -Get the KDC database master key from somewhere, filling it into -\funcparam{*key}. -\funcparam{key{\ptsto}keytype} should be set to the desired key type. - -If \funcparam{fromkeyboard} is TRUE, then the master key is read as a password -from the user's terminal. In this case: -\funcparam{eblock} should point to a block with an appropriate -\funcname{string_to_key} function; if \funcparam{twice} is TRUE, the -password is read twice for verification; and if \funcparam{salt} is -non-NULL, it is used as the salt when converting the typed -password to the master key. - - -If \funcparam{fromkeyboard} is false, then the key is read from -a file whose name is derived from the principal name \funcparam{mname}. -Therefore, \funcparam{eblock}, \funcparam{twice} and \funcparam{salt} -are ignored. - - -\funcparam{mname} is the name of the key sought; this is often used by -\funcname{string_to_key} to aid in conversion of the password to a key. - -\begin{funcdecl}{krb5_kdb_encrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_keyblock *}{in} -\funcinout -\funcarg{krb5_encrypted_keyblock *}{out} -\end{funcdecl} - -Encrypt a key for storage in the database. \funcparam{eblock} is used -to encrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_kdb_decrypt_key}{krb5_error_code}{\funcin} -\funcarg{krb5_encrypt_block *}{eblock} -\funcarg{const krb5_encrypted_keyblock *}{in} -\funcinout -\funcarg{krb5_keyblock *}{out} -\end{funcdecl} - -Decrypt a key from storage in the database. \funcparam{eblock} is used -to decrypt the key in \funcparam{in} into \funcparam{out}; the storage -pointed to by \funcparam{*out} is allocated before use and should be -freed when the caller is finished with it. - -\begin{funcdecl}{krb5_db_setup_mkey_name}{krb5_error_code}{\funcin} -\funcarg{const}{char *keyname} -\funcarg{const}{char *realm} -\funcout -\funcarg{char **}{fullname} -\funcarg{krb5_principal *}{principal} -\end{funcdecl} - -Given a key name \funcparam{keyname} and a realm name \funcparam{realm}, -construct a principal which can be used to fetch the master key from the -database. This principal is filled into \funcparam{*principal}; -\funcparam{*principal} should be freed by \funcname{krb5_free_principal} -when the caller is finished. - -If \funcparam{keyname} is NULL, the default key name will be used. - -If \funcparam{fullname} is not NULL, it is set to point to a string -representation of the complete principal name; its storage may be freed -by calling \funcname{free} on \funcparam{*fullname}. - diff --git a/doc/implement/keytab-i.tex b/doc/implement/keytab-i.tex deleted file mode 100644 index 697728721..000000000 --- a/doc/implement/keytab-i.tex +++ /dev/null @@ -1,204 +0,0 @@ -The key table functions deal with storing and retrieving service keys -for use by unattended services which participate in authentication exchanges. - -Keytab routines should all be atomic. Before a routine returns it -must make sure that all non-sharable resources it acquires are -released and in a consistent state. For example, an implementation is not -allowed to leave a file open for writing or to have a lock on a file. - -Note that all keytab implementations must support multiple concurrent -sequential scans. Another detail to note is that -the order of values returned from \funcname{get_next} is -unspecified and may be sorted to the implementor's convenience. - -\subsubsection{The krb5_kt_ops structure} -In order to implement a new key table type, the programmer should -declare a {\bf krb5_kt_ops} structure, and fill in the elements of the -structure appropriately, by implementing each of the key table -functions for the new key table type. - -In order to reduce the size of binary programs when static linking is -used, it is common to provide two \datatype{krb5_kt_ops} structures for -each key table type, one for reading only in which the pointers to the -add and delete functions are zero, and one for reading and writing. - -\begin{verbatim} -typedef struct _krb5_kt_ops { - char *prefix; - /* routines always present */ - krb5_error_code (*resolve)((char *, - krb5_keytab *)); - krb5_error_code (*get_name)((krb5_keytab, - char *, - int)); - krb5_error_code (*close)((krb5_keytab)); - krb5_error_code (*get)((krb5_keytab, - krb5_principal, - krb5_kvno, - krb5_keytab_entry *)); - krb5_error_code (*start_seq_get)((krb5_keytab, - krb5_kt_cursor *)); - krb5_error_code (*get_next)((krb5_keytab, - krb5_keytab_entry *, - krb5_kt_cursor *)); - krb5_error_code (*end_get)((krb5_keytab, - krb5_kt_cursor *)); - /* routines to be included on extended version (write routines) */ - krb5_error_code (*add)((krb5_keytab, - krb5_keytab_entry *)); - krb5_error_code (*remove)((krb5_keytab, - krb5_keytab_entry *)); -} krb5_kt_ops; -\end{verbatim} - -\subsubsection{Per-type functions that are always present} -The following entry points must be implemented for each type of -key table. However, \funcname{resolve}, \funcname{remove} and -\funcname{add} are only called by the key table glue code. -They are not called directly by the application. - - however, application programs are not expected to call -\funcname{resolve}, \funcname{remove}, -or \funcname{add} directly. - -\begin{funcdecl}{resolve}{krb5_error_code}{\funcin} -\funcarg{char *}{residual} -\funcout -\funcarg{krb5_keytab *}{id} -\end{funcdecl} - -Fills in \funcparam{*id} with a handle identifying the keytab with name -``residual''. The interpretation of ``residual'' is dependent on the -type of keytab. - -\begin{funcdecl}{get_name}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{char *}{name} -\funcin -\funcarg{int}{namesize} -\end{funcdecl} - -\funcarg{name} is filled in with the first \funcparam{namesize} bytes of -the name of the keytab identified by \funcname{id}. -If the name is shorter than \funcparam{namesize}, then \funcarg{name} -will be null-terminated. - -\begin{funcdecl}{close}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\end{funcdecl} - -Closes the keytab identified by \funcparam{id} and invalidates -\funcparam{id}, and releases any other resources acquired during use of -the key table. - -Requires that \funcparam{id} identifies a valid credentials cache. - -\begin{funcdecl}{get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_principal}{principal} -\funcarg{krb5_kvno}{vno} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Searches the keytab identified by \funcparam{id} for an entry whose -principal matches \funcparam{principal} and -whose key version number matches \funcparam{vno}. If \funcparam{vno} is -zero, the first entry whose principal matches is returned. - -%Errors: -This routine should return an error code if no suitable entry is -found. If an entry is found, the entry is returned in -\funcparam{*entry}; its contents should be deallocated by calling -\funcname{close} when no longer needed. - -\begin{funcdecl}{close}{krb5_error_code}{\funcinout} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Releases all storage allocated for \funcparam{entry}, which must point -to a structure previously filled in by \funcname{get} or -\funcname{get_next}. - -\begin{funcdecl}{start_seq_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Prepares to read sequentially every key in the keytab identified by -\funcparam{id}. -\funcparam{cursor} is filled in with a cursor to be used in calls to -\funcname{get_next}. - -\begin{funcdecl}{get_next}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcout -\funcarg{krb5_keytab_entry *}{entry} -\funcinout -\funcarg{krb5_kt_cursor}{cursor} -\end{funcdecl} - -Fetches the ``next'' entry in the keytab, returning it in -\funcparam{*entry}, and updates \funcparam{*cursor} for the next -request. If the keytab changes during the sequential get, an error -must be -%Errors: -guaranteed. \funcparam{*entry} should be freed after use by -calling -\funcname{close}. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{start_seq_get} or a subsequent call to -\funcname{get_next}. - -%Errors: error code if no more cache entries or if the keytab changes. - -\begin{funcdecl}{end_get}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_kt_cursor *}{cursor} -\end{funcdecl} - -Finishes sequential processing mode and invalidates \funcparam{cursor}, -which must never be re-used after this call. - -Requires that \funcparam{id} identifies a valid credentials cache. and -\funcparam{*cursor} be a cursor returned by -\funcname{start_seq_get} or a subsequent call to -\funcname{get_next}. - -%Errors: May return error code if \funcparam{cursor} is invalid. - -\subsubsection{Per-type functions to be included for write routines} - -\begin{funcdecl}{add}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Stores \funcparam{entry} in the keytab \funcparam{id}. -Fails if the entry already exists. - -This operation must, within the constraints of the operating system, not -return until it can verify that the write has completed succesfully. -For example, in a UNIX file-based implementation, this routine (or the part -of the underlying implementation that it calls) would be responsible for -doing an \funcname{fsync} on the file before returning. - -%Errors: -This routine should return an error code if \funcparam{entry} is -already present in the keytab or if the key could not be stored (quota -problem, etc). - -\begin{funcdecl}{remove}{krb5_error_code}{\funcin} -\funcarg{krb5_keytab}{id} -\funcarg{krb5_keytab_entry *}{entry} -\end{funcdecl} - -Searches the keytab \funcparam{id} for an entry that exactly matches -\funcparam{entry}. If one is found, it is removed from the keytab. - -%Errors: Returns an error code if not found. - diff --git a/doc/implement/libos-i.tex b/doc/implement/libos-i.tex deleted file mode 100644 index cdd4861ff..000000000 --- a/doc/implement/libos-i.tex +++ /dev/null @@ -1,34 +0,0 @@ -The operating-system specific functions provide an interface between the -other parts of the \libname{libkrb5.a} libraries and the operating system. - -Beware! Any of the functions below are allowed to be implemented as -macros. Prototypes for functions can be found in {\tt -}; other definitions (including macros, if used) are -in {\tt }. - -The following global symbols are provided in \libname{libos.a}. If you -wish to substitute for any of them, you must substitute for all of them -(they are all declared and initialized in the same object file): -\begin{description} -% These come from src/lib/osconfig.c -\item[extern char *\globalname{krb5_config_file}:] name of configuration file -\item[extern char *\globalname{krb5_trans_file}:] name of hostname/realm -name translation file -\item[extern char *\globalname{krb5_defkeyname}:] default name of key -table file -\item[extern char *\globalname{krb5_lname_file}:] name of aname/lname -translation database -\item[extern int \globalname{krb5_max_dgram_size}:] maximum allowable -datagram size -\item[extern int \globalname{krb5_max_skdc_timeout}:] maximum -per-message KDC reply timeout -\item[extern int \globalname{krb5_skdc_timeout_shift}:] shift factor -(bits) to exponentially back-off the KDC timeouts -\item[extern int \globalname{krb5_skdc_timeout_1}:] initial KDC timeout -\item[extern char *\globalname{krb5_kdc_udp_portname}:] name of KDC UDP port -\item[extern char *\globalname{krb5_default_pwd_prompt1}:] first prompt -for password reading. -\item[extern char *\globalname{krb5_default_pwd_prompt2}:] second prompt - -\end{description} - diff --git a/doc/implement/rcache-i.tex b/doc/implement/rcache-i.tex deleted file mode 100644 index e00a639da..000000000 --- a/doc/implement/rcache-i.tex +++ /dev/null @@ -1,142 +0,0 @@ -The replay cache functions deal with verifying that AP_REQ's do not -contain duplicate authenticators; the storage must be non-volatile for -the site-determined validity period of authenticators. - -Each replay cache has a string {\bf name} associated with it. The use of -this name is dependent on the underlying caching strategy (for -file-based things, it would be a cache file name). The -caching strategy should use non-volatile storage so that replay -integrity can be maintained across system failures. - -\subsubsection{The krb5_rc_ops structure} -In order to implement a new replay cache type, the programmer should -declare a {\bf krb5_rc_ops} structure, and fill in the elements of the -structure appropriately, by implementing each of the replay cache -functions for the new replay cache type. - -The prefix element specifies the prefix {bf name} of the the new replay -cache type. For example, if the prefix {\bf name} is ``dfl'', then if the -program calls \funcname{krb5_rc_resolve} with a credential cache name -such as ``dfl:host'', then \funcname{krb5_rc_resolve} -will call the resolve function (as defined by the {\bf krb5_rc_ops} -structure where the prefix element is ``dfl'') and pass it the -argument ``host''. - -Before a new replay cache type can be recognized by -\funcname{krb5_rc_resolve}, it must be registered with the Kerberos -library by calling \funcname{krb5_rc_register}. - -\begin{verbatim} -typedef struct _krb5_rc_ops { - char *type; - krb5_error_code (*init)((krb5_rcache,krb5_deltat)); - krb5_error_code (*recover)((krb5_rcache)); - krb5_error_code (*destroy)((krb5_rcache)); - krb5_error_code (*close)((krb5_rcache)); - krb5_error_code (*store)((krb5_rcache,krb5_donot_replay *)); - krb5_error_code (*expunge)((krb5_rcache)); - krb5_error_code (*get_span)((krb5_rcache,krb5_deltat *)); - char *(*get_name)((krb5_rcache)); - krb5_error_code (*resolve)((krb5_rcache, char *)); -} krb5_rc_ops; -\end{verbatim} - - -\subsubsection{Per-type functions} -The following entry points must be implemented for each type of -replay cache. - -\begin{funcdecl}{init}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_deltat}{auth_lifespan} -\end{funcdecl} - -Creates/refreshes the replay cache identified by \funcparam{id} and sets its -authenticator lifespan to \funcparam{auth_lifespan}. If the -replay cache already exists, its contents are destroyed. - -%Errors: permission errors, system errors - -\begin{funcdecl}{recover}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Attempts to recover the replay cache \funcparam{id}, (presumably after a -system crash or server restart). - -%Errors: error indicating that no cache was found to recover - -\begin{funcdecl}{destroy}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Destroys the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -%Errors: permission errors. - -\begin{funcdecl}{close}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Closes the replay cache \funcparam{id}, invalidates \funcparam{id}, -and releases any other resources acquired during use of the replay cache. -Requires that \funcparam{id} identifies a valid replay cache. - -%Errors: permission errors - -\begin{funcdecl}{store}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcarg{krb5_donot_replay *}{rep} -\end{funcdecl} -Stores \funcparam{rep} in the replay cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -Returns KRB5KRB_AP_ERR_REPEAT if \funcparam{rep} is already in the -cache. May also return permission errors, storage failure errors. - -\begin{funcdecl}{expunge}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} -Removes all expired replay information (i.e. those entries which are -older than then authenticator lifespan of the cache) from the cache -\funcparam{id}. Requires that \funcparam{id} identifies a valid replay -cache. - -%Errors: permission errors. - -\begin{funcdecl}{get_span}{krb5_error_code}{\funcin} -\funcarg{krb5_rcache}{id} -\funcout -\funcarg{krb5_deltat *}{auth_lifespan} -\end{funcdecl} -Fills in \funcparam{auth_lifespan} with the lifespan of -the cache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - -\begin{funcdecl}{resolve}{krb5_error_code}{\funcinout} -\funcarg{krb5_rcache}{id} -\funcin -\funcarg{char *}{name} -\end{funcdecl} - -Initializes private data attached to \funcparam{id}. This function MUST -be called before the other per-replay cache functions. - -Requires that \funcparam{id} points to allocated space, with an -initialized \funcparam{id{\ptsto}ops} field. - -Since \funcname{resolve} allocates memory, -\funcname{close} must be called to free the allocated memory, -even if neither \funcname{init} or -\funcname{recover} were successfully called by the application. - -%Returns: allocation errors. - - -\begin{funcdecl}{krb5_rc_get_name}{char *}{\funcin} -\funcarg{krb5_rcache}{id} -\end{funcdecl} - -Returns the name (excluding the type) of the rcache \funcparam{id}. -Requires that \funcparam{id} identifies a valid replay cache. - diff --git a/doc/kadm5/api-funcspec.tex b/doc/kadm5/api-funcspec.tex deleted file mode 100644 index 8b86a11a9..000000000 --- a/doc/kadm5/api-funcspec.tex +++ /dev/null @@ -1,1640 +0,0 @@ -\documentstyle[12pt,fullpage,changebar,rcsid]{article} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\rcs$Id$ - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\secure{OV*Secure} -\def\v#1{\verb+#1+} - -\title{OV*Secure Admin \\ Functional Specifications\thanks{\rcsId} \\ -\it{Openvision Confidential}} -\author{Barry Jaspan} - -\pagestyle{myheadings} -\markboth{OPENVISION CONFIDENTIAL}{OPENVISION CONFIDENTIAL} - -\begin{document} - -\sloppy -\maketitle - -{\setlength{\parskip}{0pt}\tableofcontents} - -\section{Policies and Password Quality} - -The Admin API Password Quality mechanism provides the following -controls. Note that two strings are defined to be ``significantly -different'' if they differ by at least one character. The compare is not -case sensitive. - -\begin{itemize} -\item A minimum length can be required; a password with -fewer than the specified number of characters will not be accepted. - -\item A minimum number of character classes can be required; a -password that does not contain at least one character from at least -the specified number of character classes will not be accepted. The -character classes are defined by islower(), isupper(), isdigit(), -ispunct(), and other. - -\item Passwords can be required to be different from -previous passwords; a password that generates the same encryption key -as any of the principal's specified previous number of passwords will -not be accepted. This comparison is performed on the encryption keys -generated from the passwords, not on the passwords themselves. - -\item A single ``forbidden password'' dictionary can be specified for all -users; a password that is not significantly different from every word -in the dictionary will not be accepted. -\end{itemize} - -\section{Multi-realm Operation} - -The behavior of any function when called with a principal name that is -not in the host's local realm is currently undefined. - -\section{Admin API requirements} - -\subsection{Versioning} - -The API will include a versioning system aimed at meeting the -following requirements: -\begin{description} -\item[R1] Admin API client applications will be source-code - compatible, whenever possible, with newer versions of the - Admin API. {\bf [high]} -\item[R2] Admin API client applications will be object-code and - shared-library compatible, whenever possible, with newer - versions of the Admin API. {\bf [low]} -\item[R3] Admin API client applications will be protocol compatible, - whenever possible, with newer versions of the Admin server. - I.e., a statically linked Admin API client application will be - able to talk to an Admin server from a later version of - Secure. {\bf [medium]} -\item[R4] Admin API client applications will be protocol compatible, - whenever possible, with older versions of the Admin server. - {\bf [lower than low]} -\item[R5] Changes to the Admin API structures or protocol will, - whenever possible, require only localized changes to the Admin - server source code and Admin API library implementation. {\bf - [medium]} -\end{description} -The present implementation meets requirements R1, R2, and R3, and -partially meets requirement R5. Requirement R4 is not addressed. - -\section{Admin API functional specification} - -This section describes the Admin API that can be used to maintain -principals and policies. It describes the data structures used for -each function and the interpretation of each data type field, the -semantics of each API function, and the possible return codes. - -The Admin API is intended to be used by remote clients using an RPC -interface. It is implemented by the admin server running on the -Kerberos master server. It may also be possible for a program running -on the Kerberos master server to use the Admin API directly, without -going through the admin server. - -\subsection{Data Structures} - -This section describes the data structures used by the Admin API that -are unique to \secure{}. They are defined in $<$ovsec_admin/admin.h$>$. - -\subsubsection{Principals, ovsec_kadm_principal_ent_t} -\label{sec:principal-structure} - -A Kerberos principal entry is represented by a -ovsec_kadm_principal_ent_t. It contains a subset of the information -stored in the master Kerberos database as well as the additional -information maintained by \secure{}. In the current version, the only -additional information is the principal's policy and the -aux_attributes flags. - -The principal may or may not have a policy enforced on it. If the -POLICY bit (see section \ref{sec:masks}) is set in aux_attributes, the -policy field names the principal's policy. If the POLICY bit is not -set in aux_attributes, no policy is enforced on the principal and the -value of the policy field is undefined. - -\begin{figure}[htbp] -\begin{verbatim} -typedef struct _ovsec_kadm_principal_ent_t { - krb5_principal principal; - - krb5_timestamp princ_expire_time; - krb5_timestamp last_pwd_change; - krb5_timestamp pw_expiration; - krb5_deltat max_life; - krb5_principal mod_name; - krb5_timestamp mod_date; - krb5_flags attributes; - krb5_kvno kvno; - krb5_kvno mkvno; - - char * policy; - u_int32 aux_attributes; -} ovsec_kadm_principal_ent_rec, *ovsec_kadm_principal_ent_t; -\end{verbatim} -\caption{Definition of ovsec_kadm_principal_ent_t.} -\label{fig:princ-t} -\end{figure} - -The fields of an ovsec_kadm_principal_ent_t are interpreted as -follows. - -\begin{description} -\item[principal] The name of the principal; must conform to Kerberos -naming specifications. - -\item[princ_expire_time] The expire time of the principal as a Kerberos -timestamp. No Kerberos tickets will be issued for a principal after -its expire time. - -\item[last_pwd_change] The time this principal's password was last -changed, as a Kerberos timestamp. - -\item[pw_expiration] The expire time of the user's current password, as a -Kerberos timestamp. No application service tickets will be issued for the -principal once the password expire time has passed. Note that the user can -only obtain tickets for services that have the PW_CHANGE_SERVICE bit set in -the attributes field. - -\item[max_life] The maximum lifetime of any Kerberos ticket issued to -this principal. - -\item[attributes] A bitfield of attributes for use by the KDC. -Note that only some are explicitly supported by \secure{}. - -\begin{tabular}{clr} -{\bf Supported} & {\bf Name} & {\bf Value} \\ - & KRB5_KDB_DISALLOW_POSTDATED & 0x00000001 \\ - & KRB5_KDB_DISALLOW_FORWARDABLE & 0x00000002 \\ -X & KRB5_KDB_DISALLOW_TGT_BASED & 0x00000004 \\ - & KRB5_KDB_DISALLOW_RENEWABLE & 0x00000008 \\ - & KRB5_KDB_DISALLOW_PROXIABLE & 0x00000010 \\ - & KRB5_KDB_DISALLOW_DUP_SKEY & 0x00000020 \\ -X & KRB5_KDB_DISALLOW_ALL_TIX & 0x00000040 \\ - & KRB5_KDB_REQUIRES_PRE_AUTH & 0x00000080 \\ - & KRB5_KDB_REQUIRES_HW_AUTH & 0x00000100 \\ -X & KRB5_KDB_REQUIRES_PWCHANGE & 0x00000200 \\ - & KRB5_KDB_DISALLOW_SVR & 0x00001000 \\ -X & KRB5_KDB_PWCHANGE_SERVICE & 0x00002000 -\end{tabular} - -The interpretation of each bit is as follows. For each of the bits -that disables a corresponding KDC_OPT option, the option is disabled -on an AS_REQ if the bit is set on either the client or the server, and -the option is disabled on TGS_REQ if the bit is set on the server (the -setting of the bit on the client is irrelevant for a TGS_REQ). - -\begin{description} -\item[KRB5_KDB_DISALLOW_POSTDATED] Disables the ALLOW_POSTDATED -and POSTDATED KDC options on AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_FORWARDABLE] Disables the FORWARDABLE KDC -option for AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_TGT_BASED] All TGS_REQ requests will fail for -a principal with this bit set. - -\item[KRB5_KDB_DISALLOW_RENEWABLE] Disables the RENEWABLE KDC option for -AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_PROXIABLE] Disables the PROXIABLE KDC option on -AS_REQ and TGS_REQ. - -\item[KRB5_KDB_DISALLOW_DUP_SKEY] Disables the ENC_TKT_IN_SKEY option on -TGS_REQ. - -\item[KRB5_KDB_DISALLOW_ALL_TIX] All AS_REQ requests fail if this bit -is set for the client or the server, and all TGS_REQ requests fail if -this bit is set for the server. Note that this bit can be set -automatically if the symbol KRBCONF_KDC_MODIFIES_KDC is defined and a -specified number of pre-authentication attempts fail. - -\item[KRB5_KDB_REQUIRES_PRE_AUTH] Any AS_REQ will fail if this bit is -set and the padata field of the request is empty. Any TGS_REQ will -fail if this bit is set and the TKT_FLAG_PRE_AUTH bit is not set in -the tgt. Thus, it is possible to have the bit not set on the TGT but -to have a specific service require pre-authentication. - -\item[KRB5_KDB_REQUIRES_HW_AUTH] Unclear. - -\item[KRB5_KDB_REQUIRES_PWCHANGE] An AS_REQ will fail if this bit is -set on the client and the KRB5_KDC_PWCHANGE_SERVICE bit is not set on -the server. - -\item[KRB5_KDB_DISALLOW_SVR] All AS_REQ and TGS_REQ request will fail -if the server has this bit set. - -\item[KRB5_KDB_PWCHANGE_SERVICE] An request from a client whose -password has expired will succeed if this bit is set on the server. -Also see KRB5_KDC_REQUIRES_PWCHANGE. -\end{description} - -\item[mod_name] The name of the Kerberos principal that most recently -modified this principal. - -\item[mod_date] The time this principal was last modified, as a Kerberos -timestamp. - -\item[kvno] The version of the principal's current key. - -\item[mkvno] The version of the Kerberos Master Key in effect when -this principal's key was last changed. - -\item[policy] If the POLICY bit is set in aux_attributes, the name -of the policy controlling this principal. - -\item[aux_attributes] A bitfield of flags for use by the -administration system. Currently, the only valid flag is POLICY, and -it indicates whether or not the principal has a policy enforced on it. -\end{description} - -\subsubsection{Policies, ovsec_kadm_policy_ent_t} -\label{sec:policy-fields} - -If the POLICY bit is set in aux_attributes, the \v{policy} name field -in the ovsec_kadm_principal_ent_t structure refers to a password -policy entry defined in a \v{ovsec_kadm_policy_ent_t}. - -\begin{verbatim} -typedef struct _ovsec_kadm_policy_ent_t { - char *policy; - - u_int32 pw_min_life; - u_int32 pw_max_life; - u_int32 pw_min_length; - u_int32 pw_min_classes; - u_int32 pw_history_num; - u_int32 policy_refcnt; -} ovsec_kadm_policy_ent_rec, *ovsec_kadm_policy_ent_t; -\end{verbatim} - -The fields of an ovsec_kadm_policy_ent_t are interpreted as follows. -Note that a policy's values only apply to a principal using that -policy. - -\begin{description} -\item[policy] The name of this policy, as a NULL-terminated string. -The ASCII characters between 32 (space) and 126 (tilde), inclusive, -are legal. - -\item[pw_min_life] The minimum password lifetime, in seconds. -A principal cannot change its password before pw_min_life seconds have -passed since last_pwd_change. - -\item[pw_max_life] The default duration, in seconds, used to compute -pw_expiration when a principal's password is changed. - -\item[pw_min_length] The minimum password length, in characters. A -principal cannot set its password to anything with fewer than this -number of characters. This value must be greater than zero. - -\item[pw_min_classes] The minimum number of character classes in the -password. This value can only be 1, 2, 3, 4, or 5. A principal cannot -set its password to anything with fewer than this number of character -classes in it. - -\item[pw_history_num] The number of past passwords that are -stored for the principal; the minimum value is 1 and the maximum value -is 10. A principal cannot set its password to any of its previous -pw_history_num passwords. The first ``previous'' password is the -current password; thus, a principal with a policy can never reset its -password to its current value. - -\item[policy_refcnt] The number of principals currently using this policy. -A policy cannot be deleted unless this number is zero. -\end{description} - -\subsubsection{Create/Modify Masks} -\label{sec:masks} - -The API functions for creating and modifying principals and policies -allow for a relevant subset of the fields of the -ovsec_kadm_principal_ent_t and ovsec_kadm_policy_ent_t to be specified -or changed. The chosen fields are determined by a bitmask that is -passed to the relevant function. Each API function has different -rules for which mask values can be specified, and can specify whether -a given mask value is mandatory, optional, or forbidden. Mandatory -fields must be present and forbidden fields must not be present or an -error is generated. When creating a principal or policy, optional -fields have a default value if they are not specified; when modifying -a principal or policy, optional fields are unchanged if they are not -specified. The values for forbidden fields are defined in the -function semantics. - -The masks for principals are in table \ref{tab:princ-bits} and the -masks for policies are in table \ref{tab:policy-bits}. They are -defined in $<$ovsec_admin/admin.h$>$. The -OVSEC_KADM_ prefix has been removed from the Name fields. In the -Create and Modify fields, M means mandatory, F means forbidden, and O -means optional. Create fields that are optional specify the default -value. The notation ``K/M value'' means that the field inherits its -value from the corresponding field in the Kerberos master principal. - -Note that the POLICY and POLICY_CLR bits are special. When POLICY is -set, the policy is assigned to the principal. When POLICY_CLR is -specified, the policy is unassigned to the principal and as a result -no policy controls the principal. - -If the principal has a policy assigned, the POLICY bit is set in -aux_attributes. - -\begin{table}[htbp] -\begin{tabular}{@{}lclll} -{\bf Name} & {\bf Value} & {\bf Field Affected} & {\bf Create} & - {\bf Modify} \\ -PRINCIPAL & 0x000001 & principal & M & F \\ -PRINC_EXPIRE_TIME & 0x000002 & princ_expire_time & O, K/M value & O \\ -PW_EXPIRATION & 0x000004 & pw_expiration & O, now+pw_max_life & O \\ -LAST_PWD_CHANGE & 0x000008 & last_pwd_change & F & F \\ -ATTRIBUTES & 0x000010 & attributes & O, 0 & O \\ -MAX_LIFE & 0x000020 & max_life & O, K/M value & O \\ -MOD_TIME & 0x000040 & mod_date & F & F \\ -MOD_NAME & 0x000080 & mod_name & F & F \\ -KVNO & 0x000100 & kvno & O, 1 & O \\ -MKVNO & 0x000200 & mkvno & F & F \\ -AUX_ATTRIBUTES & 0x000400 & aux_attributes & F & F \\ -POLICY & 0x000800 & policy & O, none & O \\ -POLICY_CLR & 0x001000 & policy & F & O -\end{tabular} -\caption{Mask bits for creating/modifying principals.} -\label{tab:princ-bits} -\end{table} - -\begin{table}[htbp] -\begin{tabular}{@{}lclll} -Name & Value & Field Affected & Create & Modify \\ -POLICY & same & policy & M & F \\ -PW_MAX_LIFE & 0x004000 & pw_max_life & O, 0 (infinite) & O \\ -PW_MIN_LIFE & 0x008000 & pw_min_life & O, 0 & O \\ -PW_MIN_LENGTH & 0x010000 & pw_min_length & O, 1 & O \\ -PW_MIN_CLASSES & 0x020000 & pw_min_classes & O, 1 & O \\ -PW_HISTORY_NUM & 0x040000 & pw_history_num & O, 0 & O \\ -REF_COUNT & 0x080000 & pw_refcnt & F & F -\end{tabular} -\caption{Mask bits for creating/modifying policies.} -\label{tab:policy-bits} -\end{table} - -\subsection{Constants, Header Files, Libraries} - -For release 1.0 and release 1.0.1, all of the files decribed in this -section are -rooted off of the ``stage'' directory in the build tree. If we export -this interface in future releases they will move to the ``install'' -tree. Include files are found under ``stage/include'', libraries under -``stage/lib''. - -$<$ovsec_admin/admin.h$>$ includes a number of required header files, -including RPC, Kerberos 5, com_err, and \secure{} admin com_err -defines. It contains prototypes for all ovsec_kadm routines mentioned -below, as well as all Admin API data structures, type definitions and -defines mentioned in this document. The defines and their values -contained in the file include the following (whose OVSEC_KADM_ -prefixes have been removed): -\begin{description} -\item[admin service principal] ADMIN_SERVICE (``ovsec_adm/admin'') -\item[admin history key] HIST_PRINCIPAL (``ovsec_adm/history'') -\item[change password principal] CHANGEPW_SERVICE (``ovsec_adm/changepw'') -\item[server acl file path] ACLFILE (``/krb5/ovsec_adm.acl'') -\item[dictionary] WORDFILE (``/krb5/ovsec_adm.dict'') -\end{description} - -OVSEC_KADM errors are described in $<$ovsec_admin/kadm_err.h$>$, which -is included by $<$ovsec_admin/admin.h$>$. - -The locations of the admin policy and principal databases, as well as -defines and type definitions for the databases, are defined in -$<$ovsec_admin/adb.h$>$. Some of the defines in that file are: -\begin{description} -\item[admin policy database] POLICY_DB (``/krb5/ovsec_policy.db'') -\item[admin principal database] PRINCIPAL_DB (``/krb5/ovsec_principal.db'') -\end{description} - -Client applications will link against libadmclnt.a and server programs -against libadmsrv.a.\footnote{In Secure 1.0, client applications -linked against libclient.a and libcommon.a, and server applications -linked against libsrv.a and libcommon.a.} Client applications must -also link against: libgssapi_krb5.a, libkrb5.a, libisode.a, -libcrypto.a, librpclib.a, libcom_err.a, libdyn.a, and libdb.a. Server -applications must also link against: libkdb5.a, libkrb5.a, -libcrypto.a, libdb.a, librpclib.a, libcom_err.a, and libdyn.a. - -\subsection{Error Codes} - -The error codes that can be returned by admin functions are listed -below. Error codes indicated with a ``*'' can be returned by every -admin function and always have the same meaning; these codes are -omitted from the list presented with each function. - -The admin system guarantees that a function that returns an error code -has no other side effect. - -The Admin system will use \v{com_err} for error codes. Note that this -means \v{com_err} codes may be returned from functions that the admin -routines call (e.g. the kerberos library). Callers should not expect -that only OVSEC errors will be returned. The Admin system error code -table name will be ``ovk'', and the offsets will be the same as the -order presented here. As mentioned above, the error table include file -will be $<$ovsec_admin/kadm_err.h$>$. - -\begin{description} -\item[* OVSEC_KADM_FAILURE] Operation failed for unspecified reason -\item[* OVSEC_KADM_AUTH_GET] Operation requires ``get'' privilege -\item[* OVSEC_KADM_AUTH_ADD] Operation requires ``add'' privilege -\item[* OVSEC_KADM_AUTH_MODIFY] Operation requires ``modify'' privilege -\item[* OVSEC_KADM_AUTH_DELETE] Operation requires ``delete'' privilege -\item[* OVSEC_KADM_AUTH_INSUFFICIENT] Insufficient authorization for -operation -\item[* OVSEC_KADM_BAD_DB] Database inconsistency detected -\item[OVSEC_KADM_DUP] Principal or policy already exists -\item[OVSEC_KADM_RPC_ERROR] Communication failure with server -\item[OVSEC_KADM_NO_SRV] No administration server found for realm -\item[OVSEC_KADM_BAD_HIST_KEY] Password history principal key version -mismatch -\item[OVSEC_KADM_NOT_INIT] Connection to server not initialized -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist -\item[OVSEC_KADM_UNK_POLICY] Policy does not exist -\item[OVSEC_KADM_BAD_MASK] Invalid field mask for operation -\item[OVSEC_KADM_BAD_CLASS] Invalid number of character classes -\item[OVSEC_KADM_BAD_LENGTH] Invalid password length -\item[OVSEC_KADM_BAD_POLICY] Illegal policy name -\item[OVSEC_KADM_BAD_PRINCIPAL] Illegal principal name (XXX use krb5 -error code?) -\item[OVSEC_KADM_BAD_AUX_ATTR] Invalid auxillary attributes -\item[OVSEC_KADM_BAD_HISTORY] Invalid password history count -\item[OVSEC_KADM_BAD_MIN_PASS_LIFE] Password minimum life is greater -then password maximum life -\item[OVSEC_KADM_PASS_Q_TOOSHORT] Password is too short -\item[OVSEC_KADM_PASS_Q_CLASS] Password does not contain enough -character classes -\item[OVSEC_KADM_PASS_Q_DICT] Password is in the password dictionary -\item[OVSEC_KADM_PASS_REUSE] Cannot resuse password -\item[OVSEC_KADM_PASS_TOOSOON] Current password's minimum life has not -expired -\item[OVSEC_KADM_POLICY_REF] Policy is in use -\item[OVSEC_KADM_INIT] Connection to server already initialized -\item[OVSEC_KADM_BAD_PASSWORD] Incorrect password -\item[OVSEC_KADM_PROTECT_PRINCIPAL] Cannot change protected principal -\item[* OVSEC_KADM_BAD_SERVER_HANDLE] Programmer error! Bad Admin server handle -\item[* OVSEC_KADM_BAD_STRUCT_VERSION] Programmer error! Bad API structure version -\item[* OVSEC_KADM_OLD_STRUCT_VERSION] API structure version specified by application is no longer supported (to fix, recompile application against current OpenV*Secure Admin API header files and libraries) -\item[* OVSEC_KADM_NEW_STRUCT_VERSION] API structure version specified by application is unknown to libraries (to fix, obtain current OpenV*Secure Admin API header files and libraries and recompile application) -\item[* OVSEC_KADM_BAD_API_VERSION] Programmer error! Bad API version -\item[* OVSEC_KADM_OLD_LIB_API_VERSION] API version specified by application is no longer supported by libraries (to fix, update application to adhere to current API version and recompile) -\item[* OVSEC_KADM_OLD_SERVER_API_VERSION] API version specified by application is no longer supported by server (to fix, update application to adhere to current API version and recompile) -\item[* OVSEC_KADM_NEW_LIB_API_VERSION] API version specified by application is unknown to libraries (to fix, obtain current OpenV*Secure Admin API header files and libraries and recompile application) -\item[* OVSEC_KADM_NEW_SERVER_API_VERSION] API version specified by application is unknown to server (to fix, obtain and install newest OpenV*Secure Admin Server) -\end{description} - -\subsection{Authentication and Authorization} -\label{sec:auth} - -Two Kerberos principals exist for use in communicating with the Admin -system: ovsec_adm/admin and ovsec_adm/changepw. Both principals -have the KRB5_KDB_DISALLOW_TGT_BASED bit set in their attributes so -that service tickets for them can only be acquired via a -password-based (AS_REQ) request. Additionally, ovsec_adm/changepw -has the KRB5_KDB_PWCHANGE_SERVICE bit set so that a principal with an -expired password can still obtain a service ticket for it. - -The Admin system accepts requests that are authenticated to either -service principal, but the sets of operations that can be performed by -a request authenticated to each service are different. In particular, -only the functions chpass_principal, randkey_principal, get_principal, -and get_policy can be performed by a request authenticated to the -ovsec_adm/changepw service. The function semantics descriptions below -give the precise details. - -Each Admin API operation authenticated to the ovsec_adm/admin service -requires a specific authorization to run. This version uses a simple -named privilege system with the following names and meanings: - -The Authorization checks only happen if you are using the RPC mechanism. -If you are using the server-side API functions locally on the admin server, -the only authorization check is if you can access the approporiate local -files. - -\begin{description} -\item[Get] Able to examine the attributes (NOT key data) of principals -and policies. -\item[Add] Able to add principals and policies. -\item[Modify] Able to modify attributes of existing principals and policies. -\item[Delete] Able to remove principals and policies. -\end{description} - -Privileges are specified via an external configuration file on the -Kerberos master server (see section \ref{sec:acls}). - -Table \ref{tab:func-overview} summarizes the authorization -requirements of each function. Additionally, each API function -description identifies the privilege required to perform it. - -\subsection{Function Overview} - -The functions provided by the Admin API, and the authorization they -require, are listed in the table \ref{tab:func-overview}. The -``ovsec_kadm_'' prefix has been removed from each function name. - -The function semantics in the following sections omit details that are -the same for every function. - -\begin{itemize} -\item The effects of every function are atomic. - -\item Every function performs an authorization check and returns -the appropriate OVSEC_KADM_AUTH_* error code if the caller does not -have the required privilege. No other information or error code is -ever returned to an unauthorized user. - -\item Every function checks its arguments for NULL pointers or other -obviously invalid values, and returns EINVAL if any are detected. - -\item Any function that performs a policy check uses the policy named -in the principal's policy field. If the POLICY bit is not set in the -principal's aux_attributes field, however, the principal has no -policy, so the policy check is not performed. - -\item Unless otherwise specified, all functions return OVSEC_KADM_OK. -\end{itemize} - -\begin{table}[htbp] -\caption{Summary of functions and required authorization.} -\label{tab:func-overview} -\begin{tabular}{@{}llp{3.24in}} -\\ -{\bf Function Name} & {\bf Authorization} & {\bf Operation} \\ - -init & none & Open a connection with the ovsec_kadm library. OBSOLETE -but still provided---use init_with_password instead. \\ -init_with_password & none & Open a connection with the ovsec_kadm -library using a password to obtain initial credentials. \\ -init_with_skey & none & Open a connection with the ovsec_kadm library -using the keytab entry to obtain initial credentials. \\ -destroy & none & Close the connection with the ovsec_kadm library. \\ -create_principal & add & Create a new principal. \\ -delete_principal & delete & Delete a principal. \\ -modify_principal & modify & Modify the attributes of an existing - principal (not password). \\ -rename_principal & add and delete & Rename a principal. \\ -get_principal & get\footnotemark & Retrieve a principal. \\ -chpass_principal & modify\footnotemark[\thefootnote] & - Change a principal's password. \\ -chpass_principal_util & modify\footnotemark[\thefootnote] & Utility wrapper around chpass_principal. \\ -randkey_principal & modify\footnotemark[\thefootnote] & - Randomize a principal's key. \\ -create_policy & add & Create a new policy. \\ -delete_policy & delete & Delete a policy. \\ -modify_policy & modify & Modify the attributes of a policy. \\ -get_policy & get & Retrieve a policy. \\ -free_principal_ent & none & Free the memory associated with an - ovsec_kadm_principal_ent_t. \\ -free_policy_ent & none & Free the memory associated with an - ovsec_kadm_policy_ent_t. \\ -get_privs & none & Return the caller's admin server privileges. -\end{tabular} -\end{table} -\footnotetext[\thefootnote]{These functions also allow a principal to -perform the operation on itself; see the function's semantics for -details.} - -\subsection{ovsec_kadm_init_*} - -\begin{verbatim} -ovsec_kadm_ret_t ovsec_kadm_init_with_password(char *client_name, char *pass, - char *service_name, char *realm, - unsigned long struct_version, - unsigned long api_version, - void **server_handle) - -ovsec_kadm_ret_t ovsec_kadm_init_with_skey(char *client_name, char *keytab, - char *service_name, char *realm, - unsigned long struct_version, - unsigned long api_version, - void **server_handle) - -ovsec_kadm_ret_t ovsec_kadm_init(char *client_name, char *pass, - char *service_name, char *realm, - unsigned long struct_version, - unsigned long api_version, - void **server_handle) -\end{verbatim} - -AUTHORIZATION REQUIRED: none - -NOTE: ovsec_kadm_init is an obsolete provided for backwards -compatibility. It is identical to ovsec_kadm_init_with_password. - -These three functions open a connection to the ovsec_kadm library and -initialize any neccessary state information. They behave differently -when called from local and remote clients. - -For remote clients, the semantics are: - -\begin{enumerate} -\item Initializes all the com_err error tables used by the Admin -system. - -\item Acquires a Kerberos ticket for the specified service. - -\begin{enumerate} -\item The ticket's client is client_name, which can be any valid -Kerberos principal. If client_name does not include a realm, the -default realm of the local host is used -\item The ticket's service is service_name@realm. service_name must -be one of the constants OVSEC_KADM_ADMIN_SERVICE or -OVSEC_KADM_CHANGEPW_SERVICE. -\item If realm is NULL, client_name's realm is used. - -\item For init_with_password, the ticket is decoded with the password -pass, which must be client_name's password. If pass is NULL or an -empty string, the user is prompted (via the tty) for a password. - -\item For init_with_skey, the ticket is decoded with client_name's key -obtained from the keytab keytab. If keytab is NULL or an empty string -the default keytab is used. -\end{enumerate} - -\item Creates a GSS-API authenticated connection to the Admin server, -using the just-acquired Kerberos ticket. - -\item Verifies that the struct_version and api_version specified by -the caller are valid and known to the library. - -\item Sends the specified api_version to the server. - -\item Upon successful completion, fills in server_handle with a handle -for this connection, to be used in all subsequent API calls. -\end{enumerate} - -The caller should always specify OVSEC_KADM_STRUCT_VERSION for the -struct_version argument, a valid and supported API version constant -for the api_version argument (currently, theonly valid API version -constant is OVSEC_KADM_API_VERSION_1), and a valid pointer in which -the server handle will be stored. - -Local clients, running on the KDC, may be useful. For now this is will -most likely be used for testing, but could in the future be the basis -for a command-line system that works both remotely and on the KDC -machine. If any ovsec_kadm_init_* is invoked locally its semantics are: - -\begin{enumerate} -\item Initializes all the com_err error tables used by the Admin -system. - -\item Initializes direct access to the KDC database. If pass (or -keytab) is NULL or an empty string, reads the master password from -/.k5.REALM-NAME (created by kstash). Otherwise, the non-NULL password -is ignored and the user is prompted for it via the tty. - -\item Initializes the dictionary (if present) for dictionary checks. - -\item Parses client_name as a Kerberos principal. client_name should -usually be specified as the name of the program. - -\item Verifies that the struct_version and api_version specified by -the caller are valid. - -\item Fills in server_handle with a handle containing all state -information (version numbers and client name) for this ``connection.'' -\end{enumerate} -The service_name argument is not used. - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_NO_SRV] No Admin server can be found for the -specified realm. - -\item[OVSEC_KADM_RPC_ERROR] The RPC connection to the server cannot be -initiated. - -\item[OVSEC_KADM_BAD_PASSWORD] Incorrect password. -\end{description} - -\subsection{ovsec_kadm_destroy} - -\begin{verbatim} -ovsec_kadm_ret_t ovsec_kadm_destroy(void *server_handle) -\end{verbatim} - -AUTHORIZATION REQUIRED: none - -Close the connection to the Admin server and releases all related -resources. This function behaves differently when called by local and -remote clients. - -For remote clients, the semantics are: - -\begin{enumerate} -\item Destroy the temporary credential cache created by -ovsec_kadm_init. - -\item Tear down the GSS-API context negotiated with the server. - -\item Close the RPC connection. - -\item Free storage space associated with server_handle, after erasing -its magic number so it won't be mistaken for a valid handle by the -library later. -\end{enumerate} - -For local clients, this function just frees the storage space -associated with server_handle after erasing its magic number. - -RETURN CODES: - -\subsection{ovsec_kadm_create_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_create_principal(void *server_handle, - ovsec_kadm_principal_ent_t princ, u_int32 mask, - char *pw); -\end{verbatim} - -AUTHORIZATION REQUIRED: add - -\begin{enumerate} - -\item Return OVSEC_KADM_BAD_MASK if the mask is invalid. -\item If the named principal exists, return OVSEC_KADM_DUP. -\item If the POLICY bit is set and the named policy does not exist, -return OVSEC_KADM_UNK_POLICY. -\item If OVSEC_KADM_POLICY bit is set in aux_attributes check to see if -the password does not meets quality standards, return the appropriate -OVSEC_KADM_PASS_Q_* error code if it fails. -\item Store the principal, set the key. The key is generated with -Kerberos' string-to-key function, using the salt method specified on -the admin server's command line; see section \ref{sec:commandline}. -\item If the POLICY bit is set, increment the named policy's reference -count by one. - -\item Set the pw_expiration field. -\begin{enumerate} -\item If the POLICY bit is not set, then -\begin{enumerate} -\item if the PW_EXPIRATION bit is set, set pw_expiration to the given -value, else -\item set pw_expiration to never. -\end{enumerate} -\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to -the sooner of the given value and now + pw_max_life. -\item Otherwise, set pw_expiration to now + pw_max_life. -\end{enumerate} - -\item Set mod_date to now and set mod_name to caller. -\item Set last_pwd_change to now. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_MASK] The field mask is invalid for a create -operation. -\item[OVSEC_KADM_DUP] Principal already exists. -\item[OVSEC_KADM_UNK_POLICY] Policy named in entry does not exist. -\item[OVSEC_KADM_PASS_Q_*] Specified password does not meet policy -standards. -\end{description} - -\subsection{ovsec_kadm_delete_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_delete_principal(void *server_handle, krb5_principal princ); -\end{verbatim} - -AUTHORIZATION REQUIRED: delete - -\begin{enumerate} -\item Return OVSEC_KADM_UNK_PRINC if the principal does not exist. -\item If the POLICY bit is set in aux_attributes, decrement the named -policy's reference count by one. -\item Delete principal. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\end{description} - -\subsection{ovsec_kadm_modify_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_modify_principal(void *server_handle, - ovsec_kadm_principal_ent_t princ, u_int32 mask); -\end{verbatim} - -Modify the attributes of the principal named in -ovsec_kadm_principal_ent_t. This does not allow the principal to be -renamed or for its password to be changed. - -AUTHORIZATION REQUIRED: modify - -Although a principal's pw_expiration is usually computed based on its -policy and the time at which it changes its password, this function -also allows it to be specified explicitly. This allows an -administrator, for example, to create a principal and assign it to a -policy with a pw_max_life of one month, but to declare that the new -principal must change its password away from its initial value -sometime within the first week. - -\begin{enumerate} -\item Return OVSEC_KADM_UNK_PRINC if the principal does not exist. -\item Return OVSEC_KADM_BAD_MASK if the mask is invalid. -\item If POLICY bit is set but the new policy does not exist, return -OVSEC_KADM_UNK_POLICY. -\item If either the POLICY or POLICY_CLR bits are set, update the -corresponding bits in aux_attributes. - -\item Update policy reference counts. -\begin{enumerate} -\item If the POLICY bit is set, then increment policy count on new -policy. -\item If the POLICY or POLICY_CLR bit is set, and the POLICY bit in -aux_attributes is set, decrement policy count on old policy. -\end{enumerate} - -\item Set pw_expiration according to the new policy. -\begin{enumerate} -\item If the POLICY bit is not set in aux_attributes, then -\begin{enumerate} -\item if the PW_EXPIRATION bit is set, set pw_expiration to the given -value, else -\item set pw_expiration to never. -\end{enumerate} -\item Otherwise, if the PW_EXPIRATION bit is set, set pw_expiration to -the sooner of the given value and last_pwd_change + pw_max_life. -\item Otherwise, set pw_expiration to last_pwd_change + pw_max_life. -\end{enumerate} - -\item Update the fields specified in the mask. -\item Update mod_name field to caller and mod_date to now. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Entry does not exist. -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify -operation. -\item[OVSEC_KADM_UNK_POLICY] The POLICY bit is set but the new -policy does not exist. -\end{description} - -\subsection{ovsec_kadm_rename_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_rename_principal(void *server_handle, krb5_principal source, - krb5_principal target); -\end{verbatim} - -AUTHORIZATION REQUIRED: add and delete - -\begin{enumerate} -\item Check to see if source principal exists, if not return -OVSEC_KADM_UNK_PRINC error. -\item Check to see if target exists, if so return OVSEC_KADM_DUP error. -\item Create the new principal named target, then delete the old -principal named source. All of target's fields will be the same as -source's fields, except that mod_name and mod_date will be updated to -reflect the current caller and time. -\end{enumerate} - -Note that since the principal name may have been used as the salt for -the principal's key, renaming the principal may render the principal's -current password useless; with the new salt, the key generated by -string-to-key on the password will suddenly be different. Therefore, -an application that renames a principal must also require the user to -specify a new password for the principal (and administrators should -notify the affected party). - -Note also that, by the same argument, renaming a principal will -invalidate that principal's password history information; since the -salt will be different, a user will be able to select a previous -password without error. - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Source principal does not exist. -\item[OVSEC_KADM_DUP] Target principal already exist. -\end{description} - -\subsection{ovsec_kadm_chpass_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_chpass_principal(void *server_handle, krb5_principal princ, - char *pw); -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_adm/changepw service, the modify privilege is disregarded. - -Change a principal's password. - -This function enforces password policy and dictionary checks. If the new -password specified is in the password dictionary, and the policy bit is set -OVSEC_KADM_PASS_DICT is returned. If the principal's POLICY bit is set in -aux_attributes, compliance with each of the named policy fields is verified -and an appropriate error code is returned if verification fails. - -Note that the policy checks are only be performed if the POLICY bit is -set in the principal's aux_attributes field. - -\begin{enumerate} -\item Make sure principal exists, if not return OVSEC_KADM_UNK_PRINC error. -\item If caller does not have modify privilege, (now - last_pwd_change) $<$ -pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the -principal's attributes, return OVSEC_KADM_PASS_TOOSOON. -\item If the principal your are trying to change is ovsec_adm/history -return OVSEC_KADM_PROTECT_PRINCIPAL. -\item If the password does not meet the quality -standards, return the appropriate OVSEC_KADM_PASS_Q_* error code. -\item Convert password to key. The key is generated with -Kerberos' string-to-key function, using the salt method specified on -the admin server's command line; see section \ref{sec:commandline}. -\item If the new key is in the principal's password history, return -OVSEC_KADM_PASS_REUSE. -\item Store old key in history. -\item Update principal to have new key. -\item Increment principal's key version number by one. -\item If the POLICY bit is set, set pw_expiration to now + -max_pw_life. If the POLICY bit is not set, set pw_expiration to -never. -\item If the KRB5_KDB_REQUIRES_PWCHANGE bit is set in the principal's -attributes, clear it. -\item Update last_pwd_change and mod_date to now, update mod_name to -caller. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality -standards. -\item[OVSEC_KADM_PASS_REUSE] Requested password is in user's -password history. -\item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum life -\item[OVSEC_KADM_PROTECT_PRINCIPAL] Cannot change the password of a special principal -\end{description} - - -\subsection{ovsec_kadm_chpass_principal_util} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_chpass_principal_util(void *server_handle, krb5_principal princ, - char *new_pw, char **pw_ret, - char *msg_ret); -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_adm/changepw service, the modify privilege is disregarded. - -This function is a wrapper around ovsec_kadm_chpass_principal. It can -read a new password from a user, change a principal's password, and -return detailed error messages. msg_ret should point to a char buffer -in the caller's space of sufficient length for the error messages -described below. 1024 bytes is recommended. It will also return the -new password to the caller if pw_ret is non-NULL. - -\begin{enumerate} -\item If new_pw is NULL, this routine will prompt the user for the new -password (using the strings specified by OVSEC_KADM_PW_FIRST_PROMPT and -OVSEC_KADM_PW_SECOND_PROMPT) and read (without echoing) the password input. -Since it is likely that this will simply call krb5_read_password only -terminal-based applications will make use of the password reading -functionality. If the passwords don't match the string ``New passwords do -not match - password not changed.'' will be copied into msg_ret, and the -error code KRB5_LIBOS_BADPWDMATCH will be returned. For other errors that -ocurr while reading the new password, copy the string ``$ -occurred while trying to read new password.'' followed by a blank line and -the string specified by CHPASS_UTIL_PASSWORD_NOT_CHANGED into msg_ret and -return the error code returned by krb5_read_password. - -\item If pw_ret is non-NULL, and the password was prompted, set *pw_ret to -point to a static buffer containing the password. If pw_ret is non-NULL -and the password was supplied, set *pw_ret to the supplied password. - -\item Call ovsec_kadm_chpass_principal with princ, and new_pw. - -\item If successful copy the string specified by CHPASS_UTIL_PASSWORD_CHANGED -into msg_ret and return zero. - -\item For a policy related failure copy the appropriate message (from below) -followed by a newline and ``Password not changed.'' into msg_ret -filling in the parameters from the principal's policy information. If -the policy information cannot be obtained copy the generic message if -one is specified below. Return the error code from -ovsec_kadm_chpass_principal. - -Detailed messages: -\begin{description} - -\item[PASS_Q_TOO_SHORT] -New password is too short. Please choose a -password which is more than $<$pw-min-len$>$ characters. - -\item[PASS_Q_TOO_SHORT - generic] -New password is too short. Please choose a longer password. - -\item[PASS_REUSE] -New password was used previously. Please choose a -different password. - -\item[PASS_Q_CLASS] -New password does not have enough character classes. Classes include -lower class letters, upper case letters, digits, punctuation and all -other characters. Please choose a password with at least -$<$min-classes$>$ character classes. - -\item[PASS_Q_CLASS - generic] -New password does not have enough character classes. Classes include -lower class letters, upper case letters, digits, punctuation and all -other characters. - -\item[PASS_Q_DICT] -New password was found in a dictionary of possible passwords and -therefore may be easily guessed. Please choose another password. See -the kpasswd man page for help in choosing a good password. - -\item[PASS_TOOSOON] -Password cannot be changed because it was changed too recently. Please -wait until $<$last-pw-change+pw-min-life$>$ before you change it. If you -need to change your password before then, contact your system -security administrator. - -\item[PASS_TOOSOON - generic] -Password cannot be changed because it was changed too recently. If you -need to change your now please contact your system security -administrator. -\end{description} - -\item For other errors copy the string ``$<$com_err message$>$ -occurred while trying to change password.'' following by a blank line -and ``Password not changed.'' into msg_ret. Return the error code -returned by ovsec_kadm_chpass_principal. -\end{enumerate} - - -RETURN CODES: - -\begin{description} -\item[KRB5_LIBOS_BADPWDMATCH] Typed new passwords did not match. -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_Q_*] Requested password does not meet quality -standards. -\item[OVSEC_KADM_PASS_REUSE] Requested password is in user's -password history. -\item[OVSEC_KADM_PASS_TOOSOON] Current password has not reached minimum -life. -\end{description} - - -\subsection{ovsec_kadm_randkey_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_randkey_principal(void *server_handle, krb5_principal princ, - krb5_keyblock **new_key) -\end{verbatim} - -AUTHORIZATION REQUIRED: modify, or the calling principal being the -same as the princ argument. If the request is authenticated to the -ovsec_adm/changepw service, the modify privilege is disregarded. - -Generate and assign a new random key to the named principal, and -return the generated key in allocated storage. The caller must free -the returned krb5_keyblock * with krb5_free_keyblock. - -If the principal's POLICY bit is set in aux_attributes and the caller does -not have modify privilege , compliance with the password minimum life -specified by the policy is verified and an appropriate error code is returned -if verification fails. - -\begin{enumerate} -\item If the principal does not exist, return OVSEC_KADM_UNK_PRINC. -\item If caller does not have modify privilege, (now - last_pwd_change) $<$ -pw_min_life, and the KRB5_KDB_REQUIRES_PWCHANGE bit is not set in the -principal's attributes, return OVSEC_KADM_PASS_TOOSOON. -\item If the principal you are trying to change is ovsec_adm/history return -OVSEC_KADM_PROTECT_PRINCIPAL. -\item Store old key in history. -\item Update principal to have new key. -\item Increment principal's key version number by one. -\item If the POLICY bit in aux_attributes is set, set pw_expiration to -now + max_pw_life. -\item If the KRB5_KDC_REQUIRES_PWCHANGE bit is set in the principal's -attributes, clear it. -\item Update last_pwd_change and mod_date to now, update mod_name to -caller. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\item[OVSEC_KADM_PASS_TOOSOON] The minimum lifetime for the current -key has not expired. -\item[OVSEC_KADM_PROTECT_PRINCIPAL] Cannot change the password of a special -principal -\end{description} - -This function can also be used as part of a sequence to create a new -principal with a random key. The steps to perform the operation -securely are - -\begin{enumerate} -\item Create the principal with ovsec_kadm_create_principal with a -random password string and with the KRB5_KDB_DISALLOW_ALL_TIX bit set -in the attributes field. - -\item Randomize the principal's key with ovsec_kadm_randkey_principal. - -\item Call ovsec_kadm_modify_principal to reset the -KRB5_KDB_DISALLOW_ALL_TIX bit in the attributes field. -\end{enumerate} - -The three steps are necessary to ensure secure creation. Since an -attacker might be able to guess the initial password assigned by the -client program, the principal must be disabled until the key can be -truly randomized. - -\subsection{ovsec_kadm_get_principal} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_principal(void *server_handle, krb5_principal princ, - ovsec_kadm_principal_ent_t *ent); -\end{verbatim} - -Return the principal's attributes in allocated memory. The caller -must free the returned entry with ovsec_kadm_free_principal_ent. -If an error is returned entry is set to NULL. - -AUTHORIZATION REQUIRED: get, or the calling principal being the same -as the princ argument. If the request is authenticated to the -ovsec_adm/changepw service, the get privilege is disregarded. - - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_UNK_PRINC] Principal does not exist. -\end{description} - -\subsection{ovsec_kadm_create_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_create_policy(void *server_handle, - ovsec_kadm_policy_ent_t policy, u_int32 mask); -\end{verbatim} - -Create a new policy. - -AUTHORIZATION REQUIRED: add - -\begin{enumerate} -\item Check to see if mask is valid, if not return OVSEC_KADM_BAD_MASK error. -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. - -\item Check to see if the policy already exists, if so return -OVSEC_KADM_DUP error. -\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2, -3, 4, or 5, return OVSEC_KADM_BAD_CLASS. -\item Create a new policy setting the appropriate fields determined -by the mask. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_DUP] Policy already exists -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a create -operation. -\item[OVSEC_KADM_BAD_CLASS] The specified number of character classes -is invalid. -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\end{description} - -\subsection{ovsec_kadm_delete_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_delete_policy(void *server_handle, char *policy); -\end{verbatim} - -Deletes a policy. - -AUTHORIZATION REQUIRED: delete - -\begin{enumerate} -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. -\item Return OVSEC_KADM_UNK_POLICY if the named policy does not exist. -\item Return OVSEC_KADM_POLICY_REF if the named policy's refcnt is not 0. -\item Delete policy. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy does not exist. -\item[OVSEC_KADM_POLICY_REF] Policy is being referenced. -\end{description} - -\subsection{ovsec_kadm_modify_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_modify_policy(void *server_handle, - ovsec_kadm_policy_ent_t policy, u_int32 mask); -\end{verbatim} - -Modify an existing policy. Note that modifying a policy has no affect -on a principal using the policy until the next time the principal's -password is changed. - -AUTHORIZATION REQUIRED: modify - -\begin{enumerate} -\item Return OVSEC_KADM_BAD_POLICY if the policy name contains illegal -characters. -\item Check to see if mask is legal, if not return OVSEC_KADM_BAD_MASK error. -\item Check to see if policy exists, if not return -OVSEC_KADM_UNK_POLICY error. -\item If the PW_MIN_CLASSES bit is set and pw_min_classes is not 1, 2, -3, 4, or 5, return OVSEC_KADM_BAD_CLASS. -\item Update the fields specified in the mask. -\end{enumerate} - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy not found. -\item[OVSEC_KADM_BAD_MASK] The mask is not valid for a modify -operation. -\item[OVSEC_KADM_BAD_CLASS] The specified number of character classes -is invalid. -\end{description} - -\subsection{ovsec_kadm_get_policy} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_policy(void *server_handle, char *policy, - ovsec_kadm_policy_ent_t *ent); -\end{verbatim} - -AUTHORIZATION REQUIRED: get, or the calling principal's policy being -the same as the policy argument. If the request is authenticated to -the ovsec_adm/changepw service, the get privilege is disregarded. -If an error is returned entry is set to NULL. - -Return the policy's attributes in allocated memory. The caller must -free the returned entry with ovsec_kadm_free_policy_ent. - -RETURN CODES: - -\begin{description} -\item[OVSEC_KADM_BAD_POLICY] The policy name contains illegal characters. -\item[OVSEC_KADM_UNK_POLICY] Policy not found. -\end{description} - -\subsection{ovsec_kadm_free_principal_ent, _policy_ent} - -\begin{verbatim} -void ovsec_kadm_free_principal_ent(void *server_handle, - ovsec_kadm_principal_ent_t princ); -\end{verbatim} - -Free the memory that was allocated by a call to -ovsec_kadm_get_principal. If the argument is NULL, the function -returns succesfully. - -AUTHORIZATION REQUIRED: none (local operation) - -\begin{verbatim} -void ovsec_kadm_free_policy_ent(ovsec_kadm_policy_ent_t policy); -\end{verbatim} - -Free memory that was allocated by a call to ovsec_kadm_get_policy. If -the argument is NULL, the function returns succesfully. - -AUTHORIZATION REQUIRED: none (local operation) - -\subsection{ovsec_kadm_get_privs} - -\begin{verbatim} -ovsec_kadm_ret_t -ovsec_kadm_get_privs(void *server_handle, u_int32 *privs); -\end{verbatim} - -Return the caller's admin server privileges in the integer pointed to -by the argument. The Admin API does not define any way for a -principal's privileges to be set. Note that this function will -probably be removed or drastically changed in future versions of this -system. - -The returned value is a bitmask indicating the caller's privileges: - -\begin{tabular}{llr} -{\bf Privilege} & {\bf Symbol} & {\bf Value} \\ -Get & OVSEC_KADM_PRIV_GET & 0x01 \\ -Add & OVSEC_KADM_PRIV_ADD & 0x02 \\ -Modify & OVSEC_KADM_PRIV_MODIFY & 0x04 \\ -Delete & OVSEC_KADM_PRIV_DELETE & 0x08 -\end{tabular} - -There is no guarantee that a caller will have a privilege indicated by -this function for any length of time; applications using this function -must still be prepared to handle all possible OVSEC_KADM_AUTH_* error -codes. - -\section{Server} - -The Admin API will be implemented by a server process running on the -same machine as the Kerberos server, and a client library to -communicate with the server. - -\subsection{Command Line} -\label{sec:commandline} - -The command line syntax of the admin server is - -\begin{verbatim} -ovsec_adm_server [-m] [-r realm] [-createsalt normal|none] - [-modifysalt normal|none|keep] -\end{verbatim} - -The -m argument specifies that the Kerberos master key should be read -from the keyboard instead of from the stash file. If the stash file -does not exist and this argument is not specified, the server will -not start. - -The -r argument specifies the Kerberos realm. If this argument is not -specified, the host's default realm is used. - -The -createsalt and -modifysalt arguments control the type of salt -used when creating and modifying keys in the Kerberos database, -respectively. ``normal'' means the standard V5 salt which uses the -principal and realm name. ``none'' means no salt, which is compatible -with Kerberos V4. ``keep'' means maintain the previous salt when a -key is changed. - -If the either admin principal or policy databases are reloaded using -the tools described in section \ref{sec:tools}, the admin server must -be shut down during the process. If the admin server is left running -during the import process, at best the server may use old information -and at worst the database may become inconsistent. - -\subsection{Protocol and Port Number} - -The admin server accepts TCP Sun RPC connections. The port number -(which the server listens on, and which clients should use to contact -it) is determined by a three step process: - -\begin{enumerate} -\item If ovsec_kadm/tcp exists in /etc/services, the specified port -number is used. - -\item Otherwise, if kerberos_adm/tcp exists in /etc/services, the -specified port number is used. - -\item Otherwise, port number 752 is used. -\end{enumerate} - -\subsection{Key Table, Authorization ACLs} -\label{sec:acls} - -The admin server's keytable is stored in /krb5/ovsec_adm.srvtab. It -contains entries for the principals OVSEC_KADM_ADMIN_SERVICE and -OVSEC_KADM_CHANGEPW_SERVICE. - -The admin server will use a simple ACL mechanism to grant privileges -to principals. The file OVSEC_KADM_ACLFILE will contain a -list of principals and their privileges. It is read at start-up, and -can only be reread by restarting the admin server. - -The format of this file is: - -\begin{itemize} -\item Blank lines or lines beginning with ``\#'' are ignored. - -\item ACL entry lines contain two fields separated by any number of -spaces, tabs, or newlines, and are terminated with a semi-colon. The -first field is a Kerberos name and the second field is the privilege -list. - -\item The privilege list can contain a comma separated list of the -words ``get'', ``add'', ``modify'', and ``delete''. -\end{itemize} - -The principal named in the first field of each ACL entry has the -privileges listed in the second field the ACL entry. - -\subsection{Logging} - -The Admin server will log various events via the syslog mechanism (see -the syslog(3) manual page). The level depends on the notice, the -facility is LOG_LOCAL6, and notices are identified with the name -``ovsec_adm_server''. Each syslog message described below begins with -a prefix including the time the message was logged, the host name of -the logging machine, and the pid of the logging process: - -\begin{verbatim} -Nov 11 12:37:26 suan-la-chow-show ovsec_adm_server[9229]: -\end{verbatim} - -\subsubsection{Miscellaneous Messages} - -When the server starts successfully and is ready to handle requests, -is logs the message ``starting'' at the LOG_INFO level. When it exits -(due to a signal, for example) it logs the message ``finished, -exiting'' at the LOG_INFO level. - -If the dictionary file does not exist, the server logs the message -``WARNING: Cannot find the dictionary file $<$name$>$, continuing -without one.'' at the LOG_ERR level and continues with dictionary -checking disabled. - -If the server cannot register itself as an RPC server via the portmap -daemon, it logs the message ``Cannot register RPC service, failing.'' -at the LOG_ERR level and exits with non-zero status. This error can -happen if the portmapper is not running. - -If the GSS-API authentication system cannot be initialized, the server -logs the message ``Cannot initialize GSS-API authentication, -failing.'' at the LOG_ERR level and exits with non-zero status. This -error can happen if, for example, the file ovsec_adm.srvtab does not -exist or is incorrect. - -\subsubsection{Request Messages} - -In the event descriptions below, IP address refers to the originating -remote IP address, procedure name refers to the name of the API -function, client name refers to the authenticated name of the caller, -service name refers to the service the client authenticated to (see -section \ref{sec:auth}), primary argument refers to the name of the -principal or policy affected by the call,\footnote{The first release -only logs the primary argument, rather than logging the old and new -values of all fields.} and status refers to the com_err string -corresponding to the error code generated. All of these messages are -logged at the LOG_NOTICE level. - -\begin{itemize} -\item Unsuccessful authentication attempts (e.g.: failures during -GSS-API context establishment). This error occurs inside the RPC; the -admin server is notified via a callback. - -\begin{verbatim} -Authentication attempt failed: , -\end{verbatim} - -Example: A buggy client attempts to authenticate to the admin server -as the existing but invalid service name ``mailserver@REALM.COM'': - -\begin{verbatim} -Authentication attempt failed: 192.231.148.11, Miscellaneous error, -Wrong principal in request -\end{verbatim} - -\item Authentication failure. This error can occur both within the -RPC, while parsing the RPC call header, and while arguments are -decoded by the admin server. It can be the result of a a garbled -{\it or retransmitted} packet, a replay attack, a packet-modification -attack, or a header/argument splicing attack. - -\begin{verbatim} -WARNING! Forged/garbled request: , claimed client = -, service = , addr = -\end{verbatim} - -Example: An attacker attempts to replay a previously valid ``create -principal'' message from jon/admin@REALM.COM: - -\begin{verbatim} -WARNING! Forged/garbled request: ovsec_kadm_create_principal, claimed -client = jon/admin@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -\item Unauthorized request. This error occurs when a properly -authenticated caller attempts to perform an operation for which it is -not authorized. - -\begin{verbatim} -Unauthorized request: , , client = -, service = , addr = -\end{verbatim} - -Example: An attacker cracker@REALM.COM attempts to modify the Kerberos -master principal: - -\begin{verbatim} -Unauthorized request: ovsec_kadm_modify_principal, K/M@REALM.COM, -client = cracker@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -\item Authorized requests and miscellaneous errors. A message is -logged when an authorized request succeeds or fails for any reason -other than those listed above. In the case of success, the status is -``success''; otherwise, the status can be anything from ``no space -left on device'' (ENOSPC) to an OVSEC_KADM error such as ``principal -does not exist'' (OVSEC_KADM_UNK_PRINC). - -\begin{verbatim} -Request: , , , client = -, service = , addr = -\end{verbatim} - -Example: jon/admin@REALM.COM creates a new principal new@REALM.COM: - -\begin{verbatim} -Request: ovsec_kadm_create_principal, new@REALM.COM, success, -client = jon/admin@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -Example: A buggy client program attempts to create a principal with a -NULL name: - -\begin{verbatim} -Request: ovsec_kadm_create_principal, (null), Invalid argument, client -= jon/admin@REALM.COM, service = admin@REALM.COM, addr = -192.231.148.12 -\end{verbatim} - -Example: joe/user@REALM.COM changes its own password: - -\begin{verbatim} -Request: ovsec_kadm_chpass_principal, joe/user@REALM.COM, success, -client = joe/user@REALM.COM, server = ovsec_adm/changepw@REALM.COM, -addr = 192.231.148.12 -\end{verbatim} - -Example: jon/admin@REALM.COM attempts to get a principal that does not -exist: - -\begin{verbatim} -Request: ovsec_kadm_get_principal, does/not/exist@REALM.COM, principal -does not exist, client = jon/admin@REALM.COM, server = -admin@REALM.COM, addr = 192.231.148.12 -\end{verbatim} - -\end{itemize} - -\subsection{Password Dictionary} - -The Admin server's password dictionary is stored in -OVSEC_KADM_WORDFILE. It is read once when the server starts. It -contains a list of entries, separated by newlines. An entry may -include any character except a newline and NULL, including spaces. -The dictionary does not need to be sorted. - -\section{Tools} -\label{sec:tools} - -Three tools will be provided to create and manage the admin databases. -This need only run on the admin server machine and do not need to -operate remotely. The tools are: - -\begin{description} -\item[ovsec_adm_create] create the admin service principal, the admin -history principal, the admin password-changing principal, and empty -admin policy database, and an admin principal database with an empty -entry for every exist principal. -\item[ovsec_adm_db_export/import] dump or load the admin policy and -principal databases -\item[ovsec_adm_check] check the KDC and admin databases for -inconsistencies and repair them.\footnote{Not yet implemented.} -\end{description} - -The details of these tools are described in their own documents. - -\end{document} diff --git a/doc/kadm5/api-server-design.tex b/doc/kadm5/api-server-design.tex deleted file mode 100644 index ecc64bac0..000000000 --- a/doc/kadm5/api-server-design.tex +++ /dev/null @@ -1,585 +0,0 @@ -\documentstyle[12pt,fullpage,changebar,rcsid]{article} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\rcs$Id$ - -\setlength{\parskip}{.7\baselineskip} -\setlength{\parindent}{0pt} - -\def\secure{OV*Secure} -\def\v#1{\verb+#1+} -\def\k#1{K$_#1$} - -\title{OV*Secure Admin Server \\ Implementation Design\thanks{\rcsId}} -\author{Barry Jaspan} - -\begin{document} - -\sloppy -\maketitle - -{\setlength{\parskip}{0pt}\tableofcontents} - -\section{Overview} - -The admin server is implemented as a nearly-stateless transaction -server, where each admin API function represents a single transaction. -No per-client or per-connection information is stored; only local -database handles are maintained between requests. - -The admin API is exported via an RPC interface that hides all details -about network encoding, authentication, and encryption of data on the -wire. The RPC mechanism does, however, allow the server to access the -underlying authentication credentials for authorization purposes. - -The admin server accesses a total of three databases. -\begin{itemize} -\item The master Kerberos database is used to store all the -information that the Kerberos server understands, thus allowing the -greatest functionality with no modifications to a standard KDC. - -\item The admin principal database stores \secure{}-specific per-principal -information. - -\item The policy database stores \secure{} policy information. -\end{itemize} - -The per-principal information stored in the admin principal database -consists of the principal's policy name and an array of the -principal's previous keys. The old keys are stored encrypted in the -key of the special principal ``ovsec_adm/history'' that is created by -ovsec_adm_create. Since a change in ovsec_adm/history's key renders -every principal's key history array useless, it can only be changed -using the ovsec_adm_edit utility; that program will reencrypt every -principal's key history in the new key.\footnote{ovsec_adm_edit has -not yet been implemented, and there are currently no plans to -implement it.} The admin server refuses all requests to change -ovsec_adm/history's key. - -\section{Main} - -The admin server starts by trapping all fatal signals and directing -them to a cleanup-and-exit function. It then creates and exports the -RPC interface and enters its main loop. - -The main loop dispatches all incoming requests to the RPC mechanism. -After 15 seconds of inactivity, the server closes all open databases; -each database will be automatically reopened by the API function -implementations as necessary. - -\section{Remote Procedure Calls} - -The RPC for the Admin system will be based on SUNRPC. SUNRPC is used -because it is a well-known, portable RPC mechanism. The underlying -external data representation (xdr) mechanisms for wire encapsulation -are well-known and extensible. - -Authentication to the admin server will be handled by adding a GSS-API -authentication type within the existing SUNRPC structure. This will -require code modifications to SUNRPC, but the API and wire protocol do -not need to change. This may affect whether the RPC will use UDP or -TCP; although all the admin functions are stateless, the GSS-API -authentication binding will not be and it might be easier to use TCP -for this reason. - -\section{Database Record Types} -\label{sec:db-types} - -\subsection{Admin Principal, osa_princ_ent_t} - -The admin principal database stores records of the type -osa_princ_ent_t (declared in $<$ovsec_admin/adb.h$>$), which is the -subset of the ovsec_kadm_principal_ent_t structure that is not stored -in the Kerberos database plus the necessary bookkeeping information. -The records are keyed by the ASCII representation of the principal's -name, including the trailing NULL. - -\begin{verbatim} -typedef struct _osa_princ_ent_t { - krb5_principal name; - - char * policy; - u_int32 aux_attributes; - - u_int32 num_old_keys; - u_int32 next_old_key; - krb5_kvno admin_history_kvno; - krb5_encrypted_keyblock *old_keys; -} osa_princ_ent_rec, *osa_princ_ent_t; -\end{verbatim} - -The fields that are different from ovsec_kadm_principal_ent_t are: - -\begin{description} -\item[num_old_keys] The number of previous keys in the old_keys array. -This value must be 0 $\le$ num_old_keys $<$ pw_history_num. - -\item[next_old_key] The index into old_keys where the next key should -be inserted. This value must be 0 $\le$ next_old_key $\le$ -num_old_keys. - -\item[admin_history_kvno] The key version number of the admin/history -principal's key used to encrypt the values in old_keys. If the admin -server finds that admin/history's kvno is different from the value in -this field, an error message is logged. (XXX where?) - -\item[old_keys] The array of the principal's previous keys, each -encrypted in the admin/history key. There are num_old_keys elements. -\end{description} - -\subsection{Policy, osa_policy_ent_t} - -The policy database stores records of the type osa_policy_ent_t -(declared in $<$ovsec_admin/adb.h$>$) , which is all of -ovsec_kadm_policy_ent_t plus necessary bookkeeping information. The -records are keyed by the policy name. - -\begin{verbatim} -typedef struct _osa_policy_ent_t { - char *policy; - - u_int32 pw_min_life; - u_int32 pw_max_life; - u_int32 pw_min_length; - u_int32 pw_min_classes; - u_int32 pw_history_num; - - u_int32 refcnt; -} osa_policy_ent_rec, *osa_policy_ent_t; -\end{verbatim} - -\subsection{Kerberos, krb5_db_entry} - -The Kerberos database stores records of type krb5_db_entry, which is -defined in the $<$krb5/kdb.h$>$ header file. - -\begin{verbatim} -typedef struct _krb5_encrypted_keyblock { - krb5_keytype keytype; - int length; - krb5_octet *contents; -} krb5_encrypted_keyblock; - -typedef struct _krb5_db_entry { - krb5_principal principal; - krb5_encrypted_keyblock key; - krb5_kvno kvno; - krb5_deltat max_life; - krb5_deltat max_renewable_life; - krb5_kvno mkvno; - - krb5_timestamp expiration; - krb5_timestamp pw_expiration; - krb5_timestamp last_pwd_change; - krb5_timestamp last_success; - - krb5_timestamp last_failed; - krb5_kvno fail_auth_count; - - krb5_principal mod_name; - krb5_timestamp mod_date; - krb5_flags attributes; - krb5_int32 salt_type:8, - salt_length:24; - krb5_octet *salt; - krb5_encrypted_keyblock alt_key; - krb5_int32 alt_salt_type:8, - alt_salt_length:24; - krb5_octet *alt_salt; - - krb5_int32 expansion[8]; -} krb5_db_entry; -\end{verbatim} - -The interpretation of most of these fields is the same as given in the -``Principals, ovsec_kadm_principal_ent_t'' section of the functional -specification. The fields that are not defined there are not used by -\secure{}; however, the admin server preserves the value of any fields -it does not understand. - -\section{Database Access Methods} - -\subsection{Principal and Policy Databases} - -This section describes the database abstraction used for the admin -principal and policy databases. Since both databases export -equivalent functionality, the API is only described once. The -character T is used to represent both ``princ'' and ``policy''. The -location of the principal database is defined by the \#define -PRINCIPAL_DB (``/krb5/ovsec_principal.db'') in $<$ovsec_admin/adb.h$>$. The -location of the policy database is defined by the \#define POLICY_DB -(``/krb5/ovsec_policy.db'') in $<$ovsec_admin/adb.h$>$. - -Note that this is {\it only} a database abstraction. All functional -intelligence, such as maintaining policy reference counts or sanity -checking, must be implemented above this layer. - -Prototypes for the osa functions are supplied in -$<$ovsec_admin/adb.h$>$. The routines can be found (in the first -relase) in ``stage/lib/libadb.a''. They require linking with the -Berkely DB library (``stage/lib/libdb.a''). [Note: We needed to remove -the dbm compatibility routines from libdb.a because we want to leave -KDB library alone in case somebody wants to run a stock MIT KDC with -our admin server.] - -The database routines use com_err for error codes. The error code -table name is ``adb'' and the offsets are the same as the order -presented here. The error table header file is -$<$ovsec_admin/adb_err.h$>$. Callers of the OSA routines should first call -init_adb_err_tbl() to initialize the database table. - -\begin{description} -\item[OSA_ADB_OK] Operation successful. -\item[OSA_ADB_FAILURE] General failure. -\item[OSA_ADB_DUP] Operation would create a duplicate database entry. -\item[OSA_ADB_NOENT] Named entry not in database. -\item[OSA_ADB_BAD_PRINC] The krb5_principal structure is invalid. -\item[OSA_ADB_BAD_POLICY] The specified policy name is invalid. -\item[OSA_ADB_XDR_FAILURE] The principal or policy structure cannot be -encoded for storage. -\end{description} - -Database functions can also return system errors. Unless otherwise -specified, database functions return OSA_ADB_OK. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_open_T(osa_adb_T_t *db, char *filename); -\end{verbatim} -% -Open the database named filename. Returns OSA_ADB_FAILURE if it -cannot open the database. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_close_T(osa_adb_T_t db); -\end{verbatim} -% -Close an open database. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_create_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} -% -Adds the entry to the database. All fields are defined. Returns -OSA_ADB_DUP if it already exists. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_destroy_T(osa_adb_T_t db, osa_T_t name); -\end{verbatim} - -Removes the named entry from the database. Returns OSA_ADB_NOENT if -it does not exist. - -\begin{verbatim} -osa_adb_ret_t -osa_adb_get_T(osa_adb_T_t db, osa_T_t name, - osa_princ_ent_t *entry); -\end{verbatim} - -Looks up the named entry in the db, and returns it in *entry in -allocated storage that must be freed with osa_adb_free_T. Returns -OSA_ADB_NOENT if name does not exist, OSA_ADB_MEM if memory cannot be -allocated. - -\begin{verbatim} -osa_adb_ret_t -osadb_adb_put_T(osa_adb_T_t db, osa_T_ent_t entry); -\end{verbatim} - -Modifies the existing entry named in entry. All fields must be filled -in. Returns OSA_DB_NOENT if the named entry does not exist. Note -that this cannot be used to rename an entry; rename is implemented by -deleting the old name and creating the new one (NOT ATOMIC!). - -\begin{verbatim} -void osa_adb_free_T(osa_T_ent_t); -\end{verbatim} - -Frees the memory associated with an osa_T_ent_t allocated by -osa_adb_get_T. - -\begin{verbatim} -typedef osa_adb_ret_t (*osa_adb_iter_T_func)(void *data, - osa_T_ent_t entry); - -osa_adb_ret_t osa_adb_iter_T(osa_adb_T_t db, osa_adb_iter_T_func func, - void *data); -\end{verbatim} - -Iterates over every entry in the database. For each entry ent in the -database db, the function (*func)(data, ent) is called. If func -returns an error code, osa_adb_iter_T returns an error code. If all -invokations of func return OSA_ADB_OK, osa_adb_iter_T returns -OSA_ADB_OK. The function func is permitted to access the database, -but the consequences of modifying the database during the iteration -are undefined. - -\subsection{Kerberos Database} - -Kerberos uses dbm to store krb5_db_entry records. It can be accessed -and modified in parallel with the Kerberos server, using functions -that are defined inside the KDC and the libkdb.a. - -\subsubsection{Database Manipulation Functions} - -The following functions are declared in \v{lib/kdb/kdb_dbm.c} in the -Kerberos sources and are available in libkdb.a. They can return the -following error codes; error codes that can be returned by any -function are indicated with a ``*'' and are not listed specifically -for each function. - -\begin{description} -\item[* KRB5_KDB_NOTINITED] The database is not open; call -krb5_dbm_db_init. -\item[* KRB5_KDB_CANTLOCK_DB] The necessary lock cannot be acquired. Try -again later. -\item[* system errors] An error occurred accessing the database files. -\item[KRB5_KDB_DB_INUSE] The database was modified without the use -of proper locking.\footnote{This error occurs when the entire database -is swapped out from the under the process, say by a kdb5_edit restore. -It can only be returned by krb5_db_get_principal. It is not yet clear -what a program should do when it gets this error.} -\item[KRB5_KDB_NOENTRY] The principal to be deleted is not -in the database. -\end{description} - -\begin{verbatim} -krb5_dbm_db_init(void) -\end{verbatim} - -Opens the Kerberos database file (but does not actually call -dbm_open). This can be called even if the database is already open, -in which case it just returns success. - -\begin{verbatim} -krb5_dbm_db_fini(void) -\end{verbatim} - -Closes the database file; this MUST be called before the process -exits. Returns KRB5_KDB_DBNOTINITED if the database isn't open, but -that isn't really a fatal error. - -\begin{verbatim} -krb5_dbm_get_principal(krb5_principal searchfor, - krb5_db_entry *entries, int *nentries, krb5_boolean *more) -\end{verbatim} - -Search the database for the principal searchfor and write the results -into *entries. The interface is set up to handle wildcard gets, but -the code doesn't handle it: *nentries is assumed to be 1, and *more is -always returned as 0. - -This function does not retry if the database cannot be locked; that is -up to the caller. - -Returns KRB5_KDB_DB_INUSE. - -\begin{verbatim} -krb5_dbm_put_principal(krb5_db_entry *entries, int *nentries) -\end{verbatim} - -Stores *nentries elements from the entries array into the database. -On return *nentries is set to the number of entries actually written; -the first *nentries entries will have been written, even if an error -pis returned. - -This function does not retry if the database cannot be locked; that is -up to the caller. - -\begin{verbatim} -krb5_dbm_db_delete_principal(krb5_principal searchfor, int *nentries) -\end{verbatim} - -Removes the principal searchfor from the database. nentries will be -set to 0 or 1 on output, indicating the number of entries deleted (the -code does not currently support wildcards). - -Returns KRB5_KDB_NOENTRY. - -\begin{verbatim} -typedef krb5_error_code (*iter_func)(krb5_pointer, krb5_db_entry *); - -krb5_dbm_db_iterate(iter_func func, krb5_point func_arg) -\end{verbatim} - -Calls (*func)(func_arg, entry) for every entry in the database. If -func returns an error code, the iteration stops and that error code is -returned. - -Returns func error codes. - -\begin{verbatim} -void krb5_dbm_db_free_principal(krb5_db_entry *entries, int nentries) -\end{verbatim} - -Frees entries returned by krb5_dbm_db_get_principal. nentries entries -in the array entries will be freed. - -\subsubsection{Initialization and Key Access} - -Keys stored in the Kerberos database are encrypted in the Kerberos -master key. The admin server will therefore have to acquire the key -before it can perform any key-changing operations, and will have to -decrypt and encrypt the keys retrieved from and placed into the -database via krb5_db_get_principal and _put_principal. This section -describes the internal admin server API that will be used to perform -these functions. - -\begin{verbatim} -krb5_principal master_princ; -krb5_encrypt_block master_encblock; -krb5_keyblock master_keyblock; - -void kdc_init_master() -\end{verbatim} - -kdc_init_master opens the database and acquires the master key. It -also sets the global variables master_princ, master_encblock, and -master_keyblock: - -\begin{itemize} -\item master_princ is set to the name of the Kerberos master principal -(\v{K/M@REALM}). - -\item master_encblock is something I have no idea about. - -\item master_keyblock is the Kerberos master key -\end{itemize} - -\begin{verbatim} -krb5_error_code kdb_get_entry_and_key(krb5_principal principal, - krb5_db_entry *entry, - krb5_keyblock *key) -\end{verbatim} - -kdb_get_entry_and_key retrieves the named principal's entry from the -database in entry, and decrypts its key into key. The caller must -free entry with krb5_dbm_db_free_principal and free key-$>$contents with -free.\footnote{The caller should also \v{memset(key-$>$contents, 0, -key-$>$length)}. There should be a function krb5_free_keyblock_contents -for this, but there is not.} - -\begin{verbatim} -krb5_error_code kdb_put_entry_pw(krb5_db_entry *entry, char *pw) -\end{verbatim} - -kdb_put_entry_pw stores entry in the database. All the entry values -must already be set; this function does not change any of them except -the key. pw, the NULL-terminated password string, is converted to a -key using string-to-key with the salt type specified in -entry-$>$salt_type.\footnote{The salt_type should be set based on the -command line arguments to the kadmin server (see the ``Command Line'' -section of the functional specification).} - -\section{Admin Principal and Policy Database Implementation} - -The admin principal and policy databases will each be stored in a -single hash table, implemented by the Berkeley 4.4BSD db library. -Each record will consist of an entire osa_T_ent_t. The key into the -hash table is the entry name (for principals, the ASCII representation -of the name). The value is the T entry structure. Since the key and -data must be self-contained, with no pointers, the Sun xdr mechanisms -will be used to marshal and unmarshal data in the database. - -The server in the first release will be single-threaded in that a -request will run to completion (or error) before the next will run, -but multiple connections will be allowed simultaneously. - -\section{ACLs, acl_check} - -The ACL mechanism described in the ``Authorization ACLs'' section of -the functional specifications will be implemented by the acl_check -function. - -\begin{verbatim} -enum access_t { - ACCESS_DENIED = 0, - ACCESS_OK = 1, -}; - -enum access_t acl_check(krb5_principal princ, char *priv); -\end{verbatim} - -The priv argument must be one of ``get'', ``add'', ``delete'', or -``modify''. acl_check returns 1 if the principal princ has the named -privilege, 0 if it does not. - -\section{Function Details} - -This section discusses specific design issues for Admin API functions -that are not addresed by the functional specifications. - -\subsection{ovsec_kadm_create_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -The principal's initial key is not stored in the key history array at -creation time. - -\subsection{ovsec_kadm_delete_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -\subsection{ovsec_kadm_modify_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -If pw_history_num changes and the new value $n$ is smaller than the -current value of num_old_keys, old_keys should end up with the $n$ -most recent keys; these are found by counting backwards $n$ elements -in old_keys from next_old_key. next_old_keys should then be reset to -0, the oldest of the saved keys, and num_old_keys set to $n$, the -new actual number of old keys in the array. - -\subsection{ovsec_kadm_chpass_principal, randkey_principal} - -The algorithm for determining whether a password is in the principal's -key history is complicated by the use of the kadmin/history \k{h} -encrypting key. - -\begin{enumerate} -\item For ovsec_kadm_chpass_principal, convert the password to a key -using string-to-key and the salt method specified by the command line -arguments. - -\item If the POLICY bit is set and pw_history_num is not zero, check -if the new key is in the history. -\begin{enumerate} -\item Retrieve the principal's current key and decrypt it with \k{M}. -If it is the same as the new key, return OVSEC_KADM_PASS_REUSE. -\item Retrieve the kadmin/history key \k{h} and decrypt it with \k{M}. -\item Encrypt the principal's new key in \k{h}. -\item If the principal's new key encrypted in \k{h} is in old_keys, -return OVSEC_KADM_PASS_REUSE. -\item Encrypt the principal's current key in \k{h} and store it in -old_keys. -\item Erase the memory containing \k{h}. -\end{enumerate} - -\item Encrypt the principal's new key in \k{M} and store it in the -database. -\item Erase the memory containing \k{M}. -\end{enumerate} - -To store the an encrypted key in old_keys, insert it as the -next_old_key element of old_keys, and increment next_old_key by one -modulo pw_history_num. - -\subsection{ovsec_kadm_get_principal} - -If the named principal exists in either the Kerberos or admin -principal database, but not both, return OVSEC_KADM_BAD_DB. - -\end{document} diff --git a/doc/kadm5/api-unit-test.tex b/doc/kadm5/api-unit-test.tex deleted file mode 100644 index acc68602e..000000000 --- a/doc/kadm5/api-unit-test.tex +++ /dev/null @@ -1,2121 +0,0 @@ -\documentstyle[times,fullpage,rcsid]{article} - -\rcs$Header$ - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Make _ actually generate an _, and allow line-breaking after it. -\let\underscore=\_ -\catcode`_=13 -\def_{\underscore\penalty75\relax} -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\newcommand{\test}[1]{\begin{description} -\setlength{\itemsep}{0pt} -#1 -\end{description} - -} - -\newcommand{\numtest}[2]{\begin{description} -\setlength{\itemsep}{0pt} -\Number{#1} -#2 -\end{description} - -} - -\newcommand{\Number}[1]{\item[Number:] #1} -\newcommand{\Reason}[1]{\item[Reason:] #1} -%\newcommand{\Call}[1]{\item[Call:] #1} -\newcommand{\Expected}[1]{\item[Expected:] #1} -\newcommand{\Conditions}[1]{\item[Conditions:] #1} -\newcommand{\Priority}[1]{\item[Priority:] #1} -\newcommand{\Status}[1]{\item[Status:] #1} -%\newcommand{\Number}[1]{} -%\newcommand{\Reason}[1]{} -\newcommand{\Call}[1]{} -%\newcommand{\Expected}[1]{} -%\newcommand{\Conditions}[1]{} -%\newcommand{\Priority}[1]{} - -\title{OpenV*Secure 1.0 Admin API\\ -Unit Test Description\footnote{\rcsHeader}} -\author{Jonathan I. Kamens} - -\begin{document} - -\maketitle - -%\tableofcontents - -\section{Introduction} - -The following is a description of a black-box unit test of the -OpenV*Secure Admin API. Each API function is listed, followed by the -tests that shoud be performed on it. - -The tests described here are based on the ``OV*Secure Admin Functional -Specifications'' revision 1.41, dated August 18, 1994. - -Since inter-realm functionality is not a requirement for OpenV*Secure -1.0, it is not tested. - -All tests which test for success should verify, using some means other -than the return value of the function being tested, that the requested -operation was successfully performed. For example: for init, test -that other operations can be performed after init; for destroy, test -that other operations can't be performed after destroy; for modify -functions, verify that all modifications to the database which should -have taken place did, and that the new, modified data is in effect; -for get operations, verify that the data retrieved is the data that -should actually be in the database. - -As of now the tests are being re-worked to use database comparision routines -simular to the GUI tests. This routines are not completly in place yet. The -purpose for using these routines is for better detection of incorrect -database modification. - -Similarly, all tests which test for failure should verify that the -no component of the requested operation took place. For example: if -init fails, other operations should not work. If a modify fails, all -data in the database should be the same as it was before the attempt -to modify, and the old data should still be what is enforced. -Furthermore, tests which test for failure should verify that the -failure code returned is correct for the specific failure condition -tested. - -Most of the tests listed below should be run twice -- once locally on -the server after linking against the server API library, and once -talking to the server via authenticated Sun RPC after linking against -the client API library. Tests which should only be run locally or via -RPC are labelled with a ``local'' or ``RPC''. - -Furthermore, in addition to the tests labelled below, a test should be -implemented to verify that a client can't perform operations on the -server through the client API library when it's linked against -standard Sun RPC instead of OpenV*Secure's authenticated Sun RPC. -This will require a client with a modified version of ovsec_kadm_init -which doesn't call auth_gssapi_create. This client should call this -modified ovsec_kadm_init and then call some other admin API function, -specifying arguments to both functions that would work if the -authenticated Sun RPC had been used, but shouldn't if authentication -wasn't used. The test should verify that the API function call after -the init doesn't succeed. - -\section{ovsec_kadm_init} - -\numtest{1}{ -\Reason{An empty string realm is rejected.} -\Status{Implemented} -} - -\numtest{2}{ -\Reason{A realm containing invalid characters is rejected.} -\Status{Implemented} -} - -\numtest{2.5}{ -\Reason{A non-existent realm is rejected.} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{A bad service name representing an existing principal - (different from the client principal) is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{4}{ -\Reason{A bad service name representing a non-existent - principal is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{A bad service name identical to the (existing) client - name is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{6}{ -\Reason{A null password causes password prompting.} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{An empty-string causes password prompting} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{An incorrect password which is the password of another - user is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{9}{ -\Reason{An incorrect password which isn't the password of any - user is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{10}{ -\Reason{A null client_name is rejected.} -\Status{Implemented} -} - -% Empty string client name is legal. -%\numtest{11}{ -%\Reason{An empty-string client_name is rejected.} -%} - -\numtest{12}{ -\Reason{A client_name referring to a non-existent principal in - the default realm is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{13}{ -\Reason{A client_name referring to a non-existent principal - with the local realm specified explicitly is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{14}{ -\Reason{A client_name referring to a non-existent principal in - a nonexistent realm is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{15}{ -\Reason{A client_name referring to an existing principal in a - nonexistent realm is rejected.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{16}{ -\Reason{Valid invocation.} -\Status{Implemented} -} - -\numtest{17}{ -\Reason{Valid invocation (explicit client realm).} -\Status{Implemented} -} - -\numtest{18}{ -\Reason{Valid invocation (CHANGEPW_SERVICE).} -\Status{Implemented} -} - -\numtest{19}{ -\Reason{Valid invocation (explicit service realm).} -\Status{Implemented} -} - -\numtest{20}{ -\Reason{Valid invocation (database access allowed after init).} -\Status{Implemented} -} - -%\numtest{21}{ -%\Reason{Init fails when called twice in a row.} -%\Status{Implemented} -%} - -\numtest{22}{ -\Reason{A null password causes master-key prompting.} -\Conditions{local} -\Status{Implemented} -} - -\numtest{22.5}{ -\Reason{A empty string password causes master-key prompting.} -\Conditions{local} -\Status{Implemented} -} - -%\numtest{23}{ -%\Reason{A non-null password causes reading from the kstash.} -%\Conditions{local} -%\Status{Implemented} -%} - -\numtest{24}{ -\Reason{Null service name is ignored in local invocation.} -\Conditions{local} -\Status{Implemented} -} - -\numtest{25}{ -\Reason{Non-null service name is ignored in local invocation.} -\Conditions{local} -\Status{Implemented} -} - -%\numtest{26}{ -%\Reason{Can't do ``get'' operation before calling init.} -%\Status{Implemented} -%} - -%\numtest{27}{ -%\Reason{Can't do ``add'' operation before calling init.} -%\Status{Implemented} -%} - -\%numtest{28}{ -%\Reason{Can't do ``modify'' operation before calling init.} -%\Status{Implemented} -%} - -%\numtest{29}{ -%\Reason{Can't do ``delete'' operation before calling init.} -%\Status{Implemented} -%} - -\numtest{30}{ -\Reason{Can init after failed init attempt.} -\Conditions{local} -\Status{Implemented} -} - -\section{ovsec_kadm_destroy} - -\numtest{1}{ -\Reason{Valid invocation.} -\Status{Implemented} -} - -%\numtest{2}{ -%\Reason{Valid invocation (``get'' not allowed after destroy).} -%\Status{Implemented} -%} - -%\numtest{3}{ -%\Reason{Valid invocation (``add'' not allowed after destroy).} -%\Status{Implemented} -%} - -%\numtest{4}{ -%\Reason{Valid invocation (``modify'' not allowed after destroy).} -%\Status{Implemented} -%} - -%\numtest{5}{ -%\Reason{Valid invocation (``delete'' not allowed after destroy).} -%\Status{Implemented} -%} - -%\numtest{6}{ -%\Reason{Fails if database not initialized.} -%\Status{Implemented} -%} - -%\numtest{7}{ -%\Reason{Fails if invoked twice in a row.} -%\Status{Implemented} -%} - -\numtest{8}{ -\Reason{Database can be reinitialized after destroy.} -\Status{Implemented} -} - -\section{ovsec_kadm_create_principal} - -%In the tests below, ``getu'' refers to a user who has only ``get'' access, -%''addu'' refers to a user who has only ``add'' access, ``modifyu'' refers to -%a user who has only ``modify'' access, and ``deleteu'' refers to a user -%who has only ``delete'' access. ``amu'' refers to a user with ``add'' and -%''modify'' access. ``new_princ'' refers to a principal entry structure -%filled in as follows: -% -% krb5_parse_name("newuser", \&new_princ.principal); -% krb5_timeofday(\&new_princ.princ_expire_time); -% new_princ.princ_expire_time += 130; -% krb5_timeofday(\&new_princ.last_pwd_change); -% new_princ.last_pwd_change += 140; -% krb5_timeofday(\&new_princ.pw_expiration); -% new_princ.pw_expiration += 150; -% new_princ.max_life = 160; -% krb5_parse_name("usera", \&new_princ.mod_name); -% krb5_timeofday(\&new_princ.mod_date); -% new_princ.mod_date += 170; -% new_princ.attributes = 0xabcdabcd; -% new_princ.kvno = 180; -% new_princ.mkvno = 190; -% new_princ.policy = null; -% new_princ.aux_attributes = 0xdeadbeef; -% -%The offsets of 130 through 190 above are used to ensure that the -%fields are all known to be different from each other, so that -%accidentally switched fields can be detected. Some of the fields in -%this structure may be changed by the tests, but they should clean up -%after themselves. - -%\numtest{1}{ -%\Reason{Fails if database not initialized.} -%\Status{Implemented} -%} - -\numtest{2}{ -\Reason{Fails on null princ argument.} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{Fails on null password argument.} -\Status{Implemented} -} - -\numtest{4}{ -\Reason{Fails on empty-string password argument.} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{Fails when mask contains undefined bit.} -\Status{Implemented} -} - -\numtest{6}{ -\Reason{Fails when mask contains LAST_PWD_CHANGE bit.} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{Fails when mask contains MOD_TIME bit.} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{Fails when mask contains MOD_NAME bit.} -\Status{Implemented} -} - -\numtest{9}{ -\Reason{Fails when mask contains MKVNO bit.} -\Status{Implemented} -} - -\numtest{10}{ -\Reason{Fails when mask contains AUX_ATTRIBUTES bit.} -\Status{Implemented} -} - -\numtest{11}{ -\Reason{Fails when mask contains POLICY_CLR bit.} -\Status{Implemented} -} - -\numtest{12}{ -\Reason{Fails for caller with no access bits.} -\Status{Implemented} -} - -\numtest{13}{ -\Reason{Fails when caller has ``get'' access and not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{14}{ -\Reason{Fails when caller has ``modify'' access and not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{15}{ -\Reason{Fails when caller has ``delete'' access and not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{16}{ -\Reason{Fails when caller connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{17}{ -\Reason{Fails on attempt to create existing principal.} -\Status{Implemented} -} - -\numtest{18}{ -\Reason{Fails when password is too short.} -\Status{Implemented} -} - -\numtest{19}{ -\Reason{Fails when password has too few classes.} -\Status{Implemented} -} - -\numtest{20}{ -\Reason{Fails when password is in dictionary.} -\Status{Implemented} -} - -\numtest{21}{ -\Reason{Nonexistent policy is rejected.} -\Status{Implemented} -} - -\numtest{22}{ -\Reason{Fails on invalid principal name.} -\Status{Implemented} -} - -\numtest{23}{ -\Reason{Valid invocation.} -\Status{Implemented} -} - -\numtest{24}{ -\Reason{Succeeds when caller has ``add'' access and another one.} -\Status{Implemented} -} - -%\numtest{25}{ -%\Reason{Fails when password is too short, when override_qual is true.} -%} - -%\numtest{26}{ -%\Reason{Fails when password has too few classes, when -% override_qual is true.} -%} - -%\numtest{27}{ -%\Reason{Fails when password is in dictionary, when override_qual is -% true.} -%} - -\numtest{28}{ -\Reason{Succeeds when assigning policy.} -\Status{Implemented} -} - -\numtest{29}{ -\Priority{High} -\Reason{Allows 0 (never) for princ_expire_time.} -\Status{Implemented} -} - -\numtest{30}{ -\Reason{Allows 0 (never) for pw_expiration when there's no policy.} -\Status{Implemented} -} - -\numtest{31}{ -\Reason{Allows 0 (never) for pw_expiration when there's a policy with - 0 for pw_max_life.} -\Status{Implemented} -} - -\numtest{32}{ -\Reason{Accepts 0 (never) for pw_expiration when there's a policy with - non-zero pw_max_life, but actually sets pw_expiration to now + - pw_max_life.} -\Status{Implemented} -} - -\numtest{33}{ -\Reason{Accepts and sets non-zero pw_expiration when no policy.} -\Status{Implemented} -} - -\numtest{34}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with zero pw_max_life.} -\Status{Implemented} -} - -\numtest{35}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with pw_max_life later than the specified pw_expiration.} -\Status{Implemented} -} - -\numtest{36}{ -\Reason{Accepts non-zero pw_expiration and limits it to now + - pw_max_life when it's later than now + non-zero pw_max_life in - policy.} -\Status{Implemented} -} - -\numtest{37}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if there's no policy and no - specified pw_expiration.} -\Status{Implemented} -} - -\numtest{38}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if it isn't specified and the - policy has a 0 (never) pw_max_life.} -\Status{Implemented} -} - -\numtest{39}{ -\Priority{High} -\Reason{Sets pw_expiration to now + pw_max_life if it isn't specified - and the policy has a non-zero pw_max_life.} -\Status{Implemented} -} - -\numtest{40}{ -\Priority{High} -\Reason{Allows 0 (forever) for max_life.} -\Status{Implemented} -} - -\numtest{41}{ -\Priority{High} -\Reason{Doesn't modify or free mod_name on success.} -} - -\numtest{42}{ -\Priority{High} -\Reason{Doesn't modify or free mod_name on failure.} -} - -\section{ovsec_kadm_delete_principal} - -%\numtest{1}{ -%\Reason{Fails if database not initialized.} -%\Status{Implemented} -%} - -\numtest{2}{ -\Reason{Fails on null principal.} -\Status{Implemented} -} - -% Empty string principal is legal. -%\numtest{3}{ -%\Reason{Fails on empty-string principal.} -%} - -% There is not invalid principal names -%\numtest{4}{ -%\Reason{Fails on invalid principal name.} -%} - -\numtest{5}{ -\Priority{High} -\Reason{Fails on nonexistent principal.} -\Status{Implemented} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails when caller connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails if caller has ``add'' access and not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails if caller has ``modify'' access and not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{9}{ -\Priority{High} -\Reason{Fails if caller has ``get'' access and not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{10}{ -\Priority{High} -\Reason{Fails if caller has no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{11}{ -\Priority{High} -\Reason{Valid invocation.} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Valid invocation (on principal with policy).} -\Status{Implemented} -} - - - -\section{ovsec_kadm_modify_principal} - -%\numtest{1}{ -%\Reason{Fails if database not initialized.} -%\Status{Implemented} -%} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if user connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{Fails on mask with undefined bit set.} -\Status{Implemented} -} - -\numtest{4}{ -\Reason{Fails on mask with PRINCIPAL set.} -\Status{Implemented} -} - -\numtest{5}{ -\Priority{High} -\Reason{Fails on mask with LAST_PWD_CHANGE set.} -\Status{Implemented} -} - -\numtest{6}{ -\Reason{Fails on mask with MOD_TIME set.} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{Fails on mask with MOD_NAME set.} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{Fails on mask with MKVNO set.} -\Status{Implemented} -} - -\numtest{9}{ -\Priority{High} -\Reason{Fails on mask with AUX_ATTRIBUTES set.} -\Status{Implemented} -} - -\numtest{10}{ -\Reason{Fails on nonexistent principal.} -\Status{Implemented} -} - -\numtest{11}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for user with ``get'' access.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{13}{ -\Priority{High} -\Reason{Fails for user with ``add'' access.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{14}{ -\Priority{High} -\Reason{Fails for user with ``delete'' access.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{15}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' access.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{16}{ -\Reason{Succeeds for user with ``modify'' and another access.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{17}{ -\Priority{High} -\Reason{Fails when nonexistent policy is specified.} -\Status{Implemented} -} - -\numtest{18}{ -\Priority{High} -\Reason{Succeeds when existent policy is specified.} -\Status{Implemented} -} - -\numtest{19}{ -\Reason{Updates policy count when setting policy from none.} -\Status{Implemented} -} - -\numtest{20}{ -\Reason{Updates policy count when clearing policy from set.} -\Status{Implemented} -} - -\numtest{21}{ -\Reason{Updates policy count when setting policy from other policy.} -\Status{Implemented} -} - -\numtest{21.5}{ -\Reason{Policy reference count remains unchanged when policy is - changed to itself.} -\Status{Implemented.} -} - -\numtest{22}{ -\Reason{Allows 0 (never) for pw_expiration when there's no policy.} -\Status{Implemented} -} - -\numtest{23}{ -\Reason{Allows 0 (never) for pw_expiration when there's a policy with - 0 for pw_max_life.} -\Status{Implemented} -} - -\numtest{24}{ -\Reason{Accepts 0 (never) for pw_expiration when there's a policy with - non-zero pw_max_life, but actually sets pw_expiration to - last_pwd_change + pw_max_life.} -\Status{Implemented} -} - -\numtest{25}{ -\Reason{Accepts and sets non-zero pw_expiration when no policy.} -\Status{Implemented} -} - -\numtest{26}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with zero pw_max_life.} -\Status{Implemented} -} - -\numtest{27}{ -\Reason{Accepts and sets non-zero pw_expiration when there's a policy - with pw_max_life later than the specified pw_expiration.} -\Status{Implemented} -} - -\numtest{28}{ -\Reason{Accepts non-zero pw_expiration and limits it to last_pwd_change + - pw_max_life when it's later than last_pwd_change + non-zero - pw_max_life in policy.} -\Status{Implemented} -} - -\numtest{29}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if there's no policy and no - specified pw_expiration.} -\Status{Implemented} -} - -\numtest{30}{ -\Priority{High} -\Reason{Sets pw_expiration to 0 (never) if it isn't specified and the - policy has a 0 (never) pw_max_life.} -\Status{Implemented} -} - -\numtest{31}{ -\Priority{High} -\Reason{Sets pw_expiration to now + pw_max_life if it isn't specified - and the policy has a non-zero pw_max_life.} -\Status{Implemented} -} - -\numtest{32}{ -\Priority{High} -\Reason{Accepts princ_expire_time change.} -\Status{Implemented} -} - - - -\numtest{33}{ -\Priority{High} -\Reason{Accepts attributes change.} -\Status{Implemented} -} - -\numtest{33.25}{ -\Priority{High} -\Reason{Accepts attributes change (KRB5_KDB_REQUIRES_PW_CHANGE).} -\Status{Implemented} -} - -\numtest{33.5}{ -\Priority{High} -\Reason{Accepts attributes change (KRB5_DISALLOW_TGT_BASE).} -\Status{Implemented} -} - -\numtest{33.75}{ -\Priority{High} -\Reason{Accepts attributes change (KRB5_PW_CHANGE_SERVICE).} -\Status{Implemented} -} - -\numtest{34}{ -\Priority{High} -\Reason{Accepts max_life change.} -\Status{Implemented} -} - -\numtest{35}{ -\Priority{High} -\Reason{Accepts kvno change.} -\Status{Implemented} -} - -\numtest{36}{ -\Reason{Behaves correctly when policy is set to the same as it was - before.} -\Status{Implemented} -} - -\numtest{37}{ -\Reason{Behaves properly when POLICY_CLR is specified and there was no - policy before.} -\Status{Implemented} -} - -\numtest{38}{ -\Priority{High} -\Reason{Accepts 0 (never) for princ_expire_time.} -\Status{Implemented} -} - -\numtest{39}{ -\Priority{High} -\Reason{Accepts 0 for max_life.} -\Status{Implemented} -} - -\numtest{40}{ -\Reason{Rejects null principal argument.} -\Status{Implemented} -} - -\numtest{41}{ -\Priority{High} -\Reason{Doesn't modify or free mod_name on success.} -} - -\numtest{42}{ -\Priority{High} -\Reason{Doesn't modify or free mod_name on failure.} -} - - -\section{ovsec_kadm_rename_principal} - -%\numtest{1}{ -%\Reason{Fails if database not initialized.} -%\Status{Implemented} -%} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if user connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{4}{ -\Reason{Fails for user with ``modify'' access and not ``add'' or -``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{Fails for user with ``get'' access and not ``add'' or -``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{6}{ -\Reason{Fails for user with ``modify'' and ``add'' but not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{Fails for user with ``modify'' and ``delete'' but not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{Fails for user with ``get'' and ``add'' but not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{9}{ -\Reason{Fails for user with ``get'' and ``delete'' but not ``add.''} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{10}{ -\Reason{Fails for user with ``modify'', ``get'' and ``add'', but not - ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{11}{ -\Reason{Fails for user with ``modify'', ``get'' and ``delete'', but - not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{13}{ -\Priority{High} -\Reason{Fails for user with ``delete'' but not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{14}{ -\Priority{High} -\Reason{Succeeds for user with ``add'' and ``delete''.} -\Status{Implemented} -} - -\numtest{15}{ -\Priority{High} -\Reason{Fails if target principal name exists.} -\Status{Implemented} -} - - - -\section{ovsec_kadm_chpass_principal} -\label{ovseckadmchpassprincipal} - -\subsection{Quality/history enforcement tests} - -This section lists a series of tests which will be run a number of -times, with various parameter settings (e.g., which access bits user -has, whether user connected with ADMIN_SERVICE or CHANGEPW_SERVICE, -etc.). The table following the -list of tests gives the various parameter settings under which the -tests should be run, as well which should succeed and which should -fail for each choice of parameter settings. - -\subsubsection{List of tests} - -The test number of each of these tests is an offset from the base -given in the table below. - -\numtest{1}{ -\Priority{High} -\Reason{With history setting of 1, change password to itself.} -} - -\numtest{2}{ -\Reason{With history setting of 2 but no password changes since - principal creation, change password to itself.} -} - -\numtest{3}{ -\Reason{With history setting of 2 and one password change since - principal creation, change password to itself - and directly previous password.} -} - -\numtest{4}{ -\Priority{High} -\Reason{With a history setting of 3 and no password changes, - change password to itself.} -} - -\numtest{5}{ -\Priority{High} -\Reason{With a history setting of 3 and 1 password change, - change password to itself or previous password.} -} - -\numtest{6}{ -\Priority{High} -\Reason{With a history setting of 3 and 2 password changes, - change password to itself and the two previous passwords.} -} - -\numtest{7}{ -\Priority{High} -\Reason{Change to previously unused password when now - - last_pwd_change $<$ pw_min_life.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Change to previously unused password that doesn't contain enough - character classes.} -} - -\numtest{9}{ -\Priority{High} -\Reason{Change to previously unused password that's too short.} -} - -\numtest{10}{ -\Priority{High} -\Reason{Change to previously unused password that's in the dictionary.} -} - -\subsubsection{List of parameter settings} - -In the table below, ``7 passes'' means that test 7 above passes and -the rest of the tests fail. - -\begin{tabular}{llllll} -Base & Modify access? & Own password? & Service & Pass/Fail \\ \hline -0 & No & Yes & ADMIN & all fail \\ -20 & No & Yes & CHANGEPW & all fail \\ -40 & No & No & ADMIN & all fail \\ -60 & No & No & CHANGEPW & all fail \\ -80 & Yes & Yes & ADMIN & 7 passes \\ -100 & Yes & Yes & CHANGEPW & all fail \\ -120 & Yes & No & ADMIN & 7 passes \\ -140 & Yes & No & CHANGEPW & all fail \\ -\end{tabular} - -\subsection{Other quality/history tests} - -\numtest{161}{ -\Priority{High} -\Reason{With history of 1, can change password to anything other than - itself that doesn't conflict with other quality - rules.} -} - -\numtest{162}{ -\Reason{With history of 2 and 2 password changes, can change password - to original password.} -} - -\numtest{163}{ -\Priority{High} -\Reason{With history of 3 and 3 password changes, can change password - to original password.} -} - -\numtest{164}{ -\Priority{High} -\Reason{Can change password when now - last_pwd_change $>$ pw_min_life.} -} - -\numtest{165}{ -\Priority{High} -\Reason{Can change password when it contains exactly the number of - classes required by the policy.} -} - -\numtest{166}{ -\Priority{High} -\Reason{Can change password when it is exactly the length required by - the policy.} -} - -\numtest{167}{ -\Priority{High} -\Reason{Can change password to a word that isn't in the dictionary.} -} - - -\subsection{Other tests} - -%\numtest{168}{ -%\Reason{Fails if database not initialized.} -%} - -\numtest{169}{ -\Reason{Fails for non-existent principal.} -} - -\numtest{170}{ -\Reason{Fails for null password.} -} - -\numtest{171}{ -\Priority{High} -\Reason{Fails for empty-string password.} -} - -\numtest{172}{ -\Priority{High} -\Reason{Pw_expiration is set to now + max_pw_life if policy exists and - has non-zero max_pw_life.} -} - -\numtest{173}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if policy exists and has zero - max_pw_life.} -} - -\numtest{174}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if no policy.} -} - -\numtest{175}{ -\Priority{High} -\Reason{KRB5_KDC_REQUIRES_PWCHANGE bit is cleared when password is - successfully changed.} -} - -\numtest{176}{ -\Priority{High} -\Reason{Fails for user with no access bits, on other's password.} -} - -\numtest{177}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify'' access, on - other's password.} -} - -\numtest{178}{ -\Reason{Fails for user with ``delete'' but not ``modify'' access, on - other's password.} -} - -\numtest{179}{ -\Reason{Fails for user with ``add'' but not ``modify'' access, on - other's password.} -} - -\numtest{180}{ -\Reason{Succeeds for user with ``get'' and ``modify'' access, on - other's password.} -\Status{Implemented} -} - -\numtest{180.5}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' but not ``get'' access, on - other's password.} -\Conditions{RPC} -\Status{Implemented} -} -\numtest{180.625}{ -\Priority{High} -\Reason{Fails for user with modify when connecting with CHANGEPW_SERVICE on - others password} -\Conditions{RPC} -\Status{Implemented} -} -\numtest{180.75}{ -\Priority{High} -\Reason{Fails for user with modify when connecting with CHANGEPW_SERVICE - on other's password which has expired} -\Conditions{RPC} -\Status{Implemented} -} - -%\numtest{181}{ -%\Reason{Password that would succeed if override_qual were false fails -% if override_qual is true.} -%\Expected{Returns CANNOT_OVERRIDE.} -%} - -\numtest{182}{ -\Priority{High} -\Reason{Can not change key of ovsec_adm/history principal.} -\Status{Implemented} -} - - - -\section{ovsec_kadm_chpass_principal_util} - -Rerun all the tests listed for ovsec_kadm_chpass_principal above in -Section \ref{ovseckadmchpassprincipal}. Verify that they succeed -and fail in the same circumstances. Also verify that in each failure -case, the error message returned in msg_ret is as specified in the -functional specification. - -Also, run the following additional tests. - -\numtest{1}{ -\Reason{Null msg_ret is rejected.} -} - -\numtest{2}{ -\Priority{High} -\Reason{New password is put into pw_ret, when it's prompted for.} -} - -\numtest{3}{ -\Priority{High} -Reason{New password is put into pw_ret, when it's supplied by the - caller.} -} - -\numtest{4}{ -\Priority{High} -\Reason{Successful invocation when pw_ret is null.} -} - - - -\section{ovsec_kadm_randkey_principal} - -\subsection{TOOSOON enforcement tests} - -This test should be run a number of times, as indicated in the table -following it. The table also indicates the expected result of each -run of the test. - -\test{ -\Reason{Change key when now - last_pwd_change $<$ pw_min_life.} -} - -\subsubsection{List of parameter settings} - -\begin{tabular}{llllll} -Number & Modify Access? & Own Key? & Service & Pass/Fail & Implemented? \\ \hline -1 & No & Yes & ADMIN & fail & Yes \\ -3 & No & Yes & CHANGEPW & fail & Yes \\ -5 & No & No & ADMIN & fail \\ -7 & No & No & CHANGEPW & fail \\ -9 & Yes & Yes & ADMIN & pass \\ -11 & Yes & Yes & CHANGEPW & fail \\ -13 & Yes & No & ADMIN & pass & Yes \\ -15 & Yes & No & CHANGEPW & fail & Yes \\ -\end{tabular} - -\subsection{Other tests} - -\numtest{17}{ -\Reason{Fails if database not initialized.} -} - -\numtest{18}{ -\Reason{Fails for non-existent principal.} -} - -\numtest{19}{ -\Reason{Fails for null keyblock pointer.} -} - -\numtest{20}{ -\Priority{High} -\Reason{Pw_expiration is set to now + max_pw_life if policy exists and - has non-zero max_pw_life.} -} - -\numtest{21}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if policy exists and has zero - max_pw_life.} -} - -\numtest{22}{ -\Priority{High} -\Reason{Pw_expiration is set to 0 if no policy.} -} - -\numtest{23}{ -\Priority{High} -\Reason{KRB5_KDC_REQUIRES_PWCHANGE bit is cleared when key is - successfully changed.} -} - -\numtest{24}{ -\Priority{High} -\Reason{Fails for user with no access bits, on other's password.} -} - -\numtest{25}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify'' access, on - other's password.} -} - -\numtest{26}{ -\Reason{Fails for user with ``delete'' but not ``modify'' access, on - other's password.} -} - -\numtest{27}{ -\Reason{Fails for user with ``add'' but not ``modify'' access, on - other's password.} -} - -\numtest{28}{ -\Reason{Succeeds for user with ``get'' and ``modify'' access, on - other's password.} -\Status{Implemented} -} -\numtest{28.25}{ -\Priority{High} -\Reason{Fails for user with get and modify access on others password - When conneceted with CHANGEPW_SERVICE} -\Status{Implemented} -} - -\numtest{28.5}{ -\Priority{High} -\Reason{Succeeds for user with ``modify'' but not ``get'' access, on - other's password.} -\Status{Implemented} - -} - -\numtest{29}{ -\Reason{The new key that's assigned is truly random. XXX not sure how - to test this.} -} - -\numtest{30}{ -\Reason{Succeeds for own key, no other access bits when connecting with CHANGEPW service} -\Status{Implemented} -} -\numtest{31}{ -\Reason{Succeeds for own key, no other access bits when connecting with ADMIM service} -\Status{Implemented} -} -\numtest{32}{ -\Reason{Cannot change ovsec_adm/history key} -\Status{Implemented} -} - - -\section{ovsec_kadm_get_principal} - -\numtest{1}{ -\Reason{Fails for null ent.} -\Status{Implemented} -} - -\numtest{2}{ -\Reason{Fails for non-existent principal.} -\Status{Implemented} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for user with no access bits, retrieving other principal.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{4}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``get'', getting principal - other than his own, using ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{Fails for user with ``modify'' but not ``get'', getting - principal other than his own, using ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{6}{ -\Reason{Fails for user with ``delete'' but not ``get'', getting - principal other than his own, using ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{Fails for user with ``delete'' but not ``get'', getting - principal other than his own, using CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for user with ``get'', getting principal other than his - own, using CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{9}{ -\Priority{High} -\Reason{Succeeds for user without ``get'', retrieving self, using - ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{10}{ -\Reason{Succeeds for user without ``get'', retrieving self, using - CHANGEPW_SERVICE.} -\Status{Implemented} -} - -\numtest{11}{ -\Reason{Succeeds for user with ``get'', retrieving self, using - ADMIN_SERVICE.} -\Status{Implemented} -} - -\numtest{12}{ -\Reason{Succeeds for user with ``get'', retrieving self, using - CHANGEPW_SERVICE.} -\Status{Implemented} -} - -\numtest{13}{ -\Priority{High} -\Reason{Succeeds for user with ``get'', retrieving other user, using - ADMIN_SERVICE.} -\Status{Implemented} -} - -\numtest{14}{ -\Reason{Succeeds for user with ``get'' and ``modify'', retrieving - other principal, using ADMIN_SERVICE.} -\Status{Implemented} -} - - - -\section{ovsec_kadm_create_policy} - -\numtest{1}{ -\Reason{Fails for mask with undefined bit set.} -\Status{Implemented - untested} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{Fails for mask without POLICY bit set.} -\Status{Implemented - untested} -} - -\numtest{4}{ -\Reason{Fails for mask with REF_COUNT bit set.} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{Fails for invalid policy name.} -\Status{Implemented - untested} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for existing policy name.} -\Status{Implemented} -} - -\numtest{7}{ -\Reason{Fails for null policy name.} -\Status{Implemented - untested} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -\Status{Implemented} -} - -\numtest{9}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_life.} -\Status{Implemented} -} - -\numtest{10}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_life.} -\Status{Implemented} -} - -\numtest{11}{ -\Priority{High} -\Reason{Accepts 0 for pw_max_life.} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Accepts non-zero for pw_max_life.} -\Status{Implemented} -} - -\numtest{13}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_length.} -\Status{Implemented} -} - -\numtest{14}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_length.} -\Status{Implemented} -} - -\numtest{15}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{16}{ -\Priority{High} -\Reason{Accepts 1 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{17}{ -\Priority{High} -\Reason{Accepts 4 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{18}{ -\Priority{High} -\Reason{Rejects 5 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{19}{ -\Priority{High} -\Reason{Rejects 0 for pw_history_num.} -\Status{Implemented} -} - -\numtest{20}{ -\Priority{High} -\Reason{Accepts 1 for pw_history_num.} -\Status{Implemented} -} - -\numtest{21}{ -\Priority{High} -\Reason{Accepts 10 for pw_history_num.} -\Status{Implemented} -} - -\numtest{21.5}{ -\Reason{Rejects 11 for pw_history_num.} -\Status{Implemented - untested} -} - -\numtest{22}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{23}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``add''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{24}{ -\Reason{Fails for user with ``modify'' but not ``add.''} -\Conditions{RPC} -\Status{Implemented - untested} -} - -\numtest{25}{ -\Reason{Fails for user with ``delete'' but not ``add.''} -\Conditions{RPC} -\Status{Implemented - untested} -} - -\numtest{26}{ -\Priority{High} -\Reason{Succeeds for user with ``add.''} -\Status{Implemented} -} - -\numtest{27}{ -\Reason{Succeeds for user with ``get'' and ``add.''} -\Status{Implemented - untested} -} - -\numtest{28}{ -\Reason{Rejects null policy argument.} -\Status{Implemented - untested} -} - -\numtest{29}{ -\Reason{Rejects pw_min_life greater than pw_max_life.} -} - - -\section{ovsec_kadm_delete_policy} - -\numtest{1}{ -\Reason{Fails for null policy name.} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{4}{ -\Reason{Fails for bad policy name.} -} - -\numtest{5}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``delete''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{Fails for user with ``modify'' but not ``delete''.} -\Conditions{RPC} -} - -\numtest{9}{ -\Reason{Fails for user with ``get'' but not ``delete.''} -\Conditions{RPC} -} - -\numtest{10}{ -\Priority{High} -\Reason{Succeeds for user with only ``delete''.} -\Status{Implemented} -} - -\numtest{11}{ -\Reason{Succeeds for user with ``delete'' and ``add''.} -} - -\numtest{12}{ -\Priority{High} -\Reason{Fails for policy with non-zero reference count.} -\Status{Implemented} -} - - - -\section{ovsec_kadm_modify_policy} - -\numtest{1}{ -\Reason{Fails for mask with undefined bit set.} -\Conditions{RPC} -} - -\numtest{2}{ -\Priority{High} -\Reason{Fails if caller connected with CHANGEPW_SERVICE.} -\Status{Implemented} -} - -\numtest{3}{ -\Reason{Fails for mask with POLICY bit set.} -} - -\numtest{4}{ -\Reason{Fails for mask with REF_COUNT bit set.} -\Status{Implemented} -} - -\numtest{5}{ -\Reason{Fails for invalid policy name.} -} - -\numtest{6}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{7}{ -\Reason{Fails for null policy name.} -} - -\numtest{8}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -\Status{Implemented} -} - -\numtest{9}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_life.} -\Status{Implemented} -} - -\numtest{10}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_life.} -\Status{Implemented} -} - -\numtest{11}{ -\Priority{High} -\Reason{Accepts 0 for pw_max_life.} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Accepts non-zero for pw_max_life.} -\Status{Implemented} -} - -\numtest{13}{ -\Priority{High} -\Reason{Accepts 0 for pw_min_length.} -\Status{Implemented} -} - -\numtest{14}{ -\Priority{High} -\Reason{Accepts non-zero for pw_min_length.} -\Status{Implemented} -} - -\numtest{15}{ -\Priority{High} -\Reason{Rejects 0 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{16}{ -\Priority{High} -\Reason{Accepts 1 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{17}{ -\Priority{High} -\Reason{Accepts 4 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{18}{ -\Priority{High} -\Reason{Rejects 5 for pw_min_classes.} -\Status{Implemented} -} - -\numtest{19}{ -\Priority{High} -\Reason{Rejects 0 for pw_history_num.} -\Status{Implemented} -} - -\numtest{20}{ -\Priority{High} -\Reason{Accepts 1 for pw_history_num.} -\Status{Implemented} -} - -\numtest{21}{ -\Priority{High} -\Reason{Accepts 10 for pw_history_num.} -\Status{Implemented} -} - -\numtest{22}{ -\Priority{High} -\Reason{Fails for user with no access bits.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{23}{ -\Priority{High} -\Reason{Fails for user with ``get'' but not ``modify''.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{24}{ -\Reason{Fails for user with ``add'' but not ``modify.''} -\Conditions{RPC} -} - -\numtest{25}{ -\Reason{Fails for user with ``delete'' but not ``modify.''} -\Conditions{RPC} -} - -\numtest{26}{ -\Priority{High} -\Reason{Succeeds for user with ``modify.''} -\Status{Implemented} -} - -\numtest{27}{ -\Reason{Succeeds for user with ``get'' and ``modify.''} -} - -\numtest{28}{ -\Reason{Rejects null policy argument.} -} - -\numtest{29}{ -\Reason{Rejects change which makes pw_min_life greater than - pw_max_life.} -} - -\section{ovsec_kadm_get_policy} - -\numtest{1}{ -\Reason{Fails for null policy.} -} - -\numtest{2}{ -\Reason{Fails for invalid policy name.} -} - -\numtest{3}{ -\Priority{High} -\Reason{Fails for empty-string policy name.} -\Status{Implemented} -} - -\numtest{4}{ -\Reason{Fails for non-existent policy name.} -} - -\numtest{5}{ -\Reason{Fails for null ent.} -} - -\numtest{6}{ -\Priority{High} -\Reason{Fails for user with no access bits trying to get other's - policy, using ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{7}{ -\Priority{High} -\Reason{Fails for user with ``add'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{8}{ -\Reason{Fails for user with ``modify'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -\Conditions{RPC} -} - -\numtest{9}{ -\Reason{Fails for user with ``delete'' but not ``get'' trying to get - other's policy, using ADMIN_SERVICE.} -\Conditions{RPC} -} - -\numtest{10}{ -\Reason{Fails for user with ``delete'' but not ``get'' trying to get - other's policy, using CHANGEPW_SERVICE.} -\Conditions{RPC} -} - -\numtest{11}{ -\Priority{High} -\Reason{Succeeds for user with only ``get'', trying to get own policy, - using ADMIN_SERVICE.} -\Status{Implemented} -} - -\numtest{12}{ -\Priority{High} -\Reason{Succeeds for user with only ``get'', trying to get own policy, - using CHANGEPW_SERVICE.} -\Status{Implemented} -} - -\numtest{13}{ -\Reason{Succeeds for user with ``add'' and ``get'', trying to get own - policy, using ADMIN_SERVICE.} -} - -\numtest{14}{ -\Reason{Succeeds for user with ``add'' and ``get'', trying to get own - policy, using CHANGEPW_SERVICE.} -} - -\numtest{15}{ -\Reason{Succeeds for user without ``get'', trying to get own policy, - using ADMIN_SERVICE.} -} - -\numtest{16}{ -\Priority{High} -\Reason{Succeeds for user without ``get'', trying to get own policy, - using CHANGEPW_SERVICE.} -\Status{Implemented} -} - -\numtest{17}{ -\Priority{High} -\Reason{Succeeds for user with ``get'', trying to get other's policy, - using ADMIN_SERVICE.} -\Status{Implemented} -} - -\numtest{18}{ -\Priority{High} -\Reason{Fails for user with ``get'', trying to get other's policy, - using CHANGEPW_SERVICE.} -\Conditions{RPC} -\Status{Implemented} -} - -\numtest{19}{ -\Reason{Succeeds for user with ``modify'' and ``get'', trying to get - other's policy, using ADMIN_SERVICE.} -} - -\numtest{20}{ -\Reason{Fails for user with ``modify'' and ``get'', trying to get - other's policy, using CHANGEPW_SERVICE.} -} - - - -\section{ovsec_kadm_free_principal_ent} - -In addition to the tests listed here, a memory-leak detector such as -TestCenter, Purify or dbmalloc should be used to verify that the -memory freed by this function is really freed. - -\numtest{1}{ -\Reason{Null princ succeeds.} -} - -\numtest{2}{ -\Reason{Non-null princ succeeds.} -} - - -\section{ovsec_kadm_free_policy_ent} - -In addition to the tests listed here, a memory-leak detector such as -TestCenter, Purify or dbmalloc should be used to verify that the -memory freed by this function is really freed. - -\numtest{1}{ -\Reason{Null policy succeeds.} -} - -\numtest{2}{ -\Reason{Non-null policy succeeds.} -} - - - -\section{ovsec_kadm_get_privs} - -\numtest{1}{ -\Reason{Fails for null pointer argument.} -} - -This test should be run with the 16 possible combinations of access -bits (since there are 4 access bits, there are $2^4 = 16$ possible -combinations of them): - -\numtest{2}{ -\Priority{High} -\Reason{Returns correct bit mask for access bits of user.} -\Conditions{RPC} -} - -This test should be run locally: - -\numtest{3}{ -\Priority{High} -\Reason{Returns 0x0f.} -\Conditions{local} -} - -\end{document} diff --git a/doc/kadmin/cli.func-spec b/doc/kadmin/cli.func-spec deleted file mode 100644 index 1f336cbfd..000000000 --- a/doc/kadmin/cli.func-spec +++ /dev/null @@ -1,388 +0,0 @@ -kadmin [-r _realm_] [[-p _principal_] [-k _keytab_]] [-q _query_] - - If given the -p option, kadmin will use the specified - principal to authenticate. If the -p option is not given, - kadmin will default appending "/admin" to the first component - of the default principal of the default credentials cache. If - the default credentials cache does not exist, then kadmin will - default to $USER/admin (if the environment variable USER is - set). If $USER is not set, then the first component of the - principal will be the username as obtained from - getpwnam(getuid()). If given -k, kadmin will not prompt for a - password, but rather use the specified keytab. Also, if the - -k option is given, the default principal will be the - host/hostname. If -r is present, then kadmin will use the - specified realm as the default database realm rather than the - default realm for the local machine. Upon starting up, kadmin - will prompt for a password (unless the -k option has been - given). The program will then obtain tickets for - ovsec_admin/admin in the default realm (unless -r has been - specified, in which case it will use the specified realm). - The ticket is stored in a separate ccache. The lifetime for - these tickets is 5 minutes. - - The -q option allows the passing of a request directly to - kadmin, which will then exit. This can be useful for writing - scripts. The query provided must be quoted as a single - argument to the program if there is more than one word in it. - -DATE FORMAT - Various commands in kadmin can take a variety of date formats, - specifying durations or absolute times. Examples of valid - formats are: - - 1 month ago - 2 hours ago - 400000 seconds ago - last year - last Monday - yesterday - a fortnight ago - 3/31/92 10:00:07 PST - January 23, 1987 10:05pm - 22:00 GMT - - Dates which do not have the "ago" specifier default to being - absolute dates, unless they appear in a field where a duration - is expected. In that case the time specifier will be - interpreted as relative. Specifying "ago" on a duration may - result in unexpected behaviour. The format follows that of - the public-domain "getdate" package. All date parameters must - be provided as a single word, which means that they must be - double-quoted if there are any spaces. - -COMMAND DESCRIPTIONS - -add_principal [options] _newprinc_ - creates the principal _newprinc_, prompting twice for a - password. This command requires the "add" privilege. This - command has the aliases "addprinc", "ank". - - OPTIONS - -expire _expdate_ - expiration date of the principal - - -pwexpire _pwexpdate_ - password expiration date - - -maxlife _maxlife_ - maximum ticket life of the principal - - -kvno _kvno_ - explicity set the key version number. This is not - recommended. - - -policy _policy_ - policy used by this principal. If no policy is - supplied, the principal will default to having no - policy, and a warning message will be printed. - - {-|+}allow_tgs_req - "-allow_tgs_req" specifies that a TGS request for a - ticket for a service ticket for this principal is not - permitted. This option is useless for most things. - "+allow_tgs_req" clears this flag. The default is - "+allow_tgs_req". In effect, "-allow_tgs_req" sets - the KRB5_KDB_DISALLOW_TGT_BASED flag on the principal - in the database. - - {-|+}allow_tix - "-allow_tix" forbids the issuance of any tickets for - this principal. "+allow_tix" clears this flag. The - default is "+allow_tix". In effect, "-allow_tix" sets - the KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in - the database. - - {-|+}needchange - "+needchange" sets a flag in attributes field to force - a password change; "-needchange" clears it. The - default is "-needchange". In effect, "+needchange" - sets the KRB5_KDB_REQUIRES_PWCHANGE flag on the - principal in the database. - - {-|+}password_changing_service - "+password_changing_service" sets a flag in the - attributes field marking this as a password change - service principal (useless for most things). - "-password_changing_service" clears the flag. This - flag intentionally has a long name. The default is - "-password_changing_service". In effect, - "+password_changing_service" sets the - KRB5_KDB_PWCHANGE_SERVICE flag on the principal in the - database. - - -randkey - sets the key of the principal to a random value - - -pw _password_ - sets the key of the principal to the specified string - and does not prompt for a password. This is not - recommended. - - EXAMPLE - kadmin: addprinc tlyu/deity - WARNING: no policy specified for "tlyu/deity@ATHENA.MIT.EDU"; - defaulting to no policy. - Enter password for principal tlyu/deity@ATHENA.MIT.EDU: - Re-enter password for principal tlyu/deity@ATHENA.MIT.EDU: - Principal "tlyu/deity@ATHENA.MIT.EDU" created. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_ADD (requires "add" privilege) - OVSEC_KADM_DUP (principal exists already) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_PASS_Q_* (password quality violations) - -delete_principal [-force] _principal_ - deletes the specified principal from the database. This - command prompts for deletion, unless the "-force" option is - given. This command requires the "delete" privilege. Aliased - to "delprinc". - - EXAMPLE - kadmin: delprinc testuser - Are you sure you want to delete the principal - "testuser@ATHENA.MIT.EDU"? (yes/no): yes - Principal "testuser@ATHENA.MIT.EDU" deleted. - Make sure that you have removed this principal from - all ACLs before reusing. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_DELETE (reequires "delete" privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - -modify_principal [options] _principal_ - modifies the specified principal, changing the fields as - specified. The options are as above for "add_principal", - except that password changing is forbidden by this command. - In addition, the option "-clearpolicy" will remove clear the - current policy of a principal. This command requires the - "modify" privilege. Aliased to "modprinc". - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires "modify" privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_BAD_MASK (shouldn't happen) - -rename_principal [-force] _old_ _new_ - rename the principal _old_ to _new_. Prompts for - confirmation, unless the "-force" option is given. Requires - both the "add" and "delete" privileges. Aliased to - "renprinc". - - EXAMPLE - kadmin: renprinc tlyutest test0 - Are you sure you want to rename the principal - "tlyutest@ATHENA.MIT.EDU" to - "test0@ATHENA.MIT.EDU"? (yes/no): yes - Principal "tlyutest@ATHENA.MIT.EDU" renamed to - "test0@ATHENA.MIT.EDU". - Make sure that you have removed "tlyutest@ATHENA.MIT.EDU" from - all ACLs before reusing. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_ADD (requires "add" privilege) - OVSEC_KADM_AUTH_DELETE (requires "delete" privilege) - OVSEC_KADM_UNK_PRINC (source principal does not exist) - OVSEC_KADM_DUP (target principal already exists) - -change_password [options] _principal_ - changes the password of _principal_. Prompts for a new - password if neither -randpass or -pw is specified. Requires - the "modify" privilege, or that the principal that is running - the program to be the same as the one changed. Aliased to - "cpw". - - OPTIONS - -randkey - sets the key of the principal to a random value - - -pw _password_ - set the password to the specified string. Not - recommended. - - EXAMPLE - kadmin: cpw systest - Enter password for principal systest@ATHENA.MIT.EDU: - Re-enter password for principal systest@ATHENA.MIT.EDU: - Password for systest@ATHENA.MIT.EDU changed. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires the modify privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - OVSEC_KADM_PASS_Q_* (password policy violation errors) - OVSEC_KADM_PADD_REUSE (password is in principal's password - history) - OVSEC_KADM_PASS_TOOSOON (current password minimum life not - expired) - -get_principal [-terse] _principal_ - gets the attributes of _principal_. Requires the "get" - privilege, or that the principal that is running the the - program to be the same as the one being listed. With the - "-terse" option, outputs fields as tab-separated strings. Any - string fields get double-quoted. Alias "getprinc". - - EXAMPLES - kadmin: getprinc tlyu/deity - Principal: tlyu/deity@ATHENA.MIT.EDU - Key version: 3 - Maximum life: 1 day 00:00:00 - Maximum renewable life: 7 days 00:00:00 - Master key version: 1 - Expires: Mon Jan 18 22:14:07 EDT 2038 - Password expires: Mon Sep 19 14:40:00 EDT 1994 - Password last changed: Mon Jan 31 02:06:40 EDT 1994 - Last modified: by tlyu/admin@ATHENA.MIT.EDU - on Wed Jul 13 18:27:08 EDT 1994 - Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE, - REQUIRES_HW_AUTH - Salt type: DEFAULT - kadmin: getprinc -terse systest - "systest@ATHENA.MIT.EDU" 3 86400 604800 - 1 785926535 753241234 785900000 - "tlyu/admin@ATHENA.MIT.EDU" 786100034 0 0 - kadmin: - - ERRORS - OVSEC_KADM_AUTH_GET (requires the get privilege) - OVSEC_KADM_UNK_PRINC (principal does not exist) - -add_policy [options] _policy_ - adds the named policy to the policy database. Requires the - "add" privilege. Aliased to "addpol". - - OPTIONS - -maxlife _time_ - sets the maximum lifetime of a password - - -minlife _time_ - sets the minimum lifetime of a password - - -minlength _length_ - sets the minimum length of a password - - -minclasses _number_ - sets the minimum number of character classes allowed - in a password - - -history _number_ - sets the number of past keys kept for a principal - - ERRORS - OVSEC_KADM_AUTH_ADD (requires the add privilege) - OVSEC_KADM_DUP (policy already exists) - -delete_policy _policy_ - deletes the named policy. Prompts for confirmation before - deletion. The command will fail if the policy is in use by - any principals. Requires the "delete" privilege. Alias - "delpol". - - EXAMPLE - kadmin: del_policy guests - Are you sure you want to delete the policy "guests"? - (yes/no): yes - Policy "guests" deleted. - kadmin: - - ERRORS - OVSEC_KADM_AUTH_DELETE (requires the delete privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - OVSEC_KADM_POLICY_REF (reference count on policy is not zero) - -modify_policy [options] _policy_ - modifies the named policy. Options are as above for - "add_policy". Requires the "modify" privilege". Alias - "modpol". - - ERRORS - OVSEC_KADM_AUTH_MODIFY (requires the modify privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - -get_policy [-terse] _policy_ - displays the values of the named policy. Requires the "get" - privilege. With the "-terse" flag, outputs the fields as - strings separated by tabs. All string fields get - double-quoted. Alias "getpol". - - EXAMPLES - kadmin: get_policy admin - Policy: admin - Maximum password life: 180 days 00:00:00 - Minimum password life: 00:00:00 - Minimum password length: 6 - Minimum number of password character classes: 2 - Number of old keys kept: 5 - Reference count: 17 - kadmin: get_policy -terse admin - "admin" 15552000 0 6 2 5 17 - kadmin: - - ERRORS - OVSEC_KADM_AUTH_GET (requires the get privilege) - OVSEC_KADM_UNK_POLICY (policy does not exist) - -get_privs - returns the administrative privileges of the current user. - Alias "getprivs". - - EXAMPLE - kadmin: get_privs - Principal tlyu/admin@ATHENA.MIT.EDU - has privileges: GET, ADD, MODIFY, DELETE, CHSTAB - kadmin: - -OPEN POINTS - Implementation will most likely be in tcl, which implies that - scripts can be written to be run directly by kadmin. This - will require some more spec'ing out. - - get_srvtab is being pulled out into a separate program, to be - spec'ed out and documented at a later time. ----------------------------------------------------------------------------- -get_srvtab [-v4] [-file _name_] {_principal..._}|{-host _host_ _service..._} - Creates a srvtab (a krb4 srvtab if -v4 is specified). If - given a list of principals, randomizes the keys for the - principals named, creating them if necessary, and stores the - keys in the new srvtab. If -host is given, then the named service - principals are randomized/created for the named host and - placed in the new srvtab. The naming convention for the files - is hostname-new-srvtab if -host is given, overwriting anything - previously in such a file. If -host is not given, then the - filename defaults to the principal-new-srvtab, using only the - first component of the principal name. - - If the principals need to be created, the command will prompt - for confirmation. This command requires the "chstab" - privilege, and only certain service names can be obtained this - way. (The services are specified in a configuration file on - the server.) In addition, certain hosts may be excluded from - this command. The "modify" privilege is necessary in order to - use this command on arbitrary principals. - - This command is aliased to "gst" - - EXAMPLE - kadmin: get_srvtab -host dragons-lair host rvdsrv discuss - WARNING: hostname canonicalized to "dragons-lair.mit.edu" - Principal "host/dragons-lair.mit.edu@ATHENA.MIT.EDU" - updated to kvno 3. - WARNING: principal - "rvdsrv/dragons-lair.mit.edu@ATHENA.MIT.EDU" - does not exist. Create? (y/n): y - Created principal - "rvdsrv/dragons-lair.mit.edu@ATHENA.MIT.EDU". - Principal "discuss/dragons-lair.mit.edu@ATHENA.MIT.EDU" - updated to kvno 3. - Wrote keytab "WRFILE:dragons-lair-new-srvtab". - kadmin: - - ERRORS - "Operation requires the chstab privilege" - "Operation requires the modify privilege" diff --git a/doc/krb5-protocol/krb5.constants b/doc/krb5-protocol/krb5.constants deleted file mode 100644 index 8d9a446ed..000000000 --- a/doc/krb5-protocol/krb5.constants +++ /dev/null @@ -1,143 +0,0 @@ -8.3. Protocol constants and associated values - - The following tables list constants used in the protocol and defines - their meanings. - - ----------------+-----------+----------+----------------+--------------- -Encryption type|etype value|block size|minimum pad size|confounder size ----------------+-----------+----------+----------------+--------------- -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - 4 - --------------------------------+-------------------+------------- -Checksum type |sumtype value |checksum size --------------------------------+-------------------+------------- -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 - --------------------------------+----------------- -padata type |padata-type value --------------------------------+----------------- -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - 4 -PA-ENC-UNIX-TIME 5 -PA-SANDIA-SECUREID 6 -PA-SESAME 7 -PA-OSF-DCE 8 -PA-CYBERSAFE-SECUREID 9 - --------------------------------+------------- -authorization data type |ad-type value --------------------------------+------------- -reserved values 0-63 -AD-OSF-DCE 64 -AD-SESAME 65 - --------------------------------+----------------- -alternate authentication type |method-type value --------------------------------+----------------- -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - --------------------------------+------------- -transited encoding type |tr-type value --------------------------------+------------- -DOMAIN-X500-COMPRESS 1 -reserved values all others - - ---------------+-------+----------------------------------------- -Label |Value |Meaning or MIT code ---------------+-------+----------------------------------------- - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired -KDC_ERR_BAD_PVNO 3 Requested protocol version # not supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than end time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authentication required* -KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method required* -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in message -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this implementation - - *This error carries additional information in the e-data field. The - contents of the e-data field for this message is described in section - 5.9.1. - diff --git a/doc/krb5-protocol/rfc1510.errata b/doc/krb5-protocol/rfc1510.errata deleted file mode 100644 index 602325b27..000000000 --- a/doc/krb5-protocol/rfc1510.errata +++ /dev/null @@ -1,105 +0,0 @@ ----rfc1510.eratta---as of Auguest 10, 1994--- - -1. [19940312] The following lines describes corrections to pseudocode - in rfc1510 as of March 12, 1994. - - A: Throughout the pseudocode (section A), flags.ALLOW-POSTDATE should be - replaced by flags.MAY-POSTDATE. kdc-options.ALLOW-POSTDATE is - correct, however. - -A.2: In the processing for the kdc-options.POSTDATE (imperitive), both - the POSTDATED and the INVALID flag should be set. The setting of the - POSTDATE flag was inadvertantly omitted. - - You should change: - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when - - To: - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.POSTDATED; <**** - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when - -A.6: In section A.6, all occursences of kdc-options.POSTDATE (imperitive) - should be replaced by kdc-options.ALLOW-POSTDATE and tgt.flags.POSTDATE - should be replaced by tgt.flags.MAY-POSTDATE. - - Note that instances of POSTDATED (adjective) are correct. - - ---- -2. [19940614] Processing of the etype filed, described in 3.1.3, and 5.4.1. - -If a there are multiple encryption keys registered for a client in the -Kerberos database (or if the key registered supports multiple -encryption types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype -field from the AS request is used by the KDC to select the encryption -method to be used for encrypting the response to the client. If there -is more than one supported, strong encryption type in the etype list, -the first valid etype for which an encryption key is available is -used. The encryption method used to respond to a TGS request is taken -from the keytype of the session key found in the ticket granting -ticket. - -When the etype field is present in a KDC request, whether an AS or TGS -request, the KDC will attempt to assign the type of the random session -key from the list of methods in the etype field. The KDC will select -the appropriate type using the list of methods provided together with -information from the Kerberos database indicating acceptable -encryption methods for the application server. The KDC will not issue -tickets with a weak session key encryption type. - ---- -3. [19940707] Case of realm names for DNS based realm names, - - The following should appear in section 7.1 before the description - of the four classed of realm names (before "There are presently...") - - Kerberos realm names are case sensitive. Realm names that differ - only in the case of the characters are not equivalent. - - The domain example should be changes from: - domain: host.subdomain.domain (example) - - To: - - domain: ATHENA.MIT.EDU (example) - - The following should be append to the domain name paragraph of - section 7.1 (following "nor slashes (/).") - - Domain names must be converted to upper case when used as realm names. - ---- -4. [19940707] Official name of host is instance for NT-SRV-HST - - Append to paragraph 7.2.1: - - When a host has an official name and one or more aliases, the - official name of the host must be used when constructing the name - of the server principal. - ---- - -5. [19940722] The protocol is standards track - - In the 3rd paragraph of the overview delete: - - ", and are not being submitted for consideration as - an Internet standard at this time" - - as it contradicts the first sentence of the RFC. - diff --git a/doc/krb5-protocol/rfc1510.txt b/doc/krb5-protocol/rfc1510.txt deleted file mode 100644 index bc810cc50..000000000 --- a/doc/krb5-protocol/rfc1510.txt +++ /dev/null @@ -1,6275 +0,0 @@ - - - - - - -Network Working Group J. Kohl -Request for Comments: 1510 Digital Equipment Corporation - C. Neuman - ISI - September 1993 - - - The Kerberos Network Authentication Service (V5) - -Status of this Memo - - This RFC specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" for the standardization state and status - of this protocol. Distribution of this memo is unlimited. - -Abstract - - This document gives an overview and specification of Version 5 of the - protocol for the Kerberos network authentication system. Version 4, - described elsewhere [1,2], is presently in production use at MIT's - Project Athena, and at other Internet sites. - -Overview - - Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, - Moira, and Zephyr are trademarks of the Massachusetts Institute of - Technology (MIT). No commercial use of these trademarks may be made - without prior written permission of MIT. - - This RFC describes the concepts and model upon which the Kerberos - network authentication system is based. It also specifies Version 5 - of the Kerberos protocol. - - The motivations, goals, assumptions, and rationale behind most design - decisions are treated cursorily; for Version 4 they are fully - described in the Kerberos portion of the Athena Technical Plan [1]. - The protocols are under review, and are not being submitted for - consideration as an Internet standard at this time. Comments are - encouraged. Requests for addition to an electronic mailing list for - discussion of Kerberos, kerberos@MIT.EDU, may be addressed to - kerberos-request@MIT.EDU. This mailing list is gatewayed onto the - Usenet as the group comp.protocols.kerberos. Requests for further - information, including documents and code availability, may be sent - to info-kerberos@MIT.EDU. - - - - - -Kohl & Neuman [Page 1] - -RFC 1510 Kerberos September 1993 - - -Background - - The Kerberos model is based in part on Needham and Schroeder's - trusted third-party authentication protocol [3] and on modifications - suggested by Denning and Sacco [4]. The original design and - implementation of Kerberos Versions 1 through 4 was the work of two - former Project Athena staff members, Steve Miller of Digital - Equipment Corporation and Clifford Neuman (now at the Information - Sciences Institute of the University of Southern California), along - with Jerome Saltzer, Technical Director of Project Athena, and - Jeffrey Schiller, MIT Campus Network Manager. Many other members of - Project Athena have also contributed to the work on Kerberos. - Version 4 is publicly available, and has seen wide use across the - Internet. - - Version 5 (described in this document) has evolved from Version 4 - based on new requirements and desires for features not available in - Version 4. Details on the differences between Kerberos Versions 4 - and 5 can be found in [5]. - -Table of Contents - - 1. Introduction ....................................... 5 - 1.1. Cross-Realm Operation ............................ 7 - 1.2. Environmental assumptions ........................ 8 - 1.3. Glossary of terms ................................ 9 - 2. Ticket flag uses and requests ...................... 12 - 2.1. Initial and pre-authenticated tickets ............ 12 - 2.2. Invalid tickets .................................. 12 - 2.3. Renewable tickets ................................ 12 - 2.4. Postdated tickets ................................ 13 - 2.5. Proxiable and proxy tickets ...................... 14 - 2.6. Forwardable tickets .............................. 15 - 2.7. Other KDC options ................................ 15 - 3. Message Exchanges .................................. 16 - 3.1. The Authentication Service Exchange .............. 16 - 3.1.1. Generation of KRB_AS_REQ message ............... 17 - 3.1.2. Receipt of KRB_AS_REQ message .................. 17 - 3.1.3. Generation of KRB_AS_REP message ............... 17 - 3.1.4. Generation of KRB_ERROR message ................ 19 - 3.1.5. Receipt of KRB_AS_REP message .................. 19 - 3.1.6. Receipt of KRB_ERROR message ................... 20 - 3.2. The Client/Server Authentication Exchange ........ 20 - 3.2.1. The KRB_AP_REQ message ......................... 20 - 3.2.2. Generation of a KRB_AP_REQ message ............. 20 - 3.2.3. Receipt of KRB_AP_REQ message .................. 21 - 3.2.4. Generation of a KRB_AP_REP message ............. 23 - 3.2.5. Receipt of KRB_AP_REP message .................. 23 - - - -Kohl & Neuman [Page 2] - -RFC 1510 Kerberos September 1993 - - - 3.2.6. Using the encryption key ....................... 24 - 3.3. The Ticket-Granting Service (TGS) Exchange ....... 24 - 3.3.1. Generation of KRB_TGS_REQ message .............. 25 - 3.3.2. Receipt of KRB_TGS_REQ message ................. 26 - 3.3.3. Generation of KRB_TGS_REP message .............. 27 - 3.3.3.1. Encoding the transited field ................. 29 - 3.3.4. Receipt of KRB_TGS_REP message ................. 31 - 3.4. The KRB_SAFE Exchange ............................ 31 - 3.4.1. Generation of a KRB_SAFE message ............... 31 - 3.4.2. Receipt of KRB_SAFE message .................... 32 - 3.5. The KRB_PRIV Exchange ............................ 33 - 3.5.1. Generation of a KRB_PRIV message ............... 33 - 3.5.2. Receipt of KRB_PRIV message .................... 33 - 3.6. The KRB_CRED Exchange ............................ 34 - 3.6.1. Generation of a KRB_CRED message ............... 34 - 3.6.2. Receipt of KRB_CRED message .................... 34 - 4. The Kerberos Database .............................. 35 - 4.1. Database contents ................................ 35 - 4.2. Additional fields ................................ 36 - 4.3. Frequently Changing Fields ....................... 37 - 4.4. Site Constants ................................... 37 - 5. Message Specifications ............................. 38 - 5.1. ASN.1 Distinguished Encoding Representation ...... 38 - 5.2. ASN.1 Base Definitions ........................... 38 - 5.3. Tickets and Authenticators ....................... 42 - 5.3.1. Tickets ........................................ 42 - 5.3.2. Authenticators ................................. 47 - 5.4. Specifications for the AS and TGS exchanges ...... 49 - 5.4.1. KRB_KDC_REQ definition ......................... 49 - 5.4.2. KRB_KDC_REP definition ......................... 56 - 5.5. Client/Server (CS) message specifications ........ 58 - 5.5.1. KRB_AP_REQ definition .......................... 58 - 5.5.2. KRB_AP_REP definition .......................... 60 - 5.5.3. Error message reply ............................ 61 - 5.6. KRB_SAFE message specification ................... 61 - 5.6.1. KRB_SAFE definition ............................ 61 - 5.7. KRB_PRIV message specification ................... 62 - 5.7.1. KRB_PRIV definition ............................ 62 - 5.8. KRB_CRED message specification ................... 63 - 5.8.1. KRB_CRED definition ............................ 63 - 5.9. Error message specification ...................... 65 - 5.9.1. KRB_ERROR definition ........................... 66 - 6. Encryption and Checksum Specifications ............. 67 - 6.1. Encryption Specifications ........................ 68 - 6.2. Encryption Keys .................................. 71 - 6.3. Encryption Systems ............................... 71 - 6.3.1. The NULL Encryption System (null) .............. 71 - 6.3.2. DES in CBC mode with a CRC-32 checksum (descbc-crc)71 - - - -Kohl & Neuman [Page 3] - -RFC 1510 Kerberos September 1993 - - - 6.3.3. DES in CBC mode with an MD4 checksum (descbc-md4) 72 - 6.3.4. DES in CBC mode with an MD5 checksum (descbc-md5) 72 - 6.4. Checksums ........................................ 74 - 6.4.1. The CRC-32 Checksum (crc32) .................... 74 - 6.4.2. The RSA MD4 Checksum (rsa-md4) ................. 75 - 6.4.3. RSA MD4 Cryptographic Checksum Using DES - (rsa-md4-des) ......................................... 75 - 6.4.4. The RSA MD5 Checksum (rsa-md5) ................. 76 - 6.4.5. RSA MD5 Cryptographic Checksum Using DES - (rsa-md5-des) ......................................... 76 - 6.4.6. DES cipher-block chained checksum (des-mac) - 6.4.7. RSA MD4 Cryptographic Checksum Using DES - alternative (rsa-md4-des-k) ........................... 77 - 6.4.8. DES cipher-block chained checksum alternative - (des-mac-k) ........................................... 77 - 7. Naming Constraints ................................. 78 - 7.1. Realm Names ...................................... 77 - 7.2. Principal Names .................................. 79 - 7.2.1. Name of server principals ...................... 80 - 8. Constants and other defined values ................. 80 - 8.1. Host address types ............................... 80 - 8.2. KDC messages ..................................... 81 - 8.2.1. IP transport ................................... 81 - 8.2.2. OSI transport .................................. 82 - 8.2.3. Name of the TGS ................................ 82 - 8.3. Protocol constants and associated values ......... 82 - 9. Interoperability requirements ...................... 86 - 9.1. Specification 1 .................................. 86 - 9.2. Recommended KDC values ........................... 88 - 10. Acknowledgments ................................... 88 - 11. References ........................................ 89 - 12. Security Considerations ........................... 90 - 13. Authors' Addresses ................................ 90 - A. Pseudo-code for protocol processing ................ 91 - A.1. KRB_AS_REQ generation ............................ 91 - A.2. KRB_AS_REQ verification and KRB_AS_REP generation 92 - A.3. KRB_AS_REP verification .......................... 95 - A.4. KRB_AS_REP and KRB_TGS_REP common checks ......... 96 - A.5. KRB_TGS_REQ generation ........................... 97 - A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation 98 - A.7. KRB_TGS_REP verification ......................... 104 - A.8. Authenticator generation ......................... 104 - A.9. KRB_AP_REQ generation ............................ 105 - A.10. KRB_AP_REQ verification ......................... 105 - A.11. KRB_AP_REP generation ........................... 106 - A.12. KRB_AP_REP verification ......................... 107 - A.13. KRB_SAFE generation ............................. 107 - A.14. KRB_SAFE verification ........................... 108 - - - -Kohl & Neuman [Page 4] - -RFC 1510 Kerberos September 1993 - - - A.15. KRB_SAFE and KRB_PRIV common checks ............. 108 - A.16. KRB_PRIV generation ............................. 109 - A.17. KRB_PRIV verification ........................... 110 - A.18. KRB_CRED generation ............................. 110 - A.19. KRB_CRED verification ........................... 111 - A.20. KRB_ERROR generation ............................ 112 - -1. Introduction - - Kerberos provides a means of verifying the identities of principals, - (e.g., a workstation user or a network server) on an open - (unprotected) network. This is accomplished without relying on - authentication by the host operating system, without basing trust on - host addresses, without requiring physical security of all the hosts - on the network, and under the assumption that packets traveling along - the network can be read, modified, and inserted at will. (Note, - however, that many applications use Kerberos' functions only upon the - initiation of a stream-based network connection, and assume the - absence of any "hijackers" who might subvert such a connection. Such - use implicitly trusts the host addresses involved.) Kerberos - performs authentication under these conditions as a trusted third- - party authentication service by using conventional cryptography, - i.e., shared secret key. (shared secret key - Secret and private are - often used interchangeably in the literature. In our usage, it takes - two (or more) to share a secret, thus a shared DES key is a secret - key. Something is only private when no one but its owner knows it. - Thus, in public key cryptosystems, one has a public and a private - key.) - - The authentication process proceeds as follows: A client sends a - request to the authentication server (AS) requesting "credentials" - for a given server. The AS responds with these credentials, - encrypted in the client's key. The credentials consist of 1) a - "ticket" for the server and 2) a temporary encryption key (often - called a "session key"). The client transmits the ticket (which - contains the client's identity and a copy of the session key, all - encrypted in the server's key) to the server. The session key (now - shared by the client and server) is used to authenticate the client, - and may optionally be used to authenticate the server. It may also - be used to encrypt further communication between the two parties or - to exchange a separate sub-session key to be used to encrypt further - communication. - - The implementation consists of one or more authentication servers - running on physically secure hosts. The authentication servers - maintain a database of principals (i.e., users and servers) and their - secret keys. Code libraries provide encryption and implement the - Kerberos protocol. In order to add authentication to its - - - -Kohl & Neuman [Page 5] - -RFC 1510 Kerberos September 1993 - - - transactions, a typical network application adds one or two calls to - the Kerberos library, which results in the transmission of the - necessary messages to achieve authentication. - - The Kerberos protocol consists of several sub-protocols (or - exchanges). There are two methods by which a client can ask a - Kerberos server for credentials. In the first approach, the client - sends a cleartext request for a ticket for the desired server to the - AS. The reply is sent encrypted in the client's secret key. Usually - this request is for a ticket-granting ticket (TGT) which can later be - used with the ticket-granting server (TGS). In the second method, - the client sends a request to the TGS. The client sends the TGT to - the TGS in the same manner as if it were contacting any other - application server which requires Kerberos credentials. The reply is - encrypted in the session key from the TGT. - - Once obtained, credentials may be used to verify the identity of the - principals in a transaction, to ensure the integrity of messages - exchanged between them, or to preserve privacy of the messages. The - application is free to choose whatever protection may be necessary. - - To verify the identities of the principals in a transaction, the - client transmits the ticket to the server. Since the ticket is sent - "in the clear" (parts of it are encrypted, but this encryption - doesn't thwart replay) and might be intercepted and reused by an - attacker, additional information is sent to prove that the message - was originated by the principal to whom the ticket was issued. This - information (called the authenticator) is encrypted in the session - key, and includes a timestamp. The timestamp proves that the message - was recently generated and is not a replay. Encrypting the - authenticator in the session key proves that it was generated by a - party possessing the session key. Since no one except the requesting - principal and the server know the session key (it is never sent over - the network in the clear) this guarantees the identity of the client. - - The integrity of the messages exchanged between principals can also - be guaranteed using the session key (passed in the ticket and - contained in the credentials). This approach provides detection of - both replay attacks and message stream modification attacks. It is - accomplished by generating and transmitting a collision-proof - checksum (elsewhere called a hash or digest function) of the client's - message, keyed with the session key. Privacy and integrity of the - messages exchanged between principals can be secured by encrypting - the data to be passed using the session key passed in the ticket, and - contained in the credentials. - - The authentication exchanges mentioned above require read-only access - to the Kerberos database. Sometimes, however, the entries in the - - - -Kohl & Neuman [Page 6] - -RFC 1510 Kerberos September 1993 - - - database must be modified, such as when adding new principals or - changing a principal's key. This is done using a protocol between a - client and a third Kerberos server, the Kerberos Administration - Server (KADM). The administration protocol is not described in this - document. There is also a protocol for maintaining multiple copies of - the Kerberos database, but this can be considered an implementation - detail and may vary to support different database technologies. - -1.1. Cross-Realm Operation - - The Kerberos protocol is designed to operate across organizational - boundaries. A client in one organization can be authenticated to a - server in another. Each organization wishing to run a Kerberos - server establishes its own "realm". The name of the realm in which a - client is registered is part of the client's name, and can be used by - the end-service to decide whether to honor a request. - - By establishing "inter-realm" keys, the administrators of two realms - can allow a client authenticated in the local realm to use its - authentication remotely (Of course, with appropriate permission the - client could arrange registration of a separately-named principal in - a remote realm, and engage in normal exchanges with that realm's - services. However, for even small numbers of clients this becomes - cumbersome, and more automatic methods as described here are - necessary). The exchange of inter-realm keys (a separate key may be - used for each direction) registers the ticket-granting service of - each realm as a principal in the other realm. A client is then able - to obtain a ticket-granting ticket for the remote realm's ticket- - granting service from its local realm. When that ticket-granting - ticket is used, the remote ticket-granting service uses the inter- - realm key (which usually differs from its own normal TGS key) to - decrypt the ticket-granting ticket, and is thus certain that it was - issued by the client's own TGS. Tickets issued by the remote ticket- - granting service will indicate to the end-service that the client was - authenticated from another realm. - - A realm is said to communicate with another realm if the two realms - share an inter-realm key, or if the local realm shares an inter-realm - key with an intermediate realm that communicates with the remote - realm. An authentication path is the sequence of intermediate realms - that are transited in communicating from one realm to another. - - Realms are typically organized hierarchically. Each realm shares a - key with its parent and a different key with each child. If an - inter-realm key is not directly shared by two realms, the - hierarchical organization allows an authentication path to be easily - constructed. If a hierarchical organization is not used, it may be - necessary to consult some database in order to construct an - - - -Kohl & Neuman [Page 7] - -RFC 1510 Kerberos September 1993 - - - authentication path between realms. - - Although realms are typically hierarchical, intermediate realms may - be bypassed to achieve cross-realm authentication through alternate - authentication paths (these might be established to make - communication between two realms more efficient). It is important - for the end-service to know which realms were transited when deciding - how much faith to place in the authentication process. To facilitate - this decision, a field in each ticket contains the names of the - realms that were involved in authenticating the client. - -1.2. Environmental assumptions - - Kerberos imposes a few assumptions on the environment in which it can - properly function: - - + "Denial of service" attacks are not solved with Kerberos. There - are places in these protocols where an intruder intruder can - prevent an application from participating in the proper - authentication steps. Detection and solution of such attacks - (some of which can appear to be not-uncommon "normal" failure - modes for the system) is usually best left to the human - administrators and users. - - + Principals must keep their secret keys secret. If an intruder - somehow steals a principal's key, it will be able to masquerade - as that principal or impersonate any server to the legitimate - principal. - - + "Password guessing" attacks are not solved by Kerberos. If a - user chooses a poor password, it is possible for an attacker to - successfully mount an offline dictionary attack by repeatedly - attempting to decrypt, with successive entries from a - dictionary, messages obtained which are encrypted under a key - derived from the user's password. - - + Each host on the network must have a clock which is "loosely - synchronized" to the time of the other hosts; this - synchronization is used to reduce the bookkeeping needs of - application servers when they do replay detection. The degree - of "looseness" can be configured on a per-server basis. If the - clocks are synchronized over the network, the clock - synchronization protocol must itself be secured from network - attackers. - - + Principal identifiers are not recycled on a short-term basis. A - typical mode of access control will use access control lists - (ACLs) to grant permissions to particular principals. If a - - - -Kohl & Neuman [Page 8] - -RFC 1510 Kerberos September 1993 - - - stale ACL entry remains for a deleted principal and the - principal identifier is reused, the new principal will inherit - rights specified in the stale ACL entry. By not re-using - principal identifiers, the danger of inadvertent access is - removed. - -1.3. Glossary of terms - - Below is a list of terms used throughout this document. - - - Authentication Verifying the claimed identity of a - principal. - - - Authentication header A record containing a Ticket and an - Authenticator to be presented to a - server as part of the authentication - process. - - - Authentication path A sequence of intermediate realms transited - in the authentication process when - communicating from one realm to another. - - Authenticator A record containing information that can - be shown to have been recently generated - using the session key known only by the - client and server. - - - Authorization The process of determining whether a - client may use a service, which objects - the client is allowed to access, and the - type of access allowed for each. - - - Capability A token that grants the bearer permission - to access an object or service. In - Kerberos, this might be a ticket whose - use is restricted by the contents of the - authorization data field, but which - lists no network addresses, together - with the session key necessary to use - the ticket. - - - - - - -Kohl & Neuman [Page 9] - -RFC 1510 Kerberos September 1993 - - - Ciphertext The output of an encryption function. - Encryption transforms plaintext into - ciphertext. - - - Client A process that makes use of a network - service on behalf of a user. Note that - in some cases a Server may itself be a - client of some other server (e.g., a - print server may be a client of a file - server). - - - Credentials A ticket plus the secret session key - necessary to successfully use that - ticket in an authentication exchange. - - - KDC Key Distribution Center, a network service - that supplies tickets and temporary - session keys; or an instance of that - service or the host on which it runs. - The KDC services both initial ticket and - ticket-granting ticket requests. The - initial ticket portion is sometimes - referred to as the Authentication Server - (or service). The ticket-granting - ticket portion is sometimes referred to - as the ticket-granting server (or service). - - Kerberos Aside from the 3-headed dog guarding - Hades, the name given to Project - Athena's authentication service, the - protocol used by that service, or the - code used to implement the authentication - service. - - - Plaintext The input to an encryption function or - the output of a decryption function. - Decryption transforms ciphertext into - plaintext. - - - Principal A uniquely named client or server - instance that participates in a network - communication. - - - - -Kohl & Neuman [Page 10] - -RFC 1510 Kerberos September 1993 - - - Principal identifier The name used to uniquely identify each - different principal. - - - Seal To encipher a record containing several - fields in such a way that the fields - cannot be individually replaced without - either knowledge of the encryption key - or leaving evidence of tampering. - - - Secret key An encryption key shared by a principal - and the KDC, distributed outside the - bounds of the system, with a long lifetime. - In the case of a human user's - principal, the secret key is derived - from a password. - - - Server A particular Principal which provides a - resource to network clients. - - - Service A resource provided to network clients; - often provided by more than one server - (for example, remote file service). - - - Session key A temporary encryption key used between - two principals, with a lifetime limited - to the duration of a single login "session". - - - Sub-session key A temporary encryption key used between - two principals, selected and exchanged - by the principals using the session key, - and with a lifetime limited to the duration - of a single association. - - - Ticket A record that helps a client authenticate - itself to a server; it contains the - client's identity, a session key, a - timestamp, and other information, all - sealed using the server's secret key. - It only serves to authenticate a client - when presented along with a fresh - Authenticator. - - - -Kohl & Neuman [Page 11] - -RFC 1510 Kerberos September 1993 - - -2. Ticket flag uses and requests - - Each Kerberos ticket contains a set of flags which are used to - indicate various attributes of that ticket. Most flags may be - requested by a client when the ticket is obtained; some are - automatically turned on and off by a Kerberos server as required. - The following sections explain what the various flags mean, and gives - examples of reasons to use such a flag. - -2.1. Initial and pre-authenticated tickets - - The INITIAL flag indicates that a ticket was issued using the AS - protocol and not issued based on a ticket-granting ticket. - Application servers that want to require the knowledge of a client's - secret key (e.g., a passwordchanging program) can insist that this - flag be set in any tickets they accept, and thus be assured that the - client's key was recently presented to the application client. - - The PRE-AUTHENT and HW-AUTHENT flags provide addition information - about the initial authentication, regardless of whether the current - ticket was issued directly (in which case INITIAL will also be set) - or issued on the basis of a ticket-granting ticket (in which case the - INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags are - carried forward from the ticket-granting ticket). - -2.2. Invalid tickets - - The INVALID flag indicates that a ticket is invalid. Application - servers must reject tickets which have this flag set. A postdated - ticket will usually be issued in this form. Invalid tickets must be - validated by the KDC before use, by presenting them to the KDC in a - TGS request with the VALIDATE option specified. The KDC will only - validate tickets after their starttime has passed. The validation is - required so that postdated tickets which have been stolen before - their starttime can be rendered permanently invalid (through a hot- - list mechanism). - -2.3. Renewable tickets - - Applications may desire to hold tickets which can be valid for long - periods of time. However, this can expose their credentials to - potential theft for equally long periods, and those stolen - credentials would be valid until the expiration time of the - ticket(s). Simply using shortlived tickets and obtaining new ones - periodically would require the client to have long-term access to its - secret key, an even greater risk. Renewable tickets can be used to - mitigate the consequences of theft. Renewable tickets have two - "expiration times": the first is when the current instance of the - - - -Kohl & Neuman [Page 12] - -RFC 1510 Kerberos September 1993 - - - ticket expires, and the second is the latest permissible value for an - individual expiration time. An application client must periodically - (i.e., before it expires) present a renewable ticket to the KDC, with - the RENEW option set in the KDC request. The KDC will issue a new - ticket with a new session key and a later expiration time. All other - fields of the ticket are left unmodified by the renewal process. - When the latest permissible expiration time arrives, the ticket - expires permanently. At each renewal, the KDC may consult a hot-list - to determine if the ticket had been reported stolen since its last - renewal; it will refuse to renew such stolen tickets, and thus the - usable lifetime of stolen tickets is reduced. - - The RENEWABLE flag in a ticket is normally only interpreted by the - ticket-granting service (discussed below in section 3.3). It can - usually be ignored by application servers. However, some - particularly careful application servers may wish to disallow - renewable tickets. - - If a renewable ticket is not renewed by its expiration time, the KDC - will not renew the ticket. The RENEWABLE flag is reset by default, - but a client may request it be set by setting the RENEWABLE option - in the KRB_AS_REQ message. If it is set, then the renew-till field - in the ticket contains the time after which the ticket may not be - renewed. - -2.4. Postdated tickets - - Applications may occasionally need to obtain tickets for use much - later, e.g., a batch submission system would need tickets to be valid - at the time the batch job is serviced. However, it is dangerous to - hold valid tickets in a batch queue, since they will be on-line - longer and more prone to theft. Postdated tickets provide a way to - obtain these tickets from the KDC at job submission time, but to - leave them "dormant" until they are activated and validated by a - further request of the KDC. If a ticket theft were reported in the - interim, the KDC would refuse to validate the ticket, and the thief - would be foiled. - - The MAY-POSTDATE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - This flag must be set in a ticket-granting ticket in order to issue a - postdated ticket based on the presented ticket. It is reset by - default; it may be requested by a client by setting the ALLOW- - POSTDATE option in the KRB_AS_REQ message. This flag does not allow - a client to obtain a postdated ticket-granting ticket; postdated - ticket-granting tickets can only by obtained by requesting the - postdating in the KRB_AS_REQ message. The life (endtime-starttime) - of a postdated ticket will be the remaining life of the ticket- - - - -Kohl & Neuman [Page 13] - -RFC 1510 Kerberos September 1993 - - - granting ticket at the time of the request, unless the RENEWABLE - option is also set, in which case it can be the full life (endtime- - starttime) of the ticket-granting ticket. The KDC may limit how far - in the future a ticket may be postdated. - - The POSTDATED flag indicates that a ticket has been postdated. The - application server can check the authtime field in the ticket to see - when the original authentication occurred. Some services may choose - to reject postdated tickets, or they may only accept them within a - certain period after the original authentication. When the KDC issues - a POSTDATED ticket, it will also be marked as INVALID, so that the - application client must present the ticket to the KDC to be validated - before use. - -2.5. Proxiable and proxy tickets - - At times it may be necessary for a principal to allow a service to - perform an operation on its behalf. The service must be able to take - on the identity of the client, but only for a particular purpose. A - principal can allow a service to take on the principal's identity for - a particular purpose by granting it a proxy. - - The PROXIABLE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - When set, this flag tells the ticket-granting server that it is OK to - issue a new ticket (but not a ticket-granting ticket) with a - different network address based on this ticket. This flag is set by - default. - - This flag allows a client to pass a proxy to a server to perform a - remote request on its behalf, e.g., a print service client can give - the print server a proxy to access the client's files on a particular - file server in order to satisfy a print request. - - In order to complicate the use of stolen credentials, Kerberos - tickets are usually valid from only those network addresses - specifically included in the ticket (It is permissible to request or - issue tickets with no network addresses specified, but we do not - recommend it). For this reason, a client wishing to grant a proxy - must request a new ticket valid for the network address of the - service to be granted the proxy. - - The PROXY flag is set in a ticket by the TGS when it issues a - proxy ticket. Application servers may check this flag and require - additional authentication from the agent presenting the proxy in - order to provide an audit trail. - - - - - -Kohl & Neuman [Page 14] - -RFC 1510 Kerberos September 1993 - - -2.6. Forwardable tickets - - Authentication forwarding is an instance of the proxy case where the - service is granted complete use of the client's identity. An example - where it might be used is when a user logs in to a remote system and - wants authentication to work from that system as if the login were - local. - - The FORWARDABLE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - The FORWARDABLE flag has an interpretation similar to that of the - PROXIABLE flag, except ticket-granting tickets may also be issued - with different network addresses. This flag is reset by default, but - users may request that it be set by setting the FORWARDABLE option in - the AS request when they request their initial ticket-granting - ticket. - - This flag allows for authentication forwarding without requiring the - user to enter a password again. If the flag is not set, then - authentication forwarding is not permitted, but the same end result - can still be achieved if the user engages in the AS exchange with the - requested network addresses and supplies a password. - - The FORWARDED flag is set by the TGS when a client presents a ticket - with the FORWARDABLE flag set and requests it be set by specifying - the FORWARDED KDC option and supplying a set of addresses for the new - ticket. It is also set in all tickets issued based on tickets with - the FORWARDED flag set. Application servers may wish to process - FORWARDED tickets differently than non-FORWARDED tickets. - -2.7. Other KDC options - - There are two additional options which may be set in a client's - request of the KDC. The RENEWABLE-OK option indicates that the - client will accept a renewable ticket if a ticket with the requested - life cannot otherwise be provided. If a ticket with the requested - life cannot be provided, then the KDC may issue a renewable ticket - with a renew-till equal to the the requested endtime. The value of - the renew-till field may still be adjusted by site-determined limits - or limits imposed by the individual principal or server. - - The ENC-TKT-IN-SKEY option is honored only by the ticket-granting - service. It indicates that the to-be-issued ticket for the end - server is to be encrypted in the session key from the additional - ticket-granting ticket provided with the request. See section 3.3.3 - for specific details. - - - - - -Kohl & Neuman [Page 15] - -RFC 1510 Kerberos September 1993 - - -3. Message Exchanges - - The following sections describe the interactions between network - clients and servers and the messages involved in those exchanges. - -3.1. The Authentication Service Exchange - - Summary - - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - The Authentication Service (AS) Exchange between the client and the - Kerberos Authentication Server is usually initiated by a client when - it wishes to obtain authentication credentials for a given server but - currently holds no credentials. The client's secret key is used for - encryption and decryption. This exchange is typically used at the - initiation of a login session, to obtain credentials for a Ticket- - Granting Server, which will subsequently be used to obtain - credentials for other servers (see section 3.3) without requiring - further use of the client's secret key. This exchange is also used - to request credentials for services which must not be mediated - through the Ticket-Granting Service, but rather require a principal's - secret key, such as the password-changing service. (The password- - changing request must not be honored unless the requester can provide - the old password (the user's current secret key). Otherwise, it - would be possible for someone to walk up to an unattended session and - change another user's password.) This exchange does not by itself - provide any assurance of the the identity of the user. (To - authenticate a user logging on to a local system, the credentials - obtained in the AS exchange may first be used in a TGS exchange to - obtain credentials for a local server. Those credentials must then - be verified by the local server through successful completion of the - Client/Server exchange.) - - The exchange consists of two messages: KRB_AS_REQ from the client to - Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these - messages are described in sections 5.4.1, 5.4.2, and 5.9.1. - - In the request, the client sends (in cleartext) its own identity and - the identity of the server for which it is requesting credentials. - The response, KRB_AS_REP, contains a ticket for the client to present - to the server, and a session key that will be shared by the client - and the server. The session key and additional information are - encrypted in the client's secret key. The KRB_AS_REP message - contains information which can be used to detect replays, and to - - - -Kohl & Neuman [Page 16] - -RFC 1510 Kerberos September 1993 - - - associate it with the message to which it replies. Various errors - can occur; these are indicated by an error response (KRB_ERROR) - instead of the KRB_AS_REP response. The error message is not - encrypted. The KRB_ERROR message also contains information which can - be used to associate it with the message to which it replies. The - lack of encryption in the KRB_ERROR message precludes the ability to - detect replays or fabrications of such messages. - - In the normal case the authentication server does not know whether - the client is actually the principal named in the request. It simply - sends a reply without knowing or caring whether they are the same. - This is acceptable because nobody but the principal whose identity - was given in the request will be able to use the reply. Its critical - information is encrypted in that principal's key. The initial - request supports an optional field that can be used to pass - additional information that might be needed for the initial exchange. - This field may be used for preauthentication if desired, but the - mechanism is not currently specified. - -3.1.1. Generation of KRB_AS_REQ message - - The client may specify a number of options in the initial request. - Among these options are whether preauthentication is to be performed; - whether the requested ticket is to be renewable, proxiable, or - forwardable; whether it should be postdated or allow postdating of - derivative tickets; and whether a renewable ticket will be accepted - in lieu of a non-renewable ticket if the requested ticket expiration - date cannot be satisfied by a nonrenewable ticket (due to - configuration constraints; see section 4). See section A.1 for - pseudocode. - - The client prepares the KRB_AS_REQ message and sends it to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - - If all goes well, processing the KRB_AS_REQ message will result in - the creation of a ticket for the client to present to the server. - The format for the ticket is described in section 5.3.1. The - contents of the ticket are determined as follows. - -3.1.3. Generation of KRB_AS_REP message - - The authentication server looks up the client and server principals - named in the KRB_AS_REQ in its database, extracting their respective - keys. If required, the server pre-authenticates the request, and if - the pre-authentication check fails, an error message with the code - KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate - the requested encryption type, an error message with code - - - -Kohl & Neuman [Page 17] - -RFC 1510 Kerberos September 1993 - - - KDC_ERR_ETYPE_NOSUPP is returned. Otherwise it generates a "random" - session key ("Random" means that, among other things, it should be - impossible to guess the next session key based on knowledge of past - session keys. This can only be achieved in a pseudo-random number - generator if it is based on cryptographic principles. It would be - more desirable to use a truly random number generator, such as one - based on measurements of random physical phenomena.). - - If the requested start time is absent or indicates a time in the - past, then the start time of the ticket is set to the authentication - server's current time. If it indicates a time in the future, but the - POSTDATED option has not been specified, then the error - KDC_ERR_CANNOT_POSTDATE is returned. Otherwise the requested start - time is checked against the policy of the local realm (the - administrator might decide to prohibit certain types or ranges of - postdated tickets), and if acceptable, the ticket's start time is set - as requested and the INVALID flag is set in the new ticket. The - postdated ticket must be validated before use by presenting it to the - KDC after the start time has been reached. - - The expiration time of the ticket will be set to the minimum of the - following: - - +The expiration time (endtime) requested in the KRB_AS_REQ - message. - - +The ticket's start time plus the maximum allowable lifetime - associated with the client principal (the authentication - server's database includes a maximum ticket lifetime field - in each principal's record; see section 4). - - +The ticket's start time plus the maximum allowable lifetime - associated with the server principal. - - +The ticket's start time plus the maximum lifetime set by - the policy of the local realm. - - If the requested expiration time minus the start time (as determined - above) is less than a site-determined minimum lifetime, an error - message with code KDC_ERR_NEVER_VALID is returned. If the requested - expiration time for the ticket exceeds what was determined as above, - and if the "RENEWABLE-OK" option was requested, then the "RENEWABLE" - flag is set in the new ticket, and the renew-till value is set as if - the "RENEWABLE" option were requested (the field and option names are - described fully in section 5.4.1). If the RENEWABLE option has been - requested or if the RENEWABLE-OK option has been set and a renewable - ticket is to be issued, then the renew-till field is set to the - minimum of: - - - -Kohl & Neuman [Page 18] - -RFC 1510 Kerberos September 1993 - - - +Its requested value. - - +The start time of the ticket plus the minimum of the two - maximum renewable lifetimes associated with the principals' - database entries. - - +The start time of the ticket plus the maximum renewable - lifetime set by the policy of the local realm. - - The flags field of the new ticket will have the following options set - if they have been requested and if the policy of the local realm - allows: FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. - If the new ticket is postdated (the start time is in the future), its - INVALID flag will also be set. - - If all of the above succeed, the server formats a KRB_AS_REP message - (see section 5.4.2), copying the addresses in the request into the - caddr of the response, placing any required pre-authentication data - into the padata of the response, and encrypts the ciphertext part in - the client's key using the requested encryption method, and sends it - to the client. See section A.2 for pseudocode. - -3.1.4. Generation of KRB_ERROR message - - Several errors can occur, and the Authentication Server responds by - returning an error message, KRB_ERROR, to the client, with the - error-code and e-text fields set to appropriate values. The error - message contents and details are described in Section 5.9.1. - -3.1.5. Receipt of KRB_AS_REP message - - If the reply message type is KRB_AS_REP, then the client verifies - that the cname and crealm fields in the cleartext portion of the - reply match what it requested. If any padata fields are present, - they may be used to derive the proper secret key to decrypt the - message. The client decrypts the encrypted part of the response - using its secret key, verifies that the nonce in the encrypted part - matches the nonce it supplied in its request (to detect replays). It - also verifies that the sname and srealm in the response match those - in the request, and that the host address field is also correct. It - then stores the ticket, session key, start and expiration times, and - other information for later use. The key-expiration field from the - encrypted part of the response may be checked to notify the user of - impending key expiration (the client program could then suggest - remedial action, such as a password change). See section A.3 for - pseudocode. - - Proper decryption of the KRB_AS_REP message is not sufficient to - - - -Kohl & Neuman [Page 19] - -RFC 1510 Kerberos September 1993 - - - verify the identity of the user; the user and an attacker could - cooperate to generate a KRB_AS_REP format message which decrypts - properly but is not from the proper KDC. If the host wishes to - verify the identity of the user, it must require the user to present - application credentials which can be verified using a securely-stored - secret key. If those credentials can be verified, then the identity - of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - - If the reply message type is KRB_ERROR, then the client interprets it - as an error and performs whatever application-specific tasks are - necessary to recover. - -3.2. The Client/Server Authentication Exchange - - Summary - - Message direction Message type Section - Client to Application server KRB_AP_REQ 5.5.1 - [optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - - The client/server authentication (CS) exchange is used by network - applications to authenticate the client to the server and vice versa. - The client must have already acquired credentials for the server - using the AS or TGS exchange. - -3.2.1. The KRB_AP_REQ message - - The KRB_AP_REQ contains authentication information which should be - part of the first message in an authenticated transaction. It - contains a ticket, an authenticator, and some additional bookkeeping - information (see section 5.5.1 for the exact format). The ticket by - itself is insufficient to authenticate a client, since tickets are - passed across the network in cleartext(Tickets contain both an - encrypted and unencrypted portion, so cleartext here refers to the - entire unit, which can be copied from one message and replayed in - another without any cryptographic skill.), so the authenticator is - used to prevent invalid replay of tickets by proving to the server - that the client knows the session key of the ticket and thus is - entitled to use it. The KRB_AP_REQ message is referred to elsewhere - as the "authentication header." - -3.2.2. Generation of a KRB_AP_REQ message - - When a client wishes to initiate authentication to a server, it - obtains (either through a credentials cache, the AS exchange, or the - - - -Kohl & Neuman [Page 20] - -RFC 1510 Kerberos September 1993 - - - TGS exchange) a ticket and session key for the desired service. The - client may re-use any tickets it holds until they expire. The client - then constructs a new Authenticator from the the system time, its - name, and optionally an application specific checksum, an initial - sequence number to be used in KRB_SAFE or KRB_PRIV messages, and/or a - session subkey to be used in negotiations for a session key unique to - this particular session. Authenticators may not be re-used and will - be rejected if replayed to a server (Note that this can make - applications based on unreliable transports difficult to code - correctly, if the transport might deliver duplicated messages. In - such cases, a new authenticator must be generated for each retry.). - If a sequence number is to be included, it should be randomly chosen - so that even after many messages have been exchanged it is not likely - to collide with other sequence numbers in use. - - The client may indicate a requirement of mutual authentication or the - use of a session-key based ticket by setting the appropriate flag(s) - in the ap-options field of the message. - - The Authenticator is encrypted in the session key and combined with - the ticket to form the KRB_AP_REQ message which is then sent to the - end server along with any additional application-specific - information. See section A.9 for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - - Authentication is based on the server's current time of day (clocks - must be loosely synchronized), the authenticator, and the ticket. - Several errors are possible. If an error occurs, the server is - expected to reply to the client with a KRB_ERROR message. This - message may be encapsulated in the application protocol if its "raw" - form is not acceptable to the protocol. The format of error messages - is described in section 5.9.1. - - The algorithm for verifying authentication information is as follows. - If the message type is not KRB_AP_REQ, the server returns the - KRB_AP_ERR_MSG_TYPE error. If the key version indicated by the Ticket - in the KRB_AP_REQ is not one the server can use (e.g., it indicates - an old key, and the server no longer possesses a copy of the old - key), the KRB_AP_ERR_BADKEYVER error is returned. If the USE- - SESSION-KEY flag is set in the ap-options field, it indicates to the - server that the ticket is encrypted in the session key from the - server's ticket-granting ticket rather than its secret key (This is - used for user-to-user authentication as described in [6]). Since it - is possible for the server to be registered in multiple realms, with - different keys in each, the srealm field in the unencrypted portion - of the ticket in the KRB_AP_REQ is used to specify which secret key - the server should use to decrypt that ticket. The KRB_AP_ERR_NOKEY - - - -Kohl & Neuman [Page 21] - -RFC 1510 Kerberos September 1993 - - - error code is returned if the server doesn't have the proper key to - decipher the ticket. - - The ticket is decrypted using the version of the server's key - specified by the ticket. If the decryption routines detect a - modification of the ticket (each encryption system must provide - safeguards to detect modified ciphertext; see section 6), the - KRB_AP_ERR_BAD_INTEGRITY error is returned (chances are good that - different keys were used to encrypt and decrypt). - - The authenticator is decrypted using the session key extracted from - the decrypted ticket. If decryption shows it to have been modified, - the KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm - of the client from the ticket are compared against the same fields in - the authenticator. If they don't match, the KRB_AP_ERR_BADMATCH - error is returned (they might not match, for example, if the wrong - session key was used to encrypt the authenticator). The addresses in - the ticket (if any) are then searched for an address matching the - operating-system reported address of the client. If no match is - found or the server insists on ticket addresses but none are present - in the ticket, the KRB_AP_ERR_BADADDR error is returned. - - If the local (server) time and the client time in the authenticator - differ by more than the allowable clock skew (e.g., 5 minutes), the - KRB_AP_ERR_SKEW error is returned. If the server name, along with - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - returned (Note that the rejection here is restricted to - authenticators from the same principal to the same server. Other - client principals communicating with the same server principal should - not be have their authenticators rejected if the time and microsecond - fields happen to match some other client's authenticator.). The - server must remember any authenticator presented within the allowable - clock skew, so that a replay attempt is guaranteed to fail. If a - server loses track of any authenticator presented within the - allowable clock skew, it must reject all requests until the clock - skew interval has passed. This assures that any lost or re-played - authenticators will fall outside the allowable clock skew and can no - longer be successfully replayed (If this is not done, an attacker - could conceivably record the ticket and authenticator sent over the - network to a server, then disable the client's host, pose as the - disabled host, and replay the ticket and authenticator to subvert the - authentication.). If a sequence number is provided in the - authenticator, the server saves it for later use in processing - KRB_SAFE and/or KRB_PRIV messages. If a subkey is present, the - server either saves it for later use or uses it to help generate its - own choice for a subkey to be returned in a KRB_AP_REP message. - - - - -Kohl & Neuman [Page 22] - -RFC 1510 Kerberos September 1993 - - - The server computes the age of the ticket: local (server) time minus - the start time inside the Ticket. If the start time is later than - the current time by more than the allowable clock skew or if the - INVALID flag is set in the ticket, the KRB_AP_ERR_TKT_NYV error is - returned. Otherwise, if the current time is later than end time by - more than the allowable clock skew, the KRB_AP_ERR_TKT_EXPIRED error - is returned. - - If all these checks succeed without an error, the server is assured - that the client possesses the credentials of the principal named in - the ticket and thus, the client has been authenticated to the server. - See section A.10 for pseudocode. - -3.2.4. Generation of a KRB_AP_REP message - - Typically, a client's request will include both the authentication - information and its initial request in the same message, and the - server need not explicitly reply to the KRB_AP_REQ. However, if - mutual authentication (not only authenticating the client to the - server, but also the server to the client) is being performed, the - KRB_AP_REQ message will have MUTUAL-REQUIRED set in its ap-options - field, and a KRB_AP_REP message is required in response. As with the - error message, this message may be encapsulated in the application - protocol if its "raw" form is not acceptable to the application's - protocol. The timestamp and microsecond field used in the reply must - be the client's timestamp and microsecond field (as provided in the - authenticator). [Note: In the Kerberos version 4 protocol, the - timestamp in the reply was the client's timestamp plus one. This is - not necessary in version 5 because version 5 messages are formatted - in such a way that it is not possible to create the reply by - judicious message surgery (even in encrypted form) without knowledge - of the appropriate encryption keys.] If a sequence number is to be - included, it should be randomly chosen as described above for the - authenticator. A subkey may be included if the server desires to - negotiate a different subkey. The KRB_AP_REP message is encrypted in - the session key extracted from the ticket. See section A.11 for - pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - - If a KRB_AP_REP message is returned, the client uses the session key - from the credentials obtained for the server (Note that for - encrypting the KRB_AP_REP message, the sub-session key is not used, - even if present in the Authenticator.) to decrypt the message, and - verifies that the timestamp and microsecond fields match those in the - Authenticator it sent to the server. If they match, then the client - is assured that the server is genuine. The sequence number and subkey - (if present) are retained for later use. See section A.12 for - - - -Kohl & Neuman [Page 23] - -RFC 1510 Kerberos September 1993 - - - pseudocode. - -3.2.6. Using the encryption key - - After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and - server share an encryption key which can be used by the application. - The "true session key" to be used for KRB_PRIV, KRB_SAFE, or other - application-specific uses may be chosen by the application based on - the subkeys in the KRB_AP_REP message and the authenticator - (Implementations of the protocol may wish to provide routines to - choose subkeys based on session keys and random numbers and to - orchestrate a negotiated key to be returned in the KRB_AP_REP - message.). In some cases, the use of this session key will be - implicit in the protocol; in others the method of use must be chosen - from a several alternatives. We leave the protocol negotiations of - how to use the key (e.g., selecting an encryption or checksum type) - to the application programmer; the Kerberos protocol does not - constrain the implementation options. - - With both the one-way and mutual authentication exchanges, the peers - should take care not to send sensitive information to each other - without proper assurances. In particular, applications that require - privacy or integrity should use the KRB_AP_REP or KRB_ERROR responses - from the server to client to assure both client and server of their - peer's identity. If an application protocol requires privacy of its - messages, it can use the KRB_PRIV message (section 3.5). The KRB_SAFE - message (section 3.4) can be used to assure integrity. - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - The TGS exchange between a client and the Kerberos Ticket-Granting - Server is initiated by a client when it wishes to obtain - authentication credentials for a given server (which might be - registered in a remote realm), when it wishes to renew or validate an - existing ticket, or when it wishes to obtain a proxy ticket. In the - first case, the client must already have acquired a ticket for the - Ticket-Granting Service using the AS exchange (the ticket-granting - ticket is usually obtained when a client initially authenticates to - the system, such as when a user logs in). The message format for the - TGS exchange is almost identical to that for the AS exchange. The - primary difference is that encryption and decryption in the TGS - - - -Kohl & Neuman [Page 24] - -RFC 1510 Kerberos September 1993 - - - exchange does not take place under the client's key. Instead, the - session key from the ticket-granting ticket or renewable ticket, or - sub-session key from an Authenticator is used. As is the case for - all application servers, expired tickets are not accepted by the TGS, - so once a renewable or ticket-granting ticket expires, the client - must use a separate exchange to obtain valid tickets. - - The TGS exchange consists of two messages: A request (KRB_TGS_REQ) - from the client to the Kerberos Ticket-Granting Server, and a reply - (KRB_TGS_REP or KRB_ERROR). The KRB_TGS_REQ message includes - information authenticating the client plus a request for credentials. - The authentication information consists of the authentication header - (KRB_AP_REQ) which includes the client's previously obtained ticket- - granting, renewable, or invalid ticket. In the ticket-granting - ticket and proxy cases, the request may include one or more of: a - list of network addresses, a collection of typed authorization data - to be sealed in the ticket for authorization use by the application - server, or additional tickets (the use of which are described later). - The TGS reply (KRB_TGS_REP) contains the requested credentials, - encrypted in the session key from the ticket-granting ticket or - renewable ticket, or if present, in the subsession key from the - Authenticator (part of the authentication header). The KRB_ERROR - message contains an error code and text explaining what went wrong. - The KRB_ERROR message is not encrypted. The KRB_TGS_REP message - contains information which can be used to detect replays, and to - associate it with the message to which it replies. The KRB_ERROR - message also contains information which can be used to associate it - with the message to which it replies, but the lack of encryption in - the KRB_ERROR message precludes the ability to detect replays or - fabrications of such messages. - -3.3.1. Generation of KRB_TGS_REQ message - - Before sending a request to the ticket-granting service, the client - must determine in which realm the application server is registered - [Note: This can be accomplished in several ways. It might be known - beforehand (since the realm is part of the principal identifier), or - it might be stored in a nameserver. Presently, however, this - information is obtained from a configuration file. If the realm to - be used is obtained from a nameserver, there is a danger of being - spoofed if the nameservice providing the realm name is not - authenticated. This might result in the use of a realm which has - been compromised, and would result in an attacker's ability to - compromise the authentication of the application server to the - client.]. If the client does not already possess a ticket-granting - ticket for the appropriate realm, then one must be obtained. This is - first attempted by requesting a ticket-granting ticket for the - destination realm from the local Kerberos server (using the - - - -Kohl & Neuman [Page 25] - -RFC 1510 Kerberos September 1993 - - - KRB_TGS_REQ message recursively). The Kerberos server may return a - TGT for the desired realm in which case one can proceed. - Alternatively, the Kerberos server may return a TGT for a realm which - is "closer" to the desired realm (further along the standard - hierarchical path), in which case this step must be repeated with a - Kerberos server in the realm specified in the returned TGT. If - neither are returned, then the request must be retried with a - Kerberos server for a realm higher in the hierarchy. This request - will itself require a ticket-granting ticket for the higher realm - which must be obtained by recursively applying these directions. - - Once the client obtains a ticket-granting ticket for the appropriate - realm, it determines which Kerberos servers serve that realm, and - contacts one. The list might be obtained through a configuration file - or network service; as long as the secret keys exchanged by realms - are kept secret, only denial of service results from a false Kerberos - server. - - As in the AS exchange, the client may specify a number of options in - the KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ - message, providing an authentication header as an element of the - padata field, and including the same fields as used in the KRB_AS_REQ - message along with several optional fields: the enc-authorization- - data field for application server use and additional tickets required - by some options. - - In preparing the authentication header, the client can select a sub- - session key under which the response from the Kerberos server will be - encrypted (If the client selects a sub-session key, care must be - taken to ensure the randomness of the selected subsession key. One - approach would be to generate a random number and XOR it with the - session key from the ticket-granting ticket.). If the sub-session key - is not specified, the session key from the ticket-granting ticket - will be used. If the enc-authorization-data is present, it must be - encrypted in the sub-session key, if present, from the authenticator - portion of the authentication header, or if not present in the - session key from the ticket-granting ticket. - - Once prepared, the message is sent to a Kerberos server for the - destination realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - - The KRB_TGS_REQ message is processed in a manner similar to the - KRB_AS_REQ message, but there are many additional checks to be - performed. First, the Kerberos server must determine which server - the accompanying ticket is for and it must select the appropriate key - to decrypt it. For a normal KRB_TGS_REQ message, it will be for the - - - -Kohl & Neuman [Page 26] - -RFC 1510 Kerberos September 1993 - - - ticket granting service, and the TGS's key will be used. If the TGT - was issued by another realm, then the appropriate inter-realm key - must be used. If the accompanying ticket is not a ticket granting - ticket for the current realm, but is for an application server in the - current realm, the RENEW, VALIDATE, or PROXY options are specified in - the request, and the server for which a ticket is requested is the - server named in the accompanying ticket, then the KDC will decrypt - the ticket in the authentication header using the key of the server - for which it was issued. If no ticket can be found in the padata - field, the KDC_ERR_PADATA_TYPE_NOSUPP error is returned. - - Once the accompanying ticket has been decrypted, the user-supplied - checksum in the Authenticator must be verified against the contents - of the request, and the message rejected if the checksums do not - match (with an error code of KRB_AP_ERR_MODIFIED) or if the checksum - is not keyed or not collision-proof (with an error code of - KRB_AP_ERR_INAPP_CKSUM). If the checksum type is not supported, the - KDC_ERR_SUMTYPE_NOSUPP error is returned. If the authorization-data - are present, they are decrypted using the sub-session key from the - Authenticator. - - If any of the decryptions indicate failed integrity checks, the - KRB_AP_ERR_BAD_INTEGRITY error is returned. - -3.3.3. Generation of KRB_TGS_REP message - - The KRB_TGS_REP message shares its format with the KRB_AS_REP - (KRB_KDC_REP), but with its type field set to KRB_TGS_REP. The - detailed specification is in section 5.4.2. - - The response will include a ticket for the requested server. The - Kerberos database is queried to retrieve the record for the requested - server (including the key with which the ticket will be encrypted). - If the request is for a ticket granting ticket for a remote realm, - and if no key is shared with the requested realm, then the Kerberos - server will select the realm "closest" to the requested realm with - which it does share a key, and use that realm instead. This is the - only case where the response from the KDC will be for a different - server than that requested by the client. - - By default, the address field, the client's name and realm, the list - of transited realms, the time of initial authentication, the - expiration time, and the authorization data of the newly-issued - ticket will be copied from the ticket-granting ticket (TGT) or - renewable ticket. If the transited field needs to be updated, but - the transited type is not supported, the KDC_ERR_TRTYPE_NOSUPP error - is returned. - - - - -Kohl & Neuman [Page 27] - -RFC 1510 Kerberos September 1993 - - - If the request specifies an endtime, then the endtime of the new - ticket is set to the minimum of (a) that request, (b) the endtime - from the TGT, and (c) the starttime of the TGT plus the minimum of - the maximum life for the application server and the maximum life for - the local realm (the maximum life for the requesting principal was - already applied when the TGT was issued). If the new ticket is to be - a renewal, then the endtime above is replaced by the minimum of (a) - the value of the renew_till field of the ticket and (b) the starttime - for the new ticket plus the life (endtimestarttime) of the old - ticket. - - If the FORWARDED option has been requested, then the resulting ticket - will contain the addresses specified by the client. This option will - only be honored if the FORWARDABLE flag is set in the TGT. The PROXY - option is similar; the resulting ticket will contain the addresses - specified by the client. It will be honored only if the PROXIABLE - flag in the TGT is set. The PROXY option will not be honored on - requests for additional ticket-granting tickets. - - If the requested start time is absent or indicates a time in the - past, then the start time of the ticket is set to the authentication - server's current time. If it indicates a time in the future, but the - POSTDATED option has not been specified or the MAY-POSTDATE flag is - not set in the TGT, then the error KDC_ERR_CANNOT_POSTDATE is - returned. Otherwise, if the ticket-granting ticket has the - MAYPOSTDATE flag set, then the resulting ticket will be postdated and - the requested starttime is checked against the policy of the local - realm. If acceptable, the ticket's start time is set as requested, - and the INVALID flag is set. The postdated ticket must be validated - before use by presenting it to the KDC after the starttime has been - reached. However, in no case may the starttime, endtime, or renew- - till time of a newly-issued postdated ticket extend beyond the - renew-till time of the ticket-granting ticket. - - If the ENC-TKT-IN-SKEY option has been specified and an additional - ticket has been included in the request, the KDC will decrypt the - additional ticket using the key for the server to which the - additional ticket was issued and verify that it is a ticket-granting - ticket. If the name of the requested server is missing from the - request, the name of the client in the additional ticket will be - used. Otherwise the name of the requested server will be compared to - the name of the client in the additional ticket and if different, the - request will be rejected. If the request succeeds, the session key - from the additional ticket will be used to encrypt the new ticket - that is issued instead of using the key of the server for which the - new ticket will be used (This allows easy implementation of user-to- - user authentication [6], which uses ticket-granting ticket session - keys in lieu of secret server keys in situations where such secret - - - -Kohl & Neuman [Page 28] - -RFC 1510 Kerberos September 1993 - - - keys could be easily compromised.). - - If the name of the server in the ticket that is presented to the KDC - as part of the authentication header is not that of the ticket- - granting server itself, and the server is registered in the realm of - the KDC, If the RENEW option is requested, then the KDC will verify - that the RENEWABLE flag is set in the ticket and that the renew_till - time is still in the future. If the VALIDATE option is rqeuested, - the KDC will check that the starttime has passed and the INVALID flag - is set. If the PROXY option is requested, then the KDC will check - that the PROXIABLE flag is set in the ticket. If the tests succeed, - the KDC will issue the appropriate new ticket. - - Whenever a request is made to the ticket-granting server, the - presented ticket(s) is(are) checked against a hot-list of tickets - which have been canceled. This hot-list might be implemented by - storing a range of issue dates for "suspect tickets"; if a presented - ticket had an authtime in that range, it would be rejected. In this - way, a stolen ticket-granting ticket or renewable ticket cannot be - used to gain additional tickets (renewals or otherwise) once the - theft has been reported. Any normal ticket obtained before it was - reported stolen will still be valid (because they require no - interaction with the KDC), but only until their normal expiration - time. - - The ciphertext part of the response in the KRB_TGS_REP message is - encrypted in the sub-session key from the Authenticator, if present, - or the session key key from the ticket-granting ticket. It is not - encrypted using the client's secret key. Furthermore, the client's - key's expiration date and the key version number fields are left out - since these values are stored along with the client's database - record, and that record is not needed to satisfy a request based on a - ticket-granting ticket. See section A.6 for pseudocode. - -3.3.3.1. Encoding the transited field - - If the identity of the server in the TGT that is presented to the KDC - as part of the authentication header is that of the ticket-granting - service, but the TGT was issued from another realm, the KDC will look - up the inter-realm key shared with that realm and use that key to - decrypt the ticket. If the ticket is valid, then the KDC will honor - the request, subject to the constraints outlined above in the section - describing the AS exchange. The realm part of the client's identity - will be taken from the ticket-granting ticket. The name of the realm - that issued the ticket-granting ticket will be added to the transited - field of the ticket to be issued. This is accomplished by reading - the transited field from the ticket-granting ticket (which is treated - as an unordered set of realm names), adding the new realm to the set, - - - -Kohl & Neuman [Page 29] - -RFC 1510 Kerberos September 1993 - - - then constructing and writing out its encoded (shorthand) form (this - may involve a rearrangement of the existing encoding). - - Note that the ticket-granting service does not add the name of its - own realm. Instead, its responsibility is to add the name of the - previous realm. This prevents a malicious Kerberos server from - intentionally leaving out its own name (it could, however, omit other - realms' names). - - The names of neither the local realm nor the principal's realm are to - be included in the transited field. They appear elsewhere in the - ticket and both are known to have taken part in authenticating the - principal. Since the endpoints are not included, both local and - single-hop inter-realm authentication result in a transited field - that is empty. - - Because the name of each realm transited is added to this field, - it might potentially be very long. To decrease the length of this - field, its contents are encoded. The initially supported encoding is - optimized for the normal case of inter-realm communication: a - hierarchical arrangement of realms using either domain or X.500 style - realm names. This encoding (called DOMAIN-X500-COMPRESS) is now - described. - - Realm names in the transited field are separated by a ",". The ",", - "\", trailing "."s, and leading spaces (" ") are special characters, - and if they are part of a realm name, they must be quoted in the - transited field by preceding them with a "\". - - A realm name ending with a "." is interpreted as being prepended to - the previous realm. For example, we can encode traversal of EDU, - MIT.EDU, ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - - Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were endpoints, - that they would not be included in this field, and we would have: - - "EDU,MIT.,WASHINGTON.EDU" - - A realm name beginning with a "/" is interpreted as being appended to - the previous realm (For the purpose of appending, the realm preceding - the first listed realm is considered to be the null realm ("")). If - it is to stand by itself, then it should be preceded by a space (" - "). For example, we can encode traversal of /COM/HP/APOLLO, /COM/HP, - /COM, and /COM/DEC as: - - "/COM,/HP,/APOLLO, /COM/DEC". - - - -Kohl & Neuman [Page 30] - -RFC 1510 Kerberos September 1993 - - - Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, - they they would not be included in this field, and we would have: - - "/COM,/HP" - - A null subfield preceding or following a "," indicates that all - realms between the previous realm and the next realm have been - traversed (For the purpose of interpreting null subfields, the - client's realm is considered to precede those in the transited field, - and the server's realm is considered to follow them.). Thus, "," - means that all realms along the path between the client and the - server have been traversed. ",EDU, /COM," means that that all realms - from the client's realm up to EDU (in a domain style hierarchy) have - been traversed, and that everything from /COM down to the server's - realm in an X.500 style has also been traversed. This could occur if - the EDU realm in one hierarchy shares an inter-realm key directly - with the /COM realm in another hierarchy. - -3.3.4. Receipt of KRB_TGS_REP message - - When the KRB_TGS_REP is received by the client, it is processed in - the same manner as the KRB_AS_REP processing described above. The - primary difference is that the ciphertext part of the response must - be decrypted using the session key from the ticket-granting ticket - rather than the client's secret key. See section A.7 for pseudocode. - -3.4. The KRB_SAFE Exchange - - The KRB_SAFE message may be used by clients requiring the ability to - detect modifications of messages they exchange. It achieves this by - including a keyed collisionproof checksum of the user data and some - control information. The checksum is keyed with an encryption key - (usually the last key negotiated via subkeys, or the session key if - no negotiation has occured). - -3.4.1. Generation of a KRB_SAFE message - - When an application wishes to send a KRB_SAFE message, it collects - its data and the appropriate control information and computes a - checksum over them. The checksum algorithm should be some sort of - keyed one-way hash function (such as the RSA-MD5-DES checksum - algorithm specified in section 6.4.5, or the DES MAC), generated - using the sub-session key if present, or the session key. Different - algorithms may be selected by changing the checksum type in the - message. Unkeyed or non-collision-proof checksums are not suitable - for this use. - - The control information for the KRB_SAFE message includes both a - - - -Kohl & Neuman [Page 31] - -RFC 1510 Kerberos September 1993 - - - timestamp and a sequence number. The designer of an application - using the KRB_SAFE message must choose at least one of the two - mechanisms. This choice should be based on the needs of the - application protocol. - - Sequence numbers are useful when all messages sent will be received - by one's peer. Connection state is presently required to maintain - the session key, so maintaining the next sequence number should not - present an additional problem. - - If the application protocol is expected to tolerate lost messages - without them being resent, the use of the timestamp is the - appropriate replay detection mechanism. Using timestamps is also the - appropriate mechanism for multi-cast protocols where all of one's - peers share a common sub-session key, but some messages will be sent - to a subset of one's peers. - - After computing the checksum, the client then transmits the - information and checksum to the recipient in the message format - specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - - When an application receives a KRB_SAFE message, it verifies it as - follows. If any error occurs, an error code is reported for use by - the application. - - The message is first checked by verifying that the protocol version - and type fields match the current version and KRB_SAFE, respectively. - A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE - error. The application verifies that the checksum used is a - collisionproof keyed checksum, and if it is not, a - KRB_AP_ERR_INAPP_CKSUM error is generated. The recipient verifies - that the operating system's report of the sender's address matches - the sender's address in the message, and (if a recipient address is - specified or the recipient requires an address) that one of the - recipient's addresses appears as the recipient's address in the - message. A failed match for either case generates a - KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the - sequence number fields are checked. If timestamp and usec are - expected and not present, or they are present but not current, the - KRB_AP_ERR_SKEW error is generated. If the server name, along with - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - generated. If an incorrect sequence number is included, or a - sequence number is expected but not present, the KRB_AP_ERR_BADORDER - error is generated. If neither a timestamp and usec or a sequence - number is present, a KRB_AP_ERR_MODIFIED error is generated. - - - -Kohl & Neuman [Page 32] - -RFC 1510 Kerberos September 1993 - - - Finally, the checksum is computed over the data and control - information, and if it doesn't match the received checksum, a - KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application is assured that the - message was generated by its peer and was not modified in transit. - -3.5. The KRB_PRIV Exchange - - The KRB_PRIV message may be used by clients requiring confidentiality - and the ability to detect modifications of exchanged messages. It - achieves this by encrypting the messages and adding control - information. - -3.5.1. Generation of a KRB_PRIV message - - When an application wishes to send a KRB_PRIV message, it collects - its data and the appropriate control information (specified in - section 5.7.1) and encrypts them under an encryption key (usually the - last key negotiated via subkeys, or the session key if no negotiation - has occured). As part of the control information, the client must - choose to use either a timestamp or a sequence number (or both); see - the discussion in section 3.4.1 for guidelines on which to use. - After the user data and control information are encrypted, the client - transmits the ciphertext and some "envelope" information to the - recipient. - -3.5.2. Receipt of KRB_PRIV message - - When an application receives a KRB_PRIV message, it verifies it as - follows. If any error occurs, an error code is reported for use by - the application. - - The message is first checked by verifying that the protocol version - and type fields match the current version and KRB_PRIV, respectively. - A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE - error. The application then decrypts the ciphertext and processes - the resultant plaintext. If decryption shows the data to have been - modified, a KRB_AP_ERR_BAD_INTEGRITY error is generated. The - recipient verifies that the operating system's report of the sender's - address matches the sender's address in the message, and (if a - recipient address is specified or the recipient requires an address) - that one of the recipient's addresses appears as the recipient's - address in the message. A failed match for either case generates a - KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the - sequence number fields are checked. If timestamp and usec are - expected and not present, or they are present but not current, the - KRB_AP_ERR_SKEW error is generated. If the server name, along with - - - -Kohl & Neuman [Page 33] - -RFC 1510 Kerberos September 1993 - - - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - generated. If an incorrect sequence number is included, or a - sequence number is expected but not present, the KRB_AP_ERR_BADORDER - error is generated. If neither a timestamp and usec or a sequence - number is present, a KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application can assume the message was - generated by its peer, and was securely transmitted (without - intruders able to see the unencrypted contents). - -3.6. The KRB_CRED Exchange - - The KRB_CRED message may be used by clients requiring the ability to - send Kerberos credentials from one host to another. It achieves this - by sending the tickets together with encrypted data containing the - session keys and other information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - - When an application wishes to send a KRB_CRED message it first (using - the KRB_TGS exchange) obtains credentials to be sent to the remote - host. It then constructs a KRB_CRED message using the ticket or - tickets so obtained, placing the session key needed to use each - ticket in the key field of the corresponding KrbCredInfo sequence of - the encrypted part of the the KRB_CRED message. - - Other information associated with each ticket and obtained during the - KRB_TGS exchange is also placed in the corresponding KrbCredInfo - sequence in the encrypted part of the KRB_CRED message. The current - time and, if specifically required by the application the nonce, s- - address, and raddress fields, are placed in the encrypted part of the - KRB_CRED message which is then encrypted under an encryption key - previosuly exchanged in the KRB_AP exchange (usually the last key - negotiated via subkeys, or the session key if no negotiation has - occured). - -3.6.2. Receipt of KRB_CRED message - - When an application receives a KRB_CRED message, it verifies it. If - any error occurs, an error code is reported for use by the - application. The message is verified by checking that the protocol - version and type fields match the current version and KRB_CRED, - respectively. A mismatch generates a KRB_AP_ERR_BADVERSION or - KRB_AP_ERR_MSG_TYPE error. The application then decrypts the - ciphertext and processes the resultant plaintext. If decryption shows - the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is - generated. - - - -Kohl & Neuman [Page 34] - -RFC 1510 Kerberos September 1993 - - - If present or required, the recipient verifies that the operating - system's report of the sender's address matches the sender's address - in the message, and that one of the recipient's addresses appears as - the recipient's address in the message. A failed match for either - case generates a KRB_AP_ERR_BADADDR error. The timestamp and usec - fields (and the nonce field if required) are checked next. If the - timestamp and usec are not present, or they are present but not - current, the KRB_AP_ERR_SKEW error is generated. - - If all the checks succeed, the application stores each of the new - tickets in its ticket cache together with the session key and other - information in the corresponding KrbCredInfo sequence from the - encrypted part of the KRB_CRED message. - -4. The Kerberos Database - - The Kerberos server must have access to a database containing the - principal identifiers and secret keys of principals to be - authenticated (The implementation of the Kerberos server need not - combine the database and the server on the same machine; it is - feasible to store the principal database in, say, a network name - service, as long as the entries stored therein are protected from - disclosure to and modification by unauthorized parties. However, we - recommend against such strategies, as they can make system management - and threat analysis quite complex.). - -4.1. Database contents - - A database entry should contain at least the following fields: - - Field Value - - name Principal's identifier - key Principal's secret key - p_kvno Principal's key version - max_life Maximum lifetime for Tickets - max_renewable_life Maximum total lifetime for renewable - Tickets - - The name field is an encoding of the principal's identifier. The key - field contains an encryption key. This key is the principal's secret - key. (The key can be encrypted before storage under a Kerberos - "master key" to protect it in case the database is compromised but - the master key is not. In that case, an extra field must be added to - indicate the master key version used, see below.) The p_kvno field is - the key version number of the principal's secret key. The max_life - field contains the maximum allowable lifetime (endtime - starttime) - for any Ticket issued for this principal. The max_renewable_life - - - -Kohl & Neuman [Page 35] - -RFC 1510 Kerberos September 1993 - - - field contains the maximum allowable total lifetime for any renewable - Ticket issued for this principal. (See section 3.1 for a description - of how these lifetimes are used in determining the lifetime of a - given Ticket.) - - A server may provide KDC service to several realms, as long as the - database representation provides a mechanism to distinguish between - principal records with identifiers which differ only in the realm - name. - - When an application server's key changes, if the change is routine - (i.e., not the result of disclosure of the old key), the old key - should be retained by the server until all tickets that had been - issued using that key have expired. Because of this, it is possible - for several keys to be active for a single principal. Ciphertext - encrypted in a principal's key is always tagged with the version of - the key that was used for encryption, to help the recipient find the - proper key for decryption. - - When more than one key is active for a particular principal, the - principal will have more than one record in the Kerberos database. - The keys and key version numbers will differ between the records (the - rest of the fields may or may not be the same). Whenever Kerberos - issues a ticket, or responds to a request for initial authentication, - the most recent key (known by the Kerberos server) will be used for - encryption. This is the key with the highest key version number. - -4.2. Additional fields - - Project Athena's KDC implementation uses additional fields in its - database: - - Field Value - - K_kvno Kerberos' key version - expiration Expiration date for entry - attributes Bit field of attributes - mod_date Timestamp of last modification - mod_name Modifying principal's identifier - - The K_kvno field indicates the key version of the Kerberos master key - under which the principal's secret key is encrypted. - - After an entry's expiration date has passed, the KDC will return an - error to any client attempting to gain tickets as or for the - principal. (A database may want to maintain two expiration dates: - one for the principal, and one for the principal's current key. This - allows password aging to work independently of the principal's - - - -Kohl & Neuman [Page 36] - -RFC 1510 Kerberos September 1993 - - - expiration date. However, due to the limited space in the responses, - the KDC must combine the key expiration and principal expiration date - into a single value called "key_exp", which is used as a hint to the - user to take administrative action.) - - The attributes field is a bitfield used to govern the operations - involving the principal. This field might be useful in conjunction - with user registration procedures, for site-specific policy - implementations (Project Athena currently uses it for their user - registration process controlled by the system-wide database service, - Moira [7]), or to identify the "string to key" conversion algorithm - used for a principal's key. (See the discussion of the padata field - in section 5.4.2 for details on why this can be useful.) Other bits - are used to indicate that certain ticket options should not be - allowed in tickets encrypted under a principal's key (one bit each): - Disallow issuing postdated tickets, disallow issuing forwardable - tickets, disallow issuing tickets based on TGT authentication, - disallow issuing renewable tickets, disallow issuing proxiable - tickets, and disallow issuing tickets for which the principal is the - server. - - The mod_date field contains the time of last modification of the - entry, and the mod_name field contains the name of the principal - which last modified the entry. - -4.3. Frequently Changing Fields - - Some KDC implementations may wish to maintain the last time that a - request was made by a particular principal. Information that might - be maintained includes the time of the last request, the time of the - last request for a ticket-granting ticket, the time of the last use - of a ticket-granting ticket, or other times. This information can - then be returned to the user in the last-req field (see section 5.2). - - Other frequently changing information that can be maintained is the - latest expiration time for any tickets that have been issued using - each key. This field would be used to indicate how long old keys - must remain valid to allow the continued use of outstanding tickets. - -4.4. Site Constants - - The KDC implementation should have the following configurable - constants or options, to allow an administrator to make and enforce - policy decisions: - - + The minimum supported lifetime (used to determine whether the - KDC_ERR_NEVER_VALID error should be returned). This constant - should reflect reasonable expectations of round-trip time to the - - - -Kohl & Neuman [Page 37] - -RFC 1510 Kerberos September 1993 - - - KDC, encryption/decryption time, and processing time by the client - and target server, and it should allow for a minimum "useful" - lifetime. - - + The maximum allowable total (renewable) lifetime of a ticket - (renew_till - starttime). - - + The maximum allowable lifetime of a ticket (endtime - starttime). - - + Whether to allow the issue of tickets with empty address fields - (including the ability to specify that such tickets may only be - issued if the request specifies some authorization_data). - - + Whether proxiable, forwardable, renewable or post-datable tickets - are to be issued. - -5. Message Specifications - - The following sections describe the exact contents and encoding of - protocol messages and objects. The ASN.1 base definitions are - presented in the first subsection. The remaining subsections specify - the protocol objects (tickets and authenticators) and messages. - Specification of encryption and checksum techniques, and the fields - related to them, appear in section 6. - -5.1. ASN.1 Distinguished Encoding Representation - - All uses of ASN.1 in Kerberos shall use the Distinguished Encoding - Representation of the data elements as described in the X.509 - specification, section 8.7 [8]. - -5.2. ASN.1 Base Definitions - - The following ASN.1 base definitions are used in the rest of this - section. Note that since the underscore character (_) is not - permitted in ASN.1 names, the hyphen (-) is used in its place for the - purposes of ASN.1 names. - - Realm ::= GeneralString - PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString - } - - Kerberos realms are encoded as GeneralStrings. Realms shall not - contain a character with the code 0 (the ASCII NUL). Most realms - will usually consist of several components separated by periods (.), - in the style of Internet Domain Names, or separated by slashes (/) in - - - -Kohl & Neuman [Page 38] - -RFC 1510 Kerberos September 1993 - - - the style of X.500 names. Acceptable forms for realm names are - specified in section 7. A PrincipalName is a typed sequence of - components consisting of the following sub-fields: - - name-type This field specifies the type of name that follows. - Pre-defined values for this field are - specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two - names can be the same (i.e., at least one of the - components, or the realm, must be different). - This constraint may be eliminated in the future. - - name-string This field encodes a sequence of components that - form a name, each component encoded as a General - String. Taken together, a PrincipalName and a Realm - form a principal identifier. Most PrincipalNames - will have only a few components (typically one or two). - - KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - - The timestamps used in Kerberos are encoded as GeneralizedTimes. An - encoding shall specify the UTC time zone (Z) and shall not include - any fractional portions of the seconds. It further shall not include - any separators. Example: The only valid format for UTC time 6 - minutes, 27 seconds after 9 pm on 6 November 1985 is 19851106210627Z. - - HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - } - - HostAddresses ::= SEQUENCE OF SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - } - - - The host adddress encodings consists of two fields: - - addr-type This field specifies the type of address that - follows. Pre-defined values for this field are - specified in section 8.1. - - - address This field encodes a single address of type addr-type. - - The two forms differ slightly. HostAddress contains exactly one - - - -Kohl & Neuman [Page 39] - -RFC 1510 Kerberos September 1993 - - - address; HostAddresses contains a sequence of possibly many - addresses. - - AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING - } - - - ad-data This field contains authorization data to be - interpreted according to the value of the - corresponding ad-type field. - - ad-type This field specifies the format for the ad-data - subfield. All negative values are reserved for - local use. Non-negative values are reserved for - registered use. - - APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - } - - - TicketFlags ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - may-postdate(5), - postdated(6), - invalid(7), - renewable(8), - initial(9), - pre-authent(10), - hw-authent(11) - } - - KDCOptions ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - allow-postdate(5), - postdated(6), - - - -Kohl & Neuman [Page 40] - -RFC 1510 Kerberos September 1993 - - - unused7(7), - renewable(8), - unused9(9), - unused10(10), - unused11(11), - renewable-ok(27), - enc-tkt-in-skey(28), - renew(30), - validate(31) - } - - - LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime - } - - lr-type This field indicates how the following lr-value - field is to be interpreted. Negative values indicate - that the information pertains only to the - responding server. Non-negative values pertain to - all servers for the realm. - - If the lr-type field is zero (0), then no information - is conveyed by the lr-value subfield. If the - absolute value of the lr-type field is one (1), - then the lr-value subfield is the time of last - initial request for a TGT. If it is two (2), then - the lr-value subfield is the time of last initial - request. If it is three (3), then the lr-value - subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), - then the lr-value subfield is the time of the last - renewal. If it is five (5), then the lr-value - subfield is the time of last request (of any - type). - - lr-value This field contains the time of the last request. - The time must be interpreted according to the contents - of the accompanying lr-type subfield. - - See section 6 for the definitions of Checksum, ChecksumType, - EncryptedData, EncryptionKey, EncryptionType, and KeyType. - - - - - - - - -Kohl & Neuman [Page 41] - -RFC 1510 Kerberos September 1993 - - -5.3. Tickets and Authenticators - - This section describes the format and encryption parameters for - tickets and authenticators. When a ticket or authenticator is - included in a protocol message it is treated as an opaque object. - -5.3.1. Tickets - - A ticket is a record that helps a client authenticate to a service. - A Ticket contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData -} --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be registered - contents[1] OCTET STRING -} - - The encoding of EncTicketPart is encrypted in the key shared by - Kerberos and the end server (the server's secret key). See section 6 - for the format of the ciphertext. - - tkt-vno This field specifies the version number for the ticket - format. This document describes version number 5. - - realm This field specifies the realm that issued a ticket. It - also serves to identify the realm part of the server's - principal identifier. Since a Kerberos server can only - issue tickets for servers within its realm, the two will - - - -Kohl & Neuman [Page 42] - -RFC 1510 Kerberos September 1993 - - - always be identical. - - sname This field specifies the name part of the server's - identity. - - enc-part This field holds the encrypted encoding of the - EncTicketPart sequence. - - flags This field indicates which of various options were used or - requested when the ticket was issued. It is a bit-field, - where the selected options are indicated by the bit being - set (1), and the unselected options and reserved fields - being reset (0). Bit 0 is the most significant bit. The - encoding of the bits is specified in section 5.2. The - flags are described in more detail above in section 2. The - meanings of the flags are: - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of this - field. - - 1 FORWARDABLE The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, - this flag tells the ticket-granting - server that it is OK to issue a new - ticket- granting ticket with a - different network address based on - the presented ticket. - - 2 FORWARDED When set, this flag indicates that - the ticket has either been forwarded - or was issued based on authentication - involving a forwarded ticket-granting - ticket. - - 3 PROXIABLE The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical - to that of the FORWARDABLE flag, - except that the PROXIABLE flag tells - the ticket-granting server that only - non- ticket-granting tickets may be - issued with different network - addresses. - - - - -Kohl & Neuman [Page 43] - -RFC 1510 Kerberos September 1993 - - - 4 PROXY When set, this flag indicates that a - ticket is a proxy. - - 5 MAY-POSTDATE The MAY-POSTDATE flag is normally - only interpreted by the TGS, and can - be ignored by end servers. This flag - tells the ticket-granting server that - a post- dated ticket may be issued - based on this ticket-granting ticket. - - 6 POSTDATED This flag indicates that this ticket - has been postdated. The end-service - can check the authtime field to see - when the original authentication - occurred. - - 7 INVALID This flag indicates that a ticket is - invalid, and it must be validated by - the KDC before use. Application - servers must reject tickets which - have this flag set. - - 8 RENEWABLE The RENEWABLE flag is normally only - interpreted by the TGS, and can - usually be ignored by end servers - (some particularly careful servers - may wish to disallow renewable - tickets). A renewable ticket can be - used to obtain a replacement ticket - that expires at a later date. - - 9 INITIAL This flag indicates that this ticket - was issued using the AS protocol, and - not issued based on a ticket-granting - ticket. - - 10 PRE-AUTHENT This flag indicates that during - initial authentication, the client - was authenticated by the KDC before a - ticket was issued. The strength of - the preauthentication method is not - indicated, but is acceptable to the - KDC. - - 11 HW-AUTHENT This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected - to be possessed solely by the named - - - -Kohl & Neuman [Page 44] - -RFC 1510 Kerberos September 1993 - - - client. The hardware authentication - method is selected by the KDC and the - strength of the method is not - indicated. - - 12-31 RESERVED Reserved for future use. - - key This field exists in the ticket and the KDC response and is - used to pass the session key from Kerberos to the - application server and the client. The field's encoding is - described in section 6.2. - - crealm This field contains the name of the realm in which the - client is registered and in which initial authentication - took place. - - cname This field contains the name part of the client's principal - identifier. - - transited This field lists the names of the Kerberos realms that took - part in authenticating the user to whom this ticket was - issued. It does not specify the order in which the realms - were transited. See section 3.3.3.1 for details on how - this field encodes the traversed realms. - - authtime This field indicates the time of initial authentication for - the named principal. It is the time of issue for the - original ticket on which this ticket is based. It is - included in the ticket to provide additional information to - the end service, and to provide the necessary information - for implementation of a `hot list' service at the KDC. An - end service that is particularly paranoid could refuse to - accept tickets for which the initial authentication - occurred "too far" in the past. - - This field is also returned as part of the response from - the KDC. When returned as part of the response to initial - authentication (KRB_AS_REP), this is the current time on - the Kerberos server (It is NOT recommended that this time - value be used to adjust the workstation's clock since the - workstation cannot reliably determine that such a - KRB_AS_REP actually came from the proper KDC in a timely - manner.). - - starttime This field in the ticket specifies the time after which the - ticket is valid. Together with endtime, this field - specifies the life of the ticket. If it is absent from - the ticket, its value should be treated as that of the - - - -Kohl & Neuman [Page 45] - -RFC 1510 Kerberos September 1993 - - - authtime field. - - endtime This field contains the time after which the ticket will - not be honored (its expiration time). Note that individual - services may place their own limits on the life of a ticket - and may reject tickets which have not yet expired. As - such, this is really an upper bound on the expiration time - for the ticket. - - renew-till This field is only present in tickets that have the - RENEWABLE flag set in the flags field. It indicates the - maximum endtime that may be included in a renewal. It can - be thought of as the absolute expiration time for the - ticket, including all renewals. - - caddr This field in a ticket contains zero (if omitted) or more - (if present) host addresses. These are the addresses from - which the ticket can be used. If there are no addresses, - the ticket can be used from any location. The decision - by the KDC to issue or by the end server to accept zero- - address tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may refuse to - issue or accept such tickets. The suggested and default - policy, however, is that such tickets will only be issued - or accepted when additional information that can be used to - restrict the use of the ticket is included in the - authorization_data field. Such a ticket is a capability. - - Network addresses are included in the ticket to make it - harder for an attacker to use stolen credentials. Because - the session key is not sent over the network in cleartext, - credentials can't be stolen simply by listening to the - network; an attacker has to gain access to the session key - (perhaps through operating system security breaches or a - careless user's unattended session) to make use of stolen - tickets. - - It is important to note that the network address from which - a connection is received cannot be reliably determined. - Even if it could be, an attacker who has compromised the - client's workstation could use the credentials from there. - Including the network addresses only makes it more - difficult, not impossible, for an attacker to walk off with - stolen credentials and then use them from a "safe" - location. - - - - - - -Kohl & Neuman [Page 46] - -RFC 1510 Kerberos September 1993 - - - authorization-data The authorization-data field is used to pass - authorization data from the principal on whose behalf a - ticket was issued to the application service. If no - authorization data is included, this field will be left - out. The data in this field are specific to the end - service. It is expected that the field will contain the - names of service specific objects, and the rights to those - objects. The format for this field is described in section - 5.2. Although Kerberos is not concerned with the format of - the contents of the subfields, it does carry type - information (ad-type). - - By using the authorization_data field, a principal is able - to issue a proxy that is valid for a specific purpose. For - example, a client wishing to print a file can obtain a file - server proxy to be passed to the print server. By - specifying the name of the file in the authorization_data - field, the file server knows that the print server can only - use the client's rights when accessing the particular file - to be printed. - - It is interesting to note that if one specifies the - authorization-data field of a proxy and leaves the host - addresses blank, the resulting ticket and session key can - be treated as a capability. See [9] for some suggested - uses of this field. - - The authorization-data field is optional and does not have - to be included in a ticket. - -5.3.2. Authenticators - - An authenticator is a record sent with a ticket to a server to - certify the client's knowledge of the encryption key in the ticket, - to help the server detect replays, and to help choose a "true session - key" to use with the particular session. The encoding is encrypted - in the ticket's session key shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - - - -Kohl & Neuman [Page 47] - -RFC 1510 Kerberos September 1993 - - - authorization-data[8] AuthorizationData OPTIONAL - } - - authenticator-vno This field specifies the version number for the - format of the authenticator. This document specifies - version 5. - - crealm and cname These fields are the same as those described for the - ticket in section 5.3.1. - - cksum This field contains a checksum of the the application data - that accompanies the KRB_AP_REQ. - - cusec This field contains the microsecond part of the client's - timestamp. Its value (before encryption) ranges from 0 to - 999999. It often appears along with ctime. The two fields - are used together to specify a reasonably accurate - timestamp. - - ctime This field contains the current time on the client's host. - - subkey This field contains the client's choice for an encryption - key which is to be used to protect this specific - application session. Unless an application specifies - otherwise, if this field is left out the session key from - the ticket will be used. - - seq-number This optional field includes the initial sequence number - to be used by the KRB_PRIV or KRB_SAFE messages when - sequence numbers are used to detect replays (It may also be - used by application specific messages). When included in - the authenticator this field specifies the initial sequence - number for messages from the client to the server. When - included in the AP-REP message, the initial sequence number - is that for messages from the server to the client. When - used in KRB_PRIV or KRB_SAFE messages, it is incremented by - one after each message is sent. - - For sequence numbers to adequately support the detection of - replays they should be non-repeating, even across - connection boundaries. The initial sequence number should - be random and uniformly distributed across the full space - of possible sequence numbers, so that it cannot be guessed - by an attacker and so that it and the successive sequence - numbers do not repeat other sequences. - - - - - - -Kohl & Neuman [Page 48] - -RFC 1510 Kerberos September 1993 - - - authorization-data This field is the same as described for the ticket - in section 5.3.1. It is optional and will only appear when - additional restrictions are to be placed on the use of a - ticket, beyond those carried in the ticket itself. - -5.4. Specifications for the AS and TGS exchanges - - This section specifies the format of the messages used in exchange - between the client and the Kerberos server. The format of possible - error messages appears in section 5.9.1. - -5.4.1. KRB_KDC_REQ definition - - The KRB_KDC_REQ message has no type of its own. Instead, its type is - one of KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is - for an initial ticket or an additional ticket. In either case, the - message is sent from the client to the Authentication Server to - request credentials for a service. - -The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - - - -Kohl & Neuman [Page 49] - -RFC 1510 Kerberos September 1993 - - - etype[8] SEQUENCE OF INTEGER, -- EncryptionType, - -- in preference order - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - - The fields in this message are: - - pvno This field is included in each message, and specifies the - protocol version number. This document specifies protocol - version 5. - - msg-type This field indicates the type of a protocol message. It - will almost always be the same as the application - identifier associated with a message. It is included to - make the identifier more readily accessible to the - application. For the KDC-REQ message, this type will be - KRB_AS_REQ or KRB_TGS_REQ. - - padata The padata (pre-authentication data) field contains a of - authentication information which may be needed before - credentials can be issued or decrypted. In the case of - requests for additional tickets (KRB_TGS_REQ), this field - will include an element with padata-type of PA-TGS-REQ and - data of an authentication header (ticket-granting ticket - and authenticator). The checksum in the authenticator - (which must be collisionproof) is to be computed over the - KDC-REQ-BODY encoding. In most requests for initial - authentication (KRB_AS_REQ) and most replies (KDC-REP), the - padata field will be left out. - - This field may also contain information needed by certain - extensions to the Kerberos protocol. For example, it might - be used to initially verify the identity of a client before - any response is returned. This is accomplished with a - padata field with padata-type equal to PA-ENC-TIMESTAMP and - padata-value defined as follows: - - padata-type ::= PA-ENC-TIMESTAMP - padata-value ::= EncryptedData -- PA-ENC-TS-ENC - - PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL - } - - - - -Kohl & Neuman [Page 50] - -RFC 1510 Kerberos September 1993 - - - with patimestamp containing the client's time and pausec - containing the microseconds which may be omitted if a - client will not generate more than one request per second. - The ciphertext (padata-value) consists of the PA-ENC-TS-ENC - sequence, encrypted using the client's secret key. - - The padata field can also contain information needed to - help the KDC or the client select the key needed for - generating or decrypting the response. This form of the - padata is useful for supporting the use of certain - "smartcards" with Kerberos. The details of such extensions - are beyond the scope of this specification. See [10] for - additional uses of this field. - - padata-type The padata-type element of the padata field indicates the - way that the padata-value element is to be interpreted. - Negative values of padata-type are reserved for - unregistered use; non-negative values are used for a - registered interpretation of the element type. - - req-body This field is a placeholder delimiting the extent of the - remaining fields. If a checksum is to be calculated over - the request, it is calculated over an encoding of the KDC- - REQ-BODY sequence which is enclosed within the req-body - field. - - kdc-options This field appears in the KRB_AS_REQ and KRB_TGS_REQ - requests to the KDC and indicates the flags that the client - wants set on the tickets as well as other information that - is to modify the behavior of the KDC. Where appropriate, - the name of an option may be the same as the flag that is - set by that option. Although in most case, the bit in the - options field will be the same as that in the flags field, - this is not guaranteed, so it is not acceptable to simply - copy the options field to the flags field. There are - various checks that must be made before honoring an option - anyway. - - The kdc_options field is a bit-field, where the selected - options are indicated by the bit being set (1), and the - unselected options and reserved fields being reset (0). - The encoding of the bits is specified in section 5.2. The - options are described in more detail above in section 2. - The meanings of the options are: - - - - - - - -Kohl & Neuman [Page 51] - -RFC 1510 Kerberos September 1993 - - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of this - field. - - 1 FORWARDABLE The FORWARDABLE option indicates that - the ticket to be issued is to have its - forwardable flag set. It may only be - set on the initial request, or in a - subsequent request if the ticket- - granting ticket on which it is based - is also forwardable. - - 2 FORWARDED The FORWARDED option is only specified - in a request to the ticket-granting - server and will only be honored if the - ticket-granting ticket in the request - has its FORWARDABLE bit set. This - option indicates that this is a - request for forwarding. The - address(es) of the host from which the - resulting ticket is to be valid are - included in the addresses field of the - request. - - - 3 PROXIABLE The PROXIABLE option indicates that - the ticket to be issued is to have its - proxiable flag set. It may only be set - on the initial request, or in a - subsequent request if the ticket- - granting ticket on which it is based - is also proxiable. - - 4 PROXY The PROXY option indicates that this - is a request for a proxy. This option - will only be honored if the ticket- - granting ticket in the request has its - PROXIABLE bit set. The address(es) of - the host from which the resulting - ticket is to be valid are included in - the addresses field of the request. - - 5 ALLOW-POSTDATE The ALLOW-POSTDATE option indicates - that the ticket to be issued is to - have its MAY-POSTDATE flag set. It - may only be set on the initial - request, or in a subsequent request if - - - -Kohl & Neuman [Page 52] - -RFC 1510 Kerberos September 1993 - - - the ticket-granting ticket on which it - is based also has its MAY-POSTDATE - flag set. - - 6 POSTDATED The POSTDATED option indicates that - this is a request for a postdated - ticket. This option will only be - honored if the ticket-granting ticket - on which it is based has its MAY- - POSTDATE flag set. The resulting - ticket will also have its INVALID flag - set, and that flag may be reset by a - subsequent request to the KDC after - the starttime in the ticket has been - reached. - - 7 UNUSED This option is presently unused. - - 8 RENEWABLE The RENEWABLE option indicates that - the ticket to be issued is to have its - RENEWABLE flag set. It may only be - set on the initial request, or when - the ticket-granting ticket on which - the request is based is also - renewable. If this option is - requested, then the rtime field in the - request contains the desired absolute - expiration time for the ticket. - - 9-26 RESERVED Reserved for future use. - - 27 RENEWABLE-OK The RENEWABLE-OK option indicates that - a renewable ticket will be acceptable - if a ticket with the requested life - cannot otherwise be provided. If a - ticket with the requested life cannot - be provided, then a renewable ticket - may be issued with a renew-till equal - to the the requested endtime. The - value of the renew-till field may - still be limited by local limits, or - limits selected by the individual - principal or server. - - 28 ENC-TKT-IN-SKEY This option is used only by the - ticket-granting service. The ENC- - TKT-IN-SKEY option indicates that the - ticket for the end server is to be - - - -Kohl & Neuman [Page 53] - -RFC 1510 Kerberos September 1993 - - - encrypted in the session key from the - additional ticket-granting ticket - provided. - - 29 RESERVED Reserved for future use. - - 30 RENEW This option is used only by the - ticket-granting service. The RENEW - option indicates that the present - request is for a renewal. The ticket - provided is encrypted in the secret - key for the server on which it is - valid. This option will only be - honored if the ticket to be renewed - has its RENEWABLE flag set and if the - time in its renew till field has not - passed. The ticket to be renewed is - passed in the padata field as part of - the authentication header. - - 31 VALIDATE This option is used only by the - ticket-granting service. The VALIDATE - option indicates that the request is - to validate a postdated ticket. It - will only be honored if the ticket - presented is postdated, presently has - its INVALID flag set, and would be - otherwise usable at this time. A - ticket cannot be validated before its - starttime. The ticket presented for - validation is encrypted in the key of - the server for which it is valid and - is passed in the padata field as part - of the authentication header. - - cname and sname These fields are the same as those described for the - ticket in section 5.3.1. sname may only be absent when the - ENC-TKT-IN-SKEY option is specified. If absent, the name - of the server is taken from the name of the client in the - ticket passed as additional-tickets. - - enc-authorization-data The enc-authorization-data, if present (and it - can only be present in the TGS_REQ form), is an encoding of - the desired authorization-data encrypted under the sub- - session key if present in the Authenticator, or - alternatively from the session key in the ticket-granting - ticket, both from the padata field in the KRB_AP_REQ. - - - - -Kohl & Neuman [Page 54] - -RFC 1510 Kerberos September 1993 - - - realm This field specifies the realm part of the server's - principal identifier. In the AS exchange, this is also the - realm part of the client's principal identifier. - - from This field is included in the KRB_AS_REQ and KRB_TGS_REQ - ticket requests when the requested ticket is to be - postdated. It specifies the desired start time for the - requested ticket. - - till This field contains the expiration date requested by the - client in a ticket request. - - rtime This field is the requested renew-till time sent from a - client to the KDC in a ticket request. It is optional. - - nonce This field is part of the KDC request and response. It it - intended to hold a random number generated by the client. - If the same number is included in the encrypted response - from the KDC, it provides evidence that the response is - fresh and has not been replayed by an attacker. Nonces - must never be re-used. Ideally, it should be gen erated - randomly, but if the correct time is known, it may suffice - (Note, however, that if the time is used as the nonce, one - must make sure that the workstation time is monotonically - increasing. If the time is ever reset backwards, there is - a small, but finite, probability that a nonce will be - reused.). - - etype This field specifies the desired encryption algorithm to be - used in the response. - - addresses This field is included in the initial request for tickets, - and optionally included in requests for additional tickets - from the ticket-granting server. It specifies the - addresses from which the requested ticket is to be valid. - Normally it includes the addresses for the client's host. - If a proxy is requested, this field will contain other - addresses. The contents of this field are usually copied - by the KDC into the caddr field of the resulting ticket. - - additional-tickets Additional tickets may be optionally included in a - request to the ticket-granting server. If the ENC-TKT-IN- - SKEY option has been specified, then the session key from - the additional ticket will be used in place of the server's - key to encrypt the new ticket. If more than one option - which requires additional tickets has been specified, then - the additional tickets are used in the order specified by - the ordering of the options bits (see kdc-options, above). - - - -Kohl & Neuman [Page 55] - -RFC 1510 Kerberos September 1993 - - - The application code will be either ten (10) or twelve (12) depending - on whether the request is for an initial ticket (AS-REQ) or for an - additional ticket (TGS-REQ). - - The optional fields (addresses, authorization-data and additional- - tickets) are only included if necessary to perform the operation - specified in the kdc-options field. - - It should be noted that in KRB_TGS_REQ, the protocol version number - appears twice and two different message types appear: the KRB_TGS_REQ - message contains these fields as does the authentication header - (KRB_AP_REQ) that is passed in the padata field. - -5.4.2. KRB_KDC_REP definition - - The KRB_KDC_REP message format is used for the reply from the KDC for - either an initial (AS) request or a subsequent (TGS) request. There - is no message type for KRB_KDC_REP. Instead, the type will be either - KRB_AS_REP or KRB_TGS_REP. The key used to encrypt the ciphertext - part of the reply depends on the message type. For KRB_AS_REP, the - ciphertext is encrypted in the client's secret key, and the client's - key version number is included in the key version number for the - encrypted data. For KRB_TGS_REP, the ciphertext is encrypted in the - sub-session key from the Authenticator, or if absent, the session key - from the ticket-granting ticket used in the request. In that case, - no version number will be present in the EncryptedData sequence. - - The KRB_KDC_REP message contains the following fields: - - AS-REP ::= [APPLICATION 11] KDC-REP - TGS-REP ::= [APPLICATION 13] KDC-REP - - KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData - } - - EncASRepPart ::= [APPLICATION 25[25]] EncKDCRepPart - EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - - EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - - - -Kohl & Neuman [Page 56] - -RFC 1510 Kerberos September 1993 - - - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL - } - - NOTE: In EncASRepPart, the application code in the encrypted - part of a message provides an additional check that - the message was decrypted properly. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is either KRB_AS_REP or KRB_TGS_REP. - - padata This field is described in detail in section 5.4.1. One - possible use for this field is to encode an alternate - "mix-in" string to be used with a string-to-key algorithm - (such as is described in section 6.3.2). This ability is - useful to ease transitions if a realm name needs to change - (e.g., when a company is acquired); in such a case all - existing password-derived entries in the KDC database would - be flagged as needing a special mix-in string until the - next password change. - - crealm, cname, srealm and sname These fields are the same as those - described for the ticket in section 5.3.1. - - ticket The newly-issued ticket, from section 5.3.1. - - enc-part This field is a place holder for the ciphertext and related - information that forms the encrypted part of a message. - The description of the encrypted part of the message - follows each appearance of this field. The encrypted part - is encoded as described in section 6.1. - - key This field is the same as described for the ticket in - section 5.3.1. - - last-req This field is returned by the KDC and specifies the time(s) - of the last request by a principal. Depending on what - information is available, this might be the last time that - a request for a ticket-granting ticket was made, or the - last time that a request based on a ticket-granting ticket - - - -Kohl & Neuman [Page 57] - -RFC 1510 Kerberos September 1993 - - - was successful. It also might cover all servers for a - realm, or just the particular server. Some implementations - may display this information to the user to aid in - discovering unauthorized use of one's identity. It is - similar in spirit to the last login time displayed when - logging into timesharing systems. - - nonce This field is described above in section 5.4.1. - - key-expiration The key-expiration field is part of the response from - the KDC and specifies the time that the client's secret key - is due to expire. The expiration might be the result of - password aging or an account expiration. This field will - usually be left out of the TGS reply since the response to - the TGS request is encrypted in a session key and no client - information need be retrieved from the KDC database. It is - up to the application client (usually the login program) to - take appropriate action (such as notifying the user) if the - expira tion time is imminent. - - flags, authtime, starttime, endtime, renew-till and caddr These - fields are duplicates of those found in the encrypted - portion of the attached ticket (see section 5.3.1), - provided so the client may verify they match the intended - request and to assist in proper ticket caching. If the - message is of type KRB_TGS_REP, the caddr field will only - be filled in if the request was for a proxy or forwarded - ticket, or if the user is substituting a subset of the - addresses from the ticket granting ticket. If the client- - requested addresses are not present or not used, then the - addresses contained in the ticket will be the same as those - included in the ticket-granting ticket. - -5.5. Client/Server (CS) message specifications - - This section specifies the format of the messages used for the - authentication of the client to the application server. - -5.5.1. KRB_AP_REQ definition - - The KRB_AP_REQ message contains the Kerberos protocol version number, - the message type KRB_AP_REQ, an options field to indicate any options - in use, and the ticket and authenticator themselves. The KRB_AP_REQ - message is often referred to as the "authentication header". - - AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - - - -Kohl & Neuman [Page 58] - -RFC 1510 Kerberos September 1993 - - - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData - } - - APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_AP_REQ. - - ap-options This field appears in the application request (KRB_AP_REQ) - and affects the way the request is processed. It is a - bit-field, where the selected options are indicated by the - bit being set (1), and the unselected options and reserved - fields being reset (0). The encoding of the bits is - specified in section 5.2. The meanings of the options are: - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of - this field. - - 1 USE-SESSION-KEYThe USE-SESSION-KEY option indicates - that the ticket the client is - presenting to a server is encrypted in - the session key from the server's - ticket-granting ticket. When this - option is not specified, the ticket is - encrypted in the server's secret key. - - 2 MUTUAL-REQUIREDThe MUTUAL-REQUIRED option tells the - server that the client requires mutual - authentication, and that it must - respond with a KRB_AP_REP message. - - 3-31 RESERVED Reserved for future use. - - ticket This field is a ticket authenticating the client to the - server. - - authenticator This contains the authenticator, which includes the - client's choice of a subkey. Its encoding is described in - section 5.3.2. - - - - -Kohl & Neuman [Page 59] - -RFC 1510 Kerberos September 1993 - - -5.5.2. KRB_AP_REP definition - - The KRB_AP_REP message contains the Kerberos protocol version number, - the message type, and an encrypted timestamp. The message is sent in - in response to an application request (KRB_AP_REQ) where the mutual - authentication option has been selected in the ap-options field. - - AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData - } - - EncAPRepPart ::= [APPLICATION 27] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL - } - - NOTE: in EncAPRepPart, the application code in the encrypted part of - a message provides an additional check that the message was decrypted - properly. - - The encoded EncAPRepPart is encrypted in the shared session key of - the ticket. The optional subkey field can be used in an - application-arranged negotiation to choose a per association session - key. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_AP_REP. - - enc-part This field is described above in section 5.4.2. - - ctime This field contains the current time on the client's host. - - cusec This field contains the microsecond part of the client's - timestamp. - - subkey This field contains an encryption key which is to be used - to protect this specific application session. See section - 3.2.6 for specifics on how this field is used to negotiate - a key. Unless an application specifies otherwise, if this - field is left out, the sub-session key from the - authenticator, or if also left out, the session key from - the ticket will be used. - - - - - -Kohl & Neuman [Page 60] - -RFC 1510 Kerberos September 1993 - - -5.5.3. Error message reply - - If an error occurs while processing the application request, the - KRB_ERROR message will be sent in response. See section 5.9.1 for - the format of the error message. The cname and crealm fields may be - left out if the server cannot determine their appropriate values from - the corresponding KRB_AP_REQ message. If the authenticator was - decipherable, the ctime and cusec fields will contain the values from - it. - -5.6. KRB_SAFE message specification - - This section specifies the format of a message that can be used by - either side (client or server) of an application to send a tamper- - proof message to its peer. It presumes that a session key has - previously been exchanged (for example, by using the - KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - - The KRB_SAFE message contains user data along with a collision-proof - checksum keyed with the session key. The message fields are: - - KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum - } - - KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress, - r-address[5] HostAddress OPTIONAL - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_SAFE. - - safe-body This field is a placeholder for the body of the KRB-SAFE - message. It is to be encoded separately and then have the - checksum computed over it, for use in the cksum field. - - cksum This field contains the checksum of the application data. - Checksum details are described in section 6.4. The - - - -Kohl & Neuman [Page 61] - -RFC 1510 Kerberos September 1993 - - - checksum is computed over the encoding of the KRB-SAFE-BODY - sequence. - - user-data This field is part of the KRB_SAFE and KRB_PRIV messages - and contain the application specific data that is being - passed from the sender to the recipient. - - timestamp This field is part of the KRB_SAFE and KRB_PRIV messages. - Its contents are the current time as known by the sender of - the message. By checking the timestamp, the recipient of - the message is able to make sure that it was recently - generated, and is not a replay. - - usec This field is part of the KRB_SAFE and KRB_PRIV headers. - It contains the microsecond part of the timestamp. - - seq-number This field is described above in section 5.3.2. - - s-address This field specifies the address in use by the sender of - the message. - - r-address This field specifies the address in use by the recipient of - the message. It may be omitted for some uses (such as - broadcast protocols), but the recipient may arbitrarily - reject such messages. This field along with s-address can - be used to help detect messages which have been incorrectly - or maliciously delivered to the wrong recipient. - -5.7. KRB_PRIV message specification - - This section specifies the format of a message that can be used by - either side (client or server) of an application to securely and - privately send a message to its peer. It presumes that a session key - has previously been exchanged (for example, by using the - KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - - The KRB_PRIV message contains user data encrypted in the Session Key. - The message fields are: - - KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData - } - - - - - -Kohl & Neuman [Page 62] - -RFC 1510 Kerberos September 1993 - - - EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress, -- sender's addr - r-address[5] HostAddress OPTIONAL - -- recip's addr - } - - NOTE: In EncKrbPrivPart, the application code in the encrypted part - of a message provides an additional check that the message was - decrypted properly. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_PRIV. - - enc-part This field holds an encoding of the EncKrbPrivPart sequence - encrypted under the session key (If supported by the - encryption method in use, an initialization vector may be - passed to the encryption procedure, in order to achieve - proper cipher chaining. The initialization vector might - come from the last block of the ciphertext from the - previous KRB_PRIV message, but it is the application's - choice whether or not to use such an initialization vector. - If left out, the default initialization vector for the - encryption algorithm will be used.). This encrypted - encoding is used for the enc-part field of the KRB-PRIV - message. See section 6 for the format of the ciphertext. - - user-data, timestamp, usec, s-address and r-address These fields are - described above in section 5.6.1. - - seq-number This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - - This section specifies the format of a message that can be used to - send Kerberos credentials from one principal to another. It is - presented here to encourage a common mechanism to be used by - applications when forwarding tickets or providing proxies to - subordinate servers. It presumes that a session key has already been - exchanged perhaps by using the KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - - The KRB_CRED message contains a sequence of tickets to be sent and - information needed to use the tickets, including the session key from - - - -Kohl & Neuman [Page 63] - -RFC 1510 Kerberos September 1993 - - - each. The information needed to use the tickets is encryped under an - encryption key previously exchanged. The message fields are: - - KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData - } - - EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL - } - - KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL - } - - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_CRED. - - tickets - These are the tickets obtained from the KDC specifically - for use by the intended recipient. Successive tickets are - paired with the corresponding KrbCredInfo sequence from the - enc-part of the KRB-CRED message. - - enc-part This field holds an encoding of the EncKrbCredPart sequence - encrypted under the session key shared between the sender - and the intended recipient. This encrypted encoding is - used for the enc-part field of the KRB-CRED message. See - section 6 for the format of the ciphertext. - - - -Kohl & Neuman [Page 64] - -RFC 1510 Kerberos September 1993 - - - nonce If practical, an application may require the inclusion of a - nonce generated by the recipient of the message. If the - same value is included as the nonce in the message, it - provides evidence that the message is fresh and has not - been replayed by an attacker. A nonce must never be re- - used; it should be generated randomly by the recipient of - the message and provided to the sender of the mes sage in - an application specific manner. - - timestamp and usec These fields specify the time that the KRB-CRED - message was generated. The time is used to provide - assurance that the message is fresh. - - s-address and r-address These fields are described above in section - 5.6.1. They are used optionally to provide additional - assurance of the integrity of the KRB-CRED message. - - key This field exists in the corresponding ticket passed by the - KRB-CRED message and is used to pass the session key from - the sender to the intended recipient. The field's encoding - is described in section 6.2. - - The following fields are optional. If present, they can be - associated with the credentials in the remote ticket file. If left - out, then it is assumed that the recipient of the credentials already - knows their value. - - prealm and pname The name and realm of the delegated principal - identity. - - flags, authtime, starttime, endtime, renew-till, srealm, sname, - and caddr These fields contain the values of the - corresponding fields from the ticket found in the ticket - field. Descriptions of the fields are identical to the - descriptions in the KDC-REP message. - -5.9. Error message specification - - This section specifies the format for the KRB_ERROR message. The - fields included in the message are intended to return as much - information as possible about an error. It is not expected that all - the information required by the fields will be available for all - types of errors. If the appropriate information is not available - when the message is composed, the corresponding field will be left - out of the message. - - Note that since the KRB_ERROR message is not protected by any - encryption, it is quite possible for an intruder to synthesize or - - - -Kohl & Neuman [Page 65] - -RFC 1510 Kerberos September 1993 - - - modify such a message. In particular, this means that the client - should not use any fields in this message for security-critical - purposes, such as setting a system clock or generating a fresh - authenticator. The message can be useful, however, for advising a - user on the reason for some failure. - -5.9.1. KRB_ERROR definition - - The KRB_ERROR message consists of the following fields: - - KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_ERROR. - - ctime This field is described above in section 5.4.1. - - cusec This field is described above in section 5.5.2. - - stime This field contains the current time on the server. It is - of type KerberosTime. - - susec This field contains the microsecond part of the server's - timestamp. Its value ranges from 0 to 999. It appears - along with stime. The two fields are used in conjunction to - specify a reasonably accurate timestamp. - - error-code This field contains the error code returned by Kerberos or - the server when a request fails. To interpret the value of - this field see the list of error codes in section 8. - Implementations are encouraged to provide for national - language support in the display of error messages. - - crealm, cname, srealm and sname These fields are described above in - - - -Kohl & Neuman [Page 66] - -RFC 1510 Kerberos September 1993 - - - section 5.3.1. - - e-text This field contains additional text to help explain the - error code associated with the failed request (for example, - it might include a principal name which was unknown). - - e-data This field contains additional data about the error for use - by the application to help it recover from or handle the - error. If the errorcode is KDC_ERR_PREAUTH_REQUIRED, then - the e-data field will contain an encoding of a sequence of - padata fields, each corresponding to an acceptable pre- - authentication method and optionally containing data for - the method: - - METHOD-DATA ::= SEQUENCE of PA-DATA - - If the error-code is KRB_AP_ERR_METHOD, then the e-data field will - contain an encoding of the following sequence: - - METHOD-DATA ::= SEQUENCE { - method-type[0] INTEGER, - method-data[1] OCTET STRING OPTIONAL - } - - method-type will indicate the required alternate method; method-data - will contain any required additional information. - -6. Encryption and Checksum Specifications - - The Kerberos protocols described in this document are designed to use - stream encryption ciphers, which can be simulated using commonly - available block encryption ciphers, such as the Data Encryption - Standard [11], in conjunction with block chaining and checksum - methods [12]. Encryption is used to prove the identities of the - network entities participating in message exchanges. The Key - Distribution Center for each realm is trusted by all principals - registered in that realm to store a secret key in confidence. Proof - of knowledge of this secret key is used to verify the authenticity of - a principal. - - The KDC uses the principal's secret key (in the AS exchange) or a - shared session key (in the TGS exchange) to encrypt responses to - ticket requests; the ability to obtain the secret key or session key - implies the knowledge of the appropriate keys and the identity of the - KDC. The ability of a principal to decrypt the KDC response and - present a Ticket and a properly formed Authenticator (generated with - the session key from the KDC response) to a service verifies the - identity of the principal; likewise the ability of the service to - - - -Kohl & Neuman [Page 67] - -RFC 1510 Kerberos September 1993 - - - extract the session key from the Ticket and prove its knowledge - thereof in a response verifies the identity of the service. - - The Kerberos protocols generally assume that the encryption used is - secure from cryptanalysis; however, in some cases, the order of - fields in the encrypted portions of messages are arranged to minimize - the effects of poorly chosen keys. It is still important to choose - good keys. If keys are derived from user-typed passwords, those - passwords need to be well chosen to make brute force attacks more - difficult. Poorly chosen keys still make easy targets for intruders. - - The following sections specify the encryption and checksum mechanisms - currently defined for Kerberos. The encodings, chaining, and padding - requirements for each are described. For encryption methods, it is - often desirable to place random information (often referred to as a - confounder) at the start of the message. The requirements for a - confounder are specified with each encryption mechanism. - - Some encryption systems use a block-chaining method to improve the - the security characteristics of the ciphertext. However, these - chaining methods often don't provide an integrity check upon - decryption. Such systems (such as DES in CBC mode) must be augmented - with a checksum of the plaintext which can be verified at decryption - and used to detect any tampering or damage. Such checksums should be - good at detecting burst errors in the input. If any damage is - detected, the decryption routine is expected to return an error - indicating the failure of an integrity check. Each encryption type is - expected to provide and verify an appropriate checksum. The - specification of each encryption method sets out its checksum - requirements. - - Finally, where a key is to be derived from a user's password, an - algorithm for converting the password to a key of the appropriate - type is included. It is desirable for the string to key function to - be one-way, and for the mapping to be different in different realms. - This is important because users who are registered in more than one - realm will often use the same password in each, and it is desirable - that an attacker compromising the Kerberos server in one realm not - obtain or derive the user's key in another. - - For a discussion of the integrity characteristics of the candidate - encryption and checksum methods considered for Kerberos, the the - reader is referred to [13]. - -6.1. Encryption Specifications - - The following ASN.1 definition describes all encrypted messages. The - enc-part field which appears in the unencrypted part of messages in - - - -Kohl & Neuman [Page 68] - -RFC 1510 Kerberos September 1993 - - - section 5 is a sequence consisting of an encryption type, an optional - key version number, and the ciphertext. - - EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext - } - - etype This field identifies which encryption algorithm was used - to encipher the cipher. Detailed specifications for - selected encryption types appear later in this section. - - kvno This field contains the version number of the key under - which data is encrypted. It is only present in messages - encrypted under long lasting keys, such as principals' - secret keys. - - cipher This field contains the enciphered text, encoded as an - OCTET STRING. - - The cipher field is generated by applying the specified encryption - algorithm to data composed of the message and algorithm-specific - inputs. Encryption mechanisms defined for use with Kerberos must - take sufficient measures to guarantee the integrity of the plaintext, - and we recommend they also take measures to protect against - precomputed dictionary attacks. If the encryption algorithm is not - itself capable of doing so, the protections can often be enhanced by - adding a checksum and a confounder. - - The suggested format for the data to be encrypted includes a - confounder, a checksum, the encoded plaintext, and any necessary - padding. The msg-seq field contains the part of the protocol message - described in section 5 which is to be encrypted. The confounder, - checksum, and padding are all untagged and untyped, and their length - is exactly sufficient to hold the appropriate item. The type and - length is implicit and specified by the particular encryption type - being used (etype). The format for the data to be encrypted is - described in the following diagram: - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - - - - -Kohl & Neuman [Page 69] - -RFC 1510 Kerberos September 1993 - - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - - In the above specification, UNTAGGED OCTET STRING(length) is the - notation for an octet string with its tag and length removed. It is - not a valid ASN.1 type. The tag bits and length must be removed from - the confounder since the purpose of the confounder is so that the - message starts with random data, but the tag and its length are - fixed. For other fields, the length and tag would be redundant if - they were included because they are specified by the encryption type. - - One generates a random confounder of the appropriate length, placing - it in confounder; zeroes out check; calculates the appropriate - checksum over confounder, check, and msg-seq, placing the result in - check; adds the necessary padding; then encrypts using the specified - encryption type and the appropriate key. - - Unless otherwise specified, a definition of an encryption algorithm - that specifies a checksum, a length for the confounder field, or an - octet boundary for padding uses this ciphertext format (The ordering - of the fields in the CipherText is important. Additionally, messages - encoded in this format must include a length as part of the msg-seq - field. This allows the recipient to verify that the message has not - been truncated. Without a length, an attacker could use a chosen - plaintext attack to generate a message which could be truncated, - while leaving the checksum intact. Note that if the msg-seq is an - encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length is - part of that encoding.). Those fields which are not specified will be - omitted. - - In the interest of allowing all implementations using a particular - encryption type to communicate with all others using that type, the - specification of an encryption type defines any checksum that is - needed as part of the encryption process. If an alternative checksum - is to be used, a new encryption type must be defined. - - Some cryptosystems require additional information beyond the key and - the data to be encrypted. For example, DES, when used in cipher- - block-chaining mode, requires an initialization vector. If required, - the description for each encryption type must specify the source of - such additional information. - - - - - - -Kohl & Neuman [Page 70] - -RFC 1510 Kerberos September 1993 - - -6.2. Encryption Keys - - The sequence below shows the encoding of an encryption key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - - keytype This field specifies the type of encryption key that - follows in the keyvalue field. It will almost always - correspond to the encryption algorithm used to generate the - EncryptedData, though more than one algorithm may use the - same type of key (the mapping is many to one). This might - happen, for example, if the encryption algorithm uses an - alternate checksum algorithm for an integrity check, or a - different chaining mechanism. - - keyvalue This field contains the key itself, encoded as an octet - string. - - All negative values for the encryption key type are reserved for - local use. All non-negative values are reserved for officially - assigned type fields and interpretations. - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - - If no encryption is in use, the encryption system is said to be the - NULL encryption system. In the NULL encryption system there is no - checksum, confounder or padding. The ciphertext is simply the - plaintext. The NULL Key is used by the null encryption system and is - zero octets in length, with keytype zero (0). - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - - The des-cbc-crc encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - A CRC-32 checksum (described in ISO 3309 [14]) is applied to the - confounder and message sequence (msg-seq) and placed in the cksum - field. DES blocks are 8 bytes. As a result, the data to be - encrypted (the concatenation of confounder, checksum, and message) - must be padded to an 8 byte boundary before encryption. The details - of the encryption of this data are identical to those for the des- - cbc-md5 encryption mode. - - Note that, since the CRC-32 checksum is not collisionproof, an - - - -Kohl & Neuman [Page 71] - -RFC 1510 Kerberos September 1993 - - - attacker could use a probabilistic chosenplaintext attack to generate - a valid message even if a confounder is used [13]. The use of - collision-proof checksums is recommended for environments where such - attacks represent a significant threat. The use of the CRC-32 as the - checksum for ticket or authenticator is no longer mandated as an - interoperability requirement for Kerberos Version 5 Specification 1 - (See section 9.1 for specific details). - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - - The des-cbc-md4 encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - An MD4 checksum (described in [15]) is applied to the confounder and - message sequence (msg-seq) and placed in the cksum field. DES blocks - are 8 bytes. As a result, the data to be encrypted (the - concatenation of confounder, checksum, and message) must be padded to - an 8 byte boundary before encryption. The details of the encryption - of this data are identical to those for the descbc-md5 encryption - mode. - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - - The des-cbc-md5 encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - An MD5 checksum (described in [16]) is applied to the confounder and - message sequence (msg-seq) and placed in the cksum field. DES blocks - are 8 bytes. As a result, the data to be encrypted (the - concatenation of confounder, checksum, and message) must be padded to - an 8 byte boundary before encryption. - - Plaintext and DES ciphtertext are encoded as 8-octet blocks which are - concatenated to make the 64-bit inputs for the DES algorithms. The - first octet supplies the 8 most significant bits (with the octet's - MSbit used as the DES input block's MSbit, etc.), the second octet - the next 8 bits, ..., and the eighth octet supplies the 8 least - significant bits. - - Encryption under DES using cipher block chaining requires an - additional input in the form of an initialization vector. Unless - otherwise specified, zero should be used as the initialization - vector. Kerberos' use of DES requires an 8-octet confounder. - - The DES specifications identify some "weak" and "semiweak" keys; - those keys shall not be used for encrypting messages for use in - Kerberos. Additionally, because of the way that keys are derived for - the encryption of checksums, keys shall not be used that yield "weak" - or "semi-weak" keys when eXclusive-ORed with the constant - F0F0F0F0F0F0F0F0. - - - -Kohl & Neuman [Page 72] - -RFC 1510 Kerberos September 1993 - - - A DES key is 8 octets of data, with keytype one (1). This consists - of 56 bits of key, and 8 parity bits (one per octet). The key is - encoded as a series of 8 octets written in MSB-first order. The bits - within the key are also encoded in MSB order. For example, if the - encryption key is: - (B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where - B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the - parity bits, the first octet of the key would be B1,B2,...,B7,P1 - (with B1 as the MSbit). [See the FIPS 81 introduction for - reference.] - - To generate a DES key from a text string (password), the text string - normally must have the realm and each component of the principal's - name appended(In some cases, it may be necessary to use a different - "mix-in" string for compatibility reasons; see the discussion of - padata in section 5.4.2.), then padded with ASCII nulls to an 8 byte - boundary. This string is then fan-folded and eXclusive-ORed with - itself to form an 8 byte DES key. The parity is corrected on the - key, and it is used to generate a DES CBC checksum on the initial - string (with the realm and name appended). Next, parity is corrected - on the CBC checksum. If the result matches a "weak" or "semiweak" - key as described in the DES specification, it is eXclusive-ORed with - the constant 00000000000000F0. Finally, the result is returned as - the key. Pseudocode follows: - - string_to_key(string,realm,name) { - odd = 1; - s = string + realm; - for(each component in name) { - s = s + component; - } - tempkey = NULL; - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - tempkey = tempkey XOR 8byteblock; - } - fixparity(tempkey); - key = DES-CBC-check(s,tempkey); - fixparity(key); - if(is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - - - -Kohl & Neuman [Page 73] - -RFC 1510 Kerberos September 1993 - - -6.4. Checksums - - The following is the ASN.1 definition used for a checksum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - - cksumtype This field indicates the algorithm used to generate the - accompanying checksum. - - checksum This field contains the checksum itself, encoded - as an octet string. - - Detailed specification of selected checksum types appear later in - this section. Negative values for the checksum type are reserved for - local use. All non-negative values are reserved for officially - assigned type fields and interpretations. - - Checksums used by Kerberos can be classified by two properties: - whether they are collision-proof, and whether they are keyed. It is - infeasible to find two plaintexts which generate the same checksum - value for a collision-proof checksum. A key is required to perturb - or initialize the algorithm in a keyed checksum. To prevent - message-stream modification by an active attacker, unkeyed checksums - should only be used when the checksum and message will be - subsequently encrypted (e.g., the checksums defined as part of the - encryption algorithms covered earlier in this section). Collision- - proof checksums can be made tamper-proof as well if the checksum - value is encrypted before inclusion in a message. In such cases, the - composition of the checksum and the encryption algorithm must be - considered a separate checksum algorithm (e.g., RSA-MD5 encrypted - using DES is a new checksum algorithm of type RSA-MD5-DES). For most - keyed checksums, as well as for the encrypted forms of collisionproof - checksums, Kerberos prepends a confounder before the checksum is - calculated. - -6.4.1. The CRC-32 Checksum (crc32) - - The CRC-32 checksum calculates a checksum based on a cyclic - redundancy check as described in ISO 3309 [14]. The resulting - checksum is four (4) octets in length. The CRC-32 is neither keyed - nor collision-proof. The use of this checksum is not recommended. - An attacker using a probabilistic chosen-plaintext attack as - described in [13] might be able to generate an alternative message - that satisfies the checksum. The use of collision-proof checksums is - recommended for environments where such attacks represent a - - - -Kohl & Neuman [Page 74] - -RFC 1510 Kerberos September 1993 - - - significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - - The RSA-MD4 checksum calculates a checksum using the RSA MD4 - algorithm [15]. The algorithm takes as input an input message of - arbitrary length and produces as output a 128-bit (16 octet) - checksum. RSA-MD4 is believed to be collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4des) - - The RSA-MD4-DES checksum calculates a keyed collisionproof checksum - by prepending an 8 octet confounder before the text, applying the RSA - MD4 checksum algorithm, and encrypting the confounder and the - checksum using DES in cipher-block-chaining (CBC) mode using a - variant of the key, where the variant is computed by eXclusive-ORing - the key with the constant F0F0F0F0F0F0F0F0 (A variant of the key is - used to limit the use of a key to a particular function, separating - the functions of generating a checksum from other encryption - performed using the session key. The constant F0F0F0F0F0F0F0F0 was - chosen because it maintains key parity. The properties of DES - precluded the use of the complement. The same constant is used for - similar purpose in the Message Integrity Check in the Privacy - Enhanced Mail standard.). The initialization vector should be zero. - The resulting checksum is 24 octets long (8 octets of which are - redundant). This checksum is tamper-proof and believed to be - collision-proof. - - The DES specifications identify some "weak keys"; those keys shall - not be used for generating RSA-MD4 checksums for use in Kerberos. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - rsa-md4(confounder+msg),key=var(key),iv=0) | - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) - } - - - -Kohl & Neuman [Page 75] - -RFC 1510 Kerberos September 1993 - - -6.4.4. The RSA MD5 Checksum (rsa-md5) - - The RSA-MD5 checksum calculates a checksum using the RSA MD5 - algorithm [16]. The algorithm takes as input an input message of - arbitrary length and produces as output a 128-bit (16 octet) - checksum. RSA-MD5 is believed to be collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5des) - - The RSA-MD5-DES checksum calculates a keyed collisionproof checksum - by prepending an 8 octet confounder before the text, applying the RSA - MD5 checksum algorithm, and encrypting the confounder and the - checksum using DES in cipher-block-chaining (CBC) mode using a - variant of the key, where the variant is computed by eXclusive-ORing - the key with the constant F0F0F0F0F0F0F0F0. The initialization - vector should be zero. The resulting checksum is 24 octets long (8 - octets of which are redundant). This checksum is tamper-proof and - believed to be collision-proof. - - The DES specifications identify some "weak keys"; those keys shall - not be used for encrypting RSA-MD5 checksums for use in Kerberos. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - rsa-md5(confounder+msg),key=var(key),iv=0) | - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) - } - -6.4.6. DES cipher-block chained checksum (des-mac) - - The DES-MAC checksum is computed by prepending an 8 octet confounder - to the plaintext, performing a DES CBC-mode encryption on the result - using the key and an initialization vector of zero, taking the last - block of the ciphertext, prepending the same confounder and - encrypting the pair using DES in cipher-block-chaining (CBC) mode - using a a variant of the key, where the variant is computed by - - - -Kohl & Neuman [Page 76] - -RFC 1510 Kerberos September 1993 - - - eXclusive-ORing the key with the constant F0F0F0F0F0F0F0F0. The - initialization vector should be zero. The resulting checksum is 128 - bits (16 octets) long, 64 bits of which are redundant. This checksum - is tamper-proof and collision-proof. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +-----+-----+-----+-----+-----+-----+-----+-----+ - des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | - +-----+-----+-----+-----+-----+-----+-----+-----+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) - } - - The DES specifications identify some "weak" and "semiweak" keys; - those keys shall not be used for generating DES-MAC checksums for use - in Kerberos, nor shall a key be used whose veriant is "weak" or - "semi-weak". - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative - (rsa-md4-des-k) - - The RSA-MD4-DES-K checksum calculates a keyed collision-proof - checksum by applying the RSA MD4 checksum algorithm and encrypting - the results using DES in cipherblock-chaining (CBC) mode using a DES - key as both key and initialization vector. The resulting checksum is - 16 octets long. This checksum is tamper-proof and believed to be - collision-proof. Note that this checksum type is the old method for - encoding the RSA-MD4-DES checksum and it is no longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (desmac-k) - - The DES-MAC-K checksum is computed by performing a DES CBC-mode - encryption of the plaintext, and using the last block of the - ciphertext as the checksum value. It is keyed with an encryption key - and an initialization vector; any uses which do not specify an - additional initialization vector will use the key as both key and - initialization vector. The resulting checksum is 64 bits (8 octets) - long. This checksum is tamper-proof and collision-proof. Note that - - - -Kohl & Neuman [Page 77] - -RFC 1510 Kerberos September 1993 - - - this checksum type is the old method for encoding the DESMAC checksum - and it is no longer recommended. - - The DES specifications identify some "weak keys"; those keys shall - not be used for generating DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - -7.1. Realm Names - - Although realm names are encoded as GeneralStrings and although a - realm can technically select any name it chooses, interoperability - across realm boundaries requires agreement on how realm names are to - be assigned, and what information they imply. - - To enforce these conventions, each realm must conform to the - conventions itself, and it must require that any realms with which - inter-realm keys are shared also conform to the conventions and - require the same from its neighbors. - - There are presently four styles of realm names: domain, X500, other, - and reserved. Examples of each style follow: - - domain: host.subdomain.domain (example) - X500: C=US/O=OSF (example) - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - - Domain names must look like domain names: they consist of components - separated by periods (.) and they contain neither colons (:) nor - slashes (/). - - X.500 names contain an equal (=) and cannot contain a colon (:) - before the equal. The realm names for X.500 names will be string - representations of the names with components separated by slashes. - Leading and trailing slashes will not be included. - - Names that fall into the other category must begin with a prefix that - contains no equal (=) or period (.) and the prefix must be followed - by a colon (:) and the rest of the name. All prefixes must be - assigned before they may be used. Presently none are assigned. - - The reserved category includes strings which do not fall into the - first three categories. All names in this category are reserved. It - is unlikely that names will be assigned to this category unless there - is a very strong argument for not using the "other" category. - - These rules guarantee that there will be no conflicts between the - - - -Kohl & Neuman [Page 78] - -RFC 1510 Kerberos September 1993 - - - various name styles. The following additional constraints apply to - the assignment of realm names in the domain and X.500 categories: the - name of a realm for the domain or X.500 formats must either be used - by the organization owning (to whom it was assigned) an Internet - domain name or X.500 name, or in the case that no such names are - registered, authority to use a realm name may be derived from the - authority of the parent realm. For example, if there is no domain - name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can - authorize the creation of a realm with that name. - - This is acceptable because the organization to which the parent is - assigned is presumably the organization authorized to assign names to - its children in the X.500 and domain name systems as well. If the - parent assigns a realm name without also registering it in the domain - name or X.500 hierarchy, it is the parent's responsibility to make - sure that there will not in the future exists a name identical to the - realm name of the child unless it is assigned to the same entity as - the realm name. - -7.2. Principal Names - - As was the case for realm names, conventions are needed to ensure - that all agree on what information is implied by a principal name. - The name-type field that is part of the principal name indicates the - kind of information implied by the name. The name-type should be - treated as a hint. Ignoring the name type, no two names can be the - same (i.e., at least one of the components, or the realm, must be - different). This constraint may be eliminated in the future. The - following name types are defined: - - name-type value meaning - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 Just the name of the principal as in - DCE, or for users - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance - (telnet, rcommands) - NT-SRV-XHST 4 Service with host as remaining components - NT-UID 5 Unique ID - - When a name implies no information other than its uniqueness at a - particular time the name type PRINCIPAL should be used. The - principal name type should be used for users, and it might also be - used for a unique server. If the name is a unique machine generated - ID that is guaranteed never to be reassigned then the name type of - UID should be used (note that it is generally a bad idea to reassign - names of any type since stale entries might remain in access control - lists). - - - -Kohl & Neuman [Page 79] - -RFC 1510 Kerberos September 1993 - - - If the first component of a name identifies a service and the - remaining components identify an instance of the service in a server - specified manner, then the name type of SRV-INST should be used. An - example of this name type is the Kerberos ticket-granting ticket - which has a first component of krbtgt and a second component - identifying the realm for which the ticket is valid. - - If instance is a single component following the service name and the - instance identifies the host on which the server is running, then the - name type SRV-HST should be used. This type is typically used for - Internet services such as telnet and the Berkeley R commands. If the - separate components of the host name appear as successive components - following the name of the service, then the name type SRVXHST should - be used. This type might be used to identify servers on hosts with - X.500 names where the slash (/) might otherwise be ambiguous. - - A name type of UNKNOWN should be used when the form of the name is - not known. When comparing names, a name of type UNKNOWN will match - principals authenticated with names of any type. A principal - authenticated with a name of type UNKNOWN, however, will only match - other names of type UNKNOWN. - - Names of any type with an initial component of "krbtgt" are reserved - for the Kerberos ticket granting service. See section 8.2.3 for the - form of such names. - -7.2.1. Name of server principals - - The principal identifier for a server on a host will generally be - composed of two parts: (1) the realm of the KDC with which the server - is registered, and (2) a two-component name of type NT-SRV-HST if the - host name is an Internet domain name or a multi-component name of - type NT-SRV-XHST if the name of the host is of a form such as X.500 - that allows slash (/) separators. The first component of the two- or - multi-component name will identify the service and the latter - components will identify the host. Where the name of the host is not - case sensitive (for example, with Internet domain names) the name of - the host must be lower case. For services such as telnet and the - Berkeley R commands which run with system privileges, the first - component will be the string "host" instead of a service specific - identifier. - -8. Constants and other defined values - -8.1. Host address types - - All negative values for the host address type are reserved for local - use. All non-negative values are reserved for officially assigned - - - -Kohl & Neuman [Page 80] - -RFC 1510 Kerberos September 1993 - - - type fields and interpretations. - - The values of the types for the following addresses are chosen to - match the defined address family constants in the Berkeley Standard - Distributions of Unix. They can be found in with - symbolic names AF_xxx (where xxx is an abbreviation of the address - family name). - - - Internet addresses - - Internet addresses are 32-bit (4-octet) quantities, encoded in MSB - order. The type of internet addresses is two (2). - - CHAOSnet addresses - - CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB - order. The type of CHAOSnet addresses is five (5). - - ISO addresses - - ISO addresses are variable-length. The type of ISO addresses is - seven (7). - - Xerox Network Services (XNS) addresses - - XNS addresses are 48-bit (6-octet) quantities, encoded in MSB - order. The type of XNS addresses is six (6). - - AppleTalk Datagram Delivery Protocol (DDP) addresses - - AppleTalk DDP addresses consist of an 8-bit node number and a 16- - bit network number. The first octet of the address is the node - number; the remaining two octets encode the network number in MSB - order. The type of AppleTalk DDP addresses is sixteen (16). - - DECnet Phase IV addresses - - DECnet Phase IV addresses are 16-bit addresses, encoded in LSB - order. The type of DECnet Phase IV addresses is twelve (12). - -8.2. KDC messages - -8.2.1. IP transport - - When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request - using IP transport, the client shall send a UDP datagram containing - only an encoding of the request to port 88 (decimal) at the KDC's IP - - - -Kohl & Neuman [Page 81] - -RFC 1510 Kerberos September 1993 - - - address; the KDC will respond with a reply datagram containing only - an encoding of the reply message (either a KRB_ERROR or a - KRB_KDC_REP) to the sending port at the sender's IP address. - -8.2.2. OSI transport - - During authentication of an OSI client to and OSI server, the mutual - authentication of an OSI server to an OSI client, the transfer of - credentials from an OSI client to an OSI server, or during exchange - of private or integrity checked messages, Kerberos protocol messages - may be treated as opaque objects and the type of the authentication - mechanism will be: - - OBJECT IDENTIFIER ::= {iso (1), org(3), dod(5),internet(1), - security(5), kerberosv5(2)} - - Depending on the situation, the opaque object will be an - authentication header (KRB_AP_REQ), an authentication reply - (KRB_AP_REP), a safe message (KRB_SAFE), a private message - (KRB_PRIV), or a credentials message (KRB_CRED). The opaque data - contains an application code as specified in the ASN.1 description - for each message. The application code may be used by Kerberos to - determine the message type. - -8.2.3. Name of the TGS - - The principal identifier of the ticket-granting service shall be - composed of three parts: (1) the realm of the KDC issuing the TGS - ticket (2) a two-part name of type NT-SRVINST, with the first part - "krbtgt" and the second part the name of the realm which will accept - the ticket-granting ticket. For example, a ticket-granting ticket - issued by the ATHENA.MIT.EDU realm to be used to get tickets from the - ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU" - (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting - ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets - from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" - (realm), ("krbtgt", "MIT.EDU") (name). - -8.3. Protocol constants and associated values - - The following tables list constants used in the protocol and defines - their meanings. - - - - - - - - - -Kohl & Neuman [Page 82] - -RFC 1510 Kerberos September 1993 - - ----------------+-----------+----------+----------------+--------------- -Encryption type|etype value|block size|minimum pad size|confounder size ----------------+-----------+----------+----------------+--------------- -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - --------------------------------+-------------------+------------- -Checksum type |sumtype value |checksum size --------------------------------+-------------------+------------- -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 - --------------------------------+----------------- -padata type |padata-type value --------------------------------+----------------- -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - --------------------------------+------------- -authorization data type |ad-type value --------------------------------+------------- -reserved values 0-63 -OSF-DCE 64 -SESAME 65 - --------------------------------+----------------- -alternate authentication type |method-type value --------------------------------+----------------- -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - --------------------------------+------------- -transited encoding type |tr-type value --------------------------------+------------- -DOMAIN-X500-COMPRESS 1 -reserved values all others - - - - - - -Kohl & Neuman [Page 83] - -RFC 1510 Kerberos September 1993 - - ---------------+-------+----------------------------------------- -Label |Value |Meaning or MIT code ---------------+-------+----------------------------------------- - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward - credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or - for users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, - rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has - expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has - expired -KDC_ERR_BAD_PVNO 3 Requested protocol version number - not supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old - master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old - master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in - database - - - -Kohl & Neuman [Page 84] - -RFC 1510 Kerberos September 1993 - - -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than - end time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested - option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption - type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been - revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again - later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again - later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change - password to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information - was invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authentication - required* -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field - failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not - available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method - required* -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in - - - -Kohl & Neuman [Page 85] - -RFC 1510 Kerberos September 1993 - - - message -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this - implementation - - *This error carries additional information in the e-data field. The - contents of the e-data field for this message is described in section - 5.9.1. - -9. Interoperability requirements - - Version 5 of the Kerberos protocol supports a myriad of options. - Among these are multiple encryption and checksum types, alternative - encoding schemes for the transited field, optional mechanisms for - pre-authentication, the handling of tickets with no addresses, - options for mutual authentication, user to user authentication, - support for proxies, forwarding, postdating, and renewing tickets, - the format of realm names, and the handling of authorization data. - - In order to ensure the interoperability of realms, it is necessary to - define a minimal configuration which must be supported by all - implementations. This minimal configuration is subject to change as - technology does. For example, if at some later date it is discovered - that one of the required encryption or checksum algorithms is not - secure, it will be replaced. - -9.1. Specification 1 - - This section defines the first specification of these options. - Implementations which are configured in this way can be said to - support Kerberos Version 5 Specification 1 (5.1). - - Encryption and checksum methods - - The following encryption and checksum mechanisms must be supported. - Implementations may support other mechanisms as well, but the - additional mechanisms may only be used when communicating with - principals known to also support them: Encryption: DES-CBC-MD5 - Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - - Realm Names - - All implementations must understand hierarchical realms in both the - Internet Domain and the X.500 style. When a ticket granting ticket - for an unknown realm is requested, the KDC must be able to determine - the names of the intermediate realms between the KDCs realm and the - requested realm. - - - - -Kohl & Neuman [Page 86] - -RFC 1510 Kerberos September 1993 - - - Transited field encoding - - DOMAIN-X500-COMPRESS (described in section 3.3.3.1) must be - supported. Alternative encodings may be supported, but they may be - used only when that encoding is supported by ALL intermediate realms. - - Pre-authentication methods - - The TGS-REQ method must be supported. The TGS-REQ method is not used - on the initial request. The PA-ENC-TIMESTAMP method must be supported - by clients but whether it is enabled by default may be determined on - a realm by realm basis. If not used in the initial request and the - error KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENCTIMESTAMP - as an acceptable method, the client should retry the initial request - using the PA-ENC-TIMESTAMP preauthentication method. Servers need not - support the PAENC-TIMESTAMP method, but if not supported the server - should ignore the presence of PA-ENC-TIMESTAMP pre-authentication in - a request. - - Mutual authentication - - Mutual authentication (via the KRB_AP_REP message) must be supported. - - Ticket addresses and flags - - All KDC's must pass on tickets that carry no addresses (i.e., if a - TGT contains no addresses, the KDC will return derivative tickets), - but each realm may set its own policy for issuing such tickets, and - each application server will set its own policy with respect to - accepting them. By default, servers should not accept them. - - Proxies and forwarded tickets must be supported. Individual realms - and application servers can set their own policy on when such tickets - will be accepted. - - All implementations must recognize renewable and postdated tickets, - but need not actually implement them. If these options are not - supported, the starttime and endtime in the ticket shall specify a - ticket's entire useful life. When a postdated ticket is decoded by a - server, all implementations shall make the presence of the postdated - flag visible to the calling server. - - User-to-user authentication - - Support for user to user authentication (via the ENC-TKTIN-SKEY KDC - option) must be provided by implementations, but individual realms - may decide as a matter of policy to reject such requests on a per- - principal or realm-wide basis. - - - -Kohl & Neuman [Page 87] - -RFC 1510 Kerberos September 1993 - - - Authorization data - - Implementations must pass all authorization data subfields from - ticket-granting tickets to any derivative tickets unless directed to - suppress a subfield as part of the definition of that registered - subfield type (it is never incorrect to pass on a subfield, and no - registered subfield types presently specify suppression at the KDC). - - Implementations must make the contents of any authorization data - subfields available to the server when a ticket is used. - Implementations are not required to allow clients to specify the - contents of the authorization data fields. - -9.2. Recommended KDC values - - Following is a list of recommended values for a KDC implementation, - based on the list of suggested configuration constants (see section - 4.4). - - minimum lifetime 5 minutes - - maximum renewable lifetime 1 week - - maximum ticket lifetime 1 day - - empty addresses only when suitable restrictions appear - in authorization data - - proxiable, etc. Allowed. - -10. Acknowledgments - - Early versions of this document, describing version 4 of the - protocol, were written by Jennifer Steiner (formerly at Project - Athena); these drafts provided an excellent starting point for this - current version 5 specification. Many people in the Internet - community have contributed ideas and suggested protocol changes for - version 5. Notable contributions came from Ted Anderson, Steve - Bellovin and Michael Merritt [17], Daniel Bernstein, Mike Burrows, - Donald Davis, Ravi Ganesan, Morrie Gasser, Virgil Gligor, Bill - Griffeth, Mark Lillibridge, Mark Lomas, Steve Lunt, Piers McMahon, - Joe Pato, William Sommerfeld, Stuart Stubblebine, Ralph Swick, Ted - T'so, and Stanley Zanarotti. Many others commented and helped shape - this specification into its current form. - - - - - - - -Kohl & Neuman [Page 88] - -RFC 1510 Kerberos September 1993 - - -11. References - - [1] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section - E.2.1: Kerberos Authentication and Authorization System", - M.I.T. Project Athena, Cambridge, Massachusetts, December 21, - 1987. - - [2] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An - Authentication Service for Open Network Systems", pp. 191-202 in - Usenix Conference Proceedings, Dallas, Texas, February, 1988. - - [3] Needham, R., and M. Schroeder, "Using Encryption for - Authentication in Large Networks of Computers", Communications - of the ACM, Vol. 21 (12), pp. 993-999, December 1978. - - [4] Denning, D., and G. Sacco, "Time stamps in Key Distribution - Protocols", Communications of the ACM, Vol. 24 (8), pp. 533-536, - August 1981. - - [5] Kohl, J., Neuman, C., and T. Ts'o, "The Evolution of the - Kerberos Authentication Service", in an IEEE Computer Society - Text soon to be published, June 1992. - - [6] Davis, D., and R. Swick, "Workstation Services and Kerberos - Authentication at Project Athena", Technical Memorandum TM-424, - MIT Laboratory for Computer Science, February 1990. - - [7] Levine, P., Gretzinger, M, Diaz, J., Sommerfeld, W., and K. - Raeburn, "Section E.1: Service Management System, M.I.T. - Project Athena, Cambridge, Mas sachusetts (1987). - - [8] CCITT, Recommendation X.509: The Directory Authentication - Framework, December 1988. - - [9] Neuman, C., "Proxy-Based Authorization and Accounting for - Distributed Systems," in Proceedings of the 13th International - Conference on Distributed Computing Systems", Pittsburgh, PA, - May 1993. - - [10] Pato, J., "Using Pre-Authentication to Avoid Password Guessing - Attacks", Open Software Foundation DCE Request for Comments 26, - December 1992. - - [11] National Bureau of Standards, U.S. Department of Commerce, "Data - Encryption Standard", Federal Information Processing Standards - Publication 46, Washington, DC (1977). - - - - - -Kohl & Neuman [Page 89] - -RFC 1510 Kerberos September 1993 - - - [12] National Bureau of Standards, U.S. Department of Commerce, "DES - Modes of Operation", Federal Information Processing Standards - Publication 81, Springfield, VA, December 1980. - - [13] Stubblebine S., and V. Gligor, "On Message Integrity in - Cryptographic Protocols", in Proceedings of the IEEE Symposium - on Research in Security and Privacy, Oakland, California, May - 1992. - - [14] International Organization for Standardization, "ISO Information - Processing Systems - Data Communication High-Level Data Link - Control Procedure - Frame Structure", IS 3309, October 1984, 3rd - Edition. - - [15] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT - Laboratory for Computer Science, April 1992. - - [16] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, MIT - Laboratory for Computer Science, April 1992. - - [17] Bellovin S., and M. Merritt, "Limitations of the Kerberos - Authentication System", Computer Communications Review, Vol. - 20(5), pp. 119-132, October 1990. - -12. Security Considerations - - Security issues are discussed throughout this memo. - -13. Authors' Addresses - - John Kohl - Digital Equipment Corporation - 110 Spit Brook Road, M/S ZKO3-3/U14 - Nashua, NH 03062 - - Phone: 603-881-2481 - EMail: jtkohl@zk3.dec.com - - - B. Clifford Neuman - USC/Information Sciences Institute - 4676 Admiralty Way #1001 - Marina del Rey, CA 90292-6695 - - Phone: 310-822-1511 - EMail: bcn@isi.edu - - - - - -Kohl & Neuman [Page 90] - -RFC 1510 Kerberos September 1993 - - -A. Pseudo-code for protocol processing - - This appendix provides pseudo-code describing how the messages are to - be constructed and interpreted by clients and servers. - -A.1. KRB_AS_REQ generation - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", - "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - - - -Kohl & Neuman [Page 91] - -RFC 1510 Kerberos September 1993 - - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable - skew) then error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - - - -Kohl & Neuman [Page 92] - -RFC 1510 Kerberos September 1993 - - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.ALLOW-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when - omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - - -Kohl & Neuman [Page 93] - -RFC 1510 Kerberos September 1993 - - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - - - -Kohl & Neuman [Page 94] - -RFC 1510 Kerberos September 1993 - - - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - -A.3. KRB_AS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) - then set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - - - -Kohl & Neuman [Page 95] - -RFC 1510 Kerberos September 1993 - - - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - /* make sure no flags are set that shouldn't be, and that */ - /* all that should be are set */ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) - then destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - - - -Kohl & Neuman [Page 96] - -RFC 1510 Kerberos September 1993 - - - endif - -A.5. KRB_TGS_REQ generation - /* Note that make_application_request might have to */ - /* recursivly call this routine to get the appropriate */ - /* ticket-granting ticket */ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - - - -Kohl & Neuman [Page 97] - -RFC 1510 Kerberos September 1993 - - - /* add in any other padata as required/supplied */ - - kerberos := lookup(name of local kerberose server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - /* note that reading the application request requires first - determining the server for which a ticket was issued, and - choosing the correct key for decryption. The name of the - server appears in the plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is - operating is determined by the instance from the - ticket-granting ticket. The realm in the ticket-granting - ticket is the realm under which the ticket granting ticket was - issued. It is possible for a single Kerberos server to - support more than one realm. */ - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not - req.sname) then error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof - and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - - -Kohl & Neuman [Page 98] - -RFC 1510 Kerberos September 1993 - - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(server)) then - server := best_intermediate_tgs(server); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - endif - - session := generate_random_session_key(); - - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - new_tkt.caddr := req.addresses; - - - -Kohl & Neuman [Page 99] - -RFC 1510 Kerberos September 1993 - - - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.POSTDATE is set) then - if (tgt.flags.POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - - if (req.kdc-options.VALIDATE is set) then - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - - - -Kohl & Neuman [Page 100] - -RFC 1510 Kerberos September 1993 - - - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket */ - /* would have been rejected in the initial authentication */ - /* stage, so there is no need to check again here */ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till >= kdc_time) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later */ - /* processing */ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - - - -Kohl & Neuman [Page 101] - -RFC 1510 Kerberos September 1993 - - - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; - /* leave the renew-till field out */ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data - into decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := - req.auth_hdr.ticket.authorization_data + - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited - := compress_transited(tgt.transited + tgt.realm) - endif - - - -Kohl & Neuman [Page 102] - -RFC 1510 Kerberos September 1993 - - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), - second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, - server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - - - -Kohl & Neuman [Page 103] - -RFC 1510 Kerberos September 1993 - - - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING - using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := - decode of decrypt of resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := - decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - -A.8. Authenticator generation - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - - -Kohl & Neuman [Page 104] - -RFC 1510 Kerberos September 1993 - - -A.9. KRB_AP_REQ generation - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - else - reset packet.ap-options.USE-SESSION-KEY; - endif - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator - using session_key; - -A.10. KRB_AP_REQ verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - - - -Kohl & Neuman [Page 105] - -RFC 1510 Kerberos September 1993 - - - endif - decrypt packet.ticket.enc-part into decr_ticket - using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) - then error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) - then error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - /* caller must check decr_ticket.flags for any pertinent */ - /* details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - -A.11. KRB_AP_REP generation - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - body.ctime := packet.ctime; - body.cusec := packet.cusec; - - - -Kohl & Neuman [Page 106] - -RFC 1510 Kerberos September 1993 - - - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) - using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - -A.13. KRB_SAFE generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - - -Kohl & Neuman [Page 107] - -RFC 1510 Kerberos September 1993 - - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof - and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - - - -Kohl & Neuman [Page 108] - -RFC 1510 Kerberos September 1993 - - - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) - then error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) - then error_out(KRB_AP_ERR_REPEAT); - endif - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) - then error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and - packet.seq-number not present) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - -A.16. KRB_PRIV generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - - - - -Kohl & Neuman [Page 109] - -RFC 1510 Kerberos September 1993 - - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - -A.17. KRB_PRIV verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - - - -Kohl & Neuman [Page 110] - -RFC 1510 Kerberos September 1993 - - - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - using negotiated encryption key; - -A.19. KRB_CRED verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - - - -Kohl & Neuman [Page 111] - -RFC 1510 Kerberos September 1993 - - - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) - then error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - endif - - - - - - - - - - - -Kohl & Neuman [Page 112] - \ No newline at end of file diff --git a/doc/old-V4-docs/README b/doc/old-V4-docs/README deleted file mode 100644 index 8858655cb..000000000 --- a/doc/old-V4-docs/README +++ /dev/null @@ -1,4 +0,0 @@ -These documentation files are old --- and refer to the Kerberos V4 -implementation. They are included because the equivalent V5 documentation -set have not been written yet, and the concepts contained in these documents -may be helpful. diff --git a/doc/old-V4-docs/installation.PS b/doc/old-V4-docs/installation.PS deleted file mode 100644 index 7609d4e64..000000000 --- a/doc/old-V4-docs/installation.PS +++ /dev/null @@ -1,2338 +0,0 @@ -%!PS-Adobe-2.0 -%%Title: installation.mss -%%DocumentFonts: (atend) -%%Creator: John T Kohl,,E40-351M,31510,6176432831 and Scribe 7(1700) -%%CreationDate: 4 January 1990 11:56 -%%Pages: (atend) -%%EndComments -% PostScript Prelude for Scribe. -/BS {/SV save def 0.0 792.0 translate .01 -.01 scale} bind def -/ES {showpage SV restore} bind def -/SC {setrgbcolor} bind def -/FMTX matrix def -/RDF {WFT SLT 0.0 eq - {SSZ 0.0 0.0 SSZ neg 0.0 0.0 FMTX astore} - {SSZ 0.0 SLT neg sin SLT cos div SSZ mul SSZ neg 0.0 0.0 FMTX astore} - ifelse makefont setfont} bind def -/SLT 0.0 def -/SI { /SLT exch cvr def RDF} bind def -/WFT /Courier findfont def -/SF { /WFT exch findfont def RDF} bind def -/SSZ 1000.0 def -/SS { /SSZ exch 100.0 mul def RDF} bind def -/AF { /WFT exch findfont def /SSZ exch 100.0 mul def RDF} bind def -/MT /moveto load def -/XM {currentpoint exch pop moveto} bind def -/UL {gsave newpath moveto dup 2.0 div 0.0 exch rmoveto - setlinewidth 0.0 rlineto stroke grestore} bind def -/LH {gsave newpath moveto setlinewidth - 0.0 rlineto - gsave stroke grestore} bind def -/LV {gsave newpath moveto setlinewidth - 0.0 exch rlineto - gsave stroke grestore} bind def -/BX {gsave newpath moveto setlinewidth - exch - dup 0.0 rlineto - exch 0.0 exch neg rlineto - neg 0.0 rlineto - closepath - gsave stroke grestore} bind def -/BX1 {grestore} bind def -/BX2 {setlinewidth 1 setgray stroke grestore} bind def -/PB {/PV save def newpath translate - 100.0 -100.0 scale pop /showpage {} def} bind def -/PE {PV restore} bind def -/GB {/PV save def newpath translate rotate - div dup scale 100.0 -100.0 scale /showpage {} def} bind def -/GE {PV restore} bind def -/FB {dict dup /FontMapDict exch def begin} bind def -/FM {cvn exch cvn exch def} bind def -/FE {end /original-findfont /findfont load def /findfont - {dup FontMapDict exch known{FontMapDict exch get} if - original-findfont} def} bind def -/BC {gsave moveto dup 0 exch rlineto exch 0 rlineto neg 0 exch rlineto closepath clip} bind def -/EC /grestore load def -/SH /show load def -/MX {exch show 0.0 rmoveto} bind def -/W {0 32 4 -1 roll widthshow} bind def -/WX {0 32 5 -1 roll widthshow 0.0 rmoveto} bind def -/RC {100.0 -100.0 scale -612.0 0.0 translate --90.0 rotate -.01 -.01 scale} bind def -/URC {100.0 -100.0 scale -90.0 rotate --612.0 0.0 translate -.01 -.01 scale} bind def -/RCC {100.0 -100.0 scale -0.0 -792.0 translate 90.0 rotate -.01 -.01 scale} bind def -/URCC {100.0 -100.0 scale --90.0 rotate 0.0 792.0 translate -.01 -.01 scale} bind def -%%EndProlog -%%Page: 0 1 -BS -0 SI -20 /Times-Bold AF -18823 13788 MT -(Kerberos Installation Notes)SH -27156 15798 MT -(DRAFT)SH -16 /Times-Roman AF -27021 23502 MT -(Bill Bryant)SH -25557 25150 MT -(Jennifer Steiner)SH -27289 26798 MT -(John Kohl)SH -23957 30444 MT -(Project Athena, MIT)SH -/Times-Bold SF -19489 36042 MT -(Initial Release, January 24, 1989)SH -/Times-Italic SF -17558 37690 MT -(\050plus later patches through patchlevel 7\051)SH -11 /Times-Roman AF -7200 45644 MT -(The release consists of three parts.)SH -7200 47942 MT -(The first part consists of the core Kerberos system, which was developed at MIT and does not require)SH -7200 49138 MT -(additional licenses for us to distribute. Included in this part are the Kerberos authentication server, the)SH -7200 50334 MT -(Kerberos library, the)SH -/Times-Italic SF -16606 XM -(ndbm)SH -/Times-Roman SF -19325 XM -(database interface library, user programs, administration programs, manual)SH -7200 51530 MT -(pages, some applications which use Kerberos for authentication, and some utilities.)SH -7200 53828 MT -(The second part is the Data Encryption Standard \050DES\051 library, which we are distributing only within the)SH -7200 55024 MT -(United States.)SH -7200 57322 MT -(The third part contains Kerberos modifications to Sun's NFS, which we distribute as ``context diffs'' to)SH -7200 58518 MT -(the Sun NFS source code. Its distribution is controlled to provide an accounting of who has retrieved the)SH -7200 59714 MT -(patches, so that Project Athena can comply with its agreements with Sun regarding distribution of these)SH -7200 60910 MT -(changes.)SH -ES -%%Page: 1 2 -BS -0 SI -16 /Times-Bold AF -7200 8272 MT -(1. Organization) -400 W( of the Source Directory)SH -11 /Times-Roman AF -7200 10467 MT -(The Kerberos building and installation process, as described in this document, builds the binaries and)SH -7200 11663 MT -(executables from the files contained in the Kerberos source tree, and deposits them in a separate object)SH -7200 12859 MT -(tree. This) -275 W( is intended to easily support several different build trees from a single source tree \050this is useful)SH -7200 14055 MT -(if you support several machine architectures\051. We suggest that you copy the Kerberos sources into a)SH -/Times-Italic SF -7200 15251 MT -(/mit/kerberos/src)SH -/Times-Roman SF -14991 XM -(directory, and create as well a)SH -/Times-Italic SF -28396 XM -(/mit/kerberos/obj)SH -/Times-Roman SF -36249 XM -(directory in which to hold the)SH -7200 16447 MT -(executables. In) -275 W( the rest of this document, we'll refer to the Kerberos source and object directories as)SH -7200 17643 MT -([SOURCE_DIR] and [OBJ_DIR], respectively.)SH -7200 19941 MT -(Below is a brief overview of the organization of the complete source directory. More detailed)SH -7200 21137 MT -(descriptions follow.)SH -/Times-Bold SF -7200 23088 MT -(admin)SH -/Times-Roman SF -18200 XM -(utilities for the Kerberos administrator)SH -/Times-Bold SF -7200 24783 MT -(appl)SH -/Times-Roman SF -18200 XM -(applications that use Kerberos)SH -/Times-Bold SF -7200 26478 MT -(appl/bsd)SH -/Times-Roman SF -18200 XM -(Berkeley's rsh/rlogin suite, using Kerberos)SH -/Times-Bold SF -7200 28173 MT -(appl/knetd)SH -/Times-Roman SF -18200 XM -(\050old\051 software for inetd-like multiplexing of a single TCP listening port)SH -/Times-Bold SF -7200 29868 MT -(appl/sample)SH -/Times-Roman SF -18200 XM -(sample application servers and clients)SH -/Times-Bold SF -7200 31563 MT -(appl/tftp)SH -/Times-Roman SF -18200 XM -(Trivial File Transfer Protocol, using Kerberos)SH -/Times-Bold SF -7200 33258 MT -(include)SH -/Times-Roman SF -18200 XM -(include files)SH -/Times-Bold SF -7200 34953 MT -(kadmin)SH -/Times-Roman SF -18200 XM -(remote administrative interface to the Kerberos master database)SH -/Times-Bold SF -7200 36648 MT -(kuser)SH -/Times-Roman SF -18200 XM -(assorted user programs)SH -/Times-Bold SF -7200 38343 MT -(lib)SH -/Times-Roman SF -18200 XM -(libraries for use with/by Kerberos)SH -/Times-Bold SF -7200 40038 MT -(lib/acl)SH -/Times-Roman SF -18200 XM -(Access Control List library)SH -/Times-Bold SF -7200 41733 MT -(lib/des)SH -/Times-Roman SF -18200 XM -(Data Encryption Standard library \050US only\051)SH -/Times-Bold SF -7200 43428 MT -(lib/kadm)SH -/Times-Roman SF -18200 XM -(administrative interface library)SH -/Times-Bold SF -7200 45123 MT -(lib/kdb)SH -/Times-Roman SF -18200 XM -(Kerberos server library interface to)SH -/Times-Italic SF -33925 XM -(ndbm)SH -/Times-Bold SF -7200 46818 MT -(lib/knet)SH -/Times-Roman SF -18200 XM -(\050old\051 library for use with)SH -/Times-Bold SF -29349 XM -(knetd)SH -7200 48513 MT -(lib/krb)SH -/Times-Roman SF -18200 XM -(Kerberos library)SH -/Times-Bold SF -7200 50208 MT -(man)SH -/Times-Roman SF -18200 XM -(manual pages)SH -/Times-Bold SF -7200 51903 MT -(prototypes)SH -/Times-Roman SF -18200 XM -(sample configuration files)SH -/Times-Bold SF -7200 53598 MT -(server)SH -/Times-Roman SF -18200 XM -(the authentication server)SH -/Times-Bold SF -7200 55293 MT -(slave)SH -/Times-Roman SF -18200 XM -(Kerberos slave database propagation software)SH -/Times-Bold SF -7200 56988 MT -(tools)SH -/Times-Roman SF -18200 XM -(shell scripts for maintaining the source tree)SH -/Times-Bold SF -7200 58683 MT -(util)SH -/Times-Roman SF -18200 XM -(utilities)SH -/Times-Bold SF -7200 60378 MT -(util/imake)SH -/Times-Roman SF -18200 XM -(Imakefile-to-Makefile ``compilation'' tool)SH -/Times-Bold SF -7200 62073 MT -(util/ss)SH -/Times-Roman SF -18200 XM -(Sub-system library \050for command line subsystems\051)SH -/Times-Bold SF -7200 63768 MT -(util/et)SH -/Times-Roman SF -18200 XM -(Error-table library \050for independent, unique error codes\051)SH -/Times-Bold SF -7200 65463 MT -(util/makedepend)SH -/Times-Roman SF -18200 XM -(Makefile dependency generator tool)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(1)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 2 3 -BS -0 SI -14 /Times-Bold AF -7200 8167 MT -(1.1 The)350 W -/Times-BoldItalic SF -12334 XM -(admin)SH -/Times-Bold SF -16340 XM -(Directory)SH -11 /Times-Roman AF -7200 10362 MT -(This directory contains source for the Kerberos master database administration tools.)SH -/Times-Bold SF -7200 12313 MT -(kdb_init)SH -/Times-Roman SF -18200 XM -(This program creates and initializes the Kerberos master database. It prompts)SH -18200 13509 MT -(for a Kerberos realmname, and the Kerberos master password.)SH -/Times-Bold SF -7200 15204 MT -(kstash)SH -/Times-Roman SF -18200 XM -(This program ``stashes'' the master password in the file)SH -/Times-Italic SF -43033 XM -(/.k)SH -/Times-Roman SF -44377 XM -(so that the master)SH -18200 16400 MT -(server machine can restart the Kerberos server automatically after an unattended)SH -18200 17596 MT -(reboot. The) -275 W( hidden password is also available to administrative programs that)SH -18200 18792 MT -(have been set to run automatically.)SH -/Times-Bold SF -7200 20487 MT -(kdb_edit)SH -/Times-Roman SF -18200 XM -(This program is a low-level tool for editing the master database.)SH -/Times-Bold SF -7200 22182 MT -(kdb_destroy)SH -/Times-Roman SF -18200 XM -(This program deletes the master database.)SH -/Times-Bold SF -7200 23877 MT -(kdb_util)SH -/Times-Roman SF -18200 XM -(This program can be used to dump the master database into an ascii file, and can)SH -18200 25073 MT -(also be used to load the ascii file into the master database.)SH -/Times-Bold SF -7200 26768 MT -(ext_srvtab)SH -/Times-Roman SF -18200 XM -(This program extracts information from the master database and creates a host-)SH -18200 27964 MT -(dependent)SH -/Times-Italic SF -22995 XM -(srvtab)SH -/Times-Roman SF -26020 XM -(file. This) -275 W( file contains the Kerberos keys for the host's)SH -18200 29160 MT -(``Kerberized'' services. These services look up their keys in the)SH -/Times-Italic SF -46846 XM -(srvtab)SH -/Times-Roman SF -49871 XM -(file for)SH -18200 30356 MT -(use in the authentication process.)SH -14 /Times-Bold AF -7200 34203 MT -(1.2 The)350 W -/Times-BoldItalic SF -12334 XM -(kuser)SH -/Times-Bold SF -15874 XM -(Directory)SH -11 /Times-Roman AF -7200 36398 MT -(This directory contains the source code for several user-oriented programs.)SH -/Times-Bold SF -7200 38349 MT -(kinit)SH -/Times-Roman SF -18200 XM -(This program prompts users for their usernames and Kerberos passwords, then)SH -18200 39545 MT -(furnishes them with Kerberos ticket-granting tickets.)SH -/Times-Bold SF -7200 41240 MT -(kdestroy)SH -/Times-Roman SF -18200 XM -(This program destroys any active tickets. Users should use)SH -/Times-Italic SF -44563 XM -(kdestroy)SH -/Times-Roman SF -48564 XM -(before they)SH -18200 42436 MT -(log off their workstations.)SH -/Times-Bold SF -7200 44131 MT -(klist)SH -/Times-Roman SF -18200 XM -(This program lists a user's active tickets.)SH -/Times-Bold SF -7200 45826 MT -(ksrvtgt)SH -/Times-Roman SF -18200 XM -(This retrieves a ticket-granting ticket with a life time of five minutes, using a)SH -18200 47022 MT -(server's secret key in lieu of a password. It is primarily for use in shell scripts)SH -18200 48218 MT -(and other batch facilities.)SH -/Times-Bold SF -7200 49913 MT -(ksu)SH -/Times-Roman SF -18200 XM -(Substitute user id, using Kerberos to mediate attempts to change to ``root''.)SH -14 /Times-Bold AF -7200 53760 MT -(1.3 The)350 W -/Times-BoldItalic SF -12334 XM -(appl)SH -/Times-Bold SF -15173 XM -(Directory)SH -11 /Times-Roman AF -7200 55955 MT -(If your site has the appropriate BSD license, your Kerberos release provides certain Unix utilities The)SH -7200 57151 MT -(Berkeley programs that have been modified to use Kerberos authentication are found in the)SH -/Times-Italic SF -47640 XM -(appl/bsd)SH -/Times-Roman SF -7200 58347 MT -(directory. They) -275 W( include)SH -/Times-Italic SF -18043 XM -(login)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -20855 XM -(rlogin)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -24095 XM -(rsh)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -27914 XM -(rcp)SH -/Times-Roman SF -(, as well as the associated daemon programs)SH -/Times-Italic SF -49081 XM -(kshd)SH -/Times-Roman SF -51372 XM -(and)SH -/Times-Italic SF -7200 59543 MT -(klogind)SH -/Times-Roman SF -(. The)275 W -/Times-Italic SF -13310 XM -(login)SH -/Times-Roman SF -15847 XM -(program obtains ticket-granting tickets for users upon login; the other utilities provide)SH -7200 60739 MT -(authenticated Unix network services.)SH -7200 63037 MT -(The)SH -/Times-Italic SF -9185 XM -(appl)SH -/Times-Roman SF -11416 XM -(directory also contains samples Kerberos application client and server programs, an)SH -7200 64233 MT -(authenticated)SH -/Times-Italic SF -13339 XM -(tftp)SH -/Times-Roman SF -15082 XM -(program,)SH -/Times-Italic SF -19358 XM -(knetd)SH -/Times-Roman SF -(, an authenticated inet daemon.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(2)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 3 4 -BS -0 SI -14 /Times-Bold AF -7200 8167 MT -(1.4 The)350 W -/Times-BoldItalic SF -12334 XM -(server)SH -/Times-Bold SF -16185 XM -(Directory)SH -11 /Times-Roman AF -7200 10362 MT -(The)SH -/Times-Italic SF -9185 XM -(server)SH -/Times-Roman SF -12208 XM -(directory contains the Kerberos KDC server, called)SH -/Times-Italic SF -35052 XM -(kerberos)SH -/Times-Roman SF -(. This) -275 W( program manages read-)SH -7200 11558 MT -(only requests made to the master database, distributing tickets and encryption keys to clients requesting)SH -7200 12754 MT -(authentication service.)SH -14 /Times-Bold AF -7200 16601 MT -(1.5 The)350 W -/Times-BoldItalic SF -12334 XM -(kadmin)SH -/Times-Bold SF -17040 XM -(Directory)SH -11 /Times-Roman AF -7200 18796 MT -(The)SH -/Times-Italic SF -9185 XM -(kadmin)SH -/Times-Roman SF -12698 XM -(directory contains the Kerberos administration server and associated client programs. The)SH -7200 19992 MT -(server accepts network requests from the user program)SH -/Times-Italic SF -31570 XM -(kpasswd)SH -/Times-Roman SF -35573 XM -(\050used to change a user's password\051, the)SH -7200 21188 MT -(Kerberos administration program)SH -/Times-Italic SF -22137 XM -(kadmin)SH -/Times-Roman SF -(, and the srvtab utility program)SH -/Times-Italic SF -39276 XM -(ksrvutil)SH -/Times-Roman SF -(. The) -275 W( administration)SH -7200 22384 MT -(server can make modifications to the master database.)SH -14 /Times-Bold AF -7200 26231 MT -(1.6 The)350 W -/Times-BoldItalic SF -12334 XM -(include)SH -/Times-Bold SF -16962 XM -(Directory)SH -11 /Times-Roman AF -7200 28426 MT -(This directory contains the)SH -/Times-Italic SF -19236 XM -(include)SH -/Times-Roman SF -22749 XM -(files needed to build the Kerberos system.)SH -14 /Times-Bold AF -7200 32273 MT -(1.7 The)350 W -/Times-BoldItalic SF -12334 XM -(lib)SH -/Times-Bold SF -14162 XM -(Directory)SH -11 /Times-Roman AF -7200 34468 MT -(The)SH -/Times-Italic SF -9185 XM -(lib)SH -/Times-Roman SF -10622 XM -(directory has six subdirectories:)SH -/Times-Italic SF -25193 XM -(acl)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -27087 XM -(des)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -29103 XM -(kadm)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -32035 XM -(kdb)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -34173 XM -(knet)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -38418 XM -(krb)SH -/Times-Roman SF -(. The)275 W -/Times-Italic SF -42694 XM -(des)SH -/Times-Roman SF -44435 XM -(directory contains)SH -7200 35664 MT -(source for the DES encryption library. The)SH -/Times-Italic SF -26595 XM -(kadm)SH -/Times-Roman SF -29252 XM -(directory contains source for the Kerberos)SH -7200 36860 MT -(administration server utility library. The)SH -/Times-Italic SF -25439 XM -(kdb)SH -/Times-Roman SF -27302 XM -(directory contains source for the Kerberos database routine)SH -7200 38056 MT -(library. The)275 W -/Times-Italic SF -12942 XM -(knet)SH -/Times-Roman SF -15049 XM -(directory contains source for a library used by clients of the)SH -/Times-Italic SF -41530 XM -(knetd)SH -/Times-Roman SF -44187 XM -(server. The)275 W -/Times-Italic SF -49683 XM -(krb)SH -/Times-Roman SF -7200 39252 MT -(directory contains source for the)SH -/Times-Italic SF -21707 XM -(libkrb.a)SH -/Times-Roman SF -25435 XM -(library. This) -275 W( library contains routines that are used by the)SH -7200 40448 MT -(Kerberos server program, and by applications programs that require authentication service.)SH -14 /Times-Bold AF -7200 44295 MT -(1.8 The)350 W -/Times-BoldItalic SF -12334 XM -(man)SH -/Times-Bold SF -15251 XM -(Directory)SH -11 /Times-Roman AF -7200 46490 MT -(This directory contains manual pages for Kerberos programs and library routines.)SH -14 /Times-Bold AF -7200 50337 MT -(1.9 The)350 W -/Times-BoldItalic SF -12334 XM -(prototypes)SH -/Times-Bold SF -18596 XM -(Directory)SH -11 /Times-Roman AF -7200 52532 MT -(This directory contains prototype)SH -/Times-Italic SF -22108 XM -(/etc/services)SH -/Times-Roman SF -27819 XM -(and)SH -/Times-Italic SF -29682 XM -(/etc/krb.conf)SH -/Times-Roman SF -35486 XM -(files. New) -275 W( entries must be added to the)SH -/Times-Italic SF -7200 53728 MT -(/etc/services)SH -/Times-Roman SF -12911 XM -(file for the Kerberos server, and possibly for Kerberized applications \050)SH -/Times-Italic SF -(services.append)SH -/Times-Roman SF -7200 54924 MT -(contains the entries used by the Athena-provided servers & applications, and is suitable for appending to)SH -7200 56120 MT -(your existing)SH -/Times-Italic SF -13250 XM -(/etc/services)SH -/Times-Roman SF -18961 XM -(file.\051. The)275 W -/Times-Italic SF -23878 XM -(/etc/krb.conf)SH -/Times-Roman SF -29682 XM -(file defines the local Kerberos realm for its host and)SH -7200 57316 MT -(lists Kerberos servers for given realms. The)SH -/Times-Italic SF -26961 XM -(/etc/krb.realms)SH -/Times-Roman SF -33865 XM -(file defines exceptions for mapping machine)SH -7200 58512 MT -(names to Kerberos realms.)SH -14 /Times-Bold AF -7200 62359 MT -(1.10 The)350 W -/Times-BoldItalic SF -13034 XM -(tools)SH -/Times-Bold SF -16107 XM -(Directory)SH -11 /Times-Roman AF -7200 64554 MT -(This directory contains a makefile to set up a directory tree for building the software in, and a shell script)SH -7200 65750 MT -(to format code in the style we use.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(3)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 4 5 -BS -0 SI -14 /Times-Bold AF -7200 8167 MT -(1.11 The)350 W -/Times-BoldItalic SF -13034 XM -(util)SH -/Times-Bold SF -15329 XM -(Directory)SH -11 /Times-Roman AF -7200 10362 MT -(This directory contains several utility programs and libraries. Included are Larry Wall's)SH -/Times-Italic SF -46296 XM -(patch)SH -/Times-Roman SF -49015 XM -(program, a)SH -/Times-Italic SF -7200 11558 MT -(make)SH -/Times-Roman SF -9795 XM -(pre-processor program called)SH -/Times-Italic SF -22956 XM -(imake)SH -/Times-Roman SF -(, and a program for generating Makefile dependencies,)SH -/Times-Italic SF -7200 12754 MT -(makedepend)SH -/Times-Roman SF -(, as well as the Sub-system library and utilities \050)SH -/Times-Italic SF -(ss)SH -/Times-Roman SF -(\051, and the Error table library and utilities)SH -7200 13950 MT -(\050)SH -/Times-Italic SF -(et)SH -/Times-Roman SF -(\051.)SH -16 /Times-Bold AF -7200 18622 MT -(2. Preparing) -400 W( for Installation)SH -11 /Times-Roman AF -7200 20817 MT -(This document assumes that you will build the system on the machine on which you plan to install the)SH -7200 22013 MT -(Kerberos master server and its database. You'll need about 10 megabytes for source and executables.)SH -7200 24311 MT -(By default, there must be a)SH -/Times-Italic SF -19327 XM -(/kerberos)SH -/Times-Roman SF -23756 XM -(directory on the master server machine in which to store the)SH -7200 25507 MT -(Kerberos database files. If the master server machine does not have room on its root partition for these)SH -7200 26703 MT -(files, create a)SH -/Times-Italic SF -13306 XM -(/kerberos)SH -/Times-Roman SF -17735 XM -(symbolic link to another file system.)SH -16 /Times-Bold AF -7200 31375 MT -(3. Preparing) -400 W( for the Build)SH -11 /Times-Roman AF -7200 33570 MT -(Before you build the system, you have to choose a)SH -/Times-Bold SF -29653 XM -(realm name)SH -/Times-Roman SF -(, the name that specifies the system's)SH -7200 34766 MT -(administrative domain. Project Athena uses the internet domain name ATHENA.MIT.EDU to specify its)SH -7200 35962 MT -(Kerberos realm name. We recommend using a name of this form.)SH -/Times-Bold SF -36857 XM -(NOTE:)SH -/Times-Roman SF -40616 XM -(the realm-name is case)SH -7200 37158 MT -(sensitive; by convention, we suggest that you use your internet domain name, in capital letters.)SH -7200 39456 MT -(Edit the [SOURCE_DIR]/)SH -/Times-Italic SF -(include/krb.h)SH -/Times-Roman SF -24860 XM -(file and look for the following lines of code:)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(4)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 5 6 -BS -0 SI -11 /Courier AF -8520 7886 MT -(/*)SH -9180 9000 MT -(* Kerberos specific definitions)SH -9180 10114 MT -(*)SH -9180 11228 MT -(* KRBLOG is the log file for the kerberos master server.)SH -9180 12342 MT -(* KRB_CONF is the configuration file where different host)SH -9180 13456 MT -(* machines running master and slave servers can be found.)SH -9180 14570 MT -(* KRB_MASTER is the name of the machine with the master)SH -9180 15684 MT -(* database. The admin_server runs on this machine, and all)SH -9180 16798 MT -(* changes to the db \050as opposed to read-only requests, which)SH -9180 17912 MT -(* can go to slaves\051 must go to it.)SH -9180 19026 MT -(* KRB_HOST is the default machine when looking for a kerberos)SH -9180 20140 MT -(* slave server. Other possibilities are in the KRB_CONF file.)SH -9180 21254 MT -(* KRB_REALM is the name of the realm.)SH -9180 22368 MT -(*/)SH -8520 24596 MT -(#ifdef notdef)SH -8520 25710 MT -(this is server-only, does not belong here;)SH -8520 26824 MT -(#define KRBLOG) -3960 W( "/kerberos/kerberos.log")5940 W -8520 27938 MT -(are these used anyplace '?';)SH -8520 29052 MT -(#define VX_KRB_HSTFILE) -9240 W( "/etc/krbhst")660 W -8520 30166 MT -(#define PC_KRB_HSTFILE) -9240 W( "\134\134kerberos\134\134krbhst")660 W -8520 31280 MT -(#endif)SH -8520 33508 MT -(#define KRB_CONF) -9240 W( "/etc/krb.conf")4620 W -8520 34622 MT -(#define KRB_RLM_TRANS) -9240 W( "/etc/krb.realms")1320 W -8520 35736 MT -(#define KRB_MASTER) -9240 W( "kerberos")3300 W -8520 36850 MT -(#define KRB_HOST) -9240 W( KRB_MASTER)5280 W -8520 37964 MT -(#define KRB_REALM) -9240 W( "ATHENA.MIT.EDU")3960 W -/Times-Roman SF -7200 39559 MT -(Edit the last line as follows:)SH -9400 41510 MT -(1.)SH -10500 XM -(Change the KRB_REALM definition so that it specifies the realm name you have chosen)SH -10500 42706 MT -(for your Kerberos system. This is a default which is usually overridden by a configuration)SH -10500 43902 MT -(file on each machine; however, if that config file is absent, many programs will use this)SH -10500 45098 MT -("built-in" realm name.)SH -14 /Times-Bold AF -7200 48945 MT -(3.1 The)350 W -/Times-BoldItalic SF -12334 XM -(/etc/krb.conf)SH -/Times-Bold SF -19956 XM -(File)SH -11 /Times-Roman AF -7200 51140 MT -(Create a)SH -/Times-Italic SF -11108 XM -(/etc/krb.conf)SH -/Times-Roman SF -16912 XM -(file using the following format:)SH -/Times-BoldItalic SF -8520 52740 MT -(realm_name)SH -8520 53854 MT -(realm_name master_server_name)1045 W -/Courier SF -25594 XM -(admin server)SH -/Times-Roman SF -7200 55449 MT -(where)SH -/Times-Italic SF -10161 XM -(realm_name)SH -/Times-Roman SF -15934 XM -(specifies the system's realm name, and)SH -/Times-Italic SF -33375 XM -(master_server_name)SH -/Times-Roman SF -42874 XM -(specifies the machine)SH -7200 56645 MT -(name on which you will run the master server. The words 'admin server' must appear next to the name of)SH -7200 57841 MT -(the server on which you intend to run the administration server \050which must be a machine with access to)SH -7200 59037 MT -(the database\051.)SH -7200 61335 MT -(For example, if your realm name is)SH -/Times-Italic SF -22962 XM -(tim.edu)SH -/Times-Roman SF -26506 XM -(and your master server's name is)SH -/Times-Italic SF -41288 XM -(kerberos.tim.edu)SH -/Times-Roman SF -(, the file)SH -7200 62531 MT -(should have these contents:)SH -/Courier SF -8520 64057 MT -(tim.edu)SH -8520 65171 MT -(tim.edu kerberos.tim.edu) -660 W( admin server)SH -/Times-Roman SF -7200 67469 MT -(See the [SOURCE_DIR]/)SH -/Times-Italic SF -(prototypes/etc.krb.conf)SH -/Times-Roman SF -28921 XM -(file for an example)SH -/Times-Italic SF -37533 XM -(/etc/krb.conf)SH -/Times-Roman SF -43337 XM -(file. That) -275 W( file has)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(5)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 6 7 -BS -0 SI -11 /Times-Roman AF -7200 7955 MT -(examples of how to provide backup servers for a given realm \050additional lines with the same leading)SH -7200 9151 MT -(realm name\051 and how to designate servers for remote realms.)SH -14 /Times-Bold AF -7200 12998 MT -(3.2 The)350 W -/Times-BoldItalic SF -12334 XM -(/etc/krb.realms)SH -/Times-Bold SF -21280 XM -(File)SH -11 /Times-Roman AF -7200 15193 MT -(In many situations, the default realm in which a host operates will be identical to the domain portion its)SH -7200 16389 MT -(Internet domain name.)SH -7200 18687 MT -(If this is not the case, you will need to establish a translation from host name or domain name to realm)SH -7200 19883 MT -(name. This) -275 W( is accomplished with the)SH -/Times-Italic SF -23820 XM -(/etc/krb.realms)SH -/Times-Roman SF -30724 XM -(file.)SH -7200 22181 MT -(Each line of the translation file specifies either a hostname or domain name, and its associated realm:)SH -/Courier SF -8520 23707 MT -(.domain.name kerberos.realm1)SH -8520 24821 MT -(host.name kerberos.realm2)SH -/Times-Roman SF -7200 26416 MT -(For example, to map all hosts in the domain LSC.TIM.EDU to KRB.REALM1 but the host)SH -7200 27612 MT -(FILMS.LSC.TIM.EDU to KRB.REALM2 your file would read:)SH -/Courier SF -8520 29138 MT -(.LSC.TIM.EDU KRB.REALM1)SH -8520 30252 MT -(FILMS.LSC.TIM.EDU KRB.REALM2)SH -/Times-Roman SF -7200 31847 MT -(If a particular host matches both a domain and a host entry, the host entry takes precedence.)SH -16 /Times-Bold AF -7200 36519 MT -(4. Building) -400 W( the Software)SH -11 /Times-Roman AF -7200 38714 MT -(Before you build the software read the)SH -/Times-Bold SF -24395 XM -(README)SH -/Times-Roman SF -29558 XM -(file in [SOURCE_DIR]. What follows is a more)SH -7200 39910 MT -(detailed description of the instructions listed in README.)SH -9400 41861 MT -(1.)SH -10500 XM -(Create an [OBJ_DIR] directory to hold the tree of Kerberos object files you are about to)SH -10500 43057 MT -(build, for example,)SH -/Times-Italic SF -19145 XM -(/mit/kerberos/obj)SH -/Times-Roman SF -(.)SH -9400 44951 MT -(2.)SH -10500 XM -(Change directory to [OBJ_DIR]. The following command creates directories under)SH -10500 46147 MT -([OBJ_DIR] and installs Makefiles for the final build.)SH -/Courier SF -11820 47724 MT -(host%)SH -/Times-Bold SF -15780 XM -(make -f [SOURCE_DIR]/tools/makeconfig SRCDIR=[SOURCE_DIR])275 W -/Times-Roman SF -9400 49618 MT -(3.)SH -10500 XM -(Change directory to util/imake.includes. Read through config.Imakefile, turning on)SH -10500 50814 MT -(appropriate flags for your installation. Change SRCTOP so that it is set to the top level of)SH -10500 52010 MT -(your source directory.)SH -9400 53904 MT -(4.)SH -10500 XM -(Check that your machine type has a definition in include/osconf.h & related files in the)SH -10500 55100 MT -(source tree \050if it doesn't, then you may need to create your own; if you get successful)SH -10500 56296 MT -(results, please post to kerberos@athena.mit.edu\051)SH -9400 58190 MT -(5.)SH -10500 XM -(Change directory to [OBJ_DIR]. The next command generates new Makefiles based on the)SH -10500 59386 MT -(configuration you selected in config.Imakefile, then adds dependency information to the)SH -10500 60582 MT -(Makefiles, and finally builds the system:)SH -/Courier SF -11820 62159 MT -(host%)SH -/Times-Bold SF -15780 XM -(make world)275 W -/Times-Roman SF -10500 63754 MT -(This command takes a while to complete; you may wish to redirect the output onto a file)SH -10500 64950 MT -(and put the job in the background:)SH -/Courier SF -11820 66527 MT -(host%)SH -/Times-Bold SF -15780 XM -(make world) -275 W( >&WORLDLOG_891201 &)SH -/Times-Roman SF -10500 68122 MT -(If you need to rebuild the Kerberos programs and libraries after making a change, you can)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(6)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 7 8 -BS -0 SI -11 /Times-Roman AF -10500 7955 MT -(usually just type:)SH -/Courier SF -11820 9532 MT -(host%)SH -/Times-Bold SF -15780 XM -(make all)275 W -/Times-Roman SF -10500 11127 MT -(However, if you changed the configuration in config.Imakefile or modified the Imakefiles)SH -10500 12323 MT -(or Makefiles, you should run)SH -/Times-Italic SF -23514 XM -(make world)SH -/Times-Roman SF -28952 XM -(to re-build all the Makefiles and dependency lists.)SH -14 /Times-Bold AF -7200 16141 MT -(4.1 Testing) -350 W( the DES Library)SH -11 /Times-Roman AF -7200 18336 MT -(Use the)SH -/Times-Italic SF -10804 XM -(verify)SH -/Times-Roman SF -13583 XM -(command to test the DES library implementation:)SH -/Courier SF -8520 19913 MT -(host%)SH -/Times-Bold SF -12480 XM -([OBJ_DIR]/lib/des/verify)SH -/Times-Roman SF -7200 21508 MT -(The command should display the following:)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(7)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 8 9 -BS -0 SI -11 /Courier AF -8520 7886 MT -(Examples per FIPS publication 81, keys ivs and cipher)SH -8520 9000 MT -(in hex. These are the correct answers, see below for)SH -8520 10114 MT -(the actual answers.)SH -8520 12342 MT -(Examples per Davies and Price.)SH -8520 14570 MT -(EXAMPLE ECB) -SH( key) -2640 W( = 08192a3b4c5d6e7f)SH -13800 15684 MT -(clear = 0)SH -13800 16798 MT -(cipher = 25 dd ac 3e 96 17 64 67)SH -8520 17912 MT -(ACTUAL ECB)SH -13800 19026 MT -(clear "")SH -13800 20140 MT -(cipher =) -660 W( \050low to high bytes\051)SH -19080 21254 MT -(25 dd ac 3e 96 17 64 67)SH -8520 23482 MT -(EXAMPLE ECB) -SH( key) -2640 W( = 0123456789abcdef)SH -13800 24596 MT -(clear = "Now is the time for all ")SH -13800 25710 MT -(cipher = 3f a4 0e 8a 98 4d 48 15 ...)SH -8520 26824 MT -(ACTUAL ECB)SH -13800 27938 MT -(clear "Now is the time for all ")SH -13800 29052 MT -(cipher =) -660 W( \050low to high bytes\051)SH -19080 30166 MT -(3f a4 0e 8a 98 4d 48 15)SH -8520 32394 MT -(EXAMPLE CBC) -SH( key) -2640 W( = 0123456789abcdef iv = 1234567890abcdef)SH -13800 33508 MT -(clear = "Now is the time for all ")SH -13800 34622 MT -(cipher =) -SH( e5) -4620 W( c7 cd de 87 2b f2 7c)SH -24360 35736 MT -(43 e9 34 00 8c 38 9c 0f)SH -24360 36850 MT -(68 37 88 49 9a 7c 05 f6)SH -8520 37964 MT -(ACTUAL CBC)SH -13800 39078 MT -(clear "Now is the time for all ")SH -13800 40192 MT -(ciphertext = \050low to high bytes\051)SH -19080 41306 MT -(e5 c7 cd de 87 2b f2 7c)SH -19080 42420 MT -(43 e9 34 00 8c 38 9c 0f)SH -19080 43534 MT -(68 37 88 49 9a 7c 05 f6)SH -19080 44648 MT -(00 00 00 00 00 00 00 00)SH -19080 45762 MT -(00 00 00 00 00 00 00 00)SH -19080 46876 MT -(00 00 00 00 00 00 00 00)SH -19080 47990 MT -(00 00 00 00 00 00 00 00)SH -19080 49104 MT -(00 00 00 00 00 00 00 00)SH -13800 50218 MT -(decrypted clear_text = "Now is the time for all ")SH -8520 51332 MT -(EXAMPLE CBC checksum) -SH( key) -1980 W( = 0123456789abcdef iv = 1234567890abcdef)SH -13800 52446 MT -(clear =) -SH( "7654321) -5280 W( Now is the time for ")SH -13800 53560 MT -(checksum 58) -4620 W( d2 e7 7e 86 06 27 33 or some part thereof)SH -8520 54674 MT -(ACTUAL CBC checksum)SH -19080 55788 MT -(encrypted cksum = \050low to high bytes\051)SH -19080 56902 MT -(58 d2 e7 7e 86 06 27 33)SH -/Times-Roman SF -7200 59200 MT -(If the)SH -/Times-Italic SF -9826 XM -(verify)SH -/Times-Roman SF -12605 XM -(command fails to display this information as specified above, the implementation of DES for)SH -7200 60396 MT -(your hardware needs to be adjusted. Your Kerberos system cannot work properly if your DES library)SH -7200 61592 MT -(fails this test.)SH -7200 63890 MT -(When you have finished building the software, you will find the executables in the object tree as follows:)SH -/Times-Bold SF -7200 65841 MT -([OBJ_DIR]/admin)SH -/Times-Italic SF -18200 XM -(ext_srvtab)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -23332 XM -(kdb_destroy)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -29258 XM -(kdb_edit)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -33596 XM -(kdb_init)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -37752 XM -(kdb_util)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -43771 XM -(kstash)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 67536 MT -([OBJ_DIR]/kuser)SH -/Times-Italic SF -18200 XM -(kdestroy)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -22476 XM -(kinit)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -24982 XM -(klist)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -27366 XM -(ksrvtgt)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -32773 XM -(ksu)SH -/Times-Roman SF -(.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(8)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 9 10 -BS -0 SI -11 /Times-Bold AF -7200 7955 MT -([OBJ_DIR]/server)SH -/Times-Italic SF -18200 XM -(kerberos)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 9650 MT -([OBJ_DIR]/appl/bsd)SH -/Times-Italic SF -18200 XM -(klogind)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -22050 XM -(kshd)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -24616 XM -(login.krb)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -29169 XM -(rcp)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -31185 XM -(rlogin)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -36288 XM -(rsh)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 11345 MT -([OBJ_DIR]/appl/knetd)SH -/Times-Italic SF -18200 XM -(knetd)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 13040 MT -([OBJ_DIR]/appl/sample)SH -/Times-Italic SF -18200 14236 MT -(sample_server)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -25164 XM -(sample_client)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -31824 XM -(simple_server)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -40407 XM -(simple_client)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 15931 MT -([OBJ_DIR]/appl/tftp)SH -/Times-Italic SF -18200 XM -(tcom)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -20888 XM -(tftpd)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -25319 XM -(tftp)SH -/Times-Roman SF -(.)SH -/Times-Bold SF -7200 17626 MT -([OBJ_DIR]/slave)SH -/Times-Italic SF -18200 XM -(kprop)SH -/Times-Roman SF -21041 XM -(and)SH -/Times-Italic SF -22904 XM -(kpropd)SH -/Times-Roman SF -(.)SH -16 /Times-Bold AF -7200 22298 MT -(5. Installing) -400 W( the Software)SH -11 /Times-Roman AF -7200 24493 MT -(To install the software, issue the)SH -/Times-Italic SF -21711 XM -(make install)SH -/Times-Roman SF -27333 XM -(command from the [OBJ_DIR] \050you need to be a privileged)SH -7200 25689 MT -(user in order to properly install the programs\051. Programs can either be installed in default directories, or)SH -7200 26885 MT -(under a given root directory, as described below.)SH -14 /Times-Bold AF -7200 30703 MT -(5.1 The) -350 W( ``Standard'' Places)SH -11 /Times-Roman AF -7200 32898 MT -(If you use the)SH -/Times-Italic SF -13492 XM -(make)SH -/Times-Roman SF -16087 XM -(command as follows:)SH -/Courier SF -8520 34475 MT -(host#)SH -/Times-Bold SF -12480 XM -(make install)275 W -/Times-Roman SF -7200 36070 MT -(the installation process will try to install the various parts of the system in ``standard'' directories. This)SH -7200 37266 MT -(process creates the ``standard'' directories as needed.)SH -7200 39564 MT -(The standard installation process copies things as follows:)SH -/Symbol SF -9169 41640 MT -(\267)SH -/Times-Roman SF -9950 XM -(The)SH -/Times-Italic SF -11935 XM -(include)SH -/Times-Roman SF -15448 XM -(files)SH -/Times-Italic SF -17617 XM -(krb.h)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -20458 XM -(des.h)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -23299 XM -(mit-copyright.h)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -30662 XM -(kadm.h)SH -/Times-Roman SF -34144 XM -(and)SH -/Times-Italic SF -36007 XM -(kadm_err.h)SH -/Times-Roman SF -41383 XM -(get copied to the)SH -/Times-Italic SF -9950 42836 MT -(/usr/include)SH -/Times-Roman SF -15481 XM -(directory.)SH -/Symbol SF -9169 44730 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos libraries)SH -/Times-Italic SF -20119 XM -(libdes.a)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -24122 XM -(libkrb.a)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -28125 XM -(libkdb.a)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -32250 XM -(libkadm.a)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -37169 XM -(libknet.a)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -43401 XM -(libacl.a)SH -/Times-Roman SF -47007 XM -(get)SH -9950 45926 MT -(copied to the)SH -/Times-Italic SF -15907 XM -(/usr/athena/lib)SH -/Times-Roman SF -22662 XM -(\050or wherever you pointed LIBDIR in config.Imakefile\051)SH -9950 47122 MT -(directory.)SH -/Symbol SF -9169 49016 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos master database utilities)SH -/Times-Italic SF -27085 XM -(kdb_init)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -31241 XM -(kdb_destroy)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -37167 XM -(kdb_edit)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -41505 XM -(kdb_util)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -45661 XM -(kstash)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -9950 50212 MT -(ext_srvtab)SH -/Times-Roman SF -14807 XM -(get copied to the)SH -/Times-Italic SF -22383 XM -(/usr/etc)SH -/Times-Roman SF -25958 XM -(\050DAEMDIR\051 directory.)SH -/Symbol SF -9169 52106 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos user utilities)SH -/Times-Italic SF -21924 XM -(kinit)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -24430 XM -(kdestroy)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -28706 XM -(klist)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -31090 XM -(ksrvtgt)SH -/Times-Roman SF -34359 XM -(and)SH -/Times-Italic SF -36222 XM -(ksu)SH -/Times-Roman SF -37963 XM -(get copied to the)SH -/Times-Italic SF -45539 XM -(/usr/athena)SH -/Times-Roman SF -9950 53302 MT -(\050PROGDIR\051 directory.)SH -/Symbol SF -9169 55196 MT -(\267)SH -/Times-Roman SF -9950 XM -(The modified Berkeley utilities)SH -/Times-Italic SF -24004 XM -(rsh)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -25960 XM -(rlogin)SH -/Times-Roman SF -28925 XM -(get copied to the)SH -/Times-Italic SF -36501 XM -(/usr/ucb)SH -/Times-Roman SF -40382 XM -(\050UCBDIR\051 directory;)SH -/Times-Italic SF -9950 56392 MT -(rcp)SH -/Times-Roman SF -11691 XM -(gets copied to the)SH -/Times-Italic SF -19695 XM -(/bin)SH -/Times-Roman SF -21682 XM -(\050SLASHBINDIR\051 directory; and)SH -/Times-Italic SF -36375 XM -(rlogind)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -40165 XM -(rshd)SH -/Times-Roman SF -(, and)SH -/Times-Italic SF -44534 XM -(login.krb)SH -/Times-Roman SF -48812 XM -(get)SH -9950 57588 MT -(copied to the)SH -/Times-Italic SF -15907 XM -(/usr/etc)SH -/Times-Roman SF -19482 XM -(\050DAEMDIR\051 directory. The old copies of the user programs are)SH -9950 58784 MT -(renamed)SH -/Times-Italic SF -14011 XM -(rsh.ucb)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -17830 XM -(rlogin.ucb)SH -/Times-Roman SF -22658 XM -(and)SH -/Times-Italic SF -24521 XM -(rcp.ucb)SH -/Times-Roman SF -(, respectively. The Kerberos versions of these)SH -9950 59980 MT -(programs are designed to fall back and execute the original versions if something prevents)SH -9950 61176 MT -(the Kerberos versions from succeeding.)SH -/Symbol SF -9169 63070 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos version of)SH -/Times-Italic SF -20944 XM -(tftp)SH -/Times-Roman SF -22687 XM -(and)SH -/Times-Italic SF -24550 XM -(tcom)SH -/Times-Roman SF -26963 XM -(get copied to the)SH -/Times-Italic SF -34539 XM -(/usr/athena)SH -/Times-Roman SF -39826 XM -(\050PROGDIR\051 directory;)SH -/Times-Italic SF -9950 64266 MT -(tftpd)SH -/Times-Roman SF -12243 XM -(gets copied to the)SH -/Times-Italic SF -20247 XM -(/etc)SH -/Times-Roman SF -22110 XM -(\050ETCDIR\051 directory.)SH -/Times-Italic SF -31884 XM -(tftp)SH -/Times-Roman SF -33627 XM -(and)SH -/Times-Italic SF -35490 XM -(tftpd)SH -/Times-Roman SF -37783 XM -(are installed set-uid to an)SH -9950 65462 MT -(unprivileged user \050user id of DEF_UID\051.)SH -/Symbol SF -9169 67356 MT -(\267)SH -/Times-Roman SF -9950 XM -(The)SH -/Times-Italic SF -11935 XM -(knetd)SH -/Times-Roman SF -14592 XM -(daemon gets copied to the)SH -/Times-Italic SF -26353 XM -(/usr/etc)SH -/Times-Roman SF -29928 XM -(\050DAEMDIR\051 directory.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(9)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 10 11 -BS -0 SI -11 /Symbol AF -9169 8080 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos server)SH -/Times-Italic SF -19201 XM -(kerberos)SH -/Times-Roman SF -(, the slave propagation software)SH -/Times-Italic SF -37343 XM -(kprop)SH -/Times-Roman SF -40184 XM -(and)SH -/Times-Italic SF -42047 XM -(kpropd)SH -/Times-Roman SF -(, and the)SH -9950 9276 MT -(administration server)SH -/Times-Italic SF -19542 XM -(kadmind)SH -/Times-Roman SF -23605 XM -(get copied to the)SH -/Times-Italic SF -31181 XM -(/usr/etc)SH -/Times-Roman SF -34756 XM -(\050SVRDIR, SVRDIR, and)SH -9950 10472 MT -(DAEMDIR\051 directory.)SH -/Symbol SF -9169 12366 MT -(\267)SH -/Times-Roman SF -9950 XM -(The remote administration tools)SH -/Times-Italic SF -24310 XM -(kpasswd)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -28588 XM -(ksrvutil)SH -/Times-Roman SF -32163 XM -(and)SH -/Times-Italic SF -34026 XM -(kadmin)SH -/Times-Roman SF -37539 XM -(get copied to the)SH -/Times-Italic SF -45115 XM -(/usr/athena)SH -/Times-Roman SF -9950 13562 MT -(\050PROGDIR\051 directory.)SH -/Symbol SF -9169 15456 MT -(\267)SH -/Times-Roman SF -9950 XM -(The Kerberos manual pages get installed in the appropriate)SH -/Times-Italic SF -36187 XM -(/usr/man)SH -/Times-Roman SF -40374 XM -(directories. Don't)275 W -9950 16652 MT -(forget to run)SH -/Times-Italic SF -15723 XM -(makewhatis)SH -/Times-Roman SF -21192 XM -(after installing the manual pages.)SH -14 /Times-Bold AF -7200 20470 MT -(5.2 ``Non-Standard'') -350 W( Installation)SH -11 /Times-Roman AF -7200 22665 MT -(If you'd rather install the software in a different location, you can use the)SH -/Times-Italic SF -39667 XM -(make)SH -/Times-Roman SF -42262 XM -(command as follows,)SH -7200 23861 MT -(where [DEST_DIR] specifies an alternate destination directory which will be used as the root for the)SH -7200 25057 MT -(installed programs, i.e. programs that would normally be installed in /usr/athena would be installed in)SH -7200 26253 MT -([DEST_DIR]/usr/athena.)SH -/Courier SF -8520 27830 MT -(host#)SH -/Times-Bold SF -12480 XM -(make install DESTDIR=[DEST_DIR])275 W -16 SS -7200 32502 MT -(6. Conclusion)400 W -11 /Times-Roman AF -7200 34697 MT -(Now that you have built and installed your Kerberos system, use the accompanying Kerberos Operation)SH -4030 50 44224 34897 UL -4398 50 48529 34897 UL -7200 35893 MT -(Notes to create a Kerberos Master database, install authenticated services, and start the Kerberos server.)SH -2566 50 7200 36093 UL -16 /Times-Bold AF -7200 40565 MT -(7. Acknowledgements)400 W -11 /Times-Roman AF -7200 42760 MT -(We'd like to thank Henry Mensch and Jon Rochlis for helping us debug this document.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30100 XM -(10)SH -47890 XM -(4 January 1990)SH -ES -%%Page: i 12 -BS -0 SI -14 /Times-Bold AF -25272 8138 MT -(Table of Contents)SH -13 SS -7200 9781 MT -(1. Organization) -325 W( of the Source Directory)SH -53350 XM -(1)SH -12 /Times-Roman AF -9000 11136 MT -(1.1 The)300 W -/Times-BoldItalic SF -13266 XM -(admin)SH -/Times-Roman SF -16701 XM -(Directory)SH -53400 XM -(2)SH -9000 12491 MT -(1.2 The)300 W -/Times-BoldItalic SF -13266 XM -(kuser)SH -/Times-Roman SF -16300 XM -(Directory)SH -53400 XM -(2)SH -9000 13846 MT -(1.3 The)300 W -/Times-BoldItalic SF -13266 XM -(appl)SH -/Times-Roman SF -15700 XM -(Directory)SH -53400 XM -(2)SH -9000 15201 MT -(1.4 The)300 W -/Times-BoldItalic SF -13266 XM -(server)SH -/Times-Roman SF -16566 XM -(Directory)SH -53400 XM -(3)SH -9000 16556 MT -(1.5 The)300 W -/Times-BoldItalic SF -13266 XM -(kadmin)SH -/Times-Roman SF -17301 XM -(Directory)SH -53400 XM -(3)SH -9000 17911 MT -(1.6 The)300 W -/Times-BoldItalic SF -13266 XM -(include)SH -/Times-Roman SF -17234 XM -(Directory)SH -53400 XM -(3)SH -9000 19266 MT -(1.7 The)300 W -/Times-BoldItalic SF -13266 XM -(lib)SH -/Times-Roman SF -14834 XM -(Directory)SH -53400 XM -(3)SH -9000 20621 MT -(1.8 The)300 W -/Times-BoldItalic SF -13266 XM -(man)SH -/Times-Roman SF -15767 XM -(Directory)SH -53400 XM -(3)SH -9000 21976 MT -(1.9 The)300 W -/Times-BoldItalic SF -13266 XM -(prototypes)SH -/Times-Roman SF -18634 XM -(Directory)SH -53400 XM -(3)SH -9000 23331 MT -(1.10 The)300 W -/Times-BoldItalic SF -13866 XM -(tools)SH -/Times-Roman SF -16501 XM -(Directory)SH -53400 XM -(3)SH -9000 24686 MT -(1.11 The)300 W -/Times-BoldItalic SF -13866 XM -(util)SH -/Times-Roman SF -15835 XM -(Directory)SH -53400 XM -(4)SH -13 /Times-Bold AF -7200 26329 MT -(2. Preparing) -325 W( for Installation)SH -53350 XM -(4)SH -7200 27972 MT -(3. Preparing) -325 W( for the Build)SH -53350 XM -(4)SH -12 /Times-Roman AF -9000 29327 MT -(3.1 The)300 W -/Times-BoldItalic SF -13266 XM -(/etc/krb.conf)SH -/Times-Roman SF -19801 XM -(File)SH -53400 XM -(5)SH -9000 30682 MT -(3.2 The)300 W -/Times-BoldItalic SF -13266 XM -(/etc/krb.realms)SH -/Times-Roman SF -20936 XM -(File)SH -53400 XM -(6)SH -13 /Times-Bold AF -7200 32325 MT -(4. Building) -325 W( the Software)SH -53350 XM -(6)SH -12 /Times-Roman AF -9000 33674 MT -(4.1 Testing) -300 W( the DES Library)SH -53400 XM -(7)SH -13 /Times-Bold AF -7200 35317 MT -(5. Installing) -325 W( the Software)SH -53350 XM -(9)SH -12 /Times-Roman AF -9000 36666 MT -(5.1 The) -300 W( ``Standard'' Places)SH -53400 XM -(9)SH -9000 38015 MT -(5.2 ``Non-Standard'') -300 W( Installation)SH -52800 XM -(10)SH -13 /Times-Bold AF -7200 39658 MT -(6. Conclusion)325 W -52700 XM -(10)SH -7200 41301 MT -(7. Acknowledgements)325 W -52700 XM -(10)SH -10 /Times-Roman AF -7200 75600 MT -(MIT Project Athena)SH -30461 XM -(i)SH -47890 XM -(4 January 1990)SH -ES -%%Trailer -%%Pages: 12 -%%DocumentFonts: Times-Roman Times-Bold Times-Italic Times-BoldItalic Courier Symbol diff --git a/doc/old-V4-docs/installation.mss b/doc/old-V4-docs/installation.mss deleted file mode 100644 index 0a2ae7595..000000000 --- a/doc/old-V4-docs/installation.mss +++ /dev/null @@ -1,681 +0,0 @@ -@Comment[ $Source$] -@Comment[ $Author$] -@Comment[ $Id$] -@Comment[] -@device[postscript] -@make[report] -@comment[ -@DefineFont(HeadingFont, - P=, - B=, - I=, - R=) -] -@DefineFont(HeadingFont, - P=, - B=, - I=, - R=) -@Counter(MajorPart,TitleEnv HD0,ContentsEnv tc0,Numbered [@I], - IncrementedBy Use,Announced) -@Counter(Chapter,TitleEnv HD1,ContentsEnv tc1,Numbered [@1. ], - IncrementedBy Use,Referenced [@1],Announced) -@Counter(Appendix,TitleEnv HD1,ContentsEnv tc1,Numbered [@A. ], - IncrementedBy,Referenced [@A],Announced,Alias Chapter) -@Counter(UnNumbered,TitleEnv HD1,ContentsEnv tc1,Announced,Alias - Chapter) -@Counter(Section,Within Chapter,TitleEnv HD2,ContentsEnv tc2, - Numbered [@#@:.@1 ],Referenced [@#@:.@1],IncrementedBy - Use,Announced) -@Counter(AppendixSection,Within Appendix,TitleEnv HD2, - ContentsEnv tc2, - Numbered [@#@:.@1 ],Referenced [@#@:.@1],IncrementedBy - Use,Announced) -@Counter(SubSection,Within Section,TitleEnv HD3,ContentsEnv tc3, - Numbered [@#@:.@1 ],IncrementedBy Use, - Referenced [@#@:.@1 ]) -@Counter(AppendixSubSection,Within AppendixSection,TitleEnv HD3, - ContentsEnv tc3, - Numbered [@#@:.@1 ],IncrementedBy Use, - Referenced [@#@:.@1 ]) -@Counter(Paragraph,Within SubSection,TitleEnv HD4,ContentsEnv tc4, - Numbered [@#@:.@1 ],Referenced [@#@:.@1], - IncrementedBy Use) -@modify(CopyrightNotice, Fixed -1 inch, Flushright) -@Modify(Titlebox, Fixed 3.0 inches) -@Modify(hd1, below .2 inch, facecode B, size 16, spaces kept, pagebreak off) -@Modify(hd2, below .2 inch, facecode B, size 14, spaces kept) -@Modify(hd3, below .2 inch, facecode B, size 12, spaces kept) -@Modify(Description, Leftmargin +20, Indent -20,below 1 line, above 1 line) -@Modify(Tc1, Above .5, Facecode B) -@Modify(Tc2, Above .25, Below .25, Facecode R) -@Modify(Tc3,Facecode R) -@Modify(Tc4,Facecode R) -@Modify(Itemize,Above 1line,Below 1line) -@Modify(Insert,LeftMargin +2, RightMargin +2) -@libraryfile[stable] -@comment[@Style(Font NewCenturySchoolBook, size 11)] -@Style(Font TimesRoman, size 11) -@Style(Spacing 1.1, indent 0) -@Style(leftmargin 1.0inch) -@Style(justification no) -@Style(BottomMargin 1.5inch) -@Style(ChangeBarLocation Right) -@Style(ChangeBars=off) -@pageheading[immediate] -@pagefooting[immediate, left = "MIT Project Athena", center = "@value(page)", -right = "@value(date)"] -@set[page = 0] -@blankspace[.5 inches] -@begin[group, size 20] -@begin(center) -@b[Kerberos Installation Notes] -@b[DRAFT] -@end[center] -@end(group) -@blankspace[.5 inches] -@begin[group, size 16] -@begin(center) -Bill Bryant -Jennifer Steiner -John Kohl -@blankspace[1 line] -Project Athena, MIT -@blankspace[.5 inches] -@b[Initial Release, January 24, 1989] -@i[(plus later patches through patchlevel 7)] -@end[center] -@end(group) -@begin[group, size 10] -@end[group] -@blankspace[.75 inches] - - -The release consists of three parts. - -The first part consists of the core Kerberos system, which was developed -at MIT and does not require additional licenses for us to distribute. -Included in this part are the Kerberos authentication server, the -Kerberos library, the -@i[ndbm] -database interface library, user programs, administration programs, -manual pages, some applications which use Kerberos for authentication, -and some utilities. - -The second part is the Data Encryption Standard (DES) library, which we -are distributing only within the United States. - -The third part contains Kerberos modifications to Sun's NFS, which we -distribute as ``context diffs'' to the Sun NFS source code. Its -distribution is controlled to provide an accounting of who has retrieved -the patches, so that Project Athena can comply with its agreements with -Sun regarding distribution of these changes. - -@newpage() -@chapter[Organization of the Source Directory] - -The Kerberos building and installation process, -as described in this document, -builds the binaries and executables from the files contained in the Kerberos -source tree, and deposits them in a separate object tree. -This is intended to easily support several different build trees from a -single source tree (this is useful if you support several machine -architectures). -We suggest that you copy the Kerberos sources into a -@i[/mit/kerberos/src] directory, -and create as well a @i[/mit/kerberos/obj] directory in which -to hold the executables. -In the rest of this document, we'll refer to the Kerberos -source and object directories as [SOURCE_DIR] -and [OBJ_DIR], respectively. - -Below is a brief overview of the organization of the complete -source directory. -More detailed descriptions follow. - -@begin[description] - -@b[admin]@\utilities for the Kerberos administrator - -@b[appl]@\applications that use Kerberos - -@b[appl/bsd]@\Berkeley's rsh/rlogin suite, using Kerberos - -@b[appl/knetd]@\(old) software for inetd-like multiplexing of a single -TCP listening port - -@b[appl/sample]@\sample application servers and clients - -@b[appl/tftp]@\Trivial File Transfer Protocol, using Kerberos - -@b[include]@\include files - -@b[kadmin]@\remote administrative interface to the Kerberos master database - -@b[kuser]@\assorted user programs - -@b[lib]@\libraries for use with/by Kerberos - -@b[lib/acl]@\Access Control List library - -@b[lib/des]@\Data Encryption Standard library (US only) - -@b[lib/kadm]@\administrative interface library - -@b[lib/kdb]@\Kerberos server library interface to @i[ndbm] - -@b[lib/knet]@\(old) library for use with @b[knetd] - -@b[lib/krb]@\Kerberos library - -@b[man]@\manual pages - -@b[prototypes]@\sample configuration files - -@b[server]@\the authentication server - -@b[slave]@\Kerberos slave database propagation software - -@b[tools]@\shell scripts for maintaining the source tree - -@b[util]@\utilities - -@b[util/imake]@\Imakefile-to-Makefile ``compilation'' tool - -@b[util/ss]@\Sub-system library (for command line subsystems) - -@b[util/et]@\Error-table library (for independent, unique error codes) - -@b[util/makedepend]@\Makefile dependency generator tool - -@end[description] - -@section[The @p(admin) Directory] - -This directory contains source for -the Kerberos master database administration tools. -@begin[description] -@b[kdb_init]@\This program creates and initializes the -Kerberos master database. -It prompts for a Kerberos realmname, and the Kerberos master password. - -@b[kstash]@\This program ``stashes'' the master password in the file -@i[/.k] so that the master server machine can restart the Kerberos -server automatically after an unattended reboot. -The hidden password is also available to administrative programs -that have been set to run automatically. - -@b[kdb_edit]@\This program is a low-level tool for editing -the master database. - -@b[kdb_destroy]@\This program deletes the master database. - -@b[kdb_util]@\This program can be used to dump the master database -into an ascii file, and can also be used to load the ascii file -into the master database. - -@b[ext_srvtab]@\This program extracts information from the master -database and creates a host-dependent @i[srvtab] file. -This file contains the Kerberos keys for the host's -``Kerberized'' services. -These services look up their keys in the @i[srvtab] file -for use in the authentication process. -@end[description] - -@section[The @p(kuser) Directory] - -This directory contains the source code for several user-oriented -programs. -@begin[description] -@b[kinit]@\This program prompts users for their usernames and -Kerberos passwords, then furnishes them with Kerberos ticket-granting -tickets. - -@b[kdestroy]@\This program destroys any active tickets. -Users should use @i[kdestroy] before they log off their workstations. - -@b[klist]@\This program lists a user's active tickets. - -@b[ksrvtgt]@\This retrieves a ticket-granting ticket with a life time -of five minutes, using a server's secret key in lieu of a password. It -is primarily for use in shell scripts and other batch facilities. - -@b[ksu]@\Substitute user id, using Kerberos to mediate attempts to -change to ``root''. -@end[description] - -@section[The @p(appl) Directory] - -If your site has the appropriate BSD license, -your Kerberos release provides certain Unix utilities -The Berkeley programs that have been modified to use Kerberos -authentication are found in the @i[appl/bsd] directory. -They include @i[login], @i[rlogin], @i[rsh], and @i[rcp], as well as the -associated daemon programs @i[kshd] and @i[klogind]. -The @i[login] program obtains ticket-granting tickets for users -upon login; the other utilities provide authenticated -Unix network services. - -The @i[appl] directory also contains samples Kerberos application -client and server programs, an authenticated @i[tftp] program, -@i[knetd], an authenticated inet daemon. - -@section[The @p(server) Directory] - -The @i[server] directory contains the Kerberos KDC server, called -@i[kerberos]. -This program manages read-only requests made to the -master database, -distributing tickets and encryption keys to clients requesting -authentication service. - -@section[The @p(kadmin) Directory] - -The @i[kadmin] directory contains the Kerberos administration server and -associated client programs. -The server accepts network requests from the -user program @i[kpasswd] (used to change a user's password), the -Kerberos administration program @i(kadmin), and the srvtab utility -program @i[ksrvutil]. -The administration server can make modifications to the master database. - -@section[The @p(include) Directory] - -This directory contains the @i[include] files needed to -build the Kerberos system. - -@section[The @p(lib) Directory] - -The @i[lib] directory has six subdirectories: -@i[acl], @i[des], @i[kadm], @i[kdb], @i[knet], and @i[krb]. -The @i[des] directory contains source for the DES encryption library. -The @i[kadm] directory contains source for the Kerberos administration -server utility library. -The @i[kdb] directory contains source for the Kerberos database -routine library. -The @i[knet] directory contains source for a library used by clients of -the @i[knetd] server. -The @i[krb] directory contains source for the @i[libkrb.a] -library. -This library contains routines that are used by the Kerberos server program, -and by applications programs that require authentication service. - -@section[The @p(man) Directory] - -This directory contains manual pages for Kerberos programs and -library routines. - -@section[The @p(prototypes) Directory] - -This directory contains prototype -@i[/etc/services] and @i[/etc/krb.conf] files. -New entries must be added to the @i[/etc/services] file for -the Kerberos server, and possibly for Kerberized applications -(@i[services.append] contains the entries used by the Athena-provided -servers & applications, and is suitable for appending to your existing -@i[/etc/services] file.). -The @i[/etc/krb.conf] file defines the local Kerberos realm -for its host and lists Kerberos servers for given realms. -The @i[/etc/krb.realms] file defines exceptions for mapping machine -names to Kerberos realms. - -@section[The @p(tools) Directory] - -This directory contains -a makefile to set up a directory tree -for building the software in, and -a shell script to format code in the -style we use. - - -@section[The @p(util) Directory] - -This directory contains several utility programs and libraries. -Included are Larry Wall's @i[patch] program, a @i[make] pre-processor -program called -@i[imake], and a program for generating Makefile dependencies, -@i[makedepend], as well as the Sub-system library and -utilities (@i[ss]), and the Error table library and utilities (@i[et]). - -@chapter[Preparing for Installation] - -This document assumes that you will build the system -on the machine on which you plan to install -the Kerberos master server and its database. -You'll need about 10 megabytes for source and executables. - -By default, there must be -a @i[/kerberos] directory on the master server machine -in which to store the Kerberos -database files. -If the master server machine does not have room on its root partition -for these files, -create a @i[/kerberos] symbolic link to another file system. - -@chapter[Preparing for the Build] - -Before you build the system, -you have to choose a @b[realm name], -the name that specifies the system's administrative domain. -Project Athena uses the internet domain name ATHENA.MIT.EDU -to specify its Kerberos realm name. -We recommend using a name of this form. -@b[NOTE:] the realm-name is case sensitive; by convention, we suggest -that you use your internet domain name, in capital letters. - -Edit the [SOURCE_DIR]/@i[include/krb.h] file and look for the following -lines of code: -@begin[example] -/* - * Kerberos specific definitions - * - * KRBLOG is the log file for the kerberos master server. - * KRB_CONF is the configuration file where different host - * machines running master and slave servers can be found. - * KRB_MASTER is the name of the machine with the master - * database. The admin_server runs on this machine, and all - * changes to the db (as opposed to read-only requests, which - * can go to slaves) must go to it. - * KRB_HOST is the default machine when looking for a kerberos - * slave server. Other possibilities are in the KRB_CONF file. - * KRB_REALM is the name of the realm. - */ - -#ifdef notdef -this is server-only, does not belong here; -#define KRBLOG "/kerberos/kerberos.log" -are these used anyplace '?'; -#define VX_KRB_HSTFILE "/etc/krbhst" -#define PC_KRB_HSTFILE "\\kerberos\\krbhst" -#endif - -#define KRB_CONF "/etc/krb.conf" -#define KRB_RLM_TRANS "/etc/krb.realms" -#define KRB_MASTER "kerberos" -#define KRB_HOST KRB_MASTER -#define KRB_REALM "ATHENA.MIT.EDU" -@end[example] -Edit the last line as follows: -@begin[enumerate] -Change the KRB_REALM definition so that it specifies the realm name -you have chosen for your Kerberos system. This is a default which is -usually overridden by a configuration file on each machine; however, if -that config file is absent, many programs will use this "built-in" realm -name. -@end[enumerate] - -@section[The @p(/etc/krb.conf) File] - -Create a @i[/etc/krb.conf] file using the following format: -@begin[example] -@p[realm_name] -@p[realm_name] @p[master_server_name] admin server -@end[example] -where @i[realm_name] specifies the system's realm name, -and @i[master_server_name] specifies the machine name on -which you will run the master server. The words 'admin server' must -appear next to the name of the server on which you intend to run the -administration server (which must be a machine with access to the database). - -For example, -if your realm name is @i[tim.edu] and your master server's name is -@i[kerberos.tim.edu], the file should have these contents: -@begin[example] -tim.edu -tim.edu kerberos.tim.edu admin server -@end[example] - -See the [SOURCE_DIR]/@i[prototypes/etc.krb.conf] file for an -example @i[/etc/krb.conf] file. That file has examples of how to -provide backup servers for a given realm (additional lines with the same -leading realm name) and how to designate servers for remote realms. - -@section[The @p(/etc/krb.realms) File] - -In many situations, the default realm in which a host operates will be -identical to the domain portion its Internet domain name. - -If this is not the case, you will need to establish a translation from -host name or domain name to realm name. This is accomplished with the -@i(/etc/krb.realms) file. - -Each line of the translation file specifies either a hostname or domain -name, and its associated realm: -@begin[example] -.domain.name kerberos.realm1 -host.name kerberos.realm2 -@end[example] -For example, to map all hosts in the domain LSC.TIM.EDU to KRB.REALM1 -but the host FILMS.LSC.TIM.EDU to KRB.REALM2 your file would read: -@begin[example] -.LSC.TIM.EDU KRB.REALM1 -FILMS.LSC.TIM.EDU KRB.REALM2 -@end[example] -If a particular host matches both a domain and a host entry, the host -entry takes precedence. - -@chapter[Building the Software] - -Before you build the software -read the @b[README] file in [SOURCE_DIR]. -What follows is a more detailed description of the instructions -listed in README. -@begin[enumerate] -Create an [OBJ_DIR] directory to hold the tree of Kerberos object files you -are about to build, for example, -@i[/mit/kerberos/obj]. - -Change directory to [OBJ_DIR]. -The following command creates directories under [OBJ_DIR] -and installs Makefiles for the final build. -@begin[example, rightmargin -7] -host% @b(make -f [SOURCE_DIR]/tools/makeconfig SRCDIR=[SOURCE_DIR]) -@end[example] - - - -Change directory to util/imake.includes. Read through config.Imakefile, -turning on appropriate flags for your installation. Change SRCTOP so -that it is set to the top level of your source directory. - -Check that your machine type has a definition in include/osconf.h & -related files in the source tree (if it doesn't, then you may need to -create your own; if you get successful results, please post to -kerberos@@athena.mit.edu) - -Change directory to [OBJ_DIR]. The next command generates new Makefiles -based on the configuration you selected in config.Imakefile, then adds -dependency information to the Makefiles, and finally builds the system: -@begin[example, rightmargin -7] -host% @b(make world) -@end[example] -This command takes a while to complete; you may wish to redirect the -output onto a file and put the job in the background: -@begin[example, rightmargin -7] -host% @b(make world >&WORLDLOG_891201 &) -@end[example] -If you need to rebuild the Kerberos programs and libraries after making -a change, you can usually just type: -@begin[example, rightmargin -7] -host% @b(make all) -@end[example] -However, if you changed the configuration in config.Imakefile or modified -the Imakefiles or Makefiles, you should run @i[make world] to re-build -all the Makefiles and dependency lists. -@end(enumerate) - -@section[Testing the DES Library] - -Use the @i[verify] command to test the DES library -implementation: -@begin[example] -host% @b([OBJ_DIR]/lib/des/verify) -@end[example] -The command should display the following: -@begin[example, rightmargin -10] -Examples per FIPS publication 81, keys ivs and cipher -in hex. These are the correct answers, see below for -the actual answers. - -Examples per Davies and Price. - -EXAMPLE ECB key = 08192a3b4c5d6e7f - clear = 0 - cipher = 25 dd ac 3e 96 17 64 67 -ACTUAL ECB - clear "" - cipher = (low to high bytes) - 25 dd ac 3e 96 17 64 67 - -EXAMPLE ECB key = 0123456789abcdef - clear = "Now is the time for all " - cipher = 3f a4 0e 8a 98 4d 48 15 ... -ACTUAL ECB - clear "Now is the time for all " - cipher = (low to high bytes) - 3f a4 0e 8a 98 4d 48 15 - -EXAMPLE CBC key = 0123456789abcdef iv = 1234567890abcdef - clear = "Now is the time for all " - cipher = e5 c7 cd de 87 2b f2 7c - 43 e9 34 00 8c 38 9c 0f - 68 37 88 49 9a 7c 05 f6 -ACTUAL CBC - clear "Now is the time for all " - ciphertext = (low to high bytes) - e5 c7 cd de 87 2b f2 7c - 43 e9 34 00 8c 38 9c 0f - 68 37 88 49 9a 7c 05 f6 - 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00 - 00 00 00 00 00 00 00 00 - decrypted clear_text = "Now is the time for all " -EXAMPLE CBC checksum key = 0123456789abcdef iv = 1234567890abcdef - clear = "7654321 Now is the time for " - checksum 58 d2 e7 7e 86 06 27 33 or some part thereof -ACTUAL CBC checksum - encrypted cksum = (low to high bytes) - 58 d2 e7 7e 86 06 27 33 -@end[example] - -If the @i[verify] command fails to display this information as specified -above, the implementation of DES for your hardware needs to -be adjusted. -Your Kerberos system cannot work properly if your DES library -fails this test. - -When you have finished building the software, -you will find the executables in the object tree as follows: -@begin[description] -@b([OBJ_DIR]/admin)@\@i[ext_srvtab], @i[kdb_destroy], -@i[kdb_edit], @i[kdb_init], @i[kdb_util], and @i[kstash]. - -@b([OBJ_DIR]/kuser)@\@i[kdestroy], @i[kinit], @i[klist], @i[ksrvtgt], -and @i[ksu]. - -@b([OBJ_DIR]/server)@\@i[kerberos]. - -@b([OBJ_DIR]/appl/bsd)@\@i[klogind], @i[kshd], @i[login.krb], @i[rcp], -@i[rlogin], and @i[rsh]. - -@b([OBJ_DIR]/appl/knetd)@\@i[knetd]. - -@b([OBJ_DIR]/appl/sample)@\@i[sample_server], @i[sample_client], -@i[simple_server], and @i[simple_client]. - -@b([OBJ_DIR]/appl/tftp)@\@i[tcom], @i[tftpd], and @i[tftp]. - -@b([OBJ_DIR]/slave)@\@i[kprop] and @i[kpropd]. -@end[description] - -@chapter[Installing the Software] - -To install the software, issue the @i[make install] command from -the [OBJ_DIR] (you need to be a privileged user in order to -properly install the programs). -Programs can either be installed in default directories, or under -a given root directory, as described below. - -@section[The ``Standard'' Places] - -If you use the @i[make] command as follows: -@begin[example] -host# @b(make install) -@end[example] -the installation process will try to install the various parts of the -system in ``standard'' directories. -This process creates the ``standard'' directories as needed. - -The standard installation process copies things as follows: -@begin[itemize] -The @i[include] files @i[krb.h], @i[des.h], @i[mit-copyright.h], -@i[kadm.h] and @i[kadm_err.h] get copied to the -@i[/usr/include] directory. - -The Kerberos libraries @i[libdes.a], @i[libkrb.a], @i[libkdb.a], -@i[libkadm.a], @i[libknet.a], and @i[libacl.a] get copied -to the @i[/usr/athena/lib] (or wherever you pointed LIBDIR in -config.Imakefile) directory. - -The Kerberos master database utilities @i[kdb_init], @i[kdb_destroy], -@i[kdb_edit], @i[kdb_util], @i[kstash], and @i[ext_srvtab] get copied to -the @i[/usr/etc] (DAEMDIR) directory. - -The Kerberos user utilities @i[kinit], @i[kdestroy], @i[klist], -@i[ksrvtgt] and @i[ksu] get copied to the @i[/usr/athena] (PROGDIR) -directory. - -The modified Berkeley utilities @i[rsh], @i[rlogin] get copied to the -@i[/usr/ucb] (UCBDIR) directory; @i[rcp] gets copied to the @i[/bin] -(SLASHBINDIR) directory; and @i[rlogind], @i[rshd], and @i[login.krb] -get copied to the @i[/usr/etc] (DAEMDIR) directory. The old copies of -the user programs are renamed @i(rsh.ucb), @i(rlogin.ucb) and -@i(rcp.ucb), respectively. The Kerberos versions of these programs are -designed to fall back and execute the original versions if something -prevents the Kerberos versions from succeeding. - -The Kerberos version of @i[tftp] and @i[tcom] get copied to the -@i[/usr/athena] (PROGDIR) directory; @i[tftpd] gets copied to the -@i[/etc] (ETCDIR) directory. @i[tftp] and @i[tftpd] are installed -set-uid to an unprivileged user (user id of DEF_UID). - -The @i[knetd] daemon gets copied to the @i[/usr/etc] (DAEMDIR) directory. - -The Kerberos server @i[kerberos], the slave propagation software -@i[kprop] and @i[kpropd], and the administration server @i[kadmind] get -copied to the @i[/usr/etc] (SVRDIR, SVRDIR, and DAEMDIR) directory. - -The remote administration tools @i[kpasswd], @i[ksrvutil] and @i[kadmin] -get copied to the @i[/usr/athena] (PROGDIR) directory. - -The Kerberos manual pages get installed in the appropriate -@i[/usr/man] directories. Don't forget to run @i[makewhatis] -after installing the manual pages. - -@end[itemize] - -@section[``Non-Standard'' Installation] - -If you'd rather install the software in a different location, -you can use the @i[make] command as follows, -where [DEST_DIR] specifies an alternate destination directory -which will be used as the root for the installed programs, i.e. programs -that would normally be installed in /usr/athena would be installed in -[DEST_DIR]/usr/athena. -@begin[example] -host# @b(make install DESTDIR=[DEST_DIR]) -@end[example] - -@chapter[Conclusion] - -Now that you have built and installed your Kerberos system, -use the accompanying @u[Kerberos Operation Notes] -to create a Kerberos Master database, install authenticated services, -and start the Kerberos server. - -@chapter [Acknowledgements] - -We'd like to thank Henry Mensch and Jon Rochlis for helping us debug -this document. diff --git a/doc/old-V4-docs/operation.PS b/doc/old-V4-docs/operation.PS deleted file mode 100644 index 3afb8cf06..000000000 --- a/doc/old-V4-docs/operation.PS +++ /dev/null @@ -1,2669 +0,0 @@ -%!PS-Adobe-2.0 -%%Title: operation.mss -%%DocumentFonts: (atend) -%%Creator: John T Kohl,,E40-351M,31510,6176432831 and Scribe 7(1700) -%%CreationDate: 4 January 1990 11:55 -%%Pages: (atend) -%%EndComments -% PostScript Prelude for Scribe. -/BS {/SV save def 0.0 792.0 translate .01 -.01 scale} bind def -/ES {showpage SV restore} bind def -/SC {setrgbcolor} bind def -/FMTX matrix def -/RDF {WFT SLT 0.0 eq - {SSZ 0.0 0.0 SSZ neg 0.0 0.0 FMTX astore} - {SSZ 0.0 SLT neg sin SLT cos div SSZ mul SSZ neg 0.0 0.0 FMTX astore} - ifelse makefont setfont} bind def -/SLT 0.0 def -/SI { /SLT exch cvr def RDF} bind def -/WFT /Courier findfont def -/SF { /WFT exch findfont def RDF} bind def -/SSZ 1000.0 def -/SS { /SSZ exch 100.0 mul def RDF} bind def -/AF { /WFT exch findfont def /SSZ exch 100.0 mul def RDF} bind def -/MT /moveto load def -/XM {currentpoint exch pop moveto} bind def -/UL {gsave newpath moveto dup 2.0 div 0.0 exch rmoveto - setlinewidth 0.0 rlineto stroke grestore} bind def -/LH {gsave newpath moveto setlinewidth - 0.0 rlineto - gsave stroke grestore} bind def -/LV {gsave newpath moveto setlinewidth - 0.0 exch rlineto - gsave stroke grestore} bind def -/BX {gsave newpath moveto setlinewidth - exch - dup 0.0 rlineto - exch 0.0 exch neg rlineto - neg 0.0 rlineto - closepath - gsave stroke grestore} bind def -/BX1 {grestore} bind def -/BX2 {setlinewidth 1 setgray stroke grestore} bind def -/PB {/PV save def newpath translate - 100.0 -100.0 scale pop /showpage {} def} bind def -/PE {PV restore} bind def -/GB {/PV save def newpath translate rotate - div dup scale 100.0 -100.0 scale /showpage {} def} bind def -/GE {PV restore} bind def -/FB {dict dup /FontMapDict exch def begin} bind def -/FM {cvn exch cvn exch def} bind def -/FE {end /original-findfont /findfont load def /findfont - {dup FontMapDict exch known{FontMapDict exch get} if - original-findfont} def} bind def -/BC {gsave moveto dup 0 exch rlineto exch 0 rlineto neg 0 exch rlineto closepath clip} bind def -/EC /grestore load def -/SH /show load def -/MX {exch show 0.0 rmoveto} bind def -/W {0 32 4 -1 roll widthshow} bind def -/WX {0 32 5 -1 roll widthshow 0.0 rmoveto} bind def -/RC {100.0 -100.0 scale -612.0 0.0 translate --90.0 rotate -.01 -.01 scale} bind def -/URC {100.0 -100.0 scale -90.0 rotate --612.0 0.0 translate -.01 -.01 scale} bind def -/RCC {100.0 -100.0 scale -0.0 -792.0 translate 90.0 rotate -.01 -.01 scale} bind def -/URCC {100.0 -100.0 scale --90.0 rotate 0.0 792.0 translate -.01 -.01 scale} bind def -%%EndProlog -%%Page: 0 1 -BS -0 SI -20 /Times-Bold AF -19324 13788 MT -(Kerberos Operation Notes)SH -27156 15798 MT -(DRAFT)SH -16 /Times-Roman AF -27021 23502 MT -(Bill Bryant)SH -27289 25150 MT -(John Kohl)SH -23957 26798 MT -(Project Athena, MIT)SH -/Times-Bold SF -19489 32396 MT -(Initial Release, January 24, 1989)SH -/Times-Italic SF -17558 34044 MT -(\050plus later patches through patchlevel 7\051)SH -11 /Times-Roman AF -7200 43798 MT -(These notes assume that you have used the)SH -/Times-Italic SF -26322 XM -(Kerberos Installation Notes)SH -/Times-Roman SF -38821 XM -(to build and install your Kerberos)SH -7200 44994 MT -(system. As) -275 W( in that document, we refer to the directory that contains the built Kerberos binaries as)SH -7200 46190 MT -([OBJ_DIR].)SH -7200 48488 MT -(This document assumes that you are a Unix system manager.)SH -ES -%%Page: 1 2 -BS -0 SI -16 /Times-Bold AF -7200 8272 MT -(1. How) -400 W( Kerberos Works: A Schematic Description)SH -11 /Times-Roman AF -7200 10467 MT -(This section provides a simplified description of a general user's interaction with the Kerberos system.)SH -7200 11663 MT -(This interaction happens transparently--users don't need to know and probably don't care about what's)SH -7200 12859 MT -(going on--but Kerberos administrators might find a schematic description of the process useful. The)SH -7200 14055 MT -(description glosses over a lot of details; for more information, see)SH -/Times-Italic SF -36404 XM -(Kerberos: An Authentication Service)SH -7200 15251 MT -(for Open Network Systems)SH -/Times-Roman SF -(, a paper presented at Winter USENIX 1988, in Dallas, Texas.)SH -14 /Times-Bold AF -7200 19069 MT -(1.1 Network) -350 W( Services and Their Client Programs)SH -11 /Times-Roman AF -7200 21264 MT -(In an environment that provides network services, you use)SH -/Times-Italic SF -33164 XM -(client)SH -/Times-Roman SF -35883 XM -(programs to request service from)SH -/Times-Italic SF -50696 XM -(server)SH -/Times-Roman SF -7200 22460 MT -(programs that are somewhere on the network. Suppose you have logged in to a workstation and you want)SH -7200 23656 MT -(to)SH -/Times-Italic SF -8331 XM -(rlogin)SH -/Times-Roman SF -11296 XM -(to another machine. You use the local)SH -/Times-Italic SF -28493 XM -(rlogin)SH -/Times-Roman SF -31458 XM -(client program to contact the remote machine's)SH -/Times-Italic SF -7200 24852 MT -(rlogin)SH -/Times-Roman SF -10165 XM -(service daemon.)SH -14 /Times-Bold AF -7200 28670 MT -(1.2 Kerberos) -350 W( Tickets)SH -11 /Times-Roman AF -7200 30865 MT -(Under Kerberos, the)SH -/Times-Italic SF -16422 XM -(rlogin)SH -/Times-Roman SF -19387 XM -(service program allows a client to login to a remote machine if it can provide)SH -7200 32061 MT -(a Kerberos)SH -/Times-Bold SF -12268 XM -(ticket)SH -/Times-Roman SF -15169 XM -(for the request. This ticket proves the identity of the person who has used the client)SH -7200 33257 MT -(program to access the server program.)SH -14 /Times-Bold AF -7200 37075 MT -(1.3 The) -350 W( Kerberos Master Database)SH -11 /Times-Roman AF -7200 39270 MT -(Kerberos will give you tickets only if you have an entry in the Kerberos server's)SH -/Times-Bold SF -42845 XM -(master database)SH -/Times-Roman SF -(. Your)275 W -7200 40466 MT -(database entry includes your Kerberos username \050often referred to as your Kerberos)SH -/Times-Bold SF -44394 XM -(principal)SH -/Times-Roman SF -48949 XM -(name\051, and)SH -7200 41662 MT -(your Kerberos password. Every Kerberos user must have an entry in this database.)SH -14 /Times-Bold AF -7200 45480 MT -(1.4 The) -350 W( Ticket-Granting Ticket)SH -11 /Times-Roman AF -7200 47675 MT -(The)SH -/Times-Italic SF -9185 XM -(kinit)SH -/Times-Roman SF -11416 XM -(command prompts for your Kerberos username and password, and if you enter them)SH -7200 48871 MT -(successfully, you will obtain a Kerberos)SH -/Times-Italic SF -25131 XM -(ticket-granting ticket)SH -/Times-Roman SF -(. As) -275 W( illustrated below, client programs use)SH -7200 50067 MT -(this ticket to get other Kerberos tickets as needed.)SH -14 /Times-Bold AF -7200 53885 MT -(1.5 Network) -350 W( Services and the Master Database)SH -11 /Times-Roman AF -7200 56080 MT -(The master database also contains entries for all network services that require Kerberos authentication.)SH -7200 57276 MT -(Suppose for instance that your site has a machine)SH -/Times-Italic SF -29163 XM -(laughter)SH -/Times-Roman SF -33166 XM -(that requires Kerberos authentication from)SH -7200 58472 MT -(anyone who wants to)SH -/Times-Italic SF -16792 XM -(rlogin)SH -/Times-Roman SF -19757 XM -(to it. This service must be registered in the master database. Its entry)SH -7200 59668 MT -(includes the service's principal name, and its)SH -/Times-Bold SF -27238 XM -(instance)SH -/Times-Roman SF -(.)SH -7200 61966 MT -(The)SH -/Times-Italic SF -9185 XM -(instance)SH -/Times-Roman SF -13126 XM -(is the name of the service's machine; in this case, the service's instance is the name)SH -/Times-Italic SF -7200 63162 MT -(laughter)SH -/Times-Roman SF -(. The) -275 W( instance provides a means for Kerberos to distinguish between machines that provide the)SH -7200 64358 MT -(same service. Your site is likely to have more than one machine that provides)SH -/Times-Italic SF -41840 XM -(rlogin)SH -/Times-Roman SF -44805 XM -(service.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(1)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 2 3 -BS -0 SI -14 /Times-Bold AF -7200 8138 MT -(1.6 The) -350 W( User-Kerberos Interaction)SH -11 /Times-Roman AF -7200 10333 MT -(Suppose that you \050in the guise of a general user\051 walk up to a workstation intending to login to it, and)SH -7200 11529 MT -(then)SH -/Times-Italic SF -9369 XM -(rlogin)SH -/Times-Roman SF -12334 XM -(to the machine)SH -/Times-Italic SF -19085 XM -(laughter)SH -/Times-Roman SF -(. Here's) -275 W( what happens.)SH -9400 13480 MT -(1.)SH -10500 XM -(You login to the workstation and use the)SH -/Times-Italic SF -28648 XM -(kinit)SH -/Times-Roman SF -30879 XM -(command to to get a ticket-granting ticket.)SH -10500 14676 MT -(This command prompts you for your username \050your Kerberos Principal Name\051, and your)SH -10500 15872 MT -(Kerberos password [on some systems which use the new version of)SH -/Times-Italic SF -40465 XM -(/bin/login)SH -/Times-Roman SF -(, this may be)SH -10500 17068 MT -(done as part of the login process, not requiring the user to run a separate program].)SH -12762 19019 MT -(a.)SH -13800 XM -(The)SH -/Times-Italic SF -15785 XM -(kinit)SH -/Times-Roman SF -18016 XM -(command sends your request to the Kerberos master server machine. The)SH -13800 20215 MT -(server software looks for your principal name's entry in the Kerberos)SH -/Times-Bold SF -44555 XM -(master)SH -13800 21411 MT -(database)SH -/Times-Roman SF -(.)SH -12700 23305 MT -(b.)SH -13800 XM -(If this entry exists, the Kerberos server creates and returns a)SH -/Times-Italic SF -40430 XM -(ticket-granting ticket)SH -/Times-Roman SF -(,)SH -13800 24501 MT -(encrypted in your password. If)SH -/Times-Italic SF -27819 XM -(kinit)SH -/Times-Roman SF -30050 XM -(can decrypt the Kerberos reply using the)SH -13800 25697 MT -(password you provide, it stores this ticket in a)SH -/Times-Bold SF -34270 XM -(ticket file)SH -/Times-Roman SF -38912 XM -(on your local machine for)SH -13800 26893 MT -(later use. The ticket file to be used can be specified in the)SH -/Times-Bold SF -39609 XM -(KRBTKFILE)SH -/Times-Roman SF -13800 28089 MT -(environment variable. If this variable is not set, the name of the file will be)SH -/Times-Italic SF -13800 29285 MT -(/tmp/tkt)SH -/Times-BoldItalic SF -(uid)SH -/Times-Roman SF -(, where)SH -/Times-BoldItalic SF -22141 XM -(uid)SH -/Times-Roman SF -23884 XM -(is the UNIX user-id, represented in decimal.)SH -9400 31236 MT -(2.)SH -10500 XM -(Now you use the)SH -/Times-Italic SF -18198 XM -(rlogin)SH -/Times-Roman SF -21163 XM -(client to try to access the machine)SH -/Times-Italic SF -36344 XM -(laughter)SH -/Times-Roman SF -(.)SH -/Courier SF -11820 32813 MT -(host%)SH -/Times-Bold SF -15780 XM -(rlogin laughter)275 W -/Times-Roman SF -12762 34764 MT -(a.)SH -13800 XM -(The)SH -/Times-Italic SF -15785 XM -(rlogin)SH -/Times-Roman SF -18750 XM -(client checks your ticket file to see if you have a ticket for)SH -/Times-Italic SF -44559 XM -(laughter)SH -/Times-Roman SF -('s)SH -/Times-Italic SF -13800 35960 MT -(rcmd)SH -/Times-Roman SF -16335 XM -(service \050the rlogin program uses the)SH -/Times-Italic SF -32401 XM -(rcmd)SH -/Times-Roman SF -34936 XM -(service name, mostly for historical)SH -13800 37156 MT -(reasons\051. You) -275 W( don't, so)SH -/Times-Italic SF -24583 XM -(rlogin)SH -/Times-Roman SF -27548 XM -(uses the ticket file's)SH -/Times-Italic SF -36590 XM -(ticket-granting ticket)SH -/Times-Roman SF -46060 XM -(to make a)SH -13800 38352 MT -(request to the master server's ticket-granting service.)SH -12700 40246 MT -(b.)SH -13800 XM -(This ticket-granting service receives the)SH -/Times-Italic SF -31667 XM -(rcmd-laughter)SH -/Times-Roman SF -38296 XM -(request and looks in the)SH -13800 41442 MT -(master database for an)SH -/Times-Italic SF -23938 XM -(rcmd-laughter)SH -/Times-Roman SF -30567 XM -(entry. If) -275 W( that entry exists, the ticket-granting)SH -13800 42638 MT -(service issues you a ticket for that service. That ticket is also cached in your ticket)SH -13800 43834 MT -(file.)SH -12762 45728 MT -(c.)SH -13800 XM -(The)SH -/Times-Italic SF -15785 XM -(rlogin)SH -/Times-Roman SF -18750 XM -(client now uses that ticket to request service from the)SH -/Times-Italic SF -42454 XM -(laughter rlogin)SH -/Times-Roman SF -13800 46924 MT -(service program. The service program lets you)SH -/Times-Italic SF -34843 XM -(rlogin)SH -/Times-Roman SF -37808 XM -(if the ticket is valid.)SH -16 /Times-Bold AF -7200 51596 MT -(2. Setting) -400 W( Up and Testing the Kerberos Server)SH -11 /Times-Roman AF -7200 53791 MT -(The procedure for setting up and testing a Kerberos server is as follows:)SH -9400 55742 MT -(1.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kdb_init)SH -/Times-Roman SF -17985 XM -(command to create and initialize the master database.)SH -9400 57636 MT -(2.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kdb_edit)SH -/Times-Roman SF -18167 XM -(utility to add your username to the master database.)SH -9400 59530 MT -(3.)SH -10500 XM -(Start the Kerberos server.)SH -9400 61424 MT -(4.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kinit)SH -/Times-Roman SF -16335 XM -(command to obtain a Kerberos ticket-granting ticket.)SH -9400 63318 MT -(5.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(klist)SH -/Times-Roman SF -16213 XM -(command to verify that the)SH -/Times-Italic SF -28402 XM -(kinit)SH -/Times-Roman SF -30633 XM -(command authenticated you successfully.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(2)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 3 4 -BS -0 SI -14 /Times-Bold AF -7200 8138 MT -(2.1 Creating) -350 W( and Initializing the Master Database)SH -11 /Times-Roman AF -7200 10333 MT -(Login to the Kerberos master server machine, and use the)SH -/Times-Bold SF -32825 XM -(su)SH -/Times-Roman SF -34140 XM -(command to become root. If you installed)SH -7200 11529 MT -(the Kerberos administration tools with the)SH -/Times-Italic SF -26020 XM -(make install)SH -/Times-Roman SF -31642 XM -(command and the default pathnames, they should)SH -7200 12725 MT -(be in the)SH -/Times-Italic SF -11263 XM -(/usr/etc)SH -/Times-Roman SF -14838 XM -(directory. If) -275 W( you installed the tools in a different directory, hopefully you know what it)SH -7200 13921 MT -(is. From) -275 W( now on, we will refer to this directory as [ADMIN_DIR].)SH -7200 16219 MT -(The)SH -/Times-Italic SF -9185 XM -(kdb_init)SH -/Times-Roman SF -13066 XM -(command creates and initializes the master database. It asks you to enter the system's realm)SH -7200 17415 MT -(name and the database's master password. Do not forget this password. If you do, the database becomes)SH -7200 18611 MT -(useless. \050Your) -275 W( realm name should be substituted for [REALMNAME] below.\051)SH -7200 20909 MT -(Use)SH -/Times-Italic SF -9185 XM -(kdb_init)SH -/Times-Roman SF -13066 XM -(as follows:)SH -/Courier SF -8520 22486 MT -(host#)SH -/Times-Bold SF -12480 XM -([ADMIN_DIR]/kdb_init)SH -/Courier SF -8520 23600 MT -(Realm name \050default XXX\051:)SH -/Times-Bold SF -25680 XM -([REALMNAME])SH -39600 XM -(<--)SH -/Times-BoldItalic SF -41619 XM -(Enter your system's realm name.)SH -/Courier SF -8520 24714 MT -(You will be prompted for the database Master Password.)SH -8520 25828 MT -(It is important that you NOT FORGET this password.)SH -8520 28056 MT -(Enter Kerberos master key:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter the master password.)SH -14 /Times-Bold AF -7200 32988 MT -(2.2 Storing) -350 W( the Master Password)SH -11 /Times-Roman AF -7200 35183 MT -(The)SH -/Times-Italic SF -9185 XM -(kstash)SH -/Times-Roman SF -12210 XM -(command ``stashes'' the master password in the file)SH -/Times-Italic SF -35424 XM -(/.k)SH -/Times-Roman SF -36768 XM -(so that the Kerberos server can be)SH -7200 36379 MT -(started automatically during an unattended reboot of the master server. Other administrative programs)SH -7200 37575 MT -(use this hidden password so that they can access the master database without someone having to manually)SH -7200 38771 MT -(provide the master password. This command is an optional one; if you'd rather enter the master password)SH -7200 39967 MT -(each time you start the Kerberos server, don't use)SH -/Times-Italic SF -29312 XM -(kstash)SH -/Times-Roman SF -(.)SH -7200 42265 MT -(One the one hand, if you use)SH -/Times-Italic SF -20090 XM -(kstash)SH -/Times-Roman SF -(, a copy of the master key will reside on disk which may not be)SH -7200 43461 MT -(acceptable; on the other hand, if you don't use)SH -/Times-Italic SF -27848 XM -(kstash)SH -/Times-Roman SF -(, the server cannot be started unless someone is)SH -7200 44657 MT -(around to type the password in manually.)SH -7200 46955 MT -(The command prompts you twice for the master password:)SH -/Courier SF -8520 48532 MT -(host#)SH -/Times-Bold SF -12480 XM -([ADMIN_DIR]/kstash)SH -/Courier SF -8520 50760 MT -(Enter Kerberos master key:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter the master password.)SH -/Courier SF -8520 51874 MT -(Current Kerberos master key version is 1.)SH -8520 54102 MT -(Master key entered) -SH( BEWARE!)1320 W -/Times-Roman SF -7200 56400 MT -(A note about the Kerberos database master key: if your master key is compromised and the database is)SH -7200 57596 MT -(obtained, the security of your entire authentication system is compromised. The master key must be a)SH -7200 58792 MT -(carefully kept secret. If you keep backups, you must guard all the master keys you use, in case someone)SH -7200 59988 MT -(has stolen an old backup and wants to attack users' whose passwords haven't changed since the backup)SH -7200 61184 MT -(was stolen. This is why we provide the option not to store it on disk.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(3)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 4 5 -BS -0 SI -14 /Times-Bold AF -7200 8167 MT -(2.3 Using)350 W -/Times-BoldItalic SF -13423 XM -(kdb_edit)SH -/Times-Bold SF -18673 XM -(to Add Users to the Master Database)SH -11 /Times-Roman AF -7200 10362 MT -(The)SH -/Times-Italic SF -9185 XM -(kdb_edit)SH -/Times-Roman SF -13248 XM -(program is used to add new users and services to the master database, and to modify)SH -7200 11558 MT -(existing database information. The program prompts you to enter a principal's)SH -/Times-Bold SF -42177 XM -(name)SH -/Times-Roman SF -45018 XM -(and)SH -/Times-Bold SF -46881 XM -(instance)SH -/Times-Roman SF -(.)SH -7200 13856 MT -(A principal name is typically a username or a service program's name. An instance further qualifies the)SH -7200 15052 MT -(principal. If) -275 W( the principal is a service, the instance is used to specify the name of the machine on which)SH -7200 16248 MT -(that service runs. If the principal is a username that has general user privileges, the instance is usually set)SH -7200 17444 MT -(to null.)SH -7200 19742 MT -(The following example shows how to use)SH -/Times-Italic SF -25805 XM -(kdb_edit)SH -/Times-Roman SF -29868 XM -(to add the user)SH -/Times-Italic SF -36588 XM -(wave)SH -/Times-Roman SF -39123 XM -(to the Kerberos database.)SH -/Courier SF -8520 21319 MT -(host#)SH -/Times-Bold SF -12480 XM -([ADMIN_DIR]/kdb_edit)SH -/Courier SF -8520 23547 MT -(Opening database...)SH -8520 25775 MT -(Enter Kerberos master key:)SH -8520 26889 MT -(Verifying, please re-enter)SH -8520 28003 MT -(Enter Kerberos master key:)SH -8520 29117 MT -(Current Kerberos master key version is 1)SH -8520 31345 MT -(Master key entered. BEWARE!)SH -8520 32459 MT -(Previous or default values are in [brackets] ,)SH -8520 33573 MT -(enter return to leave the same, or new value.)SH -8520 35801 MT -(Principal name:)SH -/Times-Bold SF -19080 XM -(wave)SH -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter the username.)SH -/Courier SF -8520 36915 MT -(Instance:)SH -/Times-BoldItalic SF -28800 XM -(<-- Enter a null instance.)SH -/Courier SF -8520 39143 MT -(, Create [y] ?)SH -/Times-Bold SF -25680 XM -(y)SH -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(The user-instance does not exist.)SH -30450 40257 MT -(Enter y to create the user-instance.)SH -/Courier SF -8520 41371 MT -(Principal: wave Instance: m_key_v: 1)SH -8520 42485 MT -(New Password:)SH -/Times-BoldItalic SF -28800 XM -(<-- Enter the user-instance's password.)SH -/Courier SF -8520 43599 MT -(Verifying, please re-enter)SH -8520 44713 MT -(New Password:)SH -8520 45827 MT -(Principal's new key version = 1)SH -8520 46941 MT -(Expiration date \050enter dd-mm-yy\051 [ 12/31/99 ] ?)SH -/Times-Bold SF -39600 XM -(<--)SH -/Times-BoldItalic SF -41619 XM -(Enter newlines)SH -/Courier SF -8520 48055 MT -(Max ticket lifetime \050*5 minutes\051 [ 255 ] ?)SH -/Times-Bold SF -39600 XM -(<--)SH -/Times-BoldItalic SF -41619 XM -(to get the)SH -/Courier SF -8520 49169 MT -(Attributes [ 0 ] ?)SH -/Times-Bold SF -30120 XM -(<--)SH -/Times-BoldItalic SF -32139 XM -(default values.)SH -/Courier SF -8520 50283 MT -(Edit O.K.)SH -8520 52511 MT -(Principal name:)SH -/Times-BoldItalic SF -28800 XM -(<-- Enter a newline to exit the program.)SH -/Times-Roman SF -7200 54809 MT -(Use the)SH -/Times-Italic SF -10804 XM -(kdb_edit)SH -/Times-Roman SF -14867 XM -(utility to add your username to the master database.)SH -14 /Times-Bold AF -7200 58627 MT -(2.4 Starting) -350 W( the Kerberos Server)SH -11 /Times-Roman AF -7200 60822 MT -(Change directories to the directory in which you have installed the server program)SH -/Times-Italic SF -43701 XM -(kerberos)SH -/Times-Roman SF -47824 XM -(\050the default)SH -7200 62018 MT -(directory is)SH -/Times-Italic SF -12454 XM -(/usr/etc)SH -/Times-Roman SF -(\051, and start the program as a background process:)SH -/Courier SF -8520 63595 MT -(host#)SH -/Times-Bold SF -12480 XM -(./kerberos &)SH -/Times-Roman SF -7200 65190 MT -(If you have used the)SH -/Times-Italic SF -16393 XM -(kstash)SH -/Times-Roman SF -19418 XM -(command to store the master database password, the server will start)SH -7200 66386 MT -(automatically. If) -275 W( you did not use)SH -/Times-Italic SF -22048 XM -(kstash)SH -/Times-Roman SF -(, use the following command:)SH -/Courier SF -8520 67963 MT -(host#)SH -/Times-Bold SF -12480 XM -(./kerberos -m)SH -10 /Times-Roman AF -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(4)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 5 6 -BS -0 SI -11 /Times-Roman AF -7200 7955 MT -(The server will prompt you to enter the master password before actually starting itself.)SH -14 /Times-Bold AF -7200 11773 MT -(2.5 Testing) -350 W( the Kerberos Server)SH -11 /Times-Roman AF -7200 13968 MT -(Exit the root account and use the)SH -/Times-Italic SF -21893 XM -(kinit)SH -/Times-Roman SF -24124 XM -(command obtain a Kerberos ticket-granting ticket. This command)SH -7200 15164 MT -(creates your ticket file and stores the ticket-granting ticket in it.)SH -7200 17462 MT -(If you used the default)SH -/Times-Italic SF -17371 XM -(make install)SH -/Times-Roman SF -22993 XM -(command and directories to install the Kerberos user utilities,)SH -/Times-Italic SF -50365 XM -(kinit)SH -/Times-Roman SF -7200 18658 MT -(will be in the)SH -/Times-Italic SF -13250 XM -(/usr/athena)SH -/Times-Roman SF -18537 XM -(directory. From now on, we'll refer to the Kerberos user commands directory as)SH -7200 19854 MT -([K_USER].)SH -7200 22152 MT -(Use)SH -/Times-Italic SF -9185 XM -(kinit)SH -/Times-Roman SF -11416 XM -(as follows:)SH -/Courier SF -8520 23729 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/kinit)SH -/Courier SF -8520 24843 MT -(MIT Project Athena, \050ariadne\051)SH -8520 25957 MT -(Kerberos Initialization)SH -8520 27071 MT -(Kerberos name:)SH -/Times-BoldItalic SF -18420 XM -(yourusername)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter your Kerberos username.)SH -/Courier SF -8520 28185 MT -(Password:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter your Kerberos password.)SH -/Times-Roman SF -7200 30483 MT -(Use the)SH -/Times-Italic SF -10804 XM -(klist)SH -/Times-Roman SF -12913 XM -(program to list the contents of your ticket file.)SH -/Courier SF -8520 32060 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/klist)SH -/Times-Roman SF -7200 33655 MT -(The command should display something like the following:)SH -/Courier SF -8520 35181 MT -(Ticket file:) -SH( /tmp/tkt5555)1980 W -8520 36295 MT -(Principal: yourusername@REALMNAME)3300 W -9840 38523 MT -(Issued Expires) -6600 W( Principal)5940 W -8520 39637 MT -(May 6) -660 W( 10:15:23 May 6 18:15:23 krbtgt.REALMNAME@REALMNAME)SH -/Times-Roman SF -7200 41935 MT -(If you have any problems, you can examine the log file)SH -/Times-Italic SF -31758 XM -(/kerberos/kerberos.log)SH -/Times-Roman SF -42022 XM -(on the Kerberos server)SH -7200 43131 MT -(machine to see if there was some sort of error.)SH -16 /Times-Bold AF -7200 47803 MT -(3. Setting) -400 W( up and testing the Administration server)SH -11 /Times-Roman AF -7200 49998 MT -(The procedure for setting up and testing the Kerberos administration server is as follows:)SH -9400 51949 MT -(1.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kdb_edit)SH -/Times-Roman SF -18167 XM -(utility to add your username with an administration instance to the master)SH -10500 53145 MT -(database.)SH -9400 55039 MT -(2.)SH -10500 XM -(Edit the access control lists for the administration server)SH -9400 56933 MT -(3.)SH -10500 XM -(Start the Kerberos administration server.)SH -9400 58827 MT -(4.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kpasswd)SH -/Times-Roman SF -18107 XM -(command to change your password.)SH -9400 60721 MT -(5.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kadmin)SH -/Times-Roman SF -17617 XM -(command to add new entries to the database.)SH -9400 62615 MT -(6.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(kinit)SH -/Times-Roman SF -16335 XM -(command to verify that the)SH -/Times-Italic SF -28524 XM -(kadmin)SH -/Times-Roman SF -32037 XM -(command correctly added new entries to)SH -10500 63811 MT -(the database.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(5)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 6 7 -BS -0 SI -14 /Times-Bold AF -7200 8138 MT -(3.1 Adding) -350 W( an administration instance for the administrator)SH -11 /Times-Roman AF -7200 10333 MT -(Login to the Kerberos master server machine, and use the)SH -/Times-Bold SF -32825 XM -(su)SH -/Times-Roman SF -34140 XM -(command to become root. Use the)SH -/Times-Italic SF -49780 XM -(kdb_edit)SH -/Times-Roman SF -7200 11529 MT -(program to create an entry for each administrator with the instance ``)SH -/Times-BoldItalic SF -(admin)SH -/Times-Roman SF -(''.)SH -/Courier SF -8520 13106 MT -(host#)SH -/Times-Bold SF -12480 XM -([ADMIN_DIR]/kdb_edit)SH -/Courier SF -8520 15334 MT -(Opening database...)SH -8520 17562 MT -(Enter Kerberos master key:)SH -8520 18676 MT -(Verifying, please re-enter)SH -8520 19790 MT -(Enter Kerberos master key:)SH -8520 20904 MT -(Current Kerberos master key version is 1)SH -8520 23132 MT -(Master key entered. BEWARE!)SH -8520 24246 MT -(Previous or default values are in [brackets] ,)SH -8520 25360 MT -(enter return to leave the same, or new value.)SH -8520 27588 MT -(Principal name:)SH -/Times-Bold SF -19080 XM -(wave)SH -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter the username.)SH -/Courier SF -8520 28702 MT -(Instance:)SH -/Times-Bold SF -(admin)SH -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter ``admin''.)SH -/Courier SF -8520 30930 MT -(, Create [y] ?)SH -/Times-Bold SF -25680 XM -(y)SH -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(The user-instance does not exist.)SH -30450 32044 MT -(Enter y to create the user-instance.)SH -/Courier SF -8520 33158 MT -(Principal: wave Instance: admin m_key_v: 1)SH -8520 34272 MT -(New Password:)SH -/Times-BoldItalic SF -28800 XM -(<-- Enter the user-instance's password.)SH -/Courier SF -8520 35386 MT -(Verifying, please re-enter)SH -8520 36500 MT -(New Password:)SH -8520 37614 MT -(Principal's new key version = 1)SH -8520 38728 MT -(Expiration date \050enter dd-mm-yy\051 [ 12/31/99 ] ?)SH -/Times-Bold SF -39600 XM -(<--)SH -/Times-BoldItalic SF -41619 XM -(Enter newlines)SH -/Courier SF -8520 39842 MT -(Max ticket lifetime \050*5 minutes\051 [ 255 ] ?)SH -/Times-Bold SF -39600 XM -(<--)SH -/Times-BoldItalic SF -41619 XM -(to get the)SH -/Courier SF -8520 40956 MT -(Attributes [ 0 ] ?)SH -/Times-Bold SF -30120 XM -(<--)SH -/Times-BoldItalic SF -32139 XM -(default values.)SH -/Courier SF -8520 42070 MT -(Edit O.K.)SH -8520 44298 MT -(Principal name:)SH -/Times-BoldItalic SF -28800 XM -(<-- Enter a newline to exit the program.)SH -14 /Times-Bold AF -7200 48116 MT -(3.2 The) -350 W( Access Control Lists)SH -11 /Times-Roman AF -7200 50311 MT -(The Kerberos administration server uses three access control lists to determine who is authorized to make)SH -7200 51507 MT -(certain requests. The access control lists are stored on the master Kerberos server in the same directory as)SH -7200 52703 MT -(the principal database,)SH -/Times-Italic SF -17340 XM -(/kerberos)SH -/Times-Roman SF -(. The) -275 W( access control lists are simple ASCII text files, with each line)SH -7200 53899 MT -(specifying the name of one principal who is allowed the particular function. To allow several people to)SH -7200 55095 MT -(perform the same function, put their principal names on separate lines in the same file.)SH -7200 57393 MT -(The first list,)SH -/Times-Italic SF -13128 XM -(/kerberos/admin_acl.mod)SH -/Times-Roman SF -(, is a list of principals which are authorized to change entries in the)SH -7200 58589 MT -(database. To) -275 W( allow the administrator `)SH -/Times-Bold SF -(wave)SH -/Times-Roman SF -(' to modify entries in the database for the realm `)SH -/Times-Bold SF -(TIM.EDU)SH -/Times-Roman SF -(',)SH -7200 59785 MT -(you would put the following line into the file)SH -/Times-Italic SF -27275 XM -(/kerberos/admin_acl.mod)SH -/Times-Roman SF -(:)SH -/Courier SF -8520 61311 MT -(wave.admin@TIM.EDU)SH -/Times-Roman SF -7200 63609 MT -(The second list,)SH -/Times-Italic SF -14410 XM -(/kerberos/admin_acl.get)SH -/Times-Roman SF -(, is a list of principals which are authorized to retrieve entries)SH -7200 64805 MT -(from the database.)SH -7200 67103 MT -(The third list,)SH -/Times-Italic SF -13434 XM -(/kerberos/admin_acl.add)SH -/Times-Roman SF -(, is a list of principals which are authorized to add new entries to)SH -7200 68299 MT -(the database.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(6)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 7 8 -BS -0 SI -14 /Times-Bold AF -7200 8138 MT -(3.3 Starting) -350 W( the administration server)SH -11 /Times-Roman AF -7200 10333 MT -(Change directories to the directory in which you have installed the administration server program)SH -/Times-Italic SF -7200 11529 MT -(kadmind)SH -/Times-Roman SF -11263 XM -(\050the default directory is)SH -/Times-Italic SF -21831 XM -(/usr/etc)SH -/Times-Roman SF -(\051, and start the program as a background process:)SH -/Courier SF -8520 13106 MT -(host#)SH -/Times-Bold SF -12480 XM -(./kadmind -n&)SH -/Times-Roman SF -7200 14701 MT -(If you have used the)SH -/Times-Italic SF -16393 XM -(kstash)SH -/Times-Roman SF -19418 XM -(command to store the master database password, the server will start)SH -7200 15897 MT -(automatically. If) -275 W( you did not use)SH -/Times-Italic SF -22048 XM -(kstash)SH -/Times-Roman SF -(, use the following command:)SH -/Courier SF -8520 17474 MT -(host#)SH -/Times-Bold SF -12480 XM -(./kadmind)SH -/Times-Roman SF -7200 19069 MT -(The server will prompt you to enter the master password before actually starting itself; after it starts, you)SH -7200 20265 MT -(should suspend it and put it in the background \050usually this is done by typing control-Z and then)SH -/Times-Bold SF -49792 XM -(bg)SH -/Times-Roman SF -(\051.)SH -14 /Times-Bold AF -7200 24112 MT -(3.4 Testing)350 W -/Times-BoldItalic SF -14434 XM -(kpasswd)SH -11 /Times-Roman AF -7200 26307 MT -(To test the administration server, you should try changing your password with the)SH -/Times-Italic SF -43494 XM -(kpasswd)SH -/Times-Roman SF -47497 XM -(command, and)SH -7200 27503 MT -(you should try adding new users with the)SH -/Times-Italic SF -25592 XM -(kadmin)SH -/Times-Roman SF -29105 XM -(command \050both commands are installed into)SH -/Times-Italic SF -48963 XM -(/usr/athena)SH -/Times-Roman SF -7200 28699 MT -(by default\051.)SH -7200 30997 MT -(Before testing, you should exit the root account.)SH -7200 33295 MT -(To change your password, run the)SH -/Times-Italic SF -22441 XM -(kpasswd)SH -/Times-Roman SF -26444 XM -(command:)SH -/Courier SF -8520 34872 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/kpasswd)SH -/Courier SF -8520 35986 MT -(Old password for wave@TIM.EDU:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -(Enter your password)SH -/Courier SF -8520 37100 MT -(New Password for wave@TIM.EDU:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -(Enter a new password)SH -/Courier SF -8520 38214 MT -(Verifying, please re-enter New Password for wave@TIM.EDU:)SH -/Times-Bold SF -28800 39328 MT -(<--)SH -/Times-BoldItalic SF -(Enter new password again)SH -/Courier SF -8520 40442 MT -(Password changed.)SH -/Times-Roman SF -7200 42037 MT -(Once you have changed your password, use the)SH -/Times-Italic SF -28365 XM -(kinit)SH -/Times-Roman SF -30596 XM -(program as shown above to verify that the password)SH -7200 43233 MT -(was properly changed.)SH -14 /Times-Bold AF -7200 47080 MT -(3.5 Testing)350 W -/Times-BoldItalic SF -14434 XM -(kadmin)SH -11 /Times-Roman AF -7200 49275 MT -(You should also test the function of the)SH -/Times-Italic SF -24798 XM -(kadmin)SH -/Times-Roman SF -28311 XM -(program, by adding a new user \050here named)SH -7200 50471 MT -(``)SH -/Courier SF -(username)SH -/Times-Roman SF -(''\051:)SH -/Courier SF -8520 52048 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/kadmin)SH -/Courier SF -8520 53162 MT -(Welcome to the Kerberos Administration Program, version 2)SH -8520 54276 MT -(Type "help" if you need it.)SH -8520 55390 MT -(admin:)SH -/Times-Bold SF -13800 XM -(ank username)SH -/Times-BoldItalic SF -28800 XM -(`ank' stands for Add New Key)SH -/Courier SF -8520 56504 MT -(Admin password:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -(enter the password)SH -28800 57618 MT -(you chose above for wave.admin)SH -/Courier SF -8520 58732 MT -(Password for username:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -(Enter the user's initial password)SH -/Courier SF -8520 59846 MT -(Verifying, please re-enter Password for username:)SH -/Times-Bold SF -40920 XM -(<--)SH -/Times-BoldItalic SF -(enter it again)SH -/Courier SF -8520 60960 MT -(username added to database.)SH -8520 63188 MT -(admin: quit)660 W -8520 64302 MT -(Cleaning up and exiting.)SH -10 /Times-Roman AF -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(7)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 8 9 -BS -0 SI -14 /Times-Bold AF -7200 8167 MT -(3.6 Verifying) -350 W( with)SH -/Times-BoldItalic SF -18671 XM -(kinit)SH -11 /Times-Roman AF -7200 10362 MT -(Once you've added a new user, you should test to make sure it was added properly by using)SH -/Times-Italic SF -47917 XM -(kinit)SH -/Times-Roman SF -(, and)SH -7200 11558 MT -(trying to get tickets for that user:)SH -/Courier SF -8520 13135 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/kinit username)SH -/Courier SF -8520 14249 MT -(MIT Project Athena \050ariadne\051)SH -8520 15363 MT -(Kerberos Initialization for "username@TIM.EDU")SH -8520 16477 MT -(Password:)SH -/Times-Bold SF -15120 XM -(<--)SH -/Times-BoldItalic SF -(Enter the user's password you used above)SH -/Courier SF -8520 17591 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/klist)SH -/Courier SF -8520 18705 MT -(Ticket file:) -SH( /tmp/tkt_5509_spare1)1980 W -8520 19819 MT -(Principal: username@TIM.MIT.EDU)3300 W -9840 22047 MT -(Issued Expires) -6600 W( Principal)5940 W -8520 23161 MT -(Nov 20 15:58:52 Nov 20 23:58:52 krbtgt.TIM.EDU@TIM.EDU)SH -/Times-Roman SF -7200 25459 MT -(If you have any problems, you can examine the log files)SH -/Times-Italic SF -32186 XM -(/kerberos/kerberos.log)SH -/Times-Roman SF -42450 XM -(and)SH -/Times-Italic SF -7200 26655 MT -(/kerberos/admin_server.syslog)SH -/Times-Roman SF -21008 XM -(on the Kerberos server machine to see if there was some sort of error.)SH -16 /Times-Bold AF -7200 31327 MT -(4. Setting) -400 W( up and testing slave server\050s\051)SH -11 /Times-Roman AF -7200 33522 MT -([Unfortunately, this chapter is not yet ready. Sorry. -ed])SH -16 /Times-Bold AF -7200 38194 MT -(5. A) -400 W( Sample Application)SH -11 /Times-Roman AF -7200 40389 MT -(This release of Kerberos comes with a sample application server and a corresponding client program.)SH -7200 41585 MT -(You will find this software in the [OBJ_DIR])SH -/Times-Italic SF -(/appl/sample)SH -/Times-Roman SF -33170 XM -(directory. The) -275 W( file)SH -/Times-Italic SF -41691 XM -(sample_client)SH -/Times-Roman SF -48076 XM -(contains the)SH -7200 42781 MT -(client program's executable code, the file)SH -/Times-Italic SF -25677 XM -(sample_server)SH -/Times-Roman SF -32366 XM -(contains the server's executable.)SH -7200 45079 MT -(The programs are rudimentary. When they have been installed \050the installation procedure is described in)SH -7200 46275 MT -(detail later\051, they work as follows:)SH -/Symbol SF -9169 48351 MT -(\267)SH -/Times-Roman SF -9950 XM -(The user starts)SH -/Times-Italic SF -16639 XM -(sample_client)SH -/Times-Roman SF -23024 XM -(and provides as arguments to the command the name of the)SH -9950 49547 MT -(server machine and a checksum. For instance:)SH -/Courier SF -11270 51147 MT -(host%)SH -/Times-Bold SF -15230 XM -(sample_client)SH -/Times-BoldItalic SF -22966 XM -(servername 43)385 W -/Symbol SF -9169 53041 MT -(\267)SH -/Times-Italic SF -9950 XM -(Sample_client)SH -/Times-Roman SF -16457 XM -(contacts the server machine and authenticates the user to)SH -/Times-Italic SF -41654 XM -(sample_server)SH -/Times-Roman SF -(.)SH -/Symbol SF -9169 54935 MT -(\267)SH -/Times-Italic SF -9950 XM -(Sample_server)SH -/Times-Roman SF -16761 XM -(authenticates itself to)SH -/Times-Italic SF -26384 XM -(sample_client)SH -/Times-Roman SF -(, then returns a message to the client)SH -9950 56131 MT -(program. This) -275 W( message contains diagnostic information that includes the user's username,)SH -9950 57327 MT -(the Kerberos realm, and the user's workstation address.)SH -/Symbol SF -9169 59221 MT -(\267)SH -/Times-Italic SF -9950 XM -(Sample_client)SH -/Times-Roman SF -16457 XM -(displays the server's message on the user's terminal screen.)SH -14 /Times-Bold AF -7200 63039 MT -(5.1 The) -350 W( Installation Process)SH -11 /Times-Roman AF -7200 65234 MT -(In general, you use the following procedure to install a Kerberos-authenticated server-client system.)SH -9400 67185 MT -(1.)SH -10500 XM -(Add the appropriate entry to the Kerberos database using)SH -/Times-Italic SF -35881 XM -(kdb_edit)SH -/Times-Roman SF -39944 XM -(or)SH -/Times-Italic SF -41135 XM -(kadmin)SH -/Times-Roman SF -44648 XM -(\050described)SH -10500 68381 MT -(below\051.)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(8)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 9 10 -BS -0 SI -11 /Times-Roman AF -9400 7955 MT -(2.)SH -10500 XM -(Create a)SH -/Times-Italic SF -14408 XM -(/etc/srvtab)SH -/Times-Roman SF -19327 XM -(file for the server machine.)SH -9400 9849 MT -(3.)SH -10500 XM -(Install the service program and the)SH -/Times-Italic SF -26016 XM -(/etc/srvtab)SH -/Times-Roman SF -30935 XM -(file on the server machine.)SH -9400 11743 MT -(4.)SH -10500 XM -(Install the client program on the client machine.)SH -9400 13637 MT -(5.)SH -10500 XM -(Update the)SH -/Times-Italic SF -15570 XM -(/etc/services)SH -/Times-Roman SF -21281 XM -(file on the client and server machines.)SH -7200 15935 MT -(We will use the sample application as an example, although the procedure used to install)SH -/Times-Italic SF -46484 XM -(sample_server)SH -/Times-Roman SF -7200 17131 MT -(differs slightly from the general case because the)SH -/Times-Italic SF -29006 XM -(sample_server)SH -/Times-Roman SF -35695 XM -(takes requests via the)SH -/Times-Italic SF -45347 XM -(inetd)SH -/Times-Roman SF -47822 XM -(program.)SH -/Times-Italic SF -7200 18327 MT -(Inetd)SH -/Times-Roman SF -9735 XM -(starts)SH -/Times-Italic SF -12332 XM -(sample_server)SH -/Times-Roman SF -19021 XM -(each time a client process contacts the server machine.)SH -/Times-Italic SF -43606 XM -(Sample_server)SH -/Times-Roman SF -7200 19523 MT -(processes the request, terminiates, then is restarted when)SH -/Times-Italic SF -32368 XM -(inetd)SH -/Times-Roman SF -34843 XM -(receives another)SH -/Times-Italic SF -42293 XM -(sample_client)SH -/Times-Roman SF -48678 XM -(request.)SH -7200 20719 MT -(When you install the program on the server, you must add a)SH -/Times-Italic SF -33807 XM -(sample)SH -/Times-Roman SF -37198 XM -(entry to the server machine's)SH -/Times-Italic SF -7200 21915 MT -(/etc/inetd.conf)SH -/Times-Roman SF -13738 XM -(file.)SH -7200 24213 MT -(The following description assumes that you are installing)SH -/Times-Italic SF -32680 XM -(sample_server)SH -/Times-Roman SF -39369 XM -(on the machine)SH -/Times-Italic SF -46364 XM -(ariadne.tim.edu)SH -/Times-Roman SF -(.)SH -7200 25409 MT -(Here's the process, step by step:)SH -9400 27360 MT -(1.)SH -10500 XM -(Login as or)SH -/Times-Italic SF -15785 XM -(su)SH -/Times-Roman SF -17038 XM -(to root on the Kerberos server machine. Use the)SH -/Times-Italic SF -38631 XM -(kdb_edit)SH -/Times-Roman SF -42694 XM -(or)SH -/Times-Italic SF -43885 XM -(kadmin)SH -/Times-Roman SF -47398 XM -(program)SH -10500 28556 MT -(to create an entry for)SH -/Times-Italic SF -19935 XM -(sample)SH -/Times-Roman SF -23326 XM -(in the Kerberos database:)SH -/Courier SF -11820 30133 MT -(host#)SH -/Times-Bold SF -15780 XM -([ADMIN_DIR]/kdb_edit)SH -/Courier SF -11820 32361 MT -(Opening database...)SH -11820 34589 MT -(Enter Kerberos master key:)SH -11820 35703 MT -(Verifying, please re-enter)SH -11820 36817 MT -(master key entered. BEWARE!)SH -11820 37931 MT -(Previous or default values are in [brackets] ,)SH -11820 39045 MT -(enter return to leave the same, or new value.)SH -11820 41273 MT -(Principal name:)SH -/Times-Bold SF -22380 XM -(sample)SH -26220 XM -(<--)SH -/Times-BoldItalic SF -28239 XM -(Enter the principal name.)SH -/Courier SF -11820 42387 MT -(Instance:)SH -/Times-Bold SF -18420 XM -(ariadne)SH -26220 XM -(<--)SH -/Times-BoldItalic SF -28239 XM -(Instances cannot have periods in them.)SH -/Courier SF -11820 44615 MT -(, Create [y] ?)SH -/Times-Bold SF -28980 XM -(y)SH -/Courier SF -11820 46843 MT -(Principal: sample_server Instance: ariadne m_key_v: 1)SH -11820 47957 MT -(New Password:)SH -/Times-Bold SF -26220 XM -(<--)SH -/Times-BoldItalic SF -28239 XM -(Enter ``RANDOM'' to get random password.)SH -/Courier SF -11820 49071 MT -(Verifying, please re-enter)SH -11820 50185 MT -(New Password:)SH -/Times-Bold SF -26220 XM -(<--)SH -/Times-BoldItalic SF -28239 XM -(Enter ``RANDOM'' again.)SH -/Courier SF -11820 51299 MT -(Random password [y] ?)SH -/Times-Bold SF -26340 XM -(y)SH -/Courier SF -11820 53527 MT -(Principal's new key version = 1)SH -11820 54641 MT -(Expiration date \050enter dd-mm-yy\051 [ 12/31/99 ] ?)SH -11820 55755 MT -(Max ticket lifetime \050*5 minutes\051 [ 255 ] ?)SH -11820 56869 MT -(Attributes [ 0 ] ?)SH -11820 57983 MT -(Edit O.K.)SH -11820 60211 MT -(Principal name:)SH -/Times-Bold SF -26220 XM -(<--)SH -/Times-BoldItalic SF -28239 XM -(Enter newline to exit kdb_edit.)SH -/Times-Roman SF -9400 62105 MT -(2.)SH -10500 XM -(Use the)SH -/Times-Italic SF -14104 XM -(ext_srvtab)SH -/Times-Roman SF -18961 XM -(program to create a)SH -/Times-Italic SF -27755 XM -(srvtab)SH -/Times-Roman SF -30780 XM -(file for)SH -/Times-Italic SF -34078 XM -(sample_server)SH -/Times-Roman SF -('s host machine:)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30350 XM -(9)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 10 11 -BS -0 SI -11 /Courier AF -11820 7937 MT -(host#)SH -/Times-Bold SF -15780 XM -([ADMIN_DIR]/ext_srvtab ariadne)275 W -/Courier SF -11820 10165 MT -(Enter Kerberos master key:)SH -11820 11279 MT -(Current Kerberos master key version is 1.)SH -11820 13507 MT -(Generating 'ariadne-new-srvtab'....)SH -/Times-Roman SF -10500 15102 MT -(Transfer the)SH -/Times-Italic SF -16118 XM -(ariadne-new-srvtab)SH -/Times-Roman SF -25069 XM -(file to)SH -/Times-Italic SF -27941 XM -(ariadne)SH -/Times-Roman SF -31638 XM -(and install it as)SH -/Times-Italic SF -38544 XM -(/etc/srvtab)SH -/Times-Roman SF -(. Note) -275 W( that this)SH -10500 16298 MT -(file is equivalent to the service's password and should be treated with care. For example, it)SH -10500 17494 MT -(could be transferred by removable media, but should not be sent over an open network in)SH -10500 18690 MT -(the clear. Once installed, this file should be readable only by root.)SH -9400 20584 MT -(3.)SH -10500 XM -(Add the following line to the)SH -/Times-Italic SF -23516 XM -(/etc/services)SH -/Times-Roman SF -29227 XM -(file on)SH -/Times-Italic SF -32343 XM -(ariadne)SH -/Times-Roman SF -(, and on all machines that will run)SH -10500 21780 MT -(the)SH -/Times-Italic SF -12119 XM -(sample_client)SH -/Times-Roman SF -18504 XM -(program:)SH -/Courier SF -11820 23306 MT -(sample 906/tcp) -2640 W( #) -3960 W( Kerberos sample app server)SH -/Times-Roman SF -9400 25200 MT -(4.)SH -10500 XM -(Add a line similar to the following line to the)SH -/Times-Italic SF -30666 XM -(/etc/inetd.conf)SH -/Times-Roman SF -37204 XM -(file on)SH -/Times-Italic SF -40320 XM -(sample_server)SH -/Times-Roman SF -('s)SH -10500 26396 MT -(machine:)SH -/Courier SF -11820 27922 MT -(sample stream tcp nowait switched root)1320 W -14460 29036 MT -([PATH]/sample_server sample_server)SH -/Times-Roman SF -10500 30631 MT -(where [PATH] should be substituted with the path to the)SH -/Times-Italic SF -35674 XM -(sample_server)SH -/Times-Roman SF -42363 XM -(program. \050This)275 W -/Times-Italic SF -10500 31827 MT -(inetd.conf)SH -/Times-Roman SF -15144 XM -(information should be placed on one line.\051 You should examine existing lines in)SH -/Times-Italic SF -10500 33023 MT -(/etc/inetd.conf)SH -/Times-Roman SF -17038 XM -(and use the same format used by other entries \050e.g. for telnet\051. Most systems)SH -10500 34219 MT -(do not have a column for the `switched' keyword, and some do not have a column for the)SH -10500 35415 MT -(username \050usually `root', as above\051.)SH -9400 37309 MT -(5.)SH -10500 XM -(Restart)SH -/Times-Italic SF -13891 XM -(inetd)SH -/Times-Roman SF -16366 XM -(by sending the current)SH -/Times-Italic SF -26446 XM -(inetd)SH -/Times-Roman SF -28921 XM -(process a hangup signal:)SH -/Courier SF -11820 38909 MT -(host#)SH -/Times-Bold SF -15780 XM -(kill -HUP)275 W -/Times-BoldItalic SF -21373 XM -(process_id_number)SH -/Times-Roman SF -9400 40803 MT -(6.)SH -10500 XM -(The)SH -/Times-Italic SF -12485 XM -(sample_server)SH -/Times-Roman SF -19174 XM -(is now ready to take)SH -/Times-Italic SF -28307 XM -(sample_client)SH -/Times-Roman SF -34692 XM -(requests.)SH -14 /Times-Bold AF -7200 44621 MT -(5.2 Testing) -350 W( the Sample Server)SH -11 /Times-Roman AF -7200 46816 MT -(Assume that you have installed)SH -/Times-Italic SF -21223 XM -(sample_server)SH -/Times-Roman SF -27912 XM -(on)SH -/Times-Italic SF -29287 XM -(ariadne)SH -/Times-Roman SF -(.)SH -7200 49114 MT -(Login to your workstation and use the)SH -/Times-Italic SF -24217 XM -(kinit)SH -/Times-Roman SF -26448 XM -(command to obtain a Kerberos ticket-granting ticket:)SH -/Courier SF -8520 50691 MT -(host%)SH -/Times-Bold SF -12480 XM -([K_USER]/kinit)SH -/Courier SF -8520 51805 MT -(MIT Project Athena, \050your_workstation\051)SH -8520 52919 MT -(Kerberos Initialization)SH -8520 54033 MT -(Kerberos name:)SH -/Times-BoldItalic SF -18420 XM -(yourusername)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter your Kerberos username.)SH -/Courier SF -8520 55147 MT -(Password:)SH -/Times-Bold SF -28800 XM -(<--)SH -/Times-BoldItalic SF -30819 XM -(Enter your Kerberos password.)SH -/Times-Roman SF -7200 57445 MT -(Now use the)SH -/Times-Italic SF -12973 XM -(sample_client)SH -/Times-Roman SF -19358 XM -(program as follows:)SH -/Courier SF -8520 59022 MT -(host%)SH -/Times-Bold SF -12480 XM -([PATH]/sample_client ariadne)275 W -/Times-Roman SF -7200 60617 MT -(The command should display something like the following:)SH -/Courier SF -8520 62143 MT -(The server says:)SH -8520 63257 MT -(You are)SH -/Times-BoldItalic SF -13800 XM -(yourusername)SH -/Courier SF -(.@REALMNAME \050local name)SH -/Times-BoldItalic SF -36180 XM -(yourusername)SH -/Courier SF -(\051,)SH -9180 64371 MT -(at address)SH -/Times-BoldItalic SF -16440 XM -(yournetaddress)SH -/Courier SF -(, version VERSION9, cksum 997)SH -10 /Times-Roman AF -7200 75600 MT -(MIT Project Athena)SH -30100 XM -(10)SH -47890 XM -(4 January 1990)SH -ES -%%Page: 11 12 -BS -0 SI -16 /Times-Bold AF -7200 8272 MT -(6. Service) -400 W( names and other services)SH -14 SS -7200 12090 MT -(6.1 rlogin,) -350 W( rsh, rcp, tftp, and others)SH -11 /Times-Roman AF -7200 14285 MT -(Many services use a common principal name for authentication purposes.)SH -/Times-Italic SF -40128 XM -(rlogin)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -43368 XM -(rsh)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -45324 XM -(rcp)SH -/Times-Roman SF -(,)SH -/Times-Italic SF -47340 XM -(tftp)SH -/Times-Roman SF -49083 XM -(and others)SH -7200 15481 MT -(use the principal name ``)SH -/Courier SF -(rcmd)SH -/Times-Roman SF -(''. For) -275 W( example, to set up the machine)SH -/Times-Italic SF -38033 XM -(ariadne)SH -/Times-Roman SF -41730 XM -(to support Kerberos rlogin,)SH -7200 16677 MT -(it needs to have a service key for principal ``)SH -/Courier SF -(rcmd)SH -/Times-Roman SF -('', instance ``)SH -/Courier SF -(ariadne)SH -/Times-Roman SF -(''. You) -275 W( create this key in the)SH -7200 17873 MT -(same way as shown above for the sample service.)SH -7200 20171 MT -(After creating this key, you need to run the)SH -/Times-Italic SF -26382 XM -(ext_srvtab)SH -/Times-Roman SF -31239 XM -(program again to generate a new srvtab file for)SH -7200 21367 MT -(ariadne.)SH -14 /Times-Bold AF -7200 25185 MT -(6.2 NFS) -350 W( modifications)SH -11 /Times-Roman AF -7200 27380 MT -(The NFS modifications distributed separately use the service name ``)SH -/Courier SF -(rvdsrv)SH -/Times-Roman SF -('' with the instance set to)SH -7200 28576 MT -(the machine name \050as for the sample server and the rlogin, rsh, rcp and tftp services\051.)SH -14 /Times-Bold AF -7200 32394 MT -(6.3 inetd.conf) -350 W( entries)SH -11 /Times-Roman AF -7200 34589 MT -(The following are the)SH -/Times-Italic SF -16974 XM -(/etc/inetd.conf)SH -/Times-Roman SF -23512 XM -(entries necessary to support rlogin, encrypted rlogin, rsh, and rcp)SH -7200 35785 MT -(services on a server machine. As above, your)SH -/Times-Italic SF -27631 XM -(inetd.conf)SH -/Times-Roman SF -32275 XM -(may not support all the fields shown here.)SH -/Courier SF -8520 37311 MT -(eklogin stream) -660 W( tcp nowait unswitched root)1320 W -11160 38425 MT -([PATH]/klogind eklogind)1320 W -8520 39539 MT -(kshell stream tcp nowait unswitched root)1320 W -11160 40653 MT -([PATH]/kshd kshd)1320 W -8520 41767 MT -(klogin stream tcp nowait unswitched root)1320 W -11160 42881 MT -([PATH]/klogind klogind)1320 W -10 /Times-Roman AF -7200 75600 MT -(MIT Project Athena)SH -30100 XM -(11)SH -47890 XM -(4 January 1990)SH -ES -%%Page: i 13 -BS -0 SI -14 /Times-Bold AF -25272 8138 MT -(Table of Contents)SH -13 SS -7200 9781 MT -(1. How) -325 W( Kerberos Works: A Schematic Description)SH -53350 XM -(1)SH -12 /Times-Roman AF -9000 11130 MT -(1.1 Network) -300 W( Services and Their Client Programs)SH -53400 XM -(1)SH -9000 12479 MT -(1.2 Kerberos) -300 W( Tickets)SH -53400 XM -(1)SH -9000 13828 MT -(1.3 The) -300 W( Kerberos Master Database)SH -53400 XM -(1)SH -9000 15177 MT -(1.4 The) -300 W( Ticket-Granting Ticket)SH -53400 XM -(1)SH -9000 16526 MT -(1.5 Network) -300 W( Services and the Master Database)SH -53400 XM -(1)SH -9000 17875 MT -(1.6 The) -300 W( User-Kerberos Interaction)SH -53400 XM -(2)SH -13 /Times-Bold AF -7200 19518 MT -(2. Setting) -325 W( Up and Testing the Kerberos Server)SH -53350 XM -(2)SH -12 /Times-Roman AF -9000 20867 MT -(2.1 Creating) -300 W( and Initializing the Master Database)SH -53400 XM -(3)SH -9000 22216 MT -(2.2 Storing) -300 W( the Master Password)SH -53400 XM -(3)SH -9000 23571 MT -(2.3 Using)300 W -/Times-BoldItalic SF -14267 XM -(kdb_edit)SH -/Times-Roman SF -18768 XM -(to Add Users to the Master Database)SH -53400 XM -(4)SH -9000 24920 MT -(2.4 Starting) -300 W( the Kerberos Server)SH -53400 XM -(4)SH -9000 26269 MT -(2.5 Testing) -300 W( the Kerberos Server)SH -53400 XM -(5)SH -13 /Times-Bold AF -7200 27912 MT -(3. Setting) -325 W( up and testing the Administration server)SH -53350 XM -(5)SH -12 /Times-Roman AF -9000 29261 MT -(3.1 Adding) -300 W( an administration instance for the administrator)SH -53400 XM -(6)SH -9000 30610 MT -(3.2 The) -300 W( Access Control Lists)SH -53400 XM -(6)SH -9000 31959 MT -(3.3 Starting) -300 W( the administration server)SH -53400 XM -(7)SH -9000 33314 MT -(3.4 Testing)300 W -/Times-BoldItalic SF -15001 XM -(kpasswd)SH -/Times-Roman SF -53400 XM -(7)SH -9000 34669 MT -(3.5 Testing)300 W -/Times-BoldItalic SF -15001 XM -(kadmin)SH -/Times-Roman SF -53400 XM -(7)SH -9000 36024 MT -(3.6 Verifying) -300 W( with)SH -/Times-BoldItalic SF -18501 XM -(kinit)SH -/Times-Roman SF -53400 XM -(8)SH -13 /Times-Bold AF -7200 37667 MT -(4. Setting) -325 W( up and testing slave server\050s\051)SH -53350 XM -(8)SH -7200 39310 MT -(5. A) -325 W( Sample Application)SH -53350 XM -(8)SH -12 /Times-Roman AF -9000 40659 MT -(5.1 The) -300 W( Installation Process)SH -53400 XM -(8)SH -9000 42008 MT -(5.2 Testing) -300 W( the Sample Server)SH -52800 XM -(10)SH -13 /Times-Bold AF -7200 43651 MT -(6. Service) -325 W( names and other services)SH -52700 XM -(11)SH -12 /Times-Roman AF -9000 45000 MT -(6.1 rlogin,) -300 W( rsh, rcp, tftp, and others)SH -52800 XM -(11)SH -9000 46349 MT -(6.2 NFS) -300 W( modifications)SH -52800 XM -(11)SH -9000 47698 MT -(6.3 inetd.conf) -300 W( entries)SH -52800 XM -(11)SH -10 SS -7200 75600 MT -(MIT Project Athena)SH -30461 XM -(i)SH -47890 XM -(4 January 1990)SH -ES -%%Trailer -%%Pages: 13 -%%DocumentFonts: Times-Roman Times-Bold Times-Italic Times-BoldItalic Courier Symbol diff --git a/doc/old-V4-docs/operation.mss b/doc/old-V4-docs/operation.mss deleted file mode 100644 index a35bb9f95..000000000 --- a/doc/old-V4-docs/operation.mss +++ /dev/null @@ -1,799 +0,0 @@ -@Comment[ $Source$] -@Comment[ $Author$] -@Comment[ $Id$] -@Comment[] -@device[postscript] -@make[report] -@comment[ -@DefineFont(HeadingFont, - P=, - B=, - I=, - R=) -] -@DefineFont(HeadingFont, - P=, - B=, - I=, - R=) -@Counter(MajorPart,TitleEnv HD0,ContentsEnv tc0,Numbered [@I], - IncrementedBy Use,Announced) -@Counter(Chapter,TitleEnv HD1,ContentsEnv tc1,Numbered [@1. ], - IncrementedBy Use,Referenced [@1],Announced) -@Counter(Appendix,TitleEnv HD1,ContentsEnv tc1,Numbered [@A. ], - IncrementedBy,Referenced [@A],Announced,Alias Chapter) -@Counter(UnNumbered,TitleEnv HD1,ContentsEnv tc1,Announced,Alias - Chapter) -@Counter(Section,Within Chapter,TitleEnv HD2,ContentsEnv tc2, - Numbered [@#@:.@1 ],Referenced [@#@:.@1],IncrementedBy - Use,Announced) -@Counter(AppendixSection,Within Appendix,TitleEnv HD2, - ContentsEnv tc2, - Numbered [@#@:.@1 ],Referenced [@#@:.@1],IncrementedBy - Use,Announced) -@Counter(SubSection,Within Section,TitleEnv HD3,ContentsEnv tc3, - Numbered [@#@:.@1 ],IncrementedBy Use, - Referenced [@#@:.@1 ]) -@Counter(AppendixSubSection,Within AppendixSection,TitleEnv HD3, - ContentsEnv tc3, - Numbered [@#@:.@1 ],IncrementedBy Use, - Referenced [@#@:.@1 ]) -@Counter(Paragraph,Within SubSection,TitleEnv HD4,ContentsEnv tc4, - Numbered [@#@:.@1 ],Referenced [@#@:.@1], - IncrementedBy Use) -@modify(CopyrightNotice, Fixed -1 inch, Flushright) -@Modify(Titlebox, Fixed 3.0 inches) -@Modify(hd1, below .2 inch, facecode B, size 16, spaces kept, pagebreak off) -@Modify(hd2, below .2 inch, facecode B, size 14, spaces kept) -@Modify(hd3, below .2 inch, facecode B, size 12, spaces kept) -@Modify(Description, Leftmargin +20, Indent -20,below 1 line, above 1 line) -@Modify(Tc1, Above .5, Facecode B) -@Modify(Tc2, Above .25, Below .25, Facecode R) -@Modify(Tc3,Facecode R) -@Modify(Tc4,Facecode R) -@Modify(Itemize,Above 1line,Below 1line) -@Modify(Insert,LeftMargin +2, RightMargin +2) -@libraryfile[stable] -@comment[@Style(Font NewCenturySchoolBook, size 11)] -@Style(Font TimesRoman, size 11) -@Style(Spacing 1.1, indent 0) -@Style(leftmargin 1.0inch) -@Style(justification no) -@Style(BottomMargin 1.5inch) -@Style(ChangeBarLocation Right) -@Style(ChangeBars=off) -@pageheading[immediate] -@pagefooting[immediate, left = "MIT Project Athena", center = "@value(page)", -right = "@value(date)"] -@set[page = 0] -@blankspace[.5 inches] -@begin[group, size 20] -@begin(center) -@b[Kerberos Operation Notes] -@b[DRAFT] -@end[center] -@blankspace[.5 inches] -@end(group) -@begin[group, size 16] -@begin(center) -Bill Bryant -John Kohl -Project Athena, MIT -@blankspace[.5 inches] -@b[Initial Release, January 24, 1989] -@i[(plus later patches through patchlevel 7)] -@end[center] -@end(group) -@begin[group, size 10] -@end[group] -@blankspace[1inches] - -These notes assume that you have used the -@i[Kerberos Installation Notes] to build and install your -Kerberos system. -As in that document, we refer to the directory that contains -the built Kerberos binaries as [OBJ_DIR]. - -This document assumes that you are a Unix system manager. - -@newpage() -@chapter[How Kerberos Works: A Schematic Description] - -This section provides a simplified description of -a general user's interaction with the Kerberos system. -This interaction happens transparently--users don't need to know -and probably don't care about what's going on--but Kerberos administrators -might find a schematic description of the process useful. -The description glosses over a lot of details; -for more information, see @i[Kerberos: An Authentication -Service for Open Network Systems], -a paper presented at Winter USENIX 1988, in Dallas, Texas. - -@section[Network Services and Their Client Programs] - -In an environment that provides network services, -you use @i[client] programs to request service from -@i[server] programs that are somewhere on the network. -Suppose you have logged in to a workstation -and you want to @i[rlogin] to another machine. -You use the local @i[rlogin] client program to -contact the remote machine's @i[rlogin] service daemon. - -@section[Kerberos Tickets] - -Under Kerberos, the @i[rlogin] service program -allows a client to login to a remote machine if it -can provide -a Kerberos @b[ticket] for the request. -This ticket proves the identity of the person who has used -the client program to access the server program. - -@section[The Kerberos Master Database] - -Kerberos will give you tickets only if you -have an entry in the Kerberos server's -@b[master database]. -Your database entry includes your Kerberos username (often referred to -as your Kerberos @b[principal] name), and your Kerberos password. -Every Kerberos user must have an entry in this database. - -@section[The Ticket-Granting Ticket] - -The @i[kinit] command prompts for your Kerberos username and password, -and if you enter them successfully, you will obtain a Kerberos -@i[ticket-granting ticket]. -As illustrated below, -client programs use this ticket to get other Kerberos tickets as -needed. - -@section[Network Services and the Master Database] - -The master database also contains entries for all network services that -require Kerberos authentication. -Suppose for instance that your site has a machine @i[laughter] -that requires Kerberos authentication from anyone who wants -to @i[rlogin] to it. -This service must be registered in the master database. -Its entry includes the service's principal name, and its @b[instance]. - -The @i[instance] is the name of the service's machine; -in this case, the service's instance is the name @i[laughter]. -The instance provides a means for Kerberos to distinguish between -machines that provide the same service. -Your site is likely to have more than one machine that -provides @i[rlogin] service. - -@section[The User-Kerberos Interaction] - -Suppose that you (in the guise of a general user) walk up to a workstation -intending to login to it, and then @i[rlogin] to the machine @i[laughter]. -Here's what happens. -@begin[enumerate] -You login to the workstation and use the @i[kinit] command -to to get a ticket-granting ticket. -This command prompts you for your username (your Kerberos Principal Name), -and your Kerberos password [on some systems which use the new version of -@i{/bin/login}, this may be done as part of the login process, not -requiring the user to run a separate program]. -@begin[enumerate] -The @i[kinit] command sends your request to the Kerberos master server -machine. -The server software looks for your principal name's entry in the -Kerberos @b[master database]. - -If this entry exists, the -Kerberos server creates and returns a -@i[ticket-granting ticket], encrypted in your password. -If @i[kinit] can decrypt the Kerberos reply using the password you -provide, it stores this ticket in a @b[ticket file] on your -local machine for later use. -The ticket file to be used -can be specified in the @b[KRBTKFILE] environment -variable. If this variable is not set, the name of the file will be -@i[/tmp/tkt@p(uid)], where @p(uid) is the UNIX user-id, represented in decimal. -@end[enumerate] - -Now you use the @i[rlogin] client to try to access the machine @i[laughter]. -@begin[example] -host% @b[rlogin laughter] -@end[example] -@begin[enumerate] -The @i[rlogin] client checks your ticket file to see if you -have a ticket for @i[laughter]'s @i[rcmd] service (the rlogin program -uses the @i[rcmd] service name, mostly for historical reasons). -You don't, so @i[rlogin] uses the ticket file's @i[ticket-granting -ticket] to make a request to the master server's ticket-granting service. - -This ticket-granting service receives the @i[rcmd-laughter] request -and looks in the master database for an @i[rcmd-laughter] entry. -If that entry exists, the ticket-granting service issues you a ticket -for that service. -That ticket is also cached in your ticket file. - -The @i[rlogin] client now uses that ticket to request service from -the @i[laughter] @i[rlogin] service program. -The service program -lets you @i[rlogin] if the ticket is valid. -@end[enumerate] -@end[enumerate] - -@chapter[Setting Up and Testing the Kerberos Server] - -The procedure for setting up and testing a Kerberos server -is as follows: -@begin[enumerate] -Use the @i[kdb_init] command to create and initialize the master database. - -Use the @i[kdb_edit] utility to add your username to the -master database. - -Start the Kerberos server. - -Use the @i[kinit] command to obtain a Kerberos ticket-granting ticket. - -Use the @i[klist] command to verify that the @i[kinit] command -authenticated you successfully. -@end[enumerate] - -@section[Creating and Initializing the Master Database] - -Login to the Kerberos master server machine, -and use the @b[su] command to become root. -If you installed the Kerberos administration tools -with the @i[make install] command and the default pathnames, -they should be in the @i[/usr/etc] directory. -If you installed the tools in a different directory, -hopefully you know what it is. -From now on, we will refer to this directory as [ADMIN_DIR]. - -The @i[kdb_init] command creates and initializes the master database. -It asks you to enter the system's -realm name and the database's master password. -Do not forget this password. -If you do, the database becomes useless. -(Your realm name should be substituted for [REALMNAME] below.) - -Use @i[kdb_init] as follows: -@tabset[3inches, +1.5inches] -@begin[example, rightmargin -10] -host# @b([ADMIN_DIR]/kdb_init) -Realm name (default XXX): @b([REALMNAME])@\@b[<--] @p[Enter your system's realm name.] -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password. - -Enter Kerberos master key: @\@b[<--] @p[Enter the master password.] -@comment(this needs to be re-fixed...: -Verifying, please re-enter -Enter Kerberos master key: @\@b[<--] @p[Re-enter it.] -) -@end[example] - -@section[Storing the Master Password] - -The @i[kstash] command ``stashes'' the master password in the file @i[/.k] -so that the Kerberos server can -be started automatically during an unattended reboot of the -master server. -Other administrative programs use this hidden password so that they -can access the master database without someone having to manually -provide the master password. -This command is an optional one; -if you'd rather enter the master password each time you -start the Kerberos server, don't use @i[kstash]. - -One the one hand, if you use @i[kstash], a copy of the master -key will reside -on disk which may not be acceptable; on the other hand, if you don't -use @i[kstash], the server cannot be started unless someone is around to -type the password in manually. - -The command prompts you twice for the master password: -@begin[example] -@tabset[3inches] -host# @b([ADMIN_DIR]/kstash) - -Enter Kerberos master key:@\@b[<--] @p[Enter the master password.] -Current Kerberos master key version is 1. - -Master key entered BEWARE! -@end[example] - -A note about the Kerberos database master key: -if your master key is compromised and the database is obtained, -the security of your entire authentication system is compromised. -The master key must be a carefully kept secret. If you keep backups, -you must guard all the master keys you use, in case someone has stolen -an old backup and wants to attack users' whose passwords haven't changed -since the backup was stolen. -This is why we provide the option not to store it on disk. - -@section[Using @p(kdb_edit) to Add Users to the Master Database] - -The @i[kdb_edit] program is used to add new users and services -to the master database, and to modify existing database information. -The program prompts you to enter a principal's @b[name] and @b[instance]. - -A principal name is typically a username or a service program's name. -An instance further qualifies the principal. -If the principal is a service, -the instance is used to specify the name of the machine on which that -service runs. -If the principal is a username that has general user privileges, -the instance is usually set to null. - -The following example shows how to use @i[kdb_edit] to -add the user @i[wave] to the Kerberos database. -@begin[example, rightmargin -10] -@tabset[3inches, +1.5inches] -host# @b([ADMIN_DIR]/kdb_edit) - -Opening database... - -Enter Kerberos master key: -Verifying, please re-enter -Enter Kerberos master key: -Current Kerberos master key version is 1 - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -Principal name: @b[wave]@\@b[<--] @p[Enter the username.] -Instance:@\@p[<-- Enter a null instance.] - -, Create [y] ? @b[y]@\@b[<--] @p[The user-instance does not exist.] -@\@p[ Enter y to create the user-instance.] -Principal: wave Instance: m_key_v: 1 -New Password: @\@p[<-- Enter the user-instance's password.] -Verifying, please re-enter -New Password: -Principal's new key version = 1 -Expiration date (enter dd-mm-yy) [ 12/31/99 ] ?@\@b[<--] @p[Enter newlines] -Max ticket lifetime (*5 minutes) [ 255 ] ? @\@b[<--] @p[to get the] -Attributes [ 0 ] ? @\@\@b[<--] @p[default values.] -Edit O.K. - -Principal name:@\@p[<-- Enter a newline to exit the program.] -@end[example] - -Use the @i[kdb_edit] utility to add your username to the master database. - -@section[Starting the Kerberos Server] - -Change directories to the directory in which you have installed -the server program @i[kerberos] -(the default directory is @i[/usr/etc]), -and start the program as a background process: -@begin[example] -host# @b[./kerberos &] -@end[example] -If you have used the @i[kstash] command to store the master database password, -the server will start automatically. -If you did not use @i[kstash], -use the following command: -@begin[example] -host# @b[./kerberos -m] -@end[example] -The server will prompt you to enter the master password before actually -starting itself. - -@section[Testing the Kerberos Server] - -Exit the root account and use the @i[kinit] command obtain a Kerberos -ticket-granting ticket. -This command -creates your ticket file -and stores the ticket-granting ticket in it. - -If you used the default @i[make install] command and directories to -install the Kerberos user utilities, @i[kinit] will be in the -@i[/usr/athena] directory. From now on, we'll refer to the Kerberos user -commands directory as [K_USER]. - -Use @i[kinit] as follows: -@begin[example] -@tabset[3 inches] -host% @b([K_USER]/kinit) -MIT Project Athena, (ariadne) -Kerberos Initialization -Kerberos name: @p[yourusername]@\@b[<--] @p[Enter your Kerberos username.] -Password: @\@b[<--] @p[Enter your Kerberos password.] -@end[example] - -Use the @i[klist] program to list the contents of your ticket file. -@begin[example] -host% @b([K_USER]/klist) -@end[example] -The command should display something like the following: -@begin[example] -Ticket file: /tmp/tkt5555 -Principal: yourusername@@REALMNAME - - Issued Expires Principal -May 6 10:15:23 May 6 18:15:23 krbtgt.REALMNAME@@REALMNAME -@end[example] - -If you have any problems, you can examine the log file -@i[/kerberos/kerberos.log] on the Kerberos server machine to see if -there was some sort of error. - -@chapter[Setting up and testing the Administration server] - -The procedure for setting up and testing the Kerberos administration server -is as follows: -@begin[enumerate] -Use the @i[kdb_edit] utility to add your username with an administration -instance to the master database. - -Edit the access control lists for the administration server - -Start the Kerberos administration server. - -Use the @i[kpasswd] command to change your password. - -Use the @i[kadmin] command to add new entries to the database. - -Use the @i[kinit] command to verify that the @i[kadmin] command -correctly added new entries to the database. -@end(enumerate) - -@section[Adding an administration instance for the administrator] - -Login to the Kerberos master server machine, -and use the @b[su] command to become root. -Use the @i[kdb_edit] program to create an entry for each administrator -with the instance ``@p(admin)''. -@begin[example] -@tabset[3inches, +1.5inches] -host# @b([ADMIN_DIR]/kdb_edit) - -Opening database... - -Enter Kerberos master key: -Verifying, please re-enter -Enter Kerberos master key: -Current Kerberos master key version is 1 - -Master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -Principal name: @b[wave]@\@b[<--] @p[Enter the username.] -Instance:@b[admin]@\@b[<--] @p[Enter ``admin''.] - -, Create [y] ? @b[y]@\@b[<--] @p[The user-instance does not exist.] -@\@p[ Enter y to create the user-instance.] -Principal: wave Instance: admin m_key_v: 1 -New Password: @\@p[<-- Enter the user-instance's password.] -Verifying, please re-enter -New Password: -Principal's new key version = 1 -Expiration date (enter dd-mm-yy) [ 12/31/99 ] ?@\@b[<--] @p[Enter newlines] -Max ticket lifetime (*5 minutes) [ 255 ] ? @\@b[<--] @p[to get the] -Attributes [ 0 ] ? @\@\@b[<--] @p[default values.] -Edit O.K. - -Principal name:@\@p[<-- Enter a newline to exit the program.] -@end[example] - -@section[The Access Control Lists] -The Kerberos administration server uses three access control lists to -determine who is authorized to make certain requests. The access -control lists are stored on the master Kerberos server in the same -directory as the principal database, @i(/kerberos). The access control -lists are simple ASCII text files, with each line specifying the name of -one principal who is allowed the particular function. To allow several -people to perform the same function, put their principal names on -separate lines in the same file. - -The first list, @i(/kerberos/admin_acl.mod), is a list of principals -which are authorized to change entries in the database. To allow the -administrator `@b[wave]' to modify entries in the database for the realm -`@b[TIM.EDU]', you would put the following line into the file -@i(/kerberos/admin_acl.mod): -@begin(example) -wave.admin@@TIM.EDU -@end(example) - -The second list, @i(/kerberos/admin_acl.get), is a list of principals -which are authorized to retrieve entries from the database. - -The third list, @i(/kerberos/admin_acl.add), is a list of principals -which are authorized to add new entries to the database. - -@section(Starting the administration server) -Change directories to the directory in which you have installed -the administration server program @i[kadmind] -(the default directory is @i[/usr/etc]), -and start the program as a background process: -@begin[example] -host# @b[./kadmind -n&] -@end[example] -If you have used the @i[kstash] command to store the master database password, -the server will start automatically. -If you did not use @i[kstash], -use the following command: -@begin[example] -host# @b[./kadmind] -@end[example] -The server will prompt you to enter the master password before actually -starting itself; after it starts, you should suspend it and put it in -the background (usually this is done by typing control-Z and then @b(bg)). - -@section(Testing @p[kpasswd]) - -To test the administration server, you should try changing your password -with the @i[kpasswd] command, and you should try adding new users with -the @i[kadmin] command (both commands are installed into @i[/usr/athena] -by default). - -Before testing, you should exit the root account. - -To change your password, run the @i[kpasswd] command: -@begin(example) -@tabset[3inches, +1.5inches] -host% @b([K_USER]/kpasswd) -Old password for wave@@TIM.EDU:@\@b[<--]@p[Enter your password] -New Password for wave@@TIM.EDU:@\@b[<--]@p[Enter a new password] -Verifying, please re-enter New Password for wave@@TIM.EDU: -@\@b[<--]@p[Enter new password again] -Password changed. -@end(example) -Once you have changed your password, use the @i[kinit] program as shown -above to verify that the password was properly changed. - -@section(Testing @p[kadmin]) -You should also test the function of the @i[kadmin] program, by adding a -new user (here named ``@t[username]''): -@begin(example) -@tabset[3inches, +1.5inches] -host% @b([K_USER]/kadmin) -Welcome to the Kerberos Administration Program, version 2 -Type "help" if you need it. -admin: @b(ank username)@\@p[`ank' stands for Add New Key] -Admin password: @\@b[<--]@p[enter the password -@\you chose above for wave.admin] -Password for username:@\@b[<--]@p[Enter the user's initial password] -Verifying, please re-enter Password for username:@\@b[<--]@p[enter it again] -username added to database. - -admin: quit -Cleaning up and exiting. -@end[example] - -@section(Verifying with @p[kinit]) -Once you've added a new user, you should test to make sure it was added -properly by using @i[kinit], and trying to get tickets for that user: - -@begin[example] -@tabset[3inches, +1.5inches] -host% @b([K_USER]/kinit username) -MIT Project Athena (ariadne) -Kerberos Initialization for "username@@TIM.EDU" -Password: @b[<--]@p[Enter the user's password you used above] -host% @b([K_USER]/klist) -Ticket file: /tmp/tkt_5509_spare1 -Principal: username@@TIM.MIT.EDU - - Issued Expires Principal -Nov 20 15:58:52 Nov 20 23:58:52 krbtgt.TIM.EDU@@TIM.EDU -@end[example] - -If you have any problems, you can examine the log files -@i[/kerberos/kerberos.log] and @i[/kerberos/admin_server.syslog] on the -Kerberos server machine to see if there was some sort of error. - -@chapter[Setting up and testing slave server(s)] - -[Unfortunately, this chapter is not yet ready. Sorry. -ed] - -@chapter[A Sample Application] - -This release of Kerberos comes with a sample application -server and a corresponding client program. -You will find this software in the [OBJ_DIR]@i[/appl/sample] directory. -The file @i[sample_client] contains the client program's executable -code, the file @i[sample_server] contains the server's executable. - -The programs are rudimentary. -When they have been installed (the installation procedure is described -in detail later), they work as follows: -@begin[itemize] -The user starts @i[sample_client] and provides as arguments -to the command the name of the server machine and a checksum. -For instance: -@begin[example] -host% @b[sample_client] @p[servername] @p[43] -@end[example] - -@i[Sample_client] contacts the server machine and -authenticates the user to @i[sample_server]. - -@i[Sample_server] authenticates itself to @i[sample_client], -then returns a message to the client program. -This message contains diagnostic information -that includes the user's username, the Kerberos realm, -and the user's workstation address. - -@i[Sample_client] displays the server's message on the user's -terminal screen. -@end[itemize] - -@section[The Installation Process] - -In general, -you use the following procedure to install a Kerberos-authenticated -server-client system. -@begin[enumerate] -Add the appropriate entry to the Kerberos database using @i[kdb_edit] or -@i[kadmin] (described below). - -Create a @i[/etc/srvtab] file for the server machine. - -Install the service program and the @i[/etc/srvtab] -file on the server machine. - -Install the client program on the client machine. - -Update the @i[/etc/services] file on the client and server machines. -@end[enumerate] - -We will use the sample application as an example, although -the procedure used to install @i[sample_server] differs slightly -from the general case because the @i[sample_server] -takes requests via the -@i[inetd] program. -@i[Inetd] starts @i[sample_server] each time -a client process contacts the server machine. -@i[Sample_server] processes the request, -terminiates, then is restarted when @i[inetd] receives another -@i[sample_client] request. -When you install the program on the server, -you must add a @i[sample] entry to the server machine's -@i[/etc/inetd.conf] file. - -The following description assumes that you are installing -@i[sample_server] on the machine @i[ariadne.tim.edu]. -Here's the process, step by step: -@begin[enumerate] -Login as or @i[su] to root on the Kerberos server machine. -Use the @i[kdb_edit] or @i[kadmin] program to create an entry for -@i[sample] in the Kerberos database: -@begin[example, rightmargin -10] -@tabset[2.0inches, +.5inches] -host# @b([ADMIN_DIR]/kdb_edit) - -Opening database... - -Enter Kerberos master key: -Verifying, please re-enter -master key entered. BEWARE! -Previous or default values are in [brackets] , -enter return to leave the same, or new value. - -Principal name: @b[sample]@\@b[<--] @p[Enter the principal name.] -Instance: @b[ariadne]@\@b[<--] @p[Instances cannot have periods in them.] - -, Create [y] ? @b[y] - -Principal: sample_server Instance: ariadne m_key_v: 1 -New Password:@\@b[<--] @p[Enter ``RANDOM'' to get random password.] -Verifying, please re-enter -New Password:@\@b[<--] @p[Enter ``RANDOM'' again.] -Random password [y] ? @b[y] - -Principal's new key version = 1 -Expiration date (enter dd-mm-yy) [ 12/31/99 ] ? -Max ticket lifetime (*5 minutes) [ 255 ] ? -Attributes [ 0 ] ? -Edit O.K. - -Principal name:@\@b[<--] @p[Enter newline to exit kdb_edit.] -@end[example] - -Use the @i[ext_srvtab] program to create a @i[srvtab] file -for @i[sample_server]'s host machine: -@begin[example] -host# @b([ADMIN_DIR]/ext_srvtab ariadne) - -Enter Kerberos master key: -Current Kerberos master key version is 1. - -Generating 'ariadne-new-srvtab'.... -@end[example] -Transfer the @i[ariadne-new-srvtab] file to @i[ariadne] and install it as -@i[/etc/srvtab]. -Note that this file is equivalent to the service's password and should -be treated with care. -For example, it could be transferred by removable media, but should -not be sent over an open network in the clear. -Once installed, this file should be readable only by root. - -Add the following line to the @i[/etc/services] file on -@i[ariadne], and on all machines that -will run the @i[sample_client] program: -@begin[example] -sample 906/tcp # Kerberos sample app server -@end[example] - -Add a line similar to the following line to the @i[/etc/inetd.conf] -file on @i[sample_server]'s machine: -@begin[example] -sample stream tcp nowait switched root - [PATH]/sample_server sample_server -@end[example] -where [PATH] should be substituted with -the path to the @i[sample_server] program. -(This @i[inetd.conf] information should be placed on one line.) -You should examine existing lines in @i[/etc/inetd.conf] and use the -same format used by other entries (e.g. for telnet). Most systems do -not have a column for the `switched' keyword, and some do not have a -column for the username (usually `root', as above). - -Restart @i[inetd] by sending the current @i[inetd] process -a hangup signal: -@begin[example] -host# @b[kill -HUP @p(process_id_number)] -@end[example] - -The @i[sample_server] is now ready to take @i[sample_client] requests. -@end[enumerate] - -@section[Testing the Sample Server] - -Assume that you have installed @i[sample_server] on @i[ariadne]. - -Login to your workstation and use the @i[kinit] command to -obtain a Kerberos ticket-granting ticket: -@begin[example] -@tabset[3 inches] -host% @b([K_USER]/kinit) -MIT Project Athena, (your_workstation) -Kerberos Initialization -Kerberos name: @p[yourusername]@\@b[<--] @p[Enter your Kerberos username.] -Password: @\@b[<--] @p[Enter your Kerberos password.] -@end[example] - -Now use the @i[sample_client] program as follows: -@begin[example] -host% @b([PATH]/sample_client ariadne) -@end[example] -The command should display something like the following: -@begin[example] -The server says: -You are @p[yourusername].@@REALMNAME (local name @p[yourusername]), - at address @p[yournetaddress], version VERSION9, cksum 997 -@end[example] - -@chapter[Service names and other services] - -@section(rlogin, rsh, rcp, tftp, and others) - -Many services use a common principal name for authentication purposes. -@i[rlogin], @i[rsh], @i[rcp], @i[tftp] and others use the principal name -``@t[rcmd]''. For example, to set up the machine @i[ariadne] to support -Kerberos rlogin, it needs to have a service key for principal -``@t[rcmd]'', instance ``@t[ariadne]''. You create this key in the same -way as shown above for the sample service. - -After creating this key, you need to run the @i[ext_srvtab] program -again to generate a new srvtab file for ariadne. - -@section(NFS modifications) - -The NFS modifications distributed separately use the service name -``@t[rvdsrv]'' with the instance set to the machine name (as for the -sample server and the rlogin, rsh, rcp and tftp services). - -@section(inetd.conf entries) -The following are the @i(/etc/inetd.conf) entries necessary to support -rlogin, encrypted rlogin, rsh, and rcp services on a server machine. As -above, your @i(inetd.conf) may not support all the fields shown here. -@begin[example] -eklogin stream tcp nowait unswitched root - [PATH]/klogind eklogind -kshell stream tcp nowait unswitched root - [PATH]/kshd kshd -klogin stream tcp nowait unswitched root - [PATH]/klogind klogind -@end[example] diff --git a/src/appl/popper/Imakefile b/src/appl/popper/Imakefile deleted file mode 100644 index d46dc301b..000000000 --- a/src/appl/popper/Imakefile +++ /dev/null @@ -1,93 +0,0 @@ -# $Source$ -# $Author$ -# $Id$ -# -# Copyright 1991 by the Massachusetts Institute of Technology. -# 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 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. -# -# - -# Options are: -# BIND43 - If you are using BSD 4.3 domain -# name service. -# DEBUG - Include the debugging code. Note: You -# still have to use the -d or -t flag to -# enable debugging. -# HAVE_VSPRINTF - If the vsprintf functions are -# available -# on your system. -# SYSLOG42 - For BSD 4.2 syslog (default is BSD 4.3 -# syslog). -# STRNCASECMP - If you do not have strncasecmp() -# KERBEROS - If you want authentication vis Kerberos -# (tom) -# KERBEROS_PASSWD_HACK - Use popper as passwd server -# NOSTATUS - Don't create a Mail(1)-like -# Status: header - -#if defined(OS_BSD_RENO) || defined(OS_Ultrix) || defined(OS_SunOS4) || defined(OS_BSD) -BINDDEF=-DBIND43 -#else -/* assume it's not there; not really critical since we are using Kerberos to - beef up the normal IP-address checking stuff */ -BINDDEF= -#endif - -#if 0 - -/* Zephyr stuff not needed yet, since spop isn't done yet. */ -DEFINES = -DHAVE_VSPRINTF -DKERBEROS -DKRB5 -DNOSTATUS -DDEBUG $(BINDDEF) $(ZEPHDEFS) -LOCAL_LIBRARIES = $(ZEPHLIBS) $(KLIB) -DEP_LIBS= $(ZEPHDEPLIB) $(DEPKLIB) - -#else - -DEFINES = -DHAVE_VSPRINTF -DKERBEROS -DKRB5 -DNOSTATUS -DDEBUG $(BINDDEF) -LOCAL_LIBRARIES = $(KLIB) -DEP_LIBS= $(DEPKLIB) - -#endif -OBJS = pop_dele.o pop_dropcopy.o pop_dropinfo.o \ - pop_get_command.o pop_get_subcommand.o pop_init.o \ - pop_last.o pop_list.o pop_log.o pop_lower.o \ - pop_msg.o pop_parse.o pop_pass.o pop_quit.o \ - pop_rset.o pop_send.o pop_stat.o pop_updt.o \ - pop_user.o pop_xtnd.o pop_xmit.o popper.o -SRCS = pop_dele.c pop_dropcopy.c pop_dropinfo.c \ - pop_get_command.c pop_get_subcommand.c pop_init.c \ - pop_last.c pop_list.c pop_log.c pop_lower.c \ - pop_msg.c pop_parse.c pop_pass.c pop_quit.c \ - pop_rset.c pop_send.c pop_stat.c pop_updt.c \ - pop_user.c pop_xtnd.c pop_xmit.c popper.c $(SPOP_SRCS) -#if 0 -SPOP_OBJS = pop_enter.o -SPOP_SRCS = pop_enter.c -#endif - -all:: popper - -NormalProgramTarget(popper,$(OBJS),$(DEP_LIBS),$(LOCAL_LIBRARIES),) -Krb5InstallServerProgram(popper) - -#if 0 -NormalProgramTarget(spop,$(SPOP_OBJS),$(DEP_LIBS),$(LOCAL_LIBRARIES),) -Krb5InstallServerProgram(spop) -#endif - -DependTarget() -- 2.26.2