1226031Sstas<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2226031Sstas<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> 3226031Sstas<title>HeimdalKerberos5library: File formats</title> 4226031Sstas<link href="doxygen.css" rel="stylesheet" type="text/css"> 5226031Sstas<link href="tabs.css" rel="stylesheet" type="text/css"> 6226031Sstas</head><body> 7226031Sstas<p> 8226031Sstas<a href="http://www.h5l.org/"><img src="http://www.h5l.org/keyhole-heimdal.png" alt="keyhole logo"/></a> 9226031Sstas</p> 10226031Sstas<!-- end of header marker --> 11226031Sstas<!-- Generated by Doxygen 1.5.6 --> 12226031Sstas<div class="navigation" id="top"> 13226031Sstas <div class="tabs"> 14226031Sstas <ul> 15226031Sstas <li><a href="index.html"><span>Main Page</span></a></li> 16226031Sstas <li><a href="pages.html"><span>Related Pages</span></a></li> 17226031Sstas <li><a href="modules.html"><span>Modules</span></a></li> 18226031Sstas <li><a href="annotated.html"><span>Data Structures</span></a></li> 19226031Sstas </ul> 20226031Sstas </div> 21226031Sstas</div> 22226031Sstas<div class="contents"> 23226031Sstas<h1><a class="anchor" name="krb5_fileformats">File formats </a></h1><h2><a class="anchor" name="fileformats"> 24226031SstasFile formats</a></h2> 25226031SstasThis section documents the diffrent file formats that are used in Heimdal and other Kerberos implementations.<h3><a class="anchor" name="file_keytab"> 26226031Sstaskeytab</a></h3> 27226031SstasThe 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> 28226031SstasThe following C-like structure definitions illustrate the MIT keytab file format. All values are in network byte order. All text is ASCII.<p> 29226031Sstas<div class="fragment"><pre class="fragment"> keytab { 30226031Sstas uint16_t file_format_version; # 0x502 31226031Sstas keytab_entry entries[*]; 32226031Sstas }; 33226031Sstas 34226031Sstas keytab_entry { 35226031Sstas int32_t size; 36226031Sstas uint16_t num_components; # subtract 1 <span class="keywordflow">if</span> version 0x501 37226031Sstas counted_octet_string realm; 38226031Sstas counted_octet_string components[num_components]; 39226031Sstas uint32_t name_type; # not present <span class="keywordflow">if</span> version 0x501 40226031Sstas uint32_t timestamp; 41226031Sstas uint8_t vno8; 42226031Sstas keyblock key; 43226031Sstas uint32_t vno; #only present <span class="keywordflow">if</span> >= 4 bytes left in entry 44226031Sstas uint32_t flags; #only present <span class="keywordflow">if</span> >= 4 bytes left in entry 45226031Sstas }; 46226031Sstas 47226031Sstas counted_octet_string { 48226031Sstas uint16_t length; 49226031Sstas uint8_t data[length]; 50226031Sstas }; 51226031Sstas 52226031Sstas keyblock { 53226031Sstas uint16_t type; 54226031Sstas counted_octet_string; 55226031Sstas }; 56226031Sstas</pre></div><p> 57226031SstasAll numbers are stored in network byteorder (big endian) format.<p> 58226031SstasThe 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> 59226031SstasThe 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> 60226031SstasThe size is followed by a 16 bit num_components field indicating the number of counted_octet_string components in the components array.<p> 61226031SstasThe num_components field is followed by a counted_octet_string representing the realm of the principal.<p> 62226031SstasA 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> 63226031SstasFollowing 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> 64226031SstasFollowing 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> 65226031SstasThe 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> 66226031SstasThe 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> 67226031SstasThe 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> 68226031SstasThe 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> 69226031SstasOlder keytabs with a file_format_version of 0x501 are different in three ways:<p> 70226031Sstas<ul> 71226031Sstas<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> 72226031Sstas<p> 73226031Sstas[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"> 74226031SstasHeimdal database dump file</a></h3> 75226031SstasFormat of the Heimdal text dump file as of Heimdal 0.6.3:<p> 76226031SstasEach line in the dump file is one entry in the database.<p> 77226031SstasEach 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> 78226031SstasFields and their types are:<p> 79226031Sstas<div class="fragment"><pre class="fragment"> Quoted princial (quote character is \) [string] 80226031Sstas Keys [keys] 81226031Sstas Created by [event] 82226031Sstas Modified by [<span class="keyword">event</span> optional] 83226031Sstas Valid start time [time optional] 84226031Sstas Valid end time [time optional] 85226031Sstas Password end valid time [time optional] 86226031Sstas Max lifetime of ticket [time optional] 87226031Sstas Max renew time of ticket [integer optional] 88226031Sstas Flags [hdb flags] 89226031Sstas Generation number [generation optional] 90226031Sstas Extensions [extentions optional] 91226031Sstas</pre></div><p> 92226031SstasFields following these silently are ignored.<p> 93226031SstasAll optional fields will be skipped if they fail to parse (or comprise the optional field marker of "-", w/o quotes).<p> 94226031SstasExample:<p> 95226031Sstas<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 - 96226031Sstas</pre></div><p> 97226031SstasEncoding of types are as follows:<p> 98226031Sstas<ul> 99226031Sstas<li>keys</li></ul> 100226031Sstas<p> 101226031Sstas<div class="fragment"><pre class="fragment"> kvno:[masterkvno:keytype:keydata:salt]{zero or more separated by :} 102226031Sstas</pre></div><p> 103226031Sstaskvno is the key version number.<p> 104226031Sstaskeydata is hex-encoded<p> 105226031Sstasmasterkvno 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> 106226031Sstassalt is encoded as "-" (no/default salt) or<p> 107226031Sstas<div class="fragment"><pre class="fragment"> salt-type / 108226031Sstas salt-type / <span class="stringliteral">"string"</span> 109226031Sstas salt-type / hex-encoded-data 110226031Sstas</pre></div><p> 111226031Sstaskeytype is the protocol enctype number; see enum ENCTYPE in include/krb5_asn1.h for values.<p> 112226031SstasExample: <div class="fragment"><pre class="fragment"> 27:1:16:e8b4c8fc7e60b9e641dcf4cff3f08a701d982a2f89ba373733d26ca59ba6c789666f6b8bfcf169412bb1e5dceb9b33cda29f3412:-:1:3:4498a933881178c744f4232172dcd774c64e81fa6d05ecdf643a7e390624a0ebf3c7407a:-:1:2:b01934b13eb795d76f3a80717d469639b4da0cfb644161340ef44fdeb375e54d684dbb85:-:1:1:ea8e16d8078bf60c781da90f508d4deccba70595258b9d31888d33987cd31af0c9cced2e:- 113226031Sstas</pre></div><p> 114226031Sstas<div class="fragment"><pre class="fragment"> kvno=27,{key: masterkvno=1,keytype=des3-cbc-sha1,keydata=..., <span class="keywordflow">default</span> salt}... 115226031Sstas</pre></div><p> 116226031Sstas<ul> 117226031Sstas<li>time</li></ul> 118226031Sstas<p> 119226031SstasFormat of the time is: YYYYmmddHHMMSS, corresponding to strftime format "%Y%m%d%k%M%S".<p> 120226031SstasTime is expressed in UTC.<p> 121226031SstasTime can be optional (using -), when the time 0 is used.<p> 122226031SstasExample:<p> 123226031Sstas<div class="fragment"><pre class="fragment"> 20041221112428 124226031Sstas</pre></div><p> 125226031Sstas<ul> 126226031Sstas<li>event</li></ul> 127226031Sstas<p> 128226031Sstas<div class="fragment"><pre class="fragment"> time:principal 129226031Sstas</pre></div><p> 130226031Sstastime is as given in format time<p> 131226031Sstasprincipal is a string. Not quoting it may not work in earlier versions of Heimdal.<p> 132226031SstasExample: <div class="fragment"><pre class="fragment"> 20041221112428:bloggs\@CODE.COM 133226031Sstas</pre></div><p> 134226031Sstas<ul> 135226031Sstas<li>hdb flags</li></ul> 136226031Sstas<p> 137226031SstasInteger 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> 138226031Sstas<ul> 139226031Sstas<li>generation:</li></ul> 140226031Sstas<p> 141226031Sstas<div class="fragment"><pre class="fragment"> time:usec:gen 142226031Sstas</pre></div><p> 143226031Sstasusec is a the microsecond, integer. gen is generation number, integer.<p> 144226031SstasThe generation can be defaulted (using '-') or the empty string<p> 145226031Sstas<ul> 146226031Sstas<li>extensions:</li></ul> 147226031Sstas<p> 148226031Sstas<div class="fragment"><pre class="fragment"> first-hex-encoded-HDB-Extension[:second-...] 149226031Sstas</pre></div><p> 150226031SstasHDB-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> 151226031Sstas<hr size="1"><address style="text-align: right;"><small> 152234027SstasGenerated 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> 153226031Sstas</body> 154226031Sstas</html> 155
