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