1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> 3<title>HeimdalKerberos5library: File formats</title> 4<link href="doxygen.css" rel="stylesheet" type="text/css"> 5<link href="tabs.css" rel="stylesheet" type="text/css"> 6</head><body> 7<p> 8<a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a> 9</p> 10<!-- end of header marker --> 11<!-- Generated by Doxygen 1.5.6 --> 12<div class="navigation" id="top"> 13 <div class="tabs"> 14 <ul> 15 <li><a href="index.html"><span>Main Page</span></a></li> 16 <li><a href="pages.html"><span>Related Pages</span></a></li> 17 <li><a href="modules.html"><span>Modules</span></a></li> 18 <li><a href="annotated.html"><span>Data Structures</span></a></li> 19 </ul> 20 </div> 21</div> 22<div class="contents"> 23<h1><a class="anchor" name="krb5_fileformats">File formats </a></h1><h2><a class="anchor" name="fileformats"> 24File formats</a></h2> 25This section documents the diffrent file formats that are used in Heimdal and other Kerberos implementations.<h3><a class="anchor" name="file_keytab"> 26keytab</a></h3> 27The 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.<p> 28The following C-like structure definitions illustrate the MIT keytab file format. All values are in network byte order. All text is ASCII.<p> 29<div class="fragment"><pre class="fragment"> keytab { 30 uint16_t file_format_version; # 0x502 31 keytab_entry entries[*]; 32 }; 33 34 keytab_entry { 35 int32_t size; 36 uint16_t num_components; # subtract 1 <span class="keywordflow">if</span> version 0x501 37 counted_octet_string realm; 38 counted_octet_string components[num_components]; 39 uint32_t name_type; # not present <span class="keywordflow">if</span> version 0x501 40 uint32_t timestamp; 41 uint8_t vno8; 42 keyblock key; 43 uint32_t vno; #only present <span class="keywordflow">if</span> >= 4 bytes left in entry 44 uint32_t flags; #only present <span class="keywordflow">if</span> >= 4 bytes left in entry 45 }; 46 47 counted_octet_string { 48 uint16_t length; 49 uint8_t data[length]; 50 }; 51 52 keyblock { 53 uint16_t type; 54 counted_octet_string; 55 }; 56</pre></div><p> 57All numbers are stored in network byteorder (big endian) format.<p> 58The 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.<p> 59The 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.<p> 60The size is followed by a 16 bit num_components field indicating the number of counted_octet_string components in the components array.<p> 61The num_components field is followed by a counted_octet_string representing the realm of the principal.<p> 62A 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.<p> 63Following 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".<p> 64Following 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.<p> 65The 32 bit timestamp indicates the time the key was established for that principal. The value represents the number of seconds since Jan 1, 1970.<p> 66The 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.<p> 67The 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).<p> 68The 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.<p> 69Older keytabs with a file_format_version of 0x501 are different in three ways:<p> 70<ul> 71<li>All integers are in host byte order [1].</li><li>The num_components field is 1 too large (i.e. after decoding, decrement by 1).</li><li>The 32 bit name_type field is not present.</li></ul> 72<p> 73[1] The file_format_version field should really be treated as two separate 8 bit quantities representing the major and minor version number respectively.<h3><a class="anchor" name="file_hdb_dump"> 74Heimdal database dump file</a></h3> 75Format of the Heimdal text dump file as of Heimdal 0.6.3:<p> 76Each line in the dump file is one entry in the database.<p> 77Each 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 \.<p> 78Fields and their types are:<p> 79<div class="fragment"><pre class="fragment"> Quoted princial (quote character is \) [string] 80 Keys [keys] 81 Created by [event] 82 Modified by [<span class="keyword">event</span> optional] 83 Valid start time [time optional] 84 Valid end time [time optional] 85 Password end valid time [time optional] 86 Max lifetime of ticket [time optional] 87 Max renew time of ticket [integer optional] 88 Flags [hdb flags] 89 Generation number [generation optional] 90 Extensions [extentions optional] 91</pre></div><p> 92Fields following these silently are ignored.<p> 93All optional fields will be skipped if they fail to parse (or comprise the optional field marker of "-", w/o quotes).<p> 94Example:<p> 95<div class="fragment"><pre class="fragment"> fred\@CODE.COM 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 20020415130120:admin\@CODE.COM 20041221112428:fred\@CODE.COM - - - 86400 604800 126 20020415130120:793707:28 - 96</pre></div><p> 97Encoding of types are as follows:<p> 98<ul> 99<li>keys</li></ul> 100<p> 101<div class="fragment"><pre class="fragment"> kvno:[masterkvno:keytype:keydata:salt]{zero or more separated by :} 102</pre></div><p> 103kvno is the key version number.<p> 104keydata is hex-encoded<p> 105masterkvno 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.<p> 106salt is encoded as "-" (no/default salt) or<p> 107<div class="fragment"><pre class="fragment"> salt-type / 108 salt-type / <span class="stringliteral">"string"</span> 109 salt-type / hex-encoded-data 110</pre></div><p> 111keytype is the protocol enctype number; see enum ENCTYPE in include/krb5_asn1.h for values.<p> 112Example: <div class="fragment"><pre class="fragment"> 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 113</pre></div><p> 114<div class="fragment"><pre class="fragment"> kvno=27,{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., <span class="keywordflow">default</span> salt}... 115</pre></div><p> 116<ul> 117<li>time</li></ul> 118<p> 119Format of the time is: YYYYmmddHHMMSS, corresponding to strftime format "%Y%m%d%k%M%S".<p> 120Time is expressed in UTC.<p> 121Time can be optional (using -), when the time 0 is used.<p> 122Example:<p> 123<div class="fragment"><pre class="fragment"> 20041221112428 124</pre></div><p> 125<ul> 126<li>event</li></ul> 127<p> 128<div class="fragment"><pre class="fragment"> time:principal 129</pre></div><p> 130time is as given in format time<p> 131principal is a string. Not quoting it may not work in earlier versions of Heimdal.<p> 132Example: <div class="fragment"><pre class="fragment"> 20041221112428:bloggs\@CODE.COM 133</pre></div><p> 134<ul> 135<li>hdb flags</li></ul> 136<p> 137Integer 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.<p> 138<ul> 139<li>generation:</li></ul> 140<p> 141<div class="fragment"><pre class="fragment"> time:usec:gen 142</pre></div><p> 143usec is a the microsecond, integer. gen is generation number, integer.<p> 144The generation can be defaulted (using '-') or the empty string<p> 145<ul> 146<li>extensions:</li></ul> 147<p> 148<div class="fragment"><pre class="fragment"> first-hex-encoded-HDB-Extension[:second-...] 149</pre></div><p> 150HDB-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. </div> 151<hr size="1"><address style="text-align: right;"><small> 152Generated on Wed Jan 11 14:07:47 2012 for HeimdalKerberos5library by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6</small></address> 153</body> 154</html> 155
