diff --git a/doc/programming.texi b/doc/programming.texi index 5be6ec8e2..4ec1c6ca8 100644 --- a/doc/programming.texi +++ b/doc/programming.texi @@ -11,6 +11,7 @@ introduction text (@pxref{What is Kerberos?}). * 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 @@ -113,6 +114,9 @@ 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}. @@ -337,7 +341,7 @@ The server is using @manpage{krb5_rd_safe,3} and See the manual page for @manpage{krb5_verify_user,3}. -@node API differences to MIT Kerberos, , 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 @@ -385,3 +389,252 @@ the error code itself). @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 different 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 + +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