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