</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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__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 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 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#g09c1cdf2b993ab881319a33074f5ef24">kim_credential_create_for_change_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_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_old_password)
+<dl class="el"><dd class="mdescRight">Obtain a credential for changing an identity's password. <a href="#g09c1cdf2b993ab881319a33074f5ef24"></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)
<dl class="el"><dd class="mdescRight">Get a krb5 credentials object for a credential object. <a href="#g5ccc2fc794ea3bf3dc947c8a3ccd1077"></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#g823f10b2a4db687fb555920808113392">kim_credential_get_client_identity</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *out_client_identity)
<dl class="el"><dd class="mdescRight">Get the client identity of a credential object. <a href="#g823f10b2a4db687fb555920808113392"></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#g05208e303966c4c89371c18135de9cd7">kim_credential_get_service_identity</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *out_service_identity)
<dl class="el"><dd class="mdescRight">Store a credential in a ccache in the cache collection. <a href="#g52db69b8f2289a4b60a3eddb5cb6b671"></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#gf10b622ed5ea209bf06ba708732b6c07">kim_credential_verify</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_credential, <a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_service_identity, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_keytab, <a class="el" href="group__kim__types__reference.html#g6f8afd4047c4fe420c05f940f89ffba0">kim_boolean</a> in_fail_if_no_service_key)
<dl class="el"><dd class="mdescRight">Verify a TGT credential. <a href="#gf10b622ed5ea209bf06ba708732b6c07"></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#g18f43112f7ae046b2a5918b061a2072d">kim_credential_renew</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
<dl class="el"><dd class="mdescRight">Renew a TGT credential. <a href="#g18f43112f7ae046b2a5918b061a2072d"></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#g63a591ef509219ae83d11b635065984d">kim_credential_validate</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Validate a TGT credential. <a href="#g63a591ef509219ae83d11b635065984d"></a><br></dl><li>void <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845">kim_credential_free</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential)
+<dl class="el"><dd class="mdescRight">Validate a TGT credential. <a href="#g63a591ef509219ae83d11b635065984d"></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#ge51af0e19abfcba108d8fd4ca3effea3">kim_credential_change_password</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> in_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#geea99aa292876e06003b7480087eecb0">kim_string</a> in_new_password, <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> *out_rejected_err, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_rejected_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_rejected_description)
+<dl class="el"><dd class="mdescRight">Change an identity's password. <a href="#ge51af0e19abfcba108d8fd4ca3effea3"></a><br></dl><li>void <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845">kim_credential_free</a> (<a class="el" href="group__kim__types__reference.html#ge57b4df3376c4a34a119078a7f4a0030">kim_credential</a> *io_credential)
<dl class="el"><dd class="mdescRight">Free memory associated with a credential object. <a href="#g5609d3883f82eb3938a2d80e06bd0845"></a><br></dl></ul>
<hr><h2>Function Documentation</h2>
<a class="anchor" name="ga02a96b9ad6fbc64007f741fa21c8814"></a><!-- doxytag: member="kim_credential.h::kim_credential_create_new" ref="ga02a96b9ad6fbc64007f741fa21c8814" args="(kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options)" -->
</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="g09c1cdf2b993ab881319a33074f5ef24"></a><!-- doxytag: member="kim_credential.h::kim_credential_create_for_change_password" ref="g09c1cdf2b993ab881319a33074f5ef24" args="(kim_credential *out_credential, kim_identity in_identity, kim_string in_old_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_for_change_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_identity</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_old_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>
+Obtain a credential for changing an identity's 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 change password credential for <em>in_identity</em>. 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_identity</em> </td><td>a client identity to obtain a change password credential for. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_old_password</em> </td><td>the current password for <em>in_identity</em>. May be an expired password. </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>
+<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#ge51af0e19abfcba108d8fd4ca3effea3" title="Change an identity's password.">kim_credential_change_password</a> </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="gecf207628b94739322344678486b45d2"></a><!-- doxytag: member="kim_credential.h::kim_credential_copy" ref="gecf207628b94739322344678486b45d2" args="(kim_credential *out_credential, kim_credential in_credential)" -->
<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#g73f5b201d24a58936244fc4e43cd3d59" title="Validate the TGT in a ccache.">kim_ccache_validate</a> </dd></dl>
+</div>
+</div><p>
+<a class="anchor" name="ge51af0e19abfcba108d8fd4ca3effea3"></a><!-- doxytag: member="kim_credential.h::kim_credential_change_password" ref="ge51af0e19abfcba108d8fd4ca3effea3" args="(kim_credential in_credential, kim_identity in_identity, kim_string in_new_password, kim_error *out_rejected_err, kim_string *out_rejected_message, kim_string *out_rejected_description)" -->
+<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_change_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>in_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_identity</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_new_password</em>, </td>
+ </tr>
+ <tr>
+ <td class="paramkey"></td>
+ <td></td>
+ <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> * </td>
+ <td class="paramname"> <em>out_rejected_err</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>out_rejected_message</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>out_rejected_description</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>
+Change an identity's 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>in_credential</em> </td><td>a credential object containing a change password credential. Use <a class="el" href="group__kim__credential__reference.html#ge51af0e19abfcba108d8fd4ca3effea3" title="Change an identity's password.">kim_credential_change_password</a> to obtain a change password credential. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_identity</em> </td><td>an identity to change the password for. May be different than the identity the credential is for. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>in_new_password</em> </td><td>the password to change the identity to. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_rejected_err</em> </td><td>on exit, 0 if the password change was successful or an error describing why the new password was rejected. </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_rejected_message</em> </td><td>on exit, if <em>out_rejected_err</em> is non-zero this argument will contain an error message for <em>out_rejected_err</em>. Pass NULL if you do not want this error string. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_free()</a>; </td></tr>
+ <tr><td valign="top"></td><td valign="top"><em>out_rejected_description</em> </td><td>on exit, if <em>out_rejected_err</em> is non-zero this argument will contain an string describing why <em>in_new_password</em> was rejected. Pass NULL if you do not want this error string. Must be freed with <a class="el" href="group__kim__string__reference.html#g7e7207329022e97473ec71574e52a1fc" title="Free memory associated with a string.">kim_string_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>
+<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__credential__reference.html#g09c1cdf2b993ab881319a33074f5ef24" title="Obtain a credential for changing an identity's password.">kim_credential_create_for_change_password</a> </dd></dl>
+
</div>
</div><p>
<a class="anchor" name="g5609d3883f82eb3938a2d80e06bd0845"></a><!-- doxytag: member="kim_credential.h::kim_credential_free" ref="g5609d3883f82eb3938a2d80e06bd0845" args="(kim_credential *io_credential)" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 class="el"><dd class="mdescRight">Get the realm string of an identity. <a href="#gf102dfe4b89f6e87ac3059f01f174066"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#g96591cf92e03e823efcd4fc54085ca4d">kim_identity_get_number_of_components</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#g098e3611b2bc3af38b5f06838153165d">kim_count</a> *out_number_of_components)
<dl class="el"><dd class="mdescRight">Get the number of components of an identity. <a href="#g96591cf92e03e823efcd4fc54085ca4d"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gec46c138cd20035a12586dba59680728">kim_identity_get_component_at_index</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, <a class="el" href="group__kim__types__reference.html#g098e3611b2bc3af38b5f06838153165d">kim_count</a> in_index, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> *out_component_string)
<dl class="el"><dd class="mdescRight">Get the Nth component of an identity. <a href="#gec46c138cd20035a12586dba59680728"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gd293289334f024dedae5fa59856049d6">kim_identity_get_krb5_principal</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)
-<dl class="el"><dd class="mdescRight">Get the krb5_principal representation of an identity. <a href="#gd293289334f024dedae5fa59856049d6"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#gd198c678fa37a551391bc52307306394">kim_identity_change_password</a> (<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)
-<dl class="el"><dd class="mdescRight">Change the password for an identity. <a href="#gd198c678fa37a551391bc52307306394"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#g6eb2decbecaaab598d66f809187f8223">kim_identity_change_password_to_password</a> (<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_new_password)
-<dl class="el"><dd class="mdescRight">Change the password for an identity to a caller-provided new password. <a href="#g6eb2decbecaaab598d66f809187f8223"></a><br></dl><li>void <a class="el" href="group__kim__identity__reference.html#g3ae8057f3eb0040330b598645d470411">kim_identity_free</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *io_identity)
+<dl class="el"><dd class="mdescRight">Get the krb5_principal representation of an identity. <a href="#gd293289334f024dedae5fa59856049d6"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8">kim_identity_change_password</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> in_identity)
+<dl class="el"><dd class="mdescRight">Change the password for an identity. <a href="#g660c28e70656127c7c723d50414675e8"></a><br></dl><li>void <a class="el" href="group__kim__identity__reference.html#g3ae8057f3eb0040330b598645d470411">kim_identity_free</a> (<a class="el" href="group__kim__types__reference.html#gf96cafc394b0d02327b4df8ff669d589">kim_identity</a> *io_identity)
<dl class="el"><dd class="mdescRight">Free memory associated with an identity. <a href="#g3ae8057f3eb0040330b598645d470411"></a><br></dl></ul>
<hr><h2>Function Documentation</h2>
<a class="anchor" name="g23804ae9643100ad5e1fef11f6e5362c"></a><!-- doxytag: member="kim_identity.h::kim_identity_create_from_string" ref="g23804ae9643100ad5e1fef11f6e5362c" args="(kim_identity *out_identity, kim_string in_string)" -->
</div>
</div><p>
-<a class="anchor" name="gd198c678fa37a551391bc52307306394"></a><!-- doxytag: member="kim_identity.h::kim_identity_change_password" ref="gd198c678fa37a551391bc52307306394" args="(kim_identity in_identity, kim_options in_options)" -->
+<a class="anchor" name="g660c28e70656127c7c723d50414675e8"></a><!-- doxytag: member="kim_identity.h::kim_identity_change_password" ref="g660c28e70656127c7c723d50414675e8" args="(kim_identity in_identity)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<td class="memname"><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> kim_identity_change_password </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_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><td> </td>
- </tr>
- <tr>
- <td></td>
- <td>)</td>
- <td></td><td></td><td width="100%"></td>
+ <td class="paramname"> <em>in_identity</em> </td>
+ <td> ) </td>
+ <td width="100%"></td>
</tr>
</table>
</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>in_identity</em> </td><td>an identity object whose password will be changed. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>initial credential options to be used if a new credential is obtained. </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>
-<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__identity__reference.html#gd198c678fa37a551391bc52307306394" title="Change the password for an identity.">kim_identity_change_password()</a> will acquire a temporary credential to change the password. It uses the <em>in_options</em> structure to obtain information about the desired prompter and current password. </dd></dl>
-
-</div>
-</div><p>
-<a class="anchor" name="g6eb2decbecaaab598d66f809187f8223"></a><!-- doxytag: member="kim_identity.h::kim_identity_change_password_to_password" ref="g6eb2decbecaaab598d66f809187f8223" args="(kim_identity in_identity, kim_options in_options, kim_string in_new_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_identity_change_password_to_password </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_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_new_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>
-Change the password for an identity to a caller-provided new 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>in_identity</em> </td><td>an identity object whose password will be changed. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_options</em> </td><td>initial credential options to be used if a new credential is obtained. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_new_password</em> </td><td>a string representation of the identity's new password. </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>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>kim_identity_change_password_with_passwords() will acquire a temporary credential to change the password. It uses the <em>in_options</em> structure to obtain information about the desired prompter and current password. </dd></dl>
+<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8" title="Change the password for an identity.">kim_identity_change_password()</a> will acquire a temporary credential to change the password. </dd></dl>
</div>
</div><p>
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#ge36eb288b38f18491e4c903f008b1379">kim_options_create</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> *out_options)
<dl class="el"><dd class="mdescRight">Create new options with default values. <a href="#ge36eb288b38f18491e4c903f008b1379"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#g17fc17a04097c42afab7a6b1a3f8d7fb">kim_options_copy</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> *out_options, <a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options)
-<dl class="el"><dd class="mdescRight">Copy options. <a href="#g17fc17a04097c42afab7a6b1a3f8d7fb"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#g645bfc7ee5e4d17e53d34964dee2a7d7">kim_options_set_prompt_callback</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> io_options, <a class="el" href="group__kim__types__reference.html#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a> in_prompt_callback)
-<dl class="el"><dd class="mdescRight">Set the prompt callback for obtaining information from the user. <a href="#g645bfc7ee5e4d17e53d34964dee2a7d7"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#g5bde52591259c4598530553ea2719181">kim_options_get_prompt_callback</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a> *out_prompt_callback)
-<dl class="el"><dd class="mdescRight">Get the prompt callback for obtaining information from the user. <a href="#g5bde52591259c4598530553ea2719181"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#g4b061cf6dc57624b91560b5d511a7c43">kim_options_set_data</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> io_options, const void *in_data)
-<dl class="el"><dd class="mdescRight">Set caller-specific data for use in library callbacks. <a href="#g4b061cf6dc57624b91560b5d511a7c43"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#gf81e50923e7b4604950a5aec8a3676d7">kim_options_get_data</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, const void **out_data)
-<dl class="el"><dd class="mdescRight">Get caller-specific data for use in library callbacks. <a href="#gf81e50923e7b4604950a5aec8a3676d7"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#gf7f6a8a82fedc547c8502ce09a419f91">kim_options_set_start_time</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> io_options, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> in_start_time)
+<dl class="el"><dd class="mdescRight">Copy options. <a href="#g17fc17a04097c42afab7a6b1a3f8d7fb"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#gf7f6a8a82fedc547c8502ce09a419f91">kim_options_set_start_time</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> io_options, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> in_start_time)
<dl class="el"><dd class="mdescRight">Set the date when a credential should become valid. <a href="#gf7f6a8a82fedc547c8502ce09a419f91"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#gca63b972b41530c52bbe83bd974e6f9b">kim_options_get_start_time</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a> *out_start_time)
<dl class="el"><dd class="mdescRight">Get the date when a credential should become valid. <a href="#gca63b972b41530c52bbe83bd974e6f9b"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#g392369e80bea0ea9c920d6de55e080ed">kim_options_set_lifetime</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> io_options, <a class="el" href="group__kim__types__reference.html#g245934c4ef7f94ff7960e20e0cc01123">kim_lifetime</a> in_lifetime)
<dl class="el"><dd class="mdescRight">Set the duration during which a credential should be valid. <a href="#g392369e80bea0ea9c920d6de55e080ed"></a><br></dl><li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__options__reference.html#gd7a886d6c0a33d0d872bf40420023ee2">kim_options_get_lifetime</a> (<a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> in_options, <a class="el" href="group__kim__types__reference.html#g245934c4ef7f94ff7960e20e0cc01123">kim_lifetime</a> *out_lifetime)
</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="g645bfc7ee5e4d17e53d34964dee2a7d7"></a><!-- doxytag: member="kim_options.h::kim_options_set_prompt_callback" ref="g645bfc7ee5e4d17e53d34964dee2a7d7" args="(kim_options io_options, kim_prompt_callback in_prompt_callback)" -->
-<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_options_set_prompt_callback </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> </td>
- <td class="paramname"> <em>io_options</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a> </td>
- <td class="paramname"> <em>in_prompt_callback</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>
-Set the prompt callback for obtaining information from the user.
-<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>io_options</em> </td><td>an options object to modify. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_prompt_callback</em> </td><td>a prompt callback function. </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>
-<dl class="user" compact><dt><b>Default value</b></dt><dd><a class="el" href="group__kim__types__reference.html#gbacd03bffb1ba46e4d8e36d19d91a170">kim_prompt_callback_default</a> </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__options__reference.html#g5bde52591259c4598530553ea2719181" title="Get the prompt callback for obtaining information from the user.">kim_options_get_prompt_callback()</a> </dd></dl>
-
-</div>
-</div><p>
-<a class="anchor" name="g5bde52591259c4598530553ea2719181"></a><!-- doxytag: member="kim_options.h::kim_options_get_prompt_callback" ref="g5bde52591259c4598530553ea2719181" args="(kim_options in_options, kim_prompt_callback *out_prompt_callback)" -->
-<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_options_get_prompt_callback </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#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a> * </td>
- <td class="paramname"> <em>out_prompt_callback</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>
-Get the prompt callback for obtaining information from the user.
-<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>in_options</em> </td><td>an options object. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_prompt_callback</em> </td><td>on exit, the prompt callback specified by in_options. Does not need to be freed but may become invalid when <em>in_options</em> is freed. </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>
-<dl class="user" compact><dt><b>Default value</b></dt><dd><a class="el" href="group__kim__types__reference.html#gbacd03bffb1ba46e4d8e36d19d91a170">kim_prompt_callback_default</a> </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__options__reference.html#g645bfc7ee5e4d17e53d34964dee2a7d7" title="Set the prompt callback for obtaining information from the user.">kim_options_set_prompt_callback()</a> </dd></dl>
-
-</div>
-</div><p>
-<a class="anchor" name="g4b061cf6dc57624b91560b5d511a7c43"></a><!-- doxytag: member="kim_options.h::kim_options_set_data" ref="g4b061cf6dc57624b91560b5d511a7c43" args="(kim_options io_options, const void *in_data)" -->
-<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_options_set_data </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#gc61f3242847e46c14c73e423829888ab">kim_options</a> </td>
- <td class="paramname"> <em>io_options</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">const void * </td>
- <td class="paramname"> <em>in_data</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>
-Set caller-specific data for use in library callbacks.
-<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>io_options</em> </td><td>an options object to modify. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>in_data</em> </td><td>a pointer to caller-specific data. </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>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way. </dd></dl>
-<dl class="user" compact><dt><b>Default value</b></dt><dd>NULL (no data is set by default) </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__options__reference.html#gf81e50923e7b4604950a5aec8a3676d7" title="Get caller-specific data for use in library callbacks.">kim_options_get_data()</a> </dd></dl>
-
-</div>
-</div><p>
-<a class="anchor" name="gf81e50923e7b4604950a5aec8a3676d7"></a><!-- doxytag: member="kim_options.h::kim_options_get_data" ref="gf81e50923e7b4604950a5aec8a3676d7" args="(kim_options in_options, const void **out_data)" -->
-<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_options_get_data </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">const void ** </td>
- <td class="paramname"> <em>out_data</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>
-Get caller-specific data for use in library callbacks.
-<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>in_options</em> </td><td>an options object. </td></tr>
- <tr><td valign="top"></td><td valign="top"><em>out_data</em> </td><td>on exit, the pointer to caller specific data specified by in_options. Does not need to be freed but may become invalid when <em>in_options</em> is freed. </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>
-<dl class="note" compact><dt><b>Note:</b></dt><dd>This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way. </dd></dl>
-<dl class="user" compact><dt><b>Default value</b></dt><dd>NULL (no data is set by default) </dd></dl>
-<dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kim__options__reference.html#g4b061cf6dc57624b91560b5d511a7c43" title="Set caller-specific data for use in library callbacks.">kim_options_set_data()</a> </dd></dl>
-
</div>
</div><p>
<a class="anchor" name="gf7f6a8a82fedc547c8502ce09a419f91"></a><!-- doxytag: member="kim_options.h::kim_options_set_start_time" ref="gf7f6a8a82fedc547c8502ce09a419f91" args="(kim_options io_options, kim_time in_start_time)" -->
</div>
</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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>Typedefs</h2>
<ul>
<li>typedef int <a class="el" href="group__kim__types__reference.html#g48e19d7e4aec7dc6662149cab39bbe20">kim_credential_state</a>
-<li>typedef uint32_t <a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a>
-<li>typedef <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>(* <a class="el" href="group__kim__types__reference.html#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a> )(<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply)
<li>typedef int32_t <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>
<li>typedef int64_t <a class="el" href="group__kim__types__reference.html#g3da22452677b45753d40e07f3904dff5">kim_time</a>
<li>typedef int64_t <a class="el" href="group__kim__types__reference.html#g245934c4ef7f94ff7960e20e0cc01123">kim_lifetime</a>
<b>kim_credentials_state_address_mismatch</b> = 4
<br>
}
-<li>enum <b>kim_prompt_type_enum</b> { <b>kim_prompt_type_password</b> = 0,
-<b>kim_prompt_type_challenge</b> = 1
- }
-</ul>
-<h2>Functions</h2>
-<ul>
-<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__types__reference.html#gbacd03bffb1ba46e4d8e36d19d91a170">kim_prompt_callback_default</a> (<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply)
-<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__types__reference.html#g5dc825b3083c371b1cd697efc19a1c22">kim_prompt_callback_gui</a> (<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply)
-<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__types__reference.html#g7e046e29e68cee691ac652e6b9c0ce93">kim_prompt_callback_cli</a> (<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply)
-<li><a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a> <a class="el" href="group__kim__types__reference.html#gcc03830f3eece78fae04b722ca0687c3">kim_prompt_callback_none</a> (<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply)
</ul>
<hr><h2>Define Documentation</h2>
<a class="anchor" name="g8712727bab9e6b02712a8a01285441d1"></a><!-- doxytag: member="kim_error.h::KIM_NO_ERROR" ref="g8712727bab9e6b02712a8a01285441d1" args="" -->
The state of a credential. See <a class="el" href="group__kim__types__reference.html#g6e5c2c986359589562c83f1da2cf0ca0">kim_credential_state_enum</a> for possible values.
</div>
</div><p>
-<a class="anchor" name="g91894d96e0196e25424084eccdc04eb8"></a><!-- doxytag: member="kim_options.h::kim_prompt_type" ref="g91894d96e0196e25424084eccdc04eb8" args="" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname">typedef uint32_t <a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> </td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-The type of prompt which needs to be displayed. This value determines what type of user interface is displayed. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information.
-</div>
-</div><p>
-<a class="anchor" name="gded2c3c2de01d94299b65fb8df64bdcc"></a><!-- doxytag: member="kim_options.h::kim_prompt_callback" ref="gded2c3c2de01d94299b65fb8df64bdcc" args=")(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)" -->
-<div class="memitem">
-<div class="memproto">
- <table class="memname">
- <tr>
- <td class="memname">typedef <a class="el" href="group__kim__types__reference.html#g40f5fe10ab395bddc34286e0c2ff76eb">kim_error</a>(* <a class="el" href="group__kim__types__reference.html#gded2c3c2de01d94299b65fb8df64bdcc">kim_prompt_callback</a>)(<a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> in_type, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_title, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_message, <a class="el" href="group__kim__types__reference.html#geea99aa292876e06003b7480087eecb0">kim_string</a> in_description, char **out_reply) </td>
- </tr>
- </table>
-</div>
-<div class="memdoc">
-
-<p>
-The prompt callback used to display a prompt to the user. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information.
-</div>
-</div><p>
<a class="anchor" name="g40f5fe10ab395bddc34286e0c2ff76eb"></a><!-- doxytag: member="kim_types.h::kim_error" ref="g40f5fe10ab395bddc34286e0c2ff76eb" args="" -->
<div class="memitem">
<div class="memproto">
</div>
</div><p>
-<hr><h2>Function Documentation</h2>
-<a class="anchor" name="gbacd03bffb1ba46e4d8e36d19d91a170"></a><!-- doxytag: member="kim_options.h::kim_prompt_callback_default" ref="gbacd03bffb1ba46e4d8e36d19d91a170" args="(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)" -->
-<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_prompt_callback_default </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> </td>
- <td class="paramname"> <em>in_type</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_title</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_message</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_description</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">char ** </td>
- <td class="paramname"> <em>out_reply</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>
-The default prompt callback. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information.
-</div>
-</div><p>
-<a class="anchor" name="g5dc825b3083c371b1cd697efc19a1c22"></a><!-- doxytag: member="kim_options.h::kim_prompt_callback_gui" ref="g5dc825b3083c371b1cd697efc19a1c22" args="(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)" -->
-<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_prompt_callback_gui </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> </td>
- <td class="paramname"> <em>in_type</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_title</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_message</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_description</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">char ** </td>
- <td class="paramname"> <em>out_reply</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>
-The graphical prompt callback. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information.
-</div>
-</div><p>
-<a class="anchor" name="g7e046e29e68cee691ac652e6b9c0ce93"></a><!-- doxytag: member="kim_options.h::kim_prompt_callback_cli" ref="g7e046e29e68cee691ac652e6b9c0ce93" args="(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)" -->
-<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_prompt_callback_cli </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> </td>
- <td class="paramname"> <em>in_type</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_title</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_message</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_description</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">char ** </td>
- <td class="paramname"> <em>out_reply</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>
-The command line prompt callback. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information.
-</div>
-</div><p>
-<a class="anchor" name="gcc03830f3eece78fae04b722ca0687c3"></a><!-- doxytag: member="kim_options.h::kim_prompt_callback_none" ref="gcc03830f3eece78fae04b722ca0687c3" args="(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)" -->
-<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_prompt_callback_none </td>
- <td>(</td>
- <td class="paramtype"><a class="el" href="group__kim__types__reference.html#g91894d96e0196e25424084eccdc04eb8">kim_prompt_type</a> </td>
- <td class="paramname"> <em>in_type</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_title</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_message</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_description</em>, </td>
- </tr>
- <tr>
- <td class="paramkey"></td>
- <td></td>
- <td class="paramtype">char ** </td>
- <td class="paramname"> <em>out_reply</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>
-The prompt callback which always returns an error. Use to turn off prompting entirely. <dl class="note" compact><dt><b>Note:</b></dt><dd>Using this callback may prevent the user from authenicating. See <a class="el" href="kim_options_overview.html#kim_options_custom_prompt_callback">Providing a Custom Prompt Callback</a> for more information. </dd></dl>
-
-</div>
-</div><p>
-<hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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__ccache__reference.html#g01b4cbb88abf6aafd2efdaad91d74f0f" title="Get the time when the credentials in the ccache will no longer be renewable.">kim_ccache_get_renewal_expiration_time()</a> returns when the credential's in a ccache will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.</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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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__credential__reference.html#g4e50b4abf3efc36ed10c3049c9ff9a48" title="Get the time when the credentials will no longer be renewable.">kim_credential_get_renewal_expiration_time()</a> returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.</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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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>
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__error__reference.html#g7105c4527c2a247cdacd86624d7dc5fb" title="Get a text description of an error suitable for display to the user.">kim_string_get_last_error_message()</a> to obtain a copy of the descriptive error message.<p>
Note that because this string is stored in thread-specific data, callers must call <a class="el" href="group__kim__error__reference.html#g7105c4527c2a247cdacd86624d7dc5fb" title="Get a text description of an error suitable for display to the user.">kim_string_get_last_error_message()</a> before calling any KIM APIs or any other APIs which might call into KIM. Callers who are not going to display this error string immediately should also make a copy of it so that it is not overwritten by the next call into KIM.<p>
-See <a class="el" href="group__kim__error__reference.html">KIM Error Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+See <a class="el" href="group__kim__error__reference.html">KIM Error Reference Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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>
To solve this problem, <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> takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information.<h2><a class="anchor" name="kim_identity_password">
Changing a Identity's Password</a></h2>
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#g
d198c678fa37a551391bc52307306394" 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. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.<p>
+<a class="el" href="group__kim__identity__reference.html#g
660c28e70656127c7c723d50414675e8" 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. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.<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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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>
<h1><a class="anchor" name="kim_options_overview">KIM Options Overview</a></h1><h2><a class="anchor" name="kim_options_introduction">
Introduction</a></h2>
Kerberos Identity Management Options (kim_options_t) allows you to control how the Kerberos library obtains credentials. When the options structure is initialized with <a class="el" href="group__kim__options__reference.html#ge36eb288b38f18491e4c903f008b1379" title="Create new options with default values.">kim_options_create()</a>, each option is filled in with a default value which can then be modified with the kim_options_set_*() APIs. If you only want to use the default values, you may pass <a class="el" href="group__kim__types__reference.html#ge0384d3f6d9108e3ec84e322c61235a7">KIM_OPTIONS_DEFAULT</a> into any KIM function that takes a kim_options_t.<p>
-KIM options fall into two major categories: options for controlling how credentials are acquired and options for controlling what properties the newly acquired credentials will have:<h2><a class="anchor" name="kim_options_credential_acquisition">
-Options for Controlling Credential Acquisition</a></h2>
-In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. These secrets may be a certificate, password, SecurID pin, or information from a smart card. If obtaining the secret requires interaction with the user, the Kerberos libraries call a "prompter callback" to display a dialog or command line prompt to request information from the user. If you want to provide your own custom dialogs or command line prompts, the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.<h3><a class="anchor" name="kim_options_custom_prompt_callback">
-Providing a Custom Prompt Callback</a></h3>
-All secrets are obtained from the user through a kim_prompt_callback_t. By default, options use <a class="el" href="group__kim__types__reference.html#gbacd03bffb1ba46e4d8e36d19d91a170">kim_prompt_callback_default</a>, which presents a dialog to request information from the user, or if no graphical access is available, a command line prompt.<p>
-KIM also provides three other callbacks: <a class="el" href="group__kim__types__reference.html#g5dc825b3083c371b1cd697efc19a1c22">kim_prompt_callback_gui</a> only presents a dialog and returns an error if there is no graphical access. <a class="el" href="group__kim__types__reference.html#g7e046e29e68cee691ac652e6b9c0ce93">kim_prompt_callback_cli</a> only presents a command line interface and returns an error if there is no controlling terminal available. <a class="el" href="group__kim__types__reference.html#gcc03830f3eece78fae04b722ca0687c3">kim_prompt_callback_none</a> always returns an error.<p>
-Using <a class="el" href="group__kim__options__reference.html#g645bfc7ee5e4d17e53d34964dee2a7d7" title="Set the prompt callback for obtaining information from the user.">kim_options_set_prompt_callback()</a>, you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with <a class="el" href="group__kim__options__reference.html#g4b061cf6dc57624b91560b5d511a7c43" title="Set caller-specific data for use in library callbacks.">kim_options_set_data()</a> for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.<h2><a class="anchor" name="kim_options_credential_properties">
+KIM options fall into two major categories: options for controlling how credentials are acquired and options for controlling what properties the newly acquired credentials will have:<h2><a class="anchor" name="kim_options_credential_properties">
Options for Controlling Credential Properties</a></h2>
Kerberos credentials have a number of different properties which can be requested when credentials are acquired. These properties control when and for how long the credentials are valid and what you can do with them.<p>
Note that setting these properties in the KIM options only changes what the Kerberos libraries <em>request</em> from the KDC. The KDC itself may choose not to honor your requested properties if they violate the site security policy. For example, most sites place an upper bound on how long credentials may be valid. If you request a credential lifetime longer than this upper bound, the KDC may return credentials with a shorter lifetime than you requested.<h3><a class="anchor" name="kim_options_lifetimes">
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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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>
<!-- Generated by Doxygen 1.5.3 -->
<h1><a class="anchor" name="kim_string_overview">KIM String Overview</a></h1>A UTF8 string.<p>
Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.<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 Thu Sep 18 10:55:28 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 Sep 22 18:09:05 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 Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by
+<hr size="1"><address style="text-align: right;"><small>Generated on Mon Sep 22 18:09:05 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>
#include <kim/kim_types.h>
#include <krb5.h>
- /*!
- * \addtogroup kim_types_reference
- * @{
- */
-
- /*!
- * Possible credential states. Credentials may be:
- * \li valid - The credential can be used.
- * \li expired - The credential's lifetime has been exceeded.
- * \li not_yet_valid - The credential is post dated and the time when
- * it becomes valid has not yet been reached.
- * \li needs_validation - The credential is post-dated and although
- * the time when it becomes valid has been reached
- * it has not yet been validated.
- * \li address_mismatch - The credential contains IP address(es) which do
- * not match the host's local address(es).
- */
- enum kim_credential_state_enum {
- kim_credentials_state_valid = 0,
- kim_credentials_state_expired = 1,
- kim_credentials_state_not_yet_valid = 2,
- kim_credentials_state_needs_validation = 3,
- kim_credentials_state_address_mismatch = 4
- };
-
- /*!
- * The state of a credential. See #kim_credential_state_enum for
- * possible values.
- */
- typedef int kim_credential_state;
-
- /*! @} */
-
- /*!
- * \page kim_credential_overview KIM Credential Overview
- *
- * \section kim_credential_introduction Introduction
- *
- * A Kerberos credential (also called a "Kerberos ticket") is a time-limited
- * token issued by a KDC which authenticates the entity named by the credential's
- * client identity to the service named by the credential's service identity.
- *
- * The kim_credential object contains a single Kerberos credential. KIM credentials
- * objects are always copies of credentials, not references to credentials
- * stored in the cache collection. Modifying credential objects in the ccache
- * collection will not change any existing KIM credential objects.
- *
- * KIM credential APIs are intended for applications and system
- * tools which manage credentials for the user. They are not a substitute for
- * krb5 and GSSAPI functions which obtain service credentials for the purpose
- * of authenticating a client to an application server.
- *
- * \note Many of the APIs listed below have equivalent functions which
- * operate on ccaches. In most cases applications will want to use the
- * ccache versions of these APIs since they automatically store any
- * newly created credentials. See \ref kim_ccache_overview for more
- * information.
- *
- *
- * \section kim_credential_acquire_new Acquiring New Credentials
- *
- * KIM provides the #kim_credential_create_new() API for acquiring new
- * credentials. Credentials can either be obtained for a specific
- * client identity or by specifying #KIM_IDENTITY_ANY to allow
- * the user to choose. Typically callers of this API obtain the client
- * identity using #kim_selection_hints_get_identity(). Depending on the
- * kim_options specified, #kim_credential_create_new() may present a
- * GUI or command line prompt to obtain information from the user.
- *
- * 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
- * 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.
- *
- *
- * \section kim_credential_validate Validating Credentials
- *
- * 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.
- *
- * KIM provides the #kim_credential_validate() API to validate a credential.
- * Note that this API replaces the credential object with a new validated
- * credential object. If you wish to store the new credential in the
- * ccache collection you must either call #kim_credential_store() on the
- * validated credential or use #kim_ccache_validate() instead.
- *
- *
- * \section kim_credential_renew Renewing Credentials
- *
- * A renewable credential can be used to obtain a new identical credential
- * without resending secret information (such as a password) to the KDC.
- * A credential may only be renewed during its renewal lifetime and while
- * valid.
- *
- * KIM provides the #kim_credential_renew() API to renew a credential.
- * Note that this API replaces the credential object with a new renewed
- * credential object. If you wish to store the new credential in the
- * ccache collection you must either call #kim_credential_store() on the
- * renewed credential or use #kim_ccache_renew() instead.
- *
- *
- * \section kim_credential_storing Storing Credentials in the Cache Collection
- *
- * KIM credential objects may be stored in the ccache collection using
- * #kim_credential_store(). This function runs any KIM authentication
- * plugins on the credential and if the plugins return successfully, creates a
- * new ccache for the credential's client identity in the cache collection
- * and stores the credential in that ccache. Any existing ccaches and credentials
- * for that client identity will be overwritten. #kim_credential_store() may
- * optionally return a kim_ccache object for the new ccache if you need to perform
- * further operations on the new ccache.
- *
- * Most of the time if you plan to store the credentials you are manipulating, you
- * should use one of KIM ccache APIs. These functions perform the same operations
- * except that they also call #kim_credential_store() any time the credential object
- * changes. See \ref kim_ccache_overview for more information.
- *
- *
- * \section kim_credential_iterator Iterating over the Credentials in a CCache
- *
- * KIM provides a simple iterator API for iterating over the credentials
- * in a ccache. First, call #kim_credential_iterator_create() to obtain
- * an iterator for a ccache. Then loop calling #kim_credential_iterator_next()
- * until either you find the credential you are looking for or the API
- * returns a NULL credential, indicating that there are no more
- * credentials in the ccache. When you are done with the iterator, call
- * #kim_credential_iterator_free().
- *
- * \note #kim_credential_iterator_next() returns credential objects which
- * must be freed with #kim_credential_free() to avoid leaking memory.
- *
- *
- * \section kim_credential_verify Verifying Credentials
- *
- * When a program acquires TGT credentials for the purpose of authenticating
- * itself to the machine it is running on, it is insufficient for the machine
- * to assume that the caller is authorized just because it got credentials.
- * Instead, the credentials must be verified using a key the local machine.
- * The reason this is necessary is because an attacker can trick the
- * machine into obtaining credentials from any KDC, including malicious ones
- * with the same realm name as the local machine's realm. This exploit is
- * called the Zanarotti attack.
- *
- * In order to avoid the Zanarotti attack, the local machine must authenticate
- * the process in the same way an application server would authenticate a client.
- * Like an application server, the local machine must have its own identity in
- * its realm and a keytab for that identity on its local disk. However,
- * rather than forcing system daemons to use the network-oriented calls in the
- * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to
- * verify credentials directly.
- *
- * The most common reason for using #kim_credential_verify() is user login.
- * If the local machine wants to use Kerberos to verify the username and password
- * provided by the user, it must call #kim_credential_verify() on the credentials
- * it obtains to make sure they are really from a KDC it trusts. Another common
- * case is a server which is only using Kerberos internally. For example an
- * LDAP or web server might use a username and password obtained over the network
- * to get Kerberos credentials. In order to make sure they aren't being tricked
- * into talking to the wrong KDC, these servers must also call
- * #kim_credential_verify().
- *
- * The Zanarotti attack is only a concern if the act of accessing the machine
- * gives the process special access. Thus a managed cluster machine with
- * Kerberos-authenticated networked home directories does not need to call
- * #kim_credential_verify(). Even though an attacker can log in as any user on
- * the cluster machine, the attacker can't actually access any of the user's data
- * or use any of their privileges because those are all authenticated via
- * Kerberized application servers (and thus require actually having credentials
- * for the real local realm).
- *
- * #kim_credential_verify() provides an option to
- * return success even if the machine's host key is not present. This option
- * exists for sites which have a mix of different machines, some of which are
- * vulnerable to the Zanarotti attack and some are not. If this option is used,
- * it is the responsiblity of the machine's maintainer to obtain a keytab
- * for their machine if it needs one.
- *
- *
- * \section kim_credential_properties Examining Credential Properties
- *
- * \li #kim_credential_get_client_identity()
- * returns the credential's client identity.
- *
- * \li #kim_credential_get_service_identity()
- * returns the credential's service identity.
- *
- * \li #kim_credential_is_tgt()
- * returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are
- * credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".
- * These credentials allow the entity named by the client identity to obtain
- * additional service credentials without resending shared secrets (such as a password)
- * to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
- *
- * \li #kim_credential_is_valid()
- * returns whether the credential is valid and if not why the credential is not valid.
- *
- * \li #kim_credential_get_start_time()
- * returns when the credential will become valid.
- * Credentials may be "post-dated" which means that their lifetime starts sometime
- * in the future. Note that when a post-dated credential's start time is reached,
- * the credential must be validated. See \ref kim_credential_validate for more information.
- *
- * \li #kim_credential_get_expiration_time()
- * returns when the credential will expire.
- * Credentials are time limited by the lifetime of the credential. While you can
- * request a credential of any lifetime, the KDC limits the credential lifetime
- * to a administrator-defined maximum. Typically credential lifetime range from 10
- * to 21 hours.
- *
- * \li #kim_credential_get_renewal_expiration_time()
- * returns when the credential will no longer be renewable.
- * Valid credentials may be renewed up until their renewal expiration time.
- * Renewing credentials acquires a fresh set of credentials with a full lifetime
- * without resending secrets to the KDC (such as a password). If credentials are
- * not renewable, this function will return an error.
- *
- *
- * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for
- * information on specific APIs.
- */
-
- /*!
- * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation
- * @{
- */
-
- /*!
- * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache.
- * Must be freed with kim_credential_iterator_free().
- * \param in_ccache a ccache object.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get a credential iterator to enumerate credentials in a ccache.
- */
-
- kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator,
- kim_ccache in_ccache);
-
- /*!
- * \param in_credential_iterator a credential iterator object.
- * \param out_credential on exit, the next credential in the ccache iterated by
- * \a in_credential_iterator. Must be freed with
- * kim_credential_free(). If there are no more credentials
- * this argument will be set to NULL.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the next credential in a ccache.
- */
-
- kim_error kim_credential_iterator_next (kim_credential_iterator in_credential_iterator,
- kim_credential *out_credential);
-
- /*!
- * \param io_credential_iterator a credential iterator object to be freed. Set to NULL on exit.
- * \brief Free memory associated with a credential iterator.
- */
- void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator);
-
- /*!@}*/
-
- /*!
- * \defgroup kim_credential_reference KIM Credential Reference Documentation
- * @{
- */
-
- /*!
- * \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.
- * \note Depending on the kim_options specified, #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.
- * \sa kim_ccache_create_new
- */
- kim_error kim_credential_create_new (kim_credential *out_credential,
- kim_identity in_client_identity,
- kim_options in_options);
-
- /*!
- * \param out_credential on exit, a new credential object containing an initial credential
- * for \a in_identity obtained using \a in_keytab.
- * Must be freed with kim_credential_free().
- * \param in_identity a client identity to obtain a credential for. Specify NULL for
- * the first identity in the keytab.
- * \param in_options options to control credential acquisition.
- * \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Acquire a new initial credential from a keytab.
- * \sa kim_ccache_create_from_keytab
- */
- kim_error kim_credential_create_from_keytab (kim_credential *out_credential,
- kim_identity in_identity,
- kim_options in_options,
- kim_string in_keytab);
-
- /*!
- * \param out_credential on exit, a new credential object which is a copy of \a in_krb5_creds.
- * Must be freed with kim_credential_free().
- * \param in_krb5_context the krb5 context used to create \a in_krb5_creds.
- * \param in_krb5_creds a krb5 credential object.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Copy a credential from a krb5 credential object.
- */
- kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential,
- krb5_context in_krb5_context,
- krb5_creds *in_krb5_creds);
-
- /*!
- * \param out_credential on exit, a new credential object which is a copy of \a in_credential.
- * Must be freed with kim_credential_free().
- * \param in_credential a credential object.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Copy a credential object.
- */
- kim_error kim_credential_copy (kim_credential *out_credential,
- kim_credential in_credential);
-
- /*!
- * \param in_credential a credential object.
- * \param in_krb5_context a krb5 context which will be used to create \a out_krb5_creds.
- * \param out_krb5_creds on exit, a new krb5 creds object which is a copy of \a in_credential.
- * Must be freed with krb5_free_creds().
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get a krb5 credentials object for a credential object.
- */
- kim_error kim_credential_get_krb5_creds (kim_credential in_credential,
- krb5_context in_krb5_context,
- krb5_creds **out_krb5_creds);
-
- /*!
- * \param in_credential a credential object.
- * \param out_client_identity on exit, an identity object containing the client identity of
- * \a in_credential. Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the client identity of a credential object.
- */
- kim_error kim_credential_get_client_identity (kim_credential in_credential,
- kim_identity *out_client_identity);
-
- /*!
- * \param in_credential a credential object.
- * \param out_service_identity on exit, an identity object containing the service identity of
- * \a in_credential. Must be freed with kim_identity_free().
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the service identity of a credential object.
- */
- kim_error kim_credential_get_service_identity (kim_credential in_credential,
- kim_identity *out_service_identity);
-
- /*!
- * \param in_credential a credential object.
- * \param out_is_tgt on exit, whether or not the credential is a TGT.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Check if a credential is a ticket granting ticket.
- */
- kim_error kim_credential_is_tgt (kim_credential in_credential,
- kim_boolean *out_is_tgt);
-
- /*!
- * \param in_credential a credential object.
- * \param out_state on exit, the state of the credential. See #kim_credential_state_enum
- * for the possible values of \a out_state.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Check the state of a credential (valid, expired, postdated, etc).
- */
- kim_error kim_credential_get_state (kim_credential in_credential,
- kim_credential_state *out_state);
-
- /*!
- * \param in_credential a credential object.
- * \param out_start_time on exit, the time when \a in_credential becomes valid.
- * May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the time when the credentials become valid.
- * \sa kim_ccache_get_start_time
- */
- kim_error kim_credential_get_start_time (kim_credential in_credential,
- kim_time *out_start_time);
-
- /*!
- * \param in_credential a credential object.
- * \param out_expiration_time on exit, the time when \a in_credential will expire.
- * May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the time when the credentials will expire.
- * \sa kim_ccache_get_expiration_time
- */
- kim_error kim_credential_get_expiration_time (kim_credential in_credential,
- kim_time *out_expiration_time);
-
- /*!
- * \param in_credential a credential object.
- * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer
- * be renewable. May be in the past or future.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the time when the credentials will no longer be renewable.
- * \sa kim_ccache_get_renewal_expiration_time
- */
- kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential,
- kim_time *out_renewal_expiration_time);
-
-
- /*!
- * \param in_credential a credential object.
- * \param in_client_identity a client identity.
- * \param out_ccache on exit, a ccache object containing \a in_credential with the client
- * identity \a in_client_identity. Must be freed with kim_ccache_free().
- * Specify NULL if you don't want this return value.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Store a credential in a ccache in the cache collection.
- */
- kim_error kim_credential_store (kim_credential in_credential,
- kim_identity in_client_identity,
- kim_ccache *out_ccache);
-
- /*!
- * \param in_credential a TGT credential to be verified.
- * \param in_service_identity a service identity to look for in the keytab. Specify
- * KIM_IDENTITY_ANY to use the default service identity
- * (usually host/<host's FQDN>@<host's local realm>).
- * \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
- * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
- * in the host's keytab will cause a failure.
- * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
- * the Zanarotti attack if the host has no keytab installed.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Verify a TGT credential.
- * \sa kim_ccache_verify
- */
- kim_error kim_credential_verify (kim_credential in_credential,
- kim_identity in_service_identity,
- kim_string in_keytab,
- kim_boolean in_fail_if_no_service_key);
-
- /*!
- * \param io_credential a TGT credential to be renewed. On exit, the old credential
- * object will be freed and \a io_credential will be replaced
- * with a new renewed credential. The new credential must be freed
- * with kim_credential_free().
- * \param in_options initial credential options.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Renew a TGT credential.
- * \sa kim_ccache_renew
- */
- kim_error kim_credential_renew (kim_credential *io_credential,
- kim_options in_options);
-
- /*!
- * \param io_credential a credential object to be validated. On exit, the old credential
- * object will be freed and \a io_credential will be replaced
- * with a new validated credential. The new credential must be freed
- * with kim_credential_free().
- * \param in_options initial credential options.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Validate a TGT credential.
- * \sa kim_ccache_validate
- */
- kim_error kim_credential_validate (kim_credential *io_credential,
- kim_options in_options);
-
- /*!
- * \param io_credential the credential object to be freed. Set to NULL on exit.
- * \brief Free memory associated with a credential object.
- */
- void kim_credential_free (kim_credential *io_credential);
-
- /*!@}*/
+/*!
+ * \addtogroup kim_types_reference
+ * @{
+ */
+
+/*!
+ * Possible credential states. Credentials may be:
+ * \li valid - The credential can be used.
+ * \li expired - The credential's lifetime has been exceeded.
+ * \li not_yet_valid - The credential is post dated and the time when
+ * it becomes valid has not yet been reached.
+ * \li needs_validation - The credential is post-dated and although
+ * the time when it becomes valid has been reached
+ * it has not yet been validated.
+ * \li address_mismatch - The credential contains IP address(es) which do
+ * not match the host's local address(es).
+ */
+enum kim_credential_state_enum {
+ kim_credentials_state_valid = 0,
+ kim_credentials_state_expired = 1,
+ kim_credentials_state_not_yet_valid = 2,
+ kim_credentials_state_needs_validation = 3,
+ kim_credentials_state_address_mismatch = 4
+};
+
+/*!
+ * The state of a credential. See #kim_credential_state_enum for
+ * possible values.
+ */
+typedef int kim_credential_state;
+
+/*! @} */
+
+/*!
+ * \page kim_credential_overview KIM Credential Overview
+ *
+ * \section kim_credential_introduction Introduction
+ *
+ * A Kerberos credential (also called a "Kerberos ticket") is a time-limited
+ * token issued by a KDC which authenticates the entity named by the credential's
+ * client identity to the service named by the credential's service identity.
+ *
+ * The kim_credential object contains a single Kerberos credential. KIM credentials
+ * objects are always copies of credentials, not references to credentials
+ * stored in the cache collection. Modifying credential objects in the ccache
+ * collection will not change any existing KIM credential objects.
+ *
+ * KIM credential APIs are intended for applications and system
+ * tools which manage credentials for the user. They are not a substitute for
+ * krb5 and GSSAPI functions which obtain service credentials for the purpose
+ * of authenticating a client to an application server.
+ *
+ * \note Many of the APIs listed below have equivalent functions which
+ * operate on ccaches. In most cases applications will want to use the
+ * ccache versions of these APIs since they automatically store any
+ * newly created credentials. See \ref kim_ccache_overview for more
+ * information.
+ *
+ *
+ * \section kim_credential_acquire_new Acquiring New Credentials
+ *
+ * KIM provides the #kim_credential_create_new() API for acquiring new
+ * credentials. Credentials can either be obtained for a specific
+ * client identity or by specifying #KIM_IDENTITY_ANY to allow
+ * the user to choose. Typically callers of this API obtain the client
+ * identity using #kim_selection_hints_get_identity(). Depending on the
+ * kim_options specified, #kim_credential_create_new() may present a
+ * GUI or command line prompt to obtain information from the user.
+ *
+ * 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
+ * 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.
+ *
+ *
+ * \section kim_credential_validate Validating Credentials
+ *
+ * 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.
+ *
+ * KIM provides the #kim_credential_validate() API to validate a credential.
+ * Note that this API replaces the credential object with a new validated
+ * credential object. If you wish to store the new credential in the
+ * ccache collection you must either call #kim_credential_store() on the
+ * validated credential or use #kim_ccache_validate() instead.
+ *
+ *
+ * \section kim_credential_renew Renewing Credentials
+ *
+ * A renewable credential can be used to obtain a new identical credential
+ * without resending secret information (such as a password) to the KDC.
+ * A credential may only be renewed during its renewal lifetime and while
+ * valid.
+ *
+ * KIM provides the #kim_credential_renew() API to renew a credential.
+ * Note that this API replaces the credential object with a new renewed
+ * credential object. If you wish to store the new credential in the
+ * ccache collection you must either call #kim_credential_store() on the
+ * renewed credential or use #kim_ccache_renew() instead.
+ *
+ *
+ * \section kim_credential_storing Storing Credentials in the Cache Collection
+ *
+ * KIM credential objects may be stored in the ccache collection using
+ * #kim_credential_store(). This function runs any KIM authentication
+ * plugins on the credential and if the plugins return successfully, creates a
+ * new ccache for the credential's client identity in the cache collection
+ * and stores the credential in that ccache. Any existing ccaches and credentials
+ * for that client identity will be overwritten. #kim_credential_store() may
+ * optionally return a kim_ccache object for the new ccache if you need to perform
+ * further operations on the new ccache.
+ *
+ * Most of the time if you plan to store the credentials you are manipulating, you
+ * should use one of KIM ccache APIs. These functions perform the same operations
+ * except that they also call #kim_credential_store() any time the credential object
+ * changes. See \ref kim_ccache_overview for more information.
+ *
+ *
+ * \section kim_credential_iterator Iterating over the Credentials in a CCache
+ *
+ * KIM provides a simple iterator API for iterating over the credentials
+ * in a ccache. First, call #kim_credential_iterator_create() to obtain
+ * an iterator for a ccache. Then loop calling #kim_credential_iterator_next()
+ * until either you find the credential you are looking for or the API
+ * returns a NULL credential, indicating that there are no more
+ * credentials in the ccache. When you are done with the iterator, call
+ * #kim_credential_iterator_free().
+ *
+ * \note #kim_credential_iterator_next() returns credential objects which
+ * must be freed with #kim_credential_free() to avoid leaking memory.
+ *
+ *
+ * \section kim_credential_verify Verifying Credentials
+ *
+ * When a program acquires TGT credentials for the purpose of authenticating
+ * itself to the machine it is running on, it is insufficient for the machine
+ * to assume that the caller is authorized just because it got credentials.
+ * Instead, the credentials must be verified using a key the local machine.
+ * The reason this is necessary is because an attacker can trick the
+ * machine into obtaining credentials from any KDC, including malicious ones
+ * with the same realm name as the local machine's realm. This exploit is
+ * called the Zanarotti attack.
+ *
+ * In order to avoid the Zanarotti attack, the local machine must authenticate
+ * the process in the same way an application server would authenticate a client.
+ * Like an application server, the local machine must have its own identity in
+ * its realm and a keytab for that identity on its local disk. However,
+ * rather than forcing system daemons to use the network-oriented calls in the
+ * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to
+ * verify credentials directly.
+ *
+ * The most common reason for using #kim_credential_verify() is user login.
+ * If the local machine wants to use Kerberos to verify the username and password
+ * provided by the user, it must call #kim_credential_verify() on the credentials
+ * it obtains to make sure they are really from a KDC it trusts. Another common
+ * case is a server which is only using Kerberos internally. For example an
+ * LDAP or web server might use a username and password obtained over the network
+ * to get Kerberos credentials. In order to make sure they aren't being tricked
+ * into talking to the wrong KDC, these servers must also call
+ * #kim_credential_verify().
+ *
+ * The Zanarotti attack is only a concern if the act of accessing the machine
+ * gives the process special access. Thus a managed cluster machine with
+ * Kerberos-authenticated networked home directories does not need to call
+ * #kim_credential_verify(). Even though an attacker can log in as any user on
+ * the cluster machine, the attacker can't actually access any of the user's data
+ * or use any of their privileges because those are all authenticated via
+ * Kerberized application servers (and thus require actually having credentials
+ * for the real local realm).
+ *
+ * #kim_credential_verify() provides an option to
+ * return success even if the machine's host key is not present. This option
+ * exists for sites which have a mix of different machines, some of which are
+ * vulnerable to the Zanarotti attack and some are not. If this option is used,
+ * it is the responsiblity of the machine's maintainer to obtain a keytab
+ * for their machine if it needs one.
+ *
+ *
+ * \section kim_credential_properties Examining Credential Properties
+ *
+ * \li #kim_credential_get_client_identity()
+ * returns the credential's client identity.
+ *
+ * \li #kim_credential_get_service_identity()
+ * returns the credential's service identity.
+ *
+ * \li #kim_credential_is_tgt()
+ * returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are
+ * credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".
+ * These credentials allow the entity named by the client identity to obtain
+ * additional service credentials without resending shared secrets (such as a password)
+ * to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
+ *
+ * \li #kim_credential_is_valid()
+ * returns whether the credential is valid and if not why the credential is not valid.
+ *
+ * \li #kim_credential_get_start_time()
+ * returns when the credential will become valid.
+ * Credentials may be "post-dated" which means that their lifetime starts sometime
+ * in the future. Note that when a post-dated credential's start time is reached,
+ * the credential must be validated. See \ref kim_credential_validate for more information.
+ *
+ * \li #kim_credential_get_expiration_time()
+ * returns when the credential will expire.
+ * Credentials are time limited by the lifetime of the credential. While you can
+ * request a credential of any lifetime, the KDC limits the credential lifetime
+ * to a administrator-defined maximum. Typically credential lifetime range from 10
+ * to 21 hours.
+ *
+ * \li #kim_credential_get_renewal_expiration_time()
+ * returns when the credential will no longer be renewable.
+ * Valid credentials may be renewed up until their renewal expiration time.
+ * Renewing credentials acquires a fresh set of credentials with a full lifetime
+ * without resending secrets to the KDC (such as a password). If credentials are
+ * not renewable, this function will return an error.
+ *
+ *
+ * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for
+ * information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache.
+ * Must be freed with kim_credential_iterator_free().
+ * \param in_ccache a ccache object.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get a credential iterator to enumerate credentials in a ccache.
+ */
+
+kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator,
+ kim_ccache in_ccache);
+
+/*!
+ * \param in_credential_iterator a credential iterator object.
+ * \param out_credential on exit, the next credential in the ccache iterated by
+ * \a in_credential_iterator. Must be freed with
+ * kim_credential_free(). If there are no more credentials
+ * this argument will be set to NULL.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the next credential in a ccache.
+ */
+
+kim_error kim_credential_iterator_next (kim_credential_iterator in_credential_iterator,
+ kim_credential *out_credential);
+
+/*!
+ * \param io_credential_iterator a credential iterator object to be freed. Set to NULL on exit.
+ * \brief Free memory associated with a credential iterator.
+ */
+void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator);
+
+/*!@}*/
+
+/*!
+ * \defgroup kim_credential_reference KIM Credential Reference Documentation
+ * @{
+ */
+
+/*!
+ * \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.
+ * \note Depending on the kim_options specified, #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.
+ * \sa kim_ccache_create_new
+ */
+kim_error kim_credential_create_new (kim_credential *out_credential,
+ kim_identity in_client_identity,
+ kim_options in_options);
+
+/*!
+ * \param out_credential on exit, a new credential object containing an initial credential
+ * for \a in_identity obtained using \a in_keytab.
+ * Must be freed with kim_credential_free().
+ * \param in_identity a client identity to obtain a credential for. Specify NULL for
+ * the first identity in the keytab.
+ * \param in_options options to control credential acquisition.
+ * \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Acquire a new initial credential from a keytab.
+ * \sa kim_ccache_create_from_keytab
+ */
+kim_error kim_credential_create_from_keytab (kim_credential *out_credential,
+ kim_identity in_identity,
+ kim_options in_options,
+ kim_string in_keytab);
+
+/*!
+ * \param out_credential on exit, a new credential object which is a copy of \a in_krb5_creds.
+ * Must be freed with kim_credential_free().
+ * \param in_krb5_context the krb5 context used to create \a in_krb5_creds.
+ * \param in_krb5_creds a krb5 credential object.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Copy a credential from a krb5 credential object.
+ */
+kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential,
+ krb5_context in_krb5_context,
+ krb5_creds *in_krb5_creds);
+
+/*!
+ * \param out_credential on exit, a new credential object containing a change
+ * password credential for \a in_identity.
+ * Must be freed with kim_credential_free().
+ * \param in_identity a client identity to obtain a change password credential for.
+ * \param in_old_password the current password for \a in_identity. May be
+ * an expired password.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Obtain a credential for changing an identity's password.
+ * \sa kim_credential_change_password
+ */
+kim_error kim_credential_create_for_change_password (kim_credential *out_credential,
+ kim_identity in_identity,
+ kim_string in_old_password);
+
+/*!
+ * \param out_credential on exit, a new credential object which is a copy of \a in_credential.
+ * Must be freed with kim_credential_free().
+ * \param in_credential a credential object.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Copy a credential object.
+ */
+kim_error kim_credential_copy (kim_credential *out_credential,
+ kim_credential in_credential);
+
+/*!
+ * \param in_credential a credential object.
+ * \param in_krb5_context a krb5 context which will be used to create \a out_krb5_creds.
+ * \param out_krb5_creds on exit, a new krb5 creds object which is a copy of \a in_credential.
+ * Must be freed with krb5_free_creds().
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get a krb5 credentials object for a credential object.
+ */
+kim_error kim_credential_get_krb5_creds (kim_credential in_credential,
+ krb5_context in_krb5_context,
+ krb5_creds **out_krb5_creds);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_client_identity on exit, an identity object containing the client identity of
+ * \a in_credential. Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the client identity of a credential object.
+ */
+kim_error kim_credential_get_client_identity (kim_credential in_credential,
+ kim_identity *out_client_identity);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_service_identity on exit, an identity object containing the service identity of
+ * \a in_credential. Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the service identity of a credential object.
+ */
+kim_error kim_credential_get_service_identity (kim_credential in_credential,
+ kim_identity *out_service_identity);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_is_tgt on exit, whether or not the credential is a TGT.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Check if a credential is a ticket granting ticket.
+ */
+kim_error kim_credential_is_tgt (kim_credential in_credential,
+ kim_boolean *out_is_tgt);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_state on exit, the state of the credential. See #kim_credential_state_enum
+ * for the possible values of \a out_state.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Check the state of a credential (valid, expired, postdated, etc).
+ */
+kim_error kim_credential_get_state (kim_credential in_credential,
+ kim_credential_state *out_state);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_start_time on exit, the time when \a in_credential becomes valid.
+ * May be in the past or future.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the time when the credentials become valid.
+ * \sa kim_ccache_get_start_time
+ */
+kim_error kim_credential_get_start_time (kim_credential in_credential,
+ kim_time *out_start_time);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_expiration_time on exit, the time when \a in_credential will expire.
+ * May be in the past or future.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the time when the credentials will expire.
+ * \sa kim_ccache_get_expiration_time
+ */
+kim_error kim_credential_get_expiration_time (kim_credential in_credential,
+ kim_time *out_expiration_time);
+
+/*!
+ * \param in_credential a credential object.
+ * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer
+ * be renewable. May be in the past or future.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Get the time when the credentials will no longer be renewable.
+ * \sa kim_ccache_get_renewal_expiration_time
+ */
+kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential,
+ kim_time *out_renewal_expiration_time);
+
+
+/*!
+ * \param in_credential a credential object.
+ * \param in_client_identity a client identity.
+ * \param out_ccache on exit, a ccache object containing \a in_credential with the client
+ * identity \a in_client_identity. Must be freed with kim_ccache_free().
+ * Specify NULL if you don't want this return value.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Store a credential in a ccache in the cache collection.
+ */
+kim_error kim_credential_store (kim_credential in_credential,
+ kim_identity in_client_identity,
+ kim_ccache *out_ccache);
+
+/*!
+ * \param in_credential a TGT credential to be verified.
+ * \param in_service_identity a service identity to look for in the keytab. Specify
+ * KIM_IDENTITY_ANY to use the default service identity
+ * (usually host/<host's FQDN>@<host's local realm>).
+ * \param in_keytab a path to a keytab. Specify NULL for the default keytab location.
+ * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
+ * in the host's keytab will cause a failure.
+ * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to
+ * the Zanarotti attack if the host has no keytab installed.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Verify a TGT credential.
+ * \sa kim_ccache_verify
+ */
+kim_error kim_credential_verify (kim_credential in_credential,
+ kim_identity in_service_identity,
+ kim_string in_keytab,
+ kim_boolean in_fail_if_no_service_key);
+
+/*!
+ * \param io_credential a TGT credential to be renewed. On exit, the old credential
+ * object will be freed and \a io_credential will be replaced
+ * with a new renewed credential. The new credential must be freed
+ * with kim_credential_free().
+ * \param in_options initial credential options.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Renew a TGT credential.
+ * \sa kim_ccache_renew
+ */
+kim_error kim_credential_renew (kim_credential *io_credential,
+ kim_options in_options);
+
+/*!
+ * \param io_credential a credential object to be validated. On exit, the old credential
+ * object will be freed and \a io_credential will be replaced
+ * with a new validated credential. The new credential must be freed
+ * with kim_credential_free().
+ * \param in_options initial credential options.
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Validate a TGT credential.
+ * \sa kim_ccache_validate
+ */
+kim_error kim_credential_validate (kim_credential *io_credential,
+ kim_options in_options);
+
+/*!
+ * \param in_credential a credential object containing a change
+ * password credential. Use
+ * #kim_credential_change_password to obtain
+ * a change password credential.
+ * \param in_identity an identity to change the password for. May
+ * be different than the identity the credential
+ * is for.
+ * \param in_new_password the password to change the identity to.
+ * \param out_rejected_err on exit, 0 if the password change was
+ * successful or an error describing why the
+ * new password was rejected.
+ * \param out_rejected_message on exit, if \a out_rejected_err is non-zero
+ * this argument will contain an error message
+ * for \a out_rejected_err. Pass NULL if you
+ * do not want this error string. Must be
+ * freed with #kim_string_free();
+ * \param out_rejected_description on exit, if \a out_rejected_err is non-zero
+ * this argument will contain an string describing
+ * why \a in_new_password was rejected. Pass NULL
+ * if you do not want this error string. Must be
+ * freed with #kim_string_free();
+ * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
+ * \brief Change an identity's password.
+ * \sa kim_credential_create_for_change_password
+ */
+kim_error kim_credential_change_password (kim_credential in_credential,
+ kim_identity in_identity,
+ kim_string in_new_password,
+ kim_error *out_rejected_err,
+ kim_string *out_rejected_message,
+ kim_string *out_rejected_description);
+
+/*!
+ * \param io_credential the credential object to be freed. Set to NULL on exit.
+ * \brief Free memory associated with a credential object.
+ */
+void kim_credential_free (kim_credential *io_credential);
+
+/*!@}*/
#ifdef __cplusplus
/*!
* \param in_identity an identity object whose password will be changed.
- * \param in_options initial credential options to be used if a new credential is obtained.
* \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
* \brief Change the password for an identity.
* \note kim_identity_change_password() will acquire a temporary credential to change
- * the password. It uses the \a in_options structure to obtain information about the desired
- * prompter and current password.
+ * the password.
*/
-kim_error kim_identity_change_password (kim_identity in_identity,
- kim_options in_options);
-
-/*!
- * \param in_identity an identity object whose password will be changed.
- * \param in_options initial credential options to be used if a new credential is obtained.
- * \param in_new_password a string representation of the identity's new password.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Change the password for an identity to a caller-provided new password.
- * \note kim_identity_change_password_with_passwords() will acquire a temporary credential
- * to change the password. It uses the \a in_options structure to obtain information about
- * the desired prompter and current password.
- */
-kim_error kim_identity_change_password_to_password (kim_identity in_identity,
- kim_options in_options,
- kim_string in_new_password);
+kim_error kim_identity_change_password (kim_identity in_identity);
/*!
* \param io_identity the identity object to be freed. Set to NULL on exit.
*/
#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0)
-/*!
- * The type of prompt which needs to be displayed.
- * This value determines what type of user interface is displayed.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-typedef uint32_t kim_prompt_type;
-
-enum kim_prompt_type_enum {
- kim_prompt_type_password = 0,
- kim_prompt_type_challenge = 1
-};
-
-/*!
- * The prompt callback used to display a prompt to the user.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-typedef kim_error (*kim_prompt_callback) (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply);
-
-/*!
- * The default prompt callback.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-kim_error kim_prompt_callback_default (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply);
-
-/*!
- * The graphical prompt callback.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-kim_error kim_prompt_callback_gui (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply);
-
-/*!
- * The command line prompt callback.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-kim_error kim_prompt_callback_cli (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply);
-
-/*!
- * The prompt callback which always returns an error.
- * Use to turn off prompting entirely.
- * \note Using this callback may prevent the user from authenicating.
- * See \ref kim_options_custom_prompt_callback for more information.
- */
-kim_error kim_prompt_callback_none (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply);
-
/*! @} */
/*!
* KIM options fall into two major categories: options for controlling how credentials are
* acquired and options for controlling what properties the newly acquired credentials will have:
*
- * \section kim_options_credential_acquisition Options for Controlling Credential Acquisition
- *
- * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user.
- * These secrets may be a certificate, password, SecurID pin, or information from a smart card.
- * If obtaining the secret requires interaction with the user, the Kerberos libraries call a
- * "prompter callback" to display a dialog or command line prompt to request information from
- * the user. If you want to provide your own custom dialogs or command line prompts,
- * the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.
- *
- * \subsection kim_options_custom_prompt_callback Providing a Custom Prompt Callback
- *
- * All secrets are obtained from the user through a #kim_prompt_callback_t. By default,
- * options use #kim_prompt_callback_default, which presents a dialog to request
- * information from the user, or if no graphical access is available, a command line prompt.
- *
- * KIM also provides three other callbacks: #kim_prompt_callback_gui only presents
- * a dialog and returns an error if there is no graphical access. #kim_prompt_callback_cli
- * only presents a command line interface and returns an error if there is no controlling
- * terminal available. #kim_prompt_callback_none always returns an error.
- *
- * Using #kim_options_set_prompt_callback(), you can change the prompt callback to one of
- * the above callbacks or a callback you have defined yourself. Callbacks are called in a
- * loop, one for each prompt. Because network traffic may occur between calls to the prompt
- * callback, your prompt interface should support time passing between calls to the prompter.
- * If you are defining a callback yourself, you should also set your own options data with
- * #kim_options_set_data() for storing state between calls. Options data is a caller
- * defined pointer value -- the Kerberos libaries make no use of it.
- *
* \section kim_options_credential_properties Options for Controlling Credential Properties
*
* Kerberos credentials have a number of different properties which can be requested
kim_error kim_options_copy (kim_options *out_options,
kim_options in_options);
-/*!
- * \param io_options an options object to modify.
- * \param in_prompt_callback a prompt callback function.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Set the prompt callback for obtaining information from the user.
- * \par Default value
- * #kim_prompt_callback_default
- * \sa kim_options_get_prompt_callback()
- */
-kim_error kim_options_set_prompt_callback (kim_options io_options,
- kim_prompt_callback in_prompt_callback);
-
-/*!
- * \param in_options an options object.
- * \param out_prompt_callback on exit, the prompt callback specified by in_options.
- * Does not need to be freed but may become invalid when
- * \a in_options is freed.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get the prompt callback for obtaining information from the user.
- * \par Default value
- * #kim_prompt_callback_default
- * \sa kim_options_set_prompt_callback()
- */
-kim_error kim_options_get_prompt_callback (kim_options in_options,
- kim_prompt_callback *out_prompt_callback);
-
-/*!
- * \param io_options an options object to modify.
- * \param in_data a pointer to caller-specific data.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Set caller-specific data for use in library callbacks.
- * \note This option can be used by the caller to store a pointer to data needed when handling a
- * callback. The KIM library does not use this options data in any way.
- * \par Default value
- * NULL (no data is set by default)
- * \sa kim_options_get_data()
- */
-kim_error kim_options_set_data (kim_options io_options,
- const void *in_data);
-
-/*!
- * \param in_options an options object.
- * \param out_data on exit, the pointer to caller specific data specified by in_options.
- * Does not need to be freed but may become invalid when \a in_options is freed.
- * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure.
- * \brief Get caller-specific data for use in library callbacks.
- * \note This option can be used by the caller to store a pointer to data needed when handling a
- * callback. The KIM library does not use this options data in any way.
- * \par Default value
- * NULL (no data is set by default)
- * \sa kim_options_set_data()
- */
-kim_error kim_options_get_data (kim_options in_options,
- const void **out_data);
-
/*!
* \param io_options an options object to modify.
* \param in_start_time a start date (in seconds since January 1, 1970). Set to
extern "C" {
#endif
+/*!
+ * The type of prompt which needs to be displayed.
+ * This value determines what type of user interface is displayed.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+typedef uint32_t kim_prompt_type;
+
+enum kim_prompt_type_enum {
+ kim_prompt_type_password = 0,
+ kim_prompt_type_preauth = 1
+};
+
/*
+ * Plugins for Controlling Identity Selection and Credential Acquisition
+ *
+ * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user.
+ * These secrets may be a certificate, password, SecurID pin, or information from a smart card.
+ * If obtaining the secret requires interaction with the user, the Kerberos libraries call a
+ * "prompter callback" to display a dialog or command line prompt to request information from
+ * the user. If you want to provide your own custom dialogs or command line prompts,
+ * the KIM APIs provide a plugin mechanism for replacing the default prompt ui with your own.
+ *
* The function table / structure which a KIM ui plugin module must export
* as "kim_ui_0". If the interfaces work correctly, future versions of the
* table will add either more callbacks or more arguments to callbacks, and
* this ui. */
kim_error (*init) (void **out_context);
+ /* Present UI which allows the user to enter a new identity.
+ * This is typically called when the user selects a "new tickets"
+ * control or menu item from a ticket management utility.
+ * If this UI calls into KIM to get new credentials it may
+ * call auth_prompt below. */
+ kim_error (*enter_identity) (void *in_context,
+ kim_identity *out_identity);
+
/* Present UI to select which identity to use.
+ * This is typically called the first time an application tries to use
+ * Kerberos and is used to establish a hints preference for the application.
* If this UI calls into KIM to get new credentials it may
- * call acquire_new_credentials below. */
+ * call auth_prompt below. */
kim_error (*select_identity) (void *in_context,
kim_selection_hints in_hints,
kim_identity *out_identity);
kim_error (*auth_prompt) (void *in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
char **out_reply);
/* Prompt to change the identity's password.
- * May be combined with an auth prompt if additional auth is required,
+ * May be combined with an auth_prompt if additional auth is required,
* eg: SecurID pin.
* If in_old_password_expired is true, this callback is in response
* to an expired password error. If this is the case the same context
char **out_verify_password);
/* Display an error to the user; may be called after any of the prompts */
- kim_error (*display_error) (void *in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description);
+ kim_error (*handle_error) (void *in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description);
- /* Free strings returned by the UI */
- void (*free_string) (void *in_context,
- char *io_string);
+ /* Free strings returned by the UI. Will be called once for each string
+ * returned from a plugin callback. If you have returned a string twice
+ * just make sure your free function checks for NULL and sets the pointer
+ * to NULL when done freeing memory. */
+ void (*free_string) (void *in_context,
+ char **io_string);
/* Called after the last prompt (even on error) to allow the UI to
* free allocated resources associated with its context. */
kim_identity_get_component_at_index
kim_identity_get_krb5_principal
kim_identity_change_password
-kim_identity_change_password_to_password
kim_identity_free
-kim_prompt_callback_default
-kim_prompt_callback_gui
-kim_prompt_callback_cli
-kim_prompt_callback_none
-
kim_options_create
kim_options_copy
-kim_options_set_prompt_callback
-kim_options_get_prompt_callback
-kim_options_set_data
-kim_options_get_data
kim_options_set_start_time
kim_options_get_start_time
kim_options_set_lifetime
kim_credential_create_new
kim_credential_create_from_krb5_creds
+kim_credential_create_for_change_password
kim_credential_copy
kim_credential_get_krb5_creds
kim_credential_get_client_identity
kim_credential_store
kim_credential_renew
kim_credential_validate
+kim_credential_change_password
kim_credential_free
kim_ccache_iterator_create
kim_identity_get_component_at_index
kim_identity_get_krb5_principal
kim_identity_change_password
-kim_identity_change_password_to_password
kim_identity_free
-kim_prompt_callback_default
-kim_prompt_callback_gui
-kim_prompt_callback_cli
-kim_prompt_callback_none
-
kim_options_create
kim_options_copy
kim_options_set_start_time
kim_credential_create_new
kim_credential_create_from_keytab
kim_credential_create_from_krb5_creds
+kim_credential_create_for_change_password
kim_credential_copy
kim_credential_get_krb5_creds
kim_credential_get_client_identity
kim_credential_verify
kim_credential_renew
kim_credential_validate
+kim_credential_change_password
kim_credential_free
kim_ccache_iterator_create
/* ------------------------------------------------------------------------ */
kim_error kim_credential_create_new (kim_credential *out_credential,
- kim_identity in_client_identity,
+ kim_identity in_identity,
kim_options in_options)
{
kim_error err = KIM_NO_ERROR;
kim_credential credential = NULL;
-
+ kim_options options = NULL;
+ kim_ui_context context;
+ kim_string service = NULL;
+ krb5_principal principal = NULL;
+ krb5_get_init_creds_opt *init_cred_options = NULL;
+ kim_boolean ui_inited = 0;
+ kim_boolean done = 0;
+
if (!err && !out_credential) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
}
if (!err) {
-#warning Get tickets here
+ if (in_options) {
+ options = in_options;
+ } else {
+ err = kim_options_create (&options);
+ }
+ }
+
+ if (!err) {
+ err = kim_options_get_init_cred_options (options,
+ credential->context,
+ &init_cred_options);
+ }
+
+ if (!err) {
+ kim_options_get_service_name (options, &service);
+ }
+
+ if (!err) {
+ err = kim_identity_get_krb5_principal (in_identity,
+ credential->context,
+ &principal);
+ }
+
+ if (!err) {
+ err = kim_ui_init (&context);
+ if (!err) {
+ context.identity = in_identity; /* used by kim_ui_prompter */
+ ui_inited = 1;
+ }
+ }
+
+ while (!err && !done) {
+ krb5_creds creds;
+ kim_boolean free_creds = 0;
+
+ err = krb5_error (credential->context,
+ krb5_get_init_creds_password (credential->context,
+ &creds,
+ principal,
+ NULL,
+ kim_ui_prompter,
+ &context, 0,
+ (char *) service,
+ init_cred_options));
+
+ if (!err) { free_creds = 1; }
+
+ if (!err) {
+ err = krb5_error (credential->context,
+ krb5_copy_creds (credential->context,
+ &creds,
+ &credential->creds));
+ }
+
+ if (!err || err == KIM_USER_CANCELED_ERR) {
+ /* new creds obtained or the user gave up */
+ done = 1;
+
+ } else {
+ /* new creds failed, report error to user */
+ err = kim_ui_handle_kim_error (&context, in_identity,
+ kim_ui_error_type_authentication,
+ err);
+ }
+
+ if (free_creds) { krb5_free_cred_contents (credential->context, &creds); }
+ }
+
+ if (ui_inited) {
+ kim_error fini_err = kim_ui_fini (&context);
+ if (!err) { err = check_error (fini_err); }
+ }
+
+ /* free before credential is passed back to caller */
+ if (credential && init_cred_options) {
+ kim_options_free_init_cred_options (credential->context, &init_cred_options);
}
if (!err) {
credential = NULL;
}
+ if (principal ) { krb5_free_principal (credential->context, principal); }
+ if (!in_options) { kim_options_free (&options); }
+ kim_string_free (&service);
kim_credential_free (&credential);
return check_error (err);
}
if (!err) {
- err = krb5_error (NULL, krb5_init_context (&credential->context));
+ err = krb5_error (in_krb5_context,
+ krb5_copy_context (in_krb5_context,
+ &credential->context));
}
if (!err) {
/* ------------------------------------------------------------------------ */
+kim_error kim_credential_create_for_change_password (kim_credential *out_credential,
+ kim_identity in_identity,
+ kim_string in_old_password)
+{
+ kim_error err = KIM_NO_ERROR;
+ kim_credential credential = NULL;
+ kim_string realm = NULL;
+ kim_string service = NULL;
+ kim_ui_context context;
+ krb5_principal principal = NULL;
+ kim_string service_format = "kadmin/changepw@%s";
+ kim_boolean ui_inited = 0;
+ kim_boolean done = 0;
+
+ if (!err && !out_credential ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_identity ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_old_password) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ err = kim_credential_allocate (&credential);
+ }
+
+ if (!err) {
+ err = krb5_error (NULL, krb5_init_context (&credential->context));
+ }
+
+ if (!err) {
+ err = kim_identity_get_krb5_principal (in_identity,
+ credential->context,
+ &principal);
+ }
+
+ if (!err) {
+ err = kim_identity_get_realm (in_identity, &realm);
+ }
+
+ if (!err) {
+ err = kim_string_create_from_format (&service, service_format, realm);
+ }
+
+ if (!err) {
+ err = kim_ui_init (&context);
+ if (!err) {
+ context.identity = in_identity; /* used by kim_ui_prompter */
+ ui_inited = 1;
+ }
+ }
+
+ while (!err && !done) {
+ krb5_creds creds;
+ kim_boolean free_creds = 0;
+ krb5_get_init_creds_opt opts;
+
+ krb5_get_init_creds_opt_init (&opts);
+ krb5_get_init_creds_opt_set_tkt_life (&opts, 5*60);
+ krb5_get_init_creds_opt_set_renew_life (&opts, 0);
+ krb5_get_init_creds_opt_set_forwardable (&opts, 0);
+ krb5_get_init_creds_opt_set_proxiable (&opts, 0);
+
+ err = krb5_error (credential->context,
+ krb5_get_init_creds_password (credential->context,
+ &creds,
+ principal,
+ (char *) in_old_password,
+ kim_ui_prompter,
+ &context, 0, (char *) service,
+ &opts));
+ if (!err) { free_creds = 1; }
+
+ if (!err) {
+ err = krb5_error (credential->context,
+ krb5_copy_creds (credential->context,
+ &creds,
+ &credential->creds));
+ }
+
+ if (!err || err == KIM_USER_CANCELED_ERR) {
+ /* new creds obtained or the user gave up */
+ done = 1;
+
+ } else {
+ /* new creds failed, report error to user */
+ err = kim_ui_handle_kim_error (&context, in_identity,
+ kim_ui_error_type_change_password,
+ err);
+ }
+
+ if (free_creds) { krb5_free_cred_contents (credential->context, &creds); }
+ }
+
+ if (ui_inited) {
+ kim_error fini_err = kim_ui_fini (&context);
+ if (!err) { err = check_error (fini_err); }
+ }
+
+ if (!err) {
+ *out_credential = credential;
+ credential = NULL;
+ }
+
+ if (principal ) { krb5_free_principal (credential->context, principal); }
+
+ kim_string_free (&realm);
+ kim_string_free (&service);
+ kim_credential_free (&credential);
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_credential_copy (kim_credential *out_credential,
kim_credential in_credential)
{
}
if (!err) {
- err = krb5_error (NULL, krb5_init_context (&credential->context));
+ err = krb5_error (in_credential->context,
+ krb5_copy_context (in_credential->context,
+ &credential->context));
}
if (!err) {
k5ccache, in_credential->creds));
}
-#warning Call plugins here
-
if (!err && out_ccache) {
err = kim_ccache_create_from_krb5_ccache (out_ccache, context, k5ccache);
}
/* ------------------------------------------------------------------------ */
+kim_error kim_credential_change_password (kim_credential in_credential,
+ kim_identity in_identity,
+ kim_string in_new_password,
+ kim_error *out_rejected_err,
+ kim_string *out_rejected_message,
+ kim_string *out_rejected_description)
+{
+ kim_error err = KIM_NO_ERROR;
+ krb5_principal principal = NULL;
+ int rejected_code = 0;
+ krb5_data message_data;
+ krb5_data description_data;
+
+ if (!err && !in_credential ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_new_password ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !out_rejected_err) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ /* out_rejected_message and out_rejected_description may be NULL */
+
+ if (!err) {
+ err = kim_identity_get_krb5_principal (in_identity,
+ in_credential->context,
+ &principal);
+ }
+
+ if (!err) {
+ err = krb5_error (in_credential->context,
+ krb5_principal_compare (in_credential->context,
+ in_credential->creds->client,
+ principal));
+ }
+
+ if (!err) {
+ if (krb5_principal_compare (in_credential->context,
+ in_credential->creds->client,
+ principal)) {
+ /* Same principal, change the password normally */
+ err = krb5_error (in_credential->context,
+ krb5_change_password (in_credential->context,
+ in_credential->creds,
+ (char *) in_new_password,
+ &rejected_code,
+ &message_data,
+ &description_data));
+ } else {
+ /* Different principal, use set change password protocol */
+ err = krb5_error (in_credential->context,
+ krb5_set_password (in_credential->context,
+ in_credential->creds,
+ (char *) in_new_password,
+ principal,
+ &rejected_code,
+ &message_data,
+ &description_data));
+ }
+
+ }
+
+ if (!err && rejected_code) {
+ kim_string rejected_message = NULL;
+ kim_string rejected_description = NULL;
+
+ if (!err) {
+ if (message_data.data && message_data.length > 0) {
+ err = kim_string_create_from_buffer (&rejected_message,
+ message_data.data,
+ message_data.length);
+ } else {
+ err = kim_os_string_create_localized (&rejected_message,
+ "KLStringChangePasswordFailed");
+ }
+ }
+
+ if (!err) {
+ if (description_data.data && description_data.length > 0) {
+ err = kim_string_create_from_buffer (&rejected_description,
+ description_data.data,
+ description_data.length);
+ } else {
+ err = kim_os_string_create_localized (&rejected_description,
+ "KLStringPasswordRejected");
+ }
+ }
+
+ if (!err) {
+ char *c;
+
+ // replace all \n and \r characters with spaces
+ for (c = (char *) rejected_message; *c != '\0'; c++) {
+ if ((*c == '\n') || (*c == '\r')) { *c = ' '; }
+ }
+
+ for (c = (char *) rejected_description; *c != '\0'; c++) {
+ if ((*c == '\n') || (*c == '\r')) { *c = ' '; }
+ }
+ }
+
+ if (!err) {
+ if (out_rejected_message) {
+ *out_rejected_message = rejected_message;
+ rejected_message = NULL;
+ }
+
+ if (out_rejected_description) {
+ *out_rejected_description = rejected_description;
+ rejected_description = NULL;
+ }
+ }
+
+ kim_string_free (&rejected_message);
+ kim_string_free (&rejected_description);
+
+ krb5_free_data_contents (in_credential->context, &message_data);
+ krb5_free_data_contents (in_credential->context, &description_data);
+ }
+
+ if (!err) {
+ *out_rejected_err = rejected_code;
+ }
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
void kim_credential_free (kim_credential *io_credential)
{
if (io_credential && *io_credential) {
}
}
- if (!err) {
-#warning Run translator here
- }
-
if (!err) {
*out_identity = identity;
identity = NULL;
&identity->principal));
}
- if (!err) {
-#warning Run translator here
- }
-
if (!err) {
*out_identity = identity;
identity = NULL;
&identity->principal));
}
- if (!err) {
-#warning Run translator here
- }
-
if (!err) {
*out_identity = identity;
identity = NULL;
err = kim_identity_allocate (&identity);
if (!err) {
- err = krb5_error (NULL, krb5_init_context (&identity->context));
+ err = krb5_error (in_identity->context,
+ krb5_copy_context (in_identity->context,
+ &identity->context));
}
if (!err) {
/* ------------------------------------------------------------------------ */
-kim_error kim_identity_change_password (kim_identity in_identity,
- kim_options in_options)
+kim_error kim_identity_change_password (kim_identity in_identity)
{
kim_error err = KIM_NO_ERROR;
+ kim_ui_context context;
+ kim_boolean ui_inited = 0;
+ kim_boolean done = 0;
if (!err && !in_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
-#warning Implement change password GUI support
+ err = kim_ui_init (&context);
+ if (!err) { ui_inited = 1; }
}
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_identity_change_password_to_password (kim_identity in_identity,
- kim_options in_options,
- kim_string in_new_password)
-{
- kim_error err = KIM_NO_ERROR;
- if (!err && !in_identity ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !in_new_password) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ while (!err && !done) {
+ char *old_password = NULL;
+ char *new_password = NULL;
+ char *verify_password = NULL;
+ kim_error rejected_err = KIM_NO_ERROR;
+ kim_string rejected_message = NULL;
+ kim_string rejected_description = NULL;
+
+ err = kim_ui_change_password (&context,
+ in_identity,
+ 0 /* old password not expired */,
+ &old_password,
+ &new_password,
+ &verify_password);
+
+ if (!err) {
+ kim_comparison comparison;
+
+ err = kim_string_compare (new_password, verify_password, &comparison);
+ if (!err && !kim_comparison_is_equal_to (comparison)) {
+ err = check_error (KIM_PASSWORD_MISMATCH_ERR);
+ }
+ }
+
+ if (!err) {
+ kim_credential credential = NULL;
+
+ if (context.type == kim_ui_type_cli && context.tcontext) {
+ /* command line has already gotten the credentials for us */
+ credential = (kim_credential) context.tcontext;
+ } else {
+ err = kim_credential_create_for_change_password (&credential,
+ in_identity,
+ old_password);
+ }
+
+ if (!err) {
+ err = kim_credential_change_password (credential,
+ in_identity,
+ new_password,
+ &rejected_err,
+ &rejected_message,
+ &rejected_description);
+
+ }
+
+ kim_credential_free (&credential);
+ }
+
+ if (!err || err == KIM_USER_CANCELED_ERR) {
+ /* password change succeeded or the user gave up */
+ done = 1;
+
+ } else if (!err && rejected_err) {
+ /* Password rejected, report it to the user */
+ err = kim_ui_handle_error (&context, in_identity,
+ rejected_err,
+ rejected_message,
+ rejected_description);
+
+ } else {
+ /* Password change failed, report error to user */
+ err = kim_ui_handle_kim_error (&context, in_identity,
+ kim_ui_error_type_change_password,
+ err);
+ }
+
+ kim_string_free (&rejected_message);
+ kim_string_free (&rejected_description);
+ kim_ui_free_string (&context, &old_password);
+ kim_ui_free_string (&context, &new_password);
+ kim_ui_free_string (&context, &verify_password);
+ }
- if (!err) {
-#warning Implement change password support
+ if (ui_inited) {
+ kim_error fini_err = kim_ui_fini (&context);
+ if (!err) { err = check_error (fini_err); }
}
return check_error (err);
/* ------------------------------------------------------------------------ */
struct kim_options_opaque {
- kim_prompt_callback prompt_callback;
- const void *prompt_callback_data;
kim_time start_time;
kim_lifetime lifetime;
kim_boolean renewable;
};
struct kim_options_opaque kim_options_initializer = {
-NULL, NULL,
0,
kim_default_lifetime,
kim_default_renewable,
if (!err && in_options != KIM_OPTIONS_DEFAULT) {
err = kim_options_allocate (&options);
- if (!err) {
- options->prompt_callback = in_options->prompt_callback;
- options->prompt_callback_data = in_options->prompt_callback_data;
- }
-
if (!err) {
options->start_time = in_options->start_time;
options->lifetime = in_options->lifetime;
/* ------------------------------------------------------------------------ */
-kim_error kim_options_set_prompt_callback (kim_options io_options,
- kim_prompt_callback in_prompt_callback)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !io_options) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- io_options->prompt_callback = in_prompt_callback;
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_options_get_prompt_callback (kim_options in_options,
- kim_prompt_callback *out_prompt_callback)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !in_options ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !out_prompt_callback) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- *out_prompt_callback = in_options->prompt_callback;
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_options_set_data (kim_options io_options,
- const void *in_data)
-
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !io_options) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- io_options->prompt_callback_data = in_data;
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_options_get_data (kim_options in_options,
- const void **out_data)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !in_options) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !out_data ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- *out_data = in_options->prompt_callback_data;
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
kim_error kim_options_set_start_time (kim_options io_options,
kim_time in_start_time)
{
if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err && !out_init_cred_options) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !in_options->addressless) {
- err = krb5_error (in_context,
- krb5_os_localaddr (in_context, &addresses));
- }
-
if (!err) {
krb5_get_init_creds_opt_alloc (in_context, &init_cred_options);
- krb5_get_init_creds_opt_set_tkt_life (init_cred_options, in_options->lifetime);
- krb5_get_init_creds_opt_set_renew_life (init_cred_options, in_options->renewable ? in_options->renewal_lifetime : 0);
- krb5_get_init_creds_opt_set_forwardable (init_cred_options, in_options->forwardable);
- krb5_get_init_creds_opt_set_proxiable (init_cred_options, in_options->proxiable);
- krb5_get_init_creds_opt_set_address_list (init_cred_options, addresses);
+ }
+
+ if (!err && in_options) {
+ if (!in_options->addressless) {
+ err = krb5_error (in_context,
+ krb5_os_localaddr (in_context, &addresses));
+ }
- *out_init_cred_options = init_cred_options;
- init_cred_options = NULL;
- addresses = NULL;
+ if (!err) {
+ krb5_get_init_creds_opt_set_tkt_life (init_cred_options, in_options->lifetime);
+ krb5_get_init_creds_opt_set_renew_life (init_cred_options, in_options->renewable ? in_options->renewal_lifetime : 0);
+ krb5_get_init_creds_opt_set_forwardable (init_cred_options, in_options->forwardable);
+ krb5_get_init_creds_opt_set_proxiable (init_cred_options, in_options->proxiable);
+ krb5_get_init_creds_opt_set_address_list (init_cred_options, addresses);
+ addresses = NULL;
+ }
+ }
+
+ if (!err) {
+ *out_init_cred_options = init_cred_options;
+ init_cred_options = NULL;
}
if (init_cred_options) { krb5_get_init_creds_opt_free (in_context, init_cred_options); }
if (!err && io_init_cred_options && *io_init_cred_options) {
if ((*io_init_cred_options)->address_list) {
krb5_free_addresses (in_context, (*io_init_cred_options)->address_list);
+ (*io_init_cred_options)->address_list = NULL;
}
krb5_get_init_creds_opt_free (in_context, *io_init_cred_options);
*io_init_cred_options = NULL;
*io_options = NULL;
}
}
-
-#pragma mark -
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_prompt_callback_default (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !out_reply) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_prompt_callback_gui (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !out_reply) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_prompt_callback_cli (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply)
-{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !out_reply) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- }
-
- return check_error (err);
-}
-
-/* ------------------------------------------------------------------------ */
-
-kim_error kim_prompt_callback_none (kim_prompt_type in_type,
- kim_string in_title,
- kim_string in_message,
- kim_string in_description,
- char **out_reply)
-{
- return KIM_USER_CANCELED_ERR;
-}
}
if (!err && !identity && in_selection_hints->allow_user_interaction) {
-#warning GUI to let user pick identity here
+ kim_ui_context context;
+
+ err = kim_ui_init (&context);
+
+ if (!err) {
+ err = kim_ui_select_identity (&context,
+ in_selection_hints,
+ &identity);
+ }
+
+ if (!err) {
+ err = kim_ui_fini (&context);
+ }
}
if (!err) {
{
return kim_os_string_compare (in_string,
in_compare_to_string,
+ 0, /* case sensitive */
out_comparison);
}
/* OS-specific because it should use UTF8-safe sorting where possible */
kim_error kim_os_string_compare (kim_string in_string,
kim_string in_compare_to_string,
+ kim_boolean in_case_insensitive,
kim_comparison *out_comparison);
+kim_error kim_os_string_create_localized (kim_string *out_string,
+ kim_string in_string);
+
#endif /* KIM_STRING_PRIVATE_H */
#include "kim_private.h"
+/* ------------------------------------------------------------------------ */
+
+static kim_prompt_type kim_ui_ptype2ktype (krb5_prompt_type type)
+{
+ switch (type) {
+ case KRB5_PROMPT_TYPE_PASSWORD:
+ return kim_prompt_type_password;
+
+ case KRB5_PROMPT_TYPE_PREAUTH:
+ return kim_prompt_type_preauth;
+ }
+ return kim_prompt_type_preauth;
+}
+
+/* ------------------------------------------------------------------------ */
+/* Set the identity field in your context and pass the context as the data */
+
+krb5_error_code kim_ui_prompter (krb5_context in_krb5_context,
+ void *in_context,
+ const char *in_name,
+ const char *in_banner,
+ int in_num_prompts,
+ krb5_prompt in_prompts[])
+{
+ kim_error err = KIM_NO_ERROR;
+ krb5_prompt_type *types = NULL;
+ kim_ui_context *context = (kim_ui_context *) in_context;
+ int i;
+
+ if (!err && !in_krb5_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_prompts ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ types = krb5_get_prompt_types (in_krb5_context);
+ if (!types) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ }
+
+ for (i = 0; !err && i < in_num_prompts; i++) {
+ char *reply = NULL;
+
+ err = kim_ui_auth_prompt (context,
+ context->identity,
+ kim_ui_ptype2ktype (types[i]),
+ in_prompts[i].hidden,
+ in_name,
+ in_banner,
+ in_prompts[i].prompt,
+ &reply);
+
+ if (!err) {
+ uint32_t reply_len = strlen (reply);
+
+ if ((reply_len + 1) > in_prompts[i].reply->length) {
+ kim_debug_printf ("%s(): reply %d is too long (is %d, should be %d)\n",
+ __FUNCTION__, i,
+ reply_len, in_prompts[i].reply->length);
+ reply_len = in_prompts[i].reply->length;
+ }
+
+ memmove (in_prompts[i].reply->data, reply, reply_len + 1);
+ in_prompts[i].reply->length = reply_len;
+ }
+
+ kim_ui_free_string (context, &reply);
+ }
+
+ return check_error (err);
+}
+
+#pragma mark -
+
/* ------------------------------------------------------------------------ */
kim_error kim_ui_init (kim_ui_context *io_context)
if (!err && !io_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
+#ifndef LEAN_CLIENT
kim_ui_environment environment = kim_library_ui_environment ();
if (environment == KIM_UI_ENVIRONMENT_GUI) {
+#endif /* LEAN_CLIENT */
io_context->type = kim_ui_type_gui_plugin;
err = kim_ui_plugin_init ((kim_ui_plugin_context *) &io_context->tcontext);
-
+#ifndef LEAN_CLIENT
if (err) {
io_context->type = kim_ui_type_gui_builtin;
err = check_error (KIM_NO_UI_ERR);
}
+#endif /* LEAN_CLIENT */
}
return check_error (err);
/* ------------------------------------------------------------------------ */
+kim_error kim_ui_enter_identity (kim_ui_context *in_context,
+ kim_identity *out_identity)
+{
+ kim_error err = KIM_NO_ERROR;
+
+ if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !out_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ if (in_context->type == kim_ui_type_gui_plugin) {
+ err = kim_ui_plugin_enter_identity ((kim_ui_plugin_context) in_context->tcontext,
+ out_identity);
+
+#ifndef LEAN_CLIENT
+ } else if (in_context->type == kim_ui_type_gui_builtin) {
+ err = kim_ui_gui_enter_identity ((kim_ui_gui_context) in_context->tcontext,
+ out_identity);
+
+ } else if (in_context->type == kim_ui_type_cli) {
+ err = kim_ui_cli_enter_identity ((kim_ui_cli_context) in_context->tcontext,
+ out_identity);
+
+#endif /* LEAN_CLIENT */
+
+ } else {
+ err = check_error (KIM_NO_UI_ERR);
+ }
+ }
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_ui_select_identity (kim_ui_context *in_context,
kim_selection_hints in_hints,
kim_identity *out_identity)
in_hints,
out_identity);
+#ifndef LEAN_CLIENT
} else if (in_context->type == kim_ui_type_gui_builtin) {
err = kim_ui_gui_select_identity ((kim_ui_gui_context) in_context->tcontext,
in_hints,
in_hints,
out_identity);
+#endif /* LEAN_CLIENT */
+
} else {
err = check_error (KIM_NO_UI_ERR);
}
kim_error kim_ui_auth_prompt (kim_ui_context *in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
err = kim_ui_plugin_auth_prompt ((kim_ui_plugin_context) in_context->tcontext,
in_identity,
in_type,
+ in_hide_reply,
in_title,
in_message,
in_description,
out_reply);
+#ifndef LEAN_CLIENT
} else if (in_context->type == kim_ui_type_gui_builtin) {
err = kim_ui_gui_auth_prompt ((kim_ui_gui_context) in_context->tcontext,
in_identity,
in_type,
+ in_hide_reply,
in_title,
in_message,
in_description,
err = kim_ui_cli_auth_prompt ((kim_ui_cli_context) in_context->tcontext,
in_identity,
in_type,
+ in_hide_reply,
in_title,
in_message,
in_description,
out_reply);
+#endif /* LEAN_CLIENT */
} else {
err = check_error (KIM_NO_UI_ERR);
out_new_password,
out_verify_password);
+#ifndef LEAN_CLIENT
} else if (in_context->type == kim_ui_type_gui_builtin) {
err = kim_ui_gui_change_password ((kim_ui_gui_context) in_context->tcontext,
in_identity,
out_new_password,
out_verify_password);
+#endif /* LEAN_CLIENT */
+
} else {
err = check_error (KIM_NO_UI_ERR);
}
return check_error (err);
}
+/* ------------------------------------------------------------------------ */
+/* Helper function */
+
+kim_error kim_ui_handle_kim_error (kim_ui_context *in_context,
+ kim_identity in_identity,
+ enum kim_ui_error_type in_type,
+ kim_error in_error)
+{
+ kim_error err = KIM_NO_ERROR;
+ kim_string message = NULL;
+ kim_string description = NULL;
+
+ if (!err) {
+ /* Do this first so last error doesn't get overwritten */
+ err = kim_string_get_last_error_message (&description, in_error);
+ }
+
+ if (!err && !in_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ kim_string key = NULL;
+
+ switch (in_type) {
+ case kim_ui_error_type_authentication:
+ key = "KLStringLoginFailed";
+ break;
+
+ case kim_ui_error_type_change_password:
+ key = "KLStringChangePasswordFailed";
+ break;
+
+ case kim_ui_error_type_selection:
+ case kim_ui_error_type_generic:
+ default:
+ key = "KLStringKerberosOperationFailed";
+ break;
+ }
+
+ err = kim_os_string_create_localized (&message, key);
+ }
+
+ if (!err) {
+ err = kim_ui_handle_error (in_context, in_identity,
+ in_error, message, description);
+ }
+
+ kim_string_free (&description);
+ kim_string_free (&message);
+
+ return check_error (err);
+}
+
/* ------------------------------------------------------------------------ */
-kim_error kim_ui_display_error (kim_ui_context *in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description)
+kim_error kim_ui_handle_error (kim_ui_context *in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description)
{
kim_error err = KIM_NO_ERROR;
if (!err) {
if (in_context->type == kim_ui_type_gui_plugin) {
- err = kim_ui_plugin_display_error ((kim_ui_plugin_context) in_context->tcontext,
+ err = kim_ui_plugin_handle_error ((kim_ui_plugin_context) in_context->tcontext,
in_identity,
in_error,
in_error_message,
in_error_description);
+#ifndef LEAN_CLIENT
} else if (in_context->type == kim_ui_type_gui_builtin) {
- err = kim_ui_gui_display_error ((kim_ui_gui_context) in_context->tcontext,
+ err = kim_ui_gui_handle_error ((kim_ui_gui_context) in_context->tcontext,
in_identity,
in_error,
in_error_message,
in_error_description);
} else if (in_context->type == kim_ui_type_cli) {
- err = kim_ui_cli_display_error ((kim_ui_cli_context) in_context->tcontext,
+ err = kim_ui_cli_handle_error ((kim_ui_cli_context) in_context->tcontext,
in_identity,
in_error,
in_error_message,
in_error_description);
+#endif /* LEAN_CLIENT */
} else {
err = check_error (KIM_NO_UI_ERR);
/* ------------------------------------------------------------------------ */
-void kim_ui_free_string (kim_ui_context *in_context,
- char *io_string)
+void kim_ui_free_string (kim_ui_context *in_context,
+ char **io_string)
{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !in_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !io_string ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
+ if (in_context && io_string && *io_string) {
if (in_context->type == kim_ui_type_gui_plugin) {
kim_ui_plugin_free_string ((kim_ui_plugin_context) in_context->tcontext,
io_string);
+#ifndef LEAN_CLIENT
} else if (in_context->type == kim_ui_type_gui_builtin) {
kim_ui_gui_free_string ((kim_ui_gui_context) in_context->tcontext,
io_string);
} else if (in_context->type == kim_ui_type_cli) {
kim_ui_cli_free_string ((kim_ui_cli_context) in_context->tcontext,
io_string);
+#endif /* LEAN_CLIENT */
- } else {
- err = check_error (KIM_NO_UI_ERR);
}
}
}
if (!err && !io_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
+ kim_identity_free (&io_context->identity);
+
if (io_context->type == kim_ui_type_gui_plugin) {
err = kim_ui_plugin_fini ((kim_ui_plugin_context *) &io_context->tcontext);
+#ifndef LEAN_CLIENT
} else if (io_context->type == kim_ui_type_gui_builtin) {
err = kim_ui_gui_fini ((kim_ui_gui_context *) &io_context->tcontext);
} else if (io_context->type == kim_ui_type_cli) {
err = kim_ui_cli_fini ((kim_ui_cli_context *) &io_context->tcontext);
+#endif /* LEAN_CLIENT */
} else {
err = check_error (KIM_NO_UI_ERR);
* or implied warranty.
*/
+#ifndef LEAN_CLIENT
+
#include "kim_private.h"
+// ---------------------------------------------------------------------------
+static kim_error kim_ui_cli_read_string (kim_string *out_string,
+ kim_boolean in_hide_reply,
+ const char *in_format, ...)
+{
+ kim_error err = KIM_NO_ERROR;
+ krb5_context k5context = NULL;
+ krb5_prompt prompts[1];
+ char prompt_string [BUFSIZ];
+ krb5_data reply_data;
+ char reply_string [BUFSIZ];
+
+ if (!err && !out_string) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_format ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ err = krb5_init_context (&k5context);
+ }
+
+ if (!err) {
+ unsigned int count;
+ va_list args;
+
+ va_start (args, in_format);
+ count = vsnprintf (prompt_string, sizeof (prompt_string),
+ in_format, args);
+ va_end (args);
+
+ if (count > sizeof (prompt_string)) {
+ kim_debug_printf ("%s(): WARNING! Prompt should be %d characters\n",
+ __FUNCTION__, count);
+ prompt_string [sizeof (prompt_string) - 1] = '\0';
+ }
+ }
+
+ if (!err) {
+ /* Build the prompt structures */
+ prompts[0].prompt = prompt_string;
+ prompts[0].hidden = in_hide_reply;
+ prompts[0].reply = &reply_data;
+ prompts[0].reply->data = reply_string;
+ prompts[0].reply->length = sizeof (reply_string);
+
+ err = krb5_prompter_posix (k5context, NULL, NULL, NULL, 1, prompts);
+ if (err == KRB5_LIBOS_PWDINTR) { err = check_error (KIM_USER_CANCELED_ERR); }
+ }
+
+ if (!err) {
+ err = kim_string_create_from_buffer (out_string,
+ prompts[0].reply->data,
+ prompts[0].reply->length);
+ }
+
+ if (k5context) { krb5_free_context (k5context); }
+
+ return check_error (err);
+}
/* ------------------------------------------------------------------------ */
kim_error kim_ui_cli_init (kim_ui_cli_context *out_context)
{
+ *out_context = NULL;
+
return KIM_NO_ERROR;
}
/* ------------------------------------------------------------------------ */
+kim_error kim_ui_cli_enter_identity (kim_ui_cli_context in_context,
+ kim_identity *out_identity)
+{
+ kim_error err = KIM_NO_ERROR;
+ kim_string enter_identity_string = NULL;
+ kim_string identity_string = NULL;
+
+ if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !out_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&enter_identity_string,
+ "KLStringEnterPrincipal");
+ }
+
+ if (!err) {
+ err = kim_ui_cli_read_string (&identity_string,
+ 0, enter_identity_string);
+ }
+
+ if (!err) {
+ err = kim_identity_create_from_string (out_identity, identity_string);
+ }
+
+ kim_string_free (&identity_string);
+ kim_string_free (&enter_identity_string);
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_ui_cli_select_identity (kim_ui_cli_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity)
if (!err && !out_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
+ err = kim_ui_cli_enter_identity (in_context, out_identity);
}
return check_error (err);
kim_error kim_ui_cli_auth_prompt (kim_ui_cli_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
/* in_title, in_message or in_description may be NULL */
if (!err) {
+ if (in_type == kim_prompt_type_password) {
+ kim_string enter_password_format = NULL;
+ kim_string identity_string = NULL;
+
+ err = kim_os_string_create_localized (&enter_password_format,
+ "KLStringEnterPassword");
+
+ if (!err) {
+ err = kim_identity_get_display_string (in_identity,
+ &identity_string);
+ }
+
+ if (!err) {
+ err = kim_ui_cli_read_string ((kim_string *) out_reply,
+ 1, enter_password_format,
+ identity_string);
+ }
+
+ kim_string_free (&identity_string);
+ kim_string_free (&enter_password_format);
+
+ } else {
+ krb5_context k5context = NULL;
+ krb5_prompt prompts[1];
+ krb5_data reply_data;
+ char reply_string [BUFSIZ];
+
+ prompts[0].prompt = (char *) in_description;
+ prompts[0].hidden = in_hide_reply;
+ prompts[0].reply = &reply_data;
+ prompts[0].reply->data = reply_string;
+ prompts[0].reply->length = sizeof (reply_string);
+
+ err = krb5_init_context (&k5context);
+
+ if (!err) {
+ err = krb5_prompter_posix (k5context, in_context, in_title,
+ in_message, 1, prompts);
+ if (err == KRB5_LIBOS_PWDINTR) { err = check_error (KIM_USER_CANCELED_ERR); }
+ }
+
+ if (!err) {
+ err = kim_string_create_from_buffer ((kim_string *) out_reply,
+ prompts[0].reply->data,
+ prompts[0].reply->length);
+ }
+
+ if (k5context) { krb5_free_context (k5context); }
+ }
}
return check_error (err);
/* ------------------------------------------------------------------------ */
+static kim_error kim_ui_cli_ask_change_password (kim_string in_identity_string)
+{
+ kim_error err = KIM_NO_ERROR;
+ kim_string ask_change_password = NULL;
+ kim_string answer_options = NULL;
+ kim_string yes = NULL;
+ kim_string no = NULL;
+ kim_string unknown_response = NULL;
+ kim_boolean done = 0;
+ kim_comparison no_comparison, yes_comparison;
+
+ if (!err) {
+ err = kim_os_string_create_localized (&ask_change_password,
+ "KLStringPasswordExpired");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&answer_options,
+ "KLStringYesOrNoAnswerOptions");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&yes,
+ "KLStringYes");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&no,
+ "KLStringNo");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&unknown_response,
+ "KLStringUnknownResponse");
+ }
+
+ while (!err && !done) {
+ kim_string answer = NULL;
+
+ err = kim_ui_cli_read_string (&answer,
+ 0, "%s %s",
+ ask_change_password, answer_options);
+
+ if (!err) {
+ err = kim_os_string_compare (answer, no,
+ 1 /* case insensitive */,
+ &no_comparison);
+ }
+
+ if (!err && kim_comparison_is_equal_to (no_comparison)) {
+ err = check_error (KIM_USER_CANCELED_ERR);
+ }
+
+ if (!err) {
+ err = kim_os_string_compare (answer, yes,
+ 1 /* case insensitive */,
+ &yes_comparison);
+ }
+
+ if (!err) {
+ if (kim_comparison_is_equal_to (yes_comparison)) {
+ done = 1;
+ } else {
+ fprintf (stdout, unknown_response, answer);
+ fprintf (stdout, "\n");
+ }
+ }
+
+ kim_string_free (&answer);
+ }
+
+ kim_string_free (&ask_change_password);
+ kim_string_free (&answer_options);
+ kim_string_free (&yes);
+ kim_string_free (&no);
+ kim_string_free (&unknown_response);
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_ui_cli_change_password (kim_ui_cli_context in_context,
kim_identity in_identity,
kim_boolean in_old_password_expired,
char **out_verify_password)
{
kim_error err = KIM_NO_ERROR;
+ kim_string enter_old_password_format = NULL;
+ kim_string enter_new_password_format = NULL;
+ kim_string enter_verify_password_format = NULL;
+ kim_string identity_string = NULL;
+ kim_string old_password = NULL;
+ kim_string new_password = NULL;
+ kim_string verify_password = NULL;
if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err && !in_identity ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err && !out_verify_password) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
+ err = kim_identity_get_display_string (in_identity, &identity_string);
+ }
+
+ if (!err && in_old_password_expired) {
+ err = kim_ui_cli_ask_change_password (identity_string);
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&enter_old_password_format,
+ "KLStringEnterOldPassword");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&enter_new_password_format,
+ "KLStringEnterNewPassword");
+ }
+
+ if (!err) {
+ err = kim_os_string_create_localized (&enter_verify_password_format,
+ "KLStringEnterVerifyPassword");
+ }
+
+ if (!err) {
+ err = kim_ui_cli_read_string (&old_password,
+ 1, enter_old_password_format,
+ identity_string);
+ }
+
+ if (!err) {
+ err = kim_credential_create_for_change_password (&in_context,
+ in_identity,
+ old_password);
+ }
+
+ if (!err) {
+ err = kim_ui_cli_read_string (&new_password,
+ 1, enter_new_password_format,
+ identity_string);
+ }
+
+ if (!err) {
+ err = kim_ui_cli_read_string (&verify_password,
+ 1, enter_new_password_format,
+ identity_string);
+ }
+
+ if (!err) {
+ *out_old_password = (char *) old_password;
+ old_password = NULL;
+ *out_new_password = (char *) new_password;
+ new_password = NULL;
+ *out_verify_password = (char *) verify_password;
+ verify_password = NULL;
}
+ kim_string_free (&old_password);
+ kim_string_free (&new_password);
+ kim_string_free (&verify_password);
+ kim_string_free (&identity_string);
+ kim_string_free (&enter_old_password_format);
+ kim_string_free (&enter_new_password_format);
+ kim_string_free (&enter_verify_password_format);
+
return check_error (err);
}
/* ------------------------------------------------------------------------ */
-kim_error kim_ui_cli_display_error (kim_ui_cli_context in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description)
+kim_error kim_ui_cli_handle_error (kim_ui_cli_context in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description)
{
kim_error err = KIM_NO_ERROR;
if (!err && !in_error_description) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
+ fprintf (stdout, "%s: %s\n", in_error_message, in_error_description);
}
return check_error (err);
/* ------------------------------------------------------------------------ */
-void kim_ui_cli_free_string (kim_ui_cli_context in_context,
- char *io_string)
+void kim_ui_cli_free_string (kim_ui_cli_context in_context,
+ char **io_string)
{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !in_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !io_string ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- kim_string_free ((kim_string *) io_string);
- }
+ kim_string_free ((kim_string *) io_string);
}
/* ------------------------------------------------------------------------ */
kim_error kim_ui_cli_fini (kim_ui_cli_context *io_context)
{
+ if (io_context && *io_context) {
+ kim_credential_free (io_context);
+ }
+
return KIM_NO_ERROR;
}
+
+#endif /* LEAN_CLIENT */
#ifndef KIM_UI_CLI_PRIVATE_H
#define KIM_UI_CLI_PRIVATE_H
+#ifndef LEAN_CLIENT
+
#include <kim/kim.h>
-typedef void *kim_ui_cli_context;
+typedef kim_credential kim_ui_cli_context;
kim_error kim_ui_cli_init (kim_ui_cli_context *out_context);
+kim_error kim_ui_cli_enter_identity (kim_ui_cli_context in_context,
+ kim_identity *out_identity);
+
kim_error kim_ui_cli_select_identity (kim_ui_cli_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity);
kim_error kim_ui_cli_auth_prompt (kim_ui_cli_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
char **out_new_password,
char **out_verify_password);
-kim_error kim_ui_cli_display_error (kim_ui_cli_context in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description);
+kim_error kim_ui_cli_handle_error (kim_ui_cli_context in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description);
-void kim_ui_cli_free_string (kim_ui_cli_context in_context,
- char *io_string);
+void kim_ui_cli_free_string (kim_ui_cli_context in_context,
+ char **io_string);
kim_error kim_ui_cli_fini (kim_ui_cli_context *io_context);
+#endif /* LEAN_CLIENT */
+
#endif /* KIM_UI_CLI_PRIVATE_H */
* or implied warranty.
*/
+#ifndef LEAN_CLIENT
+
#include "kim_private.h"
/* ------------------------------------------------------------------------ */
+kim_error kim_ui_gui_enter_identity (kim_ui_gui_context in_context,
+ kim_identity *out_identity)
+{
+ kim_error err = KIM_NO_ERROR;
+
+ if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !out_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ }
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_ui_gui_select_identity (kim_ui_gui_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity)
kim_error kim_ui_gui_auth_prompt (kim_ui_gui_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
/* ------------------------------------------------------------------------ */
-kim_error kim_ui_gui_display_error (kim_ui_gui_context in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description)
+kim_error kim_ui_gui_handle_error (kim_ui_gui_context in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description)
{
kim_error err = KIM_NO_ERROR;
/* ------------------------------------------------------------------------ */
-void kim_ui_gui_free_string (kim_ui_gui_context in_context,
- char *io_string)
+void kim_ui_gui_free_string (kim_ui_gui_context in_context,
+ char **io_string)
{
- kim_error err = KIM_NO_ERROR;
-
- if (!err && !in_context) { err = check_error (KIM_NULL_PARAMETER_ERR); }
- if (!err && !io_string ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
-
- if (!err) {
- kim_string_free ((kim_string *) io_string);
- }
+ kim_string_free ((kim_string *) io_string);
}
/* ------------------------------------------------------------------------ */
return check_error (err);
}
+
+#endif /* LEAN_CLIENT */
#ifndef KIM_UI_GUI_PRIVATE_H
#define KIM_UI_GUI_PRIVATE_H
+#ifndef LEAN_CLIENT
+
#include <kim/kim.h>
struct kim_ui_gui_context;
kim_error kim_ui_gui_init (kim_ui_gui_context *out_context);
+kim_error kim_ui_gui_enter_identity (kim_ui_gui_context in_context,
+ kim_identity *out_identity);
+
kim_error kim_ui_gui_select_identity (kim_ui_gui_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity);
kim_error kim_ui_gui_auth_prompt (kim_ui_gui_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
char **out_new_password,
char **out_verify_password);
-kim_error kim_ui_gui_display_error (kim_ui_gui_context in_context,
+kim_error kim_ui_gui_handle_error (kim_ui_gui_context in_context,
kim_identity in_identity,
kim_error in_error,
kim_string in_error_message,
kim_string in_error_description);
-void kim_ui_gui_free_string (kim_ui_gui_context in_context,
- char *io_string);
+void kim_ui_gui_free_string (kim_ui_gui_context in_context,
+ char **io_string);
kim_error kim_ui_gui_fini (kim_ui_gui_context *io_context);
+#endif /* LEAN_CLIENT */
+
#endif /* KIM_UI_GUI_PRIVATE_H */
/* ------------------------------------------------------------------------ */
+kim_error kim_ui_plugin_enter_identity (kim_ui_plugin_context in_context,
+ kim_identity *out_identity)
+{
+ kim_error err = KIM_NO_ERROR;
+
+ if (!err && !in_context ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !out_identity) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ err = in_context->ftable->enter_identity (in_context->plugin_context,
+ out_identity);
+ }
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_ui_plugin_select_identity (kim_ui_plugin_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity)
kim_error kim_ui_plugin_auth_prompt (kim_ui_plugin_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
err = in_context->ftable->auth_prompt (in_context->plugin_context,
in_identity,
in_type,
+ in_hide_reply,
in_title,
in_message,
in_description,
/* ------------------------------------------------------------------------ */
-kim_error kim_ui_plugin_display_error (kim_ui_plugin_context in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description)
+kim_error kim_ui_plugin_handle_error (kim_ui_plugin_context in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description)
{
kim_error err = KIM_NO_ERROR;
if (!err && !in_error_description) { err = check_error (KIM_NULL_PARAMETER_ERR); }
if (!err) {
- err = in_context->ftable->display_error (in_context->plugin_context,
- in_identity,
- in_error,
- in_error_message,
- in_error_description);
+ err = in_context->ftable->handle_error (in_context->plugin_context,
+ in_identity,
+ in_error,
+ in_error_message,
+ in_error_description);
}
return check_error (err);
/* ------------------------------------------------------------------------ */
-void kim_ui_plugin_free_string (kim_ui_plugin_context in_context,
- char *io_string)
+void kim_ui_plugin_free_string (kim_ui_plugin_context in_context,
+ char **io_string)
{
kim_error err = KIM_NO_ERROR;
kim_error kim_ui_plugin_init (kim_ui_plugin_context *out_context);
+kim_error kim_ui_plugin_enter_identity (kim_ui_plugin_context in_context,
+ kim_identity *out_identity);
+
kim_error kim_ui_plugin_select_identity (kim_ui_plugin_context in_context,
kim_selection_hints in_hints,
kim_identity *out_identity);
kim_error kim_ui_plugin_auth_prompt (kim_ui_plugin_context in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
char **out_new_password,
char **out_verify_password);
-kim_error kim_ui_plugin_display_error (kim_ui_plugin_context in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description);
+kim_error kim_ui_plugin_handle_error (kim_ui_plugin_context in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description);
-void kim_ui_plugin_free_string (kim_ui_plugin_context in_context,
- char *io_string);
+void kim_ui_plugin_free_string (kim_ui_plugin_context in_context,
+ char **io_string);
kim_error kim_ui_plugin_fini (kim_ui_plugin_context *io_context);
kim_ui_type_none
};
+enum kim_ui_error_type {
+ kim_ui_error_type_authentication,
+ kim_ui_error_type_change_password,
+ kim_ui_error_type_selection,
+ kim_ui_error_type_generic
+};
+
/* declare struct on stack. Deep contents will be freed by kim_ui_fini. */
typedef struct kim_ui_context {
enum kim_ui_type type;
void *tcontext;
+ kim_identity identity;
} kim_ui_context;
+krb5_error_code kim_ui_prompter (krb5_context in_krb5_context,
+ void *in_context,
+ const char *in_name,
+ const char *in_banner,
+ int in_num_prompts,
+ krb5_prompt in_prompts[]);
+
kim_error kim_ui_init (kim_ui_context *io_context);
+kim_error kim_ui_enter_identity (kim_ui_context *in_context,
+ kim_identity *out_identity);
+
kim_error kim_ui_select_identity (kim_ui_context *in_context,
kim_selection_hints in_hints,
- kim_identity *out_identity);
+ kim_identity *out_identity);
kim_error kim_ui_auth_prompt (kim_ui_context *in_context,
kim_identity in_identity,
kim_prompt_type in_type,
+ kim_boolean in_hide_reply,
kim_string in_title,
kim_string in_message,
kim_string in_description,
char **out_new_password,
char **out_verify_password);
-kim_error kim_ui_display_error (kim_ui_context *in_context,
- kim_identity in_identity,
- kim_error in_error,
- kim_string in_error_message,
- kim_string in_error_description);
+/* Helper function */
+kim_error kim_ui_handle_kim_error (kim_ui_context *in_context,
+ kim_identity in_identity,
+ enum kim_ui_error_type in_type,
+ kim_error in_error);
+
+kim_error kim_ui_handle_error (kim_ui_context *in_context,
+ kim_identity in_identity,
+ kim_error in_error,
+ kim_string in_error_message,
+ kim_string in_error_description);
void kim_ui_free_string (kim_ui_context *in_context,
- char *io_string);
+ char **io_string);
kim_error kim_ui_fini (kim_ui_context *io_context);
kim_ui_environment kim_os_library_get_ui_environment (void)
{
+#ifndef LEAN_CLIENT
kipc_session_attributes_t attributes = kipc_session_get_attributes ();
if (attributes & kkipc_session_caller_uses_gui) {
}
kim_debug_printf ("kim_os_library_get_ui_environment(): no way to talk to the user.");
+#endif
return KIM_UI_ENVIRONMENT_NONE;
}
CFStringRef in_key,
kim_string *out_string)
{
- kim_error lock_err = kim_os_library_lock_for_bundle_lookup ();
- kim_error err = lock_err;
+ kim_error err = KIM_NO_ERROR;
kim_string string = NULL;
if (!err && !in_bundle ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
}
kim_string_free (&string);
-
- if (!lock_err) { kim_os_library_unlock_for_bundle_lookup (); }
-
+
return check_error (err);
}
/* ------------------------------------------------------------------------ */
+kim_error kim_os_string_create_localized (kim_string *out_string,
+ kim_string in_string)
+{
+ kim_error err = KIM_NO_ERROR;
+ kim_string string = NULL;
+
+ if (!err && !out_string) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+ if (!err && !in_string ) { err = check_error (KIM_NULL_PARAMETER_ERR); }
+
+ if (!err) {
+ err = kim_os_string_create_for_key (&string, in_string);
+ }
+
+ if (!err && !string) {
+ err = kim_string_copy (&string, in_string);
+ }
+
+ if (!err) {
+ *out_string = string;
+ string = NULL;
+ }
+
+ kim_string_free (&string);
+
+ return check_error (err);
+}
+
+/* ------------------------------------------------------------------------ */
+
kim_error kim_os_string_create_for_key (kim_string *out_string,
kim_string in_key_string)
{
- kim_error err = KIM_NO_ERROR;
+ kim_error lock_err = kim_os_library_lock_for_bundle_lookup ();
+ kim_error err = lock_err;
CFStringRef key = NULL;
kim_string string = NULL;
kim_string_free (&string);
if (key) { CFRelease (key); }
+ if (!lock_err) { kim_os_library_unlock_for_bundle_lookup (); }
+
return check_error (err);
}
kim_error kim_os_string_compare (kim_string in_string,
kim_string in_compare_to_string,
+ kim_boolean in_case_insensitive,
kim_comparison *out_comparison)
{
kim_error err = KIM_NO_ERROR;
}
if (!err) {
+ CFOptionFlags options = (in_case_insensitive ?
+ 1 : kCFCompareCaseInsensitive);
+
/* Returned CFComparisonResult is compatible with kim_comparison_t */
- *out_comparison = CFStringCompare (cfstring, compare_to_cfstring, 0);
+ *out_comparison = CFStringCompare (cfstring,
+ compare_to_cfstring,
+ options);
}
if (cfstring ) { CFRelease (cfstring); }
projects / krb5.git / commitdiff