</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<h2>Functions</h2>
<ul>
<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9">kim_ccache_create_new</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Acquire a new initial credential and store it in a ccache. <a href="#gcdc80c9bfa368eca7cc2d3710b4c0fa9"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce">kim_ccache_create_new_if_needed</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential. <a href="#g52fa72130f4ba6de8cce1224578102ce"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d">kim_ccache_create_from_client_identity</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity)
+<dl class="el"><dd class="mdescRight">Acquire a new initial credential and store it in a ccache. <a href="#gcdc80c9bfa368eca7cc2d3710b4c0fa9"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#ge796642d7eb76bc05142ad8112d398e5">kim_ccache_create_new_with_password</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_password)
+<dl class="el"><dd class="mdescRight">Acquire a new initial credential and store it in a ccache using the provided password.. <a href="#ge796642d7eb76bc05142ad8112d398e5"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce">kim_ccache_create_new_if_needed</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
+<dl class="el"><dd class="mdescRight">Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential. <a href="#g52fa72130f4ba6de8cce1224578102ce"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g462285a95435cf403b0330be13a515d7">kim_ccache_create_new_if_needed_with_password</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_password)
+<dl class="el"><dd class="mdescRight">Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential using the provided password. <a href="#g462285a95435cf403b0330be13a515d7"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d">kim_ccache_create_from_client_identity</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity)
<dl class="el"><dd class="mdescRight">Find a ccache for a client identity in the cache collection. <a href="#g6ecc14b94ffb57ca8008d0a407bb9c7d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g15cb7e1b9069a610030211cecc5e6232">kim_ccache_create_from_keytab</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab)
<dl class="el"><dd class="mdescRight">Acquire a new initial credential from a keytab and store it in a ccache. <a href="#g15cb7e1b9069a610030211cecc5e6232"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#g137761ce872ca756c08e7c31e4101df5">kim_ccache_create_from_default</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache)
<dl class="el"><dd class="mdescRight">Get the default ccache. <a href="#g137761ce872ca756c08e7c31e4101df5"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__ccache__reference.html#geeb02fbd667cfb75455653cf9b8b4a5a">kim_ccache_create_from_display_name</a> (<a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> *out_ccache, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_display_name)
<tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition. </td></tr>
</table>
</dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="ge796642d7eb76bc05142ad8112d398e5"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_create_new_with_password" ref="ge796642d7eb76bc05142ad8112d398e5" args="(kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options, kim_string in_password)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_ccache_create_new_with_password </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> * </td>
+ <td class="paramname"> <em>out_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
+ <td class="paramname"> <em>in_client_identity</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> </td>
+ <td class="paramname"> <em>in_options</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
+ <td class="paramname"> <em>in_password</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Acquire a new initial credential and store it in a ccache using the provided password..
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>out_ccache</em> </td><td>on exit, a new cache object for a ccache containing a newly acquired initial credential. Must be freed with <a class="el" href="group__kim__ccache__reference.html#g6c6be543e0ea2b518612be4255e15b9a" title="Free memory associated with a ccache.">kim_ccache_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_client_identity</em> </td><td>a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to allow the user to choose. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_password</em> </td><td>a password to be used while obtaining credentials. </td></tr>
+ </table>
+</dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#ge796642d7eb76bc05142ad8112d398e5" title="Acquire a new initial credential and store it in a ccache using the provided password...">kim_ccache_create_new_with_password()</a> exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin). </dd></dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
</div>
<tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition (if a credential is acquired). </td></tr>
</table>
</dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="g462285a95435cf403b0330be13a515d7"></a><!-- doxytag: member="kim_ccache.h::kim_ccache_create_new_if_needed_with_password" ref="g462285a95435cf403b0330be13a515d7" args="(kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options, kim_string in_password)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_ccache_create_new_if_needed_with_password </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gaecf0d1ae48c995038dd20b21e3781c2">kim_ccache</a> * </td>
+ <td class="paramname"> <em>out_ccache</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
+ <td class="paramname"> <em>in_client_identity</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> </td>
+ <td class="paramname"> <em>in_options</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
+ <td class="paramname"> <em>in_password</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential using the provided password.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>out_ccache</em> </td><td>on exit, a ccache object for a ccache containing a newly acquired initial credential. Must be freed with <a class="el" href="group__kim__ccache__reference.html#g6c6be543e0ea2b518612be4255e15b9a" title="Free memory associated with a ccache.">kim_ccache_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_client_identity</em> </td><td>a client identity to obtain a credential for. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition (if a credential is acquired). </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_password</em> </td><td>a password to be used while obtaining credentials. </td></tr>
+ </table>
+</dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#g462285a95435cf403b0330be13a515d7" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed_with_password()</a> exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin). </dd></dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
</div>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>out_ccache</em> </td><td>on exit, a ccache object for a ccache containing a TGT credential. Must be freed with <a class="el" href="group__kim__ccache__reference.html#g6c6be543e0ea2b518612be4255e15b9a" title="Free memory associated with a ccache.">kim_ccache_free()</a>. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_client_identity</em> </td><td>a client identity to obtain a credential for. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_client_identity</em> </td><td>a client identity to find a ccache for. If <em>in_client_identity</em> is <a class="el" href="group__kim__types__reference.html#g322f65f7d72470d57e21a4c8777ee9fb">KIM_IDENTITY_ANY</a>, this function returns the default ccache (ie: is equivalent to <a class="el" href="group__kim__ccache__reference.html#g137761ce872ca756c08e7c31e4101df5" title="Get the default ccache.">kim_ccache_create_from_default()</a>). </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<h2>Functions</h2>
<ul>
<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814">kim_credential_create_new</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Acquire a new initial credential. <a href="#ga02a96b9ad6fbc64007f741fa21c8814"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g42c9498e4e928fce495867a1d1835dc3">kim_credential_create_from_keytab</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab)
+<dl class="el"><dd class="mdescRight">Acquire a new initial credential. <a href="#ga02a96b9ad6fbc64007f741fa21c8814"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g5a91166863595b457a2c98e622f0c526">kim_credential_create_new_with_password</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_client_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_password)
+<dl class="el"><dd class="mdescRight">Acquire a new initial credential using the provided password. <a href="#g5a91166863595b457a2c98e622f0c526"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g42c9498e4e928fce495867a1d1835dc3">kim_credential_create_from_keytab</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab)
<dl class="el"><dd class="mdescRight">Acquire a new initial credential from a keytab. <a href="#g42c9498e4e928fce495867a1d1835dc3"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g5a65ab2a4209ee727d2a08ba8481dd8f">kim_credential_create_from_krb5_creds</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, krb5_context in_krb5_context, krb5_creds *in_krb5_creds)
<dl class="el"><dd class="mdescRight">Copy a credential from a krb5 credential object. <a href="#g5a65ab2a4209ee727d2a08ba8481dd8f"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#gecf207628b94739322344678486b45d2">kim_credential_copy</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *out_credential, <a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential)
<dl class="el"><dd class="mdescRight">Copy a credential object. <a href="#gecf207628b94739322344678486b45d2"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__credential__reference.html#g5ccc2fc794ea3bf3dc947c8a3ccd1077">kim_credential_get_krb5_creds</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, krb5_context in_krb5_context, krb5_creds **out_krb5_creds)
<tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition. </td></tr>
</table>
</dl>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>Depending on the kim_options specified, <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> may present a GUI or command line prompt to obtain information from the user. </dd></dl>
+<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
+<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new</a> </dd></dl>
+
+</div>
+</div><p>
+<a class="anchor" name="g5a91166863595b457a2c98e622f0c526"></a><!-- doxytag: member="kim_credential.h::kim_credential_create_new_with_password" ref="g5a91166863595b457a2c98e622f0c526" args="(kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options, kim_string in_password)" -->
+<div class="memitem">
+<div class="memproto">
+ <table class="memname">
+ <tr>
+ <td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_credential_create_new_with_password </td>
+ <td>(</td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> * </td>
+ <td class="paramname"> <em>out_credential</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> </td>
+ <td class="paramname"> <em>in_client_identity</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> </td>
+ <td class="paramname"> <em>in_options</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> </td>
+ <td class="paramname"> <em>in_password</em></td><td> </td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>)</td>
+ <td></td><td></td><td width="100%"></td>
+ </tr>
+ </table>
+</div>
+<div class="memdoc">
+
+<p>
+Acquire a new initial credential using the provided password.
+<p>
+<dl compact><dt><b>Parameters:</b></dt><dd>
+ <table border="0" cellspacing="2" cellpadding="0">
+ <tr><td valign="top"></td><td valign="top"><em>out_credential</em> </td><td>on exit, a new credential object containing a newly acquired initial credential. Must be freed with <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845" title="Free memory associated with a credential object.">kim_credential_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_client_identity</em> </td><td>a client identity to obtain a credential for. Specify NULL to allow the user to choose the identity </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>options to control credential acquisition. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_password</em> </td><td>a password to be used while obtaining the credential. </td></tr>
+ </table>
+</dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#g5a91166863595b457a2c98e622f0c526" title="Acquire a new initial credential using the provided password.">kim_credential_create_new_with_password()</a> exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin). </dd></dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new</a> </dd></dl>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<p>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
- <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, a new options object which is a copy of <em>in_options</em>. Must be freed with <a class="el" href="group__kim__options__reference.html#gd8de9ea0a4eb9e0ffb8e3056a3899f55" title="Free memory associated with an options object.">kim_options_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, a new options object which is a copy of <em>in_options</em>. Must be freed with <a class="el" href="group__kim__options__reference.html#gd8de9ea0a4eb9e0ffb8e3056a3899f55" title="Free memory associated with an options object.">kim_options_free()</a>. If passed KIM_OPTIONS_DEFAULT will set <em>out_options</em> to KIM_OPTIONS_DEFAULT. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>a options object. </td></tr>
</table>
</dl>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<dl compact><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>in_preferences</em> </td><td>a preferences object. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, the options specified in <em>in_preferences</em>. Must be freed with <a class="el" href="group__kim__options__reference.html#gd8de9ea0a4eb9e0ffb8e3056a3899f55" title="Free memory associated with an options object.">kim_options_free()</a>. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_options</em> </td><td>on exit, the options specified in <em>in_preferences</em>. M
ay be KIM_OPTIONS_DEFAULT. If not, must be freed with <a class="el" href="group__kim__options__reference.html#gd8de9ea0a4eb9e0ffb8e3056a3899f55" title="Free memory associated with an options object.">kim_options_free()</a>. </td></tr>
</table>
</dl>
<dl class="return" compact><dt><b>Returns:</b></dt><dd>On success, <a class="el" href="group__kim__types__reference.html#g8712727bab9e6b02712a8a01285441d1">KIM_NO_ERROR</a>. On failure, an error code representing the failure. </dd></dl>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<ul>
<li><a class="el" href="group__kim__types__reference.html">KIM Types and Constants</a> </li>
</ul>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
Acquiring New Credentials in a CCache</a></h2>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a> API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying <a class="el" href="group__kim__types__reference.html#g322f65f7d72470d57e21a4c8777ee9fb">KIM_IDENTITY_ANY</a> to allow the user to choose. Typically callers of this API obtain the client identity using <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a>. Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a> may present a GUI or command line prompt to obtain information from the user.<p>
<a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed()</a> searches the cache collection for a ccache for the client identity and if no appropriate ccache is available, attempts to acquire new credentials and store them in a new ccache. Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed()</a> may present a GUI or command line prompt to obtain information from the user. This function exists for convenience and to avoid code duplication. It can be trivially implemented using <a class="el" href="group__kim__ccache__reference.html#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">kim_ccache_create_from_client_identity()</a> and <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a>.<p>
+For legacy password-based Kerberos environments KIM also provides <a class="el" href="group__kim__ccache__reference.html#ge796642d7eb76bc05142ad8112d398e5" title="Acquire a new initial credential and store it in a ccache using the provided password...">kim_ccache_create_new_with_password()</a> and <a class="el" href="group__kim__ccache__reference.html#g462285a95435cf403b0330be13a515d7" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed_with_password()</a>. You should not use these functions unless you know that they will only be used in environments using passwords. Otherwise users without passwords may be prompted for them.<p>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#g15cb7e1b9069a610030211cecc5e6232" title="Acquire a new initial credential from a keytab and store it in a ccache.">kim_ccache_create_from_keytab()</a> to create credentials using a keytab and store them in the cache collection. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.<h2><a class="anchor" name="kim_ccache_validate">
Validating Credentials in a CCache</a></h2>
A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.<p>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g9ad7a15bf94420675c17bc61e83e47da" title="Get a kim_options object based on a ccache's credential attributes.">kim_ccache_get_options()</a> returns a kim_options object with the credential options of the credentials in the ccache. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.</li>
</ul>
-See <a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a> and <a class="el" href="group__kim__ccache__iterator__reference.html">KIM CCache Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a> and <a class="el" href="group__kim__ccache__iterator__reference.html">KIM CCache Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<h2><a class="anchor" name="kim_credential_acquire_new">
Acquiring New Credentials</a></h2>
KIM provides the <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying <a class="el" href="group__kim__types__reference.html#g322f65f7d72470d57e21a4c8777ee9fb">KIM_IDENTITY_ANY</a> to allow the user to choose. Typically callers of this API obtain the client identity using <a class="el" href="group__kim__selection__hints__reference.html#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a>. Depending on the kim_options specified, <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> may present a GUI or command line prompt to obtain information from the user.<p>
+For legacy password-based Kerberos environments KIM also provides <a class="el" href="group__kim__credential__reference.html#g5a91166863595b457a2c98e622f0c526" title="Acquire a new initial credential using the provided password.">kim_credential_create_new_with_password()</a>. You should not use this function unless you know that it will only be used in environments using passwords. Otherwise users without passwords may be prompted for them.<p>
KIM provides the <a class="el" href="group__kim__credential__reference.html#g42c9498e4e928fce495867a1d1835dc3" title="Acquire a new initial credential from a keytab.">kim_credential_create_from_keytab()</a> to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.<h2><a class="anchor" name="kim_credential_validate">
Validating Credentials</a></h2>
A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.<p>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g6d0cb540926a4d95923709a5104fb298" title="Get a kim_options object based on a credential's attributes.">kim_credential_get_options()</a> returns a kim_options object with the credential options of the credential. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.</li>
</ul>
-See <a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a> and <a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a> and <a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential Iterator Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.<p>
<a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8" title="Change the password for an identity.">kim_identity_change_password()</a> presents a user interface to obtain the old and new passwords from the user.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).</dd></dl>
-See <a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
Use <a class="el" href="group__kim__options__reference.html#g15ffe61f06334f4071e5b1ea6be62117" title="Set whether or not to request a proxiable credential.">kim_options_set_proxiable()</a> to change whether or not the Kerberos libraries request proxiable credentials. Use <a class="el" href="group__kim__options__reference.html#g0193dda96349a6e8d98d6154540a364e" title="Get whether or not to request a proxiable credential.">kim_options_get_proxiable()</a> to find out the current setting.<h3><a class="anchor" name="kim_options_service_name">
Service Name</a></h3>
Normally users acquire TGT credentials (ie "ticket granting tickets") and then use those credentials to acquire service credentials. This allows Kerberos to provide single sign-on while still providing mutual authentication to services. However, sometimes you just want an initial credential for a service. KIM options allows you to set the service name with <a class="el" href="group__kim__options__reference.html#g6e31c69a65efe32a5860125083d0b803" title="Set the service name to request a credential for.">kim_options_set_service_name()</a> and query it with <a class="el" href="group__kim__options__reference.html#gdf70addbc8221c252b1223b5e99dfa94" title="Get the service name to request a credential for.">kim_options_get_service_name()</a>.<p>
-See <a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
First, you need to acquire the Favorite Identities stored in the user's preferences using <a class="el" href="group__kim__preferences__reference.html#gf1dc483fcb582add046d552da9b8485f" title="Create a new preferences object from the current user's preferences.">kim_preferences_create()</a>.<p>
Then use <a class="el" href="group__kim__preferences__reference.html#g39ff3407953fedfc861efda92f961f18" title="Get the number of favorite identities in a preferences object.">kim_preferences_get_number_of_favorite_identities()</a> and <a class="el" href="group__kim__preferences__reference.html#g3012077dfb1169ebbbf2d7bf17dbbfdf" title="Get the Nth favorite identity in a preferences object.">kim_preferences_get_favorite_identity_at_index()</a> to display the identities list. Use <a class="el" href="group__kim__preferences__reference.html#gd7ed54017b8d46414c550a87ab775a9d" title="Add a favorite identity to a preferences object.">kim_preferences_add_favorite_identity()</a> and <a class="el" href="group__kim__preferences__reference.html#g85a31ca25607660c9dc2b68527c71f52" title="Remove a favorite identity from a preferences object.">kim_preferences_remove_favorite_identity()</a> to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list. If you wish to replace the identities list entirely, use <a class="el" href="group__kim__preferences__reference.html#gc28596bde36d790f569af33d50feedb8" title="Remove all favorite identities in a preferences object.">kim_preferences_remove_all_favorite_identities()</a> to clear the list before adding your identities.<p>
Once you are done editing the favorite identities list, store changes in the user's preference file using <a class="el" href="group__kim__preferences__reference.html#g6815e374d78e13714abcddc478145dd9" title="Synchronize a preferences object with the user's preferences, writing pending...">kim_preferences_synchronize()</a>.<p>
-See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:05 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with <a class="el" href="group__kim__selection__hints__reference.html#g8fce520fbadcdd10f8928fbea43083ee" title="Get the strings used to prompt the user to select the identity.">kim_selection_hints_get_explanation()</a>. You can find out what string will be used with <a class="el" href="group__kim__selection__hints__reference.html#gcc6ec35aa53cad7a2eca07ceea66a3c6" title="Set the strings used to prompt the user to select the identity.">kim_selection_hints_set_explanation()</a>.<p>
Since the user may choose to acquire credentials when selection an identity, KIM also provides <a class="el" href="group__kim__selection__hints__reference.html#g2cbc1a52c6fa4c94aa85acf7abb205c4" title="Set the options which will be used if credentials need to be acquired.">kim_selection_hints_set_options()</a> to set what credential acquisition options are used. <a class="el" href="group__kim__selection__hints__reference.html#gb8c6aea4ac6b55d77585a5f3047dd3e7" title="Get the options which will be used if credentials need to be acquired.">kim_selection_hints_get_options()</a> returns the options which will be used.<p>
If you need to disable user interaction, use <a class="el" href="group__kim__selection__hints__reference.html#g290210bc1cb57b49539cc7f8c0d8fa2c" title="Set whether or not KIM may interact with the user to select an identity.">kim_selection_hints_set_allow_user_interaction()</a>. Use <a class="el" href="group__kim__selection__hints__reference.html#g95691183f6a85b8208858bd948a64c55" title="Get whether or not KIM may interact with the user to select an identity.">kim_selection_hints_get_allow_user_interaction()</a> to find out whether or not user interaction is enabled. User interaction is enabled by default.<p>
-See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
Like most C APIs, the KIM API returns numeric error codes. These error codes may come from KIM, krb5 or GSS APIs. In most cases the caller will want to handle these error programmatically. However, in some circumstances the caller may wish to print an error string to the user.<p>
One problem with just printing the error code to the user is that frequently the context behind the error has been lost. For example if KIM is trying to obtain credentials via referrals, it may fail partway through the process. In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which maps to "Client not found in Kerberos database". Unfortunately this error isn't terribly helpful because it doesn't tell the user whether they typoed their principal name or if referrals failed.<p>
To avoid this problem, KIM maintains an explanatory string for the last error seen in each thread calling into KIM. If a caller wishes to display an error to the user, immediately after getting the error the caller should call <a class="el" href="group__kim__string__reference.html#gf1f7a5aba5f87b139f1b1db1430ca94b" title="Get a text description of an error suitable for display to the user.">kim_string_create_for_last_error()</a> to obtain a copy of the descriptive error message.<p>
-See <a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
<li><a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a>
<li><a class="el" href="group__kim__types__reference.html">KIM Types and Constants</a>
</ul>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 1 18:42:06 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
* It can be trivially implemented using
* #kim_ccache_create_from_client_identity() and #kim_ccache_create_new().
*
+ * For legacy password-based Kerberos environments KIM also provides
+ * #kim_ccache_create_new_with_password() and
+ * #kim_ccache_create_new_if_needed_with_password(). You should not use these
+ * functions unless you know that they will only be used in environments using
+ * passwords. Otherwise users without passwords may be prompted for them.
+ *
* KIM provides the #kim_ccache_create_from_keytab() to create credentials
* using a keytab and store them in the cache collection. A keytab is an
* on-disk copy of a client identity's secret key. Typically sites use
* \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to
* allow the user to choose.
* \param in_options options to control credential acquisition.
- * \note Depending on the kim_options specified, #kim_ccache_create_new() may
+ * \note #kim_ccache_create_new() may
* present a GUI or command line prompt to obtain information from the user.
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential and store it in a ccache.
kim_identity in_client_identity,
kim_options in_options);
+/*!
+ * \param out_ccache on exit, a new cache object for a ccache containing a newly acquired
+ * initial credential. Must be freed with kim_ccache_free().
+ * \param in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to
+ * allow the user to choose.
+ * \param in_options options to control credential acquisition.
+ * \param in_password a password to be used while obtaining credentials.
+ * \note #kim_ccache_create_new_with_password() exists to support
+ * legacy password-based Kerberos environments. You should not use this
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Acquire a new initial credential and store it in a ccache
+ * using the provided password..
+ */
+kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache,
+ kim_identity in_client_identity,
+ kim_options in_options,
+ kim_string in_password);
+
/*!
* \param out_ccache on exit, a ccache object for a ccache containing a newly acquired
* initial credential. Must be freed with kim_ccache_free().
* \param in_client_identity a client identity to obtain a credential for.
* \param in_options options to control credential acquisition (if a credential is acquired).
- * \note Depending on the kim_options specified, #kim_ccache_create_new_if_needed() may
+ * \note #kim_ccache_create_new_if_needed() may
* present a GUI or command line prompt to obtain information from the user.
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Find a ccache containing a valid initial credential in the cache collection, or if
kim_identity in_client_identity,
kim_options in_options);
+/*!
+ * \param out_ccache on exit, a ccache object for a ccache containing a newly acquired
+ * initial credential. Must be freed with kim_ccache_free().
+ * \param in_client_identity a client identity to obtain a credential for.
+ * \param in_options options to control credential acquisition (if a credential is acquired).
+ * \param in_password a password to be used while obtaining credentials.
+ * \note #kim_ccache_create_new_if_needed_with_password() exists to support
+ * legacy password-based Kerberos environments. You should not use this
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Find a ccache containing a valid initial credential in the cache collection, or if
+ * unavailable, acquire and store a new initial credential using the provided password.
+ */
+kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache *out_ccache,
+ kim_identity in_client_identity,
+ kim_options in_options,
+ kim_string in_password);
+
/*!
* \param out_ccache on exit, a ccache object for a ccache containing a TGT
* credential. Must be freed with kim_ccache_free().
* kim_options specified, #kim_credential_create_new() may present a
* GUI or command line prompt to obtain information from the user.
*
+ * For legacy password-based Kerberos environments KIM also provides
+ * #kim_credential_create_new_with_password(). You should not use this
+ * function unless you know that it will only be used in environments using
+ * passwords. Otherwise users without passwords may be prompted for them.
+ *
* KIM provides the #kim_credential_create_from_keytab() to create credentials
* using a keytab. A keytab is an on-disk copy of a client identity's secret
* key. Typically sites use keytabs for client identities that identify a
* \param in_client_identity a client identity to obtain a credential for. Specify NULL to
* allow the user to choose the identity
* \param in_options options to control credential acquisition.
- * \note Depending on the kim_options specified, #kim_credential_create_new() may
+ * \note #kim_credential_create_new() may
* present a GUI or command line prompt to obtain information from the user.
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Acquire a new initial credential.
kim_identity in_client_identity,
kim_options in_options);
+/*!
+ * \param out_credential on exit, a new credential object containing a newly acquired
+ * initial credential. Must be freed with kim_credential_free().
+ * \param in_client_identity a client identity to obtain a credential for. Specify NULL to
+ * allow the user to choose the identity
+ * \param in_options options to control credential acquisition.
+ * \param in_password a password to be used while obtaining the credential.
+ * \note #kim_credential_create_new_with_password() exists to support
+ * legacy password-based Kerberos environments. You should not use this
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Acquire a new initial credential using the provided password.
+ * \sa kim_ccache_create_new
+ */
+kim_error kim_credential_create_new_with_password (kim_credential *out_credential,
+ kim_identity in_client_identity,
+ kim_options in_options,
+ kim_string in_password);
+
/*!
* \param out_credential on exit, a new credential object containing an initial credential
* for \a in_identity obtained using \a in_keytab.
kim_credential_iterator_free
kim_credential_create_new
+kim_credential_create_new_with_password
kim_credential_create_from_keytab
kim_credential_create_from_krb5_creds
kim_credential_copy
kim_ccache_iterator_free
kim_ccache_create_new
+kim_ccache_create_new_with_password
kim_ccache_create_new_if_needed
+kim_ccache_create_new_if_needed_with_password
kim_ccache_create_from_client_identity
kim_ccache_create_from_keytab
kim_ccache_create_from_default
+++ /dev/null
-/*
- * $Header$
- *
- * Copyright 2006 Massachusetts Institute of Technology.
- * All Rights Reserved.
- *
- * Export of this software from the United States of America may
- * require a specific license from the United States Government.
- * It is the responsibility of any person or organization contemplating
- * export to obtain such a license before exporting.
- *
- * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
- * distribute this software and its documentation for any purpose and
- * without fee is hereby granted, provided that the above copyright
- * notice appear in all copies and that both that copyright notice and
- * this permission notice appear in supporting documentation, and that
- * the name of M.I.T. not be used in advertising or publicity pertaining
- * to distribution of the software without specific, written prior
- * permission. Furthermore if you modify this software you must label
- * your software as modified software and not distribute it in such a
- * fashion that it might be confused with the original M.I.T. software.
- * M.I.T. makes no representations about the suitability of
- * this software for any purpose. It is provided "as is" without express
- * or implied warranty.
- */
-
-#ifndef KIM_CCACHE_PRIVATE_H
-#define KIM_CCACHE_PRIVATE_H
-
-#include <kim/kim.h>
-
-kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache *out_ccache,
- kim_identity in_client_identity,
- kim_options in_options,
- kim_string in_password);
-
-kim_error kim_ccache_create_new_with_password (kim_ccache *out_ccache,
- kim_identity in_client_identity,
- kim_options in_options,
- kim_string in_password);
-
-#endif /* KIM_CCACHE_PRIVATE_H */
kim_ui_context *in_ui_context,
kim_boolean *out_user_was_prompted);
-kim_error kim_credential_create_new_with_password (kim_credential *out_credential,
- kim_identity in_identity,
- kim_options in_options,
- kim_string in_password);
-
#endif /* KIM_CREDENTIAL_PRIVATE_H */
#include "kim_debug_private.h"
#include "kim_error_private.h"
#include "kim_identity_private.h"
-#include "kim_ccache_private.h"
#include "kim_credential_private.h"
#include "kim_options_private.h"
#include "kim_preferences_private.h"
projects / krb5.git / commitdiff