From e8e1e9c2fefe557a10156cd56f76d105336f15f8 Mon Sep 17 00:00:00 2001
From: wiz <wiz@NetBSD.org>
Date: Sun, 18 Jul 2004 15:08:50 +0000
Subject: [PATCH] Sync with Heimdal: krb5_set_password.3,v 1.7 (except for a
 reference to a man page we don't have yet): Document
 krb5_set_password_using_ccache and krb5_passwd_result_to_string. Ok'd by lha.

---
 .../dist/heimdal/lib/krb5/krb5_set_password.3 | 62 ++++++++++++++-----
 1 file changed, 48 insertions(+), 14 deletions(-)

diff --git a/crypto/dist/heimdal/lib/krb5/krb5_set_password.3 b/crypto/dist/heimdal/lib/krb5/krb5_set_password.3
index 7a78eb0f0621..20ba843877ac 100644
--- a/crypto/dist/heimdal/lib/krb5/krb5_set_password.3
+++ b/crypto/dist/heimdal/lib/krb5/krb5_set_password.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2003 Kungliga Tekniska Högskolan
+.\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan
 .\" (Royal Institute of Technology, Stockholm, Sweden).
 .\" All rights reserved.
 .\"
@@ -29,21 +29,22 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $Heimdal: krb5_set_password.3,v 1.3 2004/06/02 19:24:58 lha Exp $
-.\" $NetBSD: krb5_set_password.3,v 1.4 2004/07/14 09:21:59 wiz Exp $
+.\" $Heimdal: krb5_set_password.3,v 1.7 2004/07/15 14:39:06 lha Exp $
+.\" $NetBSD: krb5_set_password.3,v 1.5 2004/07/18 15:08:50 wiz Exp $
 .\"
-.Dd June  2, 2004
+.Dd July 15, 2004
 .Dt KRB5_SET_PASSWORD 3
-.Os HEIMDAL
+.Os
 .Sh NAME
 .Nm krb5_change_password ,
 .Nm krb5_set_password ,
-.Nm krb5_set_password_using_ccache
+.Nm krb5_set_password_using_ccache ,
+.Nm krb5_passwd_result_to_string
 .Nd change password functions
 .Sh LIBRARY
 Kerberos 5 Library (libkrb5, -lkrb5)
 .Sh SYNOPSIS
-.In krb5.h
+.In krb5/krb5.h
 .Ft krb5_error_code
 .Fo krb5_change_password
 .Fa "krb5_context context"
@@ -73,6 +74,11 @@ Kerberos 5 Library (libkrb5, -lkrb5)
 .Fa "krb5_data *result_code_string"
 .Fa "krb5_data *result_string"
 .Fc
+.Ft "const char *"
+.Fo krb5_passwd_result_to_string
+.Fa "krb5_context context"
+.Fa "int result"
+.Fc
 .Sh DESCRIPTION
 These functions change the password for a given principal.
 .Pp
@@ -80,8 +86,8 @@ These functions change the password for a given principal.
 and
 .Fn krb5_set_password_using_ccache
 are the newer of the three functions, and use a newer version of the
-protocol (and also fall back to the older set-password protocol if
-the newer protocol doesn't work).
+protocol (and also fall back to the older set-password protocol if the
+newer protocol doesn't work).
 .Pp
 .Fn krb5_change_password
 sets the password
@@ -92,20 +98,48 @@ The server principal of creds must be
 .Li kadmin/changepw .
 .Pp
 .Fn krb5_set_password
-changes the password for the principal
+and
+.Fn krb5_set_password_using_ccache
+change the password for the principal
 .Fa targprinc .
+.Pp
+.Fn krb5_set_password
+requires that the credential for
+.Li kadmin/changepw@REALM
+is in
+.Fa creds .
+If the user caller isn't an administrator, this credential
+needs to be an initial credential.
+.\", see
+.\".Xr krb5_get_init_creds 3
+.\"how to get such credentials.
+.Pp
+.Fn krb5_set_password_using_ccache
+will get the credential from
+.Fa ccache .
+.Pp
 If
 .Fa targprinc
 is
-.Dv NULL
-the default principal in
+.Dv NULL ,
+.Fn krb5_set_password_using_ccache
+uses the the default principal in
 .Fa ccache
-is used.
+and
+.Fn krb5_set_password
+uses the global the default principal.
 .Pp
-Both functions return an error in
+All three functions return an error in
 .Fa result_code
 and maybe an error string to print in
 .Fa result_string .
+.Pp
+.Fn krb5_passwd_result_to_string
+returns an human readable string describing the error code in
+.Fa result_code
+from the
+.Fn krb5_set_password
+functions.
 .Sh SEE ALSO
 .Xr krb5_ccache 3 ,
 .Xr krb5_init_context 3