crypto/dist/heimdal/lib/krb5/krb5_set_password.3

   1 .\" Copyright (c) 2003 - 2004 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Heimdal: krb5_set_password.3 14052 2004-07-15 14:39:06Z lha $
  33 .\" $NetBSD$
  34 .\"
  35 .Dd July 15, 2004
  36 .Dt KRB5_SET_PASSWORD 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_change_password ,
  40 .Nm krb5_set_password ,
  41 .Nm krb5_set_password_using_ccache ,
  42 .Nm krb5_passwd_result_to_string
  43 .Nd change password functions
  44 .Sh LIBRARY
  45 Kerberos 5 Library (libkrb5, -lkrb5)
  46 .Sh SYNOPSIS
  47 .In krb5/krb5.h
  48 .Ft krb5_error_code
  49 .Fo krb5_change_password
  50 .Fa "krb5_context context"
  51 .Fa "krb5_creds *creds"
  52 .Fa "char *newpw"
  53 .Fa "int *result_code"
  54 .Fa "krb5_data *result_code_string"
  55 .Fa "krb5_data *result_string"
  56 .Fc
  57 .Ft krb5_error_code
  58 .Fo krb5_set_password
  59 .Fa "krb5_context context"
  60 .Fa "krb5_creds *creds"
  61 .Fa "char *newpw"
  62 .Fa "krb5_principal targprinc"
  63 .Fa "int *result_code"
  64 .Fa "krb5_data *result_code_string"
  65 .Fa "krb5_data *result_string"
  66 .Fc
  67 .Ft krb5_error_code
  68 .Fo krb5_set_password_using_ccache
  69 .Fa "krb5_context context"
  70 .Fa "krb5_ccache ccache"
  71 .Fa "char *newpw"
  72 .Fa "krb5_principal targprinc"
  73 .Fa "int *result_code"
  74 .Fa "krb5_data *result_code_string"
  75 .Fa "krb5_data *result_string"
  76 .Fc
  77 .Ft "const char *"
  78 .Fo krb5_passwd_result_to_string
  79 .Fa "krb5_context context"
  80 .Fa "int result"
  81 .Fc
  82 .Sh DESCRIPTION
  83 These functions change the password for a given principal.
  84 .Pp
  85 .Fn krb5_set_password
  86 and
  87 .Fn krb5_set_password_using_ccache
  88 are the newer of the three functions, and use a newer version of the
  89 protocol (and also fall back to the older set-password protocol if the
  90 newer protocol doesn't work).
  91 .Pp
  92 .Fn krb5_change_password
  93 sets the password
  94 .Fa newpasswd
  95 for the client principal in
  96 .Fa creds .
  97 The server principal of creds must be
  98 .Li kadmin/changepw .
  99 .Pp
 100 .Fn krb5_set_password
 101 and
 102 .Fn krb5_set_password_using_ccache
 103 change the password for the principal
 104 .Fa targprinc .
 105 .Pp
 106 .Fn krb5_set_password
 107 requires that the credential for
 108 .Li kadmin/changepw@REALM
 109 is in
 110 .Fa creds .
 111 If the user caller isn't an administrator, this credential
 112 needs to be an initial credential, see
 113 .Xr krb5_get_init_creds 3
 114 how to get such credentials.
 115 .Pp
 116 .Fn krb5_set_password_using_ccache
 117 will get the credential from
 118 .Fa ccache .
 119 .Pp
 120 If
 121 .Fa targprinc
 122 is
 123 .Dv NULL ,
 124 .Fn krb5_set_password_using_ccache
 125 uses the the default principal in
 126 .Fa ccache
 127 and
 128 .Fn krb5_set_password
 129 uses the global the default principal.
 130 .Pp
 131 All three functions return an error in
 132 .Fa result_code
 133 and maybe an error string to print in
 134 .Fa result_string .
 135 .Pp
 136 .Fn krb5_passwd_result_to_string
 137 returns an human readable string describing the error code in
 138 .Fa result_code
 139 from the
 140 .Fn krb5_set_password
 141 functions.
 142 .Sh SEE ALSO
 143 .Xr krb5_ccache 3 ,
 144 .Xr krb5_init_context 3