3 files changed, 420 insertions, 169 deletions
diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst
index 29c764182d..1aee19f58d 100644
--- a/doc/rst_source/krb_appldev/index.rst
+++ b/doc/rst_source/krb_appldev/index.rst
@@ -1,5 +1,3 @@
-.. _tutorial_ctx_basic:
-
 For application developers
 ===================================
 
@@ -14,59 +12,6 @@ Contents:
    princ_handle.rst
 
 
-Topics in TODO list:
-----------------------
-
-#. A basic introduction to GSS-API, making use of the sample client and server, with special attention paid to Kerberos-related GSS-API issues.
- 
-#. How to tell the GSS-API library on the client side where the existing Kerberos ticket cache is.
- 
-#. How to write mechanism-independent GSS-API code and when to do so.  
-
-#. SASL: how to use it, and how it interacts with GSS-API.
-
-#. How to get servers to use any key in a keytab.
-
-#. A more advanced introduction to using the Kerberos libraries for initial authentication, focusing on the authentication steps, validating initial credentials
-
-#. An introduction to ticket caches and keytabs and their corresponding APIs. 
-
-#. An advanced guide to the pre-auth mechanisms, FAST
-
-#. An advanced guide to the principal manipulation and parsing,
-
-#. A guide to GSS-API naming as compared to Kerberos principal naming. 
-
-#. Establish, save, restore and delete context ( server and client sides)
-
-#. Obtain context status, flags
-
-#. Wrap and send message
-
-#. Read and verify message
-
-#. Working with credentials
-
-#. Server side operations
-
-#. Delegating credentials
-
-#. Anonymous Authentication
-
-#. Developing or selecting cryptosystem
-
-#. Developing or selecting PRNG
-
-#. Developing applications for smart card
-
-#. Indicate authentication strength
-
-#. Implementing IAKERB
- 
-#. Using Smartcard with PK-INIT
-
-#. Thread safety
-
 ------------
 
 Feedback:
diff --git a/doc/rst_source/krb_build/options2configure.rst b/doc/rst_source/krb_build/options2configure.rst
index 67d5d36089..b05a0ec255 100644
--- a/doc/rst_source/krb_build/options2configure.rst
+++ b/doc/rst_source/krb_build/options2configure.rst
@@ -1,111 +1,416 @@
-.. _options2configure:
-
-Options to Configure
-=========================
-
-There are a number of options to configure which you can use to control how the Kerberos distribution is built. i
-The following table lists the most commonly used options to Kerberos V5's configure program.
-
-
---help
-    Provides help to configure. This will list the set of commonly used options for building Kerberos.
---prefix=PREFIX
-    By default, Kerberos will install the package's files rooted at '\/usr\/local' as in '\/usr\/local/bin', '\/usr\/local\/sbin', etc. 
-    If you desire a different location, use this option.
---exec-prefix=EXECPREFIX
-    This option allows one to separate the architecture independent programs from the configuration files and manual pages.
---localstatedir=LOCALSTATEDIR
-    This option sets the directory for locally modifiable single-machine data. 
-    In Kerberos, this mostly is useful for setting a location for the KDC data files, 
-    as they will be installed in LOCALSTATEDIR\/krb5kdc, which is by default PREFIX\/var\/krb5kdc.
-CC=COMPILER
-    Use COMPILER as the C compiler.
-CFLAGS=FLAGS
-    Use FLAGS as the default set of C compiler flags.
-    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 3,469 billion years to compile if you provide neither the -g flag nor the -O flag to cc.
-CPPFLAGS=CPPOPTS
-    Use CPPOPTS as the default set of C preprocessor flags. 
-    The most common use of this option is to select certain #define's for use with the operating system's include files.
-LD=LINKER
-    Use LINKER as the default loader if it should be different from C compiler as specified above.
-LDFLAGS=LDOPTS
-    This option allows one to specify optional arguments to be passed to the linker. This might be used to specify optional library paths.
---with-krb4
-    This option enables Kerberos V4 backwards compatibility using the builtin Kerberos V4 library.
---with-krb4=KRB4DIR
-    This option enables Kerberos V4 backwards compatibility using a pre-existing Kerberos V4 installation. 
-    The directory specified by KRB4DIR specifies where the V4 header files should be found (KRB4DIR\/include) 
-    as well as where the V4 Kerberos library should be found (KRB4DIR/lib).
---without-krb4
-    Disables Kerberos V4 backwards compatibility. 
-    This prevents Kerberos V4 clients from using the V5 services including the KDC. 
-    This would be useful if you know you will never install or need to interact with V4 clients.
---with-netlib[=libs]
-    Allows for suppression of or replacement of network libraries. 
-    By default, Kerberos V5 configuration will look for *-lnsl* and *-lsocket*. 
-    If your operating system has a broken resolver library (see Solaris versions 2.0 through 2.3) 
-    or fails to pass the tests in src/tests/resolv you will need to use this option.
---with-tcl=TCLPATH
-    Some of the unit-tests in the build tree rely upon using a program in Tcl. 
-    The directory specified by TCLPATH specifies where the Tcl header file (TCLPATH/include/tcl.h 
-    as well as where the Tcl library should be found (TCLPATH/lib).
---enable-shared
-    This option will turn on the building and use of shared library objects in the Kerberos build. This option is only supported on certain platforms.
---enable-dns
-
---enable-dns-for-kdc
-
---enable-dns-for-realm
-    Enable the use of DNS to look up a host's Kerberos realm, or a realm's KDCs, if the information is not provided in krb5.conf. 
-    See Hostnames for the Master and Slave KDCs for information about using DNS to locate the KDCs, 
-    and Mapping Hostnames onto Kerberos Realms for information about using DNS to determine the default realm. 
-    By default, DNS lookups are enabled for the former but not for the latter.
---enable-kdc-replay-cache
-    Enable a cache in the KDC to detect retransmitted messages, and resend the previous responses to them. 
-    This protects against certain types of attempts to extract information from the KDC through some of the hardware preauthentication systems.
---with-system-et
-    Use an installed version of the error-table support software, the compile_et program, the com_err.h header file and the com_err library. 
-    If these are not in the default locations, you may wish to specify CPPFLAGS=-I/some/dir and LDFLAGS=-L/some/other/dir options at configuration time as well.
-
-    If this option is not given, a version supplied with the Kerberos sources will be built and installed along with the rest of the Kerberos tree, for Kerberos applications to link against.
---with-system-ss
-    Use an installed version of the subsystem command-line interface software, 
-    the mk_cmds program, the ss/ss.h header file and the ss library. 
-    If these are not in the default locations, you may wish to specify CPPFLAGS=-I/some/dir and LDFLAGS=-L/some/other/dir options 
-    at configuration time as well. See also the SS_LIB option.
-
-    If this option is not given, the ss library supplied with the Kerberos sources will be compiled and linked into those programs that need it; it will not be installed separately.
-SS_LIB=libs...
-    If -lss is not the correct way to link in your installed ss library, for example if additional support libraries are needed, specify the correct link options here. Some variants of this library are around which allow for Emacs-like line editing, but different versions require different support libraries to be explicitly specified.
-
-    This option is ignored if --with-system-ss is not specified.
---with-system-db
-    Use an installed version of the Berkeley DB package, which must provide an API compatible with version 1.85. 
-    This option is unsupported and untested. In particular, we do not know if the database-rename code used in the dumpfile load operation will behave properly.
-
-    If this option is not given, a version supplied with the Kerberos sources will be built and installed. 
-    (We are not updating this version at this time because of licensing issues with newer versions that we haven't investigated sufficiently yet.)
-DB_HEADER=headername.h
-    If db.h is not the correct header file to include to compile against the Berkeley DB 1.85 API, 
-    specify the correct header file name with this option. For example, DB_HEADER=db3/db_185.h.
-DB_LIB=libs...
-    If -ldb is not the correct library specification for the Berkeley DB library version to be used, override it with this option. For example, DB_LIB=-ldb-3.3. 
-
-For example, in order to configure Kerberos on a Solaris machine using the suncc compiler with the optimizer turned on, 
-run the configure script with the following options::
-
-     % ./configure CC=suncc CFLAGS=-O
-     
-
-For a slightly more complicated example, consider a system where several packages to be used by Kerberos are installed in /usr/foobar, i
-including Berkeley DB 3.3, and an ss library that needs to link against the curses library. The configuration of Kerberos might be done thus::
-
-      ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \
-                   --with-system-et --with-system-ss --with-system-db \
-                   SS_LIB='-lss -lcurses' \
-                   DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3
-     
-
-In previous releases, --with- options were used to specify the compiler and linker and their options. 
-
+.. _options2configure:
+
+Options to *configure*
+=========================
+
+There are a number of options to configure which you can use to control 
+how the Kerberos distribution is built. 
+
+Most commonly used options
+-----------------------------
+
+ ---help
+
+    Provides help to configure. 
+    This will list the set of commonly used options for building Kerberos.
+
+ --prefix=PREFIX
+
+    By default, Kerberos will install the package's files rooted at '/usr/local'
+    If you desire to place the binaries into the directory *PREFIX*, use this option 
+
+ --exec-prefix=EXECPREFIX
+
+    This option allows one to separate the architecture independent programs
+    from the host-dependent files (configuration files, manual pages).
+    Use this option to install architecture-dependent programs in *EXECPREFIX*.
+    The default location is the value of specified by * --prefix* option.
+
+ --localstatedir=LOCALSTATEDIR
+ 
+   This option sets the directory for locally modifiable single-machine data. 
+    In Kerberos, this mostly is useful for setting a location for the KDC data files, 
+    as they will be installed in *LOCALSTATEDIR/krb5kdc*, which is by default *PREFIX/var/krb5kdc*.
+
+ --with-netlib[=libs]
+
+    Allows for suppression of or replacement of network libraries. 
+    By default, Kerberos V5 configuration will look for *-lnsl* and *-lsocket*. 
+    If your operating system has a broken resolver library 
+    or fails to pass the tests in src/tests/resolv you will need to use this option.
+
+ --with-tcl=TCLPATH
+
+    Some of the unit-tests in the build tree rely upon using a program in Tcl. 
+    The directory specified by *TCLPATH* specifies where the Tcl header file 
+    (TCLPATH/include/tcl.h) 
+    as well as where the Tcl library should be found (TCLPATH/lib).
+
+ --enable-dns-for-realm
+
+    Enable the use of DNS to look up a host's Kerberos realm, or a realm's KDCs, 
+    if the information is not provided in :ref:`krb5.conf`. 
+    See :ref:`kdc_hn_label` for information about using DNS to locate the KDCs, 
+    and :ref:`mapping_hn_label` for information about using DNS to determine the default realm. 
+    By default, DNS lookups are enabled for the former but not for the latter.
+
+ --with-system-et
+    
+    Use an installed version of the error-table (et) support software, 
+    the *compile_et* program, the com_err.h header file and the *com_err* library. 
+    If these are not in the default locations, you may wish to specify 
+    *CPPFLAGS=-I/some/dir* and *LDFLAGS=-L/some/other/dir* options at configuration time as well.
+
+    If this option is not given, a version supplied with the Kerberos sources 
+    will be built and installed along with the rest of the Kerberos tree, 
+    for Kerberos applications to link against.
+
+ --with-system-ss
+
+    Use an installed version of the subsystem command-line interface software, 
+    the *mk_cmds* program, the ss/ss.h header file and the ss library. 
+    If these are not in the default locations, you may wish to specify 
+    *CPPFLAGS=-I/some/dir* and *LDFLAGS=-L/some/other/dir* options 
+    at configuration time as well. See also the *SS_LIB* option.
+
+    If this option is not given, the *ss* library supplied with the Kerberos sources 
+    will be compiled and linked into those programs that need it; 
+    it will not be installed separately.
+
+ --with-system-db
+
+    Use an installed version of the Berkeley DB package, 
+    which must provide an API compatible with version 1.85. 
+    This option is unsupported and untested. 
+    In particular, we do not know if the database-rename code used 
+    in the dumpfile load operation will behave properly.
+
+    If this option is not given, a version supplied with the Kerberos sources 
+    will be built and installed. 
+    (We are not updating this version at this time because of licensing issues 
+    with newer versions that we haven't investigated sufficiently yet.)
+
+
+Environment variables
+----------------------------------------
+
+CC=COMPILER
+    Use *COMPILER* as the C compiler.
+
+CFLAGS=FLAGS
+    Use *FLAGS* as the default set of C compiler flags.
+
+CPPFLAGS=CPPOPTS
+    Use *CPPOPTS* as the default set of C preprocessor flags. 
+    The most common use of this option is to select certain #define's 
+    for use with the operating system's include files.
+
+CPP=CPP  
+     C preprocessor to use. (e,g, CPP='gcc -E')
+
+DB_HEADER=headername.h
+    If db.h is not the correct header file to include to compile against the Berkeley DB 1.85 API, 
+    specify the correct header file name with this option. For example, DB_HEADER=db3/db_185.h.
+
+DB_LIB=libs...
+    If *-ldb* is not the correct library specification for the Berkeley DB library version to be used, 
+    override it with this option. For example, DB_LIB=-ldb-3.3. 
+
+LD=LINKER
+    Use *LINKER* as the default loader if it should be different from C compiler as specified above.
+
+LDFLAGS=LDOPTS
+    This option informs the linker where to get additional libraries (e.g. -L<lib dir>).
+
+LIBS=LDNAME
+    This option allows one to specify libraries to be passed to the linker ( e.g. -l<library>)
+
+SS_LIB=libs...
+    If *-lss* is not the correct way to link in your installed *ss* library, 
+    for example if additional support libraries are needed, 
+    specify the correct link options here. 
+    Some variants of this library are around which allow for Emacs-like line editing, 
+    but different versions require different support libraries to be explicitly specified.
+
+    This option is ignored if \-\-with-system-ss is not specified.
+
+CXX     
+     C++ compiler command
+
+CXXFLAGS
+     C++ compiler flags
+
+YACC    
+     The 'Yet Another C Compiler' implementation to use. Defaults to
+     the first program found out of: 'bison -y', 'byacc', 'yacc'.
+
+YFLAGS 
+     The list of arguments that will be passed by default to $YACC.
+     This script will default YFLAGS to the empty string to avoid a
+     default value of '-d' given by some make applications.
+
+
+Examples
+----------
+
+For example, in order to configure Kerberos on a Solaris machine 
+
+using the *suncc* compiler with the optimizer *turned on*, 
+run the configure script with the following options::
+
+     % ./configure CC=suncc CFLAGS=-O
+     
+
+For a slightly more complicated example, consider a system 
+where several packages to be used by Kerberos are installed in /usr/foobar,
+including Berkeley DB 3.3, and an ss library that needs to link against the curses library. 
+The configuration of Kerberos might be done thus::
+
+      ./configure CPPFLAGS=-I/usr/foobar/include LDFLAGS=-L/usr/foobar/lib \-\-with-system-et \-\-with-system-ss \-\-with-system-db  SS_LIB='-lss -lcurses'  DB_HEADER=db3/db_185.h DB_LIB=-ldb-3.3
+     
+
+
+Fine tuning of the installation directories
+----------------------------------------------
+
+ --bindir=DIR    
+
+     User executables. 
+     Defaults to  *EXECPREFIX/bin*, where *EXECPREFIX* is the path specified by "--exec-prefix" configuration option.
+
+ --sbindir=DIR    
+
+     System admin executables.
+     Defaults to  *EXECPREFIX/sbin*, where *EXECPREFIX* is the path specified by "--exec-prefix" configuration option.
+
+ --libexecdir=DIR 
+
+     Program executables.
+     Defaults to  *EXECPREFIX/libexec*, where *EXECPREFIX* is the path specified by "--exec-prefix" configuration option.
+
+ --sysconfdir=DIR 
+
+     Read-only single-machine data.
+     Defaults to  *PREFIX/etc*, where *PREFIX* is the path specified by "--prefix" configuration option.
+
+ --sharedstatedir=DIR
+
+     Modifiable architecture-independent data.
+     Defaults to  *PREFIX/com*, where *PREFIX* is the path specified by "--prefix" configuration option.
+
+ --libdir=DIR    
+
+     Object code libraries [EXECPREFIX/lib]
+     Defaults to  *EXECPREFIX/lib*, where *EXECPREFIX* is the path specified by "--exec-prefix" configuration option.
+
+ --includedir=DIR  
+
+     C header files.
+     Defaults to  *PREFIX/include*, where *PREFIX* is the path specified by "--prefix" configuration option.
+
+ --oldincludedir=DIR 
+
+     C header files for non-gcc. Default to  /usr/include
+  
+ --datarootdir=DATAROOTDIR 
+
+     Read-only architecture-independent data root.
+     Defaults to  *PREFIX/sharee*, where *PREFIX* is the path specified by "--prefix" configuration option.
+  
+
+ --datadir=DIR    
+
+     Read-only architecture-independent data. 
+     Defaults to  *DATAROOTDIR* by "--datarootdir" configuration option.
+  
+ --infodir=DIR   
+
+     Info documentation.
+     Defaults to  *DATAROOTDIR/info*, where *DATAROOTDIR* is the path specified by "--datarootdir" configuration option.
+
+ --localedir=DIR  
+
+     Locale-dependent data.
+     Defaults to  *DATAROOTDIR/locate*, where *DATAROOTDIR* is the path specified by "--datarootdir" configuration option.
+ 
+ --mandir=DIR     
+
+     Man documentation.
+     Defaults to  *DATAROOTDIR/man*, where *DATAROOTDIR* is the path specified by "--datarootdir" configuration option.
+  
+ --docdir=DOCDIR    
+
+     Documentation root.
+     Defaults to  *DATAROOTDIR/doc/krb5*, where *DATAROOTDIR* is the path specified by "--datarootdir" configuration option.
+  
+ --htmldir=DIR    
+
+     html documentation.
+     Defaults to  *DOCDIR*  path specified by "--docdir" configuration option.
+  
+ --dvidir=DIR    
+
+     dvi documentation.
+     Defaults to  *DOCDIR*  path specified by "--docdir" configuration option.
+  
+ --pdfdir=DIR      
+
+     pdf documentation.
+     Defaults to  *DOCDIR*  path specified by "--docdir" configuration option.
+  
+ --psdir=DIR     
+
+     ps documentation.
+     Defaults to  *DOCDIR*  path specified by "--docdir" configuration option.
+
+
+Program names
+----------------------------------------------
+  
+ ---program-prefix=PREFIX      
+
+     Prepend *PREFIX* to the names of the programs when installing them. For example, specifying 
+     '\-\-program-prefix=mit-' at the configure time will cause the program named *abc* to be installed 
+     as *mit-abc*.
+  
+ --program-suffix=SUFFIX        
+
+     Append *SUFFIX*  to the names of the programs when installing them. For example, specifying 
+     '\-\-program-suffix=-mit' at the configure time will cause the program named *abc* to be installed 
+     as *abc-mit*.
+  
+ --program-transform-name=PROGRAM
+
+     Run *sed -e PROGRAM* on installed program names. (*PROGRAM* is a *sed* script).
+
+
+System types
+----------------------------------------------
+
+ ---build=BUILD 
+
+     Configure for building on *BUILD* (e.g. --build=x86_64-linux-gnu).
+  
+ --host=HOST  
+
+     Cross-compile to build programs to run on *HOST*  (e.g. --host=x86_64-linux-gnu). 
+     By default, Kerberos V5 configuration will look for "\-\-build" option).
+
+
+Optional features
+----------------------------------------------
+
+ ---disable-FEATURE   
+
+     Do not include FEATURE (same as  --enable-FEATURE=no)
+  
+ --disable-option-checking
+
+     Ignore unrecognized --enable/--with options
+  
+ --enable-FEATURE[=ARG]  
+
+     Include FEATURE [ARG=yes]
+  
+ --enable-dns-for-realm
+
+     Enable DNS lookups of Kerberos realm names
+  
+ --enable-maintainer-mode
+
+     Enable rebuilding of source files, Makefiles, etc
+  
+ --disable-delayed-initialization
+
+     Initialize library code when loaded [delay until first use]
+  
+ --disable-thread-support
+
+     Don't enable thread support [enabled]
+
+ --disable-rpath   
+
+     Suppress run path flags in link lines
+  
+ --enable-athena   
+
+     Build with MIT Project Athena configuration
+  
+ --enable-fortuna-test
+
+     Build to test Fortuna PRNG
+  
+ --disable-kdc-lookaside-cache
+
+     Disable the cache which detects client retransmits
+
+ --disable-pkinit    
+
+     Disable PKINIT plugin support
+
+
+Optional packages
+-----------------
+
+
+
+ ---with-*PACKAGE* \[=ARG\]
+ 
+    Use *PACKAGE* (e.g. --with-imap). The default value of *ARG* is 'yes'.
+
+ --without-*PACKAGE* 
+
+     Do not use *PACKAGE* (same as \-\-with-PACKAGE=no) (e.g. --without-libedit)
+
+ --with-size-optimizations
+
+     Enable a few optimizations to reduce code size possibly at some run-time cost
+  
+ --with-hesiod=path
+
+     Compile with Hesiod support. The *path* points to the Hesiod directory. 
+     By default Hesiod is unsupported.
+  
+ --with-ldap   
+
+     Compile OpenLDAP database backend module
+  
+ --with-edirectory 
+
+     Compile eDirectory database backend module
+  
+ --with-vague-errors 
+
+     Do not send helpful errors to client. 
+     For example, if the KDC should return only vague error codes to clients.
+  
+ --with-crypto-impl=IMPL
+
+     Use specified crypto implementation (e.g.* --with-crypto=openssl*). 
+     Default is a native MIT Kerberos implementation *builtin*
+     The other currently implemented crypto backends are *openssl* and *nss*.
+     (See :ref:`mitK5features`)
+
+ --with-prng-alg=ALG
+
+     Use specified PRNG algorithm (e.g. * --with-prng-alg=os*).
+
+     Default is the *fortuna* PRNG algorithm. For the *nss* crypto backend use one must explicitly
+     specify * --with-prng-alg=nss*. 
+     (See :ref:`mitK5features`)
+
+ --with-kdc-kdb-update 
+
+     Update the KDC database with the information about 
+     - the last successful authentication;
+     - the last failed authentication attempt;
+     - the number of the failed authentication attempts.
+
+     By default the kdb is not updated with this information..
+  
+ --with-system-verto
+
+     Always use system *verto* library
+
+
+
diff --git a/doc/rst_source/mitK5features.rst b/doc/rst_source/mitK5features.rst
index 319e007327..ea4cec639a 100644
--- a/doc/rst_source/mitK5features.rst
+++ b/doc/rst_source/mitK5features.rst
@@ -1,10 +1,11 @@
 .. highlight:: rst
 
-.. note:: This is a Draft. The list is incomplete.
+.. _mitK5features:
 
 MIT Kerberos features
 =======================================
 
+
 http://web.mit.edu/kerberos
 
 Quick facts
@@ -121,8 +122,8 @@ Feature list
     PRNG                                                                       
       - modularity:                                   1.9                        
       - Yarrow PRNG                                   < 1.10                     
-      - Fortuna PRNG                                  1.9                        
-      - OS PRNG                                       1.10                       
+      - Fortuna PRNG                                  1.9       http://www.schneier.com/book-practical.html
+      - OS PRNG                                       1.10      OS's native PRNG
     Zero configuration                                                          
     IPv6 support in iprop                                                       
    =============================================== =========== ============================================