From 8dc8d1919c06cae692c6f4207183f327542ed4b2 Mon Sep 17 00:00:00 2001
From: Greg Hudson <ghudson@mit.edu>
Date: Thu, 3 Jul 2025 16:49:47 -0400
Subject: [PATCH] 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)
---
 src/include/krb5/krb5.hin  | 19 +++++++++++++++++--
 src/lib/krb5/os/changepw.c |  8 ++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index b5d295f331..6fdd901d04 100644
--- 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 d32a12b630..e577c4a74c 100644
--- 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 -
     */
-- 
2.47.2