source4/heimdal/lib/krb5/krb5_get_init_creds.3

   1 .\" Copyright (c) 2003 - 2007 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 Sep  16, 2006
  35 .Dt KRB5_GET_INIT_CREDS 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_get_init_creds ,
  39 .Nm krb5_get_init_creds_keytab ,
  40 .Nm krb5_get_init_creds_opt ,
  41 .Nm krb5_get_init_creds_opt_alloc ,
  42 .Nm krb5_get_init_creds_opt_free ,
  43 .Nm krb5_get_init_creds_opt_init ,
  44 .Nm krb5_get_init_creds_opt_set_address_list ,
  45 .Nm krb5_get_init_creds_opt_set_addressless ,
  46 .Nm krb5_get_init_creds_opt_set_anonymous ,
  47 .Nm krb5_get_init_creds_opt_set_default_flags ,
  48 .Nm krb5_get_init_creds_opt_set_etype_list ,
  49 .Nm krb5_get_init_creds_opt_set_forwardable ,
  50 .Nm krb5_get_init_creds_opt_set_pa_password ,
  51 .Nm krb5_get_init_creds_opt_set_paq_request ,
  52 .Nm krb5_get_init_creds_opt_set_preauth_list ,
  53 .Nm krb5_get_init_creds_opt_set_proxiable ,
  54 .Nm krb5_get_init_creds_opt_set_renew_life ,
  55 .Nm krb5_get_init_creds_opt_set_salt ,
  56 .Nm krb5_get_init_creds_opt_set_tkt_life ,
  57 .Nm krb5_get_init_creds_opt_set_canonicalize ,
  58 .Nm krb5_get_init_creds_opt_set_win2k ,
  59 .Nm krb5_get_init_creds_password ,
  60 .Nm krb5_prompt ,
  61 .Nm krb5_prompter_posix
  62 .Nd Kerberos 5 initial authentication functions
  63 .Sh LIBRARY
  64 Kerberos 5 Library (libkrb5, -lkrb5)
  65 .Sh SYNOPSIS
  66 .In krb5.h
  67 .Pp
  68 .Ft krb5_get_init_creds_opt;
  69 .Pp
  70 .Ft krb5_error_code
  71 .Fo krb5_get_init_creds_opt_alloc
  72 .Fa "krb5_context context"
  73 .Fa "krb5_get_init_creds_opt **opt"
  74 .Fc
  75 .Ft void
  76 .Fo krb5_get_init_creds_opt_free
  77 .Fa "krb5_context context"
  78 .Fa "krb5_get_init_creds_opt *opt"
  79 .Fc
  80 .Ft void
  81 .Fo krb5_get_init_creds_opt_init
  82 .Fa "krb5_get_init_creds_opt *opt"
  83 .Fc
  84 .Ft void
  85 .Fo krb5_get_init_creds_opt_set_address_list
  86 .Fa "krb5_get_init_creds_opt *opt"
  87 .Fa "krb5_addresses *addresses"
  88 .Fc
  89 .Ft void
  90 .Fo krb5_get_init_creds_opt_set_addressless
  91 .Fa "krb5_get_init_creds_opt *opt"
  92 .Fa "krb5_boolean addressless"
  93 .Fc
  94 .Ft void
  95 .Fo krb5_get_init_creds_opt_set_anonymous
  96 .Fa "krb5_get_init_creds_opt *opt"
  97 .Fa "int anonymous"
  98 .Fc
  99 .Ft void
 100 .Fo krb5_get_init_creds_opt_set_change_password_prompt
 101 .Fa "krb5_get_init_creds_opt *opt"
 102 .Fa "int change_password_prompt"
 103 .Fc
 104 .Ft void
 105 .Fo krb5_get_init_creds_opt_set_default_flags
 106 .Fa "krb5_context context"
 107 .Fa "const char *appname"
 108 .Fa "krb5_const_realm realm"
 109 .Fa "krb5_get_init_creds_opt *opt"
 110 .Fc
 111 .Ft void
 112 .Fo krb5_get_init_creds_opt_set_etype_list
 113 .Fa "krb5_get_init_creds_opt *opt"
 114 .Fa "krb5_enctype *etype_list"
 115 .Fa "int etype_list_length"
 116 .Fc
 117 .Ft void
 118 .Fo krb5_get_init_creds_opt_set_forwardable
 119 .Fa "krb5_get_init_creds_opt *opt"
 120 .Fa "int forwardable"
 121 .Fc
 122 .Ft krb5_error_code
 123 .Fo krb5_get_init_creds_opt_set_pa_password
 124 .Fa "krb5_context context"
 125 .Fa "krb5_get_init_creds_opt *opt"
 126 .Fa "const char *password"
 127 .Fa "krb5_s2k_proc key_proc"
 128 .Fc
 129 .Ft krb5_error_code
 130 .Fo krb5_get_init_creds_opt_set_paq_request
 131 .Fa "krb5_context context"
 132 .Fa "krb5_get_init_creds_opt *opt"
 133 .Fa "krb5_boolean req_pac"
 134 .Fc
 135 .Ft krb5_error_code
 136 .Fo krb5_get_init_creds_opt_set_pkinit
 137 .Fa "krb5_context context"
 138 .Fa "krb5_get_init_creds_opt *opt"
 139 .Fa "const char *cert_file"
 140 .Fa "const char *key_file"
 141 .Fa "const char *x509_anchors"
 142 .Fa "int flags"
 143 .Fa "char *password"
 144 .Fc
 145 .Ft void
 146 .Fo krb5_get_init_creds_opt_set_preauth_list
 147 .Fa "krb5_get_init_creds_opt *opt"
 148 .Fa "krb5_preauthtype *preauth_list"
 149 .Fa "int preauth_list_length"
 150 .Fc
 151 .Ft void
 152 .Fo krb5_get_init_creds_opt_set_proxiable
 153 .Fa "krb5_get_init_creds_opt *opt"
 154 .Fa "int proxiable"
 155 .Fc
 156 .Ft void
 157 .Fo krb5_get_init_creds_opt_set_renew_life
 158 .Fa "krb5_get_init_creds_opt *opt"
 159 .Fa "krb5_deltat renew_life"
 160 .Fc
 161 .Ft void
 162 .Fo krb5_get_init_creds_opt_set_salt
 163 .Fa "krb5_get_init_creds_opt *opt"
 164 .Fa "krb5_data *salt"
 165 .Fc
 166 .Ft void
 167 .Fo krb5_get_init_creds_opt_set_tkt_life
 168 .Fa "krb5_get_init_creds_opt *opt"
 169 .Fa "krb5_deltat tkt_life"
 170 .Fc
 171 .Ft krb5_error_code
 172 .Fo krb5_get_init_creds_opt_set_canonicalize
 173 .Fa "krb5_context context"
 174 .Fa "krb5_get_init_creds_opt *opt"
 175 .Fa "krb5_boolean req"
 176 .Fc
 177 .Ft krb5_error_code
 178 .Fo krb5_get_init_creds_opt_set_win2k
 179 .Fa "krb5_context context"
 180 .Fa "krb5_get_init_creds_opt *opt"
 181 .Fa "krb5_boolean req"
 182 .Fc
 183 .Ft krb5_error_code
 184 .Fo krb5_get_init_creds
 185 .Fa "krb5_context context"
 186 .Fa "krb5_creds *creds"
 187 .Fa "krb5_principal client"
 188 .Fa "krb5_prompter_fct prompter"
 189 .Fa "void *prompter_data"
 190 .Fa "krb5_deltat start_time"
 191 .Fa "const char *in_tkt_service"
 192 .Fa "krb5_get_init_creds_opt *options"
 193 .Fc
 194 .Ft krb5_error_code
 195 .Fo krb5_get_init_creds_password
 196 .Fa "krb5_context context"
 197 .Fa "krb5_creds *creds"
 198 .Fa "krb5_principal client"
 199 .Fa "const char *password"
 200 .Fa "krb5_prompter_fct prompter"
 201 .Fa "void *prompter_data"
 202 .Fa "krb5_deltat start_time"
 203 .Fa "const char *in_tkt_service"
 204 .Fa "krb5_get_init_creds_opt *in_options"
 205 .Fc
 206 .Ft krb5_error_code
 207 .Fo krb5_get_init_creds_keytab
 208 .Fa "krb5_context context"
 209 .Fa "krb5_creds *creds"
 210 .Fa "krb5_principal client"
 211 .Fa "krb5_keytab keytab"
 212 .Fa "krb5_deltat start_time"
 213 .Fa "const char *in_tkt_service"
 214 .Fa "krb5_get_init_creds_opt *options"
 215 .Fc
 216 .Ft int
 217 .Fo krb5_prompter_posix
 218 .Fa "krb5_context context"
 219 .Fa "void *data"
 220 .Fa "const char *name"
 221 .Fa "const char *banner"
 222 .Fa "int num_prompts"
 223 .Fa "krb5_prompt prompts[]"
 224 .Fc
 225 .Sh DESCRIPTION
 226 Getting initial credential ticket for a principal.
 227 That may include changing an expired password, and doing preauthentication.
 228 This interface that replaces the deprecated
 229 .Fa krb5_in_tkt
 230 and
 231 .Fa krb5_in_cred
 232 functions.
 233 .Pp
 234 If you only want to verify a username and password, consider using
 235 .Xr krb5_verify_user 3
 236 instead, since it also verifies that initial credentials with using a
 237 keytab to make sure the response was from the KDC.
 238 .Pp
 239 First a
 240 .Li krb5_get_init_creds_opt
 241 structure is initialized
 242 with
 243 .Fn krb5_get_init_creds_opt_alloc
 244 or
 245 .Fn krb5_get_init_creds_opt_init .
 246 .Fn krb5_get_init_creds_opt_alloc
 247 allocates a extendible structures that needs to be freed with
 248 .Fn krb5_get_init_creds_opt_free .
 249 The structure may be modified by any of the
 250 .Fn krb5_get_init_creds_opt_set
 251 functions to change request parameters and authentication information.
 252 .Pp
 253 If the caller want to use the default options,
 254 .Dv NULL
 255 can be passed instead.
 256 .Pp
 257 The the actual request to the KDC is done by any of the
 258 .Fn krb5_get_init_creds ,
 259 .Fn krb5_get_init_creds_password ,
 260 or
 261 .Fn krb5_get_init_creds_keytab
 262 functions.
 263 .Fn krb5_get_init_creds
 264 is the least specialized function and can, with the right in data,
 265 behave like the latter two.
 266 The latter two are there for compatibility with older releases and
 267 they are slightly easier to use.
 268 .Pp
 269 .Li krb5_prompt
 270 is a structure containing the following elements:
 271 .Bd -literal
 272 typedef struct {
 273     const char *prompt;
 274     int hidden;
 275     krb5_data *reply;
 276     krb5_prompt_type type
 277 } krb5_prompt;
 278 .Ed
 279 .Pp
 280 .Fa prompt
 281 is the prompt that should shown to the user
 282 If
 283 .Fa hidden
 284 is set, the prompter function shouldn't echo the output to the display
 285 device.
 286 .Fa reply
 287 must be preallocated; it will not be allocated by the prompter
 288 function.
 289 Possible values for the
 290 .Fa type
 291 element are:
 292 .Pp
 293 .Bl -tag -width Ds -compact -offset indent
 294 .It KRB5_PROMPT_TYPE_PASSWORD
 295 .It KRB5_PROMPT_TYPE_NEW_PASSWORD
 296 .It KRB5_PROMPT_TYPE_NEW_PASSWORD_AGAIN
 297 .It KRB5_PROMPT_TYPE_PREAUTH
 298 .It KRB5_PROMPT_TYPE_INFO
 299 .El
 300 .Pp
 301 .Fn krb5_prompter_posix
 302 is the default prompter function in a POSIX environment.
 303 It matches the
 304 .Fa krb5_prompter_fct
 305 and can be used in the
 306 .Fa krb5_get_init_creds
 307 functions.
 308 .Fn krb5_prompter_posix
 309 doesn't require
 310 .Fa prompter_data.
 311 .Pp
 312 If the
 313 .Fa start_time
 314 is zero, then the requested ticket will be valid
 315 beginning immediately.
 316 Otherwise, the
 317 .Fa start_time
 318 indicates how far in the future the ticket should be postdated.
 319 .Pp
 320 If the
 321 .Fa in_tkt_service
 322 name is
 323 .Dv non-NULL ,
 324 that principal name will be
 325 used as the server name for the initial ticket request.
 326 The realm of the name specified will be ignored and will be set to the
 327 realm of the client name.
 328 If no in_tkt_service name is specified,
 329 krbtgt/CLIENT-REALM@CLIENT-REALM will be used.
 330 .Pp
 331 For the rest of arguments, a configuration or library default will be
 332 used if no value is specified in the options structure.
 333 .Pp
 334 .Fn krb5_get_init_creds_opt_set_address_list
 335 sets the list of
 336 .Fa addresses
 337 that is should be stored in the ticket.
 338 .Pp
 339 .Fn krb5_get_init_creds_opt_set_addressless
 340 controls if the ticket is requested with addresses or not,
 341 .Fn krb5_get_init_creds_opt_set_address_list
 342 overrides this option.
 343 .Pp
 344 .Fn krb5_get_init_creds_opt_set_anonymous
 345 make the request anonymous if the
 346 .Fa anonymous
 347 parameter is non-zero.
 348 .Pp
 349 .Fn krb5_get_init_creds_opt_set_default_flags
 350 sets the default flags using the configuration file.
 351 .Pp
 352 .Fn krb5_get_init_creds_opt_set_etype_list
 353 set a list of enctypes that the client is willing to support in the
 354 request.
 355 .Pp
 356 .Fn krb5_get_init_creds_opt_set_forwardable
 357 request a forwardable ticket.
 358 .Pp
 359 .Fn krb5_get_init_creds_opt_set_pa_password
 360 set the
 361 .Fa password
 362 and
 363 .Fa key_proc
 364 that is going to be used to get a new ticket.
 365 .Fa password
 366 or
 367 .Fa key_proc
 368 can be
 369 .Dv NULL
 370 if the caller wants to use the default values.
 371 If the
 372 .Fa password
 373 is unset and needed, the user will be prompted for it.
 374 .Pp
 375 .Fn krb5_get_init_creds_opt_set_paq_request
 376 sets the password that is going to be used to get a new ticket.
 377 .Pp
 378 .Fn krb5_get_init_creds_opt_set_preauth_list
 379 sets the list of client-supported preauth types.
 380 .Pp
 381 .Fn krb5_get_init_creds_opt_set_proxiable
 382 makes the request proxiable.
 383 .Pp
 384 .Fn krb5_get_init_creds_opt_set_renew_life
 385 sets the requested renewable lifetime.
 386 .Pp
 387 .Fn krb5_get_init_creds_opt_set_salt
 388 sets the salt that is going to be used in the request.
 389 .Pp
 390 .Fn krb5_get_init_creds_opt_set_tkt_life
 391 sets requested ticket lifetime.
 392 .Pp
 393 .Fn krb5_get_init_creds_opt_set_canonicalize
 394 requests that the KDC canonicalize the client principal if possible.
 395 .Pp
 396 .Fn krb5_get_init_creds_opt_set_win2k
 397 turns on compatibility with Windows 2000.
 398 .Sh SEE ALSO
 399 .Xr krb5 3 ,
 400 .Xr krb5_creds 3 ,
 401 .Xr krb5_verify_user 3 ,
 402 .Xr krb5.conf 5 ,
 403 .Xr kerberos 8