diff options
Diffstat (limited to 'crypto/heimdal/doc/programming.texi')
| -rw-r--r-- | crypto/heimdal/doc/programming.texi | 407 |
1 files changed, 381 insertions, 26 deletions
diff --git a/crypto/heimdal/doc/programming.texi b/crypto/heimdal/doc/programming.texi index 63f0715..528348b 100644 --- a/crypto/heimdal/doc/programming.texi +++ b/crypto/heimdal/doc/programming.texi @@ -1,37 +1,36 @@ -@c $Id: programming.texi,v 1.2.8.1 2003/04/24 11:55:45 lha Exp $ +@c $Id: programming.texi 22071 2007-11-14 20:04:50Z lha $ -@node Programming with Kerberos +@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?}). -@macro manpage{man, section} -@cite{\man\(\section\)} -@end macro - @menu * Kerberos 5 API Overview:: -* Walkthru a sample Kerberos 5 client:: +* 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, Walkthru a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos +@node Kerberos 5 API Overview, Walkthrough of a sample Kerberos 5 client, Programming with Kerberos, Programming with Kerberos @section Kerberos 5 API Overview -Most functions are documenteded in manual pages. This overview only -tries to point to where to look for a specific function. +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 struture, including default -encryption types, credential-cache (ticket file), and default realms. +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 authenication context +@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 @@ -45,16 +44,85 @@ 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} -@node Walkthru a sample Kerberos 5 client, Validating a password in a server application, Kerberos 5 API Overview, Programming with Kerberos -@section Walkthru a sample Kerberos 5 client +@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 @@ -63,17 +131,17 @@ 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 humal readable error-string with the +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 -reson @code{err()} is used when @code{krb5_init_context()} fails. +reason @code{err()} is used when @code{krb5_init_context()} fails. -First the client needs to call @code{krb5_init_context} to initialize +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 implemtation is failing or its disabled on +that either the Kerberos implementation is failing or it's disabled on this host. @example @@ -137,7 +205,7 @@ connection (see @manpage{krb5_auth_context,3}). @end example For setting the address in the authentication there is a help function -@code{krb5_auth_con_setaddrs_from_fd} that does everthing that is needed +@code{krb5_auth_con_setaddrs_from_fd} that does everything that is needed when given a connected file descriptor to the socket. @example @@ -169,8 +237,8 @@ out itself. The server program is using the function @manpage{krb5_recvauth,3} to receive the Kerberos 5 authenticator. -In this case, mutual authenication will be tried. That means that the server -will authenticate to the client. Using mutual authenication +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). @@ -268,12 +336,48 @@ And send it over the network. 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, , Walkthru a sample Kerberos 5 client, Programming with Kerberos +@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}. -@c @node Why you should use GSS-API for new applications, Walkthru a sample GSS-API client, Validating a password in a server application, Programming with Kerberos +@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. @@ -281,7 +385,258 @@ See the manual page for @manpage{krb5_verify_user,3}. @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 Walkthru a sample GSS-API client, , Why you should use GSS-API for new applications, Programming with Kerberos -@c @section Walkthru a sample GSS-API client +@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 |
