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: Introduction to the Kerberos 5 API</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_introduction">Introduction to the Kerberos 5 API </a></h1><h2><a class="anchor" name="api_overview"> 24226031SstasKerberos 5 API Overview</a></h2> 25226031SstasAll 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.<h3><a class="anchor" name="intro_krb5_context"> 26226031SstasKerberos context</a></h3> 27226031SstasA kerberos context (krb5_context) holds all per thread state. All global variables that are context specific are stored in this structure, including default encryption types, credential cache (for example, a ticket file), and default realms.<p> 28226031SstasThe internals of the structure should never be accessed directly, functions exist for extracting information.<p> 29226031SstasSee the manual page for <a class="el" href="group__krb5.html#gbd94206e186c58a093975424a4a567a8">krb5_init_context()</a> how to create a context and module <a class="el" href="group__krb5.html">Heimdal Kerberos 5 library</a> for more information about the functions.<h3><a class="anchor" name="intro_krb5_auth_context"> 30226031SstasKerberos authentication context</a></h3> 31226031SstasKerberos authentication context (krb5_auth_context) holds all context related to an authenticated connection, in a similar way to the kerberos context that holds the context for the thread or process.<p> 32226031SstasThe krb5_auth_context is used by various functions that are directly related to authentication between the server/client. Example of data that this structure contains are various flags, addresses of client and server, port numbers, keyblocks (and subkeys), sequence numbers, replay cache, and checksum types.<h3><a class="anchor" name="intro_krb5_principal"> 33226031SstasKerberos principal</a></h3> 34226031SstasThe Kerberos principal is the structure that identifies a user or service in Kerberos. The structure that holds the principal is the 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.<p> 35226031SstasThe are several ways to create a principal (with different degree of portability), and one way to free it.<p> 36226031SstasSee also the page <a class="el" href="krb5_principal_intro.html">The principal handing functions.</a> for more information and also module <a class="el" href="group__krb5__principal.html">Heimdal Kerberos 5 principal functions</a>.<h3><a class="anchor" name="intro_krb5_ccache"> 37226031SstasCredential cache</a></h3> 38226031SstasA 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).<p> 39226031SstasThe 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.<p> 40226031SstasCaches are opened with <a class="el" href="group__krb5__ccache.html#ge8ab9d6f4af5710dab860f2806a7d13b">krb5_cc_resolve()</a> or created with <a class="el" href="group__krb5__ccache.html#g86c0f70d0c2b5de2d876edf4b693b5b9">krb5_cc_new_unique()</a>.<p> 41226031SstasIf the cache needs to be opened again (using <a class="el" href="group__krb5__ccache.html#ge8ab9d6f4af5710dab860f2806a7d13b">krb5_cc_resolve()</a>) <a class="el" href="group__krb5__ccache.html#gebc0dd2a77529c05fb49e27235da7017">krb5_cc_close()</a> will close the handle, but not the remove the cache. <a class="el" href="group__krb5__ccache.html#g3115bcccd71594374831caa9a07b1290">krb5_cc_destroy()</a> will zero out the cache, remove the cache so it can no longer be referenced.<p> 42226031SstasSee also <a class="el" href="krb5_ccache_intro.html">The credential cache functions</a> and <a class="el" href="group__krb5__ccache.html">Heimdal Kerberos 5 credential cache functions</a> .<h3><a class="anchor" name="intro_krb5_error_code"> 43226031SstasKerberos errors</a></h3> 44226031SstasKerberos 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''.<p> 45226031SstasThis 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.<p> 46226031SstasSee also module <a class="el" href="group__krb5__error.html">Heimdal Kerberos 5 error reporting functions</a> .<h3><a class="anchor" name="intro_krb5_keytab"> 47226031SstasKeytab management</a></h3> 48226031SstasA 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.<p> 49226031SstasKeytabs are used for servers and long-running services.<p> 50226031SstasSee also <a class="el" href="krb5_keytab_intro.html">The keytab handing functions</a> and <a class="el" href="group__krb5__keytab.html">Heimdal Kerberos 5 keytab handling functions</a> .<h3><a class="anchor" name="intro_krb5_crypto"> 51226031SstasKerberos crypto</a></h3> 52226031SstasHeimdal includes a implementation of the Kerberos crypto framework, all crypto operations. To create a crypto context call <a class="el" href="group__krb5__crypto.html#gd7003a8a81cef633cc0a2cc07c93dd32">krb5_crypto_init()</a>.<p> 53226031SstasSee also module <a class="el" href="group__krb5__crypto.html">Heimdal Kerberos 5 cryptography functions</a> .<h2><a class="anchor" name="kerberos5_client"> 54226031SstasWalkthrough of a sample Kerberos 5 client</a></h2> 55226031SstasThis example contains parts of a sample TCP Kerberos 5 clients, if you want a real working client, please look in appl/test directory in the Heimdal distribution.<p> 56226031SstasAll Kerberos error-codes that are returned from kerberos functions in this program are passed to krb5_err, that will print a descriptive text of the error code and exit. Graphical programs can convert error-code to a human readable error-string with the krb5_get_error_message() function.<p> 57226031SstasNote that you should not use any Kerberos function before <a class="el" href="group__krb5.html#gbd94206e186c58a093975424a4a567a8">krb5_init_context()</a> have completed successfully. That is the reason err() is used when <a class="el" href="group__krb5.html#gbd94206e186c58a093975424a4a567a8">krb5_init_context()</a> fails.<p> 58226031SstasFirst the client needs to call 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 implementation is failing or it's disabled on this host.<p> 59226031Sstas<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <krb5.h></span> 60226031Sstas 61226031Sstas <span class="keywordtype">int</span> 62226031Sstas main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> **argv) 63226031Sstas { 64226031Sstas krb5_context context; 65226031Sstas 66226031Sstas <span class="keywordflow">if</span> (<a class="code" href="group__krb5.html#gbd94206e186c58a093975424a4a567a8">krb5_init_context</a>(&context)) 67226031Sstas errx (1, <span class="stringliteral">"krb5_context"</span>); 68226031Sstas</pre></div><p> 69226031SstasNow the client wants to connect to the host at the other end. The preferred way of doing this is using getaddrinfo (for operating system that have this function implemented), since getaddrinfo is neutral to the address type and can use any protocol that is available.<p> 70226031Sstas<div class="fragment"><pre class="fragment"> <span class="keyword">struct </span>addrinfo *ai, *a; 71226031Sstas <span class="keyword">struct </span>addrinfo hints; 72226031Sstas <span class="keywordtype">int</span> error; 73226031Sstas 74226031Sstas memset (&hints, 0, <span class="keyword">sizeof</span>(hints)); 75226031Sstas hints.ai_socktype = SOCK_STREAM; 76226031Sstas hints.ai_protocol = IPPROTO_TCP; 77226031Sstas 78226031Sstas error = getaddrinfo (hostname, <span class="stringliteral">"pop3"</span>, &hints, &ai); 79226031Sstas <span class="keywordflow">if</span> (error) 80226031Sstas errx (1, <span class="stringliteral">"%s: %s"</span>, hostname, gai_strerror(error)); 81226031Sstas 82226031Sstas <span class="keywordflow">for</span> (a = ai; a != NULL; a = a->ai_next) { 83226031Sstas <span class="keywordtype">int</span> s; 84226031Sstas 85226031Sstas s = socket (a->ai_family, a->ai_socktype, a->ai_protocol); 86226031Sstas <span class="keywordflow">if</span> (s < 0) 87226031Sstas <span class="keywordflow">continue</span>; 88226031Sstas <span class="keywordflow">if</span> (connect (s, a->ai_addr, a->ai_addrlen) < 0) { 89226031Sstas warn (<span class="stringliteral">"connect(%s)"</span>, hostname); 90226031Sstas close (s); 91226031Sstas <span class="keywordflow">continue</span>; 92226031Sstas } 93226031Sstas freeaddrinfo (ai); 94226031Sstas ai = NULL; 95226031Sstas } 96226031Sstas <span class="keywordflow">if</span> (ai) { 97226031Sstas freeaddrinfo (ai); 98226031Sstas errx (<span class="stringliteral">"failed to contact %s"</span>, hostname); 99226031Sstas } 100226031Sstas</pre></div><p> 101226031SstasBefore authenticating, an authentication context needs to be created. This context keeps all information for one (to be) authenticated connection (see krb5_auth_context).<p> 102226031Sstas<div class="fragment"><pre class="fragment"> status = krb5_auth_con_init (context, &auth_context); 103226031Sstas <span class="keywordflow">if</span> (status) 104226031Sstas krb5_err (context, 1, status, <span class="stringliteral">"krb5_auth_con_init"</span>); 105226031Sstas</pre></div><p> 106226031SstasFor setting the address in the authentication there is a help function krb5_auth_con_setaddrs_from_fd() that does everything that is needed when given a connected file descriptor to the socket.<p> 107226031Sstas<div class="fragment"><pre class="fragment"> status = krb5_auth_con_setaddrs_from_fd (context, 108226031Sstas auth_context, 109226031Sstas &sock); 110226031Sstas <span class="keywordflow">if</span> (status) 111226031Sstas krb5_err (context, 1, status, 112226031Sstas <span class="stringliteral">"krb5_auth_con_setaddrs_from_fd"</span>); 113226031Sstas</pre></div><p> 114226031SstasThe next step is to build a server principal for the service we want to connect to. (See also <a class="el" href="group__krb5__principal.html#g8be0f5000da6ee0d4bd5dcaf3cb01d08">krb5_sname_to_principal()</a>.)<p> 115226031Sstas<div class="fragment"><pre class="fragment"> status = <a class="code" href="group__krb5__principal.html#g8be0f5000da6ee0d4bd5dcaf3cb01d08">krb5_sname_to_principal</a> (context, 116226031Sstas hostname, 117226031Sstas service, 118226031Sstas KRB5_NT_SRV_HST, 119226031Sstas &server); 120226031Sstas <span class="keywordflow">if</span> (status) 121226031Sstas krb5_err (context, 1, status, <span class="stringliteral">"krb5_sname_to_principal"</span>); 122226031Sstas</pre></div><p> 123226031SstasThe client principal is not passed to krb5_sendauth() function, this causes the krb5_sendauth() function to try to figure it out itself.<p> 124226031SstasThe server program is using the function krb5_recvauth() to receive the Kerberos 5 authenticator.<p> 125226031SstasIn 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).<p> 126226031SstasIf you are using a non-blocking socket you will need to do all work of krb5_sendauth() yourself. Basically you need to send over the authenticator from krb5_mk_req() and, in case of mutual authentication, verifying the result from the server with krb5_rd_rep().<p> 127226031Sstas<div class="fragment"><pre class="fragment"> status = krb5_sendauth (context, 128226031Sstas &auth_context, 129226031Sstas &sock, 130226031Sstas VERSION, 131226031Sstas NULL, 132226031Sstas server, 133226031Sstas AP_OPTS_MUTUAL_REQUIRED, 134226031Sstas NULL, 135226031Sstas NULL, 136226031Sstas NULL, 137226031Sstas NULL, 138226031Sstas NULL, 139226031Sstas NULL); 140226031Sstas <span class="keywordflow">if</span> (status) 141226031Sstas krb5_err (context, 1, status, <span class="stringliteral">"krb5_sendauth"</span>); 142226031Sstas</pre></div><p> 143226031SstasOnce authentication has been performed, it is time to send some data. First we create a krb5_data structure, then we sign it with krb5_mk_safe() using the auth_context that contains the session-key that was exchanged in the krb5_sendauth()/krb5_recvauth() authentication sequence.<p> 144226031Sstas<div class="fragment"><pre class="fragment"> data.data = <span class="stringliteral">"hej"</span>; 145226031Sstas data.length = 3; 146226031Sstas 147226031Sstas <a class="code" href="group__krb5.html#ga059e96dde4e0b8c082eb6f3d570b7bc">krb5_data_zero</a> (&packet); 148226031Sstas 149226031Sstas status = krb5_mk_safe (context, 150226031Sstas auth_context, 151226031Sstas &data, 152226031Sstas &packet, 153226031Sstas NULL); 154226031Sstas <span class="keywordflow">if</span> (status) 155226031Sstas krb5_err (context, 1, status, <span class="stringliteral">"krb5_mk_safe"</span>); 156226031Sstas</pre></div><p> 157226031SstasAnd send it over the network.<p> 158226031Sstas<div class="fragment"><pre class="fragment"> len = packet.length; 159226031Sstas net_len = htonl(len); 160226031Sstas 161226031Sstas <span class="keywordflow">if</span> (krb5_net_write (context, &sock, &net_len, 4) != 4) 162226031Sstas err (1, <span class="stringliteral">"krb5_net_write"</span>); 163226031Sstas <span class="keywordflow">if</span> (krb5_net_write (context, &sock, packet.data, len) != len) 164226031Sstas err (1, <span class="stringliteral">"krb5_net_write"</span>); 165226031Sstas</pre></div><p> 166226031SstasTo send encrypted (and signed) data krb5_mk_priv() should be used instead. krb5_mk_priv() works the same way as krb5_mk_safe(), with the exception that it encrypts the data in addition to signing it.<p> 167226031Sstas<div class="fragment"><pre class="fragment"> data.data = <span class="stringliteral">"hemligt"</span>; 168226031Sstas data.length = 7; 169226031Sstas 170226031Sstas <a class="code" href="group__krb5.html#gb4b80ac7a8bbab89fe947ae1c7828ea8">krb5_data_free</a> (&packet); 171226031Sstas 172226031Sstas status = krb5_mk_priv (context, 173226031Sstas auth_context, 174226031Sstas &data, 175226031Sstas &packet, 176226031Sstas NULL); 177226031Sstas <span class="keywordflow">if</span> (status) 178226031Sstas krb5_err (context, 1, status, <span class="stringliteral">"krb5_mk_priv"</span>); 179226031Sstas</pre></div><p> 180226031SstasAnd send it over the network.<p> 181226031Sstas<div class="fragment"><pre class="fragment"> len = packet.length; 182226031Sstas net_len = htonl(len); 183226031Sstas 184226031Sstas <span class="keywordflow">if</span> (krb5_net_write (context, &sock, &net_len, 4) != 4) 185226031Sstas err (1, <span class="stringliteral">"krb5_net_write"</span>); 186226031Sstas <span class="keywordflow">if</span> (krb5_net_write (context, &sock, packet.data, len) != len) 187226031Sstas err (1, <span class="stringliteral">"krb5_net_write"</span>); 188226031Sstas</pre></div><p> 189226031SstasThe server is using krb5_rd_safe() and krb5_rd_priv() to verify the signature and decrypt the packet.<h2><a class="anchor" name="intro_krb5_verify_user"> 190226031SstasValidating a password in an application</a></h2> 191226031SstasSee the manual page for krb5_verify_user().<h2><a class="anchor" name="mit_differences"> 192226031SstasAPI differences to MIT Kerberos</a></h2> 193226031SstasThis 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.<h3><a class="anchor" name="mit_krb5_principal"> 194226031SstasPrincipal and realms</a></h3> 195226031SstasHeimdal stores the realm as a krb5_realm, that is a char *. MIT Kerberos uses a krb5_data to store a realm.<p> 196226031SstasIn Heimdal krb5_principal doesn't contain the component name_type; it's instead stored in component name.name_type. To get and set the nametype in Heimdal, use <a class="el" href="group__krb5__principal.html#gf4a599c42592ff7485753e80b8de67b7">krb5_principal_get_type()</a> and <a class="el" href="group__krb5__principal.html#g28b750b990452f02922bc74a6cac0313">krb5_principal_set_type()</a>.<p> 197226031SstasFor more information about principal and realms, see krb5_principal.<h3><a class="anchor" name="mit_krb5_error_code"> 198226031SstasError messages</a></h3> 199226031SstasTo get the error string, Heimdal uses krb5_get_error_message(). This is to return custom error messages (like ``Can't find host/datan.example.com@CODE.COM in /etc/krb5.conf.'' instead of a ``Key table entry not found'' that error_message returns.<p> 200226031SstasHeimdal uses a threadsafe(r) version of the com_err interface; the global com_err table isn't initialised. Then error_message returns quite a boring error string (just the error code itself). </div> 201226031Sstas<hr size="1"><address style="text-align: right;"><small> 202234027SstasGenerated 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> 203226031Sstas</body> 204226031Sstas</html> 205
