- Flatten the vendor heimdal tree.

1 files changed, 0 insertions, 642 deletions

diff --git a/crypto/heimdal/doc/programming.texi b/crypto/heimdal/doc/programming.texi
deleted file mode 100644
index 528348b..0000000
--- a/crypto/heimdal/doc/programming.texi
+++ /dev/null
@@ -1,642 +0,0 @@
-@c $Id: programming.texi 22071 2007-11-14 20:04:50Z lha $
-
-@node Programming with Kerberos, Migration, Windows 2000 compatability, Top
-@chapter Programming with Kerberos
-
-First you need to know how the Kerberos model works, go read the
-introduction text (@pxref{What is Kerberos?}).
-
-@menu
-* Kerberos 5 API Overview::     
-* Walkthrough of a sample Kerberos 5 client::  
-* Validating a password in a server application::  
-* API differences to MIT Kerberos::  
-* File formats::
-@end menu
-
-@node Kerberos 5 API Overview, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos
-@section Kerberos 5 API Overview
-
-All functions are documented in manual pages.  This section tries to
-give an overview of the major components used in Kerberos library, and
-point to where to look for a specific function.
-
-@subsection Kerberos context
-
-A kerberos context (@code{krb5_context}) holds all per thread state. All global variables that
-are context specific are stored in this structure, including default
-encryption types, credential cache (for example, a ticket file), and default realms.
-
-See the manual pages for @manpage{krb5_context,3} and
-@manpage{krb5_init_context,3}.
-
-@subsection Kerberos authentication context
-
-Kerberos authentication context (@code{krb5_auth_context}) holds all
-context related to an authenticated connection, in a similar way to the
-kerberos context that holds the context for the thread or process.
-
-The @code{krb5_auth_context} is used by various functions that are
-directly related to authentication between the server/client. Example of
-data that this structure contains are various flags, addresses of client
-and server, port numbers, keyblocks (and subkeys), sequence numbers,
-replay cache, and checksum types.
-
-See the manual page for @manpage{krb5_auth_context,3}.
-
-@subsection Kerberos principal
-
-The Kerberos principal is the structure that identifies a user or
-service in Kerberos. The structure that holds the principal is the
-@code{krb5_principal}. There are function to extract the realm and
-elements of the principal, but most applications have no reason to
-inspect the content of the structure.
-
-The are several ways to create a principal (with different degree of
-portability), and one way to free it.
-
-See manual page for @manpage{krb5_principal,3} for more information
-about the functions.
-
-@subsection Credential cache
-
-A credential cache holds the tickets for a user. A given user can have
-several credential caches, one for each realm where the user have the
-initial tickets (the first krbtgt).
-
-The credential cache data can be stored internally in different way, each of them for
-different proposes.  File credential (FILE) caches and processes based
-(KCM) caches are for permanent storage. While memory caches (MEMORY)
-are local caches to the local process.
-
-Caches are opened with @manpage{krb5_cc_resolve,3} or created with
-@manpage{krb5_cc_gen_unique,3}.
-
-If the cache needs to be opened again (using
-@manpage{krb5_cc_resolve,3}) @manpage{krb5_cc_close,3} will close the
-handle, but not the remove the cache. @manpage{krb5_cc_destroy,3} will
-zero out the cache, remove the cache so it can no longer be
-referenced.
-
-See also manual page for @manpage{krb5_ccache,3}
-
-@subsection Kerberos errors
-
-Kerberos errors are based on the com_err library.  All error codes are
-32-bit signed numbers, the first 24 bits define what subsystem the
-error originates from, and last 8 bits are 255 error codes within the
-library.  Each error code have fixed string associated with it.  For
-example, the error-code -1765328383 have the symbolic name
-KRB5KDC_ERR_NAME_EXP, and associated error string ``Client's entry in
-database has expired''.
-
-This is a great improvement compared to just getting one of the unix
-error-codes back.  However, Heimdal have an extention to pass back
-customised errors messages.  Instead of getting ``Key table entry not
-found'', the user might back ``failed to find
-host/host.example.com@@EXAMLE.COM(kvno 3) in keytab /etc/krb5.keytab
-(des-cbc-crc)''.  This improves the chance that the user find the
-cause of the error so you should use the customised error message
-whenever it's available.
-
-See also manual page for @manpage{krb5_get_error_string,3} and
-@manpage{krb5_get_err_text,3}.
-
-@subsection Keytab management
-
-A keytab is a storage for locally stored keys. Heimdal includes keytab
-support for Kerberos 5 keytabs, Kerberos 4 srvtab, AFS-KeyFile's,
-and for storing keys in memory.
-
-Keytabs are used for servers and long-running services.
-
-See also manual page for @manpage{krb5_keytab,3}
-
-@subsection Kerberos crypto
-
-Heimdal includes a implementation of the Kerberos crypto framework,
-all crypto operations.
-
-See also manual page for @manpage{krb5_crypto_init,3},
-@manpage{krb5_keyblock,3}, @manpage{krb5_create_checksum,3}, 
-and @manpage{krb5_encrypt,3}.
-
-@node Walkthrough of a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos
-@section Walkthrough of a sample Kerberos 5 client
-
-This example contains parts of a sample TCP Kerberos 5 clients, if you
-want a real working client, please look in @file{appl/test} directory in
-the Heimdal distribution.
-
-All Kerberos error-codes that are returned from kerberos functions in
-this program are passed to @code{krb5_err}, that will print a
-descriptive text of the error code and exit. Graphical programs can
-convert error-code to a human readable error-string with the
-@manpage{krb5_get_err_text,3} function.
-
-Note that you should not use any Kerberos function before
-@code{krb5_init_context()} have completed successfully. That is the
-reason @code{err()} is used when @code{krb5_init_context()} fails.
-
-First the client needs to call @code{krb5_init_context} to initialise
-the Kerberos 5 library. This is only needed once per thread
-in the program. If the function returns a non-zero value it indicates
-that either the Kerberos implementation is failing or it's disabled on
-this host.
-
-@example
-#include <krb5.h>
-
-int
-main(int argc, char **argv)
-@{
-        krb5_context context;
-
-        if (krb5_context(&context))
-                errx (1, "krb5_context");
-@end example
-
-Now the client wants to connect to the host at the other end. The
-preferred way of doing this is using @manpage{getaddrinfo,3} (for
-operating system that have this function implemented), since getaddrinfo
-is neutral to the address type and can use any protocol that is available.
-
-@example
-        struct addrinfo *ai, *a;
-        struct addrinfo hints;
-        int error;
-
-        memset (&hints, 0, sizeof(hints));
-        hints.ai_socktype = SOCK_STREAM;
-        hints.ai_protocol = IPPROTO_TCP;
-
-        error = getaddrinfo (hostname, "pop3", &hints, &ai);
-        if (error)
-                errx (1, "%s: %s", hostname, gai_strerror(error));
-
-        for (a = ai; a != NULL; a = a->ai_next) @{
-                int s;
-
-                s = socket (a->ai_family, a->ai_socktype, a->ai_protocol);
-                if (s < 0)
-                        continue;
-                if (connect (s, a->ai_addr, a->ai_addrlen) < 0) @{
-                        warn ("connect(%s)", hostname);
-                            close (s);
-                            continue;
-                @}
-                freeaddrinfo (ai);
-                ai = NULL;
-        @}
-        if (ai) @{
-                    freeaddrinfo (ai);
-                    errx ("failed to contact %s", hostname);
-        @}
-@end example
-
-Before authenticating, an authentication context needs to be
-created. This context keeps all information for one (to be) authenticated
-connection (see @manpage{krb5_auth_context,3}).
-
-@example
-        status = krb5_auth_con_init (context, &auth_context);
-        if (status)
-                krb5_err (context, 1, status, "krb5_auth_con_init");
-@end example
-
-For setting the address in the authentication there is a help function
-@code{krb5_auth_con_setaddrs_from_fd} that does everything that is needed
-when given a connected file descriptor to the socket.
-
-@example
-        status = krb5_auth_con_setaddrs_from_fd (context,
-                                                 auth_context,
-                                                 &sock);
-        if (status)
-                krb5_err (context, 1, status, 
-                          "krb5_auth_con_setaddrs_from_fd");
-@end example
-
-The next step is to build a server principal for the service we want
-to connect to. (See also @manpage{krb5_sname_to_principal,3}.)
-
-@example
-        status = krb5_sname_to_principal (context,
-                                          hostname,
-                                          service,
-                                          KRB5_NT_SRV_HST,
-                                          &server);
-        if (status)
-                krb5_err (context, 1, status, "krb5_sname_to_principal");
-@end example
-
-The client principal is not passed to @manpage{krb5_sendauth,3}
-function, this causes the @code{krb5_sendauth} function to try to figure it
-out itself.
-
-The server program is using the function @manpage{krb5_recvauth,3} to
-receive the Kerberos 5 authenticator.
-
-In this case, mutual authentication will be tried. That means that the server
-will authenticate to the client. Using mutual authentication
-is good since it enables the user to verify that they are talking to the
-right server (a server that knows the key).
-
-If you are using a non-blocking socket you will need to do all work of
-@code{krb5_sendauth} yourself. Basically you need to send over the
-authenticator from @manpage{krb5_mk_req,3} and, in case of mutual
-authentication, verifying the result from the server with
-@manpage{krb5_rd_rep,3}.
-
-@example
-        status = krb5_sendauth (context,
-                                &auth_context,
-                                &sock,
-                                VERSION,
-                                NULL,
-                                server,
-                                AP_OPTS_MUTUAL_REQUIRED,
-                                NULL,
-                                NULL,
-                                NULL,
-                                NULL,
-                                NULL,
-                                NULL);
-        if (status)
-                krb5_err (context, 1, status, "krb5_sendauth");
-@end example
-
-Once authentication has been performed, it is time to send some
-data. First we create a krb5_data structure, then we sign it with
-@manpage{krb5_mk_safe,3} using the @code{auth_context} that contains the
-session-key that was exchanged in the
-@manpage{krb5_sendauth,3}/@manpage{krb5_recvauth,3} authentication
-sequence.
-
-@example
-        data.data   = "hej";
-        data.length = 3;
-
-        krb5_data_zero (&packet);
-
-        status = krb5_mk_safe (context,
-                               auth_context,
-                               &data,
-                               &packet,
-                               NULL);
-        if (status)
-                krb5_err (context, 1, status, "krb5_mk_safe");
-@end example
-
-And send it over the network.
-
-@example
-        len = packet.length;
-        net_len = htonl(len);
-
-        if (krb5_net_write (context, &sock, &net_len, 4) != 4)
-                err (1, "krb5_net_write");
-        if (krb5_net_write (context, &sock, packet.data, len) != len)
-                err (1, "krb5_net_write");
-@end example
-
-To send encrypted (and signed) data @manpage{krb5_mk_priv,3} should be
-used instead. @manpage{krb5_mk_priv,3} works the same way as
-@manpage{krb5_mk_safe,3}, with the exception that it encrypts the data
-in addition to signing it.
-
-@example
-        data.data   = "hemligt";
-        data.length = 7;
-
-        krb5_data_free (&packet);
-
-        status = krb5_mk_priv (context,
-                               auth_context,
-                               &data,
-                               &packet,
-                               NULL);
-        if (status)
-                krb5_err (context, 1, status, "krb5_mk_priv");
-@end example
-
-And send it over the network.
-
-@example
-        len = packet.length;
-        net_len = htonl(len);
-
-        if (krb5_net_write (context, &sock, &net_len, 4) != 4)
-                err (1, "krb5_net_write");
-        if (krb5_net_write (context, &sock, packet.data, len) != len)
-                err (1, "krb5_net_write");
-
-@end example
-
-The server is using @manpage{krb5_rd_safe,3} and
-@manpage{krb5_rd_priv,3} to verify the signature and decrypt the packet.
-
-@node Validating a password in a server application, API differences to MIT Kerberos, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos
-@section Validating a password in an application
-
-See the manual page for @manpage{krb5_verify_user,3}.
-
-@node API differences to MIT Kerberos, File formats, Validating a password in a server application, Programming with Kerberos
-@section API differences to MIT Kerberos
-
-This section is somewhat disorganised, but so far there is no overall
-structure to the differences, though some of the have their root in
-that Heimdal uses an ASN.1 compiler and MIT doesn't.
-
-@subsection Principal and realms
-
-Heimdal stores the realm as a @code{krb5_realm}, that is a @code{char *}.
-MIT Kerberos uses a @code{krb5_data} to store a realm.
-
-In Heimdal @code{krb5_principal} doesn't contain the component
-@code{name_type}; it's instead stored in component
-@code{name.name_type}. To get and set the nametype in Heimdal, use
-@manpage{krb5_principal_get_type,3} and
-@manpage{krb5_principal_set_type,3}.
-
-For more information about principal and realms, see
-@manpage{krb5_principal,3}.
-
-@subsection Error messages
-
-To get the error string, Heimdal uses
-@manpage{krb5_get_error_string,3} or, if @code{NULL} is returned,
-@manpage{krb5_get_err_text,3}. This is to return custom error messages
-(like ``Can't find host/datan.example.com@@EXAMPLE.COM in
-/etc/krb5.conf.'' instead of a ``Key table entry not found'' that
-@manpage{error_message,3} returns.
-
-Heimdal uses a threadsafe(r) version of the com_err interface; the
-global @code{com_err} table isn't initialised.  Then
-@manpage{error_message,3} returns quite a boring error string (just
-the error code itself).
-
-
-@c @node Why you should use GSS-API for new applications, Walkthrough of a sample GSS-API client, Validating a password in a server application, Programming with Kerberos
-@c @section Why you should use GSS-API for new applications
-@c 
-@c SSPI, bah, bah, microsoft, bah, bah, almost GSS-API.
-@c 
-@c It would also be possible for other mechanisms then Kerberos, but that
-@c doesn't exist any other GSS-API implementations today.
-@c 
-@c @node Walkthrough of a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos
-@c @section Walkthrough of a sample GSS-API client
-@c 
-@c Write about how gssapi_clent.c works.
-
-@node File formats,  , API differences to MIT Kerberos, Programming with Kerberos
-@section File formats
-
-This section documents the diffrent file formats that are used in
-Heimdal and other Kerberos implementations.
-
-@subsection keytab
-
-The keytab binary format is not a standard format. The format has
-evolved and may continue to. It is however understood by several
-Kerberos implementations including Heimdal, MIT, Sun's Java ktab and
-are created by the ktpass.exe utility from Windows. So it has
-established itself as the defacto format for storing Kerberos keys.
-
-The following C-like structure definitions illustrate the MIT keytab
-file format. All values are in network byte order. All text is ASCII.
-
-@example
-  keytab @{
-      uint16_t file_format_version;                    /* 0x502 */
-      keytab_entry entries[*];
-  @};
-
-  keytab_entry @{
-      int32_t size;
-      uint16_t num_components;   /* subtract 1 if version 0x501 */
-      counted_octet_string realm;
-      counted_octet_string components[num_components];
-      uint32_t name_type;       /* not present if version 0x501 */
-      uint32_t timestamp;
-      uint8_t vno8;
-      keyblock key;
-      uint32_t vno; /* only present if >= 4 bytes left in entry */
-  @};
-
-  counted_octet_string @{
-      uint16_t length;
-      uint8_t data[length];
-  @};
-
-  keyblock @{
-      uint16_t type;
-      counted_octet_string;
-  @};
-@end example
-
-All numbers are stored in network byteorder (big endian) format.
-
-The keytab file format begins with the 16 bit file_format_version which
-at the time this document was authored is 0x502. The format of older
-keytabs is described at the end of this document.
-
-The file_format_version is immediately followed by an array of
-keytab_entry structures which are prefixed with a 32 bit size indicating
-the number of bytes that follow in the entry. Note that the size should be
-evaluated as signed. This is because a negative value indicates that the
-entry is in fact empty (e.g. it has been deleted) and that the negative
-value of that negative value (which is of course a positive value) is
-the offset to the next keytab_entry. Based on these size values alone
-the entire keytab file can be traversed.
-
-The size is followed by a 16 bit num_components field indicating the
-number of counted_octet_string components in the components array.
-
-The num_components field is followed by a counted_octet_string
-representing the realm of the principal.
-
-A counted_octet_string is simply an array of bytes prefixed with a 16
-bit length. For the realm and name components, the counted_octet_string
-bytes are ASCII encoded text with no zero terminator.
-
-Following the realm is the components array that represents the name of
-the principal. The text of these components may be joined with slashs
-to construct the typical SPN representation. For example, the service
-principal HTTP/www.foo.net@@FOO.NET would consist of name components
-"HTTP" followed by "www.foo.net".
-
-Following the components array is the 32 bit name_type (e.g. 1 is
-KRB5_NT_PRINCIPAL, 2 is KRB5_NT_SRV_INST, 5 is KRB5_NT_UID, etc). In
-practice the name_type is almost certainly 1 meaning KRB5_NT_PRINCIPAL.
-
-The 32 bit timestamp indicates the time the key was established for that
-principal. The value represents the number of seconds since Jan 1, 1970.
-
-The 8 bit vno8 field is the version number of the key. This value is
-overridden by the 32 bit vno field if it is present. The vno8 field is
-filled with the lower 8 bits of the 32 bit protocol kvno field.
-
-The keyblock structure consists of a 16 bit value indicating the
-encryption type and is a counted_octet_string containing the key.  The
-encryption type is the same as the Kerberos standard (e.g. 3 is
-des-cbc-md5, 23 is arcfour-hmac-md5, etc).
-
-The last field of the keytab_entry structure is optional. If the size of
-the keytab_entry indicates that there are at least 4 bytes remaining,
-a 32 bit value representing the key version number is present. This
-value supersedes the 8 bit vno8 value preceeding the keyblock.
-
-Older keytabs with a file_format_version of 0x501 are different in
-three ways:
-
-@table @asis
-@item All integers are in host byte order [1].
-@item The num_components field is 1 too large (i.e. after decoding, decrement by 1).
-@item The 32 bit name_type field is not present.
-@end table
-
-[1] The file_format_version field should really be treated as two
-separate 8 bit quantities representing the major and minor version
-number respectively.
-
-@subsection Heimdal database dump file
-
-Format of the Heimdal text dump file as of Heimdal 0.6.3:
-
-Each line in the dump file is one entry in the database.
-
-Each field of a line is separated by one or more spaces, with the
-exception of fields consisting of principals containing spaces, where
-space can be quoted with \ and \ is quoted by \.
-
-Fields and their types are:
-
-@example
-	Quoted princial (quote character is \) [string]
-	Keys [keys]
-	Created by [event]
-	Modified by [event optional]
-	Valid start time [time optional]
-	Valid end time [time optional]
-	Password end valid time [time optional]
-	Max lifetime of ticket [time optional]
-	Max renew time of ticket [integer optional]
-	Flags [hdb flags]
-	Generation number [generation optional]
-	Extensions [extentions optional]
-@end example
-
-Fields following these silently are ignored.
-
-All optional fields will be skipped if they fail to parse (or comprise
-the optional field marker of "-", w/o quotes).
-
-Example:
-
-@example
-fred@@EXAMPLE.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin@@EXAMPLE.COM 20041221112428:fred@@EXAMPLE.COM - - - 86400 604800 126 20020415130120:793707:28 -
-@end example
-
-Encoding of types are as follows:
-
-@table @asis
-@item keys
-
-@example
-kvno:[masterkvno:keytype:keydata:salt]@{zero or more separated by :@}
-@end example
-
-kvno is the key version number.
-
-keydata is hex-encoded
-
-masterkvno is the kvno of the database master key.  If this field is
-empty, the kadmin load and merge operations will encrypt the key data
-with the master key if there is one.  Otherwise the key data will be
-imported asis.
-
-salt is encoded as "-" (no/default salt) or
-
-@example
-salt-type /
-salt-type / "string"
-salt-type / hex-encoded-data
-@end example
-
-keytype is the protocol enctype number; see enum ENCTYPE in
-include/krb5_asn1.h for values.
-
-Example:
-@example
-27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:-
-@end example
-
-
-@example
-kvno=27,@{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., default salt@}...
-@end example
-
-@item time
-	
-Format of the time is: YYYYmmddHHMMSS, corresponding to strftime
-format "%Y%m%d%k%M%S".
-
-Time is expressed in UTC.
-
-Time can be optional (using -), when the time 0 is used.
-
-Example:
-
-@example
-20041221112428
-@end example
-
-@item event
-
-@example
-	time:principal
-@end example
-
-time is as given in format time
-
-principal is a string.  Not quoting it may not work in earlier
-versions of Heimdal.
-
-Example:
-@example
-20041221112428:bloggs@@EXAMPLE.COM
-@end example
-
-@item hdb flags
-
-Integer encoding of HDB flags, see HDBFlags in lib/hdb/hdb.asn1. Each
-bit in the integer is the same as the bit in the specification.
-
-@item generation:
-
-@example
-time:usec:gen
-@end example
-
-
-usec is a the microsecond, integer.
-gen is generation number, integer.
-
-The generation can be defaulted (using '-') or the empty string
-
-@item extensions:
-
-@example
-first-hex-encoded-HDB-Extension[:second-...]
-@end example
-
-HDB-extension is encoded the DER encoded HDB-Extension from
-lib/hdb/hdb.asn1. Consumers HDB extensions should be aware that
-unknown entires needs to be preserved even thought the ASN.1 data
-content might be unknown. There is a critical flag in the data to show
-to the KDC that the entry MUST be understod if the entry is to be
-used.
-
-@end table