crypto/heimdal/lib/krb5/krb5_get_in_cred.3

   1 .\" Copyright (c) 2003 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 May 31, 2003
  35 .Dt KRB5_GET_IN_TKT 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_get_in_tkt ,
  39 .Nm krb5_get_in_cred ,
  40 .Nm krb5_get_in_tkt_with_password ,
  41 .Nm krb5_get_in_tkt_with_keytab ,
  42 .Nm krb5_get_in_tkt_with_skey ,
  43 .Nm krb5_free_kdc_rep ,
  44 .Nm krb5_password_key_proc
  45 .Nd deprecated initial authentication functions
  46 .Sh LIBRARY
  47 Kerberos 5 Library (libkrb5, -lkrb5)
  48 .Sh SYNOPSIS
  49 .In krb5.h
  50 .Pp
  51 .Ft krb5_error_code
  52 .Fo krb5_get_in_tkt
  53 .Fa "krb5_context context"
  54 .Fa "krb5_flags options"
  55 .Fa "const krb5_addresses *addrs"
  56 .Fa "const krb5_enctype *etypes"
  57 .Fa "const krb5_preauthtype *ptypes"
  58 .Fa "krb5_key_proc key_proc"
  59 .Fa "krb5_const_pointer keyseed"
  60 .Fa "krb5_decrypt_proc decrypt_proc"
  61 .Fa "krb5_const_pointer decryptarg"
  62 .Fa "krb5_creds *creds"
  63 .Fa "krb5_ccache ccache"
  64 .Fa "krb5_kdc_rep *ret_as_reply"
  65 .Fc
  66 .Ft krb5_error_code
  67 .Fo krb5_get_in_cred
  68 .Fa "krb5_context context"
  69 .Fa "krb5_flags options"
  70 .Fa "const krb5_addresses *addrs"
  71 .Fa "const krb5_enctype *etypes"
  72 .Fa "const krb5_preauthtype *ptypes"
  73 .Fa "const krb5_preauthdata *preauth"
  74 .Fa "krb5_key_proc key_proc"
  75 .Fa "krb5_const_pointer keyseed"
  76 .Fa "krb5_decrypt_proc decrypt_proc"
  77 .Fa "krb5_const_pointer decryptarg"
  78 .Fa "krb5_creds *creds"
  79 .Fa "krb5_kdc_rep *ret_as_reply"
  80 .Fc
  81 .Ft krb5_error_code
  82 .Fo krb5_get_in_tkt_with_password
  83 .Fa "krb5_context context"
  84 .Fa "krb5_flags options"
  85 .Fa "krb5_addresses *addrs"
  86 .Fa "const krb5_enctype *etypes"
  87 .Fa "const krb5_preauthtype *pre_auth_types"
  88 .Fa "const char *password"
  89 .Fa "krb5_ccache ccache"
  90 .Fa "krb5_creds *creds"
  91 .Fa "krb5_kdc_rep *ret_as_reply"
  92 .Fc
  93 .Ft krb5_error_code
  94 .Fo krb5_get_in_tkt_with_keytab
  95 .Fa "krb5_context context"
  96 .Fa "krb5_flags options"
  97 .Fa "krb5_addresses *addrs"
  98 .Fa "const krb5_enctype *etypes"
  99 .Fa "const krb5_preauthtype *pre_auth_types"
 100 .Fa "krb5_keytab keytab"
 101 .Fa "krb5_ccache ccache"
 102 .Fa "krb5_creds *creds"
 103 .Fa "krb5_kdc_rep *ret_as_reply"
 104 .Fc
 105 .Ft krb5_error_code
 106 .Fo krb5_get_in_tkt_with_skey
 107 .Fa "krb5_context context"
 108 .Fa "krb5_flags options"
 109 .Fa "krb5_addresses *addrs"
 110 .Fa "const krb5_enctype *etypes"
 111 .Fa "const krb5_preauthtype *pre_auth_types"
 112 .Fa "const krb5_keyblock *key"
 113 .Fa "krb5_ccache ccache"
 114 .Fa "krb5_creds *creds"
 115 .Fa "krb5_kdc_rep *ret_as_reply"
 116 .Fc
 117 .Ft krb5_error_code
 118 .Fo krb5_free_kdc_rep
 119 .Fa "krb5_context context"
 120 .Fa "krb5_kdc_rep *rep"
 121 .Fc
 122 .Ft krb5_error_code
 123 .Fo krb5_password_key_proc
 124 .Fa "krb5_context context"
 125 .Fa "krb5_enctype type"
 126 .Fa "krb5_salt salt"
 127 .Fa "krb5_const_pointer keyseed"
 128 .Fa "krb5_keyblock **key"
 129 .Fc
 130 .Sh DESCRIPTION
 131 .Bf Em
 132 All the functions in this manual page are deprecated in the MIT
 133 implementation, and will soon be deprecated in Heimdal too, don't use them.
 134 .Ef
 135 .Pp
 136 Getting initial credential ticket for a principal.
 137 .Nm krb5_get_in_cred
 138 is the function all other krb5_get_in function uses to fetch tickets.
 139 The other krb5_get_in function are more specialized and therefor
 140 somewhat easier to use.
 141 .Pp
 142 If your need is only to verify a user and password, consider using
 143 .Xr krb5_verify_user 3
 144 instead, it have a much simpler interface.
 145 .Pp
 146 .Nm krb5_get_in_tkt
 147 and
 148 .Nm krb5_get_in_cred
 149 fetches initial credential, queries after key using the
 150 .Fa key_proc
 151 argument.
 152 The differences between the two function is that
 153 .Nm krb5_get_in_tkt
 154 stores the credential in a
 155 .Li krb5_creds
 156 while
 157 .Nm krb5_get_in_cred
 158 stores the credential in a
 159 .Li krb5_ccache .
 160 .Pp
 161 .Nm krb5_get_in_tkt_with_password ,
 162 .Nm krb5_get_in_tkt_with_keytab ,
 163 and
 164 .Nm krb5_get_in_tkt_with_skey
 165 does the same work as
 166 .Nm krb5_get_in_cred
 167 but are more specialized.
 168 .Pp
 169 .Nm krb5_get_in_tkt_with_password
 170 uses the clients password to authenticate.
 171 If the password argument is
 172 .Dv NULL
 173 the user user queried with the default password query function.
 174 .Pp
 175 .Nm krb5_get_in_tkt_with_keytab
 176 searches the given keytab for a service entry for the client principal.
 177 If the keytab is
 178 .Dv NULL
 179 the default keytab is used.
 180 .Pp
 181 .Nm krb5_get_in_tkt_with_skey
 182 uses a key to get the initial credential.
 183 .Pp
 184 There are some common arguments to the krb5_get_in functions, these are:
 185 .Pp
 186 .Fa options
 187 are the
 188 .Dv KDC_OPT
 189 flags.
 190 .Pp
 191 .Fa etypes
 192 is a
 193 .Dv NULL
 194 terminated array of encryption types that the client approves.
 195 .Pp
 196 .Fa addrs
 197 a list of the addresses that the initial ticket.
 198 If it is
 199 .Dv NULL
 200 the list will be generated by the library.
 201 .Pp
 202 .Fa pre_auth_types
 203 a
 204 .Dv NULL
 205 terminated array of pre-authentication types.
 206 If
 207 .Fa pre_auth_types
 208 is
 209 .Dv NULL
 210 the function will try without pre-authentication and return those
 211 pre-authentication that the KDC returned.
 212 .Pp
 213 .Fa ret_as_reply
 214 will (if not
 215 .Dv NULL )
 216 be filled in with the response of the KDC and should be free with
 217 .Fn krb5_free_kdc_rep .
 218 .Pp
 219 .Fa key_proc
 220 is a pointer to a function that should return a key salted appropriately.
 221 Using
 222 .Dv NULL
 223 will use the default password query function.
 224 .Pp
 225 .Fa decrypt_proc
 226 Using
 227 .Dv NULL
 228 will use the default decryption function.
 229 .Pp
 230 .Fa decryptarg
 231 will be passed to the decryption function
 232 .Fa decrypt_proc .
 233 .Pp
 234 .Fa creds
 235 creds should be filled in with the template for a credential that
 236 should be requested.
 237 The client and server elements of the creds structure must be filled in.
 238 Upon return of the function it will be contain the content of the
 239 requested credential
 240 .Fa ( krb5_get_in_cred ) ,
 241 or it will be freed with
 242 .Xr krb5_free_creds 3
 243 (all the other krb5_get_in functions).
 244 .Pp
 245 .Fa ccache
 246 will store the credential in the credential cache
 247 .Fa ccache .
 248 The credential cache will not be initialized, thats up the the caller.
 249 .Pp
 250 .Nm krb5_password_key_proc
 251 is a library function that is suitable using as the
 252 .Fa krb5_key_proc
 253 argument to
 254 .Nm krb5_get_in_cred
 255 or
 256 .Nm krb5_get_in_tkt .
 257 .Fa keyseed
 258 should be a pointer to a
 259 .Dv NUL
 260 terminated string or
 261 .Dv NULL .
 262 .Nm krb5_password_key_proc
 263 will query the user for the pass on the console if the password isn't
 264 given as the argument
 265 .Fa keyseed .
 266 .Pp
 267 .Fn krb5_free_kdc_rep
 268 frees the content of
 269 .Fa rep .
 270 .Sh SEE ALSO
 271 .Xr krb5 3 ,
 272 .Xr krb5_verify_user 3 ,
 273 .Xr krb5.conf 5 ,
 274 .Xr kerberos 8