crypto/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 .\" $Id$
  33 .\"
  34 .Dd July 15, 2004
  35 .Dt KRB5_SET_PASSWORD 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_change_password ,
  39 .Nm krb5_set_password ,
  40 .Nm krb5_set_password_using_ccache ,
  41 .Nm krb5_passwd_result_to_string
  42 .Nd change password functions
  43 .Sh LIBRARY
  44 Kerberos 5 Library (libkrb5, -lkrb5)
  45 .Sh SYNOPSIS
  46 .In krb5.h
  47 .Ft krb5_error_code
  48 .Fo krb5_change_password
  49 .Fa "krb5_context context"
  50 .Fa "krb5_creds *creds"
  51 .Fa "char *newpw"
  52 .Fa "int *result_code"
  53 .Fa "krb5_data *result_code_string"
  54 .Fa "krb5_data *result_string"
  55 .Fc
  56 .Ft krb5_error_code
  57 .Fo krb5_set_password
  58 .Fa "krb5_context context"
  59 .Fa "krb5_creds *creds"
  60 .Fa "char *newpw"
  61 .Fa "krb5_principal targprinc"
  62 .Fa "int *result_code"
  63 .Fa "krb5_data *result_code_string"
  64 .Fa "krb5_data *result_string"
  65 .Fc
  66 .Ft krb5_error_code
  67 .Fo krb5_set_password_using_ccache
  68 .Fa "krb5_context context"
  69 .Fa "krb5_ccache ccache"
  70 .Fa "char *newpw"
  71 .Fa "krb5_principal targprinc"
  72 .Fa "int *result_code"
  73 .Fa "krb5_data *result_code_string"
  74 .Fa "krb5_data *result_string"
  75 .Fc
  76 .Ft "const char *"
  77 .Fo krb5_passwd_result_to_string
  78 .Fa "krb5_context context"
  79 .Fa "int result"
  80 .Fc
  81 .Sh DESCRIPTION
  82 These functions change the password for a given principal.
  83 .Pp
  84 .Fn krb5_set_password
  85 and
  86 .Fn krb5_set_password_using_ccache
  87 are the newer of the three functions, and use a newer version of the
  88 protocol (and also fall back to the older set-password protocol if the
  89 newer protocol doesn't work).
  90 .Pp
  91 .Fn krb5_change_password
  92 sets the password
  93 .Fa newpasswd
  94 for the client principal in
  95 .Fa creds .
  96 The server principal of creds must be
  97 .Li kadmin/changepw .
  98 .Pp
  99 .Fn krb5_set_password
 100 and
 101 .Fn krb5_set_password_using_ccache
 102 change the password for the principal
 103 .Fa targprinc .
 104 .Pp
 105 .Fn krb5_set_password
 106 requires that the credential for
 107 .Li kadmin/changepw@REALM
 108 is in
 109 .Fa creds .
 110 If the user caller isn't an administrator, this credential
 111 needs to be an initial credential, see
 112 .Xr krb5_get_init_creds 3
 113 how to get such credentials.
 114 .Pp
 115 .Fn krb5_set_password_using_ccache
 116 will get the credential from
 117 .Fa ccache .
 118 .Pp
 119 If
 120 .Fa targprinc
 121 is
 122 .Dv NULL ,
 123 .Fn krb5_set_password_using_ccache
 124 uses the the default principal in
 125 .Fa ccache
 126 and
 127 .Fn krb5_set_password
 128 uses the global the default principal.
 129 .Pp
 130 All three functions return an error in
 131 .Fa result_code
 132 and maybe an error string to print in
 133 .Fa result_string .
 134 .Pp
 135 .Fn krb5_passwd_result_to_string
 136 returns an human readable string describing the error code in
 137 .Fa result_code
 138 from the
 139 .Fn krb5_set_password
 140 functions.
 141 .Sh SEE ALSO
 142 .Xr krb5_ccache 3 ,
 143 .Xr krb5_init_context 3