Improve password change API docs and behavior

For krb5_change_password(), krb5_set_password(), and
krb5_set_password_using_ccache(), document that result_code_string may
be NULL and that the caller should free result_code_string and
result_string with krb5_free_data_contents().  Also ensure that
result_code_string and result_string are initialized along all exit
paths.  Reported by Joonas Tuomisto.

ticket: 9176 (new)

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index b5d295f331c94581b33f6655596a72e7014dbef9..6fdd901d04bd42039284c4020e3e01e35d6ff3e7 100644 (file)
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -5026,6 +5026,13 @@ krb5_sname_match(krb5_context context, krb5_const_principal matching,
  *
  * Change the password for the existing principal identified by @a creds.
  *
+ * The error code and strings are returned in @a result_code,
+ * @a result_code_string and @a result_string.  The caller may pass a
+ * @a result_code_string of NULL if it is not needed, but a valid
+ * @a result_string pointer must be supplied.  Use krb5_free_data_contents()
+ * to free @a result_code_string and @a result_string when they are no longer
+ * needed.
+ *
  * The possible values of the output @a result_code are:
  *
  * @li #KRB5_KPASSWD_SUCCESS   (0) - success
@@ -5062,7 +5069,11 @@ krb5_change_password(krb5_context context, krb5_creds *creds,
  * performed on the principal name passed in @a change_password_for.
  *
  * The error code and strings are returned in @a result_code,
- * @a result_code_string and @a result_string.
+ * @a result_code_string and @a result_string.  The caller may pass a
+ * @a result_code_string of NULL if it is not needed, but a valid
+ * @a result_string pointer must be supplied.  Use krb5_free_data_contents()
+ * to free @a result_code_string and @a result_string when they are no longer
+ * needed.
  *
  * @sa krb5_set_password_using_ccache()
  *
@@ -5093,7 +5104,11 @@ krb5_set_password(krb5_context context, krb5_creds *creds, const char *newpw,
  * the credential cache.
  *
  * The error code and strings are returned in @a result_code,
- * @a result_code_string and @a result_string.
+ * @a result_code_string and @a result_string.  The caller may pass a
+ * @a result_code_string of NULL if it is not needed, but a valid
+ * @a result_string pointer must be supplied.  Use krb5_free_data_contents()
+ * to free @a result_code_string and @a result_string when they are no longer
+ * needed.
  *
  * @note If @a change_password_for is set to NULL, the change is performed on
  * the default principal in @a ccache. If @a change_password_for is non null,

diff --git a/src/lib/krb5/os/changepw.c b/src/lib/krb5/os/changepw.c
index d32a12b630a0fa350d80b985a364cd6f023231ba..e577c4a74c39611d5ee202a8e8c4aa5dbcd3de7a 100644 (file)
--- a/src/lib/krb5/os/changepw.c
+++ b/src/lib/krb5/os/changepw.c
@@ -221,6 +221,10 @@ change_set_password(krb5_context context,
     struct sockaddr_storage     remote_addr;
     struct serverlist           sl = SERVERLIST_INIT;
 
+    *result_string = empty_data();
+    if (result_code_string != NULL)
+        *result_code_string = empty_data();
+
     memset(&chpw_rep, 0, sizeof(krb5_data));
     memset( &callback_ctx, 0, sizeof(struct sendto_callback_context));
     callback_ctx.context = context;
@@ -349,6 +353,10 @@ krb5_set_password_using_ccache(krb5_context context,
     krb5_creds          *credsp;
     krb5_error_code     code;
 
+    *result_string = empty_data();
+    if (result_code_string != NULL)
+        *result_code_string = empty_data();
+
     /*
     ** get the proper creds for use with krb5_set_password -
     */